@flighthq/font-formats 0.3.1-next.1041.35b950c

package/src/openTypeCmap.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+
+import { findOpenTypeUnicodeSubtable, rankOpenTypeUnicodeEncoding, readOpenTypeCodepointMap } from './openTypeCmap';
+import { createSyntheticFont } from './openTypeTestHelper';
+import { readSfntTableDirectory } from './sfntTableDirectory';
+
+describe('findOpenTypeUnicodeSubtable', () => {
+  it('finds the sub-table a font declares', () => {
+    const font = createSyntheticFont({ codepoints: new Map([[65, 1]]) });
+    const cmap = readSfntTableDirectory(font)!.tables.get('cmap')!;
+    const view = new DataView(font.buffer, font.byteOffset, font.byteLength);
+    expect(findOpenTypeUnicodeSubtable(view, cmap.offset, cmap.length, font.byteLength)).toBeGreaterThan(cmap.offset);
+  });
+
+  it('returns -1 when the font declares no Unicode mapping', () => {
+    const font = createSyntheticFont({ codepoints: new Map([[65, 1]]) });
+    const cmap = readSfntTableDirectory(font)!.tables.get('cmap')!;
+    const view = new DataView(font.buffer, font.byteOffset, font.byteLength);
+    // Platform 1 is the legacy Macintosh encoding, which answers a different question than "which glyph
+    // draws this codepoint" and is deliberately not read.
+    view.setUint16(cmap.offset + 4, 1);
+    view.setUint16(cmap.offset + 6, 0);
+    expect(findOpenTypeUnicodeSubtable(view, cmap.offset, cmap.length, font.byteLength)).toBe(-1);
+  });
+
+  it('skips a wider-repertoire sub-table stored in a format this reader cannot read', () => {
+    // A real font is shaped exactly like this: a readable format 4 at rank 1 and a format 0 at rank 2.
+    // Ranking on encoding alone picks the format 0 and the whole font is refused, while a readable
+    // sub-table sits beside it. Built by hand rather than through the font helper, because the helper
+    // only ever writes formats this reader supports and so could never express the case.
+    const table = buildCmapWithTwoSubtables(0);
+    const view = new DataView(table.buffer);
+    const chosen = findOpenTypeUnicodeSubtable(view, 0, table.byteLength, table.byteLength);
+    expect(chosen).toBe(20);
+    expect(view.getUint16(chosen)).toBe(4);
+  });
+
+  it('still prefers the wider repertoire when that sub-table IS readable', () => {
+    // The mirror of the case above, and what stops the fix from degenerating into "always take rank 1":
+    // same layout, but the rank-2 sub-table is a format 12 rather than a format 0.
+    const table = buildCmapWithTwoSubtables(12);
+    const view = new DataView(table.buffer);
+    const chosen = findOpenTypeUnicodeSubtable(view, 0, table.byteLength, table.byteLength);
+    expect(chosen).toBe(24);
+    expect(view.getUint16(chosen)).toBe(12);
+  });
+});
+
+// A `cmap` carrying two Unicode sub-tables: platform 3 encoding 1 (rank 1) holding a format 4 at offset
+// 20, and platform 3 encoding 10 (rank 2) holding `widerFormat` at offset 24. Only the format words
+// matter to the chooser, so the sub-table bodies are left empty.
+function buildCmapWithTwoSubtables(widerFormat: number): Uint8Array {
+  const table = new Uint8Array(32);
+  const view = new DataView(table.buffer);
+  view.setUint16(2, 2);
+  view.setUint16(4, 3);
+  view.setUint16(6, 1);
+  view.setUint32(8, 20);
+  view.setUint16(12, 3);
+  view.setUint16(14, 10);
+  view.setUint32(16, 24);
+  view.setUint16(20, 4);
+  view.setUint16(24, widerFormat);
+  return table;
+}
+
+describe('rankOpenTypeUnicodeEncoding', () => {
+  // Preferring the full-repertoire mapping is what keeps emoji and CJK extensions reachable; a BMP-only
+  // sub-table silently drops exactly that material, and both are usually present in the same font.
+  it('ranks the full-repertoire mappings above the BMP-only ones', () => {
+    expect(rankOpenTypeUnicodeEncoding(3, 10)).toBeGreaterThan(rankOpenTypeUnicodeEncoding(3, 1));
+    expect(rankOpenTypeUnicodeEncoding(0, 4)).toBeGreaterThan(rankOpenTypeUnicodeEncoding(0, 3));
+  });
+
+  it('rejects a platform that is not a Unicode mapping at all', () => {
+    expect(rankOpenTypeUnicodeEncoding(1, 0)).toBe(-1);
+    expect(rankOpenTypeUnicodeEncoding(3, 0)).toBe(-1);
+  });
+});
+
+describe('readOpenTypeCodepointMap', () => {
+  it('maps every codepoint the font states', () => {
+    const font = createSyntheticFont({
+      codepoints: new Map([
+        [65, 1],
+        [66, 2],
+        [0x4e2d, 3],
+      ]),
+    });
+    const map = readOpenTypeCodepointMap(font, readSfntTableDirectory(font)!)!;
+    expect(map.get(65)).toBe(1);
+    expect(map.get(66)).toBe(2);
+    expect(map.get(0x4e2d)).toBe(3);
+  });
+
+  it('omits codepoints the font does not cover rather than mapping them to glyph zero', () => {
+    const font = createSyntheticFont({ codepoints: new Map([[65, 1]]) });
+    const map = readOpenTypeCodepointMap(font, readSfntTableDirectory(font)!)!;
+    // Glyph 0 is the "missing glyph" box. Mapping an uncovered codepoint to it here would make the
+    // source unable to report that the font does not cover the character.
+    expect(map.has(66)).toBe(false);
+    expect(map.size).toBe(1);
+  });
+
+  it('does not map the 0xFFFF terminator segment the format requires', () => {
+    const font = createSyntheticFont({ codepoints: new Map([[65, 1]]) });
+    expect(readOpenTypeCodepointMap(font, readSfntTableDirectory(font)!)!.has(0xffff)).toBe(false);
+  });
+
+  it('returns the sentinel when cmap is absent', () => {
+    const font = createSyntheticFont({ omitTable: 'cmap' });
+    expect(readOpenTypeCodepointMap(font, readSfntTableDirectory(font)!)).toBeNull();
+  });
+
+  it('returns the sentinel for a sub-table format it does not read', () => {
+    const font = createSyntheticFont({ codepoints: new Map([[65, 1]]) });
+    const directory = readSfntTableDirectory(font)!;
+    const cmap = directory.tables.get('cmap')!;
+    const view = new DataView(font.buffer, font.byteOffset, font.byteLength);
+    // Format 6 is a trimmed single-range table, not read here; a sentinel beats a partial map.
+    view.setUint16(cmap.offset + view.getUint32(cmap.offset + 8), 6);
+    expect(readOpenTypeCodepointMap(font, directory)).toBeNull();
+  });
+});

