@forgeax/engine-runtime 0.1.2

package/src/__tests__/animation-graph-slot-fill.unit.test.ts

@@ -0,0 +1,95 @@
+// feat-20260713-animation-state-machine-plugin M3 / w21 — DAG eval fills the
+// variable N-slot columns (AC-08).
+//
+// AC-08: post-order DAG evaluation spreads each Clip leaf's effective weight
+// into the variable-length weights[] / clips[] columns; a single eval frame is
+// then a valid input to advanceAnimationPlayer's N-way blend. This test drives a
+// 5-child Blend (proving the retired 4-slot cap is gone) and asserts the derived
+// slot distribution equals the expected normalized shares, that clips[] carry
+// the source handles in leaf order, and that the derived columns feed advance
+// without a length fault.
+//
+// TDD red anchor: before w24 + w25 the file fails to compile; after them the
+// slots read back at the expected distribution.
+
+import {
+  AnimationPlayer,
+  advanceAnimationPlayer,
+  defineAnimationGraph,
+  evaluateAnimationGraph,
+} from '@forgeax/engine-animation';
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function registerClip(world: World, duration: number): number {
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  return world.allocSharedRef('AnimationClip', clip) as unknown as number;
+}
+
+const lookupClip = (_guid: string): AnimationClip => ({
+  kind: 'animation-clip',
+  duration: 10,
+  channels: [],
+});
+
+function asClipGuid(raw: number): string {
+  return `test/animation-clip-${raw}`;
+}
+
+interface Slots {
+  clips: Uint32Array;
+  times: Float32Array;
+  weights: Float32Array;
+  speeds: Float32Array;
+}
+
+function readSlots(world: World, e: EntityHandle): Slots {
+  return world.get(e, AnimationPlayer).unwrap() as unknown as Slots;
+}
+
+describe('evaluateAnimationGraph — variable N-slot fill (M3 / w21)', () => {
+  it('spreads a 5-child Blend into 5 slots at the expected distribution', () => {
+    const world = new World();
+    const handles = [0, 1, 2, 3, 4].map(() => registerClip(world, 10));
+
+    // Blend of FIVE equal-weight clips -> normalized 0.2 each; 5 > 4 proves the
+    // fixed 4-slot cap is retired.
+    const built = defineAnimationGraph((b) => {
+      const leaves = handles.map((h) => b.clip(asClipGuid(h)));
+      return b.blend(leaves);
+    });
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const graphH = world.allocSharedRef('AnimationGraph', built.value);
+
+    const e = world
+      .spawn({ component: AnimationPlayer, data: { graph: graphH } })
+      .unwrap() as EntityHandle;
+
+    evaluateAnimationGraph(world, 0, lookupClip);
+
+    const ap = readSlots(world, e);
+    expect(ap.clips.length).toBe(5);
+    expect(ap.weights.length).toBe(5);
+    expect(ap.times.length).toBe(5);
+    expect(ap.speeds.length).toBe(5);
+
+    for (let i = 0; i < 5; i++) {
+      // clips[] carry the leaf handles in construction (leaf) order.
+      expect(ap.clips[i]).toBeGreaterThan(0);
+      // Each of five equal leaves gets a normalized 0.2 share.
+      expect(ap.weights[i]).toBeCloseTo(0.2, 5);
+      // Derived path parks speeds[]=0 (eval owns the seek-time, D-7).
+      expect(ap.speeds[i]).toBe(0);
+    }
+
+    // The derived slots normalize to exactly 1 (Blend semantics).
+    const total = Array.from(ap.weights).reduce((a, w) => a + w, 0);
+    expect(total).toBeCloseTo(1, 5);
+
+    // The eval output is a valid input to advance's N-way blend (length-synced).
+    expect(() => advanceAnimationPlayer(world, 1 / 60)).not.toThrow();
+  });
+});

package/src/__tests__/animation-nslot.unit.test.ts

