saitenka 0.9.0__tar.gz

saitenka-0.9.0/.gitignore

@@ -0,0 +1,9 @@
+# build/test scratch
+out.png
+*.out.png
+.pytest_cache/
+dist/
+*.egg-info/
+.coverage
+.pyscn/
+.complexipy_cache/

saitenka-0.9.0/.importlinter

@@ -0,0 +1,72 @@
+[importlinter]
+root_packages =
+    overlay
+include_external_packages = True
+exclude_type_checking_imports = True
+
+[importlinter:contract:no-cycles]
+name = No import cycles among overlay's top-level packages
+type = acyclic_siblings
+ancestors =
+    overlay
+# Ratchet baseline (2026-07-23): overlay/ is NOT layer-pure today (sc/model.py:11 already imports
+# overlay.render; sc/walk.py:19,230 too). These entries
+# grandfather the pre-existing cycles found on adoption so the gate is green on day one; burn them
+# down under the Stage 5 controller.py split, never add new ones. The mpvio<->app cycle (2 imports)
+# was fixed outright, not ratcheted: overlay/app/otel_metrics.py moved to overlay/otel_metrics.py —
+# it's a leaf instrumentation module with no app/ dependencies, so mpvio importing it from app/ was
+# a pure layering accident, not a real coupling. A facade wasn't needed; relocating the module to its
+# correct layer removed the backward edge entirely.
+# Burned down 2026-07-25: render.document -> sc.model and otel_export -> telemetry were removed here
+# when the ruff `TC` autofix moved those (typing-only) imports into TYPE_CHECKING blocks, so they are
+# no longer runtime edges — the ratchet tightened for free. Never re-add; only remove as edges vanish.
+ignore_imports =
+    overlay.draw.chip -> overlay.render.layout
+    overlay.app.dictdb -> overlay.app.yomitan_import
+    overlay.app.doctor -> overlay.app.crashlog
+    overlay.app.controller -> overlay.app.miner
+    overlay.app.report -> overlay.app.crashlog
+    overlay.app.dictdb -> overlay.app.wordlists
+
+[importlinter:contract:pil-agnostic-core]
+name = sc/ and model.py stay PIL-agnostic
+type = forbidden
+# Direct imports only (allow_indirect_imports): sc/ legitimately imports overlay.render for the
+# Inline type (see the no-cycles ratchet above) and render/draw pull in PIL themselves — a
+# transitive check would flag that pre-existing, accepted design. This preserves the original
+# test_layering.py semantics (a literal `import PIL` line), just without the hand-parsed
+# TYPE_CHECKING logic (exclude_type_checking_imports does that for free).
+allow_indirect_imports = True
+source_modules =
+    overlay.sc
+    overlay.model
+forbidden_modules =
+    PIL
+
+[importlinter:contract:pil-app-allowlist]
+name = app/ imports PIL only via raster/ or the migration allowlist
+type = forbidden
+allow_indirect_imports = True
+source_modules =
+    overlay.app
+forbidden_modules =
+    PIL
+# subtitles/toast/card_preview/controller migrate to the raster protocol opportunistically, later
+# (see tests/test_layering.py docstring, pre-existing allowlist).
+ignore_imports =
+    overlay.app.subtitles -> PIL
+    overlay.app.toast -> PIL
+    overlay.app.card_preview -> PIL
+    overlay.app.miner_ui -> PIL
+
+[importlinter:contract:gpl-chokepoint]
+name = only app.dictionary / app.doctor may import the GPL deinflect add-on
+type = forbidden
+source_modules =
+    overlay
+forbidden_modules =
+    saitenka_deinflect
+ignore_imports =
+    overlay.app.dictionary -> saitenka_deinflect
+    overlay.app.doctor -> saitenka_deinflect
+

saitenka-0.9.0/.python-version

@@ -0,0 +1 @@
+3.14+freethreaded

saitenka-0.9.0/.vulture_whitelist.py

@@ -0,0 +1,15 @@
+# Vulture whitelist — names that ARE used but look dead to static analysis because they're mandated by
+# an external interface signature (the caller passes them positionally). Regenerate/extend after review:
+#   uvx vulture src --min-confidence 80 --make-whitelist >> .vulture_whitelist.py
+# Advisory only (poe deadcode); not part of `all`. Keep this list tight — a genuine dead name hidden
+# here defeats the point.
+
+# structlog processor protocol: (logger, method_name, event_dict) — first two are required positionally.
+logger
+method_name
+
+# OpenTelemetry SpanExporter override signatures require these params even when unused.
+timeout_millis
+
+# POSIX signal handler protocol: handler(signum, frame).
+signum

saitenka-0.9.0/ARCHITECTURE.md