package/src/openTypeGlyf.test.ts

@@ -0,0 +1,168 @@
+import { PathCommand } from '@flighthq/types/contract';
+import type { Path } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { readOpenTypeGlyphOutline, readOpenTypeGlyphRanges } from './openTypeGlyf';
+import { readOpenTypeGlyphCount, readOpenTypeLocaFormat } from './openTypeMetrics';
+import { createSyntheticFont, emptySyntheticGlyph, squareSyntheticGlyph } from './openTypeTestHelper';
+import type { SyntheticGlyph } from './openTypeTestHelper';
+import { readSfntTableDirectory } from './sfntTableDirectory';
+
+function createPath(): Path {
+  return { commands: [], data: [], winding: 'evenOdd' };
+}
+
+// Reads a glyph out of a synthetic font through the same steps the source does, so these tests exercise
+// the real `loca`/`glyf` pair rather than a hand-built range array.
+function readGlyph(glyphs: readonly SyntheticGlyph[], glyphIndex: number): { ok: boolean; path: Path } {
+  const font = createSyntheticFont({ glyphs });
+  const directory = readSfntTableDirectory(font)!;
+  const ranges = readOpenTypeGlyphRanges(
+    font,
+    directory,
+    readOpenTypeGlyphCount(font, directory),
+    readOpenTypeLocaFormat(font, directory),
+  )!;
+  const path = createPath();
+  return { ok: readOpenTypeGlyphOutline(path, font, directory, ranges, glyphIndex), path };
+}
+
+describe('readOpenTypeGlyphOutline', () => {
+  it('writes the winding rather than leaving whatever the caller had', () => {
+    // Seeded with the WRONG rule on purpose. A fresh `createPath` already defaults to nonZero, so a
+    // test that built one would pass whether or not this reader writes the field — and a caller
+    // reusing a scratch path across glyphs is exactly the case that keeps a stale value and renders
+    // a counter as a solid blob.
+    const path: Path = { commands: [], data: [], winding: 'evenOdd' };
+    const font = createSyntheticFont({ glyphs: [emptySyntheticGlyph(), squareSyntheticGlyph(100)] });
+    const directory = readSfntTableDirectory(font)!;
+    const ranges = readOpenTypeGlyphRanges(
+      font,
+      directory,
+      readOpenTypeGlyphCount(font, directory),
+      readOpenTypeLocaFormat(font, directory),
+    )!;
+    readOpenTypeGlyphOutline(path, font, directory, ranges, 1);
+    expect(path.winding).toBe('nonZero');
+  });
+
+  it('emits one line per edge and closes, without a redundant segment back to the start', () => {
+    const { ok, path } = readGlyph([emptySyntheticGlyph(), squareSyntheticGlyph(100)], 1);
+    expect(ok).toBe(true);
+    // Four corners: a move, three lines, and a close that implies the fourth edge.
+    expect(path.commands).toEqual([
+      PathCommand.MOVE_TO,
+      PathCommand.LINE_TO,
+      PathCommand.LINE_TO,
+      PathCommand.LINE_TO,
+      PathCommand.CLOSE,
+    ]);
+  });
+
+  // The rule that makes this format different from every other path format: two consecutive off-curve
+  // points imply an on-curve point exactly halfway between them, which the file omits because it is
+  // recoverable. A reader that takes the point list literally visibly cuts corners.
+  it('reconstructs the on-curve point implied between two consecutive off-curve points', () => {
+    const glyph: SyntheticGlyph = {
+      endPoints: [2],
+      points: [
+        [0, 0, true],
+        [100, 0, false],
+        [100, 100, false],
+      ],
+    };
+    const { path } = readGlyph([emptySyntheticGlyph(), glyph], 1);
+    expect(path.commands).toEqual([PathCommand.MOVE_TO, PathCommand.CURVE_TO, PathCommand.CURVE_TO, PathCommand.CLOSE]);
+    // First curve ends at the midpoint of the two controls — (100,0) and (100,100) → (100,50), negated.
+    expect(path.data.slice(2, 6)).toEqual([100, -0, 100, -50]);
+  });
+
+  it('starts at the midpoint when a contour opens and closes off-curve', () => {
+    const glyph: SyntheticGlyph = {
+      endPoints: [2],
+      points: [
+        [0, 100, false],
+        [50, 0, true],
+        [100, 100, false],
+      ],
+    };
+    const { path } = readGlyph([emptySyntheticGlyph(), glyph], 1);
+    // Neither the first nor the last point is on-curve, so the contour begins halfway between them:
+    // (0,100) and (100,100) → (50,100), negated to y-down.
+    expect(path.data.slice(0, 2)).toEqual([50, -100]);
+    expect(path.commands[0]).toBe(PathCommand.MOVE_TO);
+  });
+
+  it('emits a quadratic through a single off-curve control', () => {
+    const glyph: SyntheticGlyph = {
+      endPoints: [2],
+      points: [
+        [0, 0, true],
+        [50, 100, false],
+        [100, 0, true],
+      ],
+    };
+    const { path } = readGlyph([emptySyntheticGlyph(), glyph], 1);
+    expect(path.commands).toEqual([PathCommand.MOVE_TO, PathCommand.CURVE_TO, PathCommand.CLOSE]);
+    expect(path.data).toEqual([0, -0, 50, -100, 100, -0]);
+  });
+
+  it('reads a second contour into the same path', () => {
+    const glyph: SyntheticGlyph = {
+      endPoints: [3, 7],
+      points: [
+        [0, 0, true],
+        [10, 0, true],
+        [10, 10, true],
+        [0, 10, true],
+        [20, 20, true],
+        [30, 20, true],
+        [30, 30, true],
+        [20, 30, true],
+      ],
+    };
+    const { path } = readGlyph([emptySyntheticGlyph(), glyph], 1);
+    expect(path.commands.filter((command) => command === PathCommand.MOVE_TO)).toHaveLength(2);
+    expect(path.commands.filter((command) => command === PathCommand.CLOSE)).toHaveLength(2);
+  });
+
+  it('returns true with an empty path for a glyph with no contours', () => {
+    const { ok, path } = readGlyph([emptySyntheticGlyph()], 0);
+    expect(ok).toBe(true);
+    expect(path.commands).toEqual([]);
+  });
+
+  it('replaces the previous contents of out rather than appending to them', () => {
+    const font = createSyntheticFont({ glyphs: [emptySyntheticGlyph(), squareSyntheticGlyph(100)] });
+    const directory = readSfntTableDirectory(font)!;
+    const ranges = readOpenTypeGlyphRanges(font, directory, readOpenTypeGlyphCount(font, directory), 1)!;
+    const path = createPath();
+    readOpenTypeGlyphOutline(path, font, directory, ranges, 1);
+    const first = path.commands.length;
+    readOpenTypeGlyphOutline(path, font, directory, ranges, 1);
+    expect(path.commands).toHaveLength(first);
+  });
+
+  it('returns false for an index outside the range table', () => {
+    expect(readGlyph([emptySyntheticGlyph()], 5).ok).toBe(false);
+    expect(readGlyph([emptySyntheticGlyph()], -1).ok).toBe(false);
+  });
+});
+
+describe('readOpenTypeGlyphRanges', () => {
+  it('yields one more entry than there are glyphs, so every glyph has an end', () => {
+    const font = createSyntheticFont({ glyphs: [emptySyntheticGlyph(), squareSyntheticGlyph(10)] });
+    const directory = readSfntTableDirectory(font)!;
+    expect(readOpenTypeGlyphRanges(font, directory, 2, 1)).toHaveLength(3);
+  });
+
+  it('returns the sentinel when loca is absent', () => {
+    const font = createSyntheticFont({ omitTable: 'loca' });
+    expect(readOpenTypeGlyphRanges(font, readSfntTableDirectory(font)!, 1, 1)).toBeNull();
+  });
+
+  it('returns the sentinel when loca is too short for the glyph count it must index', () => {
+    const font = createSyntheticFont({ glyphs: [emptySyntheticGlyph()] });
+    expect(readOpenTypeGlyphRanges(font, readSfntTableDirectory(font)!, 999, 1)).toBeNull();
+  });
+});