@@ -0,0 +1,63 @@
+// feat-20260713-animation-state-machine-plugin M1 / w1 — variable N-slot lock.
+//
+// AC-01: AnimationPlayer.clips/times/weights/speeds drop the fixed 4-slot cap
+// and become variable `array<T>` columns. This test constructs an entity with
+// SIX concurrent slots, runs advanceAnimationPlayer for one frame, and asserts
+// the read-back arrays keep length 6 with no overflow / truncation / throw.
+//
+// TDD red anchor: before the schema migration (w4), `clips` is
+// `array<shared<AnimationClip>, 4>`; spawning a 6-element clips array trips the
+// ECS `FixedArrayOverflowError` and `.unwrap()` throws — the construction
+// itself fails. After w4 the variable schema accepts 6 slots and the frame
+// leaves all six weight columns intact.
+
+import { AnimationPlayer, advanceAnimationPlayer } from '@forgeax/engine-animation';
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function makeClip(duration: number): AnimationClip {
+  return { kind: 'animation-clip', duration, channels: [] };
+}
+
+describe('AnimationPlayer — variable N-slot (M1 / w1)', () => {
+  it('constructs and evaluates 6 concurrent slots without overflow / truncation', () => {
+    const world = new World();
+    const clips = Array.from({ length: 6 }, () =>
+      world.allocSharedRef('AnimationClip', makeClip(10)),
+    );
+    const e = world
+      .spawn({
+        component: AnimationPlayer,
+        data: {
+          clips,
+          times: new Float32Array([0, 0, 0, 0, 0, 0]),
+          weights: new Float32Array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6]),
+          speeds: new Float32Array([1, 1, 1, 1, 1, 1]),
+        },
+      })
+      .unwrap() as EntityHandle;
+
+    expect(() => advanceAnimationPlayer(world, 0.5)).not.toThrow();
+
+    const ap = world.get(e, AnimationPlayer).unwrap() as unknown as {
+      clips: Uint32Array;
+      weights: Float32Array;
+    };
+    // No 4-slot truncation: all six slots survive one frame.
+    expect(ap.clips.length).toBe(6);
+    expect(ap.weights.length).toBe(6);
+    // advance never writes weights back (D-7); the six values read back verbatim.
+    expect(Array.from(ap.weights)).toEqual([
+      expect.closeTo(0.1, 5),
+      expect.closeTo(0.2, 5),
+      expect.closeTo(0.3, 5),
+      expect.closeTo(0.4, 5),
+      expect.closeTo(0.5, 5),
+      expect.closeTo(0.6, 5),
+    ]);
+    // The 6th clip handle is a real slot, not clamped away.
+    expect(ap.clips[5]).toBe(clips[5]);
+  });
+});

package/src/__tests__/animation-slot-length-guard.unit.test.ts

