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

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,37 @@
+// @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;
+}

package/src/video-loader.ts

@@ -0,0 +1,80 @@
+// @forgeax/engine-graphics-extras - video loader (feat-20260623-world-space-video-asset M2 / w4).
+//
+// Descriptor-only loader for the 'video' asset kind. VideoAsset is a pure
+// `{ url }` descriptor (no pixel decode, no import/cook pipeline — OOS-1);
+// the runtime resolves it into an HTMLVideoElement via the host-provided
+// `VideoElementProvider` World Resource (plan-strategy D-1).
+//
+// The loader returns the payload as VideoAsset synchronously — no fetch or
+// decode. Audio differs because its renderer-injected catalog-entry loader
+// fetches and decodes a Web Audio payload before cataloguing it.
+//
+// Registered in wireDefaultLoaders alongside the other 10 default kinds
+// (plan-strategy D-7: engine-own kind goes in the default set so AI users
+// don't have to manually register it).
+
+import {
+  type AssetDecoderContribution,
+  type AssetKind,
+  err,
+  type Loader,
+  ok,
+  type VideoAsset,
+} from '@forgeax/engine-types';
+
+const VIDEO_URL_RESOLUTION_BASE = 'https://forgeax.invalid/';
+const VIDEO_URL_WHITESPACE = /\s/u;
+
+function hasVideoUrlControlCharacter(value: string): boolean {
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    if (code <= 0x1f || code === 0x7f) return true;
+  }
+  return false;
+}
+
+function isBrowserResolvableVideoUrl(value: unknown): value is string {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.trim().length === 0 ||
+    value !== value.trim() ||
+    hasVideoUrlControlCharacter(value) ||
+    VIDEO_URL_WHITESPACE.test(value) ||
+    value.startsWith('//')
+  ) {
+    return false;
+  }
+  try {
+    const resolved = new URL(value, VIDEO_URL_RESOLUTION_BASE);
+    return resolved.protocol === 'http:' || resolved.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+export const videoLoader: Loader<VideoAsset> = {
+  kind: 'video',
+  load(payload: Record<string, unknown>): VideoAsset | undefined {
+    if (!isBrowserResolvableVideoUrl(payload.url)) return undefined;
+    return { kind: 'video', url: payload.url };
+  },
+};
+
+export const videoContribution: AssetDecoderContribution<VideoAsset, 'video'> = {
+  kind: { kind: 'video' } as AssetKind<VideoAsset, 'video'>,
+  consumer: 'VideoElementProvider',
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload;
+      return payload.kind === 'video' && isBrowserResolvableVideoUrl(payload.url)
+        ? ok(payload)
+        : err({
+            code: 'asset-package-invalid',
+            expected: 'a browser-resolvable video URL descriptor',
+            hint: 'publish an http(s) video URL and let the host create the video element',
+            detail: { guid: envelope.guid, reason: 'video owner validation failed' },
+          });
+    },
+  },
+};

package/src/video-player-system.ts

