@forgeax/engine-graphics-extras 0.0.0-dev.8d955ade1c79

package/dist/video-player.d.ts

@@ -0,0 +1,23 @@
+/**
+ * VideoPlayer — attaches video play state to an entity.
+ *
+ * Fields:
+ *   - `clip: shared<VideoAsset>` — handle to the VideoAsset describing the
+ *     source URL (mirrors `AudioSource.clip`). Resolved into an
+ *     HTMLVideoElement at frame time via the host `VideoElementProvider`
+ *     (the engine never decodes video bytes — D-1).
+ *   - `playing: bool` — whether the clip advances this frame (default false).
+ *   - `loop: bool` — whether the clip restarts at end (default false).
+ *   - `currentTime: f32` — playback head in seconds (default 0).
+ *
+ * Multiple entities may reference the same `clip` GUID with distinct
+ * play state — each entity's playing / loop / currentTime occupy independent
+ * archetype column slots (AC-05).
+ */
+export declare const VideoPlayer: import("@forgeax/engine-ecs").Component<"VideoPlayer", {
+    readonly clip: "shared<VideoAsset>";
+    readonly playing: "bool";
+    readonly loop: "bool";
+    readonly currentTime: "f32";
+}>;
+//# sourceMappingURL=video-player.d.ts.map

package/dist/video-player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-player.d.ts","sourceRoot":"","sources":["../src/video-player.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW;;;;;EAOtB,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@forgeax/engine-graphics-extras",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Pure-logic graphics-adjacent modules -- text glyph layout + mesh bake, tilemap bit encoding, and video playback -- for forgeax-engine (Tier 2.3 -- extracted from @forgeax/engine-runtime).",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-geometry": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "pure-logic glyph/tilemap/video modules, no runtime canvas; fps reported by hello-* apps that consume them"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "glyph layout + mesh bake run at text-change time, tile-bit codec is O(1) per cell; no per-frame hot path warranting a CI micro-benchmark"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; smoke gate covered by tilemap-object-layer / video-texture / text hello-* apps that consume these modules"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; graphics-extras cluster extracted from runtime in feat-20260705-runtime-tier2-decomposition"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/tile-bits.test.ts

