fontisan 0.4.24 → 0.4.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 556befd056a62c96c03bfaab023a7027b098df4145148415f4735db53da719ee
-  data.tar.gz: 41ddfe5df546ee2b1855644d0eddb1caed472f61e88030ad653038e536393ee6
+  metadata.gz: 4f8c0752461168f5fa647b8a581455a1daa4ed17f7649b1b28cf3850b1453748
+  data.tar.gz: 99e14f77bfdb9cf1303b51d9f236a82c2cfbf284885d56fbe79be56fb338a237
 SHA512:
-  metadata.gz: 057fc2598f2ad7a02b1847d502f6c0363f6f23382806de361a5dd87bb2b4c99d00993f2e272ab3f2c35697dc0b8843235df05301047b1c3cdbf0e0147498282d
-  data.tar.gz: 1669c95792cc2a7731f4495e2d91e2e89b545412e213f8aff78e0dfc625a60c9f9403dc9960e4e487da1563e794fb2d3a6d5126f4ab6ef35e6ebe42e9950fd5d
+  metadata.gz: 15960f305c5c9f6cfef40e55adf0b5eb95a54f51aa902dae77d2db6c7735b821d7b3bb320582eebed3141a3a5d72cf396e51a3a7845a9222f283c6ca4e9a0e90
+  data.tar.gz: 70d21559793f7c48965c8bf2601788dccf6f63c7c66db70cd49a3822b280664d30a333db717b61ad7348fbb831a31ab158ef22dc117f8e683321da131b52dad5

data/TODO.improvements/01-cbdt-cblc-gid-stable-propagation.md

