@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/dist/systems/transparent-sort.d.ts

@@ -0,0 +1,50 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { TransparentEntry } from '../../../render/src/systems/transparent-sort-config';
+/**
+ * Sort the transparent-bucket entries by `(layer ASC, sortValue ASC,
+ * insertion-order)` and return the reordered list.
+ *
+ * The world is consumed read-only for `getTransparentSortConfig(world)`
+ * (D-2 `hasResource` guard, never throws); no entity / component mutation.
+ *
+ * Sort stability: Array.prototype.sort is stable per ES2019 — entries that
+ * share `(layer, sortValue)` keep their insertion order. This matters for
+ * tests that spawn entities in a specific order and expect that order to
+ * survive the sort when no other ordering signal is present.
+ *
+ * @example mode=0 horizontal-z + 4 entries crossing 3 layers
+ *   const out = transparentSortEntries(entries, world);
+ *   // entries with lower layer first; within a layer, lower posZ first.
+ *
+ * @example mode=1 JRPG Y-sort, foot pivot
+ *   world.insertResource(TRANSPARENT_SORT_CONFIG_KEY,
+ *     { mode: TRANSPARENT_SORT_MODE_LAYER_Y, yzAlpha: 1.0 });
+ *   const out = transparentSortEntries(entries, world);
+ *   // entries with deeper foot-Y draw later (back-to-front).
+ *
+ * @example SortKey override
+ *   // entry { layer: 0, posY: 10, pivotY: 0.5, sizeY: 1, sortKey: -99 }
+ *   // -> uses sortValue = -99 instead of the mode formula, but layer
+ *   //    remains the primary key (foreground entries still draw last).
+ */
+export declare function transparentSortEntries(entries: readonly TransparentEntry[], world: World, cameraPos?: readonly [number, number, number]): readonly TransparentEntry[];
+/**
+ * In-place stable argsort over a Float64 key column.
+ *
+ * @param keys    immutable key column; `keys[i]` is the sort weight for the
+ *                entry at original position `i`. Out-of-range positions
+ *                referenced by `indices[i]` are treated as NaN (sort to tail
+ *                in stable order).
+ * @param indices the index buffer to reorder in place. Each element is an
+ *                index into `keys`; on return, `keys[indices[i]]` is
+ *                non-decreasing as `i` grows. The buffer (including its
+ *                underlying ArrayBuffer + byteOffset / length) is mutated in
+ *                place — no re-allocation, callers can hold the reference.
+ *
+ * @example
+ *   const keys = new Float64Array([3.1, 1.2, 2.7]);
+ *   const idx = new Int32Array([0, 1, 2]);
+ *   argsortInPlace(keys, idx); // idx -> [1, 2, 0]
+ */
+export declare function argsortInPlace(keys: Float64Array, indices: Int32Array): void;
+//# sourceMappingURL=transparent-sort.d.ts.map

package/dist/systems/transparent-sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transparent-sort.d.ts","sourceRoot":"","sources":["../../src/systems/transparent-sort.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qDAAqD,CAAC;AAS5F;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,KAAK,EAAE,KAAK,EACZ,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC5C,SAAS,gBAAgB,EAAE,CAkD7B;AA6HD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CA2I5E"}

package/dist/tilemap-register-validate.d.ts

@@ -0,0 +1,21 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { type Result } from '@forgeax/engine-rhi';
+import { AssetError } from '@forgeax/engine-types';
+/**
+ * Validate Tilemap component invariants on the spawned entity (M0 baseline).
+ *
+ * Checks: `cols / rows >= 1`, `chunkSize >= 1`, `tileset` GUID is non-empty.
+ * Returns `Result.ok(undefined)` when every invariant holds, otherwise
+ * `Result.err(AssetError 'asset-invalid-value')` with field-specific
+ * detail (charter P3 fail-fast + P4 consistent with `validateMeshPayload`).
+ */
+export declare function validateTilemapAtRegister(world: World, tilemapEntity: EntityHandle): Result<void, AssetError>;
+/**
+ * Validate TileLayer component invariants on the spawned entity (M0 baseline).
+ *
+ * Checks: parent `ChildOf` points at a Tilemap-carrying entity AND
+ * `tiles.length === parent.cols * parent.rows` (M0 second-stage mutation
+ * recheck; the invariant must hold after every spawn-time mutation).
+ */
+export declare function validateTileLayerAtRegister(world: World, layerEntity: EntityHandle): Result<void, AssetError>;
+//# sourceMappingURL=tilemap-register-validate.d.ts.map