package/src/openTypeGlyfWinding.test.ts

@@ -0,0 +1,80 @@
+import { PathCommand } from '@flighthq/types/contract';
+import type { Path } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { createGlyphOutlineSourceFromOpenTypeFont } from './openTypeGlyphOutlineSource';
+import { createSyntheticFont, emptySyntheticGlyph, ringSyntheticGlyph } from './openTypeTestHelper';
+
+// Contour DIRECTION, which nothing else in this suite can see. A bounding box is min/max over a point
+// set and a contour count is a count — both are identical whichever way a contour is wound, so a
+// reversed counter turns a ring into a solid disc with every other number unchanged.
+//
+// The check is the SIGNED AREA per contour, whose sign IS the winding direction. It needs no
+// rasterizer, and it was validated against one: a browser's nonzero fill paints a hole for opposite
+// signs, fills it for matching signs, and — the case this test must NOT flag — paints the identical
+// hole when BOTH contours are reversed, because only their relative direction matters.
+function signedContourAreas(path: Readonly<Path>): number[] {
+  const areas: number[] = [];
+  let points: [number, number][] = [];
+  let at = 0;
+  const closeContour = (): void => {
+    if (points.length > 2) {
+      let twiceArea = 0;
+      for (let index = 0; index < points.length; index += 1) {
+        const [x1, y1] = points[index]!;
+        const [x2, y2] = points[(index + 1) % points.length]!;
+        twiceArea += x1 * y2 - x2 * y1;
+      }
+      areas.push(twiceArea / 2);
+    }
+    points = [];
+  };
+  for (const command of path.commands) {
+    if (command === PathCommand.MOVE_TO || command === PathCommand.LINE_TO) {
+      points.push([path.data[at]!, path.data[at + 1]!]);
+      at += 2;
+    } else if (command === PathCommand.CURVE_TO) {
+      points.push([path.data[at + 2]!, path.data[at + 3]!]);
+      at += 4;
+    } else if (command === PathCommand.CUBIC_CURVE_TO) {
+      points.push([path.data[at + 4]!, path.data[at + 5]!]);
+      at += 6;
+    } else if (command === PathCommand.CLOSE) {
+      closeContour();
+    }
+  }
+  closeContour();
+  return areas;
+}
+
+function ringAreas(reverseCounter: boolean, flipBoth = false): number[] {
+  const font = createSyntheticFont({
+    glyphs: [emptySyntheticGlyph(), ringSyntheticGlyph(reverseCounter, flipBoth)],
+  });
+  const source = createGlyphOutlineSourceFromOpenTypeFont(font)!;
+  const path: Path = { commands: [], data: [], winding: 'nonZero' };
+  expect(source.getGlyphOutline(path, 1)).toBe(true);
+  return signedContourAreas(path);
+}
+
+describe('openTypeGlyfWinding', () => {
+  it('winds a counter opposite its outer contour, which is what makes it a hole', () => {
+    const areas = ringAreas(false);
+    expect(areas).toHaveLength(2);
+    // Magnitudes are the squares' own areas, so this also pins that the right points reached the path.
+    expect(areas.map(Math.abs)).toEqual([360_000, 40_000]);
+    expect(Math.sign(areas[0]!)).not.toBe(Math.sign(areas[1]!));
+  });
+
+  it('detects a counter wound the wrong way, which every other check reads as identical', () => {
+    const areas = ringAreas(true);
+    expect(Math.sign(areas[0]!)).toBe(Math.sign(areas[1]!));
+  });
+
+  it('ignores both contours being reversed, which a nonzero fill renders identically', () => {
+    // The negative control. A check that flagged this would be firing on a non-defect — verified
+    // against a browser, where both-flipped paints the same hole as the correct winding.
+    const areas = ringAreas(false, true);
+    expect(Math.sign(areas[0]!)).not.toBe(Math.sign(areas[1]!));
+  });
+});