@@ -0,0 +1,63 @@
+// @forgeax/engine-graphics-extras — video high-perf upload capability probe
+// (feat-20260623-world-space-video-asset M4 / w17).
+//
+// The single per-frame video upload path lives in the record stage
+// (`render-system-record.ts` `videoTextureView`): it reads the host-registered
+// VideoElementProvider (World Resource, D-1), uploads the current frame via
+// `DynamicTextureStore.uploadFrame` (copyExternalImageToTexture), and fires the
+// structured `VideoUploadUnsupportedError` on the engine error channel when a
+// VideoPlayer entity can reach NEITHER the general path (no host element) NOR
+// the high-perf path (AC-10 double-miss, charter P3). There is exactly ONE video
+// upload/failure path — this module only contributes the capability probe the
+// record stage consults to decide whether the reserved high-perf branch is
+// available.
+//
+// Decision anchors:
+//   - requirements AC-09 (two paths left in place, capability probe explicit).
+//   - plan-strategy D-2 (grep-able capability branch, not a TODO).
+
+import type { RhiCaps } from '@forgeax/engine-rhi';
+
+/**
+ * Minimal device shape the high-perf capability probe inspects: the backend
+ * kind plus the (currently-absent) `importExternalTexture` method. Declared
+ * structurally so the probe stays decoupled from the full RhiDevice surface and
+ * unit tests drive it with a small object.
+ */
+export interface VideoCapabilityDevice {
+  readonly caps: Pick<RhiCaps, 'backendKind'>;
+  /**
+   * The WebGPU zero-copy video import entry point. forgeax exposes NO such RHI
+   * method today (research Finding 4 confirmed `importExternalTexture` grep=0),
+   * so this is always `undefined` — the probe's presence check is the explicit,
+   * grep-able boundary between the general path and the reserved high-perf path
+   * (D-2 / AC-09; OOS-5 keeps the upload body unimplemented).
+   */
+  readonly importExternalTexture?: unknown;
+}
+
+/**
+ * AC-09 / D-2 capability probe: decide whether the high-perf zero-copy
+ * GPUExternalTexture upload path is available for video this frame. This is the
+ * EXPLICIT reserved hook the AC-09 "two paths left in place" acceptance is
+ * checked against by code review — it is a real, grep-able code branch, not a
+ * TODO comment.
+ *
+ * The high-perf path requires BOTH a WebGPU backend (GPUExternalTexture is a
+ * browser-WebGPU feature) AND the RHI exposing an `importExternalTexture` entry
+ * point. The latter does not exist in forgeax today (OOS-5: importing the
+ * external texture + a `texture_external` MaterialParamType + WGSL external
+ * sampling is out of scope), so this probe ALWAYS returns false and the general
+ * `copyExternalImageToTexture` path (record stage) is the sole route end-to-end.
+ * The day a future feat lands `importExternalTexture`, this probe flips on for
+ * WebGPU backends without touching the call sites.
+ */
+export function probeVideoHighPerfUpload(device: VideoCapabilityDevice | undefined): boolean {
+  if (device === undefined) return false;
+  // GPUExternalTexture is browser-WebGPU only (wgpu-native / wgpu-webgl2 lack it).
+  if (device.caps.backendKind !== 'webgpu') return false;
+  // Reserved high-perf hook: available only when the RHI exposes the import
+  // entry point. It is absent today (OOS-5), so this is the false-returning
+  // boundary the AC-09 two-path code review verifies.
+  return typeof device.importExternalTexture === 'function';
+}

package/src/video-player.ts

@@ -0,0 +1,51 @@
+// @forgeax/engine-graphics-extras — VideoPlayer ECS component
+// (feat-20260623-world-space-video-asset M3 / w7).
+//
+// Single-component play-state surface for world-space video textures. An
+// entity carries one VideoPlayer referencing a VideoAsset via the `clip`
+// handle; the per-entity playing / loop / currentTime live in independent
+// archetype column slots so multiple entities share one VideoAsset GUID with
+// independent play state (AC-05, research Finding 6).
+//
+// Schema vocab is the CLOSED ECS set (component.ts:315-333): clip uses
+// `shared<VideoAsset>` (a branded u32 handle, NOT a bare GUID string), the
+// three play-state fields use `bool` / `f32`. No opaque / object field type is
+// introduced — the host HTMLVideoElement reference travels through the
+// VideoElementProvider World Resource (plan-strategy D-1 / w9), never inside an
+// ECS field (research Finding 5: schema vocab closed).
+//
+// Decision anchors:
+//   - requirements AC-04 (VideoPlayer registers via defineComponent; reference
+//     field is a handle type, not a bare GUID; play-state fields playing/loop/
+//     currentTime).
+//   - plan-strategy D-4 (clip: Handle<'VideoAsset','shared'>, brand string
+//     'VideoAsset' mirrors AudioSource.clip: Handle<'AudioClipAsset','shared'>
+//     so AI users carry over the audio naming intuition — charter P4).
+//   - charter P1 (progressive disclosure: 4-field minimal surface).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * 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 const VideoPlayer = defineComponent('VideoPlayer', {
+  // The host HTMLVideoElement owns the live asset/presentation binding; the
+  // portable play controls remain in the simulation projection.
+  clip: { type: 'shared<VideoAsset>' },
+  playing: { type: 'bool', default: false },
+  loop: { type: 'bool', default: false },
+  currentTime: { type: 'f32', default: 0, transient: true },
+});