package/dist/tilemap-register-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tilemap-register-validate.d.ts","sourceRoot":"","sources":["../src/tilemap-register-validate.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EAAqB,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAetE;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,YAAY,GAC1B,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAkB1B;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,YAAY,GACxB,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CA4B1B"}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@forgeax/engine-runtime",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Renderer + Backend (WebGPU/WebGL2) async factory entry for forgeax-engine.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./internal/renderer-host": {
+      "types": "./dist/renderer-host.d.ts",
+      "import": "./dist/renderer-host.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-animation": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-assets-runtime": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-audio-webaudio": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-codec": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-debug-draw": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-font": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-geometry": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-graphics-extras": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-image": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-input": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-math": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-pack": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-profiler": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-render": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-render-graph": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi-null": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi-webgpu": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi-wgpu": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-scene": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-shader": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-skinning": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-vfx": "0.0.0-dev.8d955ade1c79"
+  },
+  "devDependencies": {
+    "@forgeax/engine-import": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-naga": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-state": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-vite-plugin-shader": "0.0.0-dev.8d955ade1c79",
+    "@types/node": "^20.14.0"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip",
+        "expected": 93148
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "renderer entry without bundled canvas; fps reported by hello-triangle / hello-cube apps that consume the renderer"
+      },
+      "bench": {
+        "enabled": true,
+        "reportPath": "bench-result.json",
+        "suite": "@forgeax/engine-runtime",
+        "baseline": {
+          "source": "inline",
+          "threshold": 5000000
+        }
+      },
+      "gate": {
+        "enabled": true,
+        "reason": "node scripts/forgeax/check-pipeline-vocabulary-isolation.mjs"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "bench": "vitest bench --run",
+    "test:bench": "vitest bench --run",
+    "bench:json": "FORGEAX_BENCH=fast vitest bench --run --outputJson bench-result.json",
+    "bench:nineslice": "node ../../scripts/bench/bench-nineslice-100panel.mjs"
+  }
+}

package/src/__tests__/active-camera.unit.test.ts

