# epiphany-glyphs — decisions

Editor T4-pre W2 (`spec/CONTRACT_EDITOR_T4PRE_W2_GLYPHS.md`): the shared
typed glyph-asset seam a canvas tessellator needs, populated on top of the
already-designed `layout-ir` interface (`PathCommand`, `GlyphRenderData`,
`GlyphCatalog::render_data`) rather than designing a new one.

## Scope and status

New crate. Owns the bundled Bravura outline data (`src/outlines_generated.rs`,
moved from `epiphany-render-svg`, which held it `pub(crate)` and private to
itself), the extractor tool and its OFL license (`tools/`), an in-crate
grammar-specific parser from the bundled SVG path `d` strings into
`epiphany_layout_ir::PathCommand` (`src/path.rs`, private — reachable only
through the catalog), and `BravuraGlyphCatalog` (`src/catalog.rs`): a real
`GlyphCatalog` whose `render_data` returns genuine outlines, unlike
`epiphany_layout_ir::BravuraCatalog`, which is metrics-only and honestly
returns `None`.

`BRAVURA_METRICS` does not move here and is not edited (contract pin 3): it
stays in `epiphany-layout-ir`, and this crate depends on it read-only. No
cycle: `epiphany-glyphs` → `epiphany-layout-ir`, never the reverse.

## The grammar the contract described vs. the grammar the generator emits

The contract's "verified starting point" states the bundled `d` strings use
"absolute `M`/`L`/`C`/`Z`, decimal coordinates, 4 decimal places". Verified
against all 37 bundled glyphs before writing the parser (not assumed), the
real grammar is wider on both counts, traced to
`tools/extract_bravura_outlines.py`'s use of
`fontTools.pens.svgPathPen.SVGPathPen`, whose default `optimizeCommands`
behavior the extractor never disables:

* **`V` (vertical-only) and `H` (horizontal-only) lineto shorthand** are also
  emitted, absolute, whenever a lineto's target shares an axis with the
  current point — 23 of the 37 bundled glyphs use at least one. `PathCommand`
  (the already-designed shared type) has no shorthand variant, so `parse_d`
  lowers `V`/`H` to `PathCommand::LineTo`; `emit_d` reconstructs the
  shorthand byte-for-byte purely from geometry — comparing the lineto's
  target to the current point (`V` when only *x* is unchanged, `H` when only
  *y* is, `L` otherwise) — which is exactly what the round-trip test proves
  for every bundled glyph. No information is lost: the typed form and the
  stored string are geometrically and (after this reconstruction)
  byte-for-byte equivalent.
* **Coordinates are rounded to *at most* 4 decimals**, with trailing zeros
  and a bare `-0` stripped by the generator's own `round_d`
  (`tools/extract_bravura_outlines.py:180-185`: `f"{v:.4f}".rstrip('0').rstrip('.')`,
  normalising `""`/`"-0"` to `"0"`). Printed precision therefore varies per
  number (0-3 fractional digits observed in the bundled data; 4 is the
  ceiling, not the width). `emit_d`'s number formatter reproduces this exact
  rule.
* Every command in the observed grammar carries exactly one point/coordinate
  group (`M`, `L`, `V`, `H` one; `C` three points; `Z` none) — the generator
  never merges consecutive same-type commands into a multi-coordinate group
  (SVG allows this generally; the fontTools pen never emits it), so the
  parser does not implement that generality either.

This is a correction to the contract's stated facts, not a deviation from its
design pins: pin 4 ("an in-crate parser … covers exactly the grammar the
generator emits") is satisfied by parsing the *real* grammar, which is what
"exactly the grammar the generator emits" requires once the grammar is
actually read from the data rather than assumed from the contract's summary.

## Round-trip proof, not the sanctioned fallback (pin 5)

Pin 5 sanctions a weaker fallback — comparing parsed coordinate sequences as
exact `f32` — if the generator's number formatting cannot be reproduced
exactly. It can: `emit_d`'s formatter is a direct transcription of
`round_d`'s Python (round to 4, strip trailing zeros/dot, normalise `-0`),
verified by an actual byte-for-byte `assert_eq!` against every bundled
glyph's stored `d` string (`path.rs`'s
`every_bundled_glyph_round_trips_byte_for_byte`, the load-bearing test). The
fallback was not needed and was not taken.

## `render_data` caching (pin 6)

`BravuraGlyphCatalog::render_data` looks up a `std::sync::OnceLock`-cached
`BTreeMap<&'static str, Vec<PathCommand>>`, built once by parsing every
bundled outline's `d` string on first use. `parse_d` is pure, so the cached
value a lookup clones is exactly what a fresh parse of the same bundled
string would produce on every call — caching changes only *when* the parse
work happens, never *what* it returns. No interior mutability leaks into the
result; two calls for the same name compare equal (`GlyphRenderData:
PartialEq`), asserted directly.

## `epiphany-render-svg`'s byte-neutrality (pin 2, pin 5)

`render-svg`'s `outline()`/`bundled_glyph_count()`/`smufl_codepoint()` now
delegate to this crate (`src/outline.rs` in each crate — `render-svg`'s copy
is a thin re-export/delegation, this crate's is the real lookup). Critically,
`render-svg`'s SVG emission (`svg.rs`'s `GlyphMode::PathOutline` arm) still
reads `outline(name).path` — the *stored* string — directly into the `<path
d="…">` attribute. It never routes through `parse_d`/`emit_d`; those exist
only for the round-trip proof and are not reachable from `render-svg` at all
(`path` is a private module here, and its functions are `pub(crate)`, not
exported). This is why the byte-neutrality probe (every SVG golden, every
`ResolvedLayoutIR::canonical_bytes()` reference-suite fixture) is unaffected
by this packet's existence — verified before and after against the base
commit, `diff -r` empty.

## Why a new crate and not a `layout-ir` module

The contract left this open (§CONTRACT_EDITOR_T4PRE_IR.md W2 framing: "the
open decision W2's contract resolves is the home … judged on dependency
weight and the MSRV/CI job structure"), and `CONTRACT_EDITOR_T4PRE_W2_GLYPHS.md`
pin 1 settles it: a new crate. Reasons that held once the data was in hand:

* `layout-ir` is deliberately data-light — it defines the `GlyphCatalog`
  *interface* and a small in-tree metrics slice, not asset payloads; the
  bundled outline table is ~37 KB of generated Rust literal that has nothing
  to do with the constraint-solver interface `layout-ir` exists to define.
* A separate crate keeps the "moved verbatim, byte-for-byte identical output"
  claim easy to audit: the outline table's home changed, its content and the
  bytes it produces did not.
* It matches the existing pattern (`epiphany-render-svg` already held this
  exact data privately) — moving it sideways into a shared crate is a
  smaller, more reviewable diff than folding it into `layout-ir` and then
  re-exporting it back out for `render-svg`'s and a future canvas renderer's
  use.