@forgeax/engine-runtime 0.1.3 → 0.1.6

package/src/__tests__/animation-graph-serialize.unit.test.ts

@@ -0,0 +1,171 @@
+// feat-20260713-animation-state-machine-plugin M4 / w27 -- AnimationGraph
+// serialize -> deserialize pack round-trip (AC-14 part a).
+//
+// AC-14 (part a) metric: construct a nested graph -> serialize to a pack payload
+// -> deserialize (rebuild) and assert the graph topology (Clip/Blend/Add nodes +
+// child references), every node's static weight, the root, and every clip
+// reference are field-for-field equal to the original. Clip references round-trip
+// through the existing `refs` GUID mechanism (plan D-4): serialize rewrites each
+// clip leaf's `shared<AnimationClip>` handle to a GUID (indexed into `refs`), and
+// the loader resolves each `refs` index back to its GUID string (the same "GUID
+// verbatim at load, resolve to a handle at use time" contract materialLoader
+// uses, asset-registry D-19).
+//
+// TDD red anchor: before w29 (serializeAnimationGraph) + w30 (animationGraphLoader)
+// the two imports below do not resolve, so the file fails to compile. w29 lands
+// serialize (payload + refs); w30 lands the loader; the round-trip goes green
+// once both halves exist (a round-trip test spans both impl seams by nature).
+
+import { defineAnimationGraph, serializeAnimationGraph } from '@forgeax/engine-animation';
+import { AssetRegistry, animationGraphLoader } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { AnimationClip, AnimationGraph, Handle, LoadContext } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+// Register a clip payload under `guidStr` in BOTH the registry catalog (so
+// `_guidForAsset` resolves payload -> GUID) and the world's shared-ref store (so
+// `resolveAssetHandle` resolves handle -> payload). The SAME payload object is
+// used for both so the identity-based `_guidForAsset` scan matches.
+function registerClip(
+  world: World,
+  reg: AssetRegistry,
+  guidStr: string,
+  duration: number,
+): { handle: Handle<'AnimationClip', 'shared'>; guid: string } {
+  const parsed = AssetGuid.parse(guidStr);
+  if (!parsed.ok) throw new Error(`bad test GUID ${guidStr}`);
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  reg.catalog(parsed.value, clip);
+  const handle = world.allocSharedRef('AnimationClip', clip) as Handle<'AnimationClip', 'shared'>;
+  return { handle, guid: AssetGuid.format(parsed.value) };
+}
+
+// Resolver used by serialize: clip handle -> catalogued GUID string, via the two
+// production seams (resolveAssetHandle on the world + _guidForAsset on the
+// registry). Mirrors how a scene-serialize caller resolves an asset handle.
+function makeClipGuidResolver() {
+  return (clip: string): string | undefined => clip;
+}
+
+const G1 = 'a1000000-0000-4000-8000-000000000001';
+const G2 = 'a1000000-0000-4000-8000-000000000002';
+const G3 = 'a1000000-0000-4000-8000-000000000003';
+
+// Minimal LoadContext stub -- the animation-graph loader is a pure payload/refs
+// transform and reads nothing off the context (no fetch / device / shader).
+const stubCtx = {} as LoadContext;
+
+describe('AnimationGraph serialize -> deserialize round-trip (M4 / w27, AC-14 part a)', () => {
+  it('serialize produces a pack payload with deduped refs of clip GUIDs', () => {
+    const world = new World();
+    const reg = makeRegistry();
+    const walk = registerClip(world, reg, G1, 10);
+    const run = registerClip(world, reg, G2, 20);
+
+    // overlay reuses the walk clip handle -> serialize must dedupe it to a
+    // single refs entry (mirrors material/scene refs dedup).
+    const built = defineAnimationGraph((b) => {
+      const w = b.clip(walk.guid);
+      const r = b.clip(run.guid);
+      const loco = b.blend([w, r]);
+      const overlay = b.clip(walk.guid, 0.3);
+      return b.add(loco, [overlay]);
+    });
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+
+    const out = serializeAnimationGraph(built.value, makeClipGuidResolver());
+    expect(out).not.toBeUndefined();
+    if (out === undefined) return;
+
+    // Two unique clip GUIDs despite three clip nodes (walk referenced twice).
+    expect([...out.refs].sort()).toEqual([walk.guid, run.guid].sort());
+    const payloadNodes = (out.payload.nodes as Array<Record<string, unknown>>) ?? [];
+    expect(payloadNodes).toHaveLength(5);
+    // Every clip node's `clip` in the payload is a refs index, not a handle.
+    for (const node of payloadNodes) {
+      if (node.type === 'clip') {
+        expect(typeof node.clip).toBe('number');
+        expect(node.clip as number).toBeGreaterThanOrEqual(0);
+        expect(node.clip as number).toBeLessThan(out.refs.length);
+      }
+    }
+  });
+
+  it('deserialize rebuilds the graph field-for-field equal to the original', () => {
+    const world = new World();
+    const reg = makeRegistry();
+    const walk = registerClip(world, reg, G1, 10);
+    const run = registerClip(world, reg, G2, 20);
+    const survey = registerClip(world, reg, G3, 30);
+
+    // Nested DAG: Add(base=Blend(survey@0.5, Blend(walk, run))@0.8, additive=[overlay@0.3]).
+    const built = defineAnimationGraph((b) => {
+      const w = b.clip(walk.guid);
+      const r = b.clip(run.guid);
+      const s = b.clip(survey.guid, 0.5);
+      const loco = b.blend([w, r]);
+      const base = b.blend([s, loco], 0.8);
+      const overlay = b.clip(survey.guid, 0.3);
+      return b.add(base, [overlay]);
+    });
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const original = built.value;
+
+    const out = serializeAnimationGraph(original, makeClipGuidResolver());
+    expect(out).not.toBeUndefined();
+    if (out === undefined) return;
+
+    const parsed = animationGraphLoader.load(out.payload, out.refs, stubCtx);
+    expect(parsed).not.toBeUndefined();
+    if (parsed === undefined || typeof parsed !== 'object' || 'ok' in parsed) {
+      throw new Error('animationGraphLoader returned a non-asset result');
+    }
+    const rebuilt = parsed as AnimationGraph;
+
+    // kind + root + node count are structurally identical.
+    expect(rebuilt.kind).toBe('animation-graph');
+    expect(rebuilt.root).toBe(original.root);
+    expect(rebuilt.nodes).toHaveLength(original.nodes.length);
+
+    // Field-for-field per node: type, static weight, child references identical;
+    // clip references equal at the GUID level (the persistent form).
+    for (let i = 0; i < original.nodes.length; i++) {
+      const o = original.nodes[i];
+      const d = rebuilt.nodes[i];
+      if (o === undefined || d === undefined) throw new Error(`missing node ${i}`);
+      expect(d.type).toBe(o.type);
+      expect(d.weight).toBe(o.weight);
+      if (o.type === 'clip' && d.type === 'clip') {
+        expect(d.clip).toBe(o.clip);
+      } else if (o.type === 'blend' && d.type === 'blend') {
+        expect([...d.children]).toEqual([...o.children]);
+      } else if (o.type === 'add' && d.type === 'add') {
+        expect(d.base).toBe(o.base);
+        expect([...d.additive]).toEqual([...o.additive]);
+      }
+    }
+  });
+
+  it('deserialize rejects a malformed payload with undefined (asset-parse-failed upstream)', () => {
+    // clip node whose refs index is out of range -> loader returns undefined so
+    // the load-by-guid path surfaces the existing `asset-parse-failed` code.
+    const badPayload: Record<string, unknown> = {
+      nodes: [{ type: 'clip', clip: 5, weight: 1 }],
+      root: 0,
+    };
+    const parsed = animationGraphLoader.load(
+      badPayload,
+      ['a1000000-0000-4000-8000-000000000009'],
+      stubCtx,
+    );
+    expect(parsed).toBeUndefined();
+  });
+});

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

