@flighthq/font-formats 0.3.1-next.209.43ef1bc

package/src/cffCharstring.test.ts

@@ -0,0 +1,177 @@
+import { PathCommand } from '@flighthq/types/contract';
+import type { Path } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { cffSubroutineBias, runCffCharstring } from './cffCharstring';
+
+function createPath(): Path {
+  return { commands: [], data: [], winding: 'evenOdd' };
+}
+
+// Charstrings are assembled as raw operator/operand bytes. One-byte operands cover -107..107, which is
+// the whole range these fixtures need, so `n(v)` is the encoding rather than a helper hiding one.
+function n(value: number): number {
+  return value + 139;
+}
+
+function run(...bytes: number[]): { ok: boolean; path: Path } {
+  const buffer = new Uint8Array(bytes);
+  const path = createPath();
+  return { ok: runCffCharstring(path, buffer, { end: buffer.length, start: 0 }, [], []), path };
+}
+
+describe('cffSubroutineBias', () => {
+  // The bias depends on the pool size, so it cannot be a constant. An unbiased index selects a
+  // real-but-wrong subroutine, which draws plausible garbage rather than failing.
+  it('steps at the two thresholds the format defines', () => {
+    expect(cffSubroutineBias(0)).toBe(107);
+    expect(cffSubroutineBias(1239)).toBe(107);
+    expect(cffSubroutineBias(1240)).toBe(1131);
+    expect(cffSubroutineBias(33899)).toBe(1131);
+    expect(cffSubroutineBias(33900)).toBe(32768);
+  });
+});
+
+describe('runCffCharstring', () => {
+  it('writes the winding rather than leaving whatever the caller had', () => {
+    // Seeded with the wrong rule for the same reason as the glyf reader's twin test: a fresh path
+    // already defaults to nonZero, so only a deliberately wrong seed can show the field is written.
+    // `createPath` in this file already seeds the WRONG rule, so every fixture here was positioned
+    // to expose this and nothing had asserted on it.
+    const { path } = run(n(10), n(20), 21, 14);
+    expect(path.winding).toBe('nonZero');
+  });
+
+  it('emits a move and closes on endchar', () => {
+    const { ok, path } = run(n(10), n(20), 21, 14);
+    expect(ok).toBe(true);
+    expect(path.commands).toEqual([PathCommand.MOVE_TO, PathCommand.CLOSE]);
+    // y is negated at this seam, matching the glyf reader so both flavors agree with Path's y-down rule.
+    expect(path.data).toEqual([10, -20]);
+  });
+
+  it('draws relative lines', () => {
+    const { path } = run(n(0), n(0), 21, n(50), n(0), n(0), n(60), 5, 14);
+    expect(path.commands).toEqual([PathCommand.MOVE_TO, PathCommand.LINE_TO, PathCommand.LINE_TO, PathCommand.CLOSE]);
+    expect(path.data).toEqual([0, -0, 50, -0, 50, -60]);
+  });
+
+  it('alternates the axis for hlineto and vlineto', () => {
+    const { path } = run(n(0), n(0), 21, n(10), n(20), n(30), 6, 14);
+    // Starts horizontal, then flips per argument: x+10, y+20, x+30.
+    expect(path.data).toEqual([0, -0, 10, -0, 10, -20, 40, -20]);
+  });
+
+  it('emits a cubic curve, which is what distinguishes this flavor from glyf', () => {
+    const { path } = run(n(0), n(0), 21, n(10), n(0), n(10), n(10), n(0), n(10), 8, 14);
+    expect(path.commands).toEqual([PathCommand.MOVE_TO, PathCommand.CUBIC_CURVE_TO, PathCommand.CLOSE]);
+    expect(path.data).toEqual([0, -0, 10, -0, 20, -10, 20, -20]);
+  });
+
+  // THE OPTIONAL LEADING WIDTH. Present on the first stack-clearing operator only, detected by argument
+  // count rather than assumed. Getting it wrong shifts every coordinate in the glyph by one argument.
+  it('drops a leading width argument on the first stack-clearing operator', () => {
+    const withWidth = run(n(99), n(10), n(20), 21, 14).path;
+    const without = run(n(10), n(20), 21, 14).path;
+    expect(withWidth.data).toEqual(without.data);
+  });
+
+  it('does not treat a later extra argument as a width', () => {
+    // Second rmoveto: three arguments would be malformed, but the width has already been consumed, so
+    // the first two are the move and nothing is silently dropped from the coordinates.
+    const { path } = run(n(10), n(20), 21, n(5), n(5), 21, 14);
+    expect(path.data.slice(0, 2)).toEqual([10, -20]);
+    expect(path.data.slice(2, 4)).toEqual([15, -25]);
+  });
+
+  it('opens a new contour on a second move and closes the first', () => {
+    const { path } = run(n(0), n(0), 21, n(10), n(0), 5, n(50), n(50), 21, n(10), n(0), 5, 14);
+    expect(path.commands.filter((command) => command === PathCommand.MOVE_TO)).toHaveLength(2);
+    expect(path.commands.filter((command) => command === PathCommand.CLOSE)).toHaveLength(2);
+  });
+
+  // hintmask carries inline data whose length depends on the declared stem count, INCLUDING stems
+  // declared implicitly by leaving arguments on the stack. Miscounting desynchronises everything after.
+  it('skips the hintmask bytes implied by the stem count', () => {
+    // Two stems declared explicitly, then hintmask with its one mask byte, then a line.
+    const { ok, path } = run(n(0), n(0), n(10), n(10), 1, n(0), n(0), 21, 19, 0xff, n(10), n(0), 5, 14);
+    expect(ok).toBe(true);
+    expect(path.commands).toEqual([PathCommand.MOVE_TO, PathCommand.LINE_TO, PathCommand.CLOSE]);
+  });
+
+  it('counts stems declared implicitly before a hintmask', () => {
+    // Nine implicit stems need two mask bytes; reading one would desynchronise the stream.
+    const args = [
+      n(0),
+      n(0),
+      n(1),
+      n(1),
+      n(2),
+      n(2),
+      n(3),
+      n(3),
+      n(4),
+      n(4),
+      n(5),
+      n(5),
+      n(6),
+      n(6),
+      n(7),
+      n(7),
+      n(8),
+      n(8),
+    ];
+    const { ok, path } = run(n(0), n(0), 21, ...args, 19, 0xff, 0xff, n(10), n(0), 5, 14);
+    expect(ok).toBe(true);
+    expect(path.commands).toEqual([PathCommand.MOVE_TO, PathCommand.LINE_TO, PathCommand.CLOSE]);
+  });
+
+  it('calls a local subroutine and returns', () => {
+    const subr = new Uint8Array([n(10), n(0), 5, 11]);
+    // Bias for a pool of one is 107, so the stored index must be -107 to select entry 0. Pushing 0 here
+    // would select entry 107 and fail — which is the bias doing its job.
+    const main = new Uint8Array([n(0), n(0), 21, n(-107), 10, 14]);
+    const bytes = new Uint8Array(main.length + subr.length);
+    bytes.set(main);
+    bytes.set(subr, main.length);
+    const path = createPath();
+    const ok = runCffCharstring(
+      path,
+      bytes,
+      { end: main.length, start: 0 },
+      [{ end: bytes.length, start: main.length }],
+      [],
+    );
+    expect(ok).toBe(true);
+    expect(path.commands).toEqual([PathCommand.MOVE_TO, PathCommand.LINE_TO, PathCommand.CLOSE]);
+  });
+
+  it('returns false for a subroutine index the pool does not have', () => {
+    expect(run(n(0), n(0), 21, n(50), 10, 14).ok).toBe(false);
+  });
+
+  it('returns false for an unknown operator rather than guessing its arity', () => {
+    expect(run(n(0), n(0), 21, 2, 14).ok).toBe(false);
+  });
+
+  it('returns true with an empty path for a charstring that draws nothing', () => {
+    const { ok, path } = run(14);
+    expect(ok).toBe(true);
+    expect(path.commands).toEqual([]);
+  });
+
+  it('replaces the previous contents of out rather than appending', () => {
+    const buffer = new Uint8Array([n(0), n(0), 21, n(10), n(0), 5, 14]);
+    const path = createPath();
+    runCffCharstring(path, buffer, { end: buffer.length, start: 0 }, [], []);
+    const first = path.commands.length;
+    runCffCharstring(path, buffer, { end: buffer.length, start: 0 }, [], []);
+    expect(path.commands).toHaveLength(first);
+  });
+
+  it('closes an unterminated contour rather than leaving it open', () => {
+    const { ok, path } = run(n(0), n(0), 21, n(10), n(0), 5);
+    expect(ok).toBe(true);
+    expect(path.commands[path.commands.length - 1]).toBe(PathCommand.CLOSE);
+  });
+});

