@forgeax/engine-graphics-extras 0.1.2

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

package/src/glyph-mesh-bake.ts

@@ -0,0 +1,151 @@
+// @forgeax/engine-graphics-extras - glyph mesh bake helper
+// (feat-20260531-world-space-msdf-text-rendering M4 / w17).
+//
+// Turns the pure layout output (w15) into a registered `MeshAsset` and a
+// conservative bounding-sphere cube AABB (plan-strategy D-4 / D-5). Called by
+// the `glyphTextLayoutSystem` (w18) -- not a public AI-user API; AI users
+// declare a `GlyphText` component and the system bakes behind the scenes.
+//
+// 12-float stride (R-2 hard gate): the layout already produced interleaved
+// vertices at the canonical `PROCEDURAL_FLOATS_PER_VERTEX` stride (position + uv
+// real, normal (0,0,1) / tangent (0,0,0,1) placeholder). We deinterleave into
+// the `VertexAttributeMap` (position / normal / uv / tangent) so
+// `AssetRegistry.register` can derive the GPU vertex layout + AABB. The
+// register call fail-fasts with `mesh-vertex-stride-mismatch` if the stride is
+// ever wrong -- this module never bypasses that gate.
+//
+// Empty string -> 0-vertex / 0-index mesh; `register` accepts the empty mesh
+// (validateMeshPayload branch (b)) and pick skips it (inverted-infinity AABB).
+//
+// Conservative cube AABB (D-5): pick must be orientation-independent (text may
+// billboard toward the camera at draw time, but `pick.ts` raycasts against the
+// static local AABB x world matrix without the billboard rotation). The baked
+// mesh's `attributes.position` carries the 8 corners of a cube centered at the
+// anchor with half-side = the layout radius R; `AssetRegistry.register`
+// computes the local AABB from that position attribute (`computeAABB`), so the
+// REGISTERED mesh AABB is the conservative cube -- a ray that would hit the
+// text from any in-plane orientation is caught. The GPU vertex buffer is built
+// from the interleaved `vertices` (real glyph quads), which is fully decoupled
+// from `attributes.position` (uploadMeshById reads `mesh.vertices`). `pick.ts`
+// is NOT modified -- the cube is purely a bake-step property of the mesh.
+
+import type { World } from '@forgeax/engine-ecs';
+import {
+  buildMeshAttributeMapForUvSets,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+} from '@forgeax/engine-geometry';
+import { ok, type Result } from '@forgeax/engine-rhi';
+import type { AssetError, Handle, MeshAsset } from '@forgeax/engine-types';
+
+import type { GlyphLayoutResult } from './glyph-layout';
+
+/** Result of baking a glyph layout into a registered mesh. */
+export interface GlyphMeshBakeResult {
+  /** The registered unmanaged mesh handle (feed to `MeshFilter.assetHandle`). */
+  readonly handle: Handle<'MeshAsset', 'shared'>;
+  /**
+   * Conservative bounding-sphere cube AABB in local space: 6 floats
+   * [-R,-R,-R, R,R,R] centered at the anchor (plan-strategy D-5). Empty
+   * layout -> all-zero box.
+   */
+  readonly aabb: Float32Array;
+}
+
+/** Build the MeshAsset POD (12-float stride) from a glyph layout. */
+export function buildGlyphMeshAsset(layout: GlyphLayoutResult): MeshAsset {
+  const { vertices, indices, radius } = layout;
+  return {
+    kind: 'mesh',
+    vertices,
+    indices,
+    // `attributes.position` carries the 8 conservative-cube corners (half-side
+    // = radius) so `register` computes the orientation-independent cube AABB
+    // (D-5). The GPU vertex buffer is built from the interleaved `vertices`
+    // (uploadMeshById reads `mesh.vertices`), fully decoupled from this
+    // position attribute -- which exists only to drive `computeAABB`.
+    attributes: {
+      // Keep the conservative pick/cull position stream and the canonical
+      // 12-float upload layout in one geometry-owned projection.
+      ...buildMeshAttributeMapForUvSets(1),
+      position: cubeCornerAttributes(radius).position,
+    },
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: indices.length,
+        vertexCount: vertices.length / PROCEDURAL_FLOATS_PER_VERTEX,
+        topology: 'triangle-list',
+        materialSlot: 0,
+      },
+    ],
+    materialSlots: [{ slotName: 'Default' }],
+  };
+}
+
+/** Conservative cube AABB centered at the anchor with half-side = layout radius. */
+export function conservativeCubeAabb(radius: number): Float32Array {
+  return Float32Array.of(-radius, -radius, -radius, radius, radius, radius);
+}
+
+/**
+ * Bake a glyph layout into a registered mesh + conservative cube AABB.
+ *
+ * @param assets The AssetRegistry that owns the mesh handle lifecycle.
+ * @param layout The pure layout output from `layoutGlyphText` (w15).
+ * @returns `Result.ok({ handle, aabb })` or `Result.err(AssetError)` when
+ *   `register` fail-fasts (e.g. stride mismatch -- should never happen for a
+ *   layout produced by w15, but the gate is honored, not bypassed).
+ */
+export function bakeGlyphMesh(
+  world: World,
+  layout: GlyphLayoutResult,
+): Result<GlyphMeshBakeResult, AssetError> {
+  const aabb = conservativeCubeAabb(layout.radius);
+  // feat-20260614 M8 (D-17/D-19): the baked text mesh is a runtime-minted
+  // user-tier asset allocated directly into the world's SharedRefStore. Unlike
+  // `AssetRegistry.catalog` (which runs `withMeshAabb` to compute the AABB from
+  // `attributes.position`), `allocSharedRef` stores the payload verbatim -- so
+  // the mesh POD must carry its own `.aabb` for the cull / pick path to read it.
+  const meshAsset: MeshAsset = { ...buildGlyphMeshAsset(layout), aabb };
+  const handle = world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', meshAsset);
+  return ok({ handle, aabb });
+}
+
+/**
+ * The 8 corners of a cube centered at the anchor with half-side = radius,
+ * packed as a flat `position` attribute (x,y,z per corner). `computeAABB`
+ * reduces this to the conservative cube AABB (D-5). For an empty layout
+ * (radius 0) all corners collapse to the origin, yielding a zero-volume box
+ * that pick treats as a point miss -- consistent with the empty-string path.
+ */
+function cubeCornerAttributes(radius: number): { position: Float32Array } {
+  const r = radius;
+  return {
+    position: Float32Array.of(
+      -r,
+      -r,
+      -r,
+      r,
+      -r,
+      -r,
+      r,
+      r,
+      -r,
+      -r,
+      r,
+      -r,
+      -r,
+      -r,
+      r,
+      r,
+      -r,
+      r,
+      r,
+      r,
+      r,
+      -r,
+      r,
+      r,
+    ),
+  };
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+// @forgeax/engine-graphics-extras -- public barrel.
+//
+// feat-20260705-runtime-tier2-decomposition M3: pure-logic graphics-adjacent
+// modules extracted from @forgeax/engine-runtime. System entry points
+// (tilemapChunkExtractSystem / glyphTextLayoutSystem) stay in runtime and
+// import from here -- see README.md for the package boundary declaration.
+
+// ─── glyph text layout (feat-20260531-world-space-msdf-text-rendering) ─────
+export {
+  FONT_CONCURRENCY_LIMIT,
+  type GlyphLayoutResult,
+  layoutGlyphText,
+  resetFontConcurrency,
+  trackFontConcurrency,
+  VERTEX_OFFSET,
+} from './glyph-layout';
+export {
+  bakeGlyphMesh,
+  buildGlyphMeshAsset,
+  conservativeCubeAabb,
+  type GlyphMeshBakeResult,
+} from './glyph-mesh-bake';
+
+// ─── tile-bits SSOT (feat-20260608-tilemap-object-layer-rendering) ─────────
+export { decodeTileBits, encodeTileBits } from './tile-bits';
+export { tilesetContribution } from './tileset-decoder';
+// ─── VideoElementProvider host bridge ─────────────────────────────────────
+export {
+  VIDEO_ELEMENT_PROVIDER_KEY,
+  type VideoElementProvider,
+} from './video-element-provider';
+export { videoContribution, videoLoader } from './video-loader';
+// ─── VideoPlayer component ────────────────────────────────────────────────
+export { VideoPlayer } from './video-player';
+// ─── video high-perf upload capability probe ──────────────────────────────
+export { probeVideoHighPerfUpload } from './video-player-system';

package/src/tile-bits.ts

@@ -0,0 +1,77 @@
+// @forgeax/engine-graphics-extras - tile-bits (Tiled .tmj wire-format helpers).
+//
+// Tiled .tmj packs each cell as a uint32 where the high 4 bits encode flip /
+// rotation slots and the low 28 bits encode the 1-indexed tile id (id 0 means
+// "empty cell"). The wire layout, from MSB to LSB:
+//
+//   bit 31  flipHorizontal
+//   bit 30  flipVertical
+//   bit 29  flipDiagonal       (== 90deg CW rotation in Tiled semantics)
+//   bit 28  flipHex120         (Tiled hex 120deg flip; preserved for fidelity,
+//                              unused by the orthogonal renderer in M0)
+//   bits 0..27  tileId         (0..0x0FFFFFFF; 0 sentinel = empty)
+//
+// Anchors: requirements integration points (engine-runtime tile-bits SSOT);
+// plan-strategy §M0 targetFiles (tile-bits.ts); feat-20260604 D-2 wire
+// compatibility lock.
+//
+// charter mapping: F1 (single-import barrel — encode/decode pair lives at
+// `@forgeax/engine-runtime/tile-bits`), P3 (overflow / negative / non-integer
+// tile id surface as RangeError, never silently clamp), P4 (encode and decode
+// share the same bit layout and are inverse functions over the supported
+// 0..0x0FFFFFFF tile id range).
+
+const TILE_ID_MAX = 0x0fffffff;
+const FLIP_H_BIT = 1 << 31;
+const FLIP_V_BIT = 1 << 30;
+const FLIP_D_BIT = 1 << 29;
+const FLIP_HEX120_BIT = 1 << 28;
+
+/**
+ * Pack a Tiled .tmj cell into its u32 wire form.
+ *
+ * @param tileId 1-indexed tile id in [0, 0x0FFFFFFF]; `0` is the empty-cell
+ *   sentinel that `TileLayer.tiles` carries downstream. `1` is the first real
+ *   tile entry index into `TilesetAsset.tiles[0]`.
+ * @throws RangeError when `tileId` is non-integer, negative, or > 0x0FFFFFFF.
+ */
+export function encodeTileBits(
+  tileId: number,
+  flipH: boolean,
+  flipV: boolean,
+  flipDiagonal: boolean,
+  flipHex120: boolean,
+): number {
+  if (!Number.isInteger(tileId) || tileId < 0 || tileId > TILE_ID_MAX) {
+    throw new RangeError(
+      `encodeTileBits: tileId must be an integer in [0, ${TILE_ID_MAX}]; got ${tileId}`,
+    );
+  }
+  let packed = tileId >>> 0;
+  if (flipH) packed |= FLIP_H_BIT;
+  if (flipV) packed |= FLIP_V_BIT;
+  if (flipDiagonal) packed |= FLIP_D_BIT;
+  if (flipHex120) packed |= FLIP_HEX120_BIT;
+  return packed >>> 0;
+}
+
+/**
+ * Unpack a Tiled .tmj cell from its u32 wire form into the structured shape
+ * consumed by `tilemap-chunk-extract-system.ts:spawnDerivedRenderEntities`.
+ */
+export function decodeTileBits(packed: number): {
+  readonly tileId: number;
+  readonly flipH: boolean;
+  readonly flipV: boolean;
+  readonly flipDiagonal: boolean;
+  readonly flipHex120: boolean;
+} {
+  const u = packed >>> 0;
+  return {
+    tileId: u & TILE_ID_MAX,
+    flipH: (u & FLIP_H_BIT) !== 0,
+    flipV: (u & FLIP_V_BIT) !== 0,
+    flipDiagonal: (u & FLIP_D_BIT) !== 0,
+    flipHex120: (u & FLIP_HEX120_BIT) !== 0,
+  };
+}

package/src/tileset-decoder.ts

@@ -0,0 +1,64 @@
+import {
+  type AssetDecoderContribution,
+  type AssetKind,
+  err,
+  ok,
+  type TilesetAsset,
+} from '@forgeax/engine-types';
+
+/** Tileset validation is owned here; no physics consumer exists yet. */
+export const tilesetContribution: AssetDecoderContribution<TilesetAsset, 'tileset'> = {
+  kind: { kind: 'tileset' } as AssetKind<TilesetAsset, 'tileset'>,
+  consumer: 'tilemapChunkExtractSystem (physics consumer: missing evidence)',
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload as unknown;
+      if (payload !== null && typeof payload === 'object') {
+        const source = payload as Record<string, unknown>;
+        const rawAtlases = source.atlases;
+        const regions = source.regions;
+        const tiles = source.tiles;
+        const atlases = Array.isArray(rawAtlases)
+          ? rawAtlases.map((value) =>
+              typeof value === 'number' && Number.isSafeInteger(value)
+                ? envelope.refs[value]
+                : value,
+            )
+          : undefined;
+        if (
+          source.kind === 'tileset' &&
+          atlases !== undefined &&
+          atlases.length > 0 &&
+          atlases.every(
+            (atlas): atlas is string => typeof atlas === 'string' && atlas.length > 0,
+          ) &&
+          Array.isArray(regions) &&
+          regions.length > 0 &&
+          Array.isArray(tiles) &&
+          tiles.every(
+            (tile) =>
+              tile !== null &&
+              typeof tile === 'object' &&
+              typeof (tile as { regionIndex?: unknown }).regionIndex === 'number' &&
+              (tile as { regionIndex: number }).regionIndex >= 0 &&
+              (tile as { regionIndex: number }).regionIndex < regions.length,
+          )
+        ) {
+          return ok({
+            ...source,
+            kind: 'tileset',
+            atlases,
+            regions,
+            tiles,
+          } as unknown as TilesetAsset);
+        }
+      }
+      return err({
+        code: 'asset-package-invalid',
+        expected: 'a tileset with atlas GUIDs and in-range tile regions',
+        hint: 'repair the tileset regions; physics consumption is not installed by this owner',
+        detail: { guid: envelope.guid, reason: 'tileset owner validation failed' },
+      });
+    },
+  },
+};