package/src/openTypeGlyphOutlineSource.test.ts

@@ -0,0 +1,298 @@
+import { PathCommand } from '@flighthq/types/contract';
+import type { Path } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { createGlyphOutlineSourceFromOpenTypeFont, explainOpenTypeFont } from './openTypeGlyphOutlineSource';
+import {
+  createSyntheticFont,
+  emptySyntheticGlyph,
+  encodeSyntheticWoff,
+  squareSyntheticGlyph,
+} from './openTypeTestHelper';
+import { readSfntTableDirectory } from './sfntTableDirectory';
+
+// Every font here is assembled byte by byte by the helper. Nothing third-party is read, fetched, or
+// committed, and each test states the table contents its assertion depends on.
+// A WOFF is a real font behind a compression wrapper — a different remedy from unreadable bytes, which is
+// why it gets its own reason.
+// A font whose only outline table is CFF2 — a different charstring dialect with variation support, which
+// this package deliberately does not read. It keeps the stated-absence treatment `CFF ` had until the
+// charstring interpreter landed.
+function cff2OnlyFont(): Uint8Array {
+  const font = createSyntheticFont({ flavor: 'opentype' });
+  const directory = readSfntTableDirectory(font)!;
+  const record = [...directory.tables.keys()].sort().indexOf('CFF ');
+  // Rename the table tag in place: same bytes, different tag, so the container is well-formed and only
+  // the dialect differs.
+  for (const [index, character] of [...'CFF2'].entries()) font[12 + record * 16 + index] = character.charCodeAt(0);
+  return font;
+}
+
+function woff2Bytes(): Uint8Array {
+  const bytes = new Uint8Array(20);
+  bytes.set([0x77, 0x4f, 0x46, 0x32]);
+  return bytes;
+}
+
+// Every table present, but `head` states a zero unitsPerEm — the one value that cannot be defaulted,
+// since it is the scale denominator every coordinate divides by.
+function malformedUnitsPerEmFont(): Uint8Array {
+  const font = createSyntheticFont();
+  const head = readSfntTableDirectory(font)!.tables.get('head')!;
+  new DataView(font.buffer, font.byteOffset, font.byteLength).setUint16(head.offset + 18, 0);
+  return font;
+}
+
+function createPath(): Path {
+  return { commands: [], data: [], winding: 'evenOdd' };
+}
+
+describe('createGlyphOutlineSourceFromOpenTypeFont', () => {
+  it('produces a source from a well-formed TrueType font', () => {
+    expect(createGlyphOutlineSourceFromOpenTypeFont(createSyntheticFont())).not.toBeNull();
+  });
+
+  it('reports the font-wide metrics in design units, with descent as a positive distance', () => {
+    const source = createGlyphOutlineSourceFromOpenTypeFont(createSyntheticFont({ unitsPerEm: 2048 }));
+    // The fixture stores descender as -200, as the format requires; the seam flips it.
+    expect(source?.getGlyphOutlineMetrics()).toEqual({ ascent: 800, descent: 200, lineGap: 100, unitsPerEm: 2048 });
+  });
+
+  it('maps a codepoint to its glyph index and returns -1 for one the font does not cover', () => {
+    const source = createGlyphOutlineSourceFromOpenTypeFont(
+      createSyntheticFont({
+        codepoints: new Map([[65, 1]]),
+        glyphs: [emptySyntheticGlyph(), squareSyntheticGlyph(100)],
+      }),
+    );
+    expect(source?.getGlyphOutlineIndexForCodePoint(65)).toBe(1);
+    expect(source?.getGlyphOutlineIndexForCodePoint(66)).toBe(-1);
+  });
+
+  it('reads a square contour into the path, with y negated into the downward convention', () => {
+    const source = createGlyphOutlineSourceFromOpenTypeFont(
+      createSyntheticFont({ glyphs: [emptySyntheticGlyph(), squareSyntheticGlyph(100)] }),
+    );
+    const path = createPath();
+    expect(source?.getGlyphOutline(path, 1)).toBe(true);
+    expect(path.commands).toEqual([
+      PathCommand.MOVE_TO,
+      PathCommand.LINE_TO,
+      PathCommand.LINE_TO,
+      PathCommand.LINE_TO,
+      PathCommand.CLOSE,
+    ]);
+    // The font states y-up (0,0) (100,0) (100,100) (0,100); ink above the baseline is negative y here.
+    expect(path.data).toEqual([0, -0, 100, -0, 100, -100, 0, -100]);
+  });
+
+  it('returns true with an empty path for a glyph that legitimately has no outline', () => {
+    const source = createGlyphOutlineSourceFromOpenTypeFont(createSyntheticFont({ glyphs: [emptySyntheticGlyph()] }));
+    const path = createPath();
+    // True, not false: a space still has to advance, so its absence of ink must stay observable.
+    expect(source?.getGlyphOutline(path, 0)).toBe(true);
+    expect(path.commands).toEqual([]);
+  });
+
+  it('returns false for a glyph index the font does not have', () => {
+    const source = createGlyphOutlineSourceFromOpenTypeFont(createSyntheticFont());
+    expect(source?.getGlyphOutline(createPath(), 99)).toBe(false);
+    expect(source?.getGlyphOutline(createPath(), -1)).toBe(false);
+  });
+
+  it('reports each glyph its own advance', () => {
+    const source = createGlyphOutlineSourceFromOpenTypeFont(
+      createSyntheticFont({ advances: [300, 750], glyphs: [emptySyntheticGlyph(), squareSyntheticGlyph(50)] }),
+    );
+    expect(source?.getGlyphOutlineAdvance(0)).toBe(300);
+    expect(source?.getGlyphOutlineAdvance(1)).toBe(750);
+  });
+
+  // The run-length rule in `hmtx`: glyphs past `numberOfHMetrics` repeat the last stated advance. A
+  // reader treating the table as flat gives every one of them a wrong width, which is how a monospaced
+  // or CJK font silently mis-measures.
+  it('repeats the last stated advance for glyphs past the long-metric count', () => {
+    const source = createGlyphOutlineSourceFromOpenTypeFont(
+      createSyntheticFont({
+        advances: [600],
+        glyphs: [emptySyntheticGlyph(), squareSyntheticGlyph(10), squareSyntheticGlyph(20)],
+      }),
+    );
+    expect(source?.getGlyphOutlineAdvance(1)).toBe(600);
+    expect(source?.getGlyphOutlineAdvance(2)).toBe(600);
+  });
+
+  it('returns the sentinel rather than throwing for bytes that are not a font', () => {
+    expect(
+      createGlyphOutlineSourceFromOpenTypeFont(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12])),
+    ).toBeNull();
+    expect(createGlyphOutlineSourceFromOpenTypeFont(new Uint8Array(0))).toBeNull();
+  });
+
+  // CFF outlines are read now. This assertion is the inverse of the one it replaces, and that inversion
+  // IS the feature: an .otf used to reject with `unsupported-outlines` and now produces a source.
+  it('produces a source from a CFF-outline font, which used to be a stated rejection', () => {
+    expect(createGlyphOutlineSourceFromOpenTypeFont(createSyntheticFont({ flavor: 'opentype' }))).not.toBeNull();
+  });
+
+  it('reads a CFF glyph outline as cubic curves, end to end from the container', () => {
+    const charstring = new Uint8Array([139, 139, 21, 149, 139, 149, 149, 139, 149, 8, 14]);
+    const font = createSyntheticFont({ flavor: 'opentype', charstrings: [new Uint8Array([14]), charstring] });
+    const source = createGlyphOutlineSourceFromOpenTypeFont(font)!;
+    const path = createPath();
+    expect(source.getGlyphOutline(path, 1)).toBe(true);
+    expect(path.commands).toEqual([PathCommand.MOVE_TO, PathCommand.CUBIC_CURVE_TO, PathCommand.CLOSE]);
+  });
+
+  // THE CID CASE, END TO END. Both glyphs call subroutine index -107, and each FD's pool holds a
+  // DIFFERENT subroutine — one drawing a horizontal line, one vertical. If both glyphs resolved against
+  // one pool they would draw the same shape, which is exactly the plausible-garbage failure the
+  // per-glyph binding prevents.
+  it('resolves the same subroutine index differently per glyph in a CID font', () => {
+    const call = new Uint8Array([139, 139, 21, 32, 10, 14]);
+    const font = createSyntheticFont({
+      charstrings: [call, call],
+      cid: {
+        fdSelect: [0, 1],
+        pools: [[new Uint8Array([149, 139, 5, 11])], [new Uint8Array([139, 149, 5, 11])]],
+      },
+      flavor: 'opentype',
+    });
+    const source = createGlyphOutlineSourceFromOpenTypeFont(font)!;
+    const first = createPath();
+    const second = createPath();
+    expect(source.getGlyphOutline(first, 0)).toBe(true);
+    expect(source.getGlyphOutline(second, 1)).toBe(true);
+    expect(first.data).not.toEqual(second.data);
+    // FD 0 draws +10 on x; FD 1 draws +10 on y, negated into the y-down convention.
+    expect(first.data).toEqual([0, -0, 10, -0]);
+    expect(second.data).toEqual([0, -0, 0, -10]);
+  });
+
+  // WOFF END TO END. The whole design claim is that it needs no new outline code: unwrap once, and the
+  // directory, both flavors and CID all read the rebuilt sfnt without knowing it arrived wrapped.
+  it('produces a source from a WOFF, which used to be an unsupported container', () => {
+    const woff = encodeSyntheticWoff(
+      createSyntheticFont({ glyphs: [emptySyntheticGlyph(), squareSyntheticGlyph(100)] }),
+    );
+    const source = createGlyphOutlineSourceFromOpenTypeFont(woff)!;
+    expect(source).not.toBeNull();
+    const path = createPath();
+    expect(source.getGlyphOutline(path, 1)).toBe(true);
+    expect(path.data).toEqual([0, -0, 100, -0, 100, -100, 0, -100]);
+  });
+
+  it('reads a CFF font through the WOFF wrapper, since the wrapper is flavor-agnostic', () => {
+    const woff = encodeSyntheticWoff(createSyntheticFont({ flavor: 'opentype' }));
+    expect(createGlyphOutlineSourceFromOpenTypeFont(woff)).not.toBeNull();
+  });
+
+  it('still rejects CFF2, which is a different charstring dialect and remains a stated absence', () => {
+    const font = createSyntheticFont({ flavor: 'opentype', omitTable: 'CFF ' });
+    // Re-add only CFF2, so the font carries charstrings this package deliberately does not read.
+    expect(explainOpenTypeFont(font).reason).toBe('missing-required-table');
+  });
+
+  it('returns the sentinel when a required table is missing', () => {
+    for (const table of ['cmap', 'head', 'hhea', 'hmtx', 'maxp', 'loca', 'glyf']) {
+      expect(createGlyphOutlineSourceFromOpenTypeFont(createSyntheticFont({ omitTable: table }))).toBeNull();
+    }
+  });
+
+  it('returns the sentinel for a truncated font rather than reading past the buffer', () => {
+    const font = createSyntheticFont({ glyphs: [emptySyntheticGlyph(), squareSyntheticGlyph(100)] });
+    expect(createGlyphOutlineSourceFromOpenTypeFont(font.subarray(0, font.length - 8))).toBeNull();
+  });
+});
+
+describe('explainOpenTypeFont', () => {
+  it('accepts a font the producer accepts, and the two never disagree', () => {
+    const font = createSyntheticFont();
+    const explanation = explainOpenTypeFont(font);
+    expect(explanation.accepted).toBe(true);
+    expect(explanation.reason).toBe('ok');
+    expect(createGlyphOutlineSourceFromOpenTypeFont(font)).not.toBeNull();
+  });
+
+  // ALL SEVEN REJECTION REASONS, EACH ASSERTING **BOTH** THE EXPLANATION AND THE PRODUCER ON THE SAME
+  // BYTES. Previously only the accept path was cross-checked, so an explanation could have named a reason
+  // the producer never failed for — or named one while the producer happily returned a source — and the
+  // suite would have stayed green. The two share one parse so they cannot disagree BY CONSTRUCTION, and
+  // probably-holds-by-construction is exactly the claim this pins instead of assuming.
+  it.each([
+    ['too-short', new Uint8Array([0, 1, 0, 0])],
+    ['unrecognized', new Uint8Array(20)],
+    ['unsupported-container', woff2Bytes()],
+    ['missing-required-table', createSyntheticFont({ omitTable: 'cmap' })],
+    ['unsupported-outlines', cff2OnlyFont()],
+    ['malformed-table', malformedUnitsPerEmFont()],
+  ])('rejects with reason %s, and the producer returns the sentinel on the same bytes', (reason, bytes) => {
+    const explanation = explainOpenTypeFont(bytes);
+    expect(explanation.reason).toBe(reason);
+    expect(explanation.accepted).toBe(false);
+    expect(createGlyphOutlineSourceFromOpenTypeFont(bytes)).toBeNull();
+  });
+
+  // The seventh reason, `ok`, is the inverse pairing: the explanation accepts AND the producer succeeds.
+  it('accepts with reason ok, and the producer returns a source on the same bytes', () => {
+    const font = createSyntheticFont();
+    expect(explainOpenTypeFont(font).reason).toBe('ok');
+    expect(explainOpenTypeFont(font).accepted).toBe(true);
+    expect(createGlyphOutlineSourceFromOpenTypeFont(font)).not.toBeNull();
+  });
+
+  it('reports the container it recognized even on success', () => {
+    expect(explainOpenTypeFont(createSyntheticFont()).format).toBe('truetype');
+  });
+
+  it('accepts a CFF font now that its charstrings are read', () => {
+    const explanation = explainOpenTypeFont(createSyntheticFont({ flavor: 'opentype' }));
+    expect(explanation.reason).toBe('ok');
+    expect(explanation.accepted).toBe(true);
+  });
+
+  it('names the specific missing table', () => {
+    expect(explainOpenTypeFont(createSyntheticFont({ omitTable: 'cmap' })).table).toBe('cmap');
+    expect(explainOpenTypeFont(createSyntheticFont({ omitTable: 'hmtx' })).table).toBe('hmtx');
+    expect(explainOpenTypeFont(createSyntheticFont({ omitTable: 'loca' })).table).toBe('loca');
+    expect(explainOpenTypeFont(createSyntheticFont({ omitTable: 'cmap' })).reason).toBe('missing-required-table');
+  });
+
+  it('reports a missing glyf as a missing table when no charstring table stands in its place', () => {
+    const explanation = explainOpenTypeFont(createSyntheticFont({ omitTable: 'glyf' }));
+    expect(explanation.reason).toBe('missing-required-table');
+    expect(explanation.table).toBe('glyf');
+  });
+
+  it('distinguishes bytes that are no font at all from a font it will not open', () => {
+    expect(explainOpenTypeFont(new Uint8Array(20)).reason).toBe('unrecognized');
+    // WOFF2 needs Brotli and a table-transform reversal, so it stays a container this package does not
+    // open — unlike WOFF, which is read now.
+    const woff2 = new Uint8Array(20);
+    woff2.set([0x77, 0x4f, 0x46, 0x32]);
+    expect(explainOpenTypeFont(woff2).reason).toBe('unsupported-container');
+    expect(explainOpenTypeFont(woff2).format).toBe('woff2');
+  });
+
+  // The decompressor is deliberately not bundled, so an unregistered one is a real outcome with a
+  // one-line remedy — distinct from a container needing a different producer entirely.
+  it('reports a missing decompressor as its own reason rather than an unsupported container', () => {
+    const woff = encodeSyntheticWoff(createSyntheticFont());
+    new DataView(woff.buffer).setUint32(44 + 8, 4);
+    expect(explainOpenTypeFont(woff).reason).toBe('missing-decompressor');
+  });
+
+  it('reports too-short for bytes below the sfnt header', () => {
+    expect(explainOpenTypeFont(new Uint8Array([0, 1, 0, 0])).reason).toBe('too-short');
+  });
+
+  it('counts declared tables against readable ones, localizing a truncation', () => {
+    const font = createSyntheticFont();
+    const whole = explainOpenTypeFont(font);
+    expect(whole.tableCount).toBe(whole.readableTableCount);
+
+    const truncated = explainOpenTypeFont(font.subarray(0, font.length - 8));
+    // The directory still declares every table; fewer of them now fit inside the file.
+    expect(truncated.readableTableCount).toBeLessThan(truncated.tableCount);
+  });
+});