package/src/cffDict.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+
+import { CFF_OPERATOR_CHARSTRINGS, CFF_OPERATOR_PRIVATE, CFF_OPERATOR_ROS, readCffDict } from './cffDict';
+
+function dict(...bytes: number[]): Map<number, number[]> | null {
+  const buffer = new Uint8Array(bytes);
+  return readCffDict(buffer, 0, buffer.length);
+}
+
+describe('readCffDict', () => {
+  // Operands precede their operator, which is the reverse of most bytecode and the whole reading rule.
+  it('assigns the accumulated operands to the operator that follows them', () => {
+    expect(dict(139, 17)?.get(CFF_OPERATOR_CHARSTRINGS)).toEqual([0]);
+    expect(dict(140, 141, CFF_OPERATOR_PRIVATE)?.get(CFF_OPERATOR_PRIVATE)).toEqual([1, 2]);
+  });
+
+  it('starts each operator with a fresh operand list rather than carrying leftovers forward', () => {
+    const parsed = dict(140, 17, 141, CFF_OPERATOR_PRIVATE)!;
+    expect(parsed.get(CFF_OPERATOR_CHARSTRINGS)).toEqual([1]);
+    expect(parsed.get(CFF_OPERATOR_PRIVATE)).toEqual([2]);
+  });
+
+  it('reads the one-byte operand range around its zero point', () => {
+    expect(dict(32, 17)?.get(17)).toEqual([-107]);
+    expect(dict(246, 17)?.get(17)).toEqual([107]);
+  });
+
+  it('reads the two-byte positive and negative operand encodings', () => {
+    expect(dict(247, 0, 17)?.get(17)).toEqual([108]);
+    expect(dict(251, 0, 17)?.get(17)).toEqual([-108]);
+  });
+
+  it('reads the sized integer operands', () => {
+    expect(dict(28, 0x30, 0x39, 17)?.get(17)).toEqual([12345]);
+    expect(dict(29, 0, 1, 0, 0, 17)?.get(17)).toEqual([65536]);
+  });
+
+  it('reads a packed real operand, including its exponent form', () => {
+    // -2.25 then 0.140625e-3, in the nibble encoding, terminated by 0xf.
+    expect(dict(30, 0xe2, 0xa2, 0x5f, 17)?.get(17)).toEqual([-2.25]);
+    expect(dict(30, 0x0a, 0x14, 0x0c, 0x3f, 17)?.get(17)).toEqual([0.14e-3]);
+  });
+
+  // Byte 12 introduces a second byte; keying escaped operators apart is what keeps a CID marker
+  // distinguishable from an ordinary operator with the same low number.
+  it('keys an escaped operator apart from the unescaped one', () => {
+    const parsed = dict(139, 12, 30)!;
+    expect(parsed.has(CFF_OPERATOR_ROS)).toBe(true);
+    expect(parsed.has(30)).toBe(false);
+  });
+
+  it('returns the sentinel for a reserved operand byte, which means this is not a DICT', () => {
+    expect(dict(22, 17)).toBeNull();
+    expect(dict(31, 17)).toBeNull();
+  });
+
+  it('returns the sentinel when the stream ends mid-number rather than reading arbitrary bytes', () => {
+    expect(dict(28, 0x30)).toBeNull();
+    expect(dict(29, 0, 1)).toBeNull();
+    expect(dict(247)).toBeNull();
+    expect(dict(30, 0xe2)).toBeNull();
+  });
+
+  it('returns the sentinel when an escape byte ends the stream', () => {
+    expect(dict(139, 12)).toBeNull();
+  });
+});