@@ -0,0 +1,80 @@
+# Architecture
+
+## What this is
+
+`saitenka` renders Yomitan `structured-content` (styled CJK text with ruby/furigana) as an
+image, composited directly into mpv's own OSD surface via `overlay-add` — one surface, no second
+window, so it survives fullscreen and sidesteps the Windows airspace/MPO bugs a second window would
+hit. Beyond the renderer, the codebase bolts a full reader onto mpv: subtitle draw with per-word
+hitboxes, hover → dictionary lookup → tooltip, word coloring by known/frequency/JLPT state, and
+one-key Anki mining.
+
+Design strategy: "simplest tool first, escalate on limits" (see README's Escalation ladder) —
+Pillow does the rendering today; Rust + cosmic-text + the libmpv render API is the fallback only if
+Pillow hits a real wall (per-frame animation, huge panels, GPU scaling).
+
+## Module map
+
+- **`sc/`** — Yomitan `structured-content` model and parsing (the input format). Kept PIL-agnostic
+  (enforced by `.importlinter`).
+- **`render/`** — layout/flow: the text walker, ruby positioning, line wrapping, panel chrome.
+  `render.flow` is the core. `render/window.py` is the PIL-free geometry kernel (block offset table +
+  half-open visible-range) and `render/banded.py` the **windowed (banded) tooltip engine**
+  (`WindowedPanel`): render only the blocks in the viewport±overscan, retain heights/hit-geometry past
+  pixel eviction, composite O(viewport) — pixel-identical to a `render_panel` crop. Wired into the base
+  tooltip behind `[tooltip].banded` / `SAITENKA_BANDED=1` (off by default; blob-slice path is default).
+- **`draw/`** — rasterization primitives that paint the laid-out content.
+- **`raster/`** + top-level **`panel`** — compose the final RGBA panel image; `Definition`/`Entry`
+  (in `panel.py`) hold one dictionary's rendered entry for a word. Value types with no render deps —
+  `model.Theme`, `version.overlay_version` — live at the package root to keep `render`/`app` acyclic.
+- **`parallel.py`** — the CPU-bound-render executor policy: free-threaded threads (FreeType releases
+  the GIL, faces are thread-local; ~78% of the render tail is `getmask2`/`getlength`), process-pool
+  fallback on a GIL build. Sub-interpreters are out (PIL's C extension segfaults across them).
+- **`mpvio/`** — the mpv IPC bridge: JSON-IPC transport (`ipc.py`), mpv/ffmpeg discovery
+  (`discover.py`), pushing panels into mpv's OSD surface (`osd.py`).
+- **`app/`** — the application layer. `controller.py`'s `Reader` is the main-loop orchestrator
+  (poll mpv → tokenize → hover hit-test → lookup → mine); `tokenize.py` (fugashi/unidic-lite word
+  segmentation); `dictionary.py`/`dictdb.py`/`lookup.py` (the consolidated SQLite dictionary DB);
+  `scoring.py`/`wordlists.py`/`fsrs.py` (word coloring); `anki.py`/`miner.py` (mining); `jimaku.py`
+  (subtitle fetching); `cli.py`/`cli_run.py` (the entry point — thin parser + real orchestration).
+
+## Data flow (the hover → lookup → render → mine chain)
+
+1. `Reader` polls mpv's `sub-text`/`mouse-pos` over IPC (event-driven `observe_property`).
+2. Each subtitle line is tokenized (`tokenize()`, fugashi + unidic-lite) into `Token`s with
+   per-word hitboxes, drawn as an OSD overlay.
+3. On hover, hit-testing maps screen coordinates to a token; the word's lemma is looked up against
+   the consolidated dictionary DB, producing an `Entry` (one `Definition` per configured
+   dictionary).
+4. The panel code (`panel.py`) walks the `Definition`s' structured content into a rendered tooltip
+   image via `render/` → `draw/`, composited over the mpv frame.
+5. Optionally, mining the hovered word builds an Anki note via AnkiConnect (`anki.py`, `miner.py`):
+   sentence, screenshot, audio clip, provenance.
+
+## Load-bearing decisions
+
+- **Single-surface compositing** (`overlay-add`, not a second window) is the whole point — it's
+  what makes this airspace-safe on Windows fullscreen.
+- **Dictionaries are imported once** into a consolidated SQLite DB (the Yomitan model); play-time
+  only opens it — nothing rebuilds during playback, RAM stays low.
+- **GPL-3.0 `saitenka_deinflect` is chokepointed**: only `app/dictionary.py` and `app/doctor.py`
+  may import it (enforced by import-linter + ruff `TID251` + the license gate) — keeps the core
+  Apache-2.0-clean.
+- **Free-threaded runtime** (Python ≥3.13, adopts 3.14t where available) — `assert`s across the
+  codebase double as GIL-off guardrails.
+
+## Test doubles (for the mpv boundary)
+
+- **`FakeIPC`** (`tests/util.py`) — in-process double for the mpv IPC client; feeds
+  subtitle/mouse properties and property-change events so `Reader`'s full loop runs without a real
+  mpv.
+- **`Driver`** (`tests/driver.py`) — wraps a `Reader` + `FakeIPC`, drives it through the *real*
+  input path (mouse moves, clicks, keys) so tests read as interaction scripts while still
+  exercising genuine hit-testing.
+- **`FakeMpvServer`** (`tests/fake_mpv_server.py`) — a real unix-socket server double, one layer
+  lower than `FakeIPC`, for attach-mode/transport tests needing actual socket/connection behavior.
+
+---
+
+Dependencies: `pyproject.toml`. Setup/run/test steps: README.md / RUNNING.md. Task-by-task dev
+gate: the `dev-gate` skill.

saitenka-0.9.0/BENCHMARKS.md

@@ -0,0 +1,226 @@
+# Responsiveness benchmark — in-mpv tooltip
+
+The perceived snappiness of the overlay is gated by a handful of latencies. This is the saved baseline
+so future changes can be compared against it. Regenerate with:
+
+```
+uv run python examples/bench_responsiveness.py --reps 12
+```
+
+It runs headless against the real dict set via a fake mpv IPC, so numbers **exclude mpv's own
+compositing + the socket round-trip** (a small, ~constant add) but include the real dictionary lookups,
+structured-content layout, BGRA conversion, and the temp-file upload write. "Cold" = OS/SQLite page
+cache warm but our per-word panel cache cleared (a fresh word mid-session); the very first hover after
+launch is slower because the 1.3 GB MonoB index is read from disk once.
+
+## KPIs and targets
+
+Ranked by what the eye notices. These are the numbers to watch for regressions:
+
+| KPI | Why it matters | Target |
+|---|---|---|
+| **Warm hover** (prefetched → shown) | the *common* case — prefetch warms the line while you read | **< 16 ms** |
+| **Cold first paint** (hover → first pixels) | the headline; the viewport-first head | **p50 < 100 ms, p95 < 250 ms** |
+| **Scroll frame** (one wheel step) | must stay under one display frame or scrolling stutters | **< 16 ms (60 fps)** |
+| **Poll-tick hover hit-test** | per-tick cost must be tiny vs the 25 ms poll interval | **< 5 ms** |
+| **Nested popup first paint** | first paint for an inner (scanned) word | **< 150 ms** |
+
+Secondary / diagnostic only: time-to-complete (the tail streams in behind the head, so it isn't
+blocking), cold sweep total (mitigated by prefetch), and the lookup / head-render / BGRA components
+(for locating *where* a regression is). "Scroll speed" is not a latency — it's px/step
+(`round(osd·0.12)` ≈ 130 px, coalesced per tick); what makes it feel good is the frame cost above.
+
+## Baseline — 2026-07-21
+
+Env: Apple M3 Pro · macOS 25.5.0 (arm64) · Python 3.13.5 · overlay commit `9d1864e` · single-threaded
+(prefetch off, so the head path is measured directly). Line `門前の小僧習わぬ経を読む`, 1080p,
+`tip_width` 640, `cap` 648 px. Dict set: 6 dicts + 7 freq + 1 pitch (`~/.config/saitenka/overlay.toml`).
+
+| metric | p50 | p95 | mean | min | (ms) |
+|---|---|---|---|---|---|
+| first paint (cold: head render + upload) | 49.0 | 510.7 | 116.9 | 26.3 | |
+| time-to-complete (finish deferred tail) | 138.0 | 152.0 | 139.9 | 131.9 | |
+| warm hover (prefetched → upload only) | 1.3 | 5.2 | 2.1 | 0.7 | |
+| scroll frame (one 130 px step) | 1.9 | 8.6 | 3.0 | 0.7 | |
+| nested popup first paint (inner word) | 121.1 | 129.0 | 121.6 | 115.4 | |
+| poll tick hover hit-test (`_update_hover`) | 0.4 | 0.5 | 0.5 | 0.4 | |
+| horizontal sweep: cold, 5 words (total) | 539.5 | 735.8 | 584.6 | 503.4 | |
+| horizontal sweep: warm, 5 words (total) | 5.0 | 20.1 | 7.2 | 3.4 | |
+| *component:* dict lookup, 5 words | 36.3 | 52.5 | 36.7 | 30.7 | |
+| *component:* head render, 5 words | 330.6 | 350.0 | 330.6 | 312.7 | |
+| *component:* BGRA convert, tallest head | 89.2 | 102.2 | 92.1 | 87.4 | |
+
+Verdict: warm hover, scroll, and hit-test are all far inside budget; cold first paint p50 is instant.
+
+## Known weakness
+
+Cold first-paint **p95 (~510 ms)** and BGRA-of-tallest (~90 ms): viewport-first renders **whole rows**
+until it covers `cap`, so if a word's *first* definition body is very tall (a big MonoB entry), the
+"head" overshoots to ~2000 px and costs nearly as much as the full panel. The ~860 ms → ~50 ms win
+holds for typical words but not for a word whose first dict entry is enormous. Lever (future item):
+**clip / stream the first def body itself**, not just defer later bodies.
+
+## Pathological corpus — baseline 2026-07-21 (before Stage 6/7 levers)
+
+The worst first-lookup words: the 3 largest-glossary entries per dict (auto-discovered from the built
+SQLite indexes) + hand-picked multi-sense words. Regenerate with:
+
+```
+uv run python examples/bench_responsiveness.py --pathological --reps 8
+```
+
+Env: Apple M3 Pro · macOS 25.5.0 · Python 3.14.6 (3.14t) · 1080p · tip_width 640 · cap 648 px ·
+6 dicts + 7 freq + 1 pitch. **Targets: cold p95 < 150 ms per word · first-hover-after-launch < 300 ms.**
+
+First-hover-after-launch (fresh SQLite connections, 上げる): **290.8 ms** (target met, barely; OS file
+cache warm — no sudo purge).
+
+| word | source | p50 | p95 | max | (ms) |
+|---|---|---|---|---|---|
+| 上げる | Bilingual | 181.8 | 183.7 | 183.7 | |
+| 挙げる | Bilingual | 178.5 | 187.5 | 187.5 | |
+| 揚げる | Bilingual | 180.0 | 181.6 | 181.6 | |
+| 気 | Bilingual2 | 234.7 | 244.0 | 244.0 | |
+| 手 | Bilingual2 | 157.4 | 158.8 | 158.8 | |
+| 目 | Bilingual2 | 168.5 | 202.0 | 202.0 | |
+| に | MonoC | 94.5 | 96.9 | 96.9 | |
+| の | MonoC | 82.4 | 84.3 | 84.3 | |
+| 取る | MonoC | 323.9 | 326.5 | 326.5 | |
+| 眼 | MonoD | 170.6 | 172.7 | 172.7 | |
+| とる | MonoB | 328.2 | 329.2 | 329.2 | |
+| 捕らぬ狸の皮算用 | MonoB | 124.6 | 125.6 | 125.6 | |
+| 取るに足りない | MonoB | 125.2 | 128.0 | 128.0 | |
+| 執る | MonoE | 321.7 | 329.0 | 329.0 | |
+| 採る | MonoE | 326.4 | 338.8 | 338.8 | |
+| 出る | hand-picked | 131.9 | 137.2 | 137.2 | |
+| かける | hand-picked | 247.3 | 284.8 | 284.8 | |
+| 見る | hand-picked | 89.4 | 91.6 | 91.6 | |
+| 行く | hand-picked | 116.6 | 118.3 | 118.3 | |
+| いい | hand-picked | 46.4 | 47.1 | 47.1 | |
+| **WORST** | over all words | **328.2** | **338.8** | **338.8** | |
+
+Verdict: 9 of 20 words MISS the 150 ms p95 target — the 取る family (~330 ms) and 気/かける (~250–285 ms)
+are the words whose first def body is a single enormous block. This is the Stage 6 lever's job.
+
+## After Stage 6 — deferred walk + mid-def raster clip (2026-07-21)
+
+Profiling showed the assumed culprit (raster overshoot) was only half the story: `panel_rows` walked
+EVERY def's structured content eagerly at build time, and the SC-walk of one 取る-class def alone costs
+~230 ms. Stage 6 therefore (a) moved the walk inside the deferred row thunks (one row per def body —
+the head only walks the defs the viewport shows), and (b) added mid-def raster clipping
+(`render_document`/`render_flow` `max_height`): the boundary def paints only the covering strip and
+finish() re-renders it fully, so the composed full panel stays byte-identical.
+
+Pathological corpus after Stage 6 (same env/flags):
+
+| KPI | baseline | after Stage 6 | target |
+|---|---|---|---|
+| WORST cold p50 (over 20 words) | 328.2 ms | **127.8 ms** | |
+| WORST cold p95 | 338.8 ms | **132.1 ms** | < 150 ms ✅ (all 20 words) |
+| WORST cold max | 338.8 ms | 132.1 ms | |
+| first-hover-after-launch (上げる) | 290.8 ms | **118.7 ms** | < 300 ms ✅ |
+
+Standard smoke-line benchmark also improved across the board (reps 8):
+
+| metric | baseline (2026-07-21) | after Stage 6 |
+|---|---|---|
+| first paint cold p50 / p95 | 49.0 / 510.7 | **21.8 / 46.1** |
+| nested popup first paint p50 | 121.1 | **34.1** |
+| horizontal sweep cold (5 words) p50 | 539.5 | **150.0** |
+| BGRA convert, tallest head | 89.2 | **6.3** (head is now a bounded strip) |
+| warm hover p50 / scroll frame p50 | 1.3 / 1.9 | 0.5 / 0.6 |
+
+## After Stage 7 — BGRA LUT · SQLite mmap · observe_property (2026-07-21)
+
+Three independent levers, all byte-identical / behavior-preserving:
+
+1. **BGRA LUT** (`osd.to_bgra_array`): the per-pixel uint16 widen×multiply÷255 premultiply replaced
+   by a flat `np.take` gather from a precomputed 256×256 table (64 KB, L2-resident). Property test
+   pins byte-identity vs the reference formula over random RGBA.
+2. **SQLite mmap** (`dictionary.Dictionary._conn`): `PRAGMA mmap_size=1073741824` +
+   `cache_size=-65536` (64 MiB) on every read-only per-thread connection — cold lookups hit mapped
+   memory instead of pread round-trips.
+3. **observe_property** (`controller`): `sub-text`/`mouse-pos`/`osd-dimensions`/`pause`/
+   `secondary-sub-text` are now event-driven — `run()` registers `observe_property` + one seeding
+   read each, and the poll loop consumes buffered `property-change` events. The 3–5 blocking
+   `get_property` round-trips per 25 ms tick are gone (this saves real-mpv socket latency that the
+   fake-IPC benchmark below cannot see). Dwell/hysteresis timers still tick on the loop.
+
+Pathological corpus (same env/flags): WORST cold p95 **132.1 → 133.2 ms** (noise-level — the corpus is
+CPU-bound and page-cache-warm, so levers 2–3 don't show here), first-hover-after-launch 118.7 →
+118.4 ms. Standard smoke line: first paint cold p50/p95 29.3/64.4, sweep cold 145.0, warm hover 0.5,
+scroll 0.5 — all within noise of the post-Stage-6 numbers. The mmap + observe_property wins are in
+disk-cold first hovers and live-mpv tick latency, both outside this harness's measurement envelope;
+targets remain met with margin (cold p95 < 150 ms ✅ all words · first-hover < 300 ms ✅).
+
+## Harness upgrades — tail latency, GIL guardrail, upload isolation, stress (2026-07-22, v0.2.0)
+
+Since this is a **real-time overlay** (it must not stall the poll loop or drop a video frame), the
+harness now reports the jank tail and the runtime that produced it, not just means:
+
+- **p99 + CV** on every metric. p99 is the jank tail (a p99 over the 16.7/33 ms frame budget drops a
+  frame even when p50 looks fine); CV (stdev/mean) is the run-to-run stability that decides whether a
+  metric is safe to regression-gate at all.
+- **Runtime line + GIL guardrail.** Every run records `Py_GIL_DISABLED` and the *live* `sys._is_gil_enabled()`
+  read **after** the workload (fugashi re-enables the GIL on first use, not at import). `--require-ft`
+  fails the run if the GIL came back — catching the silent worker-scaling collapse.
+- **Layer-isolated timing.** The cold path is split into `dict lookup` / `head render` / `BGRA convert`
+  / **`upload write` (warm reuse vs cold fresh+fsync)**. This settled the suspected ~55 ms temp-file
+  "floor": the write is **~1 ms** (warm and cold alike) — the number in older notes was the whole cold
+  first-paint, which is **render + lookup bound**, not IO. So mmap/shared-memory upload is not worth it.
+- **`--json`** emits a diffable baseline (metrics + runtime).
+
+### `--stress` — sustained chained session
+
+`bench_responsiveness.py --stress` chains cold hover → scroll → nested popup → scroll → dismiss over
+60+ distinct heavy entries for N rounds, surfacing what the isolated micro-benchmarks can't: panel-cache
+eviction thrash (the 48-entry LRU cap), nested-state churn, and memory growth across a session. It
+reports the per-op frame-latency tail (**MAX** = the jank signal) + peak RSS + growth, and can gate on
+`--max-frame-ms` / `--max-rss-mb`. The robustness half is always-on in the gate (`tests/test_stress.py`:
+no crash, cache stays ≤ 48, tooltip/nested overlays torn down with no ghost).
+
+First run on the full 19-dict rig flagged **MAX ~950 ms / p99 ~920 ms** per op — cold pathological
+monolingual entries blowing the frame budget under load (the known cold-p95 weakness, now visible in a
+sustained scenario). Confirms the open lever: **clip/stream the first def body**, not just defer later ones.
+
+### `--timeline` — idle-paced session (the felt-experience ground truth)
+
+`--stress` is deliberately worst-case: zero idle time, a shrunk 24-entry cache (vs. the real 128
+default), back-to-back heavy words. Real usage is the opposite — idle dominates (video plays, mouse
+doesn't move) punctuated by occasional hovers, with the background prefetch worker (`prefetch_lookahead`)
+warming ahead during the idle gaps. `--timeline` (`vibe/hot-path-idle-spreading-plan.md` Stage 1) models
+that: synthetic subtitle cues built from the real episode vocabulary (`examples/vocab.json` — 608 words
+from one Nippon Sangoku episode), advanced on a real clock (`time.sleep` between cues, so the real
+prefetch threads get real wall-clock idle time, not simulated time), with occasional injected hovers.
+Reports hover latency split **idle-warm** (the word's dictionary entries were already decoded before the
+hover) vs. **cold** (decoded synchronously, on hover), plus the worker's **lead time** (enqueued-as-upcoming
+→ decoded) against the idle budget it actually had (`lookahead × dwell`).
+
+Baseline — 2026-07-26, defaults (`--timeline-cues 80 --timeline-dwell-s 0.3 --timeline-lookahead 3`,
+900ms idle budget), 9 dicts + 9 freq + 1 pitch:
+
+| metric | p50 | p95 | max | n |
+|---|---|---|---|---|
+| hover latency — idle-warm | 36.8 | 75.7 | 75.7 | 20 |
+| hover latency — cold | — | — | — | 0 |
+| worker lead time (enqueued → decoded) | 175.5 | 410.6 | 410.6 | 19 |
+
+**0/20 misses** — at this dwell/lookahead the worker never fell behind; every hover in the run landed
+on an already-decoded word. **But "idle-warm" is not free**: idle-time warming (Stage 2) is decode-only
+(`entry_for`, no layout) — it does *not* pre-render the panel (Stage 4, pre-compiling heads, is explicitly
+deferred/opt-in because a pathological word's full render costs seconds, see `panel_mem.py` in the plan).
+So a first hover on a passively-watched (never engaged/paused) line still pays real layout + BGRA + upload
+cost even when fully idle-warm — this 36.8ms p50 is *that* cost, not the ~1-2ms "warm hover" KPI above,
+which assumes a FULL panel prefetch (only triggered once the user is already engaged — paused or hovering
+the video — which normal passive reading isn't, until the moment of the hover itself). Confirms the plan's
+Stage 4 lever (opt-in current-line head pre-compile) is the next step if this 30-75ms first-hover cost on
+a fresh line ever needs to shrink further; not yet built.
+
+### Profiling & continuous benchmarking (verified 2026-07)
+
+To *explain* a regression (not just report it): **Scalene** is the one profiler verified to work on
+free-threaded 3.13t/3.14t (full CPU+memory, with a GIL-activity timeline) — use it for "is this
+GIL/native/alloc bound". `py-spy --native` and `viztracer` are great for GIL-on runs but their
+free-threaded support is **unconfirmed** (both read/monitor interpreter internals that no-GIL changes) —
+check their trackers before relying. `pytest-benchmark` auto-disables under `pytest-xdist`, so any
+micro-suite must run serially, separate from the `-n auto` gate — the custom harness stays primary.

saitenka-0.9.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: saitenka
+Version: 0.9.0
+Summary: Rich-text + ruby renderer for the native in-mpv Yomitan overlay (Saitenka)
+Requires-Python: >=3.13
+Requires-Dist: certifi>=2026.6.17
+Requires-Dist: cyclopts>=4.22.1
+Requires-Dist: filelock>=3.32.0
+Requires-Dist: fonttools>=4.55
+Requires-Dist: fugashi>=1.5.2
+Requires-Dist: ijson>=3.5.1
+Requires-Dist: keyring>=25.7.0
+Requires-Dist: msgspec>=0.21.1
+Requires-Dist: numpy>=2.0
+Requires-Dist: pillow>=11.0
+Requires-Dist: platformdirs>=4.11.0
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: rich>=14.0
+Requires-Dist: stamina>=26.1.0
+Requires-Dist: structlog>=26.1.0
+Requires-Dist: tomlkit>=0.15.1
+Requires-Dist: unidic-lite>=1.0.8
+Provides-Extra: deinflect
+Requires-Dist: saitenka-deinflect; extra == 'deinflect'
+Provides-Extra: full
+Requires-Dist: jamdict-data-fix>=1.5.1a2; (platform_system == 'Windows') and extra == 'full'
+Requires-Dist: jamdict-data>=1.5; (platform_system != 'Windows') and extra == 'full'
+Requires-Dist: jamdict>=0.1a11.post2; extra == 'full'
+Requires-Dist: opentelemetry-api>=1.44.0; extra == 'full'
+Requires-Dist: opentelemetry-sdk>=1.44.0; extra == 'full'
+Requires-Dist: saitenka-deinflect; extra == 'full'
+Provides-Extra: jmdict
+Requires-Dist: jamdict-data-fix>=1.5.1a2; (platform_system == 'Windows') and extra == 'jmdict'
+Requires-Dist: jamdict-data>=1.5; (platform_system != 'Windows') and extra == 'jmdict'
+Requires-Dist: jamdict>=0.1a11.post2; extra == 'jmdict'
+Provides-Extra: minimal
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api>=1.44.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-sdk>=1.44.0; extra == 'telemetry'
+Description-Content-Type: text/markdown
+
+# overlay — rich-text + ruby renderer for the in-mpv Yomitan panel
+
+Renders Yomitan `structured-content` (styled, wrapping CJK text with **ruby/furigana**) into a
+panel **image**, so it can be composited over mpv video in a **single surface** (no second
+top-level window → no Windows airspace/MPO/fullscreen bugs).
+
+## Why Python + Pillow first
+
+Per the "simplest tool first, escalate on limits" rule: Pillow is the simplest thing that can
+rasterize styled CJK text + custom ruby positioning, and mpv's `overlay-add` IPC command can push
+a rendered RGBA image straight into mpv's own OSD surface — airspace-safe, no GL/FFI. We nail the
+**visual design** here (matching the real 読む popup) before escalating to Rust + cosmic-text +
+the libmpv render API if/when Pillow hits a wall.
+
+## Layout
+
+- `src/overlay/` — the library (`fonts`, `render/`, `model`, `sc/`, `panel`, `draw/`).
+- `assets/fonts/` — **vendored** Noto Sans JP (variable) + Noto Sans, so golden images reproduce
+  across machines (macOS / Windows / Linux).
+- `tests/golden/` — golden PNGs; `tests/fixtures/` — structured-content JSON.
+- `examples/render_png.py` — CLI: render a string or a fixture JSON to a PNG.
+
+Module-by-module map and the hover→lookup→render→mine data flow: [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Usage
+
+```bash
+uv sync
+uv run python examples/render_png.py --text "Saitenka" -o out.png
+uv run python examples/render_png.py --entry tests/fixtures/yomu.json --bg white -o panel.png
+uv run pytest            # golden tests
+SAITENKA_UPDATE_GOLDEN=1 uv run pytest   # regenerate goldens (inspect the diff first!)
+uv run python examples/bench_responsiveness.py   # UI latency vs the saved baseline (BENCHMARKS.md)
+```
+
+Responsiveness KPIs, targets, and the saved baseline live in [`BENCHMARKS.md`](BENCHMARKS.md).
+
+## Bolt to mpv (the airspace-safe cure)
+
+The panel is pushed into mpv's **own OSD surface** via the `overlay-add` JSON-IPC command — one
+surface, no second window, so it survives fullscreen (the Electron overlay bug can't recur). No GL,
+no FFI, no Rust.
+
+```bash
+# play a file and show the 読む panel top-left; press 'f' in mpv to test fullscreen
+uv run python examples/mpv_overlay.py /path/to/video.mkv
+
+# no file: generate a test clip, screenshot the composited mpv window, quit
+uv run python examples/mpv_overlay.py --screenshot /tmp/shot.png --seconds 2
+```
+
+A real mpv-window screenshot proving the composite is at `tests/artifacts/mpv_live_screenshot.png`.
+
+## MVP reader — subtitles + hover tooltip
+
+`examples/mpv_reader.py` is the working MVP: mpv plays a video, we hide its native subs and draw our
+own SubMiner-style subtitle (with per-word hitboxes), poll the mouse, and on **hover** look the word up
+(fugashi lemma → JMdict via jamdict) and draw a Yomitan-like tooltip — all in mpv's OSD surface.
+
+```bash
+uv run python examples/mpv_reader.py video.mkv --sub-file jp.srt   # hover words with the mouse
+uv run python examples/mpv_reader.py                                # test clip + generated JP line
+uv run python examples/mpv_reader.py --demo-word 読む --screenshot /tmp/reader.png  # screenshot demo
+```
+
+Result (real mpv window): `tests/artifacts/mvp_reader_hover.png`. The dictionary adapter
+(`app/lookup.py`) emits the same `Entry` the renderer already draws, so a monolingual / structured-
+content dictionary can be swapped in behind it later without touching the renderer.
+
+### Word coloring (SubMiner-parity, FSRS-aware)
+
+`app/scoring.py` colors each subtitle word: **N+1 > known > frequency-band > base** text color, plus a
+JLPT-level **underline** — the exact priority model SubMiner uses (Catppuccin palette). Known words come
+from Anki (`app/wordlists.py::KnownWords.from_ankiconnect`, decks→fields like SubMiner) or a static set;
+frequency from any Yomitan freq zip (user-supplied, e.g. under `tools/freq/`); JLPT from the vendored
+`assets/wordlists/jlpt.zip`. Result: `tests/artifacts/mvp_reader_colored.png`.
+
+```bash
+uv run python examples/mpv_reader.py --sub-file jp.srt --color \
+  --known "私,本,経" --freq "Frequency General"
+# or pull the known-set from Anki:
+uv run python examples/mpv_reader.py --sub-file jp.srt --color \
+  --anki-decks '{"Kaishi 1.5k":["Word"]}'
+```
+
+### Subtitle source: embedded / jimaku / file
+
+The reader takes subs from (in order): `--sub-file` → `--jimaku` (fetch from jimaku.cc, needs
+`$JIMAKU_API_KEY`) → the video's **embedded** JP track (`--slang ja,jpn`, auto-selected, native
+rendering hidden). Amazon-style **inline furigana** baked into ASS (`龍門光英りゅうもんみつひで`) is
+stripped before tokenizing (`app/tokenize.py::strip_inline_furigana`).
+
+```bash
+# real anime with an embedded JP track + your real Anki known-set (FSRS deck):
+uv run python examples/mpv_reader.py "Nippon Sangoku - 10 [...MultiSub...].mkv" \
+  --color --anki-decks '{"Saitenka::Known":["Entry","Expression","Word"]}' \
+  --freq "Frequency General"
+
+# a file with no JP subs → fetch from jimaku (title/episode parsed from the filename):
+uv run python examples/mpv_reader.py show.mkv --jimaku --color
+```
+
+### One-key mining (on one surface)
+
+`--mine` enables mining: hover a word, press the mine key (default `Ctrl+m`) → a **Lapis** card is
+created via AnkiConnect with Expression / reading / **Sentence** (mined word bolded) / **Glossary** /
+**Picture** (clean frame) / **SentenceAudio** (the subtitle's audio span, ffmpeg mp3) / provenance /
+JMdict ID. Dedup checks the deck first (no silent duplicates); a toast confirms (`✚ mined …` /
+`● already have …` / `× …`). All inside mpv's surface — no texthooker, no second window.
+
+```bash
+uv run python examples/mpv_reader.py episode.mkv --color \
+  --anki-decks '{"Saitenka::Known":["Entry","Expression","Word"]}' \
+  --freq "Frequency General" \
+  --mine --mine-deck "Saitenka::Mining" --mine-model Lapis
+# then hover a word in mpv and press Ctrl+m
+```
+
+Verified end-to-end on a real episode: the card is built with a real frame jpg + subtitle mp3,
+deduped, then cleaned up.
+
+- **Bulk mining** — `Shift+m` mines every unknown content word in the current cue, all sharing one
+  screenshot + audio clip; toast reports `mined N · M dup`.
+- **Card preview (verify without alt-tab)** — after mining, a **fixed-layout** panel shows the card so
+  you can check it's right: status, headword + reading, the sentence (mined word bolded), the meaning,
+  the **actual captured frame**, and the audio (`▶ Ns`, which **auto-plays** so you hear the clip). Mining
+  an already-present word previews the **existing** card instead (image + audio pulled from Anki). `p`
+  replays the last preview + audio. It's composed from our own primitives — no card CSS — purely to
+  verify correctness / image / sound.
+
+### Multi-dictionary tooltip (Yomitan-style, ordered)
+
+Import any **Yomitan term-bank** dictionaries (bilingual and/or monolingual — whichever you have) once
+with `saitenka import <dir>`; they build into a single **consolidated database**
+(`~/.local/share/saitenka/dictionaries.sqlite`, the Yomitan model). Then `--dict "Title A" --dict
+"Title B" …` (or the config lists) shows the word across all of them, **in order**, each as its own
+section with the dict-name pill and rich structured content (ruby examples, notes, cross-refs). Runtime
+only opens the DB — nothing is rebuilt at play time, and RAM stays low. Falls back to JMdict/jamdict when
+no dictionary is configured.
+
+### Official-translation reveal (anti-crutch)
+
+Default is **JP primary (mining) + EN secondary**: the reader auto-selects the JP sub track (`--slang
+ja,jpn,jp`) and the embedded EN track as mpv's *secondary* sub (hidden). Press `t` to toggle the EN
+line for the current cue above the JP subtitle — the professional translation on demand, not by default.
+
+```bash
+saitenka import ~/yomitan-dicts   # once: build the DB, register the titles in the config
+uv run python examples/mpv_reader.py episode.mkv --color \
+  --anki-decks '{"Saitenka::Known":["Entry"]}' --mine \
+  --dict "Bilingual Dict" \
+  --dict "Monolingual Dict A" \
+  --dict "Monolingual Dict B"
+# hover a word; Ctrl+m mine · Shift+m mine-all · t translation
+```
+
+## Escalation ladder (simplest tool first)
+
+Pillow + `overlay-add` is the simplest thing that renders this and gets it onto mpv. If it hits a
+wall — per-frame animation, huge panels, GPU scaling, live interactivity — escalate to Rust +
+cosmic-text + the libmpv render API (see `rust/README.md`). The renderer here (walker, ruby, chrome,
+goldens) is the spec that escalation must match.
+
+## Sharing it with a friend (self-contained bundle)
+
+No PyPI or public repo needed. Build one shareable archive and send it:
+
+```bash
+uv run poe bundle                        # → dist/saitenka-<ver>.zip
+```
+
+The zip carries the wheel (all fonts/wordlists/lua/data ride inside it via `importlib.resources`),
+both bootstrap installers, and an INSTALL.txt. Your friend unzips and runs the stub for their OS:
+
+```bash
+bash overlay-install.sh                   # macOS / Linux  (--dry-run to preview)
+powershell -ExecutionPolicy Bypass -File overlay-install.ps1   # Windows
+```
+
+The stub's only job is to get `uv`, `uv tool install ./<wheel>`, and hand off to
+`saitenka setup` — an interactive Python wizard that inventories the box, installs mpv +
+ffmpeg (macOS `brew`; Windows winget→choco→scoop; Linux prints copy-paste hints), runs `doctor`,
+writes the config (`init`), and offers `import-settings` + `install-plugin`. Every step is
+confirm-first, `--yes`/`--dry-run` are honoured, and it is resumable (re-runs skip satisfied steps).
+Upgrade = re-run with a newer bundle (`uv tool install --reinstall ./<wheel>`).
+
+## Development
+
+Local task runner (no CI); `uv run poe all` is the pre-push gate. Full task-by-task breakdown and
+traps: [RUNNING.md](RUNNING.md) §9 / the `dev-gate` skill.