@@ -0,0 +1,88 @@
+// tile-bits.test - encodeTileBits / decodeTileBits round-trip + boundary tests
+// (feat-20260608 M0 baseline rebuild).
+//
+// Tile id encoding (Tiled .tmj wire format compatibility, feat-20260604 D-2):
+//   - low 28 bits: tileId (0..0x0FFFFFFF).
+//   - high 4 bits, MSB -> LSB: flipHorizontal, flipVertical, flipDiagonal,
+//     flipHex120 (the latter is the Tiled hex 120deg flip slot; preserved for
+//     wire fidelity even though M0 does not consume it).
+//   - tileId === 0 means "empty cell" downstream in TileLayer.tiles (sentinel).
+//
+// Anchors: requirements integration points (engine-runtime); plan-tasks m0-t3.
+
+import { describe, expect, it } from 'vitest';
+import { decodeTileBits, encodeTileBits } from '../tile-bits';
+
+const FLIP_VARIANTS: ReadonlyArray<readonly [boolean, boolean, boolean, boolean]> = [
+  [false, false, false, false],
+  [true, false, false, false],
+  [false, true, false, false],
+  [false, false, true, false],
+  [false, false, false, true],
+  [true, true, false, false],
+  [true, false, true, false],
+  [true, true, true, true],
+];
+
+const TILE_ID_BOUNDARIES: readonly number[] = [0, 1, 0x0fffffff - 1, 0x0fffffff];
+
+describe('encodeTileBits / decodeTileBits round-trip (M0 baseline)', () => {
+  for (const tileId of TILE_ID_BOUNDARIES) {
+    for (const [flipH, flipV, flipDiagonal, flipHex120] of FLIP_VARIANTS) {
+      it(`tileId=${tileId} flipH=${flipH} flipV=${flipV} flipD=${flipDiagonal} flipHex120=${flipHex120}`, () => {
+        const packed = encodeTileBits(tileId, flipH, flipV, flipDiagonal, flipHex120);
+        const decoded = decodeTileBits(packed);
+        expect(decoded.tileId).toBe(tileId);
+        expect(decoded.flipH).toBe(flipH);
+        expect(decoded.flipV).toBe(flipV);
+        expect(decoded.flipDiagonal).toBe(flipDiagonal);
+        expect(decoded.flipHex120).toBe(flipHex120);
+      });
+    }
+  }
+});
+
+describe('encodeTileBits — high-bit wire layout (MSB H / V / D / Hex120)', () => {
+  it('flipH sets bit 31 (MSB)', () => {
+    const packed = encodeTileBits(0, true, false, false, false);
+    expect(packed >>> 31).toBe(1);
+    expect((packed >>> 30) & 0x1).toBe(0);
+  });
+
+  it('flipV sets bit 30', () => {
+    const packed = encodeTileBits(0, false, true, false, false);
+    expect((packed >>> 31) & 0x1).toBe(0);
+    expect((packed >>> 30) & 0x1).toBe(1);
+    expect((packed >>> 29) & 0x1).toBe(0);
+  });
+
+  it('flipDiagonal sets bit 29', () => {
+    const packed = encodeTileBits(0, false, false, true, false);
+    expect((packed >>> 29) & 0x1).toBe(1);
+    expect((packed >>> 28) & 0x1).toBe(0);
+  });
+
+  it('flipHex120 sets bit 28', () => {
+    const packed = encodeTileBits(0, false, false, false, true);
+    expect((packed >>> 28) & 0x1).toBe(1);
+  });
+
+  it('tileId fits in the low 28 bits', () => {
+    const packed = encodeTileBits(0x0fffffff, false, false, false, false);
+    expect(packed >>> 0).toBe(0x0fffffff);
+  });
+});
+
+describe('encodeTileBits — overflow RangeError (charter P3)', () => {
+  it('tileId === 0x10000000 throws RangeError', () => {
+    expect(() => encodeTileBits(0x10000000, false, false, false, false)).toThrow(RangeError);
+  });
+
+  it('tileId < 0 throws RangeError', () => {
+    expect(() => encodeTileBits(-1, false, false, false, false)).toThrow(RangeError);
+  });
+
+  it('non-integer tileId throws RangeError', () => {
+    expect(() => encodeTileBits(1.5, false, false, false, false)).toThrow(RangeError);
+  });
+});

package/src/__tests__/video-capability-backend-kind-owner.test-d.ts

@@ -0,0 +1,7 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { expectTypeOf } from 'vitest';
+import type { VideoCapabilityDevice } from '../video-player-system';
+
+expectTypeOf<VideoCapabilityDevice['caps']['backendKind']>().toEqualTypeOf<
+  RhiCaps['backendKind']
+>();

package/src/__tests__/video-capability-probe.unit.test.ts