@@ -0,0 +1,203 @@
+// w7 — ActiveCamera selection logic unit test (TDD red).
+//
+// Covers the engine-neutral "select active camera by entity ID" mechanism
+// (plan-strategy D-2). The engine knows only entity IDs; it does NOT carry
+// any editor/game semantic. Four scenarios:
+//   (1) ActiveCamera resource present + entity valid -> that camera selected.
+//   (2) ActiveCamera resource absent -> fall back to existing first-hit
+//       (archetype query first [Camera,Transform,Entity]).
+//   (3) ActiveCamera.entity points to a non-existent entity -> fall back to
+//       first-hit (same as absent).
+//   (4) Single-camera scene + ActiveCamera pointing at it -> selection
+//       unchanged (backward compatibility).
+//
+// Two layers of assertion:
+//   A. The pure selection helper `selectActiveCameraIndex` (no World/WebGPU).
+//   B. Integration through `extractFrame` -> `frame.cameras` ordering/length.
+//
+// Anchors:
+//   plan-tasks.json w7: ActiveCamera selection logic unit test
+//   requirements AC-12: per camera-entity-ID runtime selection, hard cut
+//   requirements OOS-4: engine layer zero editor concept (selection by entity
+//     ID, not editor/game semantics)
+//   research Finding 4: engine selects camera by archetype first-hit, no
+//     active-camera resource/marker/setter
+//   plan-strategy D-2: engine renderer gains neutral by-entity-ID active
+//     camera capability; resource absent -> first-hit fallback (backward compat)
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Camera } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { ShaderRegistry, type ShaderRegistryDevice } from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+import {
+  ACTIVE_CAMERA_KEY,
+  getActiveCamera,
+  selectActiveCameraIndex,
+  setActiveCamera,
+} from '../../../render/src/systems/active-camera';
+
+// ── Fixtures ─────────────────────────────────────────────────────────────────
+
+function identityTransform(): {
+  pos: number[];
+  quat: number[];
+  scale: number[];
+} {
+  return { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] };
+}
+
+function makeAssets(): AssetRegistry {
+  const mockDevice: ShaderRegistryDevice = {
+    createShaderModule() {
+      return {
+        ok: true,
+        value: undefined,
+        unwrap: () => undefined,
+        unwrapOr: (d: unknown) => d,
+      } as unknown as ReturnType<ShaderRegistryDevice['createShaderModule']>;
+    },
+  };
+  return new AssetRegistry(new ShaderRegistry({ device: mockDevice, manifestUrl: undefined }));
+}
+
+/** Spawn a Camera entity with a distinguishing fov so snapshots are identifiable. */
+function spawnCamera(world: World, fov: number): number {
+  const res = world.spawn(
+    { component: Transform, data: identityTransform() },
+    {
+      component: Camera,
+      data: {
+        fov,
+        aspect: 1.0,
+        near: 0.1,
+        far: 100.0,
+        projection: 0,
+        left: -1,
+        right: 1,
+        bottom: -1,
+        top: 1,
+      },
+    },
+  );
+  expect(res.ok).toBe(true);
+  return res.unwrap() as unknown as number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Layer A — pure selection helper
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('w7 — selectActiveCameraIndex (pure)', () => {
+  it('(1) active entity present in list -> returns its index', () => {
+    expect(selectActiveCameraIndex([10, 20, 30], 20)).toBe(1);
+    expect(selectActiveCameraIndex([10, 20, 30], 30)).toBe(2);
+    expect(selectActiveCameraIndex([10, 20, 30], 10)).toBe(0);
+  });
+
+  it('(2) active entity undefined -> returns -1 (first-hit fallback)', () => {
+    expect(selectActiveCameraIndex([10, 20, 30], undefined)).toBe(-1);
+  });
+
+  it('(3) active entity not in list -> returns -1 (first-hit fallback)', () => {
+    expect(selectActiveCameraIndex([10, 20, 30], 999)).toBe(-1);
+  });
+
+  it('(4) single-element list + active points at it -> returns 0', () => {
+    expect(selectActiveCameraIndex([42], 42)).toBe(0);
+  });
+
+  it('empty list -> -1 regardless of active', () => {
+    expect(selectActiveCameraIndex([], 1)).toBe(-1);
+    expect(selectActiveCameraIndex([], undefined)).toBe(-1);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Layer A' — resource helpers
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('w7 — getActiveCamera / setActiveCamera', () => {
+  it('absent resource -> getActiveCamera returns undefined', () => {
+    const world = new World();
+    expect(getActiveCamera(world)).toBeUndefined();
+  });
+
+  it('setActiveCamera writes a resource readable by getActiveCamera', () => {
+    const world = new World();
+    setActiveCamera(world, 77);
+    expect(getActiveCamera(world)).toEqual({ entity: 77 });
+    expect(
+      (world as unknown as { hasResource(k: string): boolean }).hasResource(ACTIVE_CAMERA_KEY),
+    ).toBe(true);
+  });
+
+  it('setActiveCamera overwrites previous (idempotent last-write-wins)', () => {
+    const world = new World();
+    setActiveCamera(world, 1);
+    setActiveCamera(world, 2);
+    expect(getActiveCamera(world)).toEqual({ entity: 2 });
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Layer B — integration through extractFrame
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe('w7 — extractFrame ActiveCamera selection', () => {
+  it('(2) no ActiveCamera + multiple cameras -> all cameras surface (first-hit fallback preserved)', () => {
+    const world = new World();
+    const assets = makeAssets();
+    spawnCamera(world, 1.0);
+    spawnCamera(world, 2.0);
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    // No selection -> existing behavior: both cameras flow through; record
+    // stage fires multi-camera diagnostic + uses first hit. We assert extract
+    // does NOT prune when there is no ActiveCamera.
+    expect(frame.cameras.length).toBe(2);
+  });
+
+  it('(1) ActiveCamera pointing at 2nd camera -> only that camera surfaces', () => {
+    const world = new World();
+    const assets = makeAssets();
+    spawnCamera(world, 1.0);
+    const cam2 = spawnCamera(world, 2.0);
+    setActiveCamera(world, cam2);
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    // Active camera resolved -> sole snapshot (no multi-camera diagnostic).
+    expect(frame.cameras.length).toBe(1);
+    expect(frame.cameras[0]?.fov).toBeCloseTo(2.0, 5);
+  });
+
+  it('(3) ActiveCamera pointing at non-existent entity -> fallback to first-hit (all cameras)', () => {
+    const world = new World();
+    const assets = makeAssets();
+    spawnCamera(world, 1.0);
+    spawnCamera(world, 2.0);
+    setActiveCamera(world, 999999);
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    // Unresolvable -> behave as if no ActiveCamera (do not prune).
+    expect(frame.cameras.length).toBe(2);
+  });
+
+  it('(4) single camera + ActiveCamera pointing at it -> behavior unchanged (one camera)', () => {
+    const world = new World();
+    const assets = makeAssets();
+    const cam = spawnCamera(world, 1.5);
+    setActiveCamera(world, cam);
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    expect(frame.cameras.length).toBe(1);
+    expect(frame.cameras[0]?.fov).toBeCloseTo(1.5, 5);
+  });
+
+  it('(4-regression) single camera + NO ActiveCamera -> one camera (backward compat)', () => {
+    const world = new World();
+    const assets = makeAssets();
+    spawnCamera(world, 0.9);
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+    expect(frame.cameras.length).toBe(1);
+    expect(frame.cameras[0]?.fov).toBeCloseTo(0.9, 5);
+  });
+});

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

@@ -0,0 +1,67 @@
+// feat-20260713-animation-state-machine-plugin M3 / w18 — Add non-normalizing
+// (AC-05).
+//
+// AC-05: Add(base, additive@0.3) stacks the additive layer on top of the base
+// WITHOUT normalization. With a base subtree whose effective weight is 1 and an
+// additive clip at static weight 0.3, the derived slot weights total 1.3 — the
+// hallmark of additive (non-normalizing) blending vs. Blend (which would force
+// the total back to 1).
+//
+// TDD red anchor: before w24 + w25 the file fails to compile; after them the
+// Add node leaves the total at 1.3.
+
+import {
+  AnimationPlayer,
+  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) {
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  return world.allocSharedRef('AnimationClip', clip);
+}
+
+const lookupClip = (_guid: string): AnimationClip => ({
+  kind: 'animation-clip',
+  duration: 10,
+  channels: [],
+});
+
+function readWeights(world: World, e: EntityHandle): Float32Array {
+  return (world.get(e, AnimationPlayer).unwrap() as unknown as { weights: Float32Array }).weights;
+}
+
+describe('evaluateAnimationGraph — Add non-normalizing (M3 / w18)', () => {
+  it('Add(base@1, additive@0.3) totals 1.3 (additive is NOT normalized)', () => {
+    const world = new World();
+    registerClip(world, 10);
+    registerClip(world, 10);
+
+    const built = defineAnimationGraph((b) => {
+      const baseNode = b.clip('test/animation-clip-base'); // static weight 1
+      const additiveNode = b.clip('test/animation-clip-additive', 0.3); // static weight 0.3
+      return b.add(baseNode, [additiveNode]);
+    });
+    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 weights = readWeights(world, e);
+    expect(weights.length).toBe(2);
+    // slot 0 = base (unchanged effective weight 1), slot 1 = additive (0.3).
+    expect(weights[0]).toBeCloseTo(1, 5);
+    expect(weights[1]).toBeCloseTo(0.3, 5);
+    const total = (weights[0] ?? 0) + (weights[1] ?? 0);
+    expect(total).toBeCloseTo(1.3, 5);
+  });
+});

package/src/__tests__/animation-graph-asset-union.test-d.ts

@@ -0,0 +1,83 @@
+// feat-20260713-animation-state-machine-plugin M2 / w12 — AnimationGraph enters
+// the closed Asset union (AC-14 foundation, type level).
+//
+// AC-14 (foundation): AnimationGraph joins @forgeax/engine-types' closed `Asset`
+// union with `kind: 'animation-graph'` and a GUID-addressable identity (like
+// AnimationClip / MaterialAsset). This test-d asserts, at compile time:
+//   - the payload shape (kind discriminant + nodes + root),
+//   - Asset narrows to AnimationGraph on `kind === 'animation-graph'` with NO
+//     `as` assertion at a real consumption call point,
+//   - an exhaustive `switch (asset.kind)` covers the new arm without default,
+//   - TagOf<AnimationGraph> resolves to 'AnimationGraph' (register<T> returns
+//     Handle<'AnimationGraph', 'shared'>).
+//
+// TDD red anchor: AnimationGraph is not in the Asset union before w13; the
+// imports do not resolve and the exhaustive switch's `never` default fails to
+// compile. After w13 all assertions hold.
+
+import type { AnimationGraph, Asset, TagOf } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+
+describe('AnimationGraph POD in the Asset union (M2 / w12)', () => {
+  it('type-level: payload shape — kind discriminant + nodes + root', () => {
+    expectTypeOf<AnimationGraph['kind']>().toEqualTypeOf<'animation-graph'>();
+    expectTypeOf<AnimationGraph['root']>().toEqualTypeOf<number>();
+    expectTypeOf<AnimationGraph['nodes']>().toExtend<readonly unknown[]>();
+  });
+
+  it('type-level: Asset narrows to AnimationGraph on kind, no `as` assertion', () => {
+    function narrow(a: Asset): AnimationGraph | undefined {
+      if (a.kind === 'animation-graph') return a; // no `as` — kind discriminant narrows
+      return undefined;
+    }
+    expectTypeOf(narrow).returns.toEqualTypeOf<AnimationGraph | undefined>();
+  });
+
+  it('type-level: exhaustive switch on Asset.kind includes the animation-graph arm', () => {
+    function classify(a: Asset): string {
+      switch (a.kind) {
+        case 'mesh':
+          return 'mesh';
+        case 'texture':
+          return 'texture';
+        case 'equirect':
+          return 'equirect';
+        case 'sampler':
+          return 'sampler';
+        case 'material':
+          return 'material';
+        case 'scene':
+          return 'scene';
+        case 'skeleton':
+          return 'skeleton';
+        case 'skin':
+          return 'skin';
+        case 'animation-clip':
+          return 'animation-clip';
+        case 'animation-graph':
+          return 'animation-graph';
+        case 'audio':
+          return 'audio';
+        case 'font':
+          return 'font';
+        case 'render-pipeline':
+          return 'render-pipeline';
+        case 'tileset':
+          return 'tileset';
+        case 'video':
+          return 'video';
+        case 'particle-effect':
+          return 'particle-effect';
+        default: {
+          const _exhaustive: never = a;
+          return _exhaustive;
+        }
+      }
+    }
+    expectTypeOf(classify).returns.toEqualTypeOf<string>();
+  });
+
+  it('type-level: TagOf<AnimationGraph> resolves to "AnimationGraph"', () => {
+    expectTypeOf<TagOf<AnimationGraph>>().toEqualTypeOf<'AnimationGraph'>();
+  });
+});

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

@@ -0,0 +1,66 @@
+// feat-20260713-animation-state-machine-plugin M3 / w17 — Blend normalization
+// (AC-04).
+//
+// AC-04: Blend(Walk@1, Run@1) evaluates its children with NORMALIZED effective
+// weights so they sum to 1 — the two equal-weight leaves each land at 0.5. The
+// derived N-slot columns are filled leaf-node-first (construction order), so
+// slot 0 = Walk, slot 1 = Run, both at ~0.5.
+//
+// TDD red anchor: before w24 (AnimationPlayer.graph field) + w25
+// (evaluateAnimationGraph) the file fails to compile; after them the blend
+// normalizes to [0.5, 0.5].
+
+import {
+  AnimationPlayer,
+  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) {
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  return world.allocSharedRef('AnimationClip', clip);
+}
+
+const lookupClip = (_guid: string): AnimationClip => ({
+  kind: 'animation-clip',
+  duration: 10,
+  channels: [],
+});
+
+function readWeights(world: World, e: EntityHandle): Float32Array {
+  return (world.get(e, AnimationPlayer).unwrap() as unknown as { weights: Float32Array }).weights;
+}
+
+describe('evaluateAnimationGraph — Blend normalization (M3 / w17)', () => {
+  it('Blend(Walk@1, Run@1) yields weights ~= [0.5, 0.5]', () => {
+    const world = new World();
+    registerClip(world, 10);
+    registerClip(world, 10);
+
+    const built = defineAnimationGraph((b) => {
+      const walkNode = b.clip('test/animation-clip-walk'); // static weight default 1
+      const runNode = b.clip('test/animation-clip-run'); // static weight default 1
+      return b.blend([walkNode, runNode]);
+    });
+    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 weights = readWeights(world, e);
+    expect(weights.length).toBe(2);
+    expect(weights[0]).toBeCloseTo(0.5, 5);
+    expect(weights[1]).toBeCloseTo(0.5, 5);
+    // Blend normalizes: the two leaf effective weights sum to exactly 1.
+    expect((weights[0] ?? 0) + (weights[1] ?? 0)).toBeCloseTo(1, 5);
+  });
+});