@@ -19,10 +19,10 @@
 //   (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';
+import { appendInjection } from '../../../render/src/pbr-pipeline';
 
 const standardPbrSchema: readonly ParamSchemaEntry[] = [
   { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },

package/src/__tests__/asset-brand-and-name-retirement.test.ts

@@ -0,0 +1,102 @@
+// feat-20260622 M6 / w22 — regression guards for the two side-table retirements.
+//
+//   AC-05: storedNameOf retired; per-GUID stored name lives on the envelope and
+//          feeds resolveName's `storedName` argument. resolveName's three-arg
+//          XOR derivation (single-asset basename / multi-asset stored name /
+//          no-package '' fallback / 1->N promotion freeze) must be unchanged.
+//   AC-06: the 14-arm assetBrand switch retired for the ASSET_BRAND Record
+//          table. The table maps every Asset.kind to its brand, and the two
+//          consumption points (instantiate -> allocSharedRef brand arg;
+//          inspect().assets[].brand) return the correct brand per kind.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function makeReg(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+const sampler = { kind: 'sampler' as const };
+
+// ── AC-05: resolveName XOR derivation unchanged after storedNameOf retirement ──
+
+describe('AC-05 resolveName regression (storedNameOf retired, name on envelope)', () => {
+  it('single-asset package -> basename(path), no stored name needed', () => {
+    const reg = makeReg();
+    const g = '01890000-0000-7000-8000-000000000101';
+    reg.catalog(g, sampler);
+    reg._registerPackage('assets/hero.glb', [g]);
+    expect(reg.resolveName(g)).toBe('hero.glb');
+    // The payload never carries the name (it lives on the envelope only).
+    const stored = reg.lookup(g);
+    expect(stored).toBeDefined();
+    expect(Object.hasOwn(stored as object, 'name')).toBe(false);
+  });
+
+  it('multi-asset package -> each entry stored name read from envelope', () => {
+    const reg = makeReg();
+    const a = '01890000-0000-7000-8000-000000000102';
+    const b = '01890000-0000-7000-8000-000000000103';
+    reg.catalog(a, sampler);
+    reg.catalog(b, sampler);
+    reg._registerPackage(
+      'assets/char.glb',
+      [a, b],
+      new Map([
+        [a, 'Body'],
+        [b, 'Head'],
+      ]),
+    );
+    expect(reg.resolveName(a)).toBe('Body');
+    expect(reg.resolveName(b)).toBe('Head');
+  });
+
+  it('no-package asset with self name -> stored name; without -> empty string', () => {
+    const reg = makeReg();
+    const named = '01890000-0000-7000-8000-000000000104';
+    const anon = '01890000-0000-7000-8000-000000000105';
+    reg.catalog(named, sampler);
+    reg.catalog(anon, sampler);
+    reg._registerPackage(null, [named], new Map([[named, 'myProcMesh']]));
+    reg._registerPackage(null, [anon]);
+    expect(reg.resolveName(named)).toBe('myProcMesh');
+    expect(reg.resolveName(anon)).toBe('');
+  });
+
+  it('1->N promotion -> original asset basename frozen as stored name', () => {
+    const reg = makeReg();
+    const g1 = '01890000-0000-7000-8000-000000000106';
+    const g2 = '01890000-0000-7000-8000-000000000107';
+    reg.catalog(g1, sampler);
+    reg.catalog(g2, sampler);
+    // Single-asset package first: resolveName == basename.
+    reg._registerPackage('assets/world.glb', [g1]);
+    expect(reg.resolveName(g1)).toBe('world.glb');
+    // A second member arrives: the original's derived basename freezes as its
+    // stored name so it keeps a stable name on the multi-asset branch.
+    reg._registerPackage('assets/world.glb', [g2], new Map([[g2, 'Ground']]));
+    expect(reg.resolveName(g1)).toBe('world.glb');
+    expect(reg.resolveName(g2)).toBe('Ground');
+  });
+
+  it('rename writes the stored name through the envelope', () => {
+    const reg = makeReg();
+    const a = '01890000-0000-7000-8000-000000000108';
+    const b = '01890000-0000-7000-8000-000000000109';
+    reg.catalog(a, sampler);
+    reg.catalog(b, sampler);
+    reg._registerPackage(
+      'assets/pair.glb',
+      [a, b],
+      new Map([
+        [a, 'First'],
+        [b, 'Second'],
+      ]),
+    );
+    const r = reg.rename(a, 'Renamed');
+    expect(r.ok).toBe(true);
+    expect(reg.resolveName(a)).toBe('Renamed');
+    expect(reg.resolveName(b)).toBe('Second');
+  });
+});

package/src/__tests__/asset-error-exhaustive.test-d.ts

@@ -0,0 +1,62 @@
+// feat-20260704-runtime-tier1-decomposition M2 / w13 (AC-07 c): asset cluster
+// exhaustive type-level regression guard (see render-error-exhaustive.test-d.ts
+// header for the shared pattern rationale).
+
+import type { AssetRuntimeError, AssetRuntimeErrorCode } from '@forgeax/engine-assets-runtime';
+
+function exhaustiveSwitchOnAssetCode(code: AssetRuntimeErrorCode): string {
+  switch (code) {
+    case 'material-resolved-empty-passes':
+      return code;
+    case 'mesh-ssbo-capacity-exceeded':
+      return code;
+    case 'mesh-ssbo-ceiling-reached':
+      return code;
+    case 'scene-collect-entity-ref-out-of-closure':
+      return code;
+    case 'scene-collect-asset-guid-unresolved':
+      return code;
+    default: {
+      const exhaustive: never = code;
+      return exhaustive;
+    }
+  }
+}
+
+function narrowAssetError(err: AssetRuntimeError): void {
+  switch (err.code) {
+    case 'material-resolved-empty-passes':
+      void err.detail.materialGuid; // string
+      void err.detail.reason; // 'missing-parent' | 'no-pass-in-chain'
+      break;
+    case 'mesh-ssbo-capacity-exceeded':
+      void err.detail.requested; // number
+      void err.detail.capacity; // number
+      void err.detail.ceiling; // number
+      break;
+    case 'mesh-ssbo-ceiling-reached':
+      void err.detail.requested; // number
+      void err.detail.capacity; // number
+      void err.detail.ceiling; // number
+      break;
+    case 'scene-collect-entity-ref-out-of-closure':
+      void err.detail.entity; // number
+      void err.detail.field; // string
+      void err.detail.target; // number
+      break;
+    case 'scene-collect-asset-guid-unresolved':
+      void err.detail.field; // string
+      break;
+    default: {
+      const exhaustive: never = err;
+      void exhaustive;
+    }
+  }
+}
+
+export type _AssetExhaustiveChecks = {
+  /** @internal forces tsc to type-check the exhaustive switch on AssetRuntimeErrorCode. */
+  _check: ReturnType<typeof exhaustiveSwitchOnAssetCode>;
+  /** @internal forces tsc to type-check the AssetRuntimeError detail narrowing. */
+  _narrow: typeof narrowAssetError;
+};