@forgeax/engine-font 0.1.2

package/src/font-importer.ts

@@ -0,0 +1,254 @@
+// font-importer.ts - the build-time fontImporter (feat-20260603-asset-import-loader-injection M3 / w24).
+//
+// The `{ key: 'font', import }` Importer the @forgeax/engine-import runner
+// dispatches a `*.meta.json` with `importer: 'font'` to. It absorbs the MSDF
+// bake that previously lived only behind the `forgeax-engine-remote-font
+// bake` CLI: read the `.ttf` source -> @zappar/msdf-generator atlas ->
+// (a) one atlas `TextureAsset` ImportedAsset (the RGBA MSDF atlas, kind
+// 'texture') under the declared `kind: 'texture'` sub-asset GUID, (b) one
+// sampler ImportedAsset under the declared `kind: 'sampler'` sub-asset GUID,
+// and (c) one font glyph-metrics ImportedAsset (kind 'font') under the
+// declared `kind: 'font'` sub-asset GUID. The font carries the BMFont ->
+// FontAsset glyph map + the common block + atlas/sampler GUID refs.
+//
+// Build-time-only boundary (AC-18 / requirements callout): @zappar/msdf-generator
+// is a generator dependency that MUST stay out of the runtime bundle. The
+// runtime today statically imports ZERO @forgeax/engine-font and ZERO @zappar
+// symbols (research Finding 7); this importer keeps that invariant. fontImporter
+// is a NODE-ONLY sub-export (`@forgeax/engine-font/font-importer`,
+// `default: null` under browser conditions); the generator is dynamically
+// imported (cli-font realGeneratorFactory) so even the build-time graph only
+// pays the wasm load cost when a font is actually baked. The runtime fontLoader
+// (M1 w6) reads an already-baked atlas DDC and has no bake dependency.
+//
+// GUID import-stable iron law: produced GUIDs come from `ctx.subAssets[]`. The
+// font sidecar declares `texture`, `sampler`, and `font` sub-assets; this
+// importer maps the bake output onto those declared GUIDs and stamps nothing
+// of its own.
+//
+// `ctx.importSettings` may inject a test `generatorFactory` (an
+// `() => Promise<MsdfGenerator>`) so unit tests drive the bake with a mock
+// instead of the real wasm generator; production import calls fall through to
+// the real @zappar factory.
+
+import {
+  type FontAsset,
+  type GlyphMetric,
+  IMPORT_ERROR_HINTS,
+  type ImportContext,
+  ImportError,
+  type ImportedAsset,
+  type Importer,
+  type ImportResult,
+  type SamplerAsset,
+  type TextureAsset,
+} from '@forgeax/engine-types';
+import type { BakeAtlas, MsdfGenerator } from './cli-font.js';
+import { realGeneratorFactory } from './cli-font.js';
+
+/** Stable semantic identities for the three writable font outputs. */
+export function sourceKeyForFontOutput(kind: string): string | undefined {
+  const normalizedKind = kind.trim();
+  return normalizedKind.length === 0 ? undefined : `font:${normalizedKind}`;
+}
+
+export function fontOutputSourceKeys(): readonly string[] {
+  return ['texture', 'sampler', 'font'].map((kind) => sourceKeyForFontOutput(kind) as string);
+}
+
+const FONT_REQUIRED_KINDS = ['texture', 'sampler', 'font'] as const;
+const FONT_REQUIRED_TOPOLOGY = 'exactly one texture, one sampler, and one font subAsset';
+
+function validateRequiredFontSubAssets(ctx: ImportContext): ImportError | undefined {
+  const requiredKinds = new Set<string>(FONT_REQUIRED_KINDS);
+  const counts = new Map<string, number>();
+  for (const subAsset of ctx.subAssets) {
+    if (!requiredKinds.has(subAsset.kind)) continue;
+    counts.set(subAsset.kind, (counts.get(subAsset.kind) ?? 0) + 1);
+  }
+
+  const actual = FONT_REQUIRED_KINDS.map((kind) => `${kind}=${counts.get(kind) ?? 0}`).join(', ');
+  if (FONT_REQUIRED_KINDS.every((kind) => counts.get(kind) === 1)) return undefined;
+
+  return new ImportError({
+    code: 'source-validation-failed',
+    expected: FONT_REQUIRED_TOPOLOGY,
+    hint: IMPORT_ERROR_HINTS['source-validation-failed'],
+    detail: {
+      diagnostics: [
+        {
+          code: 'font-required-subasset-topology',
+          severity: 'error',
+          sourcePath: `${ctx.source}#subAssets`,
+          sourceRange: { start: 0, end: 0, line: 1, column: 1 },
+          rule: 'font-required-subasset-topology',
+          expected: FONT_REQUIRED_TOPOLOGY,
+          actual,
+          hint: 'Declare exactly one texture, one sampler, and one font subAsset before importing.',
+        },
+      ],
+    },
+  });
+}
+
+/** Map the @zappar atlas glyphs into the FontAsset glyph-metrics record. */
+function atlasGlyphsToMetrics(atlas: BakeAtlas): Record<number, GlyphMetric> {
+  const glyphs: Record<number, GlyphMetric> = {};
+  for (const g of atlas.glyphs) {
+    glyphs[g.unicode] = {
+      advance: g.advance,
+      bearingX: g.xoffset,
+      bearingY: g.yoffset,
+      size: { w: g.atlasSize[0], h: g.atlasSize[1] },
+      region: {
+        x: g.atlasPosition[0],
+        y: g.atlasPosition[1],
+        w: g.atlasSize[0],
+        h: g.atlasSize[1],
+      },
+    };
+  }
+  return glyphs;
+}
+
+function makeAtlasTexture(atlas: BakeAtlas): TextureAsset {
+  return {
+    kind: 'texture',
+    width: atlas.texture.width,
+    height: atlas.texture.height,
+    // MSDF atlas is linear-space RGBA8 (signed-distance channels, never gamma).
+    format: 'rgba8unorm',
+    data: atlas.texture.data,
+    colorSpace: 'linear',
+    mipmap: false,
+  };
+}
+
+function makeFontCommon(atlas: BakeAtlas): FontAsset['common'] {
+  return {
+    lineHeight: atlas.metrics.lineHeight,
+    base: atlas.metrics.ascender,
+    distanceRange: atlas.fieldRange,
+    pxRange: atlas.fieldRange,
+    atlasWidth: atlas.textureSize[0],
+    atlasHeight: atlas.textureSize[1],
+  };
+}
+
+function makeAtlasSampler(): SamplerAsset {
+  return {
+    kind: 'sampler',
+    addressModeU: 'clamp-to-edge',
+    addressModeV: 'clamp-to-edge',
+    addressModeW: 'clamp-to-edge',
+    magFilter: 'linear',
+    minFilter: 'linear',
+    mipmapFilter: 'nearest',
+  };
+}
+
+async function importFont(ctx: ImportContext): Promise<ImportResult> {
+  const topologyError = validateRequiredFontSubAssets(ctx);
+  if (topologyError !== undefined) return { ok: false, error: topologyError };
+
+  const read = await ctx.readSource();
+  if (!read.ok) {
+    return {
+      ok: false,
+      error: new ImportError({
+        code: 'source-read-failed',
+        expected: `readable source file at meta.source "${ctx.source}"`,
+        hint: IMPORT_ERROR_HINTS['source-read-failed'],
+        detail: {
+          source: ctx.source,
+          reason: read.error instanceof Error ? read.error.message : String(read.error),
+        },
+      }),
+    };
+  }
+
+  const factory =
+    (ctx.importSettings.generatorFactory as (() => Promise<MsdfGenerator>) | undefined) ??
+    realGeneratorFactory;
+  const generator = await factory();
+  let atlas: BakeAtlas;
+  try {
+    atlas = await generator.generateAtlas(read.value);
+  } finally {
+    await generator.dispose().catch(() => undefined);
+  }
+
+  const atlasSub = ctx.subAssets.find((s) => s.kind === 'texture');
+  const samplerSub = ctx.subAssets.find((s) => s.kind === 'sampler');
+  const fontSub = ctx.subAssets.find((s) => s.kind === 'font');
+  const out: ImportedAsset[] = [];
+  if (atlasSub !== undefined) {
+    out.push({
+      guid: atlasSub.guid,
+      kind: 'texture',
+      payload: makeAtlasTexture(atlas),
+      refs: [],
+      artifacts: {
+        atlas: {
+          // Pack v2's runtime texture loader consumes non-Basis artifacts as
+          // raw pixels. Keep the baked RGBA8 MSDF atlas in that form here;
+          // the CLI still emits a PNG for standalone bake output.
+          mediaType: 'application/octet-stream',
+          bytes: atlas.texture.data,
+        },
+      },
+    });
+  }
+  if (samplerSub !== undefined) {
+    out.push({
+      guid: samplerSub.guid,
+      kind: 'sampler',
+      payload: makeAtlasSampler(),
+      refs: [],
+      artifacts: {},
+    });
+  }
+  if (fontSub !== undefined) {
+    // The runtime font loader reads atlasGuid / samplerGuid / glyphs / common
+    // off the DDC payload (asset-registry loadFontAsset); the produced payload
+    // mirrors that shape. atlas Handle / sampler Handle are runtime-resolved
+    // from the GUID refs, so the build-time payload carries the GUID strings
+    // (cast through FontAsset for the ImportedAsset.payload Asset slot, same
+    // build-time POD-vs-Handle bridge the gltfImporter scene arm uses).
+    const fontPayload = {
+      kind: 'font',
+      atlasGuid: atlasSub?.guid ?? '',
+      samplerGuid: samplerSub?.guid ?? '',
+      glyphs: atlasGlyphsToMetrics(atlas),
+      common: makeFontCommon(atlas),
+    } as unknown as FontAsset;
+    out.push({
+      guid: fontSub.guid,
+      kind: 'font',
+      payload: fontPayload,
+      refs: [
+        ...(atlasSub !== undefined ? [{ guid: atlasSub.guid }] : []),
+        ...(samplerSub !== undefined ? [{ guid: samplerSub.guid }] : []),
+      ],
+      artifacts: {},
+    });
+  }
+  return { ok: true, value: { assets: out, sourceDependencies: [] } };
+}
+
+/**
+ * The font {@link Importer}. Register it into an `ImporterRegistry` so the
+ * import runner dispatches `meta.importer === 'font'` sidecars here.
+ *
+ * @example
+ * ```ts
+ * import { ImporterRegistry } from '@forgeax/engine-import';
+ * import { fontImporter } from '@forgeax/engine-font/font-importer';
+ * const importers = new ImporterRegistry();
+ * importers.register(fontImporter);
+ * ```
+ */
+export const fontImporter: Importer = {
+  key: 'font',
+  import: importFont,
+};