@@ -0,0 +1,81 @@
+// feat-20260713-animation-state-machine-plugin M1 / w2 — slot-length guard.
+//
+// AC-11 (parallel-array length-mismatch branch): the four AnimationPlayer SoA
+// columns (clips / times / weights / speeds) are variable `array<T>` columns
+// set field-by-field (release-then-alloc per field, D-5), so nothing at the ECS
+// layer cross-checks their lengths. A single evaluation-entry chokepoint in
+// advanceAnimationPlayer must reject a row whose four columns disagree in
+// length with a structured error `animation-player-slot-length-mismatch`
+// carrying `.code` + `.hint` — never silently zero-pad or truncate.
+//
+// TDD red anchor: before the schema migration (w4) the columns are fixed
+// `array<T, 4>`; a short write is tail-padded to length 4 so the four columns
+// are always equal-length and the guard cannot trip — advance never throws and
+// this test stays red. After w5 lands the entry guard the mismatch is caught.
+
+import { AnimationPlayer, advanceAnimationPlayer } from '@forgeax/engine-animation';
+import { World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function makeClip(duration: number): AnimationClip {
+  return { kind: 'animation-clip', duration, channels: [] };
+}
+
+interface StructuredError {
+  code?: unknown;
+  hint?: unknown;
+}
+
+describe('AnimationPlayer — slot-length guard (M1 / w2)', () => {
+  it('rejects unequal parallel-array lengths with a structured error (no silent pad/truncate)', () => {
+    const world = new World();
+    const clipOne = world.allocSharedRef('AnimationClip', makeClip(10));
+    const clipTwo = world.allocSharedRef('AnimationClip', makeClip(10));
+
+    // clips/times/speeds carry two slots; weights carries only one — a
+    // consumer that forgot to keep the four columns length-synced.
+    world
+      .spawn({
+        component: AnimationPlayer,
+        data: {
+          clips: [clipOne, clipTwo],
+          times: new Float32Array([0, 0]),
+          weights: new Float32Array([1]),
+          speeds: new Float32Array([1, 1]),
+        },
+      })
+      .unwrap();
+
+    let caught: StructuredError | undefined;
+    try {
+      advanceAnimationPlayer(world, 0.5);
+    } catch (e) {
+      caught = e as StructuredError;
+    }
+
+    expect(caught).toBeDefined();
+    expect(caught?.code).toBe('animation-player-slot-length-mismatch');
+    expect(typeof caught?.hint).toBe('string');
+    expect((caught?.hint as string).length).toBeGreaterThan(0);
+  });
+
+  it('does not throw when the four columns are length-synced', () => {
+    const world = new World();
+    const clip = world.allocSharedRef('AnimationClip', makeClip(10));
+
+    world
+      .spawn({
+        component: AnimationPlayer,
+        data: {
+          clips: [clip],
+          times: new Float32Array([0]),
+          weights: new Float32Array([1]),
+          speeds: new Float32Array([1]),
+        },
+      })
+      .unwrap();
+
+    expect(() => advanceAnimationPlayer(world, 0.5)).not.toThrow();
+  });
+});

package/src/__tests__/append-injection.test.ts

@@ -0,0 +1,105 @@
+// append-injection.test.ts -- M3 / w11 (b) integration test for the
+// `appendInjection(bgl, kind)` API.
+//
+// feat-20260613-material-paramschema-driven-binding M3 / w11.
+//
+// Decision anchors (plan-strategy §2):
+//   - D-6  appendInjection(bgl, kind) — engine injection ('shadow' | 'ibl' |
+//          'lightmap') starts at derive(...).userRegionBindingEnd, no
+//          hardcoded emissive/AO start-binding (=14) leak.
+//   - R-1  the 14-slot user-region assumption breaks once D-3 merges UBO;
+//          appendInjection threads userRegionBindingEnd from derive output.
+//
+// What this test asserts (M3 scope):
+//   (a) appendInjection accepts the 3 injection kinds and produces BGL
+//       entries whose `.binding` values start exactly at the user-region
+//       end (the size of the input BGL list).
+//   (b) appendInjection on an empty user-region (shadow-caster) starts
+//       injection at binding 0.
+//   (c) Calling appendInjection twice (e.g. shadow + ibl) chains correctly:
+//       the second call's bindings start after the first's last binding.
+
+import { appendInjection } from '@forgeax/engine-render/internal';
+import type { ParamSchemaEntry } from '@forgeax/engine-types';
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+const standardPbrSchema: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'metallic', type: 'f32', default: 0 },
+  { name: 'roughness', type: 'f32', default: 0.5 },
+  { name: 'baseColorTexture', type: 'texture2d' },
+  { name: 'normalTexture', type: 'texture2d' },
+];
+
+describe('appendInjection (M3 w15) — engine injection BGL appending', () => {
+  it('(a) shadow injection bindings start at userRegionBindingEnd (non-empty user region)', () => {
+    const out = derive(standardPbrSchema);
+    // derive returns the forgeax-shim BindGroupLayoutEntry (?: undefined);
+    // appendInjection consumes @webgpu/types GPUBindGroupLayoutEntry. Use
+    // the explicit two-step `as unknown as` cast (RHI gate j exempts this
+    // form as an opt-in to a known-unsafe assertion — the same pattern is
+    // used in builtin-shader-register-e2e.test.ts for the same shim surface
+    // mismatch).
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+    const start = out.userRegionBindingEnd;
+    const injected = appendInjection(userBgl, 'shadow');
+    // The first injected entry's binding equals start (the exact value
+    // returned by derive — no hardcoded 14).
+    expect(injected[0]?.binding).toBe(start);
+    // All injected bindings are dense from start onward.
+    for (let i = 0; i < injected.length; i++) {
+      const entry = injected[i];
+      if (entry === undefined) continue;
+      expect(entry.binding).toBe(start + i);
+    }
+  });
+
+  it('(a/ibl) ibl injection starts at userRegionBindingEnd', () => {
+    const out = derive(standardPbrSchema);
+    // See `(a)` for the cast rationale (forgeax shim → @webgpu/types via
+    // explicit two-step `as unknown as`, exempt from RHI gate j).
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+    const start = out.userRegionBindingEnd;
+    const injected = appendInjection(userBgl, 'ibl');
+    expect(injected[0]?.binding).toBe(start);
+  });
+
+  it('(a/lightmap) lightmap injection starts at userRegionBindingEnd', () => {
+    const out = derive(standardPbrSchema);
+    // See `(a)` for the cast rationale (forgeax shim → @webgpu/types via
+    // explicit two-step `as unknown as`, exempt from RHI gate j).
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+    const start = out.userRegionBindingEnd;
+    const injected = appendInjection(userBgl, 'lightmap');
+    expect(injected[0]?.binding).toBe(start);
+  });
+
+  it('(b) empty user region (shadow-caster) injects starting at binding 0', () => {
+    const out = derive([] as readonly ParamSchemaEntry[]);
+    expect(out.userRegionBindingEnd).toBe(0);
+    const userBgl: GPUBindGroupLayoutEntry[] = [];
+    const injected = appendInjection(userBgl, 'shadow');
+    expect(injected[0]?.binding).toBe(0);
+  });
+
+  it('(c) chained injections (shadow then ibl) produce dense, non-overlapping bindings', () => {
+    const out = derive(standardPbrSchema);
+    // See `(a)` for the cast rationale (forgeax shim → @webgpu/types via
+    // explicit two-step `as unknown as`, exempt from RHI gate j).
+    const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
+    const start = out.userRegionBindingEnd;
+    const afterShadow = appendInjection(userBgl, 'shadow');
+    // Build the merged list (user + shadow) then chain ibl.
+    const merged = [...userBgl, ...afterShadow];
+    const afterIbl = appendInjection(merged, 'ibl');
+    // ibl's first binding is `merged.length`, which is start + afterShadow.length.
+    expect(afterIbl[0]?.binding).toBe(start + afterShadow.length);
+    // All ibl bindings are unique and after every shadow binding.
+    const shadowBindings = new Set(afterShadow.map((e) => e.binding));
+    for (const e of afterIbl) {
+      expect(shadowBindings.has(e.binding)).toBe(false);
+      expect(e.binding).toBeGreaterThan(start + afterShadow.length - 1);
+    }
+  });
+});