@@ -0,0 +1,73 @@
+# 01 — CBDT/CBLC GID-stable propagation
+
+## Priority
+P0
+
+## Problem
+
+`Stitcher::CbdtPropagator#propagate_tables_into` (`lib/fontisan/stitcher/cbdt_propagator.rb:147`) copies CBDT/CBLC bytes raw from the CBDT source into the compiled font. CBLC indexes glyphs by **source GID**. But the Stitcher's compile order is:
+
+1. `inject_notdef`      → compiled GID 0
+2. `copy_outlines`      → compiled GIDs 1..N (outline donor glyphs)
+3. `add_placeholder_glyphs` → compiled GIDs N+1..M (CBDT placeholders, often renamed to `"gid{N}.1"` to avoid name collisions per PR #108)
+
+So the CBDT source's GID 110 may end up at compiled GID 4027+ — but the raw-bytes CBLC still says "GID 110 → bitmap for source GID 110". The bitmap data dangles, pointing at whatever outline glyph happens to be at compiled GID 110.
+
+This is masked in the cited Essenfont use case because FSung-3 (Ext G outlines) and NotoColorEmoji (emoji bitmaps) cover disjoint codepoint ranges. But for any stitch where CBDT and outline donors cover overlapping codepoint ranges (e.g. assembling a combined Latin+emoji font from a single source that has both glyf and CBDT), the bitmap-to-glyph mapping is wrong.
+
+Documented as a known limitation in `docs/STITCHER_GUIDE.adoc` (added in PR #110).
+
+## Goal
+
+After compile, `propagate_tables_into` rebuilds the CBLC by:
+1. Walking the compiled font's cmap to find each compiled GID for every CBDT-covered codepoint.
+2. Mapping source GID → compiled GID via the Stitcher's `GlyphMapping`.
+3. Building a new CBLC whose `BitmapSize.startGlyphIndex`/`endGlyphIndex` and IndexSubTableArray entries reference compiled GIDs.
+4. Building a new CBDT that lays out bitmap blocks in compiled-GID order so each block matches its CBLC offset.
+
+The result: any stitch — overlapping codepoint ranges or not — produces a font where CBLC's GID references line up with the compiled GIDs that actually have the right bitmaps.
+
+## Approach
+
+Reuse the CBDT/CBLC BinData models from PR #106:
+- `Tables::Cblc`, `Tables::CblcBitmapSize`, `Tables::CblcIndexSubTableArrayEntry`, `Tables::CblcIndexSubTable`
+- `Subset::TableStrategy::ColorBitmapSubsetter` and its plan classes — already do the offset-remap math for the subsetter; same algorithm shape, different mapping source
+
+New collaborator: `Stitcher::CbdtReindexer`. Sits between compile and table propagation:
+
+```
+compile TTF
+  ↓
+CbdtReindexer.reindex(source_cblc, source_cbdt, glyph_mapping) → new (CBLC, CBDT) bytes
+  ↓
+FontWriter.write_to_file(tables.merge("CBLC" => new_cblc, "CBDT" => new_cbdt))
+```
+
+The reindexer is stateless given inputs — testable in isolation.
+
+Update `propagate_tables_into` to call the reindexer instead of raw-bytes copy.
+
+Update `docs/STITCHER_GUIDE.adoc` to remove the "known limitation" note.
+
+## Out of scope
+
+- Handling IndexSubTable format 4 (bit-packed offsets) — already unsupported in the subsetter; same gap.
+- Multi-strike CBLC where each strike has a different glyph range — covered (reindexer iterates strikes).
+- Subsetting the source CBDT before stitching — separate concern (the subsetter already does this for `Subset::Builder`).
+
+## Effort
+
+~1 day.
+
+## Dependencies
+
+None. Unblocks TODO 02.
+
+## Acceptance criteria
+
+- New spec `spec/fontisan/stitcher/cbdt_reindexer_spec.rb` covers:
+  - Disjoint-range stitch: CBLC's compiled GID references line up.
+  - Overlapping-range stitch: CBDT placeholder at compiled GID N gets the bitmap originally at source GID M (mapping via GlyphMapping).
+  - Multi-strike CBLC: every strike's bitmap data lands at the right compiled GID.
+- Existing `spec/fontisan/stitcher/outline_priority_spec.rb` collection-mode test (currently skipped) is unblocked and passes.
+- The "GID-stability limitation" section in `docs/STITCHER_GUIDE.adoc` is removed.

data/TODO.improvements/02-collection-outline-priority.md

@@ -0,0 +1,48 @@
+# 02 — Collection-mode outline-priority regression
+
+## Priority
+P0
+
+## Problem
+
+`spec/fontisan/stitcher/outline_priority_spec.rb:160` ("write_collection preserves outline-first cmap priority across faces") was unblocked for single-face mode in PR #108 but the **collection variant** is still skipped:
+
+```ruby
+skip "Stitcher currently raises on a CBDT source without at least one outline codepoint in each face — " \
+     "collection-mode coverage needs CbdtPropagator hardening tracked separately."
+```
+
+When the Stitcher builds a TTC/OTC, each face compiles independently. The CBDT source is global — its placeholders need to land in EVERY face that covers any of its codepoints. The current `CbdtPropagator#add_placeholder_glyphs` raises if a face has no outline glyph from any other donor (the CBDT source alone can't seed a face).
+
+## Goal
+
+The skipped test passes. A CBDT source can be stitched into a collection where some faces cover only CBDT codepoints (no outline donor coverage). Each face gets the CBDT/CBLC tables propagated.
+
+## Approach
+
+Two pieces:
+
+1. **`CbdtPropagator#add_placeholder_glyphs`** — relax the "must have an outline codepoint" precondition. Allow a face to be seeded with just CBDT placeholders (plus the `.notdef` that's always required).
+
+2. **`CbdtPropagator#propagate_tables_into`** — for collections, run per-face rather than once. The collection writer already iterates faces; this is a matter of plumbing.
+
+This depends on TODO 01 (GID-stable propagation) because the collection case multiplies the GID-mapping complexity — each face has its own compiled GID space.
+
+## Out of scope
+
+- Multi-CBDT-source support (the `MultipleCbdtSourcesError` guard remains).
+- Cross-face glyph deduplication (already handled by the existing dedup pass).
+
+## Effort
+
+~2 hours once TODO 01 lands.
+
+## Dependencies
+
+- TODO 01 (CBDT/CBLC GID-stable propagation).
+
+## Acceptance criteria
+
+- The skipped test at `outline_priority_spec.rb:160` is unskipped and passes.
+- A new test covers the "CBDT-only face" case (a face with no outline donor coverage, only CBDT placeholders).
+- `MultipleCbdtSourcesError` is still raised when two CBDT sources are declared.

data/TODO.improvements/03-fontisan-audit-command.md

@@ -0,0 +1,189 @@
+# 03 — `fontisan audit` command (identity+style+features lens)
+
+## Priority
+P1
+
+## Problem
+
+The `fontist-archive-private` pipeline currently reaches into Fontisan internals to extract font identity + metadata:
+
+```ruby
+# Current (wrong) approach — manual cmap + table poking
+font = Fontisan::FontLoader.load(font_path)
+cmap = font.table("cmap")
+codepoints = cmap ? cmap.unicode_mappings.keys : []
+# ...plus ad-hoc reads of name, OS/2, head, fvar, GSUB, GPOS
+```
+
+Fragile and bypasses Fontisan's API. Fontisan has `InfoCommand` (font metadata) and `UnicodeCommand` (codepoint/glyph mappings), but neither produces a complete, self-describing audit record suitable for archival use.
+
+## Goal
+
+A `fontisan audit` command that produces a structured **font audit report** (YAML or JSON) covering what ucode's audit does NOT:
+
+- **Identity** — name-table strings (family, full, PostScript, version)
+- **Style** — OS/2 weight/width classes, head macStyle, fsSelection italic/bold, panose, fvar axes
+- **Coverage facts** — total codepoints, total glyphs, cmap subtable provenance, optional codepoint list
+- **OpenType layout** — GSUB/GPOS scripts (distinct from Unicode scripts), features list
+- **Provenance** — `generated_at`, `fontisan_version`, `source_sha256`
+
+## MECE split with ucode
+
+ucode owns the Unicode-coverage axis (UCD parsing, block/script aggregation, per-codepoint glyph extraction). fontisan owns the font-identity axis.
+
+| Concern | Owner |
+|---------|-------|
+| UCD fetching + parsing | ucode |
+| Block/script aggregation from codepoints | ucode |
+| Per-codepoint SVG extraction | ucode |
+| HTML browsers | ucode |
+| Font identity (name table) | **fontisan audit** |
+| Style metadata (OS/2, head, fvar) | **fontisan audit** |
+| OpenType scripts + features | **fontisan audit** |
+| Source provenance (sha256, fontisan_version) | **fontisan audit** |
+| cmap subtable provenance | **fontisan audit** |
+
+**The fontisan audit does NOT bundle UCDXML parsing.** Block aggregation is delegated: fontisan audit accepts an optional pre-built ucode index path, OR emits the codepoint list and lets the consumer (fontist-archive) run ucode separately.
+
+## Beyond ucode: revised priority after self-debate
+
+A critical self-debate (see commit history) culled several "diagnostic" features that overlap with existing tools. The surviving axes:
+
+### Keep — high value, fontisan-unique
+- **Identity + Style + Features** — justified for archival format (one YAML per face, with provenance). NOT a general font inspector.
+- **Subset report** — when fontisan subsets, emit a structured report (glyph/codepoint/table breakdown). Web font engineers hit this daily; pyftsubset emits minimal output. fontisan has the subset infrastructure.
+- **Cross-format equivalence** — `fontisan equivalent font.ttf font.woff2` → true/false + diff. Catches CDN regeneration bugs from stale masters. fontTools diffs are too noisy.
+- **License/rights extraction** — OS/2 fsType embedding bits, name ID 13 license, head macStyle commercial-use hints. Compliance teams need this before redistribution. Currently buried.
+- **Collection integrity** — narrow (CJK foundries, Apple system fonts) but real for that audience. Cheap to add once identity extraction exists.
+
+### Drop — overlap with established tools
+- ~~**OTS-rejection predictor**~~ — Chromium ships `ots-sanitize`, the actual tool Chrome uses. Reimplementing in Ruby means we're always behind Chrome's evolving rule set. Better: wrap ots-sanitize as subprocess.
+- ~~**Format-round-trip report**~~ — WOFF2 is lossless by design; report would say "nothing changed" 99% of the time. TTF↔OTF outline-fidelity is a real check but it's one function, not an audit axis.
+- ~~**Variable-font readiness**~~ — **fontbakery** owns this space. Hundreds of mature checks, Google Fonts uses it for every submission. Don't compete; wrap if needed.
+- ~~**Hinting audit**~~ — audience is ~50 people worldwide. Modern web fonts ship largely unhinted. VF fonts don't use TT hints. Specialized tools (FontLab, ttfautohint) serve this niche better.
+
+### Maybe later — niche but real
+- **Performance profile** — glyph count, table-level bytes, predicted parse time. Mobile/embedded niche. Apple has internal tools; nothing public.
+- **Identity hash** — canonical hash of (name + post + head + OS/2 identity) surviving lossless conversion. CDN/asset-pipeline use case.
+
+The headline correction: the original proposal positioned fontisan audit as a "font inspector" competing with commodity tools. The actually-valuable features are **workflow-specific reports** (subset, conversion equivalence, license) that leverage fontisan's unique subsetting + conversion infrastructure. ucode can't do any of these.
+
+## Approach
+
+### Models (`lib/fontisan/models/audit/`)
+
+Use `lutaml-model` like all other fontisan models:
+
+- `AuditReport` — top-level report, attributes per the schema below
+- `AuditAxis` — variable-font axis descriptor
+- `AuditFeature` — feature tag + scripts list
+
+### Command (`lib/fontisan/commands/audit_command.rb`)
+
+`Commands::AuditCommand` orchestrates — does NOT re-parse tables. Delegates to existing commands:
+
+- `InfoCommand` — identity + name-table strings
+- `UnicodeCommand` — codepoint list + cmap subtable provenance
+- `ScriptsCommand` — `opentype_scripts`
+- `FeaturesCommand` — `features`
+- `FormatDetector` — `source_format`
+
+This makes `AuditCommand` a thin orchestration layer.
+
+### CLI (`lib/fontisan/cli.rb`)
+
+```bash
+# Standalone
+fontisan audit Inter-Regular.ttf                    # → stdout (YAML)
+fontisan audit Inter-Regular.ttf -o report.yaml     # → file
+fontisan audit Inter-Regular.ttf --format json      # → stdout (JSON)
+
+# Collection
+fontisan audit Inter.ttc -o reports/                # → reports/Inter.ttc/{00..08}-*.yaml
+
+# Single face from collection
+fontisan audit Inter.ttc --font-index 6 -o Inter-Bold.yaml
+```
+
+### Output schema (one face per file)
+
+```yaml
+generated_at: 2026-07-10T12:30:00Z
+fontisan_version: 0.4.24
+source_file: Inter-Regular.ttf
+source_sha256: 3b1a...
+source_format: ttf
+
+font_index: null
+num_fonts_in_source: 1
+
+# Identity
+family_name: Inter
+subfamily_name: Regular
+full_name: Inter Regular
+postscript_name: Inter-Regular
+version: Version 4.000;git-a52131595
+font_revision: 4.0
+
+# Style
+weight_class: 400
+width_class: 5
+italic: false
+bold: false
+panose: "2 0 5 3 0 0 0 0 0 0"
+is_variable: false
+axes: []
+
+# Coverage
+total_codepoints: 2857
+total_glyphs: 1486
+cmap_subtables: [4, 12, 14]
+codepoints: [U+0000, U+0020, ...]   # omitted with --no-codepoints
+
+# OpenType layout
+opentype_scripts: [latn, cyrl]
+features: [kern, liga, calt]
+```
+
+### Collection layout
+
+```
+reports/
+  Inter.ttc/
+    00-Inter-Regular.yaml
+    01-Inter-Italic.yaml
+    ...
+    08-Inter-Black.yaml
+```
+
+Filename pattern: `{font_index:02d}-{postscript_name}.yaml`. Index prefix guarantees face-order sort and disambiguates broken fonts where two faces share a PostScript name.
+
+## Out of scope
+
+- UCDXML parsing (ucode's domain)
+- Block/script aggregation (consumer runs ucode separately, OR a future `--with-ucode` flag calls ucode as a subprocess)
+- HTML browsers (ucode's domain)
+- Per-codepoint glyph extraction (ucode's 4-tier resolver)
+- Reading formula YAML — this command reports what the FONT FILE declares
+- Generating WOFF specimens (ConvertCommand's domain)
+
+## Effort
+
+~1-2 days.
+
+## Dependencies
+
+None directly. Existing commands (`InfoCommand`, `UnicodeCommand`, `ScriptsCommand`, `FeaturesCommand`) provide the data; `AuditCommand` just orchestrates.
+
+## Acceptance criteria
+
+- New spec `spec/fontisan/commands/audit_command_spec.rb` covers:
+  - Standalone TTF → YAML + JSON output
+  - Collection TTC → directory of N face reports
+  - `--font-index N` → single-face report
+  - `--no-codepoints` omits the codepoint list
+  - Source sha256 matches `Digest::SHA256.file(path)`
+  - Variable font with fvar → axes array populated
+- New spec `spec/fontisan/models/audit_report_spec.rb` covers the model's serialization.
+- CLI smoke test verifies `fontisan audit path/to/font.ttf` produces valid YAML on stdout.
+- README/docs updated.

data/TODO.improvements/04-ufo-composite-glyph-encoding.md

@@ -0,0 +1,46 @@
+# 04 — UFO composite glyph encoding
+
+## Priority
+P1
+
+## Problem
+
+`Ufo::Compile::GlyfLoca` (`lib/fontisan/ufo/compile/glyf_loca.rb:137`) emits simple glyphs only. UFO sources with composite glyphs (e.g., é defined as a component reference to e + acute) lose their component structure on compile — the compiled glyf either drops them or depends on `flatten_components` filter pre-processing.
+
+## Goal
+
+`GlyfLoca` encodes composite glyphs natively per OpenType spec section 5.6. A UFO `<component>` element maps to a glyf component record referencing the target glyph by index, preserving the original transform.
+
+## Approach
+
+Add a `CompositeEncoder` collaborator in `lib/fontisan/ufo/compile/glyf_loca/composite_encoder.rb` that takes a UFO `<component>` plus a GID-resolver (component name → compiled GID) and emits the binary component record per OT spec:
+
+```
+uint16 flags
+uint16 glyphIndex
+(uint8|uint8|uint8|uint8 | int8|int8|int8|int8 | uint8) args  # depends on flags bits 0/1
+(F2Dot14 × 4 | F2Dot14 × 2 | F2Dot14) transformation  # depends on flags bits 7/6/3
+```
+
+`GlyfLoca` invokes the encoder when a UFO glyph has components (no contours, OR contours + components — latter is rare but spec-legal).
+
+The existing `flatten_components` filter remains for callers who want pre-flattening (e.g., for fonts that target renderers without component support).
+
+## Out of scope
+
+- Variable-font composite variation deltas (`gvar`) — separate concern, TODO 06's blast radius.
+- Cycling component references (A → B → A) — these need pre-validation, tracked separately.
+
+## Effort
+
+~1 day.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- New spec covers encoding of all 8 component arg/transform combinations (flags bit patterns).
+- Round-trip spec: UFO with composite → compile → re-read via `FontLoader` → components match original.
+- The `flatten_components` filter still works as a pre-pass for callers that want flattened output.

data/TODO.improvements/05-otf-compiler-real-cff.md

@@ -0,0 +1,63 @@
+# 05 — OTF compiler real CFF charstrings
+
+## Priority
+P1
+
+## Problem
+
+`Ufo::Compile::OtfCompiler` (`lib/fontisan/ufo/compile/otf_compiler.rb:9`) currently emits a placeholder CFF table — no real charstrings. Any OTF output is incomplete:
+
+```
+# TODO.full/10: this currently emits a placeholder CFF table
+# real charstrings. Full CFF construction lands when TODO 10
+```
+
+The font loads but renders nothing useful. Production OTF output is blocked.
+
+## Goal
+
+`OtfCompiler` emits a complete CFF table with:
+- Real Type 2 charstrings for every glyph (converted from UFO contours)
+- Valid Top DICT (font matrix, charset, encoding, CharStrings INDEX offset)
+- Valid Private DICT (default width, nominal width, SubrZERO subroutines if any)
+- Correct name INDEX, charset, FDSelect/FDArray (for CID-keyed fonts)
+
+Round-trip: UFO → compile → re-read via `FontLoader` → contours match.
+
+## Approach
+
+Reuse the Type 2 charstring conversion logic from `lib/fontisan/type1/charstring_converter.rb` — UFO contours → moveto/lineto/curveto closepath is structurally identical to Type 1 → Type 2 charstring conversion.
+
+Add a new `CffBuilder` collaborator under `lib/fontisan/ufo/compile/otf_compiler/cff_builder.rb` that owns:
+
+1. **Top DICT construction** — font matrix, ROS (if CID), charstrings offset.
+2. **CharString INDEX** — per-glyph Type 2 charstring bytes.
+3. **Charset** — glyph name → GID map (uses post.names if available; else `gid{N}`).
+4. **Private DICT** — default width, nominal width, hint-mask operators (no-op when source has no hints).
+5. **Global / local subroutines** — empty INDEXs initially; TODO 06 wires hint subroutines.
+
+The existing `Tables::Cff` BinData record already declares the on-disk structure; the builder produces the values to populate it.
+
+## Out of scope
+
+- CFF2 (variable fonts) — TODO 06.
+- Subroutine packing / optimization — `Optimizers::SubroutineOptimizer` already exists for Type 1; CFF equivalent is a separate task.
+- CID-keyed fonts with multi-FD — single FD only initially.
+
+## Effort
+
+~2-3 days.
+
+## Dependencies
+
+None (the placeholder CFF was the only thing blocking, and we're replacing it).
+
+## Acceptance criteria
+
+- New spec `spec/fontisan/ufo/compile/otf_compiler/cff_builder_spec.rb` covers:
+  - Single-glyph font (`.notdef` + one outline) → valid CFF
+  - Multi-glyph font with quadratic curves → charstrings use rcurveto correctly
+  - Multi-glyph font with TrueType cubic curves → curve conversion to Type 2 cubic
+  - Charset ordering matches maxp.numGlyphs
+- Round-trip: UFO → OTF → re-read → contours match (within Type 2 quantization tolerance)
+- `fontisan convert font.ufo --to otf` produces a font that loads in fontTools and Chrome.

data/TODO.improvements/06-cff2-blend-vsindex-operators.md

@@ -0,0 +1,51 @@
+# 06 — CFF2 blend/vsindex operators
+
+## Priority
+P2
+
+## Problem
+
+`Ufo::Compile::VariableOtf` (`lib/fontisan/ufo/compile/variable_otf.rb:12`) emits static CFF2 only:
+
+```
+- CFF2 outlines (static — blend/vsindex operators are TODO 07/18)
+TODO 07 (blend/vsindex) and TODO 18 (blend integration) to be
+```
+
+Variable CFF2 fonts (e.g., variable OTF output from a UFO with `fvar` + `gvar`-equivalent masters) can't round-trip. The compiled font is static — variation deltas are dropped.
+
+## Goal
+
+`VariableOtf` emits CFF2 with `blend` and `vsindex` operators per CFF2 spec section 3.A.4. A variable UFO source compiles to a variable OTF that renders correctly at any chosen instance along each axis.
+
+## Approach
+
+Two pieces:
+
+1. **CharString encoder** — extend the Type 2 charstring builder (from TODO 05) to emit `blend` after each variation-aware value. The master value is the default; deltas for each region are pushed on the stack then summed via `blend`.
+
+2. **ItemVariationData emission** — translate the UFO master model (`gvar`-equivalent: per-glyph deltas keyed by region) into CFF2's `ItemVariationData` and `ItemVariationStore` structures. Reuse `Ufo::Compile::ItemVariationStore` which already handles this for the variable-TTF path.
+
+3. **Region detection** — pre-pass over `fvar` axes + master locations to compute the set of variation regions. Same algorithm as `Ufo::Compile::Fvar`.
+
+## Out of scope
+
+- HVAR/VVAR/MVAR tables for variable OTF — those are outside CFF2 but already partially supported; track separately if needed.
+- Backwards-compat with non-variable CFF fonts — separate concern.
+- Subroutine packing of variation-aware charstrings — TODO follow-up.
+
+## Effort
+
+~3-5 days. CFF2 charstring semantics are intricate.
+
+## Dependencies
+
+- TODO 05 (OTF compiler real CFF) — must land first; the CFF2 builder extends the CFF builder.
+
+## Acceptance criteria
+
+- New spec covers:
+  - Single-axis variable font → CFF2 with correct `blend` operators + `ItemVariationStore`
+  - Multi-axis variable font → region table correct, no cross-axis contamination
+  - Instance generation via `Variation::InstanceGenerator` produces output identical to direct master compile (within tolerance)
+- Round-trip: UFO with fvar + masters → variable OTF → re-read → `fvar` axes match, instances render correctly.

data/TODO.improvements/07-cpal-v1-header-fields.md

@@ -0,0 +1,71 @@
+# 07 — CPAL v1 header fields
+
+## Priority
+P2
+
+## Problem
+
+`Tables::Cpal` (`lib/fontisan/tables/cpal.rb:106,184`) only parses CPAL v0 fields. CPAL v1 adds:
+
+- `numPaletteEntryLabels` (uint16) — count of palette entry labels
+- `numPaletteLabels` (uint16) — count of palette labels
+- `paletteEntryLabelsOffset` (uint32) — offset to label records
+- `paletteLabelsOffset` (uint32) — offset to label records
+
+These attach human-readable names (via the `name` table) to color palettes and entries. Fonts with CPAL v1 lose this metadata on parse.
+
+## Goal
+
+`Tables::Cpal` parses v1 header fields and exposes:
+
+- `palette_labels` — array of name-record IDs, one per palette
+- `palette_entry_labels` — array of name-record IDs, one per palette entry index
+
+Round-trip preserves the labels.
+
+## Approach
+
+Extend the BinData record in `lib/fontisan/tables/cpal.rb`:
+
+```ruby
+class Cpal < Binary::BaseRecord
+  uint16 :version
+  uint16 :num_palette_entries
+  uint16 :num_palettes
+  uint16 :num_color_records
+  uint32 :color_records_offset
+  array :color_record_indices, type: :uint16, initial_length: :num_palettes
+  # v0 ends here
+
+  # v1 extension — only present when version >= 1
+  choice :v1_fields, onlyif: -> { version >= 1 } do
+    uint16 :num_palette_entry_labels
+    uint16 :num_palette_labels
+    uint32 :palette_entry_labels_offset
+    uint32 :palette_labels_offset
+  end
+end
+```
+
+After BinData parse, lazily walk the label offsets to populate `palette_labels` and `palette_entry_labels` arrays.
+
+For emission: if v1 fields are set, include them; else emit v0.
+
+## Out of scope
+
+- CPAL v2 changes (none — v1 is the latest defined).
+- Building new palettes from scratch — just parse + emit.
+
+## Effort
+
+~4 hours.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- New spec covers parse of a synthetic CPAL v1 table with both label arrays.
+- Round-trip: v1 table → read → `to_binary_s` → identical bytes.
+- v0 tables still parse and emit unchanged.

data/TODO.improvements/08-cff-standard-string-table.md

@@ -0,0 +1,52 @@
+# 08 — CFF standard string table
+
+## Priority
+P2
+
+## Problem
+
+`Tables::Cff` (`lib/fontisan/tables/cff.rb:419`) ships only a partial standard string table (the 391 predefined Type 1 / CFF strings per spec appendix A). Glyph names that should be in the standard set are duplicated in the custom strings index, wasting space and breaking round-trip fidelity with fontTools.
+
+## Goal
+
+Complete the 391-string standard table per CFF spec. `Cff` parses glyph names against the standard table; only non-standard names go in the custom strings index.
+
+## Approach
+
+Replace the partial list with the canonical 391 strings (spec appendix A, also in fontTools' `fontTools.cffLib.strings`).
+
+Add a class method:
+
+```ruby
+class Cff < Binary::BaseRecord
+  STANDARD_STRINGS = [...].freeze  # 391 entries
+
+  def self.standard_string?(name)
+    STANDARD_STRINGS.include?(name)
+  end
+
+  def self.standard_string_index(name)
+    STANDARD_STRINGS.index(name)
+  end
+end
+```
+
+Update the CFF builder (TODO 05's `CffBuilder`) to skip custom-string encoding when a name is standard.
+
+## Out of scope
+
+- CID-keyed fonts (no name strings) — unaffected.
+- Custom charstring-internal names (operator names) — those are operators, not string IDs.
+
+## Effort
+
+~2 hours.
+
+## Dependencies
+
+- TODO 05 (OTF compiler real CFF) benefits; doesn't strictly block.
+
+## Acceptance criteria
+
+- Spec covers: every standard name → correct index, every non-standard name → custom index.
+- Round-trip: CFF with mixed standard/non-standard names → read → emit → identical bytes.

data/TODO.improvements/09-type1-seac-expansion.md

@@ -0,0 +1,57 @@
+# 09 — Type 1 seac expansion
+
+## Priority
+P2
+
+## Problem
+
+`Type1::CharStringConverter` (`lib/fontisan/type1/charstring_converter.rb:161`) and `Type1::TtfToType1Converter` (`lib/fontisan/type1/ttf_to_type1_converter.rb:256`) emit seac operators as-is when converting Type 1 → TrueType. seac (Standard Encoding Accented Character) composites two glyphs into one — e.g., é = e + acute at a fixed offset. Modern renderers deprecated seac; Type 1 → TTF conversion must expand it into actual outlines.
+
+## Goal
+
+`TtfToType1Converter` (and the reverse path) expands seac into merged outlines:
+
+1. Resolve the two referenced glyphs (base + accent) via the source font.
+2. Translate them to the seac offset.
+3. Concatenate their contours into the parent glyph.
+
+## Approach
+
+Add a `SeacExpander` collaborator under `lib/fontisan/type1/seac_expander.rb` that takes:
+
+- A charstring with a seac operator
+- A resolver: glyph_name → charstring (for the base + accent)
+
+Returns a new charstring with the seac replaced by the merged outline operators.
+
+Walk the source's standard-encoding lookup (Adobe Standard Encoding) to map seac's two uint8 operands to glyph names. Decode the operands:
+
+```
+seac: asb base accent
+  asb     — sidebearing (unused in expansion)
+  base    — Adobe Standard Encoding index of the base glyph
+  accent  — Adobe Standard Encoding index of the accent glyph
+```
+
+The expander recursively expands seac in base/accent glyphs (seac can nest).
+
+## Out of scope
+
+- seac in CFF (not Type 1) — CFF deprecated seac entirely; should be a warning, not an expansion.
+- Replacing the deprecated `seac` operator in TTF → Type 1 conversion — seac emission is already removed; we only need to handle source seac on input.
+
+## Effort
+
+~6 hours.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- Spec covers:
+  - Single-level seac (e.g., é) → expanded to merged outline.
+  - Nested seac (e.g., a glyph that references another seac glyph as its base) → fully expanded.
+  - seac referencing a missing glyph → raise `SeacReferenceError` with the missing name.
+- Round-trip: Type 1 with seac → TTF → re-read → outline matches the merged shape.

data/TODO.improvements/10-ufo-image-set-feature-writers.md

@@ -0,0 +1,71 @@
+# 10 — UFO image set + feature writers
+
+## Priority
+P2
+
+## Problem
+
+Two UFO subsystems ship as stubs:
+
+- `Ufo::ImageSet` (`lib/fontisan/ufo/image_set.rb:6`) — placeholder, "real implementation lands with TODO 02 (glyph model + images)"
+- `Ufo::Features` (`lib/fontisan/ufo/features.rb:8`) — placeholder, "TODO 08 (feature writers)"
+
+UFO sources with `features.fea` (OpenType layout compilation from text) or images (UFO 3 image data) lose both on round-trip.
+
+## Goal
+
+### ImageSet
+- `Ufo::ImageSet` parses UFO 3 image data: reads `images/` directory, exposes `images` array of `Ufo::Image` records with filename + sha + PNG bytes.
+- `Ufo::Glyph#image` (already modeled) reads image references; round-trips.
+- Compile: glyphs with image references emit `CBDT`/`CBLC` color-bitmap entries (reusing the BinData models from PR #106).
+
+### Features (feature writers)
+- `Ufo::Features` parses `features.fea` via a new `FeatureCompiler` collaborator.
+- Compiles OpenType layout rules (kern, liga, calt, etc.) into `GSUB`/`GPOS` tables.
+- Output tables are mergeable into the compiled font.
+
+## Approach
+
+### ImageSet
+Reuse existing `Tables::Cbdt`/`Cblc` BinData records. Convert each UFO image to a small-metrics-format PNG block. Build CBLC IndexSubTableArray pointing at each block.
+
+For test fixtures: the existing `CbdtFixture` (PR #107) already builds valid CBDT/CBLC pairs — use as reference for the emission shape.
+
+### Features
+Use a fea-syntax parser. Options:
+- **Inline parser** — non-trivial; ~5 days work, ~500 LOC.
+- **Adapter for `fontTools.feaLib`** — only available with Python; introduces cross-language dep (violates "pure Ruby" rule).
+- **Limited fea subset** — handle only kern/liga (most common); error on unsupported constructs.
+
+Recommendation: **limited fea subset** initially, expanding as real-world fonts demand.
+
+Add `FeatureCompiler` under `lib/fontisan/ufo/compile/feature_compiler.rb`. Parses `features.fea` into a tree, then emits GSUB/GPOS records. Starts with:
+- `feature kern { pair ... } kern;` → GPOS PairPos (format 1)
+- `feature liga { sub ... by ...; } liga;` → GSUB LigatureSubst
+
+## Out of scope
+
+- Adobe FEA parser completeness — full spec is 100+ pages; cover what real fonts use.
+- AFDKO integration — out of scope.
+
+## Effort
+
+- ImageSet: ~1 day (BinData + IO).
+- Features (limited subset): ~3 days (kern + liga paths).
+- Features (full fea): weeks — explicitly out of scope.
+
+## Dependencies
+
+- TODO 05 (OTF compiler real CFF) — image glyphs end up in CBDT, unrelated to CFF. No dep.
+- None blocking.
+
+## Acceptance criteria
+
+### ImageSet
+- Spec covers read of UFO with one image → `glyph.image` populated, `imageset.images.first.bytes` matches PNG bytes.
+- Compile round-trip: UFO with image glyph → TTF → re-read → CBDT/CBLC tables present, bitmap decodable.
+
+### Features
+- Spec covers a UFO with kern feature → GPOS table present with correct PairPos.
+- Spec covers a UFO with liga feature → GSUB table present with correct LigatureSubst.
+- Unsupported fea constructs raise `UnsupportedFeaError` with a clear message.

data/TODO.improvements/11-kern-groups-plist.md

@@ -0,0 +1,49 @@
+# 11 — kern groups.plist support
+
+## Priority
+P2
+
+## Problem
+
+`Ufo::Compile::FeatureWriters::Kern` (`lib/fontisan/ufo/compile/feature_writers/kern.rb:18`) reads kerning pairs from `kerning.plist` but only partially supports `groups.plist`:
+
+```
+# groups.plist data (TODO: groups.plist support is partial).
+```
+
+UFO sources that use class-based kerning (kerning classes defined in `groups.plist` instead of per-glyph) lose the class data. Compiled fonts have incomplete kern tables.
+
+## Goal
+
+`Kern` feature writer reads `groups.plist` class definitions, resolves them in `kerning.plist` lookups, and emits GPOS class-based PairPos records (format 2).
+
+## Approach
+
+Two pieces:
+
+1. **Group resolution** — when `kerning.plist` references a group name (rather than a glyph name), expand to all group members. Track group → glyph-set mapping.
+
+2. **Format-2 emission** — emit PairPos format 2 (class-based) when > N pairs share a class. Threshold: ~5 pairs (configurable). Below threshold, fall back to format 1 (pair-based) for size.
+
+Add a `KerningClassResolver` collaborator under `lib/fontisan/ufo/compile/feature_writers/kern/class_resolver.rb`. Stateless given (kerning.plist, groups.plist); returns a list of resolved pairs (glyph_a, glyph_b, value).
+
+## Out of scope
+
+- Variable-font kerning (HVAR table) — separate concern.
+- Contextual kerning (`kern` feature with context) — separate feature.
+
+## Effort
+
+~4 hours.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- Spec covers:
+  - Class-based kerning (groups.plist with two classes, kerning.plist with one pair between them).
+  - Mixed class + glyph kerning (one glyph + one class).
+  - Threshold: < 5 pairs → format 1; >= 5 pairs → format 2.
+- Round-trip: UFO with class kerning → TTF → re-read → GPOS contains the right PairPos records.

data/TODO.improvements/12-cbdt-fixture-bindata-conversion.md

@@ -0,0 +1,68 @@
+# 12 — `cbdt_fixture.rb` full BinData conversion
+
+## Priority
+P3
+
+## Problem
+
+`spec/support/cbdt_fixture.rb` was partially refactored in PR #107 (CBDT/CBLC use the new BinData models), but the remaining tables still hand-roll binary packing:
+
+- `head_table` — 19-element `[...].pack("NNNNnnNNnnnnnnnnnn")`
+- `hhea_table` — 16-element pack
+- `os2_table` — 43-element pack
+- `name_table` — manual record + offset arithmetic
+- `post_table` — manual pack
+- `hmtx_table` — `Array.new(num_glyphs) { [1000, 0] }.flatten.pack("n*")`
+- `cmap_table` / `format4_subtable` / `format12_subtable` — full cmap builder, ~80 lines
+
+~200 lines of pack/unpack that duplicate the layout knowledge in `Tables::*`. If any table layout changes, the fixture breaks silently — the same anti-pattern PR #107 already fixed for CBDT/CBLC.
+
+## Goal
+
+Every table builder in `cbdt_fixture.rb` constructs via BinData record (`Tables::Head`, `Tables::Hhea`, `Tables::Maxp`, `Tables::Os2`, `Tables::Name`, `Tables::Post`, `Tables::Hmtx`, `Tables::Cmap`). No more `[...].pack(...)` calls.
+
+The fixture's self-test (`spec/support/cbdt_fixture_spec.rb`) catches any drift between the fixture's output and the BinData models.
+
+## Approach
+
+For each table, replace the hand-rolled pack with a `Tables::*` BinData construction:
+
+```ruby
+# Before
+def head_table
+  [0x00010000, 0x00005000, ...].pack("NNNNnnNNnnnnnnnnnn")
+end
+
+# After
+def head_table
+  Tables::Head.new(
+    version_raw: 0x00010000,
+    font_revision: 0x00005000,
+    ...
+  ).to_binary_s
+end
+```
+
+For tables with field shapes that don't match the BinData record cleanly (e.g., `name_table`'s variable-length string storage), use the BinData record's nested array attributes.
+
+For `cmap_table`: extract the format-4 / format-12 subtable builders to a reusable `Tables::Cmap.from_mappings(mappings)` class method. The same logic is duplicated in `Subset::TableStrategy::Cmap::Builder` and `Subset::TableStrategy::ColorBitmapSubsetter` — DRY win across three call sites.
+
+## Out of scope
+
+- Refactoring the BinData models themselves — only changes the fixture's consumers.
+- Adding `Tables::Cmap.from_mappings` if the DRY extraction scope proves larger than the fixture alone (split into separate PR).
+
+## Effort
+
+~4 hours.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- `spec/support/cbdt_fixture.rb` contains zero `[...].pack` calls.
+- `spec/support/cbdt_fixture_spec.rb` self-test still passes (it round-trips via the BinData models; the assertions don't change).
+- All downstream specs that use `CbdtFixture` still pass.
+- Bundle size of the fixture file drops from ~300 lines to ~150.

data/TODO.improvements/13-split-octokit-fetcher.md

@@ -0,0 +1,45 @@
+# 13 — Split `OctokitFetcher` out of `fixture_downloader.rb`
+
+## Priority
+P3
+
+## Problem
+
+`spec/support/fixture_downloader.rb` (post-PR #111) is ~350 lines with two distinct concerns:
+
+1. **Retry / routing loop** (the `Downloader` class) — backoff, Retry-After, permanent-vs-transient classification.
+2. **Octokit URL dispatch** (the `OctokitFetcher` module) — release-asset, raw-file, contents-API routing.
+
+These are MECE-distinct. Bundling them in one file muddies the boundary; future changes to Octokit routing shouldn't require reading the retry loop.
+
+## Goal
+
+`OctokitFetcher` moves to its own file `spec/support/fixture_downloader/octokit_fetcher.rb`. The `Downloader` class becomes the only public surface in `spec/support/fixture_downloader.rb` and delegates to `OctokitFetcher` when needed.
+
+## Approach
+
+1. Create `spec/support/fixture_downloader/` directory.
+2. Move `OctokitFetcher` module to `spec/support/fixture_downloader/octokit_fetcher.rb`.
+3. Move `HttpStatusIo` and `Downloader` constants stay in `spec/support/fixture_downloader.rb`.
+4. Add a `module FixtureFonts::Downloader` autoload or simple `require_relative "fixture_downloader/octokit_fetcher"` from `fixture_downloader.rb`.
+
+Actually — for spec/support files, `require_relative` is acceptable (CLAUDE.md rule on autoload is for `lib/`). No autoload needed; the Rakefile's `require_relative` chain handles loading.
+
+## Out of scope
+
+- Splitting the Downloader further — it's cohesive.
+- Moving `fixture_downloader_spec.rb` — already sibling, fine where it is.
+
+## Effort
+
+~1 hour.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- `spec/support/fixture_downloader.rb` < 200 lines.
+- `spec/support/fixture_downloader/octokit_fetcher.rb` exists and contains all Octokit-specific code.
+- All existing specs pass unchanged.

data/TODO.improvements/14-rubocop-baseline-chip.md

@@ -0,0 +1,62 @@
+# 14 — Rubocop baseline chip (per-namespace)
+
+## Priority
+P3
+
+## Problem
+
+PR #111's `rubocop -A --auto-gen-config` baseline refresh tracked ~9600 remaining offenses. The `.rubocop_todo.yml` file is now ~800 lines of `Exclude:` lists. Layout/Style cops dominate (most are auto-correctable; the rest need manual fixes).
+
+Leaving the baseline in this state makes future rubocop improvements invisible — new offenses are buried in baseline noise, and contributors can't see whether their PR is clean vs. baseline-burdened.
+
+## Goal
+
+Reduce baseline count to < 1000 offenses via per-namespace PRs:
+
+| Namespace | Approximate count | Priority |
+|-----------|-------------------|----------|
+| `lib/fontisan/tables/` | ~3000 | High (well-understood) |
+| `lib/fontisan/ufo/compile/` | ~2500 | High |
+| `lib/fontisan/stitcher/` | ~800 | Medium |
+| `lib/fontisan/converters/` | ~500 | Medium |
+| `lib/fontisan/type1/` | ~400 | Medium |
+| `lib/fontisan/collection/` | ~300 | Medium |
+| `lib/fontisan/subset/` | ~300 | Medium (recent PR #106 work) |
+| `lib/fontisan/woff2/` | ~250 | Medium |
+| `lib/fontisan/optimizers/` | ~200 | Low |
+| `lib/fontisan/pipeline/` | ~200 | Low |
+| `lib/fontisan/commands/` | ~150 | Low |
+| `lib/fontisan/validators/` | ~100 | Low |
+| `lib/fontisan/binary/` | ~100 | Low |
+| `spec/` | ~1500 | Low |
+
+## Approach
+
+One PR per namespace. Each PR:
+
+1. Runs `rubocop -A lib/fontisan/<namespace>/` to auto-correct everything possible.
+2. Manually fixes what auto-correct couldn't (typically: complex Layout cops, naming).
+3. Updates `.rubocop_todo.yml` to drop the now-cleaned `Exclude:` entries.
+4. Verifies the full test suite still passes.
+
+Order: tables first (highest count, lowest risk — table parsing is purely structural).
+
+## Out of scope
+
+- Disabling cops project-wide — these are real issues, not noise.
+- Refactoring architectural patterns rubocop flags (e.g., long methods) — separate refactors.
+
+## Effort
+
+~30 minutes per namespace on average. ~7 hours total.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- `.rubocop_todo.yml` < 100 lines (from ~800).
+- `bundle exec rubocop` reports 0 offenses.
+- All existing specs pass after each namespace PR.
+- No behavior change (pure style/layout).

data/TODO.improvements/README.md

@@ -0,0 +1,57 @@
+# Fontisan Improvements Backlog
+
+This directory tracks all known improvement work, ordered by priority.
+Each file is `NN-short-name.md` where `NN` is the priority order.
+
+## Priorities
+
+### P0 — Correctness gaps (open bugs / silent failures)
+- [01 — CBDT/CBLC GID-stable propagation](01-cbdt-cblc-gid-stable-propagation.md)
+- [02 — Collection-mode outline-priority regression](02-collection-outline-priority.md)
+
+### P1 — High-value features
+- [03 — `fontisan audit` command (identity+style+features lens)](03-fontisan-audit-command.md)
+- [04 — UFO composite glyph encoding](04-ufo-composite-glyph-encoding.md)
+- [05 — OTF compiler real CFF charstrings](05-otf-compiler-real-cff.md)
+
+### P2 — Specialist feature parity
+- [x] ~~[07 — CPAL v1 header fields](07-cpal-v1-header-fields.md)~~ ✓ Done
+- [06 — CFF2 blend/vsindex operators](06-cff2-blend-vsindex-operators.md)
+- [08 — CFF standard string table](08-cff-standard-string-table.md)
+- [09 — Type 1 seac expansion](09-type1-seac-expansion.md)
+- [10 — UFO image set + feature writers](10-ufo-image-set-feature-writers.md)
+- [11 — kern groups.plist support](11-kern-groups-plist.md)
+
+### P3 — Code-quality cleanup
+- [x] ~~[13 — Split `OctokitFetcher` out of `fixture_downloader.rb`](13-split-octokit-fetcher.md)~~ ✓ Done (commit `4c68f2a`)
+- [12 — `cbdt_fixture.rb` full BinData conversion](12-cbdt-fixture-bindata-conversion.md)
+- [14 — Rubocop baseline chip (per-namespace)](14-rubocop-baseline-chip.md)
+
+## Convention
+
+Each TODO file follows this template:
+
+```markdown
+# NN — Title
+
+## Priority
+P0 / P1 / P2 / P3
+
+## Problem
+What's broken or missing. Concrete examples.
+
+## Goal
+What good looks like. Acceptance criteria.
+
+## Approach
+Architecture-level sketch. Files to add/change. Constraints.
+
+## Out of scope
+Explicit non-goals.
+
+## Effort
+Rough estimate (hours/days).
+
+## Dependencies
+Other TODOs that must land first.
+```

data/lib/fontisan/tables/cpal.rb

@@ -27,7 +27,10 @@ module Fontisan
     # - numColorRecords (uint16): Total number of color records
     # - colorRecordsArrayOffset (uint32): Offset to color records array
     #
-    # Version 1 adds optional metadata for palette types and labels.
+    # Version 1 Header (24 bytes) adds:
+    # - paletteTypesArrayOffset (uint32): Offset to palette types array
+    # - paletteLabelsArrayOffset (uint32): Offset to palette labels array
+    # - paletteEntryLabelsArrayOffset (uint32): Offset to palette entry labels
     #
     # Color Record Structure (4 bytes, BGRA format):
     # - blue (uint8)
@@ -47,6 +50,13 @@ module Fontisan
       # OpenType table tag for CPAL
       TAG = "CPAL"
 
+      # Palette type bit flags (CPAL v1, paletteTypesArray entries).
+      PALETTE_TYPE_LIGHT_ON_DARK = 0x01
+      PALETTE_TYPE_DARK_ON_LIGHT = 0x02
+
+      # Offset that means "no table present" in CPAL v1.
+      NULL_OFFSET = 0
+
       # @return [Integer] CPAL version (0 or 1)
       attr_reader :version
 
@@ -71,6 +81,19 @@ module Fontisan
       # @return [Array<Hash>] Parsed color records (RGBA hashes)
       attr_reader :color_records
 
+      # @return [Array<Integer>, nil] Palette type bit flags, one per
+      #   palette. nil for CPAL v0 or when v1 has no palette types array.
+      attr_reader :palette_types
+
+      # @return [Array<Integer>, nil] Name-record IDs (name table) for
+      #   each palette. nil for CPAL v0 or when v1 has no labels array.
+      attr_reader :palette_labels
+
+      # @return [Array<Integer>, nil] Name-record IDs (name table) for
+      #   each palette entry index (shared across palettes). nil for
+      #   CPAL v0 or when v1 has no entry-labels array.
+      attr_reader :palette_entry_labels
+
       # Override read to parse CPAL structure
       #
       # @param io [IO, String] Binary data to read
@@ -102,8 +125,8 @@ module Fontisan
         # Parse color records
         parse_color_records(io)
 
-        # Version 1 features (palette types, labels) not implemented yet
-        # TODO: Add version 1 features in follow-up task
+        # Version 1: palette types + labels (lazily walked via offsets)
+        parse_v1_metadata if version == 1
       rescue StandardError => e
         raise CorruptedTableError, "Failed to parse CPAL table: #{e.message}"
       end
@@ -152,6 +175,44 @@ module Fontisan
         color_record ? color_to_hex(color_record) : nil
       end
 
+      # Get the name-record ID for a palette's human-readable label.
+      #
+      # @param palette_index [Integer]
+      # @return [Integer, nil] nameID for the palette, or nil if v0 / no labels
+      def palette_label(palette_index)
+        return nil unless palette_labels
+        return nil if palette_index.negative? || palette_index >= palette_labels.length
+
+        palette_labels[palette_index]
+      end
+
+      # Get the name-record ID for a palette entry's human-readable label.
+      #
+      # @param entry_index [Integer]
+      # @return [Integer, nil] nameID for the entry, or nil if v0 / no labels
+      def palette_entry_label(entry_index)
+        return nil unless palette_entry_labels
+        return nil if entry_index.negative? || entry_index >= palette_entry_labels.length
+
+        palette_entry_labels[entry_index]
+      end
+
+      # Whether a palette is intended for light-on-dark use (CPAL v1).
+      #
+      # @param palette_index [Integer]
+      # @return [Boolean] true if the palette type bit is set; false otherwise
+      def light_on_dark?(palette_index)
+        palette_type_set?(palette_index, PALETTE_TYPE_LIGHT_ON_DARK)
+      end
+
+      # Whether a palette is intended for dark-on-light use (CPAL v1).
+      #
+      # @param palette_index [Integer]
+      # @return [Boolean] true if the palette type bit is set; false otherwise
+      def dark_on_light?(palette_index)
+        palette_type_set?(palette_index, PALETTE_TYPE_DARK_ON_LIGHT)
+      end
+
       # Validate the CPAL table structure
       #
       # @return [Boolean] True if valid
@@ -169,7 +230,7 @@ module Fontisan
 
       private
 
-      # Parse CPAL header (12 bytes for version 0, 16 bytes for version 1)
+      # Parse CPAL header (12 bytes for v0, 24 bytes for v1)
       #
       # @param io [StringIO] Input stream
       def parse_header(io)
@@ -179,12 +240,14 @@ module Fontisan
         @num_color_records = io.read(2).unpack1("n")
         @color_records_array_offset = io.read(4).unpack1("N")
 
-        # Version 1 has additional header fields
-        if version == 1
-          # TODO: Parse version 1 header fields
-          # - paletteTypesArrayOffset (uint32)
-          # - paletteLabelsArrayOffset (uint32)
-          # - paletteEntryLabelsArrayOffset (uint32)
+        # Version 1 has three additional uint32 offset fields. Offsets
+        # are read here but the arrays themselves are walked lazily
+        # from parse_v1_metadata so the v0 path (most common) doesn't
+        # pay for the seeks.
+        if @version == 1
+          @palette_types_array_offset = io.read(4).unpack1("N")
+          @palette_labels_array_offset = io.read(4).unpack1("N")
+          @palette_entry_labels_array_offset = io.read(4).unpack1("N")
         end
       end
 
@@ -228,7 +291,7 @@ module Fontisan
         @palette_indices = []
         return if num_palettes.zero?
 
-        # Palette indices immediately follow header (at offset 12 for v0, 16 for v1)
+        # Palette indices immediately follow header (at offset 12 for v0, 24 for v1)
         # Each index is uint16 (2 bytes)
         num_palettes.times do
           index = io.read(2).unpack1("n")
@@ -262,6 +325,44 @@ module Fontisan
         end
       end
 
+      # CPAL v1 metadata: palette types + labels + entry labels.
+      # Walked lazily via the offsets parsed in parse_header. Any
+      # offset of 0 means "no table present" — leave the accessor nil
+      # rather than raise.
+      def parse_v1_metadata
+        @palette_types = walk_uint32_array(@palette_types_array_offset, num_palettes)
+        @palette_labels = walk_uint16_array(@palette_labels_array_offset, num_palettes)
+        @palette_entry_labels = walk_uint16_array(@palette_entry_labels_array_offset,
+                                                  num_palette_entries)
+      end
+
+      def walk_uint32_array(offset, count)
+        return nil if offset.nil? || offset == NULL_OFFSET
+        return [] if count.zero?
+
+        bytes = raw_data[offset, count * 4]
+        return nil unless bytes && bytes.bytesize == count * 4
+
+        bytes.unpack("N*")
+      end
+
+      def walk_uint16_array(offset, count)
+        return nil if offset.nil? || offset == NULL_OFFSET
+        return [] if count.zero?
+
+        bytes = raw_data[offset, count * 2]
+        return nil unless bytes && bytes.bytesize == count * 2
+
+        bytes.unpack("n*")
+      end
+
+      def palette_type_set?(palette_index, bit)
+        return false unless palette_types
+        return false if palette_index.negative? || palette_index >= palette_types.length
+
+        (palette_types[palette_index] & bit).nonzero? ? true : false
+      end
+
       # Convert color record to hex string
       #
       # @param color [Hash] Color hash with :red, :green, :blue, :alpha keys

data/lib/fontisan/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fontisan
-  VERSION = "0.4.24"
+  VERSION = "0.4.25"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fontisan
 version: !ruby/object:Gem::Version
-  version: 0.4.24
+  version: 0.4.25
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-09 00:00:00.000000000 Z
+date: 2026-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -133,6 +133,21 @@ files:
 - LICENSE
 - README.adoc
 - Rakefile
+- TODO.improvements/01-cbdt-cblc-gid-stable-propagation.md
+- TODO.improvements/02-collection-outline-priority.md
+- TODO.improvements/03-fontisan-audit-command.md
+- TODO.improvements/04-ufo-composite-glyph-encoding.md
+- TODO.improvements/05-otf-compiler-real-cff.md
+- TODO.improvements/06-cff2-blend-vsindex-operators.md
+- TODO.improvements/07-cpal-v1-header-fields.md
+- TODO.improvements/08-cff-standard-string-table.md
+- TODO.improvements/09-type1-seac-expansion.md
+- TODO.improvements/10-ufo-image-set-feature-writers.md
+- TODO.improvements/11-kern-groups-plist.md
+- TODO.improvements/12-cbdt-fixture-bindata-conversion.md
+- TODO.improvements/13-split-octokit-fetcher.md
+- TODO.improvements/14-rubocop-baseline-chip.md
+- TODO.improvements/README.md
 - benchmark/compile_benchmark.rb
 - benchmark/variation_quick_bench.rb
 - docs/.gitignore