@forgeax/engine-graphics-extras 0.1.2

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

@@ -0,0 +1 @@
+{"version":3,"file":"video-player-system.d.ts","sourceRoot":"","sources":["../src/video-player-system.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,MAAM,CAAA;KAAE,CAAC;IAC3F;;;;;;OAMG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,SAAS,GAAG,OAAO,CAQ3F"}

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.1.2",
+  "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.1.2",
+    "@forgeax/engine-geometry": "0.1.2",
+    "@forgeax/engine-rhi": "0.1.2",
+    "@forgeax/engine-types": "0.1.2"
+  },
+  "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-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-loader.unit.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { videoContribution, videoLoader } from '../video-loader';
+
+describe('video asset owner', () => {
+  it('exposes the host video consumer contribution', () => {
+    expect(videoContribution.kind.kind).toBe('video');
+    expect(videoContribution.consumer).toBe('VideoElementProvider');
+  });
+  it('returns the durable descriptor for a browser-resolvable source', () => {
+    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 no payload for a malformed durable source', () => {
+    expect(
+      videoLoader.load({ kind: 'video', url: 'javascript:alert(1)' }, undefined, {} as never),
+    ).toBeUndefined();
+  });
+});

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