package/src/index.ts

@@ -0,0 +1,7 @@
+// @forgeax/engine-font - runtime-safe font asset contribution.
+//
+// Build-time baking lives behind the explicit Node-only `./cli-font` and
+// `./font-importer` subpaths. Keeping the main entry free of the CLI's
+// `node:buffer`/WASM graph prevents App bundles from pulling the producer
+// toolchain into the browser runtime.
+export { fontContribution } from './runtime/font-decoder.js';

package/src/node-msdf-worker.mjs

@@ -0,0 +1,38 @@
+import { parentPort } from 'node:worker_threads';
+
+if (parentPort === null) {
+  throw new Error('the MSDF Node worker requires worker_threads.parentPort');
+}
+
+const listeners = new Map();
+const endpoint = globalThis;
+
+class NodeImageData {
+  constructor(data, width, height) {
+    this.data = data;
+    this.width = width;
+    this.height = height;
+  }
+}
+
+endpoint.ImageData = NodeImageData;
+endpoint.addEventListener = (type, listener) => {
+  if (type !== 'message') return;
+  const handler = (data) => listener({ data, origin: '*' });
+  listeners.set(listener, handler);
+  parentPort.on('message', handler);
+};
+
+endpoint.removeEventListener = (type, listener) => {
+  if (type !== 'message') return;
+  const handler = listeners.get(listener);
+  if (handler === undefined) return;
+  listeners.delete(listener);
+  parentPort.off('message', handler);
+};
+
+endpoint.postMessage = (message, transferList = []) => {
+  parentPort.postMessage(message, [...transferList]);
+};
+
+await import('@zappar/msdf-generator/worker.js');

