ucode 0.1.0

data/TODO.new/10-aggregations-ucd-rewrite.md

@@ -0,0 +1,168 @@
+# 10 — Aggregations rewrite on ucode UCD
+
+## Goal
+
+The aggregations extractor is the only one that does **not** port
+mechanically from fontisan. Fontisan's version reads `ucd.all.flat.zip`
+via UCDXML. ucode's version uses ucode's own parsed UCD text files
+(UnicodeData.txt, Blocks.txt, Scripts.txt, ScriptExtensions.txt) —
+which is the whole reason for the migration.
+
+This is also the extractor that produces the Unicode-coverage output
+fontist.org consumes, so the schema (`blocks`, `scripts`,
+`plane_summaries`, `discrepancies`) must match `02-audit-schema-design.md`
+exactly.
+
+## Files to create
+
+- `lib/ucode/audit/extractors/aggregations.rb` — main extractor.
+- `lib/ucode/audit/block_aggregator.rb` — given codepoints + ucode
+  baseline, produce `BlockSummary[]`.
+- `lib/ucode/audit/script_aggregator.rb` — given codepoints + ucode
+  baseline, produce `ScriptSummary[]`.
+- `lib/ucode/audit/plane_aggregator.rb` — roll up block summaries into
+  `PlaneSummary[]`.
+- `lib/ucode/audit/discrepancy_detector.rb` — produce `Discrepancy[]`
+  from font OS/2 ulUnicodeRange bits vs cmap codepoints.
+- Plus update `lib/ucode/audit/registry.rb` to add `Aggregations`
+  to `ORDERED_EXTRACTORS` (last entry; not in `BRIEF_EXTRACTORS`).
+
+Specs:
+- `spec/ucode/audit/extractors/aggregations_spec.rb`
+- `spec/ucode/audit/block_aggregator_spec.rb`
+- `spec/ucode/audit/script_aggregator_spec.rb`
+- `spec/ucode/audit/plane_aggregator_spec.rb`
+- `spec/ucode/audit/discrepancy_detector_spec.rb`
+
+## What to use from ucode
+
+ucode already provides (see `docs/FONTISAN_MIGRATION.md` API list):
+
+- `Ucode::Database.open(version)` / `.cached?(version)` — SQLite-backed
+  lookup.
+- `Ucode::Database#lookup_block(cp)` → block name (RangeEntry).
+- `Ucode::Database#lookup_script(cp)` → script name.
+- `Ucode::Database#each_block_overlapping(first, last)` — for block
+  range queries.
+- `Ucode::Database#block_entries` → all `(first, last, name)` triples.
+- `Ucode::Database#script_entries` → ditto for scripts.
+- `Ucode::Aggregator.aggregate_blocks(codepoints, blocks_index)` —
+  existing helper, may need extension.
+- `Ucode::Aggregator.aggregate_scripts(codepoints, scripts_index)` —
+  existing helper.
+
+**Use these.** Do not re-implement UCD parsing in the audit namespace.
+The aggregation logic IS new (it produces `BlockSummary` shapes with
+status/missing/etc.), but the underlying UCD lookup is ucode's
+existing API.
+
+## Algorithm — BlockAggregator
+
+Input: `codepoints` (sorted `Integer[]`, from Coverage extractor) +
+`baseline` (the `Ucode::Database` for the target version).
+
+Output: `Ucode::Models::Audit::BlockSummary[]` (one per touched block).
+
+```
+1. For each codepoint in the font:
+   - block_name = baseline.lookup_block(cp)
+   - tally[block_name] << cp
+   - track touched_blocks set
+2. For each touched block:
+   - first_cp, last_cp = baseline.block_range(block_name)
+   - plane = first_cp >> 16
+   - total_assigned = count of codepoints in [first_cp, last_cp]
+     where baseline says "assigned" (not reserved/unassigned).
+     For Unicode 17 new blocks, use the curated Unicode17Blocks
+     table (handles reserved gaps like Beria Erfe U+16EB9-U+16EBA).
+   - covered_count = tally[block_name].size
+   - missing_codepoints = assigned_set - tally[block_name]
+   - status = pick from enum per 02-audit-schema-design.md
+3. Return BlockSummary[] sorted by first_cp.
+```
+
+The "is this codepoint assigned?" check is the subtle bit. ucode's
+baseline knows via UnicodeData.txt entries (a codepoint is assigned
+iff it has a name entry, modulo `<range>` markers). For blocks where
+the curated `Unicode17Blocks` overrides apply, use those (Beria Erfe
+reserved gap, etc.). This logic lives in `Ucode::Database` or a new
+helper; do not duplicate it in the aggregator.
+
+## Algorithm — ScriptAggregator
+
+Same shape but keyed on `lookup_script(cp)`. Note: ScriptExtensions
+means a codepoint can have multiple scripts. Use `ScriptExtensions.txt`
+to expand — a codepoint in `ScriptExtensions: Latn;Grek` contributes
+to both `Latn` and `Grek` tallies.
+
+Output: `ScriptSummary[]` (one per touched script).
+
+## Algorithm — PlaneAggregator
+
+Roll up `BlockSummary[]` by `plane`. Straightforward sum.
+
+## Algorithm — DiscrepancyDetector
+
+Read `font.table("OS/2").ul_unicode_range1..4` (4 × 32-bit = 128 bits).
+Each bit corresponds to a Unicode range (per OpenType spec, "Unicode
+Range Bits" table). For each set bit, look up the corresponding
+codepoint range; if the cmap has zero codepoints in that range, emit
+a `Discrepancy` of kind
+`"os2_unicode_range_bit_without_cmap_codepoints"`.
+
+Also detect the inverse: cmap codepoints in a range the OS/2 bits
+don't claim. Less critical; emit as
+`"cmap_codepoints_outside_os2_unicode_range"`.
+
+Map of OS/2 ulUnicodeRange bit → range lives in OpenType spec. Embed
+as a constant table in the detector.
+
+## Output schema
+
+The `Aggregations` extractor returns a hash:
+
+```ruby
+{
+  baseline: Baseline.new(unicode_version: ..., ...),
+  blocks: [...],
+  scripts: [...],
+  plane_summaries: [...],
+  discrepancies: [...],
+}
+```
+
+The `AuditReport` constructor merges this into the right attributes.
+
+## Acceptance
+
+- Aggregations extractor produces a non-empty `blocks` array for any
+  font with at least one assigned codepoint.
+- For a fixture font with known coverage (e.g. Noto Sans Sidetic
+  covering all 26 Sidetic codepoints), the audit reports:
+  - `block_summaries` entry for Sidetic with `status: "COMPLETE"`,
+    `covered_count: 26`, `missing_codepoints: []`.
+- For a partial-coverage fixture (e.g. Inter covering 80/135 Greek):
+  - `block_summaries` entry with `status: "PARTIAL"`,
+    `missing_count: 55`, `missing_codepoints: [881, 883, ...]`.
+- Plane rollups correctly sum multi-block planes (BMP has ~200
+  blocks; rollup counts all).
+- Discrepancies detect a deliberately-broken fixture (OS/2 bit set
+  but cmap empty in that range).
+- The `Baseline` struct reports `unicode_version`, `ucode_version`,
+  `source: "ucd-text + Unicode17Blocks overrides"`.
+- All specs use real `Ucode::Database` instances (built from fixture
+  UCD slices under `spec/fixtures/ucd/`).
+- No `double()`.
+- Rubocop clean.
+
+## References
+
+- Schema: `TODO.new/02-audit-schema-design.md`
+- ucode UCD API: `docs/FONTISAN_MIGRATION.md` §"Coordinator + Indices"
+- Existing helpers: `lib/ucode/aggregator.rb`, `lib/ucode/database.rb`
+- Curated overrides: `lib/ucode/glyphs/real_fonts/unicode_17_blocks.rb`
+  (move to `lib/ucode/ucd/unicode_17_overrides.rb` as part of this TODO
+  if it makes the dependency cleaner)
+- Source being replaced:
+  `fontisan/lib/fontisan/audit/extractors/aggregations.rb` (reference
+  for the field shape, but the implementation is replaced)

data/TODO.new/11-differ-and-library-auditor-port.md

@@ -0,0 +1,102 @@
+# 11 — Differ + library auditor port
+
+## Goal
+
+Port fontisan's `Differ` (diffs two `AuditReport`s) and `LibraryAuditor`
+/ `LibraryAggregator` (audits a directory of fonts and rolls up).
+These are higher-level orchestration on top of the per-face audit
+covered by TODOs 06-10.
+
+## Files to create
+
+- `lib/ucode/audit/differ.rb` — port from fontisan.
+- `lib/ucode/audit/library_auditor.rb` — port from fontisan.
+- `lib/ucode/audit/library_aggregator.rb` — port from fontisan.
+- `lib/ucode/audit/codepoint_range_coalescer.rb` — port from fontisan
+  (already partially ported in TODO 08 if Coverage needs it; if not,
+  port here as a Differ dependency).
+- Specs for each.
+
+## Port from fontisan
+
+- `fontisan/lib/fontisan/audit/differ.rb`
+- `fontisan/lib/fontisan/audit/library_auditor.rb`
+- `fontisan/lib/fontisan/audit/library_aggregator.rb`
+- `fontisan/lib/fontisan/audit/codepoint_range_coalescer.rb`
+- `fontisan/lib/fontisan/models/audit/audit_diff.rb` (already ported in
+  TODO 07; consumed by `Differ`)
+- `fontisan/lib/fontisan/models/audit/codepoint_set_diff.rb` (ditto)
+- `fontisan/lib/fontisan/models/audit/field_change.rb` (ditto)
+- `fontisan/lib/fontisan/models/audit/duplicate_group.rb` (ditto)
+- `fontisan/lib/fontisan/models/audit/library_summary.rb` (ditto)
+
+## Differ adjustments
+
+The fontisan `Differ` produces an `AuditDiff` containing:
+
+- `field_changes` — `FieldChange[]` (per-field old/new).
+- `codepoint_set_diff` — `CodepointSetDiff` (added/removed codepoints).
+- `block_changes` — per-block coverage deltas.
+
+Port unchanged. The ucode version operates on `Ucode::Models::Audit::AuditReport`
+instances instead of fontisan's.
+
+## LibraryAuditor adjustments
+
+The fontisan `LibraryAuditor`:
+
+1. Walks a directory (optionally recursive).
+2. For each font file, runs an `AuditCommand`.
+3. Collects reports + tracks skipped files (non-font files, permission
+   errors, etc.).
+4. Returns an array of reports.
+
+Port unchanged. The ucode version delegates to `Ucode::Audit::Command`
+(added in TODO 13 with the CLI; this TODO assumes its existence or
+extracts the orchestrator earlier — see Implementation Order).
+
+## LibraryAggregator adjustments
+
+The fontisan `LibraryAggregator` takes an array of reports and produces
+a `LibrarySummary`:
+
+- Total font count.
+- Per-block coverage aggregated across all fonts (max / union /
+  intersection).
+- Duplicate detection — `DuplicateGroup[]` for fonts with identical
+  `source_sha256` or identical codepoint sets.
+- Per-foundry totals (grouped by `font.family_name` or by
+  `licensing.manufacturer`).
+
+Port unchanged.
+
+## CLI integration
+
+The library auditor is wired to the CLI in TODO 16 as
+`ucode audit library <dir>`. The compare/differ is wired as
+`ucode audit compare <left> <right>`. This TODO just delivers the
+orchestration classes; CLI is a separate concern.
+
+## Acceptance
+
+- `Ucode::Audit::Differ.new(left_report, right_report).diff` returns
+  an `AuditDiff` with all three sections populated for a meaningfully-
+  different report pair.
+- `Ucode::Audit::Differ` on identical reports returns an `AuditDiff`
+  with empty arrays (no false positives).
+- `Ucode::Audit::LibraryAuditor.new(dir, recursive: true, options:).audit`
+  walks the directory and produces one report per font, skipping
+  non-font files with a record in `#skipped`.
+- `Ucode::Audit::LibraryAggregator.aggregate(reports)` returns a
+  `LibrarySummary` with per-block union coverage and duplicate groups.
+- Spec uses a fixture library directory with 3-5 small fonts (some
+  duplicates, some unique).
+- No `double()`.
+- Rubocop clean.
+
+## References
+
+- Reports: `TODO.new/07-audit-models-port.md`
+- Source: `fontisan/lib/fontisan/audit/{differ,library_auditor,library_aggregator,codepoint_range_coalescer}.rb`
+- CLI wiring: `TODO.new/16-cli-audit-subcommands.md`
+- Output: `TODO.new/13-directory-emitter.md` (library mode layout)

data/TODO.new/12-formatters-port.md

@@ -0,0 +1,115 @@
+# 12 — Formatters port
+
+## Goal
+
+Port fontisan's text-rendering formatters. These power the
+human-readable output of `ucode audit font` (text rendering to stdout)
+and `ucode audit compare` (diff rendering). They are presentation-only
+— they take an `AuditReport` (or `AuditDiff`, `LibrarySummary`) and
+return a string.
+
+## Files to create
+
+- `lib/ucode/audit/formatters.rb` — namespace hub.
+- `lib/ucode/audit/formatters/audit_text.rb` — port from fontisan
+  `AuditTextRenderer`.
+- `lib/ucode/audit/formatters/audit_diff_text.rb` — port from fontisan
+  `AuditDiffTextRenderer`.
+- `lib/ucode/audit/formatters/library_summary_text.rb` — port from
+  fontisan `LibrarySummaryTextRenderer`.
+- `lib/ucode/audit/formatters/text_formatter.rb` — port from fontisan
+  `TextFormatter` (shared utilities).
+- Specs for each.
+
+## Port from fontisan
+
+- `fontisan/lib/fontisan/formatters/text_formatter.rb`
+- `fontisan/lib/fontisan/formatters/audit_text_renderer.rb`
+- `fontisan/lib/fontisan/formatters/audit_diff_text_renderer.rb`
+- `fontisan/lib/fontisan/formatters/library_summary_text_renderer.rb`
+
+## Adjustments vs fontisan
+
+The formatters read from the report model. Since ucode's report
+shape differs from fontisan's (see `02-audit-schema-design.md`):
+
+- Read `report.baseline.unicode_version` instead of `report.ucd_version`.
+- Read `report.scripts` (`ScriptSummary[]`) instead of
+  `report.unicode_scripts` (`String[]`). Render as a table with
+  coverage percentages, not a flat list.
+- Read `report.blocks` (`BlockSummary[]` with `status`, `coverage_percent`)
+  instead of fontisan's `AuditBlock[]` (with `fill_ratio`, `complete`).
+- Render the `discrepancies` array if non-empty (fontisan has no
+  equivalent section).
+- Render `plane_summaries` if non-empty (fontisan has no equivalent).
+
+The text formatter's job is to make the audit output scannable in a
+terminal. Aim for the same density as `git diff` or `ls -la`: short
+columns, alignment, color codes via ANSI (honor `NO_COLOR=` env var).
+
+## Output examples
+
+### `ucode audit font Inter-Regular.ttf`
+
+```
+Inter Regular  (Inter-Regular.ttf, ttf, sha256: 3b1a…)
+  Version 4.000;git-a52131595    fontRevision 4.0
+  Weight 400  Width 5  PANOSE 2 0 5 3 6 …
+
+  Coverage: 2,857 codepoints across 1,486 glyphs
+  Baseline: Unicode 17.0.0 (ucd-text + Unicode17Blocks overrides)
+
+  Plane 0 (BMP): 2,857 / 55,000 (5.2%)
+  Plane 1 (SMP): 0 / 12,000 (0.0%)
+  …
+
+  Blocks touched: 24 (12 complete, 12 partial)
+    Basic Latin                  U+0000–U+007F    128/128  COMPLETE
+    Greek and Coptic             U+0370–U+03FF     80/135  PARTIAL (55 missing)
+    …
+
+  Scripts touched: 5
+    Latin      1,307/1,207  COMPLETE
+    Greek         80/135    PARTIAL
+    …
+
+  Discrepancies: 1
+    OS/2 ulUnicodeRange bit 7 (Greek) set but cmap has 0 Greek
+    codepoints outside U+0370–U+03FF subset.
+```
+
+### `ucode audit compare old.json new.json`
+
+```
+Inter-Regular  →  Inter-Regular (v4.0 → v4.1)
+
+  Field changes:
+    version              Version 4.000 → Version 4.100
+    font_revision        4.0 → 4.1
+    total_codepoints     2,857 → 2,910 (+53)
+
+  Codepoint set:
+    + 53 added    - 0 removed    = 2,910 final
+    Added (sample): U+037D, U+037E, U+0387, …
+
+  Block changes:
+    Greek and Coptic    80/135 → 133/135 (+53 covered)
+    Latin Extended-D     0/112 → 0/112   (no change)
+```
+
+## Acceptance
+
+- All 4 formatter files exist; each has a passing spec.
+- A fixture `AuditReport` renders to a stable text snapshot (use
+  rspec's `match` against a checked-in fixture string).
+- ANSI color is suppressed when `ENV["NO_COLOR"]` is set.
+- Long lists (e.g. 4,298 missing CJK codepoints) are truncated with
+  a `… (showing first 50; see blocks/<NAME>.json for full list)` footer.
+- No `double()` in specs.
+- Rubocop clean.
+
+## References
+
+- Models: `TODO.new/07-audit-models-port.md`
+- Source: `fontisan/lib/fontisan/formatters/`
+- CLI wiring: `TODO.new/16-cli-audit-subcommands.md`

data/TODO.new/13-directory-emitter.md

@@ -0,0 +1,147 @@
+# 13 — Directory emitter
+
+## Goal
+
+Walk an in-memory `AuditReport` (built by TODOs 06-12) and write it
+to the directory tree specified in `03-directory-output-spec.md`.
+Pure I/O — no audit logic, no font parsing. Idempotent via
+content-hash comparison.
+
+This is the Mode 2 output writer; equivalent in role to
+`Ucode::Repo::CodepointWriter` for Mode 1.
+
+## Files to create
+
+```
+lib/ucode/audit/emitter.rb                 # namespace hub
+lib/ucode/audit/emitter/face_directory.rb  # top-level orchestrator
+lib/ucode/audit/emitter/index_emitter.rb   # writes index.json
+lib/ucode/audit/emitter/block_emitter.rb   # writes blocks/<NAME>.json
+lib/ucode/audit/emitter/plane_emitter.rb   # writes planes/<N>.json
+lib/ucode/audit/emitter/script_emitter.rb  # writes scripts/<CODE>.json
+lib/ucode/audit/emitter/codepoint_emitter.rb # writes codepoints/<NAME>.json (verbose)
+lib/ucode/audit/emitter/glyph_emitter.rb   # writes glyphs/U+XXXX.svg (opt-in)
+lib/ucode/audit/emitter/collection_emitter.rb # writes <source>/00-<face>/ layout for TTC
+lib/ucode/audit/emitter/library_emitter.rb # writes library-level index for directory mode
+```
+
+Specs under `spec/ucode/audit/emitter/`.
+
+## Public API
+
+```ruby
+emitter = Ucode::Audit::Emitter::FaceDirectory.new(
+  output_root: Pathname.new("output/font_audit"),
+  verbose: false,
+  with_glyphs: false,
+)
+emitter.emit_face(label: "Inter-Regular", report: report)
+# → writes output/font_audit/Inter-Regular/index.json + blocks/ + ...
+
+emitter.emit_collection(label: "Inter", reports: array_of_reports)
+# → writes output/font_audit/Inter/00-<face>/ + 01-<face>/ + ...
+
+emitter.emit_library(reports_by_label:)
+# → writes output/font_audit/<label>/... per font + library index
+```
+
+## Idempotency rules
+
+Per `03-directory-output-spec.md`:
+
+- Each output file is content-hash compared against the existing file
+  (if any). Same content → no write. Different content → atomic write
+  (write to `.tmp`, rename).
+- Skip-newer check: if the source font's mtime is older than the
+  output chunk's mtime AND the baseline UCD's mtime is older too,
+  skip the chunk entirely. Saves work on no-op re-runs.
+- Reuse `Ucode::Repo::AtomicWrites` (existing module) for the write
+  primitive. Do not reimplement.
+
+## Emitter responsibilities
+
+### IndexEmitter
+
+Writes `index.json`. Serializes the `AuditReport` via lutaml-model's
+`to_hash`, then:
+
+- Drop `codepoint_details` (always — only emitted by CodepointEmitter).
+- Drop `covered_codepoints` from each `block_summaries` entry (always
+  — IndexEmitter is for the compact form).
+- Embed `missing_codepoints` per block (per decision in `00-README.md`).
+- Add the `totals` summary computed from `block_summaries`.
+
+### BlockEmitter
+
+Writes one file per `BlockSummary` under `blocks/<NAME>.json`. The
+filename uses the block name verbatim (filesystem-safe per
+`03-directory-output-spec.md` §"Block filename encoding"). Each file
+contains the single `BlockSummary` serialized.
+
+### PlaneEmitter / ScriptEmitter
+
+Roll-up views. Same shape as `block_summaries` entries but aggregated.
+
+### CodepointEmitter (verbose only)
+
+For each touched block, walk all codepoints in the font's cmap that
+belong to that block and produce a `CodepointDetail` per codepoint.
+The detail is enriched with ucode baseline data (name, gc, script,
+age) via `Ucode::Database#lookup`.
+
+Per-block chunking keeps each file under ~1MB even for CJK Extension J
+(4,298 codepoints × ~200 bytes/detail ≈ 850KB).
+
+### GlyphEmitter (opt-in)
+
+For each covered codepoint:
+
+1. Look up GID in the audited font's cmap.
+2. Read outline via fontisan (glyf for TrueType, CharStrings for CFF).
+3. Convert to SVG, normalize viewBox.
+4. Write to `glyphs/U+XXXX.svg`.
+
+Filename pattern: `U+%04X.svg` for BMP, `U+%05X.svg` for SMP, etc.
+— same convention as Mode 1's glyph output.
+
+This is the only emitter that calls fontisan's outline reading. Lazy:
+construct the font handle once per face and reuse across codepoints.
+
+### CollectionEmitter
+
+For a TTC/OTC input, emit one `<source>/00-<face>/` directory per
+face, plus a collection-level `index.json` with face metadata
+(`num_fonts_in_source`, face labels, summary rollup).
+
+### LibraryEmitter
+
+For directory-mode input, emit one `<label>/` per font (already
+produced by FaceDirectory), plus a library-level `index.json` and
+`index.html` (the latter via TODO 15).
+
+## Acceptance
+
+- A non-verbose audit produces `index.json`, `planes/`, `blocks/`,
+  `scripts/`. No `codepoints/`. No `glyphs/`.
+- A `--verbose` audit additionally produces `codepoints/<NAME>.json`
+  per touched block.
+- A `--with-glyphs` audit additionally produces `glyphs/U+XXXX.svg`
+  per covered codepoint.
+- `index.json` size is under 200KB for a 50k-codepoint CJK font (no
+  per-codepoint detail inlined).
+- Each `codepoints/<NAME>.json` chunk is under 1MB.
+- Re-running the same audit twice produces zero file writes on the
+  second run.
+- Re-running after touching the source font rewrites the affected
+  chunks only.
+- Block filenames preserve original names verbatim (no slugifying).
+- No `double()` in specs.
+- Rubocop clean.
+
+## References
+
+- Spec: `TODO.new/03-directory-output-spec.md`
+- Models: `TODO.new/07-audit-models-port.md`
+- Atomic writes: `lib/ucode/repo/atomic_writes.rb` (existing)
+- Mode 1 equivalent: `lib/ucode/repo/codepoint_writer.rb`
+- Browser consumer: `TODO.new/14-html-face-browser.md`

data/TODO.new/14-html-face-browser.md

@@ -0,0 +1,144 @@
+# 14 — HTML face browser
+
+## Goal
+
+Generate a standalone `index.html` per audited face. The browser opens
+one file, sees the overview, and fetches JSON chunks lazily as the
+user expands blocks or drills into per-codepoint detail.
+
+This is what makes the audit locally browsable without a server. No
+build step, no JS toolchain — plain HTML + vanilla JS + inlined CSS.
+
+## Files to create
+
+- `lib/ucode/audit/browser.rb` — namespace hub.
+- `lib/ucode/audit/browser/face_page.rb` — renders one face's
+  `index.html`.
+- `lib/ucode/audit/browser/templates/face.html.erb` — the page template.
+- `lib/ucode/audit/browser/templates/face.css` — inlined into the page.
+- `lib/ucode/audit/browser/templates/face.js` — inlined into the page;
+  vanilla JS, no dependencies, uses `fetch()` for chunks.
+- `spec/ucode/audit/browser/face_page_spec.rb`.
+
+## Template structure
+
+The `face.html.erb` template emits a single HTML document with three
+sections:
+
+### Header
+
+- Font identity (family, subfamily, version, foundry, license).
+- Source provenance (file, sha256, format).
+- Baseline (Unicode version, ucode version, generated_at).
+- Summary stats (X codepoints covered across Y blocks; Z% of baseline).
+
+### Plane overview
+
+17-row visual band (one row per plane). Each plane is a thin horizontal
+strip subdivided into block rectangles, colored by coverage:
+
+- Dark green: COMPLETE
+- Light green: PARTIAL >50%
+- Yellow: PARTIAL ≤50%
+- Red: UNCOVERED_ASSIGNED
+- Gray: not touched / NO_ASSIGNED
+
+Click a plane → scrolls to that plane's block list.
+
+### Block drilldown
+
+Sortable table of all touched blocks:
+
+| Block | Range | Covered | Total | % | Status |
+|---|---|---:|---:|---:|---|
+| Basic Latin | U+0000–U+007F | 128 | 128 | 100% | COMPLETE |
+| Greek and Coptic | U+0370–U+03FF | 80 | 135 | 59% | PARTIAL |
+
+Click a row → fetches `blocks/<NAME>.json` (if not already loaded) and
+expands to show the missing-codepoint list as a grid of small
+codepoint chips (`U+037D U+0387 U+...`).
+
+Click a codepoint chip → if verbose mode produced
+`codepoints/<NAME>.json`, fetch and show name/gc/script/age detail. If
+`--with-glyphs` was on, additionally fetch `glyphs/U+XXXX.svg` and
+inline-render the outline.
+
+### Discrepancies panel
+
+If `discrepancies` is non-empty, show as a bulleted list at the bottom.
+Otherwise hide.
+
+## JS behavior
+
+Vanilla JS, ~200 lines. No framework. Behavior:
+
+- On load: fetch `index.json`, render header + plane overview + block
+  table.
+- Block row click: lazy-fetch `blocks/<NAME>.json`, expand row.
+- Codepoint chip click: lazy-fetch `codepoints/<NAME>.json` (if not
+  already fetched for this block), find detail, render.
+- Glyph thumbnail click: lazy-fetch `glyphs/U+XXXX.svg`, inline into
+  detail panel.
+- All fetches cached in a `Map` after first load — no duplicate
+  fetches.
+- Errors (404 for missing chunk) show a friendly inline message, not
+  a broken page.
+
+The JS resolves chunk paths relative to the page's own location, so
+the entire `<label>/` directory is portable (can be opened via
+`file://` or served by any static host).
+
+## CSS
+
+~150 lines. Plain CSS, no preprocessor. Honor `prefers-color-scheme`
+for light/dark. Coverage colors must be readable in both.
+
+## Standalone-ness
+
+The generated `index.html` must work via `file://` with no server. All
+JS and CSS inlined. Chunk fetches use relative URLs so they work
+regardless of where the directory is mounted.
+
+For `file://` URLs, some browsers block `fetch()` of local files. The
+browser should detect this and show a one-line hint: "Open via a local
+server (e.g. `python3 -m http.server` in this directory) for full
+functionality." Initial overview (from inlined `index.json` data, see
+below) still renders.
+
+### Inline the overview data
+
+To make the initial overview render without any fetch, the template
+inlines the `index.json` contents into a `<script type="application/json"
+id="audit-overview">...</script>` block. The JS reads from this on
+load. Subsequent chunk fetches still go to the JSON files (so the
+overview data isn't duplicated in chunks).
+
+This is a deliberate tradeoff: the HTML file is larger (~200KB for a
+typical font) but the initial render is instant and works via
+`file://`.
+
+## Acceptance
+
+- `Ucode::Audit::Browser::FacePage.new(report:, output_dir:).write`
+  produces `<output_dir>/index.html` plus reuses the JSON chunks from
+  TODO 13 (does NOT duplicate them).
+- Opening `index.html` in a browser via `file://` shows the overview
+  immediately. Plane band + block table + header all render.
+- Clicking a block row fetches the per-block JSON (when served) and
+  expands.
+- The page is fully self-contained: no external CSS, no external JS,
+  no CDN dependencies.
+- HTML validates (no missing close tags, etc.).
+- Spec asserts the generated HTML contains expected anchor strings
+  (font family name, baseline unicode version) and that the inlined
+  JSON matches the report.
+- Rubocop clean (the Ruby side; the JS isn't rubocop's concern).
+
+## References
+
+- Output spec: `TODO.new/03-directory-output-spec.md`
+- Emitter: `TODO.new/13-directory-emitter.md` (FacePage is invoked
+  after FaceDirectory to add the HTML)
+- Library browser: `TODO.new/15-html-library-browser.md`
+- CLI flag: `TODO.new/16-cli-audit-subcommands.md` (`--browse` auto-
+  generates HTML alongside JSON)