package/src/cffFdSelect.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+
+import { readCffFdSelect } from './cffFdSelect';
+
+// Format 0 is one byte per glyph; format 3 is ranges with a trailing sentinel giving the final end.
+function format0(...perGlyph: number[]): Uint8Array {
+  return new Uint8Array([0, ...perGlyph]);
+}
+
+function format3(ranges: readonly (readonly [number, number])[], sentinel: number): Uint8Array {
+  const bytes = new Uint8Array(3 + ranges.length * 3 + 2);
+  const view = new DataView(bytes.buffer);
+  view.setUint8(0, 3);
+  view.setUint16(1, ranges.length);
+  ranges.forEach(([first, fd], index) => {
+    view.setUint16(3 + index * 3, first);
+    view.setUint8(5 + index * 3, fd);
+  });
+  view.setUint16(3 + ranges.length * 3, sentinel);
+  return bytes;
+}
+
+describe('readCffFdSelect', () => {
+  it('reads a byte-per-glyph mapping', () => {
+    expect([...readCffFdSelect(format0(0, 1, 1, 2), 0, 4)!]).toEqual([0, 1, 1, 2]);
+  });
+
+  it('expands ranges into a dense per-glyph map', () => {
+    // Glyphs 0-1 use FD 0, 2-4 use FD 1, and the sentinel closes the last range at 5.
+    expect([
+      ...readCffFdSelect(
+        format3(
+          [
+            [0, 0],
+            [2, 1],
+          ],
+          5,
+        ),
+        0,
+        5,
+      )!,
+    ]).toEqual([0, 0, 1, 1, 1]);
+  });
+
+  it('reads a table that does not start at byte zero', () => {
+    const inner = format0(3, 3);
+    const bytes = new Uint8Array(4 + inner.length);
+    bytes.set(inner, 4);
+    expect([...readCffFdSelect(bytes, 4, 2)!]).toEqual([3, 3]);
+  });
+
+  // A tail left unmapped would default to FD 0, which is a REAL pool belonging to a different font DICT.
+  // That is the silent wrong-pool outcome this module exists to prevent, so it is refused.
+  it('returns the sentinel when ranges do not cover every glyph, rather than defaulting the tail to FD 0', () => {
+    expect(readCffFdSelect(format3([[0, 0]], 3), 0, 5)).toBeNull();
+  });
+
+  it('returns the sentinel for a range running backwards or past the glyph count', () => {
+    expect(
+      readCffFdSelect(
+        format3(
+          [
+            [0, 0],
+            [4, 1],
+          ],
+          2,
+        ),
+        0,
+        5,
+      ),
+    ).toBeNull();
+    expect(readCffFdSelect(format3([[0, 0]], 99), 0, 5)).toBeNull();
+  });
+
+  it('returns the sentinel for a format it does not read', () => {
+    expect(readCffFdSelect(new Uint8Array([7, 0, 0]), 0, 2)).toBeNull();
+  });
+
+  it('returns the sentinel for a truncated table rather than a partial map', () => {
+    expect(readCffFdSelect(format0(0, 1), 0, 5)).toBeNull();
+    expect(readCffFdSelect(new Uint8Array([3, 0]), 0, 2)).toBeNull();
+    expect(readCffFdSelect(new Uint8Array(0), 0, 1)).toBeNull();
+  });
+});