package/src/video-element-provider.ts

@@ -0,0 +1,72 @@
+// @forgeax/engine-graphics-extras — VideoElementProvider contract + Resource key
+// (feat-20260623-world-space-video-asset M3 / w9).
+//
+// D-1: the channel by which a host HTMLVideoElement reaches the engine is a
+// host-registered `VideoElementProvider` stored as a World Resource. The host
+// implements this interface, owns the `<video>` DOM lifecycle (create / set
+// src / autoplay / mute / dispose) single-sidedly, and registers it via
+// `world.insertResource(VIDEO_ELEMENT_PROVIDER_KEY, provider)`. The engine's
+// per-frame record stage (`render-system-record.ts` `videoTextureView`) reads
+// it back each draw via `world.getResource(VIDEO_ELEMENT_PROVIDER_KEY)` and asks
+// for the element to sample — it NEVER constructs an HTMLVideoElement, sets
+// `.src`, or touches the DOM (requirements constraint: HTMLVideoElement is
+// host-provided). There is no separate ECS "video player system" to register.
+//
+// Why a World Resource (not an ECS field): the ECS schema vocab is closed
+// (component.ts:315-333) and admits no opaque/object field type, so an
+// HTMLVideoElement reference cannot live inside a component. A World Resource
+// is the typed singleton channel for host-owned services — the same shape used
+// by animation-domain lookups / TransparentSortConfig (research Finding 5,
+// plan-strategy D-1; plan-decisions F-3 correction: this uses the REAL World
+// Resource API insertResource/getResource, not audio's direct-parameter
+// injection).
+//
+// This module is a pure contract: an interface plus a typed key constant, no
+// runtime behavior. Behavior is exercised by w10/w11 via a mock provider
+// (the host's real implementation lives in the M5 demo, w20).
+
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import type { Handle } from '@forgeax/engine-types';
+
+/**
+ * Resource key under which the host inserts its {@link VideoElementProvider}.
+ *
+ * Consumers import this constant rather than the bare string so a typo
+ * degrades to an import error rather than a silent missing-resource at runtime
+ * (charter P3). Naming mirrors the animation-domain lookup boundary /
+ * `TRANSPARENT_SORT_CONFIG_KEY`.
+ *
+ * @example Host registers its provider once per World:
+ *   world.insertResource(VIDEO_ELEMENT_PROVIDER_KEY, myProvider);
+ *   // ...the record stage reads it back each renderer.draw...
+ */
+export const VIDEO_ELEMENT_PROVIDER_KEY = 'VideoElementProvider' as const;
+
+/**
+ * Host-implemented bridge from a VideoPlayer entity (+ its `clip` handle) to
+ * the host-owned HTMLVideoElement the engine samples each frame.
+ *
+ * The engine calls {@link getElement} during the video tick; the host returns
+ * the element it owns for that clip, or `undefined` when no element is
+ * available yet (clip not loaded / metadata pending / host has none). The
+ * engine treats `undefined` as "no source this frame" and routes through the
+ * structured failure / degrade path (AC-10) rather than sampling garbage.
+ *
+ * The engine NEVER mutates the returned element — it only reads it for the
+ * per-frame `copyExternalImageToTexture` upload (M4). DOM lifecycle is the
+ * host's sole responsibility (D-1).
+ */
+export interface VideoElementProvider {
+  /**
+   * Return the host-owned HTMLVideoElement for the given entity + clip, or
+   * `undefined` when none is available this frame.
+   *
+   * @param entity - the VideoPlayer entity requesting its element.
+   * @param clipHandle - the entity's `VideoPlayer.clip` handle
+   *   (`Handle<'VideoAsset','shared'>`).
+   */
+  getElement(
+    entity: EntityHandle,
+    clipHandle: Handle<'VideoAsset', 'shared'>,
+  ): HTMLVideoElement | undefined;
+}