package/src/__tests__/asi-world-baseline-export.unit.test.ts

@@ -0,0 +1,173 @@
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch / M5 / w16.
+//
+// Forward-looking contract for the asi-world baseline PNG export script
+// (`apps/hello/asi-world/scripts/export-baseline.mjs`) — plan-tasks w16
+// targets. Both R-NEW-1 (upstream demo not landed) and R-4 (baseline PNG
+// fallback) are engaged:
+//
+//   - R-NEW-1: `apps/hello/asi-world/` does not exist on this branch
+//     (m0-probe.json: upstream_tweak20260624_landed=false). The export
+//     script cannot be written into a non-existent demo directory.
+//   - R-4 (plan-strategy section 4): even if the demo existed, dawn-node
+//     readback in this environment is blocked by the pre-existing
+//     wgpu_wasm import-binding gate documented in M1-M4 deferred-gate
+//     evidence (apps/preview vite-plugin-shader buildStart hook fails
+//     with WebAssembly import binding mismatch on
+//     __wbg_rhiwgputextureview_unwrap). R-4 fallback maps to "if baseline
+//     PNG is hard to export, degrade to structural-only smoke + append the
+//     degradation evidence to the task description".
+//
+// This test locks the export-script contract surface so a future
+// follow-up commit (once upstream lands and wgpu_wasm is materialised on
+// the runner) can write the actual `export-baseline.mjs` script with
+// review-friendly mechanical alignment.
+//
+// w18 (asi-world smoke) under the same fallback chain falls back to
+// structural-only ECS query assertions (entity counts, drawcall caps,
+// onError=0) without pixel-diff. ε≤0.05 mode is deferred to the
+// upstream-landed follow-up.
+//
+// Anchors:
+//   - requirements.md AC-08 (line 2): asi-world smoke 300 frames + baseline
+//     PNG ε≤0.05 diff.
+//   - plan-strategy.md section 4 R-4 fallback.
+//   - plan-strategy.md section 5.4 + charter P5 (subagent produces PNG,
+//     main session compares — but only when PNG can be produced).
+//   - plan-strategy.md section 7 M5 boundary.
+
+import { describe, it } from 'vitest';
+
+/**
+ * Closed contract specifying the `export-baseline.mjs` script surface.
+ * Each field locks one immutable property the script must satisfy when
+ * authored against the upstream-landed asi-world demo. The follow-up
+ * commit that adds the script will reference this contract directly.
+ */
+interface BaselineExportContract {
+  /** Script file path inside the asi-world demo workspace. */
+  readonly scriptPath: 'apps/hello/asi-world/scripts/export-baseline.mjs';
+  /**
+   * PNG output path inside the assets submodule. Must live under the
+   * loop screenshots tree (Apache-2.0 carve-out per
+   * forgeax-engine-assets/README.md).
+   */
+  readonly outputPngPath: 'forgeax-engine-assets/.forgeax-harness/forgeax-loop/feat-20260625-sprite-instances-and-tilemap-terrain-static-batch/screenshots/asi-world-baseline.png';
+  /**
+   * Baseline worktree the script must drive end-to-end. Cannot be the
+   * current feat's worktree (circular reference would corrupt the
+   * fixture invariance property).
+   */
+  readonly baselineWorktreeId: 'feat-20260624-sprite-lit-shading-model-pure-2d-lighting';
+  /**
+   * Frame index at which readback is performed. Must equal the frame
+   * index w18's smoke uses for ε≤0.05 diff (otherwise the baseline is
+   * comparing apples and oranges). 60 / 120 are typical stable points;
+   * the chosen value is locked here so both scripts read the same SSOT.
+   */
+  readonly readbackFrameIndex: 120;
+  /** Idempotency: re-running the script overwrites the PNG in place. */
+  readonly idempotent: true;
+  /**
+   * The script is one-off; never invoked from CI matrix. CI consumes the
+   * PNG produced by a maintainer run, not the script itself.
+   */
+  readonly inCi: false;
+}
+
+const CONTRACT: BaselineExportContract = {
+  scriptPath: 'apps/hello/asi-world/scripts/export-baseline.mjs',
+  outputPngPath:
+    'forgeax-engine-assets/.forgeax-harness/forgeax-loop/feat-20260625-sprite-instances-and-tilemap-terrain-static-batch/screenshots/asi-world-baseline.png',
+  baselineWorktreeId: 'feat-20260624-sprite-lit-shading-model-pure-2d-lighting',
+  readbackFrameIndex: 120,
+  idempotent: true,
+  inCi: false,
+};
+
+describe('asi-world baseline PNG export script contract (w16, R-NEW-1 + R-4 fallback)', () => {
+  it('script lives inside the asi-world demo workspace under scripts/', () => {
+    if (!CONTRACT.scriptPath.startsWith('apps/hello/asi-world/scripts/')) {
+      throw new Error(
+        `scriptPath drift: ${CONTRACT.scriptPath} not under asi-world demo workspace scripts/`,
+      );
+    }
+    if (!CONTRACT.scriptPath.endsWith('.mjs')) {
+      throw new Error(`scriptPath must be ESM .mjs: got ${CONTRACT.scriptPath}`);
+    }
+  });
+
+  it('PNG output lives in assets submodule under loop screenshots tree', () => {
+    if (
+      !CONTRACT.outputPngPath.startsWith('forgeax-engine-assets/.forgeax-harness/forgeax-loop/')
+    ) {
+      throw new Error(
+        `outputPngPath outside assets submodule loop screenshots tree: ${CONTRACT.outputPngPath}`,
+      );
+    }
+    if (!CONTRACT.outputPngPath.includes('asi-world-baseline.png')) {
+      throw new Error(
+        `outputPngPath must name file asi-world-baseline.png: got ${CONTRACT.outputPngPath}`,
+      );
+    }
+  });
+
+  it('baseline worktree is feat-20260624 (not the current feat — circular reference protection)', () => {
+    if (CONTRACT.baselineWorktreeId !== 'feat-20260624-sprite-lit-shading-model-pure-2d-lighting') {
+      throw new Error(
+        `baselineWorktreeId drift: ${CONTRACT.baselineWorktreeId} (must be feat-20260624)`,
+      );
+    }
+    // Compile-time guard: cannot accidentally point at the current feat.
+    const _circular: 'feat-20260625-sprite-instances-and-tilemap-terrain-static-batch' =
+      'feat-20260625-sprite-instances-and-tilemap-terrain-static-batch';
+    // @ts-expect-error baseline cannot equal the current feat id.
+    const wrong: typeof CONTRACT.baselineWorktreeId = _circular;
+    void wrong;
+  });
+
+  it('readbackFrameIndex is stable post-init (60 + warm-up; 120 chosen for asi-world)', () => {
+    if (CONTRACT.readbackFrameIndex < 60) {
+      throw new Error(
+        `readbackFrameIndex ${CONTRACT.readbackFrameIndex} too early (< 60 frames warm-up)`,
+      );
+    }
+    if (CONTRACT.readbackFrameIndex > 300) {
+      throw new Error(
+        `readbackFrameIndex ${CONTRACT.readbackFrameIndex} exceeds smoke TARGET_FRAMES=300`,
+      );
+    }
+  });
+
+  it('script is idempotent (re-runs overwrite PNG, never accumulate)', () => {
+    if (CONTRACT.idempotent !== true) {
+      throw new Error('script must be idempotent (Idempotency principle)');
+    }
+  });
+
+  it('script is NOT executed from CI (one-off maintainer tool)', () => {
+    if (CONTRACT.inCi !== false) {
+      throw new Error('export-baseline.mjs must not run in CI (PNG is a checked-in fixture)');
+    }
+  });
+});
+
+describe('w16 R-4 + R-NEW-1 fallback documentation', () => {
+  it('declared deferral: dawn-node readback blocked by wgpu_wasm gate documented in M1-M4 implement-progress.jsonl', () => {
+    // The pre-existing environmental gate that blocks `pnpm test:unit`,
+    // `pnpm test:browser`, `pnpm test:dawn` (recorded in M1, M2, M3, M4
+    // milestone-completed events under `gatesDeferred[].reason`) equally
+    // blocks dawn-node readback for baseline export. R-4 fallback maps to
+    // "degrade to structural-only smoke". Test passes to record the fallback
+    // is INTENTIONAL (not a regression).
+    const fallbackEvidence = {
+      r4Applied: true,
+      reason:
+        'wgpu_wasm import-binding gate (WebAssembly.instantiate __wbg_rhiwgputextureview_unwrap mismatch) blocks dawn-node init; reproducible on main HEAD per M1-M4 deferred-gate proof',
+      followUp:
+        'w18 falls back to structural-only ECS query assertions (entity counts + drawcall caps + onError=0); pixel diff ε≤0.05 deferred to upstream-landed follow-up',
+    };
+    if (!fallbackEvidence.r4Applied) {
+      throw new Error('R-4 fallback flag drifted out of declaration');
+    }
+  });
+});