@@ -0,0 +1,130 @@
+// feat-20260623-world-space-video-asset M4 / w17 — AC-09 capability probe.
+//
+// AC-09 / D-2: the high-perf GPUExternalTexture upload path is left in place as
+// an EXPLICIT, grep-able capability-probe branch (not a TODO comment); the
+// general copyExternalImageToTexture path is the one actually wired (w16). This
+// test pins the probe's truth table + the source-level guarantee that the
+// reserved hook is a real code branch keyed on backendKind +
+// importExternalTexture presence.
+//
+// OOS-5: the high-perf upload body is intentionally NOT implemented; the probe
+// returns false for every device the engine produces today (no RHI exposes
+// `importExternalTexture`). The probe flips on automatically the day a future
+// feat adds that entry point on a WebGPU backend.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it, vi } from 'vitest';
+import { videoLoader } from '../video-loader';
+import { probeVideoHighPerfUpload, type VideoCapabilityDevice } from '../video-player-system';
+
+const SYS_SRC = fileURLToPath(new URL('../video-player-system.ts', import.meta.url));
+
+describe('AC-09 — probeVideoHighPerfUpload truth table (M4 / w17)', () => {
+  it('rejects a malformed durable URL descriptor without fetching', () => {
+    expect(
+      videoLoader.load({ kind: 'video', url: 'not a url' }, undefined, {} as never),
+    ).toBeUndefined();
+  });
+
+  it.each([
+    ['/cutscene.webm', '/cutscene.webm'],
+    ['cutscene.webm', 'cutscene.webm'],
+    ['http://cdn.example/video.mp4', 'http://cdn.example/video.mp4'],
+    ['https://cdn.example/video.mp4', 'https://cdn.example/video.mp4'],
+  ] as const)('accepts browser-resolvable URL %s without normalizing it', (input, output) => {
+    expect(videoLoader.load({ kind: 'video', url: input }, undefined, {} as never)).toEqual({
+      kind: 'video',
+      url: output,
+    });
+  });
+
+  it('returns a valid URL descriptor without invoking network fetch', () => {
+    const fetch = vi.fn(() => Promise.reject(new Error('video Cook must not fetch')));
+    vi.stubGlobal('fetch', fetch);
+    try {
+      expect(
+        videoLoader.load(
+          { kind: 'video', url: 'https://cdn.example/video.mp4' },
+          undefined,
+          {} as never,
+        ),
+      ).toEqual({ kind: 'video', url: 'https://cdn.example/video.mp4' });
+      expect(fetch).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it.each([
+    'javascript:alert(1)',
+    'data:video/webm;base64,AAAA',
+    'file:///tmp/cutscene.webm',
+    '//cdn.example/cutscene.webm',
+    'cut\nscene.webm',
+    '',
+    '   ',
+  ])('rejects unsafe or empty URL %j', (url) => {
+    expect(videoLoader.load({ kind: 'video', url }, undefined, {} as never)).toBeUndefined();
+  });
+
+  it.each([undefined, null, 42, {}, []])('rejects non-string URL %j', (url) => {
+    expect(videoLoader.load({ kind: 'video', url }, undefined, {} as never)).toBeUndefined();
+  });
+
+  it('keeps descriptor loading independent from the optional GPU capability', () => {
+    expect(probeVideoHighPerfUpload(undefined)).toBe(false);
+    expect(
+      videoLoader.load(
+        { kind: 'video', url: 'https://cdn.example/cutscene.webm' },
+        undefined,
+        {} as never,
+      ),
+    ).toEqual({ kind: 'video', url: 'https://cdn.example/cutscene.webm' });
+  });
+
+  it('returns false when no device is wired', () => {
+    expect(probeVideoHighPerfUpload(undefined)).toBe(false);
+  });
+
+  it('returns false on a WebGPU backend without importExternalTexture (today, OOS-5)', () => {
+    const device: VideoCapabilityDevice = { caps: { backendKind: 'webgpu' } };
+    expect(probeVideoHighPerfUpload(device)).toBe(false);
+  });
+
+  it('returns false on non-WebGPU backends even if importExternalTexture existed', () => {
+    const native: VideoCapabilityDevice = {
+      caps: { backendKind: 'wgpu-native' },
+      importExternalTexture: () => undefined,
+    };
+    const webgl2: VideoCapabilityDevice = {
+      caps: { backendKind: 'wgpu-webgl2' },
+      importExternalTexture: () => undefined,
+    };
+    expect(probeVideoHighPerfUpload(native)).toBe(false);
+    expect(probeVideoHighPerfUpload(webgl2)).toBe(false);
+  });
+
+  it('returns true ONLY when a WebGPU backend exposes importExternalTexture (future hook)', () => {
+    // Simulates the day a future feat lands the RHI entry point. Proves the
+    // reserved branch is live (not dead code) and flips on without touching the
+    // call sites — the AC-09 "two paths left in place" guarantee.
+    const future: VideoCapabilityDevice = {
+      caps: { backendKind: 'webgpu' },
+      importExternalTexture: () => undefined,
+    };
+    expect(probeVideoHighPerfUpload(future)).toBe(true);
+  });
+});
+
+describe('AC-09 — reserved high-perf hook is an explicit code branch (M4 / w17)', () => {
+  it('the probe source references GPUExternalTexture import as a real condition, not a comment', () => {
+    const src = readFileSync(SYS_SRC, 'utf8');
+    const stripped = src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+    // Executable code (comments stripped) must test importExternalTexture
+    // presence and gate on the WebGPU backend — the grep-able two-path boundary.
+    expect(stripped.includes('importExternalTexture')).toBe(true);
+    expect(stripped.includes('backendKind')).toBe(true);
+  });
+});

package/src/__tests__/video-player-component.unit.test.ts

@@ -0,0 +1,73 @@
+// feat-20260623-world-space-video-asset M3 / w6 — AC-04: VideoPlayer ECS
+// component registration + mount + read-back.
+//
+// AC-04 (requirements.md:66): a new `VideoPlayer` component must register
+// through `defineComponent`, mount on a spawned entity, and read back its
+// field values via `world.get`. The reference field `clip` must be a handle
+// type (NOT a bare GUID string); the field set must include at least
+// playing / loop / currentTime.
+//
+// Decision anchors:
+//   - plan-strategy D-4 (clip: Handle<'VideoAsset','shared'>, brand string
+//     'VideoAsset' aligns with AudioSource.clip: Handle<'AudioClipAsset',
+//     'shared'>).
+//   - research Finding 5 (ECS schema vocab is closed — VideoPlayer fields use
+//     only shared<T> / bool / f32, no opaque/object field type).
+//   - charter P4 (consistent abstraction: same defineComponent pattern as
+//     AudioSource / Transform / Camera).
+
+import { World } from '@forgeax/engine-ecs';
+import type { Handle } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+import { VideoPlayer } from '../video-player';
+
+describe('AC-04 — VideoPlayer component registration + mount + read-back', () => {
+  it('VideoPlayer is a schema token owned by the importing package', () => {
+    expect(VideoPlayer.name).toBe('VideoPlayer');
+  });
+
+  it('spawn entity with VideoPlayer + read back clip/playing/loop/currentTime', () => {
+    const world = new World();
+    const clip: Handle<'VideoAsset', 'shared'> = toShared<'VideoAsset'>(42);
+
+    const e = world
+      .spawn({
+        component: VideoPlayer,
+        data: { clip, playing: true, loop: true, currentTime: 3.5 },
+      })
+      .unwrap();
+
+    const r = world.get(e, VideoPlayer).unwrap();
+    // clip is the raw u32 carried inside the Handle brand (43 in handle terms).
+    expect(r.clip).toBe(42);
+    expect(r.playing).toBe(true);
+    expect(r.loop).toBe(true);
+    expect(r.currentTime).toBe(3.5);
+  });
+
+  it('clip is a handle type (numeric u32), not a bare GUID string', () => {
+    const world = new World();
+    const clip: Handle<'VideoAsset', 'shared'> = toShared<'VideoAsset'>(7);
+
+    const e = world.spawn({ component: VideoPlayer, data: { clip } }).unwrap();
+
+    const r = world.get(e, VideoPlayer).unwrap();
+    // AC-04 red line: the reference field is a handle (number), never a GUID
+    // string. A bare GUID string would fail the typeof check below.
+    expect(typeof r.clip).toBe('number');
+    expect(r.clip).toBe(7);
+  });
+
+  it('playing/loop/currentTime default to false/false/0 when omitted at spawn', () => {
+    const world = new World();
+    const clip: Handle<'VideoAsset', 'shared'> = toShared<'VideoAsset'>(1);
+
+    const e = world.spawn({ component: VideoPlayer, data: { clip } }).unwrap();
+    const r = world.get(e, VideoPlayer).unwrap();
+    expect(r.playing).toBe(false);
+    expect(r.loop).toBe(false);
+    expect(r.currentTime).toBe(0);
+  });
+});

package/src/__tests__/video-player-multi-entity.unit.test.ts

@@ -0,0 +1,75 @@
+// feat-20260623-world-space-video-asset M3 / w8 — AC-05: multiple entities
+// share one VideoAsset GUID with independent play state.
+//
+// AC-05 (requirements.md:67): two entities referencing the SAME VideoAsset
+// GUID, each with its own VideoPlayer, may hold different loop / currentTime
+// without crosstalk. Per-entity playing / loop / currentTime occupy
+// independent archetype column slots (research Finding 6 — AudioSource already
+// proves this pattern).
+//
+// Decision anchors:
+//   - requirements AC-05 (same GUID, different play state, no crosstalk).
+//   - research Finding 6 (ECS archetype columns isolate per-entity fields).
+
+import { World } from '@forgeax/engine-ecs';
+import type { Handle } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+import { VideoPlayer } from '../video-player';
+
+describe('AC-05 — multi-entity VideoPlayer independent play state', () => {
+  it('two entities share one VideoAsset GUID with distinct loop/currentTime', () => {
+    const world = new World();
+    // Same VideoAsset handle (one GUID) referenced by both entities.
+    const clip: Handle<'VideoAsset', 'shared'> = toShared<'VideoAsset'>(99);
+
+    const a = world
+      .spawn({
+        component: VideoPlayer,
+        data: { clip, playing: true, loop: true, currentTime: 5 },
+      })
+      .unwrap();
+    const b = world
+      .spawn({
+        component: VideoPlayer,
+        data: { clip, playing: false, loop: false, currentTime: 10 },
+      })
+      .unwrap();
+
+    const ra = world.get(a, VideoPlayer).unwrap();
+    const rb = world.get(b, VideoPlayer).unwrap();
+
+    // Both reference the identical clip GUID.
+    expect(ra.clip).toBe(99);
+    expect(rb.clip).toBe(99);
+
+    // Play state is per-entity, no crosstalk.
+    expect(ra.loop).toBe(true);
+    expect(rb.loop).toBe(false);
+    expect(ra.currentTime).toBe(5);
+    expect(rb.currentTime).toBe(10);
+    expect(ra.playing).toBe(true);
+    expect(rb.playing).toBe(false);
+  });
+
+  it('mutating entity A play state does not leak into entity B', () => {
+    const world = new World();
+    const clip: Handle<'VideoAsset', 'shared'> = toShared<'VideoAsset'>(42);
+
+    const a = world.spawn({ component: VideoPlayer, data: { clip, currentTime: 0 } }).unwrap();
+    const b = world.spawn({ component: VideoPlayer, data: { clip, currentTime: 0 } }).unwrap();
+
+    // Advance only A's playhead.
+    world.set(a, VideoPlayer, { currentTime: 7.25, loop: true });
+
+    const ra = world.get(a, VideoPlayer).unwrap();
+    const rb = world.get(b, VideoPlayer).unwrap();
+
+    expect(ra.currentTime).toBe(7.25);
+    expect(ra.loop).toBe(true);
+    // B untouched — independent column slot.
+    expect(rb.currentTime).toBe(0);
+    expect(rb.loop).toBe(false);
+  });
+});

package/src/glyph-layout.ts

@@ -0,0 +1,208 @@
+// @forgeax/engine-graphics-extras - glyph layout algorithm
+// (feat-20260531-world-space-msdf-text-rendering M4 / w15).
+//
+// Pure functions: lay out a `GlyphText` string against a `FontAsset`'s glyph
+// metrics into per-glyph quad vertices (position + uv) and indices, plus a
+// conservative bounding-sphere radius for pick (plan-strategy D-5). NO ECS,
+// NO GPU -- the mesh baking (12-float stride fill + register) is the job of
+// `glyph-mesh-bake.ts` (w17); this module produces only the geometry data.
+//
+// Layout model (plan-strategy D-2 / D-4 / D-5):
+//   - left-aligned: the pen advances by `metric.advance * fontSize` per glyph.
+//   - baseline at local y = 0 on the first line; the local space is Y-up so a
+//     glyph quad's top edge sits at `penY - bearingY*s + size.h*s` and its
+//     bottom edge at `penY - bearingY*s` (BMFont yoffset measures DOWN from
+//     the line top; we negate into Y-up so higher bearingY -> lower top).
+//   - `\n` resets penX to 0 and drops penY by `lineHeight * fontSize`
+//     (line-2 baseline = -lineHeight, AC-21).
+//   - missing codepoint -> notdef TOFU fallback; the glyph still counts and
+//     emits a quad (AC-14). A codepoint with neither a metric nor a notdef
+//     emits no quad but still advances by the notdef-or-zero advance.
+//   - empty string -> zero vertices / zero indices / radius 0 (the bake
+//     helper registers a 0-vertex mesh, which is legal; pick skips it).
+//
+// Vertex layout produced here is the 12-float canonical stride
+// (PROCEDURAL_FLOATS_PER_VERTEX): position(vec3) + normal(vec3) + uv(vec2) +
+// tangent(vec4). This module writes position + uv as real values and leaves
+// normal/tangent as placeholder constants so the buffer is register-ready
+// without a second pass (R-2: 12-float stride is a hard register gate). The
+// per-vertex offsets are exported so the bake helper + tests share one SSOT.
+
+import { PROCEDURAL_FLOATS_PER_VERTEX } from '@forgeax/engine-geometry';
+import type { FontAsset, GlyphMetric } from '@forgeax/engine-types';
+import { TextError } from '@forgeax/engine-types';
+
+/**
+ * Canonical 12-float vertex stride (position vec3 + normal vec3 + uv vec2 +
+ * tangent vec4) owned by `PROCEDURAL_FLOATS_PER_VERTEX` in
+ * `@forgeax/engine-geometry`. R-2: the baked mesh must satisfy this stride or `register`
+ * fail-fasts with `mesh-vertex-stride-mismatch`.
+ */
+/** Byte-free float offsets within a single 12-float vertex. */
+export const VERTEX_OFFSET = {
+  position: 0, // vec3
+  normal: 3, // vec3 (placeholder (0,0,1))
+  uv: 6, // vec2
+  tangent: 8, // vec4 (placeholder (0,0,0,1))
+} as const;
+
+/** Soft per-frame concurrent-font ceiling (plan-strategy D-8 / AC-20). */
+export const FONT_CONCURRENCY_LIMIT = 8;
+
+/** Layout output: per-glyph quad geometry + conservative sphere radius. */
+export interface GlyphLayoutResult {
+  /** 12-float-stride interleaved vertices (4 vertices per glyph). */
+  readonly vertices: Float32Array;
+  /** Triangle indices (6 per glyph: two triangles). */
+  readonly indices: Uint16Array;
+  /**
+   * Conservative bounding-sphere radius from the anchor (local origin) to the
+   * farthest glyph quad corner (plan-strategy D-5). The bake helper turns this
+   * into a cube AABB (half-side = radius) so pick is orientation-independent.
+   */
+  readonly radius: number;
+}
+
+// Module-level set tracking distinct FontAsset handle ids active in the
+// current frame. The layout system resets this at the top of each frame
+// (resetFontConcurrency) and calls trackFontConcurrency once per distinct
+// font; the 9th distinct font throws a structured TextError (D-8 rejects
+// silently evicting the oldest font).
+const activeFontIds = new Set<number>();
+
+/** Reset the per-frame concurrent-font tracker (call once at frame start). */
+export function resetFontConcurrency(): void {
+  activeFontIds.clear();
+}
+
+/**
+ * Track one distinct FontAsset handle id as active this frame. Re-tracking an
+ * already-active id is a no-op; the (N+1)th distinct id beyond
+ * {@link FONT_CONCURRENCY_LIMIT} throws `TextError('font-concurrency-exceeded')`
+ * (plan-strategy D-8 / AC-20).
+ */
+export function trackFontConcurrency(fontId: number): void {
+  if (activeFontIds.has(fontId)) return;
+  if (activeFontIds.size >= FONT_CONCURRENCY_LIMIT) {
+    throw new TextError({
+      code: 'font-concurrency-exceeded',
+      expected: String(FONT_CONCURRENCY_LIMIT),
+      hint: 'reuse a shared FontAsset across labels, or split text into fewer distinct fonts per frame',
+      detail: { active: activeFontIds.size, limit: FONT_CONCURRENCY_LIMIT, rejected: fontId },
+    });
+  }
+  activeFontIds.add(fontId);
+}
+
+const NEWLINE = '\n'.codePointAt(0) as number;
+
+/**
+ * Lay out `text` against `font` at `fontSize`, producing per-glyph quad
+ * geometry (12-float stride) + indices + the conservative sphere radius.
+ *
+ * @param font The resolved FontAsset (glyph metrics + common block).
+ * @param text The authoring string (`\n` starts a new line).
+ * @param fontSize Uniform scale applied to all metric units.
+ */
+export function layoutGlyphText(
+  font: FontAsset,
+  text: string,
+  fontSize: number,
+): GlyphLayoutResult {
+  const s = fontSize;
+  const { atlasWidth, atlasHeight, lineHeight } = font.common;
+
+  // First pass over code points: collect the renderable glyph quads.
+  const quads: Array<{ x0: number; y0: number; x1: number; y1: number; m: GlyphMetric }> = [];
+  let penX = 0;
+  let penY = 0;
+  let maxCornerDist = 0;
+
+  // Iterate by code point so surrogate pairs count as one glyph.
+  for (const ch of text) {
+    const cp = ch.codePointAt(0) as number;
+    if (cp === NEWLINE) {
+      penX = 0;
+      penY -= lineHeight * s;
+      continue;
+    }
+    const metric = font.glyphs[cp] ?? font.notdef;
+    if (metric === undefined) {
+      // Neither a glyph nor a notdef -> nothing to render; advance by zero so
+      // the cursor does not jump (rare: a font with no notdef and missing cp).
+      continue;
+    }
+    // Quad corners in Y-up local space (baseline at penY).
+    const x0 = penX + metric.bearingX * s;
+    const yTop = penY - metric.bearingY * s + metric.size.h * s;
+    const yBot = penY - metric.bearingY * s;
+    const x1 = x0 + metric.size.w * s;
+    quads.push({ x0, y0: yBot, x1, y1: yTop, m: metric });
+    maxCornerDist = Math.max(
+      maxCornerDist,
+      Math.hypot(x0, yBot),
+      Math.hypot(x1, yBot),
+      Math.hypot(x0, yTop),
+      Math.hypot(x1, yTop),
+    );
+    penX += metric.advance * s;
+  }
+
+  const glyphCount = quads.length;
+  const vertices = new Float32Array(glyphCount * 4 * PROCEDURAL_FLOATS_PER_VERTEX);
+  const indices = new Uint16Array(glyphCount * 6);
+
+  for (let g = 0; g < glyphCount; g++) {
+    const q = quads[g] as (typeof quads)[number];
+    const { region } = q.m;
+    // Atlas UV (top-left origin) normalized into [0,1].
+    const u0 = region.x / atlasWidth;
+    const u1 = (region.x + region.w) / atlasWidth;
+    const v0 = region.y / atlasHeight;
+    const v1 = (region.y + region.h) / atlasHeight;
+    // 4 corners: TL, TR, BR, BL (CCW); position z = 0 (billboard before).
+    // uv pairs the top edge (y1) with v0 and the bottom edge (y0) with v1.
+    writeVertex(vertices, g * 4 + 0, q.x0, q.y1, u0, v0);
+    writeVertex(vertices, g * 4 + 1, q.x1, q.y1, u1, v0);
+    writeVertex(vertices, g * 4 + 2, q.x1, q.y0, u1, v1);
+    writeVertex(vertices, g * 4 + 3, q.x0, q.y0, u0, v1);
+    const vbase = g * 4;
+    const ibase = g * 6;
+    indices[ibase + 0] = vbase + 0;
+    indices[ibase + 1] = vbase + 1;
+    indices[ibase + 2] = vbase + 2;
+    indices[ibase + 3] = vbase + 0;
+    indices[ibase + 4] = vbase + 2;
+    indices[ibase + 5] = vbase + 3;
+  }
+
+  return { vertices, indices, radius: maxCornerDist };
+}
+
+/** Write one 12-float vertex (position + placeholder normal + uv + placeholder tangent). */
+function writeVertex(
+  out: Float32Array,
+  vertexIndex: number,
+  x: number,
+  y: number,
+  u: number,
+  v: number,
+): void {
+  const o = vertexIndex * PROCEDURAL_FLOATS_PER_VERTEX;
+  // position (vec3)
+  out[o + VERTEX_OFFSET.position + 0] = x;
+  out[o + VERTEX_OFFSET.position + 1] = y;
+  out[o + VERTEX_OFFSET.position + 2] = 0;
+  // normal placeholder (0,0,1)
+  out[o + VERTEX_OFFSET.normal + 0] = 0;
+  out[o + VERTEX_OFFSET.normal + 1] = 0;
+  out[o + VERTEX_OFFSET.normal + 2] = 1;
+  // uv (vec2)
+  out[o + VERTEX_OFFSET.uv + 0] = u;
+  out[o + VERTEX_OFFSET.uv + 1] = v;
+  // tangent placeholder (0,0,0,1)
+  out[o + VERTEX_OFFSET.tangent + 0] = 0;
+  out[o + VERTEX_OFFSET.tangent + 1] = 0;
+  out[o + VERTEX_OFFSET.tangent + 2] = 0;
+  out[o + VERTEX_OFFSET.tangent + 3] = 1;
+}