package/src/cffIndex.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+
+import { readCffIndex } from './cffIndex';
+
+// INDEXes are built here byte by byte, like every other fixture in this package: offsets are 1-based from
+// the byte before the data block, and that off-by-one is exactly the detail a stub would paper over.
+function buildIndex(entries: readonly string[], offSize = 1): Uint8Array {
+  if (entries.length === 0) return new Uint8Array([0, 0]);
+  const payload = entries.map((entry) => new TextEncoder().encode(entry));
+  const offsets = [1];
+  for (const entry of payload) offsets.push(offsets[offsets.length - 1]! + entry.length);
+  const bytes = new Uint8Array(3 + offsets.length * offSize + offsets[offsets.length - 1]! - 1);
+  const view = new DataView(bytes.buffer);
+  view.setUint16(0, entries.length);
+  view.setUint8(2, offSize);
+  offsets.forEach((offset, index) => {
+    for (let byte = 0; byte < offSize; byte += 1) {
+      view.setUint8(3 + index * offSize + byte, (offset >> (8 * (offSize - 1 - byte))) & 0xff);
+    }
+  });
+  let cursor = 3 + offsets.length * offSize;
+  for (const entry of payload) {
+    bytes.set(entry, cursor);
+    cursor += entry.length;
+  }
+  return bytes;
+}
+
+function textOf(bytes: Uint8Array, entry: { end: number; start: number }): string {
+  return new TextDecoder().decode(bytes.subarray(entry.start, entry.end));
+}
+
+describe('readCffIndex', () => {
+  it('carves the data into one range per entry', () => {
+    const bytes = buildIndex(['alpha', 'be', 'gamma']);
+    const index = readCffIndex(bytes, 0)!;
+    expect(index.entries).toHaveLength(3);
+    expect(index.entries.map((entry) => textOf(bytes, entry))).toEqual(['alpha', 'be', 'gamma']);
+  });
+
+  it('reports the byte just past itself, so the next structure can be read without recomputing', () => {
+    const bytes = buildIndex(['alpha', 'be']);
+    expect(readCffIndex(bytes, 0)?.endOffset).toBe(bytes.byteLength);
+  });
+
+  // A font with no local subroutines relies on this being a normal answer rather than an error.
+  it('reads an empty INDEX as two bytes and no entries', () => {
+    const index = readCffIndex(new Uint8Array([0, 0, 0xff]), 0)!;
+    expect(index.entries).toEqual([]);
+    expect(index.endOffset).toBe(2);
+  });
+
+  it('reads multi-byte offsets', () => {
+    const bytes = buildIndex(['alpha', 'be'], 3);
+    expect(readCffIndex(bytes, 0)!.entries.map((entry) => textOf(bytes, entry))).toEqual(['alpha', 'be']);
+  });
+
+  it('preserves a legitimately empty entry rather than dropping it', () => {
+    const bytes = buildIndex(['a', '', 'c']);
+    const index = readCffIndex(bytes, 0)!;
+    expect(index.entries).toHaveLength(3);
+    expect(textOf(bytes, index.entries[1]!)).toBe('');
+  });
+
+  it('reads an INDEX that does not start at byte zero', () => {
+    const inner = buildIndex(['x']);
+    const bytes = new Uint8Array(4 + inner.length);
+    bytes.set(inner, 4);
+    expect(readCffIndex(bytes, 4)!.entries.map((entry) => textOf(bytes, entry))).toEqual(['x']);
+  });
+
+  it('returns the sentinel when the first offset is not 1, which means these are not its offsets', () => {
+    const bytes = buildIndex(['alpha']);
+    new DataView(bytes.buffer).setUint8(3, 2);
+    expect(readCffIndex(bytes, 0)).toBeNull();
+  });
+
+  it('returns the sentinel for offsets that run backwards', () => {
+    const bytes = buildIndex(['alpha', 'be']);
+    new DataView(bytes.buffer).setUint8(5, 1);
+    expect(readCffIndex(bytes, 0)).toBeNull();
+  });
+
+  it('returns the sentinel for an offset width the format does not define', () => {
+    const bytes = buildIndex(['alpha']);
+    new DataView(bytes.buffer).setUint8(2, 9);
+    expect(readCffIndex(bytes, 0)).toBeNull();
+  });
+
+  // A truncated INDEX yields ranges pointing at arbitrary bytes, which every consumer downstream would
+  // read as real charstrings. The sentinel is the only safe answer.
+  it('returns the sentinel for a truncated INDEX rather than ranges into arbitrary bytes', () => {
+    const bytes = buildIndex(['alpha', 'be']);
+    expect(readCffIndex(bytes.subarray(0, bytes.length - 4), 0)).toBeNull();
+    expect(readCffIndex(new Uint8Array([0]), 0)).toBeNull();
+  });
+});

