Hankan · 한칸

A Korean reading tutor for manhwa. One codebase, two shells: a web app and an Android app. Works entirely offline — there is no server.

Ported from a single-file Claude artifact. The curriculum, the tutor prompt and the five logic modules came finished and tested; this repo is the application built around them.

---

What is here

data/  lib/  prompt/  validate.mjs     verbatim from the export bundle — do not edit
shared/                                band table + phonological ladder, shared by app and build
types/                                 TypeScript declarations for lib/ and shared/
tools/dict/                            the dictionary build pipeline
app/                                   Vite + React + TypeScript, and the Capacitor shell
  src/db/                              one storage interface, two SQLite drivers
  src/domain/                          the gate, the lexicon, SRS, the tutor clients
  src/sync/                            push/pull against the Pi
  src/ui/                              six tabs, the review overlay, the 한글 keyboard
  public/dict/                         generated dictionary — committed, shipped
server/                                sync + the tutor endpoint (optional)
tools/icons/                           the 한칸 mark, generated
test/                                  lib goldens, driver conformance, domain, sync, SSE

data/, lib/, prompt/ and validate.mjs are byte-identical to the export and are excluded from lint and formatting. lib/conjugation.js encodes the seven Korean irregular classes and is the reason no runtime morphological analyser is needed; lib/hangul.js implements 두벌식 composition. Types are supplied alongside in types/, so neither file had to be touched.

Running it

npm install
npm run dict:build     # only needed if app/public/dict/ is missing or stale
npm run dev            # http://localhost:5173

npm run check          # validate.mjs, typecheck, tests, roadmap assertion
npm run build          # production build + service worker

Android

The Capacitor project lives at app/android/ and is committed. It needs the Android SDK, which this repo does not install:

export ANDROID_HOME=/path/to/Android/Sdk
npm run build
npm run cap:sync
cd app/android && ./gradlew assembleDebug

npx cap sync copies app/dist/ — including the dictionary — into the APK's assets, so the phone build is as offline as the web one.

How it works

Storage — one interface, two drivers

app/src/db/ exposes a single Db interface. sqlite.web.ts runs @sqlite.org/sqlite-wasm in a dedicated Worker over the OPFS SAHPool VFS (the plain OPFS VFS needs COOP/COEP headers, which neither a static host nor the Capacitor webview reliably provides). sqlite.native.ts uses the Capacitor SQLite plugin. Both apply the same migration array from migrations.ts.

Seeded state never carries a write timestamp. The artifact had a sync bug where a fresh device stamped its own empty defaults as newer than the server's real history and clobbered it. Three layers stop that from being expressible: every syncable table declares updated_at INTEGER NOT NULL DEFAULT 0, so forgetting the column is the safe failure; db/writes.ts splits every mutation into seedX() (never stamps) and editX() (always stamps) and is the only file allowed to read the clock; an ESLint rule enforces that, and the conformance suite asserts a freshly seeded database has no non-zero updated_at anywhere.

The dictionary

npm run dict:build merges a dictionary source, a frequency list, the curated data in data/, and a hand-written grammar lexicon, then runs lib/conjugation.js → surfaceForms() over every verb and adjective to fill the surface table. Lookup of a conjugated form is therefore an index hit, not an analysis — no runtime morphological analyser ships.

Sources are chosen automatically: KRDICT if a download has been vendored (it has curated learner glosses and a graded 초급/중급/고급 level), otherwise the kaikki.org Korean extract. KRDICT's download page is a JavaScript form behind anti-bot protection, so it cannot be fetched by a script — see the comment at the top of tools/dict/fetch.mjs.

Frequency needs care: a subtitle frequency list holds surface forms while a dictionary holds lemmas, and a naive join on the headword gives every verb a frequency of roughly zero. tools/dict/freq-forms.mjs inverts the join — expanding each lemma into the forms it plausibly takes and summing — which recovers 하다 from 118 to 89,041.

