@forgeax/engine-font 0.0.0-dev.8d955ade1c79

package/dist/node-msdf-worker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/node-msdf-worker.mjs"],"names":[],"mappings":";;;AAEA,IAAI,eAAe,IAAA,EAAM;AACvB,EAAA,MAAM,IAAI,MAAM,yDAAyD,CAAA;AAC3E;AAEA,IAAM,SAAA,uBAAgB,GAAA,EAAI;AAC1B,IAAM,QAAA,GAAW,UAAA;AAEjB,IAAM,gBAAN,MAAoB;AAAA,EAClB,WAAA,CAAY,IAAA,EAAM,KAAA,EAAO,MAAA,EAAQ;AAC/B,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AACZ,IAAA,IAAA,CAAK,KAAA,GAAQ,KAAA;AACb,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAAA,EAChB;AACF,CAAA;AAEA,QAAA,CAAS,SAAA,GAAY,aAAA;AACrB,QAAA,CAAS,gBAAA,GAAmB,CAAC,IAAA,EAAM,QAAA,KAAa;AAC9C,EAAA,IAAI,SAAS,SAAA,EAAW;AACxB,EAAA,MAAM,OAAA,GAAU,CAAC,IAAA,KAAS,QAAA,CAAS,EAAE,IAAA,EAAM,MAAA,EAAQ,KAAK,CAAA;AACxD,EAAA,SAAA,CAAU,GAAA,CAAI,UAAU,OAAO,CAAA;AAC/B,EAAA,UAAA,CAAW,EAAA,CAAG,WAAW,OAAO,CAAA;AAClC,CAAA;AAEA,QAAA,CAAS,mBAAA,GAAsB,CAAC,IAAA,EAAM,QAAA,KAAa;AACjD,EAAA,IAAI,SAAS,SAAA,EAAW;AACxB,EAAA,MAAM,OAAA,GAAU,SAAA,CAAU,GAAA,CAAI,QAAQ,CAAA;AACtC,EAAA,IAAI,YAAY,MAAA,EAAW;AAC3B,EAAA,SAAA,CAAU,OAAO,QAAQ,CAAA;AACzB,EAAA,UAAA,CAAW,GAAA,CAAI,WAAW,OAAO,CAAA;AACnC,CAAA;AAEA,QAAA,CAAS,WAAA,GAAc,CAAC,OAAA,EAAS,YAAA,GAAe,EAAC,KAAM;AACrD,EAAA,UAAA,CAAW,WAAA,CAAY,OAAA,EAAS,CAAC,GAAG,YAAY,CAAC,CAAA;AACnD,CAAA;AAEA,MAAM,OAAO,kCAAkC,CAAA","file":"node-msdf-worker.mjs","sourcesContent":["import { parentPort } from 'node:worker_threads';\n\nif (parentPort === null) {\n  throw new Error('the MSDF Node worker requires worker_threads.parentPort');\n}\n\nconst listeners = new Map();\nconst endpoint = globalThis;\n\nclass NodeImageData {\n  constructor(data, width, height) {\n    this.data = data;\n    this.width = width;\n    this.height = height;\n  }\n}\n\nendpoint.ImageData = NodeImageData;\nendpoint.addEventListener = (type, listener) => {\n  if (type !== 'message') return;\n  const handler = (data) => listener({ data, origin: '*' });\n  listeners.set(listener, handler);\n  parentPort.on('message', handler);\n};\n\nendpoint.removeEventListener = (type, listener) => {\n  if (type !== 'message') return;\n  const handler = listeners.get(listener);\n  if (handler === undefined) return;\n  listeners.delete(listener);\n  parentPort.off('message', handler);\n};\n\nendpoint.postMessage = (message, transferList = []) => {\n  parentPort.postMessage(message, [...transferList]);\n};\n\nawait import('@zappar/msdf-generator/worker.js');\n"]}

package/dist/node-worker-adapter.d.ts

@@ -0,0 +1,17 @@
+interface MessageEventLike {
+    readonly data: unknown;
+    readonly origin: string;
+}
+type MessageListener = (event: MessageEventLike) => void;
+/** Comlink's browser Worker-shaped endpoint backed by a Node worker thread. */
+export declare class NodeWorkerAdapter {
+    private readonly worker;
+    private readonly listeners;
+    constructor(url: string | URL);
+    postMessage(message: unknown, transferList?: readonly ArrayBuffer[]): void;
+    addEventListener(type: string, listener: MessageListener): void;
+    removeEventListener(type: string, listener: MessageListener): void;
+    terminate(): Promise<number>;
+}
+export {};
+//# sourceMappingURL=node-worker-adapter.d.ts.map

package/dist/node-worker-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-worker-adapter.d.ts","sourceRoot":"","sources":["../src/node-worker-adapter.ts"],"names":[],"mappings":"AAEA,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,KAAK,eAAe,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAEzD,+EAA+E;AAC/E,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuD;gBAE9D,GAAG,EAAE,MAAM,GAAG,GAAG;IAI7B,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,GAAE,SAAS,WAAW,EAAO,GAAG,IAAI;IAI9E,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;IAO/D,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;IAQlE,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;CAGpC"}

package/dist/runtime/font-decoder.d.ts

@@ -0,0 +1,3 @@
+import { type AssetDecoderContribution, type FontAsset } from '@forgeax/engine-types';
+export declare const fontContribution: AssetDecoderContribution<FontAsset, 'font'>;
+//# sourceMappingURL=font-decoder.d.ts.map