package/src/cffTable.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+
+import { readCffTable } from './cffTable';
+import { createSyntheticFont } from './openTypeTestHelper';
+import { readSfntTableDirectory } from './sfntTableDirectory';
+
+function cffOf(options: Parameters<typeof createSyntheticFont>[0] = {}) {
+  const font = createSyntheticFont({ flavor: 'opentype', ...options });
+  return { font, table: readCffTable(font, readSfntTableDirectory(font)!) };
+}
+
+describe('readCffTable', () => {
+  it('reaches the charstrings through the offset the top DICT states', () => {
+    const { table } = cffOf({ charstrings: [new Uint8Array([14]), new Uint8Array([14])] });
+    expect(table?.charstrings).toHaveLength(2);
+  });
+
+  it('yields an empty subroutine pool when the font declares none, rather than failing', () => {
+    // Absent and present-but-empty are identical to the biasing arithmetic, so a caller never has to
+    // distinguish them.
+    const { table } = cffOf();
+    expect(table?.localSubrs).toEqual([]);
+    expect(table?.globalSubrs).toEqual([]);
+  });
+
+  it('returns the sentinel when the table is absent', () => {
+    const font = createSyntheticFont();
+    expect(readCffTable(font, readSfntTableDirectory(font)!)).toBeNull();
+  });
+
+  it('returns the sentinel for a truncated table rather than ranges into arbitrary bytes', () => {
+    const { font } = cffOf();
+    const directory = readSfntTableDirectory(font)!;
+    const shortened = new Map(directory.tables);
+    shortened.set('CFF ', { length: 8, offset: directory.tables.get('CFF ')!.offset });
+    expect(readCffTable(font, { ...directory, tables: shortened })).toBeNull();
+  });
+});
+
+describe('readCffTable — CID-keyed', () => {
+  // Two FDs with DIFFERENT subroutine pools. The point of the whole slab is that glyph 0 and glyph 1
+  // resolve the SAME subroutine index to DIFFERENT bytes.
+  function cidFont() {
+    return createSyntheticFont({
+      charstrings: [new Uint8Array([139, 139, 21, 32, 10, 14]), new Uint8Array([139, 139, 21, 32, 10, 14])],
+      cid: {
+        fdSelect: [0, 1],
+        pools: [[new Uint8Array([149, 139, 5, 11])], [new Uint8Array([139, 149, 5, 11])]],
+      },
+      flavor: 'opentype',
+    });
+  }
+
+  it('reads a CID font instead of refusing it', () => {
+    const font = cidFont();
+    const table = readCffTable(font, readSfntTableDirectory(font)!)!;
+    expect(table).not.toBeNull();
+    expect(table.charstrings).toHaveLength(2);
+  });
+
+  it('binds each glyph to its own pool, which is the entire reason this path exists', () => {
+    const font = cidFont();
+    const table = readCffTable(font, readSfntTableDirectory(font)!)!;
+    expect(table.localSubrsByGlyph).not.toBeNull();
+    expect(table.localSubrsByGlyph).toHaveLength(2);
+    // Different FDs, so different pools — not merely two references to one.
+    expect(table.localSubrsByGlyph![0]).not.toBe(table.localSubrsByGlyph![1]);
+  });
+
+  it('leaves the single table-wide pool empty, so a reader ignoring CID fails visibly', () => {
+    const font = cidFont();
+    expect(readCffTable(font, readSfntTableDirectory(font)!)!.localSubrs).toEqual([]);
+  });
+
+  it('refuses rather than falling back when FDSelect names an FD the FDArray does not have', () => {
+    const font = createSyntheticFont({
+      charstrings: [new Uint8Array([14])],
+      cid: { fdSelect: [5], pools: [[]] },
+      flavor: 'opentype',
+    });
+    // A fallback to pool 0 would be the wrong-pool outcome wearing a reasonable-looking default.
+    expect(readCffTable(font, readSfntTableDirectory(font)!)).toBeNull();
+  });
+});

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();
+  });
+});