@forgeax/engine-font 0.1.2

package/src/__tests__/font.unit.test.ts

@@ -0,0 +1,1039 @@
+// Consolidated by feat-20260609-test-pool-startup-reduction-merge-tiny-test-files
+// biome-ignore-all lint/complexity/noUselessLoneBlockStatements: scope isolation between merged source files
+//
+// Source files (N=3):
+//   - packages/font/src/__tests__/bake-real.test.ts
+//   - packages/font/src/__tests__/font-importer.test.ts
+//   - packages/font/src/__tests__/plugin-discoverable.test.ts
+//
+// Paradigm: each block-scoped describe('<source-filename>.test.ts', ...) preserves
+// source as ancestorTitles[0]. Top-level imports merged + deduped.
+
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ImporterRegistry } from '@forgeax/engine-import';
+import type { ImportContext, ImportedAsset, ImportSubAsset } from '@forgeax/engine-types';
+import { FontError } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  type BakeAtlas,
+  bakeFont,
+  type MsdfGenerator,
+  realGeneratorFactory,
+  runCliFont,
+} from '../cli-font.js';
+import { fontImporter, fontOutputSourceKeys, sourceKeyForFontOutput } from '../font-importer.js';
+
+let tmpRoot: string;
+
+beforeEach(async () => {
+  tmpRoot = await mkdtemp(join(tmpdir(), 'forgeax-font-bake-'));
+});
+
+afterEach(async () => {
+  await rm(tmpRoot, { recursive: true, force: true });
+});
+
+const TTF_MAGIC = new Uint8Array([0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]);
+const WOFF2_MAGIC = new Uint8Array([0x77, 0x4f, 0x46, 0x32]);
+
+const REAL_TTF_CANDIDATES = [
+  '/System/Library/Fonts/Supplemental/Arial.ttf',
+  '/Library/Fonts/Arial Unicode.ttf',
+  '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf',
+  '/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf',
+];
+
+async function findRealTtf(): Promise<string | undefined> {
+  for (const p of REAL_TTF_CANDIDATES) {
+    try {
+      await stat(p);
+      return p;
+    } catch {
+      // not present -- try next
+    }
+  }
+  return undefined;
+}
+
+{
+  // ─── from bake-real.test.ts ───
+
+  describe('bake-real.test.ts', () => {
+    describe('real bake pipeline (w29)', () => {
+      it('(a) best-effort real run produces a valid atlas + sidecar (skips when Worker / TTF unavailable)', async () => {
+        const hasWorker = typeof (globalThis as { Worker?: unknown }).Worker !== 'undefined';
+        const ttfPath = await findRealTtf();
+        if (!hasWorker || ttfPath === undefined) {
+          const reason = !hasWorker ? 'zappar-worker-unavailable' : 'no-real-ttf-fixture';
+          expect(['zappar-worker-unavailable', 'no-real-ttf-fixture']).toContain(reason);
+          return;
+        }
+        const ttf = await readFile(ttfPath);
+        const ttfBytes = new Uint8Array(ttf.buffer, ttf.byteOffset, ttf.byteLength);
+        const charset = Array.from({ length: 0x7e - 0x20 + 1 }, (_, i) =>
+          String.fromCharCode(0x20 + i),
+        ).join('');
+        const factory = async (): Promise<MsdfGenerator> => {
+          const mod = (await import('@zappar/msdf-generator')) as unknown as {
+            MSDF: new () => {
+              initialize(): Promise<void>;
+              generateAtlas(opts: unknown): Promise<BakeAtlas>;
+              dispose(): Promise<void>;
+            };
+          };
+          const msdf = new mod.MSDF();
+          await msdf.initialize();
+          return {
+            generateAtlas: (bytes: Uint8Array) =>
+              msdf.generateAtlas({
+                font: bytes,
+                charset,
+                textureSize: [1024, 1024],
+                fieldRange: 4,
+                fontSize: 48,
+              }),
+            dispose: () => msdf.dispose(),
+          };
+        };
+        const localTtf = join(tmpRoot, 'Real.ttf');
+        await writeFile(localTtf, ttfBytes);
+        const result = await bakeFont(localTtf, tmpRoot, factory);
+        const png = await readFile(result.atlasPath);
+        expect(png.length).toBeGreaterThan(0);
+        expect(png[0]).toBe(0x89);
+        const sidecar = JSON.parse(await readFile(result.sidecarPath, 'utf8')) as {
+          common: { distanceRange: number; atlasWidth: number };
+          glyphs: Record<string, unknown>;
+        };
+        expect(sidecar.common.distanceRange).toBeGreaterThan(0);
+        expect(sidecar.common.atlasWidth).toBe(1024);
+        expect(Object.keys(sidecar.glyphs).length).toBeGreaterThan(0);
+      });
+
+      it('(a2) plain Node real run uses the Worker-capable host and writes artefacts', async () => {
+        const ttfPath = resolve(
+          dirname(fileURLToPath(import.meta.url)),
+          '../../../../forgeax-engine-assets/dejavu-fonts/DejaVuSansMono.ttf',
+        );
+        const result = await bakeFont(ttfPath, tmpRoot, realGeneratorFactory);
+        const png = await readFile(result.atlasPath);
+        const sidecar = JSON.parse(await readFile(result.sidecarPath, 'utf8')) as {
+          common: { distanceRange: number; atlasWidth: number; atlasHeight: number };
+          glyphs: Record<string, unknown>;
+        };
+        expect(png[0]).toBe(0x89);
+        expect(sidecar.common).toMatchObject({
+          distanceRange: 4,
+          atlasWidth: 1024,
+          atlasHeight: 1024,
+        });
+        expect(Object.keys(sidecar.glyphs).length).toBeGreaterThan(90);
+      });
+
+      it('(b) non-TTF input throws unsupported-font-format; valid TTF magic does not', async () => {
+        const woffPath = join(tmpRoot, 'X.woff2');
+        await writeFile(woffPath, WOFF2_MAGIC);
+        const neverGen = async (): Promise<MsdfGenerator> => {
+          throw new Error('generator must not be reached for a non-TTF input');
+        };
+        await expect(bakeFont(woffPath, tmpRoot, neverGen)).rejects.toMatchObject({
+          code: 'unsupported-font-format',
+          expected: 'ttf',
+        });
+        const err = await bakeFont(woffPath, tmpRoot, neverGen).catch((e) => e);
+        expect(err).toBeInstanceOf(FontError);
+
+        const ttfPath = join(tmpRoot, 'Valid.ttf');
+        await writeFile(ttfPath, TTF_MAGIC);
+        const boomGen = async (): Promise<MsdfGenerator> => ({
+          generateAtlas: async () => {
+            throw new Error('reached generator');
+          },
+          dispose: async () => undefined,
+        });
+        const passErr = await bakeFont(ttfPath, tmpRoot, boomGen).catch((e) => e);
+        expect(passErr).toBeInstanceOf(FontError);
+        expect((passErr as FontError).code).not.toBe('unsupported-font-format');
+      });
+
+      it('(c) mock generator failure yields bake-failed (no silent success)', async () => {
+        const ttfPath = join(tmpRoot, 'Valid.ttf');
+        await writeFile(ttfPath, TTF_MAGIC);
+        const failGen = async (): Promise<MsdfGenerator> => ({
+          generateAtlas: async () => {
+            throw new Error('wasm boom');
+          },
+          dispose: async () => undefined,
+        });
+        const err = await bakeFont(ttfPath, tmpRoot, failGen).catch((e) => e);
+        expect(err).toBeInstanceOf(FontError);
+        expect((err as FontError).code).toBe('bake-failed');
+        expect((err as FontError).detail?.cause).toBe('wasm boom');
+      });
+
+      it('(d) output-root refusal is structured before generator work and repairs on the same path', async () => {
+        const ttfPath = join(tmpRoot, 'Valid.ttf');
+        await writeFile(ttfPath, TTF_MAGIC);
+        const blockedParent = join(tmpRoot, 'blocked-parent');
+        const outDir = join(blockedParent, 'atlas');
+        await writeFile(blockedParent, 'not a directory');
+
+        let factoryCalls = 0;
+        let generateCalls = 0;
+        let disposeCalls = 0;
+        const factory = async (): Promise<MsdfGenerator> => {
+          factoryCalls += 1;
+          return {
+            generateAtlas: async (bytes) => {
+              generateCalls += 1;
+              expect(bytes).toEqual(TTF_MAGIC);
+              return {
+                texture: { width: 1, height: 1, data: new Uint8Array([255, 255, 255, 255]) },
+                glyphs: [],
+                metrics: { lineHeight: 1, ascender: 1 },
+                textureSize: [1, 1],
+                fieldRange: 4,
+              };
+            },
+            dispose: async () => {
+              disposeCalls += 1;
+            },
+          };
+        };
+
+        const refusal = await bakeFont(ttfPath, outDir, factory).catch((error) => error);
+        expect(refusal).toBeInstanceOf(FontError);
+        expect(refusal).toMatchObject({ code: 'bake-failed' });
+        expect((refusal as FontError).detail).toMatchObject({ path: outDir });
+        expect(typeof (refusal as FontError).detail?.cause).toBe('string');
+        expect((refusal as FontError).detail?.cause).toContain('ENOTDIR');
+        expect((refusal as FontError).hint).toContain('output');
+        expect(factoryCalls).toBe(0);
+        expect(generateCalls).toBe(0);
+        expect(disposeCalls).toBe(0);
+        await expect(stat(join(outDir, 'Valid.atlas.png'))).rejects.toMatchObject({
+          code: 'ENOTDIR',
+        });
+        await expect(stat(join(outDir, 'Valid.meta.json'))).rejects.toMatchObject({
+          code: 'ENOTDIR',
+        });
+
+        await rm(blockedParent);
+        await mkdir(blockedParent);
+        const repaired = await bakeFont(ttfPath, outDir, factory);
+        const repairedAtlas = await readFile(repaired.atlasPath);
+        const repairedSidecar = await readFile(repaired.sidecarPath, 'utf8');
+        expect(repaired).toEqual({
+          atlasPath: join(outDir, 'Valid.atlas.png'),
+          sidecarPath: join(outDir, 'Valid.meta.json'),
+        });
+        expect(factoryCalls).toBe(1);
+        expect(generateCalls).toBe(1);
+        expect(disposeCalls).toBe(1);
+
+        const repeated = await bakeFont(ttfPath, outDir, factory);
+        expect(await readFile(repeated.atlasPath)).toEqual(repairedAtlas);
+        expect(await readFile(repeated.sidecarPath, 'utf8')).toBe(repairedSidecar);
+        expect(repeated).toEqual(repaired);
+        expect(factoryCalls).toBe(2);
+        expect(generateCalls).toBe(2);
+        expect(disposeCalls).toBe(2);
+      });
+
+      it('(d2) atlas-target refusal is structured and repairs on the same path', async () => {
+        const ttfPath = join(tmpRoot, 'Valid.ttf');
+        const outDir = join(tmpRoot, 'output');
+        await writeFile(ttfPath, TTF_MAGIC);
+        await mkdir(outDir);
+        const atlasPath = join(outDir, 'Valid.atlas.png');
+        const sidecarPath = join(outDir, 'Valid.meta.json');
+        await mkdir(atlasPath);
+
+        let factoryCalls = 0;
+        let generateCalls = 0;
+        let disposeCalls = 0;
+        const factory = async (): Promise<MsdfGenerator> => {
+          factoryCalls += 1;
+          return {
+            generateAtlas: async (bytes) => {
+              generateCalls += 1;
+              expect(bytes).toEqual(TTF_MAGIC);
+              return {
+                texture: { width: 1, height: 1, data: new Uint8Array([255, 0, 255, 255]) },
+                glyphs: [],
+                metrics: { lineHeight: 1, ascender: 1 },
+                textureSize: [1, 1],
+                fieldRange: 4,
+              };
+            },
+            dispose: async () => {
+              disposeCalls += 1;
+            },
+          };
+        };
+
+        const refusal = await bakeFont(ttfPath, outDir, factory).catch((error) => error);
+        expect(refusal).toBeInstanceOf(FontError);
+        expect(refusal).toMatchObject({
+          code: 'bake-failed',
+          hint: expect.stringContaining('atlas'),
+          detail: {
+            path: atlasPath,
+            cause: expect.stringContaining('EISDIR'),
+          },
+        });
+        expect((refusal as FontError).detail?.cause).toContain(atlasPath);
+        const refusedTarget = await stat(atlasPath);
+        expect(refusedTarget.isDirectory()).toBe(true);
+        await expect(stat(sidecarPath)).rejects.toMatchObject({ code: 'ENOENT' });
+        expect(factoryCalls).toBe(1);
+        expect(generateCalls).toBe(1);
+        expect(disposeCalls).toBe(1);
+
+        await rm(atlasPath, { recursive: true, force: true });
+        const repaired = await bakeFont(ttfPath, outDir, factory);
+        const repairedAtlas = await readFile(repaired.atlasPath);
+        const repairedSidecar = await readFile(repaired.sidecarPath, 'utf8');
+        expect(repaired).toEqual({ atlasPath, sidecarPath });
+        expect(factoryCalls).toBe(2);
+        expect(generateCalls).toBe(2);
+        expect(disposeCalls).toBe(2);
+
+        const repeated = await bakeFont(ttfPath, outDir, factory);
+        expect(await readFile(repeated.atlasPath)).toEqual(repairedAtlas);
+        expect(await readFile(repeated.sidecarPath, 'utf8')).toBe(repairedSidecar);
+        expect(repeated).toEqual(repaired);
+        expect(factoryCalls).toBe(3);
+        expect(generateCalls).toBe(3);
+        expect(disposeCalls).toBe(3);
+      });
+
+      it('(d3) sidecar-target refusal is structured and repairs on the same path', async () => {
+        const ttfPath = join(tmpRoot, 'Valid.ttf');
+        const outDir = join(tmpRoot, 'output');
+        await writeFile(ttfPath, TTF_MAGIC);
+        await mkdir(outDir);
+        const atlasPath = join(outDir, 'Valid.atlas.png');
+        const sidecarPath = join(outDir, 'Valid.meta.json');
+        await mkdir(sidecarPath);
+
+        let factoryCalls = 0;
+        let generateCalls = 0;
+        let disposeCalls = 0;
+        const factory = async (): Promise<MsdfGenerator> => {
+          factoryCalls += 1;
+          return {
+            generateAtlas: async (bytes) => {
+              generateCalls += 1;
+              expect(bytes).toEqual(TTF_MAGIC);
+              return {
+                texture: { width: 1, height: 1, data: new Uint8Array([255, 64, 128, 255]) },
+                glyphs: [],
+                metrics: { lineHeight: 1, ascender: 1 },
+                textureSize: [1, 1],
+                fieldRange: 4,
+              };
+            },
+            dispose: async () => {
+              disposeCalls += 1;
+            },
+          };
+        };
+
+        const refusal = await bakeFont(ttfPath, outDir, factory).catch((error) => error);
+        expect(refusal).toBeInstanceOf(FontError);
+        expect(refusal).toMatchObject({
+          code: 'bake-failed',
+          expected: expect.stringContaining('sidecar'),
+          hint: expect.stringContaining('sidecar'),
+          detail: {
+            path: sidecarPath,
+            cause: expect.stringContaining('EISDIR'),
+          },
+        });
+        expect((refusal as FontError).code).not.toBe('EISDIR');
+        expect('atlasPath' in (refusal as object)).toBe(false);
+        const cause = (refusal as FontError).detail?.cause;
+        expect(typeof cause).toBe('string');
+        expect((cause as string).length).toBeLessThan(1024);
+        expect((await stat(sidecarPath)).isDirectory()).toBe(true);
+        const refusedAtlas = await readFile(atlasPath);
+        expect(refusedAtlas.length).toBeGreaterThan(0);
+        expect(factoryCalls).toBe(1);
+        expect(generateCalls).toBe(1);
+        expect(disposeCalls).toBe(1);
+
+        await rm(sidecarPath, { recursive: true, force: true });
+        const repaired = await bakeFont(ttfPath, outDir, factory);
+        const repairedAtlas = await readFile(repaired.atlasPath);
+        const repairedSidecar = await readFile(repaired.sidecarPath, 'utf8');
+        expect(repaired).toEqual({ atlasPath, sidecarPath });
+        expect(repairedAtlas).toEqual(refusedAtlas);
+        expect(JSON.parse(repairedSidecar)).toMatchObject({ importer: 'font' });
+        expect(factoryCalls).toBe(2);
+        expect(generateCalls).toBe(2);
+        expect(disposeCalls).toBe(2);
+
+        const repeated = await bakeFont(ttfPath, outDir, factory);
+        expect(await readFile(repeated.atlasPath)).toEqual(repairedAtlas);
+        expect(await readFile(repeated.sidecarPath, 'utf8')).toBe(repairedSidecar);
+        expect(repeated).toEqual(repaired);
+        expect(factoryCalls).toBe(3);
+        expect(generateCalls).toBe(3);
+        expect(disposeCalls).toBe(3);
+      });
+
+      it('(d4) malformed atlas textures fail before publication and repair on the same factory', async () => {
+        const ttfPath = join(tmpRoot, 'MalformedAtlas.ttf');
+        await writeFile(ttfPath, TTF_MAGIC);
+
+        const repairedAtlas: BakeAtlas = {
+          texture: { width: 2, height: 2, data: new Uint8Array(16) },
+          glyphs: [
+            {
+              unicode: 65,
+              advance: 10,
+              xoffset: 1,
+              yoffset: 2,
+              atlasPosition: [0, 0],
+              atlasSize: [1, 1],
+            },
+          ],
+          metrics: { lineHeight: 20, ascender: 16 },
+          textureSize: [2, 2],
+          fieldRange: 4,
+        };
+
+        const malformedCases: readonly [string, (atlas: BakeAtlas) => BakeAtlas][] = [
+          [
+            'non-positive-dimension',
+            (atlas) => ({
+              ...atlas,
+              texture: { ...atlas.texture, width: 0 },
+            }),
+          ],
+          [
+            'non-finite-dimension',
+            (atlas) => ({
+              ...atlas,
+              texture: { ...atlas.texture, height: Number.NaN },
+            }),
+          ],
+          [
+            'non-integer-dimension',
+            (atlas) => ({
+              ...atlas,
+              texture: { ...atlas.texture, width: 1.5 },
+            }),
+          ],
+          [
+            'rgba-length-mismatch',
+            (atlas) => ({
+              ...atlas,
+              texture: { ...atlas.texture, data: new Uint8Array(15) },
+            }),
+          ],
+          [
+            'texture-size-mismatch',
+            (atlas) => ({
+              ...atlas,
+              textureSize: [1, 2],
+            }),
+          ],
+        ];
+
+        for (const [caseName, makeMalformed] of malformedCases) {
+          const outDir = join(tmpRoot, `malformed-${caseName}`);
+          const atlasPath = join(outDir, 'MalformedAtlas.atlas.png');
+          const sidecarPath = join(outDir, 'MalformedAtlas.meta.json');
+          let returnMalformed = true;
+          let factoryCalls = 0;
+          let generateCalls = 0;
+          let disposeCalls = 0;
+          const factory = async (): Promise<MsdfGenerator> => {
+            factoryCalls += 1;
+            return {
+              generateAtlas: async (bytes) => {
+                generateCalls += 1;
+                expect(bytes).toEqual(TTF_MAGIC);
+                return returnMalformed ? makeMalformed(repairedAtlas) : repairedAtlas;
+              },
+              dispose: async () => {
+                disposeCalls += 1;
+              },
+            };
+          };
+
+          const refusal = await bakeFont(ttfPath, outDir, factory).catch((error) => error);
+          expect(refusal).toBeInstanceOf(FontError);
+          expect(refusal).toMatchObject({
+            code: 'bake-failed',
+            expected: expect.stringContaining('atlas'),
+            hint: expect.stringContaining('atlas'),
+            detail: { cause: expect.stringContaining('malformed-atlas') },
+          });
+          const cause = (refusal as FontError).detail?.cause;
+          expect(typeof cause).toBe('string');
+          expect((cause as string).length).toBeLessThan(256);
+          expect('atlasPath' in (refusal as object)).toBe(false);
+          await expect(stat(atlasPath)).rejects.toMatchObject({ code: 'ENOENT' });
+          await expect(stat(sidecarPath)).rejects.toMatchObject({ code: 'ENOENT' });
+          expect(factoryCalls).toBe(1);
+          expect(generateCalls).toBe(1);
+          expect(disposeCalls).toBe(1);
+
+          returnMalformed = false;
+          const repaired = await bakeFont(ttfPath, outDir, factory);
+          const repairedAtlasBytes = await readFile(repaired.atlasPath);
+          const repairedSidecar = await readFile(repaired.sidecarPath, 'utf8');
+          expect(repaired).toEqual({ atlasPath, sidecarPath });
+          expect(JSON.parse(repairedSidecar)).toMatchObject({
+            common: { atlasWidth: 2, atlasHeight: 2 },
+            glyphs: {
+              '65': {
+                advance: 10,
+                bearingX: 1,
+                bearingY: 2,
+                size: { w: 1, h: 1 },
+                region: { x: 0, y: 0, w: 1, h: 1 },
+              },
+            },
+          });
+          expect(factoryCalls).toBe(2);
+          expect(generateCalls).toBe(2);
+          expect(disposeCalls).toBe(2);
+
+          const repeated = await bakeFont(ttfPath, outDir, factory);
+          expect(repeated).toEqual(repaired);
+          expect(await readFile(repeated.atlasPath)).toEqual(repairedAtlasBytes);
+          expect(await readFile(repeated.sidecarPath, 'utf8')).toBe(repairedSidecar);
+          expect(factoryCalls).toBe(3);
+          expect(generateCalls).toBe(3);
+          expect(disposeCalls).toBe(3);
+        }
+      });
+
+      it('(d5) malformed glyph metrics fail before publication and repair on the same factory', async () => {
+        const ttfPath = join(tmpRoot, 'MalformedGlyphs.ttf');
+        await writeFile(ttfPath, TTF_MAGIC);
+
+        const validAtlas: BakeAtlas = {
+          texture: { width: 2, height: 2, data: new Uint8Array(16) },
+          glyphs: [
+            {
+              unicode: 65,
+              advance: 10,
+              xoffset: 1,
+              yoffset: 2,
+              atlasPosition: [0, 0],
+              atlasSize: [1, 1],
+            },
+          ],
+          metrics: { lineHeight: 20, ascender: 16 },
+          textureSize: [2, 2],
+          fieldRange: 4,
+        };
+        const baseGlyph = validAtlas.glyphs[0];
+        if (baseGlyph === undefined) {
+          throw new Error('test fixture must contain a base glyph');
+        }
+        const malformedCases: readonly [string, (atlas: BakeAtlas) => BakeAtlas][] = [
+          [
+            'non-finite-metric',
+            (atlas) => ({
+              ...atlas,
+              glyphs: [{ ...baseGlyph, advance: Number.NaN }],
+            }),
+          ],
+          [
+            'duplicate-unicode',
+            (atlas) => ({
+              ...atlas,
+              glyphs: [...atlas.glyphs, { ...baseGlyph, atlasPosition: [1, 0] }],
+            }),
+          ],
+          [
+            'out-of-atlas-region',
+            (atlas) => ({
+              ...atlas,
+              glyphs: [{ ...baseGlyph, atlasPosition: [1, 1], atlasSize: [2, 1] }],
+            }),
+          ],
+        ];
+
+        for (const [caseName, makeMalformed] of malformedCases) {
+          const outDir = join(tmpRoot, `malformed-glyph-${caseName}`);
+          const atlasPath = join(outDir, 'MalformedGlyphs.atlas.png');
+          const sidecarPath = join(outDir, 'MalformedGlyphs.meta.json');
+          let returnMalformed = true;
+          let factoryCalls = 0;
+          let generateCalls = 0;
+          let disposeCalls = 0;
+          const factory = async (): Promise<MsdfGenerator> => {
+            factoryCalls += 1;
+            return {
+              generateAtlas: async (bytes) => {
+                generateCalls += 1;
+                expect(bytes).toEqual(TTF_MAGIC);
+                return returnMalformed ? makeMalformed(validAtlas) : validAtlas;
+              },
+              dispose: async () => {
+                disposeCalls += 1;
+              },
+            };
+          };
+
+          const refusal = await bakeFont(ttfPath, outDir, factory).catch((error) => error);
+          expect(refusal).toBeInstanceOf(FontError);
+          expect(refusal).toMatchObject({
+            code: 'bake-failed',
+            expected: expect.stringContaining('glyph'),
+            hint: expect.stringContaining('glyph'),
+            detail: { cause: expect.stringContaining('malformed-glyph') },
+          });
+          const cause = (refusal as FontError).detail?.cause;
+          expect(typeof cause).toBe('string');
+          expect((cause as string).length).toBeLessThan(256);
+          expect('atlasPath' in (refusal as object)).toBe(false);
+          await expect(stat(atlasPath)).rejects.toMatchObject({ code: 'ENOENT' });
+          await expect(stat(sidecarPath)).rejects.toMatchObject({ code: 'ENOENT' });
+          expect(factoryCalls).toBe(1);
+          expect(generateCalls).toBe(1);
+          expect(disposeCalls).toBe(1);
+
+          returnMalformed = false;
+          const repaired = await bakeFont(ttfPath, outDir, factory);
+          const repairedAtlasBytes = await readFile(repaired.atlasPath);
+          const repairedSidecar = await readFile(repaired.sidecarPath, 'utf8');
+          expect(repaired).toEqual({ atlasPath, sidecarPath });
+          expect(factoryCalls).toBe(2);
+          expect(generateCalls).toBe(2);
+          expect(disposeCalls).toBe(2);
+
+          const repeated = await bakeFont(ttfPath, outDir, factory);
+          expect(repeated).toEqual(repaired);
+          expect(await readFile(repeated.atlasPath)).toEqual(repairedAtlasBytes);
+          expect(await readFile(repeated.sidecarPath, 'utf8')).toBe(repairedSidecar);
+          expect(factoryCalls).toBe(3);
+          expect(generateCalls).toBe(3);
+          expect(disposeCalls).toBe(3);
+        }
+      });
+
+      it('(d6) generator disposal rejection is structured and preserves primary failure', async () => {
+        const ttfPath = join(tmpRoot, 'GeneratorDispose.ttf');
+        await writeFile(ttfPath, TTF_MAGIC);
+
+        const validAtlas: BakeAtlas = {
+          texture: { width: 2, height: 2, data: new Uint8Array(16) },
+          glyphs: [
+            {
+              unicode: 65,
+              advance: 10,
+              xoffset: 1,
+              yoffset: 2,
+              atlasPosition: [0, 0],
+              atlasSize: [1, 1],
+            },
+          ],
+          metrics: { lineHeight: 20, ascender: 16 },
+          textureSize: [2, 2],
+          fieldRange: 4,
+        };
+        const cases: readonly [string, 'dispose' | 'primary'][] = [
+          ['dispose-rejection', 'dispose'],
+          ['primary-failure-preservation', 'primary'],
+        ];
+
+        for (const [caseName, failure] of cases) {
+          const outDir = join(tmpRoot, `generator-dispose-${caseName}`);
+          const atlasPath = join(outDir, 'GeneratorDispose.atlas.png');
+          const sidecarPath = join(outDir, 'GeneratorDispose.meta.json');
+          let fail = true;
+          let factoryCalls = 0;
+          let generateCalls = 0;
+          let disposeCalls = 0;
+          const factory = async (): Promise<MsdfGenerator> => {
+            factoryCalls += 1;
+            return {
+              generateAtlas: async (bytes) => {
+                generateCalls += 1;
+                expect(bytes).toEqual(TTF_MAGIC);
+                if (failure === 'primary' && fail) {
+                  throw new Error('primary generator failure');
+                }
+                return validAtlas;
+              },
+              dispose: async () => {
+                disposeCalls += 1;
+                if (failure === 'dispose' && fail) {
+                  throw new Error('dispose sentinel must not escape');
+                }
+                if (failure === 'primary' && fail) {
+                  throw new Error('cleanup sentinel must not replace primary');
+                }
+              },
+            };
+          };
+
+          const refusal = await bakeFont(ttfPath, outDir, factory).catch((error) => error);
+          expect(refusal).toBeInstanceOf(FontError);
+          expect(refusal).toMatchObject({
+            code: 'bake-failed',
+            expected: expect.stringContaining('generator'),
+            hint: expect.stringContaining('generator'),
+            detail: { cause: expect.any(String) },
+          });
+          const cause = (refusal as FontError).detail?.cause;
+          expect(typeof cause).toBe('string');
+          expect((cause as string).length).toBeLessThan(256);
+          if (failure === 'dispose') {
+            expect(cause).toContain('dispose');
+          } else {
+            expect(cause).toBe('primary generator failure');
+            expect(cause).not.toContain('cleanup sentinel');
+          }
+          expect('atlasPath' in (refusal as object)).toBe(false);
+          await expect(stat(atlasPath)).rejects.toMatchObject({ code: 'ENOENT' });
+          await expect(stat(sidecarPath)).rejects.toMatchObject({ code: 'ENOENT' });
+          expect(factoryCalls).toBe(1);
+          expect(generateCalls).toBe(1);
+          expect(disposeCalls).toBe(1);
+
+          fail = false;
+          const repaired = await bakeFont(ttfPath, outDir, factory);
+          const repairedAtlasBytes = await readFile(repaired.atlasPath);
+          const repairedSidecar = await readFile(repaired.sidecarPath, 'utf8');
+          expect(repaired).toEqual({ atlasPath, sidecarPath });
+          expect(factoryCalls).toBe(2);
+          expect(generateCalls).toBe(2);
+          expect(disposeCalls).toBe(2);
+
+          const repeated = await bakeFont(ttfPath, outDir, factory);
+          expect(repeated).toEqual(repaired);
+          expect(await readFile(repeated.atlasPath)).toEqual(repairedAtlasBytes);
+          expect(await readFile(repeated.sidecarPath, 'utf8')).toBe(repairedSidecar);
+          expect(factoryCalls).toBe(3);
+          expect(generateCalls).toBe(3);
+          expect(disposeCalls).toBe(3);
+        }
+      });
+
+      it('(e) unreadable source yields structured bake-failed before generator or output work', async () => {
+        const ttfPath = join(tmpRoot, 'missing-source.ttf');
+        const outDir = join(tmpRoot, 'untouched-output');
+        let factoryCalls = 0;
+        let generateCalls = 0;
+        let disposeCalls = 0;
+        const factory = async (): Promise<MsdfGenerator> => {
+          factoryCalls += 1;
+          return {
+            generateAtlas: async () => {
+              generateCalls += 1;
+              return {} as BakeAtlas;
+            },
+            dispose: async () => {
+              disposeCalls += 1;
+            },
+          };
+        };
+
+        const error = await bakeFont(ttfPath, outDir, factory).catch((e) => e);
+        expect(error).toBeInstanceOf(FontError);
+        expect(error).toMatchObject({
+          code: 'bake-failed',
+          expected: expect.stringContaining('readable'),
+          hint: expect.stringContaining('source'),
+        });
+        expect((error as FontError).detail).toMatchObject({
+          path: ttfPath,
+          cause: expect.stringContaining('ENOENT'),
+        });
+        expect(factoryCalls).toBe(0);
+        expect(generateCalls).toBe(0);
+        expect(disposeCalls).toBe(0);
+        await expect(stat(outDir)).rejects.toMatchObject({ code: 'ENOENT' });
+      });
+
+      it('(e) repairs the same source path and repeats deterministic output with balanced disposal', async () => {
+        const ttfPath = join(tmpRoot, 'repair-in-place.ttf');
+        const outDir = join(tmpRoot, 'repair-output');
+        let factoryCalls = 0;
+        let generateCalls = 0;
+        let disposeCalls = 0;
+        const factory = async (): Promise<MsdfGenerator> => {
+          factoryCalls += 1;
+          return {
+            generateAtlas: async (bytes) => {
+              generateCalls += 1;
+              expect(bytes.slice(0, TTF_MAGIC.length)).toEqual(TTF_MAGIC);
+              return {
+                texture: { width: 2, height: 2, data: new Uint8Array(16) },
+                glyphs: [
+                  {
+                    unicode: 65,
+                    advance: 10,
+                    xoffset: 1,
+                    yoffset: 2,
+                    atlasPosition: [0, 0],
+                    atlasSize: [1, 1],
+                  },
+                ],
+                metrics: { lineHeight: 20, ascender: 16 },
+                textureSize: [2, 2],
+                fieldRange: 4,
+              };
+            },
+            dispose: async () => {
+              disposeCalls += 1;
+            },
+          };
+        };
+
+        const missing = await bakeFont(ttfPath, outDir, factory).catch((e) => e);
+        expect(missing).toBeInstanceOf(FontError);
+        expect((missing as FontError).code).toBe('bake-failed');
+        expect(factoryCalls).toBe(0);
+        expect(generateCalls).toBe(0);
+        expect(disposeCalls).toBe(0);
+
+        await writeFile(ttfPath, TTF_MAGIC);
+        const first = await bakeFont(ttfPath, outDir, factory);
+        const firstPng = await readFile(first.atlasPath);
+        const firstSidecar = await readFile(first.sidecarPath, 'utf8');
+
+        const second = await bakeFont(ttfPath, outDir, factory);
+        const secondPng = await readFile(second.atlasPath);
+        const secondSidecar = await readFile(second.sidecarPath, 'utf8');
+
+        expect(first).toEqual({
+          atlasPath: join(outDir, 'repair-in-place.atlas.png'),
+          sidecarPath: join(outDir, 'repair-in-place.meta.json'),
+        });
+        expect(second).toEqual(first);
+        expect(secondPng).toEqual(firstPng);
+        expect(secondSidecar).toBe(firstSidecar);
+        expect(factoryCalls).toBe(2);
+        expect(generateCalls).toBe(2);
+        expect(disposeCalls).toBe(2);
+      });
+    });
+  });
+}
+
+describe('font producer sourceKey', () => {
+  it('assigns unique stable keys to atlas, sampler, and font outputs', () => {
+    const keys = fontOutputSourceKeys();
+    expect(keys).toEqual(['font:texture', 'font:sampler', 'font:font']);
+    expect(new Set(keys).size).toBe(keys.length);
+    expect(sourceKeyForFontOutput('texture')).toBe('font:texture');
+    expect(sourceKeyForFontOutput('')).toBeUndefined();
+  });
+});
+
+describe('font package root surface', () => {
+  it('keeps the version authority in package metadata, not a root mirror', async () => {
+    const mod = await import('../index.js');
+    expect('FONT_PACKAGE_VERSION' in mod).toBe(false);
+    expect(typeof mod.fontContribution).toBe('object');
+    expect('bakeFont' in mod).toBe(false);
+    expect('runCliFont' in mod).toBe(false);
+  });
+});
+
+{
+  // ─── from font-importer.test.ts ───
+
+  const ATLAS_GUID = '019e3969-1d43-7610-8810-e80dbd491d90';
+  const FONT_GUID = '019e3969-1d43-7610-8810-e80dbd491d91';
+  const SAMPLER_GUID = '019e3969-1d43-7610-8810-e80dbd491d92';
+
+  function mockAtlas(): BakeAtlas {
+    return {
+      texture: { width: 16, height: 16, data: new Uint8Array(16 * 16 * 4) },
+      glyphs: [
+        {
+          unicode: 65,
+          advance: 10,
+          xoffset: 1,
+          yoffset: 2,
+          atlasPosition: [0, 0],
+          atlasSize: [8, 8],
+        },
+      ],
+      metrics: { lineHeight: 20, ascender: 16 },
+      textureSize: [16, 16],
+      fieldRange: 4,
+    };
+  }
+
+  function mockGeneratorFactory(): () => Promise<MsdfGenerator> {
+    return async () => ({
+      generateAtlas: async () => mockAtlas(),
+      dispose: async () => undefined,
+    });
+  }
+
+  function makeCtx(subAssets: readonly ImportSubAsset[]): ImportContext {
+    return {
+      source: 'roboto.ttf',
+      readSource: async () => ({ ok: true, value: new Uint8Array([0x00, 0x01, 0x00, 0x00]) }),
+      readSibling: async () => ({ ok: true, value: new Uint8Array() }),
+      decodeImage: async () => {
+        throw new Error('decodeImage not used by fontImporter');
+      },
+      subAssets,
+      importSettings: { generatorFactory: mockGeneratorFactory() },
+    };
+  }
+
+  describe('font-importer.test.ts', () => {
+    describe('fontImporter dispatch (AC-18)', () => {
+      it('an ImporterRegistry resolves meta.importer="font" to fontImporter', () => {
+        const registry = new ImporterRegistry();
+        registry.register(fontImporter);
+        const resolved = registry.get('font');
+        expect(resolved).toBe(fontImporter);
+        expect(resolved?.key).toBe('font');
+        expect(typeof resolved?.import).toBe('function');
+      });
+    });
+
+    describe('fontImporter bake mapping (AC-18)', () => {
+      it('maps the mock atlas onto declared atlas, sampler, and font sub-asset GUIDs', async () => {
+        const ctx = makeCtx([
+          { guid: ATLAS_GUID, sourceIndex: 0, kind: 'texture' },
+          { guid: SAMPLER_GUID, sourceIndex: 1, kind: 'sampler' },
+          { guid: FONT_GUID, sourceIndex: 0, kind: 'font' },
+        ]);
+        const result = await fontImporter.import(ctx);
+        expect(result.ok).toBe(true);
+        const produced: readonly ImportedAsset[] = result.ok ? result.value.assets : [];
+
+        const atlas = produced.find((a) => a.guid === ATLAS_GUID);
+        expect(atlas?.kind).toBe('texture');
+
+        const font = produced.find((a) => a.guid === FONT_GUID);
+        expect(font?.kind).toBe('font');
+        expect(font?.refs.map((r) => r.guid)).toEqual([ATLAS_GUID, SAMPLER_GUID]);
+        expect(font?.payload).toMatchObject({
+          atlasGuid: ATLAS_GUID,
+          samplerGuid: SAMPLER_GUID,
+        });
+
+        expect(produced).toContainEqual({
+          guid: SAMPLER_GUID,
+          kind: 'sampler',
+          payload: {
+            kind: 'sampler',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge',
+            addressModeW: 'clamp-to-edge',
+            magFilter: 'linear',
+            minFilter: 'linear',
+            mipmapFilter: 'nearest',
+          },
+          refs: [],
+          artifacts: {},
+        });
+      });
+
+      // P1: fontImporter atlas lookup uses s.kind === 'texture' instead of 'image'.
+      it('P1: uses s.kind === "texture" to find atlas sub-asset', async () => {
+        const ctx = makeCtx([
+          { guid: ATLAS_GUID, sourceIndex: 0, kind: 'texture' },
+          { guid: SAMPLER_GUID, sourceIndex: 1, kind: 'sampler' },
+          { guid: FONT_GUID, sourceIndex: 0, kind: 'font' },
+        ]);
+        const result = await fontImporter.import(ctx);
+        expect(result.ok).toBe(true);
+        const produced: readonly ImportedAsset[] = result.ok ? result.value.assets : [];
+
+        const atlas = produced.find((a) => a.guid === ATLAS_GUID);
+        expect(atlas?.kind).toBe('texture');
+
+        const font = produced.find((a) => a.guid === FONT_GUID);
+        expect(font?.kind).toBe('font');
+        expect(font?.refs.map((r) => r.guid)).toEqual([ATLAS_GUID, SAMPLER_GUID]);
+      });
+    });
+  });
+}
+
+{
+  // ─── from plugin-discoverable.test.ts ───
+
+  const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+  describe('plugin-discoverable.test.ts', () => {
+    describe('plugin-discoverable (forgeax-engine-remote-font)', () => {
+      describe('bake subcommand routing (a)', () => {
+        it('--help on root exits 0 and prints usage', async () => {
+          const code = await runCliFont(['--help']);
+          expect(code).toBe(0);
+        });
+
+        it('bake --help exits 0 and prints bake usage', async () => {
+          const code = await runCliFont(['bake', '--help']);
+          expect(code).toBe(0);
+        });
+
+        it('bake with two positionals routes to the real bake (exits 1 on a missing source)', async () => {
+          const code = await runCliFont(['bake', 'font.ttf', 'out/']);
+          expect(code).toBe(1);
+        });
+
+        it('unknown subcommand exits 1', async () => {
+          const code = await runCliFont(['unknown-cmd']);
+          expect(code).toBe(1);
+        });
+
+        it('no subcommand with empty argv exits 0 (prints help)', async () => {
+          const code = await runCliFont([]);
+          expect(code).toBe(0);
+        });
+      });
+
+      describe('plugin bin naming contract (b)', () => {
+        it('package.json bin field is forgeax-engine-remote-font -> ./dist/cli-font.mjs', async () => {
+          const pkgPath = join(PKG_DIR, 'package.json');
+          const raw = await readFile(pkgPath, 'utf-8');
+          const pkg = JSON.parse(raw) as Record<string, unknown>;
+          const bin = pkg.bin as Record<string, string>;
+          expect(bin).toBeDefined();
+          expect(typeof bin).toBe('object');
+          expect(bin['forgeax-engine-remote-font']).toBe('./dist/cli-font.mjs');
+        });
+
+        it('bin name starts with forgeax-engine-remote- (PLUGIN_PREFIX contract)', async () => {
+          const pkgPath = join(PKG_DIR, 'package.json');
+          const raw = await readFile(pkgPath, 'utf-8');
+          const pkg = JSON.parse(raw) as Record<string, unknown>;
+          const bin = pkg.bin as Record<string, string>;
+          const binNames = Object.keys(bin);
+          expect(binNames.length).toBe(1);
+          expect(binNames[0]).toBe('forgeax-engine-remote-font');
+        });
+      });
+
+      describe('package.json bin contract (c)', () => {
+        it('package name is @forgeax/engine-font', async () => {
+          const pkgPath = join(PKG_DIR, 'package.json');
+          const raw = await readFile(pkgPath, 'utf-8');
+          const pkg = JSON.parse(raw) as Record<string, unknown>;
+          expect(pkg.name).toBe('@forgeax/engine-font');
+        });
+
+        it('package exports ./dist/index.mjs as main', async () => {
+          const pkgPath = join(PKG_DIR, 'package.json');
+          const raw = await readFile(pkgPath, 'utf-8');
+          const pkg = JSON.parse(raw) as Record<string, unknown>;
+          expect(pkg.main).toBe('./dist/index.mjs');
+        });
+      });
+    });
+  });
+}