BadNote/README.md

# BadNote

Local-first Surface Pen note-taking app with PDF/PPT annotation.

All notes, documents, search, and OCR run on your device. No server is required to use the app.

## Features

- Ink notes with Surface Pen (pressure, stabilizer, undo/redo)
- PDF and PPT import with page-level annotation
- Full-text search over note titles, typed text, and OCR results
- **Local OCR** — pluggable, fully on-device. An embedded ONNX recognition
  backend (cross-platform, CPU/iGPU) with a graceful fallback to the platform's
  built-in OCR (Windows). See [Local OCR](#local-ocr).

## Build (Windows)

Prerequisites:

- Flutter SDK (3.10+)
- Visual Studio Build Tools with **Desktop development with C++**
- Developer Mode enabled (for Flutter plugin symlinks)

```powershell
flutter pub get
flutter build windows --release
```

Output: `build\windows\x64\runner\Release\badnote.exe`

The `sqlite3` native binary is **vendored** under `vendor/sqlite3/` (configured via
`hooks.user_defines` in `pubspec.yaml`), so the build does not download anything
from GitHub — it works fully offline / behind a firewall. To add another
platform or architecture, drop its official release binary from
[sqlite3.dart releases](https://github.com/simolus3/sqlite3.dart/releases) into
`vendor/sqlite3/` (the build validates each file's SHA-256).

In mainland China, point pub/Flutter at the local mirrors:

```powershell
$env:PUB_HOSTED_URL="https://pub.flutter-io.cn"
$env:FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"
flutter pub get
flutter build windows --release
```

## Continuous integration

`.gitea/workflows/ci.yml` runs format + analyze + test + Windows release build on
a self-hosted **Windows** runner. It is written for runners behind the GFW:
actions come from the `gitea.com` mirror, Flutter is expected to be
pre-installed on the runner, and pub uses the `flutter-io.cn` mirror. If
`gitea.com` is unreachable too, set `DEFAULT_ACTIONS_URL=https://gitea.com` (or
your own mirror) in the runner config and use bare `actions/checkout@v4`.

## Architecture

```
lib/
├── screens/          # UI (notes, PDF/PPT annotator, search, settings)
├── services/         # Local business logic
│   ├── database_service.dart   # SQLite + FTS5
│   ├── ocr_service.dart        # Local OCR orchestration
│   ├── stroke_rasterizer.dart  # Ink → PNG for OCR
│   ├── ocr_engine.dart         # OCR entry point (delegates to a backend)
│   └── ocr/                    # Pluggable OCR backends
│       ├── ocr_backend.dart           # Backend interface
│       ├── ocr_backends.dart          # Backend selector (ONNX → native)
│       ├── onnx_recognition_backend.dart  # Embedded ONNX (cross-platform)
│       ├── native_ocr_backend.dart    # OS OCR (Windows WinRT)
│       └── ctc_decoder.dart           # Pure-Dart CTC greedy decode
├── providers/        # Riverpod state
└── widgets/          # Ink canvas, toolbars, thumbnails
```

OCR flow on save:

1. Extract typed text from text-tool strokes
2. Rasterize handwriting strokes to PNG
3. Recognize via the active local OCR backend (embedded ONNX if a model is
   bundled, otherwise the platform's native OCR)
4. Merge recognized text into the local FTS index for search

## Local OCR

OCR runs entirely on-device through a pluggable backend (`lib/services/ocr/`).
`OcrBackends` selects, in order:

1. **`OnnxRecognitionBackend`** — embedded, cross-platform recognition via
   `flutter_onnxruntime` (CPU/iGPU; suited to low-power APUs). Active only when
   an ONNX model is bundled.
2. **`NativeOcrBackend`** — the OS built-in OCR (Windows WinRT today).

If no backend is available, OCR is a clean no-op — the app still works.

### Enabling the embedded ONNX model

The model is **not committed** (it is large). Fetch it onto your dev machine
before building so it bundles as an asset:

```bash
tool/fetch_ocr_model.sh   # downloads PP-OCRv4 rec ONNX + ppocr_keys_v1.txt
                          # into assets/models/ocr/  (proxy hint inside)
```

See [assets/models/ocr/README.md](assets/models/ocr/README.md). The recognition
geometry / CTC-blank assumptions (PP-OCRv4 mobile rec, 3×48×W, blank=0) are
documented in `onnx_recognition_backend.dart` and should be verified on-device
against your exact exported model.

> **Windows build note:** the `flutter_onnxruntime` plugin downloads the ONNX
> Runtime native library (v1.22.0) from GitHub at build time. Behind a firewall,
> set `HTTPS_PROXY` for the build (CMake honours it), or install ONNX Runtime
> system-wide and build with `-DUSE_SYSTEM_ONNXRUNTIME=ON
> -DONNXRUNTIME_ROOT_DIR=<path>`.

## Optional server

The `server/` directory contains an experimental FastAPI backend (sync + EasyOCR). It is **not required** for the desktop app and is kept separately for future multi-device sync experiments. See [server/README.md](server/README.md).

## Development

```bash
flutter run -d windows
flutter test
```