package/src/node-worker-adapter.ts

@@ -0,0 +1,41 @@
+import { Worker } from 'node:worker_threads';
+
+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 class NodeWorkerAdapter {
+  private readonly worker: Worker;
+  private readonly listeners = new Map<MessageListener, (data: unknown) => void>();
+
+  public constructor(url: string | URL) {
+    this.worker = new Worker(url);
+  }
+
+  public postMessage(message: unknown, transferList: readonly ArrayBuffer[] = []): void {
+    this.worker.postMessage(message, [...transferList]);
+  }
+
+  public addEventListener(type: string, listener: MessageListener): void {
+    if (type !== 'message') return;
+    const handler = (data: unknown) => listener({ data, origin: '*' });
+    this.listeners.set(listener, handler);
+    this.worker.on('message', handler);
+  }
+
+  public removeEventListener(type: string, listener: MessageListener): void {
+    if (type !== 'message') return;
+    const handler = this.listeners.get(listener);
+    if (handler === undefined) return;
+    this.listeners.delete(listener);
+    this.worker.off('message', handler);
+  }
+
+  public terminate(): Promise<number> {
+    return this.worker.terminate();
+  }
+}

package/src/runtime/font-decoder.ts

@@ -0,0 +1,70 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import {
+  type AssetDecoderContribution,
+  type AssetKind,
+  err,
+  type FontAsset,
+  ok,
+} from '@forgeax/engine-types';
+
+function parseGuid(value: unknown): FontAsset['atlas'] | undefined {
+  if (value instanceof Uint8Array && value.length === 16) return value as FontAsset['atlas'];
+  if (
+    Array.isArray(value) &&
+    value.length === 16 &&
+    value.every((item) => Number.isInteger(item) && item >= 0 && item <= 255)
+  ) {
+    return Uint8Array.from(value) as FontAsset['atlas'];
+  }
+  if (typeof value !== 'string') return undefined;
+  const parsed = AssetGuid.parse(value);
+  return parsed.ok ? parsed.value : undefined;
+}
+
+function validCommon(value: unknown): value is FontAsset['common'] {
+  if (value === null || typeof value !== 'object') return false;
+  const common = value as Record<string, unknown>;
+  return ['lineHeight', 'base', 'distanceRange', 'pxRange', 'atlasWidth', 'atlasHeight'].every(
+    (key) => typeof common[key] === 'number' && Number.isFinite(common[key]),
+  );
+}
+
+export const fontContribution: AssetDecoderContribution<FontAsset, 'font'> = {
+  kind: { kind: 'font' } as AssetKind<FontAsset, 'font'>,
+  consumer: 'GlyphTextLayout',
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload as unknown;
+      if (payload !== null && typeof payload === 'object') {
+        const source = payload as Record<string, unknown>;
+        const atlas = parseGuid(source.atlas ?? source.atlasGuid);
+        const sampler = parseGuid(source.sampler ?? source.samplerGuid);
+        if (
+          (source.kind === undefined || source.kind === 'font') &&
+          atlas !== undefined &&
+          sampler !== undefined &&
+          source.glyphs !== null &&
+          typeof source.glyphs === 'object' &&
+          validCommon(source.common)
+        ) {
+          return ok({
+            kind: 'font',
+            atlas,
+            sampler,
+            glyphs: source.glyphs as FontAsset['glyphs'],
+            common: source.common,
+            ...(source.notdef === undefined
+              ? {}
+              : { notdef: source.notdef as NonNullable<FontAsset['notdef']> }),
+          });
+        }
+      }
+      return err({
+        code: 'asset-package-invalid',
+        expected: 'a font payload with atlas and sampler references',
+        hint: 'recook the font atlas and publish its local sub-assets',
+        detail: { guid: envelope.guid, reason: 'font owner validation failed' },
+      });
+    },
+  },
+};