Output is one gzipped row dump per band, committed under app/public/dict/. They are static assets in the bundle and in the APK's assets, so no server is involved. Attribution is in NOTICE.md; share-alike attaches to the dictionary data, not to this code.

The gate

lib/gate.js computes what the tutor may teach from the curriculum plus progress, and renderGate() renders it into {{GATE}} in prompt/tutor-system.md, which ships unchanged. buildGate() takes a vocabQuery hook; app/src/domain/gate.ts fills it with a frequency-band query so vocabulary grows as units are finished. Three refinements sit inside that hook, all of them narrowing:

1. words a not-yet-finished unit is the first to introduce are excluded, so a band ceiling cannot smuggle 3.4's material into 2.1;
2. during Phase 1 the results are filtered by the same phonological ladder validate.mjs checks, so a band cannot hand the learner a 겹받침 at 1.4;
3. the list is capped at 800 by frequency, because renderGate() inlines it into the prompt. The cap is strictly more restrictive than the band.

Confidence is clamped to MAX_DELTA_PER_TURN per turn. The artifact wrote the model's number straight into the advancement gate, so one hallucinated ::progress 95 could skip a unit.

The tutor

app/src/domain/stub-tutor.ts stands in for the model and implements the exact contract the real endpoint will (onText receives cumulative text; an aborted turn keeps what it streamed). It rotates all four exercise types, builds its ::words from the current unit's real vocabulary, and climbs ::progress gradually, so every render path — including the 85% advancement banner — is reachable with no server. Swapping in the Pi's SSE endpoint later touches only that file.

Checks

Command	What it guards
node validate.mjs	the curriculum. PASS — 0 blocking, 0 advisory
npm test	lib golden tests, driver conformance, the seeded-timestamp rule, the gate
npm run dict:assert	371/371 roadmap words resolve (was 167 unglossable)
npm run typecheck · npm run lint	types, and the clock guard on src/db/

CI runs them in that order, validate.mjs first.

Sync and the tutor — optional, and genuinely optional

The app is complete without a server: its own SQLite, the shipped dictionary, and a local stand-in tutor. Pointing it at a Pi adds two things — the real 선생님, and syncing between devices. Everything degrades to the offline behaviour when the server is unreachable, and a sync failure is recorded in settings rather than surfaced as an interruption.

Setup, the Caddy config, and how sync resolves conflicts: server/README.md.

Three details worth knowing here:

• Seeded rows carry updated_at = 0, so a fresh device can neither push its empty defaults nor win a conflict with them. The artifact's clobbering bug is unrepresentable rather than merely avoided, and test/sync/roundtrip.test.ts asserts it against a real Postgres.
• An allowlist decides what leaves the device. meta mixes preferences with per-install bookkeeping; dict.loadedBands crossing the wire would tell a phone it holds rows it never downloaded.
• The system prompt is cached. It is ~12k characters of gate, identical for as long as the learner stays in one unit, so every turn after the first reads it at a fraction of the input price.
• The model is a config line, not a code change. HANKAN_TUTOR_BACKEND selects the Claude API, any OpenAI-compatible endpoint (LM Studio, Ollama, llama.cpp, vLLM, OpenRouter), or a keyless echo backend for proving a deployment. Keeping the system prompt first and unchanged is what makes Anthropic's prefix cache work — and, it turns out, a local server's KV cache too: 1,563ms to first token cold, 324ms warm.

Not in this pass

Android beyond the existing Capacitor scaffold, and Play Store packaging.

Known limitation

lib/blocks.js parse() does not close a ::gloss block on its = line, so a multi-sentence gloss collapses into one run-on line. Since lib/ ships unchanged, app/src/domain/gloss.ts splits the block and parses each sentence separately. The behaviour is pinned in test/lib/blocks.test.ts; if the library is ever revised, the one-line fix is cur = null and both workarounds go.