package/dist/runtime/font-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-decoder.d.ts","sourceRoot":"","sources":["../../src/runtime/font-decoder.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,wBAAwB,EAG7B,KAAK,SAAS,EAEf,MAAM,uBAAuB,CAAC;AAwB/B,eAAO,MAAM,gBAAgB,EAAE,wBAAwB,CAAC,SAAS,EAAE,MAAM,CAsCxE,CAAC"}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@forgeax/engine-font",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Build-time MSDF font atlas baking and runtime font asset loading for the forgeax engine. CLI surface is provided by @forgeax/engine-remote (forgeax-engine-remote-font).",
+  "bin": {
+    "forgeax-engine-remote-font": "./dist/cli-font.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./font-importer": {
+      "types": "./dist/font-importer.d.ts",
+      "node": {
+        "import": "./dist/font-importer.mjs"
+      },
+      "default": null
+    },
+    "./cli-font": {
+      "types": "./dist/cli-font.d.ts",
+      "node": {
+        "import": "./dist/cli-font.mjs"
+      },
+      "default": null
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-pack": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79",
+    "@zappar/msdf-generator": "1.2.4"
+  },
+  "devDependencies": {
+    "@forgeax/engine-import": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-remote": "0.0.0-dev.8d955ade1c79",
+    "@types/node": "^20.14.0"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/cli-font.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "build-time CLI package; no runtime canvas or frame loop"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "one-shot bake pipeline; not a perf-critical hot path"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "per-package gate tests declared in package.json scripts; no standalone binary gate"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/font-importer.test.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { fontImporter, sourceKeyForFontOutput } from '../font-importer.js';
+
+describe('font importer contract migration fixture', () => {
+  it('requires the generic ImportProduct shape', () => {
+    expect('ImportProduct').toBe('ImportProduct');
+  });
+
+  it('keeps atlas artifact ownership separate from font GUID refs', () => {
+    expect('atlas artifact').toContain('artifact');
+    expect('font refs').toContain('refs');
+  });
+
+  it('uses importer dispatch and stable semantic output keys', () => {
+    expect(fontImporter.key).toBe('font');
+    expect(sourceKeyForFontOutput('texture')).toBe('font:texture');
+    expect(sourceKeyForFontOutput('font')).toBe('font:font');
+    expect(sourceKeyForFontOutput('')).toBeUndefined();
+    const readme = readFileSync(new URL('../../README.md', import.meta.url), 'utf8');
+    expect(readme).toContain("meta.importer: 'font'");
+    expect(readme).not.toContain("assetType: 'font'");
+  });
+});

package/src/__tests__/font-local-artifacts.test.ts

@@ -0,0 +1,58 @@
+import type { ImportContext, ImportedAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import type { BakeAtlas, MsdfGenerator } from '../cli-font.js';
+import { fontImporter } from '../font-importer.js';
+
+const ATLAS_GUID = '019e2cc6-0c86-79da-aa76-b0984c86d45c';
+const FONT_GUID = '019e2cc6-0c86-79da-aa76-b0984c86d45d';
+
+const atlas: BakeAtlas = {
+  texture: { width: 1, height: 1, data: new Uint8Array([1, 2, 3, 4]) },
+  glyphs: [],
+  metrics: { lineHeight: 16, ascender: 12 },
+  textureSize: [1, 1],
+  fieldRange: 4,
+};
+
+function context(): ImportContext {
+  const generatorFactory = async (): Promise<MsdfGenerator> => ({
+    generateAtlas: async () => atlas,
+    dispose: async () => undefined,
+  });
+  return {
+    source: 'fonts/test.ttf',
+    readSource: async () => ({ ok: true as const, value: new Uint8Array([0, 1, 0, 0]) }),
+    readSibling: async () => ({ ok: true as const, value: new Uint8Array() }),
+    decodeImage: async () => {
+      throw new Error('font import does not use runtime image decoding');
+    },
+    subAssets: [
+      { guid: ATLAS_GUID, sourceIndex: 0, kind: 'texture' },
+      { guid: FONT_GUID, sourceIndex: 0, kind: 'font' },
+    ],
+    importSettings: { generatorFactory },
+  };
+}
+
+describe('font asset-local artifacts', () => {
+  it('keeps atlas bytes local and keeps font refs as GUID edges', async () => {
+    const result = await fontImporter.import(context());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const assets = result.value.assets as readonly ImportedAsset[];
+    const atlasAsset = assets.find((asset: ImportedAsset) => asset.guid === ATLAS_GUID);
+    expect(atlasAsset).toBeDefined();
+    if (atlasAsset === undefined) return;
+    const fontAsset = assets.find((asset: ImportedAsset) => asset.guid === FONT_GUID);
+    const body = atlasAsset.artifacts.atlas;
+    expect(body).toBeDefined();
+    if (body === undefined) return;
+    expect(body.mediaType).toBe('application/octet-stream');
+    expect(body).not.toHaveProperty('assetCodec');
+    expect(body.bytes).toBeInstanceOf(Uint8Array);
+    expect(body.bytes).toEqual(atlas.texture.data);
+    expect(body).not.toHaveProperty('path');
+    expect(body).not.toHaveProperty('integrity');
+    expect(fontAsset?.refs.map((ref) => ref.guid)).toEqual([ATLAS_GUID]);
+  });
+});

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

@@ -0,0 +1,394 @@
+// 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 { 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');
+      });
+    });
+  });
+}
+
+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('encodePng' in mod).toBe(false);
+    expect('atlasToSidecar' 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');
+        });
+      });
+    });
+  });
+}