@forgeax/engine-runtime 0.1.25 → 0.1.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-runtime",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -26,37 +26,37 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-animation": "0.1.25",
-    "@forgeax/engine-assets-runtime": "0.1.25",
-    "@forgeax/engine-audio-webaudio": "0.1.25",
-    "@forgeax/engine-codec": "0.1.25",
-    "@forgeax/engine-debug-draw": "0.1.25",
-    "@forgeax/engine-ecs": "0.1.25",
-    "@forgeax/engine-font": "0.1.25",
-    "@forgeax/engine-geometry": "0.1.25",
-    "@forgeax/engine-graphics-extras": "0.1.25",
-    "@forgeax/engine-image": "0.1.25",
-    "@forgeax/engine-input": "0.1.25",
-    "@forgeax/engine-math": "0.1.25",
-    "@forgeax/engine-pack": "0.1.25",
-    "@forgeax/engine-profiler": "0.1.25",
-    "@forgeax/engine-render": "0.1.25",
-    "@forgeax/engine-render-graph": "0.1.25",
-    "@forgeax/engine-rhi": "0.1.25",
-    "@forgeax/engine-rhi-null": "0.1.25",
-    "@forgeax/engine-rhi-webgpu": "0.1.25",
-    "@forgeax/engine-rhi-wgpu": "0.1.25",
-    "@forgeax/engine-scene": "0.1.25",
-    "@forgeax/engine-shader": "0.1.25",
-    "@forgeax/engine-skinning": "0.1.25",
-    "@forgeax/engine-types": "0.1.25",
-    "@forgeax/engine-vfx": "0.1.25"
+    "@forgeax/engine-animation": "0.1.27",
+    "@forgeax/engine-assets-runtime": "0.1.27",
+    "@forgeax/engine-audio-webaudio": "0.1.27",
+    "@forgeax/engine-codec": "0.1.27",
+    "@forgeax/engine-debug-draw": "0.1.27",
+    "@forgeax/engine-ecs": "0.1.27",
+    "@forgeax/engine-font": "0.1.27",
+    "@forgeax/engine-geometry": "0.1.27",
+    "@forgeax/engine-graphics-extras": "0.1.27",
+    "@forgeax/engine-image": "0.1.27",
+    "@forgeax/engine-input": "0.1.27",
+    "@forgeax/engine-math": "0.1.27",
+    "@forgeax/engine-pack": "0.1.27",
+    "@forgeax/engine-profiler": "0.1.27",
+    "@forgeax/engine-render": "0.1.27",
+    "@forgeax/engine-render-graph": "0.1.27",
+    "@forgeax/engine-rhi": "0.1.27",
+    "@forgeax/engine-rhi-null": "0.1.27",
+    "@forgeax/engine-rhi-webgpu": "0.1.27",
+    "@forgeax/engine-rhi-wgpu": "0.1.27",
+    "@forgeax/engine-scene": "0.1.27",
+    "@forgeax/engine-shader": "0.1.27",
+    "@forgeax/engine-skinning": "0.1.27",
+    "@forgeax/engine-types": "0.1.27",
+    "@forgeax/engine-vfx": "0.1.27"
   },
   "devDependencies": {
-    "@forgeax/engine-import": "0.1.25",
-    "@forgeax/engine-naga": "0.1.25",
-    "@forgeax/engine-state": "0.1.25",
-    "@forgeax/engine-vite-plugin-shader": "0.1.25",
+    "@forgeax/engine-import": "0.1.27",
+    "@forgeax/engine-naga": "0.1.27",
+    "@forgeax/engine-state": "0.1.27",
+    "@forgeax/engine-vite-plugin-shader": "0.1.27",
     "@types/node": "^20.14.0"
   },
   "forgeax": {

package/src/__tests__/dawn/material-cooked-fixture.dawn.test.ts

@@ -5,7 +5,9 @@ import { describe, expect, it } from 'vitest';
 type CookedRecord = {
   readonly specializationKey: string;
   readonly artifactDigest: string;
-  readonly artifact: { readonly digest: string; readonly bytes: readonly number[] };
+  readonly programs: readonly {
+    readonly artifact: { readonly digest: string; readonly bytes: readonly number[] };
+  }[];
   readonly resolved?: {
     readonly values?: unknown;
   };
@@ -54,9 +56,9 @@ describe('custom-shader cooked MaterialAsset fixture', () => {
     const cookedRecords = [root?.payload.cooked, derived?.payload.cooked];
     for (const cooked of cookedRecords) {
       expect(cooked).toBeDefined();
-      expect(cooked?.artifact?.digest).toMatch(/^sha256:/);
-      expect(cooked?.artifact?.digest).toBe(cooked?.artifactDigest);
-      expect(cooked?.receipt?.schemaVersion).toBe('material-cook/3');
+      expect(cooked?.programs?.[0]?.artifact?.digest).toMatch(/^sha256:/);
+      expect(cooked?.artifactDigest).toMatch(/^sha256:/);
+      expect(cooked?.receipt?.schemaVersion).toBe('material-cook/4');
       expect(cooked?.receipt?.identity?.layoutIdentity).toMatch(/^sha256-/);
       expect(cooked?.receipt?.identity?.programIdentity).toMatch(/^sha256:/);
       expect(cooked?.receipt?.identity?.pipelineIdentity).toMatch(/^sha256:/);
@@ -67,7 +69,9 @@ describe('custom-shader cooked MaterialAsset fixture', () => {
       root?.payload.cooked?.specializationKey,
     );
     expect(derived?.payload.cooked?.artifactDigest).toBe(root?.payload.cooked?.artifactDigest);
-    expect(derived?.payload.cooked?.artifact?.bytes).toEqual(root?.payload.cooked?.artifact?.bytes);
+    expect(derived?.payload.cooked?.programs?.[0]?.artifact?.bytes).toEqual(
+      root?.payload.cooked?.programs?.[0]?.artifact?.bytes,
+    );
     expect(root?.payload.cooked?.resolved?.values).toMatchObject({
       baseColor: [0.95, 0.45, 0.2, 1],
       time: 0,
@@ -82,7 +86,7 @@ describe('custom-shader cooked MaterialAsset fixture', () => {
 
   it('keeps cooked layout identity and authored coordinate transforms', () => {
     const cooked = root?.payload.cooked;
-    expect(cooked?.receipt?.schemaVersion).toBe('material-cook/3');
+    expect(cooked?.receipt?.schemaVersion).toBe('material-cook/4');
     expect(cooked?.receipt?.identity?.layoutIdentity).toMatch(/^sha256-/);
     expect(cooked?.receipt?.identity?.programIdentity).toMatch(/^sha256:/);
     expect(cooked?.receipt?.identity?.pipelineIdentity).toMatch(/^sha256:/);

package/src/__tests__/fixtures/material-programs/center-right.wgsl

@@ -0,0 +1,15 @@
+#define_import_path regression::center_right
+#import forgeax_material::parameters::{material}
+struct Input { @location(0) position: vec3<f32> }
+@vertex fn vs_main(input: Input) -> @builtin(position) vec4<f32> {
+  return vec4<f32>(input.position.xy * 0.4, 0.5, 1.0);
+}
+@vertex fn vs_right(input: Input) -> @builtin(position) vec4<f32> {
+  return vec4<f32>(input.position.xy * 0.4 + vec2<f32>(0.6, 0.0), 0.5, 1.0);
+}
+@fragment fn fs_main() -> @location(0) vec4<f32> {
+  return vec4<f32>(0.0, material.strength, 0.0, 1.0);
+}
+@fragment fn fs_blue() -> @location(0) vec4<f32> {
+  return vec4<f32>(0.0, 0.0, material.strength, 1.0);
+}

package/src/__tests__/fixtures/material-programs/left.wgsl

@@ -0,0 +1,9 @@
+#define_import_path regression::left
+#import forgeax_material::parameters::{material}
+struct Input { @location(0) position: vec3<f32> }
+@vertex fn vs_main(input: Input) -> @builtin(position) vec4<f32> {
+  return vec4<f32>(input.position.xy * 0.4 + vec2<f32>(-0.6, 0.0), 0.5, 1.0);
+}
+@fragment fn fs_main() -> @location(0) vec4<f32> {
+  return vec4<f32>(material.strength, 0.0, 0.0, 1.0);
+}

package/src/__tests__/instances-renderer-lifecycle.integration.test.ts

@@ -45,6 +45,9 @@ function matrices(x: number, count = 1): Float32Array {
   return result;
 }
 
+// Coverage instrumentation plus a contended heavy runner can make the
+// 20,000-instance recovery case exceed the normal one-minute budget even
+// though the operation remains bounded and completes quickly uninstrumented.
 it.each([
   1, 129, 20000,
 ])('renders %i World instances after replacing and recovering the Renderer', async (count) => {
@@ -158,4 +161,4 @@ it.each([
   expect(retained[(count - 1) * 16 + 12]).toBe(finalX);
   expect(b.inspect().instanceCollections[0]?.count).toBe(count);
   await b.dispose();
-}, 60000);
+}, 120_000);

package/src/__tests__/loader-extract-graceful.test.ts

@@ -99,24 +99,25 @@ describe('loader-extract graceful handoff (M4 w24)', () => {
     expect('baseColorTexture' in pv).toBe(false);
   });
 
-  it('(3) shader NOT registered (R-4 cross-worktree) -> graceful "try every int" fallback', () => {
-    // No paramSchema lookup available -> getMaterialShaderTextureFieldNames
-    // returns undefined for every shader id.
+  it('(3) shader NOT registered (R-4 cross-worktree) -> graceful structured texture fallback', () => {
+    // No paramSchema lookup is available, so the loader cannot classify bare
+    // integers as texture refs. Explicit structured texture values remain
+    // resolvable across worktrees without guessing at scalar fields.
     const ctx = makeCtx({
       shaderTextureFieldNames: () => undefined,
     });
     const out = materialLoader.load(
       {
         passes: [{ program: { module: 'forgeax::user-defined' } }],
-        values: { customTexture: 0 },
+        values: { customTexture: { texture: 0 } },
       },
       ['tex-guid'],
       ctx,
     );
     expect(out).toMatchObject({ kind: 'material' });
     const pv = (out as { values: Record<string, unknown> }).values;
-    // Graceful fallback resolves any in-range int to its refs[] GUID string.
-    expect(pv.customTexture).toBe('tex-guid');
+    // Explicit structured refs resolve to the enclosing refs[] GUID.
+    expect(pv.customTexture).toEqual({ texture: 'tex-guid' });
   });
 
   it('(4) shader registered + scalar paramValue with refs[] index in range -> NOT misclassified', () => {

package/src/__tests__/loader-registry.cases.unit.test.ts

@@ -546,29 +546,22 @@ type __MergedKeep =
       expect(out).toMatchObject({ kind: 'material', parentGuid: 'parent-guid' });
     });
 
-    it('materialLoader resolves heightTexture from refs index to its GUID (M4 / w22, D-19)', () => {
-      // feat-20260613-material-paramschema-driven-binding M4 / w22:
-      // the legacy hardcoded texture-field allowlist Set has been deleted.
-      // When the shader is not yet registered (mock ctx returns undefined
-      // from getMaterialShaderTextureFieldNames), the loader falls back to
-      // a graceful "try every int paramValue in [0, refs.length)" walk and
-      // resolves heightTexture (any field name) to the refs[] entry.
-      //
-      // feat-20260614 M8 (D-19): the embedded sub-asset ref is stored as its
-      // GUID string verbatim (dash-form) -- the ECS/render side resolves the
-      // GUID -> column handle at use time via world.allocSharedRef; the loader
-      // no longer mints a numeric handle (resolveRefSync is deleted). Mirrors
-      // the sibling `parentGuid` contract (refs index -> GUID string).
+    it('materialLoader resolves an explicit heightTexture ref index to its GUID (M4 / w22, D-19)', () => {
+      // Texture references use the explicit `{ texture: refsIndex }` wire
+      // shape. This remains safe when the shader is not registered because
+      // the loader does not guess whether a bare integer is a scalar.
       const out = materialLoader.load(
         {
           passes: [{ shader: 'test' }],
-          values: { heightTexture: 0 },
+          values: { heightTexture: { texture: 0 } },
         },
         ['height-guid'],
         mockCtx(),
       );
       expect(out).toMatchObject({ kind: 'material' });
-      expect((out as Record<string, unknown>)?.values?.heightTexture).toBe('height-guid');
+      expect((out as Record<string, unknown>)?.values?.heightTexture).toEqual({
+        texture: 'height-guid',
+      });
     });
 
     it('materialLoader returns normally when values has no heightTexture field', () => {

package/src/__tests__/material-programs.browser.test.ts

@@ -0,0 +1,145 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { page } from 'vitest/browser';
+import { constructRuntimeRendererHost } from '../renderer-host';
+import { drawPublished } from './draw-published';
+
+it.each([
+  false,
+  true,
+])('draws every selected material Pass with mixed blending=%s', async (mixed) => {
+  if (!navigator.gpu) throw new Error('WebGPU is required');
+  const canvas = document.createElement('canvas');
+  canvas.width = 384;
+  canvas.height = 256;
+  document.body.append(canvas);
+  const requestAdapter = navigator.gpu.requestAdapter.bind(navigator.gpu);
+  const validation: string[] = [];
+  const entries: string[] = [];
+  const devices: GPUDevice[] = [];
+  navigator.gpu.requestAdapter = async (options) => {
+    const adapter = await requestAdapter(options);
+    if (adapter === null) return adapter;
+    const requestDevice = adapter.requestDevice.bind(adapter);
+    adapter.requestDevice = async (descriptor) => {
+      const device = await requestDevice(descriptor);
+      devices.push(device);
+      device.addEventListener('uncapturederror', (event) => validation.push(event.error.message));
+      const record = (descriptor: GPURenderPipelineDescriptor) =>
+        entries.push(`${descriptor.vertex.entryPoint}/${descriptor.fragment?.entryPoint}`);
+      const create = device.createRenderPipeline.bind(device);
+      device.createRenderPipeline = (descriptor) => {
+        record(descriptor);
+        return create(descriptor);
+      };
+      const createAsync = device.createRenderPipelineAsync.bind(device);
+      device.createRenderPipelineAsync = async (descriptor) => {
+        record(descriptor);
+        return createAsync(descriptor);
+      };
+      return device;
+    };
+    return adapter;
+  };
+  const host = await constructRuntimeRendererHost(
+    canvas,
+    {},
+    { shaderManifestUrl: '/shaders/manifest.json' },
+  );
+  if (!host.ok) {
+    navigator.gpu.requestAdapter = requestAdapter;
+    canvas.remove();
+    throw host.error;
+  }
+  const errors: string[] = [];
+  const unsubscribe = host.value.renderer.subscribe((event) => {
+    if (event.kind === 'error') errors.push(event.error.message);
+  });
+  try {
+    const assets = host.value.assets;
+    assets.configurePackIndex(
+      mixed ? '/__material-programs-mixed/pack-index.json' : '/__material-programs/pack-index.json',
+    );
+    const material = (
+      await assets.loadByGuid<MaterialAsset>(
+        assets.parseGuid('8f50ae65-6e0a-40b4-8949-b47006edab90'),
+      )
+    ).unwrap();
+    const projection = assets.getMaterialProjectionForPayload(material);
+    expect(
+      new Set(
+        projection?.passes.flatMap((pass) =>
+          pass.programs.map((program) => program.specializationKey),
+        ),
+      ).size,
+    ).toBe(2);
+    const world = new World();
+    const handle = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', material);
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 3], scale: [1, 1, 1], quat: [0, 0, 0, 1] } },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 1.5,
+            near: 0.1,
+            far: 100,
+            clearColor: [0.02, 0.02, 0.02, 1],
+          },
+        },
+      )
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 0], scale: [1, 1, 1], quat: [0, 0, 0, 1] } },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        { component: MeshRenderer, data: { materials: [handle] } },
+      )
+      .unwrap();
+    for (let frame = 0; frame < 40; frame++) {
+      const receipt = drawPublished(host.value.renderer, world);
+      if (!receipt.ok) throw receipt.error;
+      const completed = await receipt.value.completed;
+      if (!completed.ok) throw completed.error;
+      await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+    }
+    await Promise.all(devices.map((device) => device.queue.onSubmittedWorkDone()));
+    const shot = await page.elementLocator(canvas).screenshot({ base64: true });
+    const bytes = Uint8Array.from(atob(typeof shot === 'string' ? shot : shot.base64), (char) =>
+      char.charCodeAt(0),
+    );
+    const bitmap = await createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+    const surface = new OffscreenCanvas(bitmap.width, bitmap.height);
+    const ctx = surface.getContext('2d');
+    if (ctx === null) throw new Error('pixel readback unavailable');
+    ctx.drawImage(bitmap, 0, 0);
+    bitmap.close();
+    const pixels = ctx.getImageData(0, 0, surface.width, surface.height);
+    for (const [fraction, channel] of [
+      [0.2, 0],
+      [0.5, 1],
+      [0.8, 2],
+    ] as const) {
+      const offset =
+        (Math.floor(surface.height * 0.5) * surface.width + Math.floor(surface.width * fraction)) *
+        4;
+      const color = [...pixels.data.slice(offset, offset + 3)];
+      expect(color[channel], `Pass color at ${fraction}: ${color}`).toBeGreaterThan(200);
+      expect(color.filter((_, index) => index !== channel).every((value) => value < 40)).toBe(true);
+    }
+    expect(entries).toContain('vs_right/fs_blue');
+    expect(validation).toEqual([]);
+    expect(errors).toEqual([]);
+  } finally {
+    unsubscribe();
+    host.value.renderer.dispose();
+    for (const device of devices) device.destroy();
+    navigator.gpu.requestAdapter = requestAdapter;
+    canvas.remove();
+  }
+}, 60_000);

package/src/__tests__/materials.unit.test.ts

@@ -80,10 +80,10 @@ describe('Materials.standard multi-pass (w14)', () => {
       expect(shadowPass).toBeDefined();
     });
 
-    it('shadow-caster pass uses forgeax_material::standard shader', () => {
+    it('shadow-caster pass uses the canonical depth-only shader', () => {
       const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
       const shadowPass = mat.passes?.find((p) => p.name === ('shadow-caster' as PassKind));
-      expect(shadowPass?.program.module).toBe('forgeax_material::standard');
+      expect(shadowPass?.program.module).toBe('forgeax::default-shadow-caster');
     });
 
     it('castShadow=false suppresses the shadow-caster pass', () => {

package/src/__tests__/pipeline-cache-keying.unit.test.ts

@@ -53,6 +53,18 @@ function specOf(
 describe('cacheKeyOf passKind dimension', () => {
   const SHADER_ID = 'forgeax::default-unlit';
 
+  it('separates authored entry selections within one published module', () => {
+    const base = specOf('custom::two-entries', false);
+    const first = {
+      ...base,
+      shader: { ...base.shader, vertexEntry: 'vs_main', fragmentEntry: 'fs_main' },
+    };
+    const second = { ...base, shader: { ...first.shader, fragmentEntry: 'fs_readability' } };
+    const shadow = { ...base, shader: { ...first.shader, vertexEntry: 'vs_shadow' } };
+    expect(new Set([first, second, shadow].map(cacheKeyOf)).size).toBe(3);
+    expect(cacheKeyOf({ ...first })).toBe(cacheKeyOf(first));
+  });
+
   it('same shaderId + entries produce different keys for forward vs shadow-caster', () => {
     const forwardKey = cacheKeyOf(specOf(SHADER_ID, false, 'forward'));
     const shadowKey = cacheKeyOf(specOf(SHADER_ID, false, 'shadow-caster'));

package/src/__tests__/pipeline-spec.test.ts

@@ -490,6 +490,20 @@ describe('buildPipelineDescriptor (M2-T3-TEST)', () => {
     };
   }
 
+  it('uses the entry selection carried by the pipeline spec', () => {
+    const base = makeForwardSpec();
+    const spec: PipelineSpec = {
+      ...base,
+      shader: { ...base.shader, vertexEntry: 'vs_custom', fragmentEntry: 'fs_readability' },
+    };
+    const descriptor = buildPipelineDescriptor(spec, {
+      vertex: mockVertexModule,
+      fragment: mockFragmentModule,
+    });
+    expect(descriptor.vertex.entryPoint).toBe('vs_custom');
+    expect(descriptor.fragment?.entryPoint).toBe('fs_readability');
+  });
+
   function makeShadowCasterSpec(sampleCount: 1 | 4 = 1): PipelineSpec {
     return {
       shader: { id: 'forgeax::shadow-caster', passKind: 'shadow-caster', variantSet: undefined },

package/src/__tests__/propagate-transforms.cases.unit.test.ts

@@ -105,6 +105,7 @@ import type {
 } from '@forgeax/engine-types';
 import { toShared } from '@forgeax/engine-types';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { componentId } from '../../../ecs/src/component';
 import { worldInternal } from '../../../ecs/src/world-internal';
 import {
   SPRITE_PLAYBACK_MODE_CLAMP,
@@ -489,7 +490,10 @@ type __MergedKeep =
       if (archetype === undefined || record === undefined) throw new Error('child row missing');
       const tableRow = archetype.rows[record.archetypeRow];
       if (tableRow === undefined) throw new Error('child table row missing');
-      world[worldInternal].writeRow(archetype, ChildOf, tableRow, { parent: ghost });
+      const table = world[worldInternal].getGraph().tables[archetype.tableId];
+      const parentColumn = table?.storage.get(componentId(ChildOf))?.fields.get('parent');
+      if (parentColumn === undefined) throw new Error('ChildOf.parent column missing');
+      parentColumn.view[tableRow] = ghost as number;
 
       const r = propagateTransforms(world);
       expect(r.ok).toBe(false);

package/src/__tests__/propagate-transforms.dawn.test.ts

@@ -25,6 +25,7 @@ import { World } from '@forgeax/engine-ecs';
 import { readRenderArrayView } from '@forgeax/engine-ecs/projection';
 import { ChildOf, GlobalTransform, propagateTransforms, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { componentId } from '../../../ecs/src/component';
 import { worldInternal } from '../../../ecs/src/world-internal';
 import { TileLayer, Tilemap } from '../../../render/src/components';
 
@@ -258,7 +259,10 @@ describe('propagate-transforms.dawn - root-down DFS + stale ChildOf fail-fast (A
     if (archetype === undefined || record === undefined) throw new Error('orphan row missing');
     const tableRow = archetype.rows[record.archetypeRow];
     if (tableRow === undefined) throw new Error('orphan table row missing');
-    world[worldInternal].writeRow(archetype, ChildOf, tableRow, { parent: ghost });
+    const table = world[worldInternal].getGraph().tables[archetype.tableId];
+    const parentColumn = table?.storage.get(componentId(ChildOf))?.fields.get('parent');
+    if (parentColumn === undefined) throw new Error('ChildOf.parent column missing');
+    parentColumn.view[tableRow] = ghost as number;
 
     const r = propagateTransforms(world);
     expect(r.ok).toBe(false);

package/src/__tests__/record-worldid-isolation.test.ts

@@ -103,7 +103,6 @@ const SPRITE_FILE = fileURLToPath(
 describe('production-path shared instance bind-group resolver', () => {
   it('sprite identity and sprite-instance paths use the shared resolver', () => {
     const src = readFileSync(SPRITE_FILE, 'utf8');
-    expect(src).toContain('const identityInstBg = resolveGeometryInstancesBindGroup(');
     expect(src).toContain('const spriteInstBg = resolveGeometryInstancesBindGroup(');
     expect(src).toContain('const spriteInstancesBg = resolveGeometryInstancesBindGroup(');
   });

package/src/__tests__/render-system-extract.test.ts

@@ -13,6 +13,7 @@ import { AssetGuid } from '@forgeax/engine-pack/guid';
 import {
   Camera,
   DirectionalLight,
+  Materials,
   MeshFilter,
   MeshRenderer,
   PointLight,
@@ -185,6 +186,17 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       const mesh = registerMesh(world);
       const materialGuid = '019ffa97-4000-7000-8000-000000000101';
       const cookedShaderId = 'sha256:rusted-iron-cooked-specialization';
+      const cookedShadowShaderId = 'sha256:rusted-iron-cooked-shadow-specialization';
+      const materialContext = {
+        backend: 'webgpu' as const,
+        capability: 'storage-buffer' as const,
+        pipeline: 'forward' as const,
+        geometry: 'mesh' as const,
+        pass: 'forward' as const,
+        profile: 'forgeax-material-wgsl-v1' as const,
+        toolchain: 'naga-oil' as const,
+        instrumentation: 'none' as const,
+      };
       const material = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
         kind: 'material',
         passes: [
@@ -223,6 +235,26 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
             module: 'forgeax_material::standard',
             moduleSlots: { surface: 'game_3d::rusted_iron_surface' },
             artifactHash: 'sha256:rusted-iron-artifact',
+            programs: [
+              {
+                context: materialContext,
+                specializationKey: cookedShaderId,
+                artifactHash: 'sha256:rusted-iron-forward-artifact',
+              },
+            ],
+          },
+          {
+            name: 'shadow-caster',
+            module: 'forgeax_material::standard',
+            moduleSlots: { surface: 'game_3d::rusted_iron_surface' },
+            artifactHash: 'sha256:rusted-iron-artifact',
+            programs: [
+              {
+                context: { ...materialContext, pass: 'shadow' as const },
+                specializationKey: cookedShadowShaderId,
+                artifactHash: 'sha256:rusted-iron-shadow-artifact',
+              },
+            ],
           },
         ],
         runtimeValues: {},
@@ -236,7 +268,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         )
         .unwrap();
 
-      const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+      const frame = extractFrame(world, prepareExtractContext(world, { assets, materialContext }));
       expect(frame.renderables[0]?.material.materialShaderId).toBe(cookedShaderId);
       const materialDispatch = frame.dispatch.filter((entry) => entry.materialHandle === material);
       expect(materialDispatch).toEqual(
@@ -247,12 +279,58 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
           }),
           expect.objectContaining({
             tags: { LightMode: 'ShadowCaster' },
-            materialShaderId: 'forgeax::default-shadow-caster',
+            materialShaderId: cookedShadowShaderId,
           }),
         ]),
       );
     });
 
+    it('keeps custom Standard Surface fields in the extracted material ABI', () => {
+      const world = new World();
+      spawnCamera(world);
+      const assets = new AssetRegistry(makeMockShaderRegistry());
+      const mesh = registerMesh(world);
+      const material = world.allocSharedRef<'MaterialAsset', MaterialAsset>(
+        'MaterialAsset',
+        Materials.standard({
+          surfaceModule: 'game_3d::rusted_iron_surface',
+          parameters: [
+            { name: 'ironColor', type: 'color' },
+            { name: 'rustDark', type: 'color' },
+            { name: 'rustBright', type: 'color' },
+            { name: 'noiseScale', type: 'f32' },
+          ],
+          values: {
+            ironColor: [0.4, 0.45, 0.47, 1],
+            rustDark: [0.42, 0.085, 0.018, 1],
+            rustBright: [0.95, 0.34, 0.055, 1],
+            noiseScale: 1.85,
+          },
+        }),
+      );
+      world
+        .spawn(
+          { component: Transform, data: { ...identity(), pos: [0, 0, -2] } },
+          { component: MeshFilter, data: { assetHandle: mesh } },
+          { component: MeshRenderer, data: { materials: [material] } },
+        )
+        .unwrap();
+
+      const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+      const snapshot = frame.renderables[0]?.material;
+      const schemaNames = snapshot?.materialParamSchema?.map((entry) => entry.name) ?? [];
+
+      expect(schemaNames).toEqual(
+        expect.arrayContaining(['ironColor', 'rustDark', 'rustBright', 'noiseScale']),
+      );
+      expect(snapshot?.paramSnapshot).toMatchObject({
+        ironColor: [0.4, 0.45, 0.47].map(srgbChannelToLinear).concat(1),
+        rustDark: [0.42, 0.085, 0.018].map(srgbChannelToLinear).concat(1),
+        rustBright: [0.95, 0.34, 0.055].map(srgbChannelToLinear).concat(1),
+        noiseScale: 1.85,
+      });
+    });
+
     it('mesh-walk: RenderableSnapshot.transform.world is the resolved world mat4 (parent x child), zero per-snapshot compose', () => {
       const world = new World();
       world

package/src/__tests__/surface-standard-pipeline.browser.test.ts

@@ -233,11 +233,14 @@ describe('Standard Surface runtime Browser WebGPU provenance', () => {
       const projection = assets.getMaterialProjectionForPayload(material);
       if (surfaceCase.id.startsWith('custom-')) {
         expect(projection?.specializationKey).toBeTruthy();
-        expect(
-          projection === undefined
-            ? undefined
-            : assets.getMaterialArtifact(projection.specializationKey),
-        ).toBeDefined();
+        const programKeys =
+          projection?.passes.flatMap((pass) =>
+            pass.programs.map((program) => program.specializationKey),
+          ) ?? [];
+        expect(programKeys.length).toBeGreaterThan(0);
+        for (const specializationKey of new Set(programKeys)) {
+          expect(assets.getMaterialArtifact(specializationKey)).toBeDefined();
+        }
       }
       materials.push(material);
       publications.push({ surfaceCase, row, publication, material });

package/src/__tests__/weapon-spirit-material.browser.test.ts

@@ -0,0 +1,249 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import {
+  Camera,
+  DirectionalLight,
+  Materials,
+  MeshFilter,
+  MeshRenderer,
+  type Renderer,
+} from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { page } from 'vitest/browser';
+import { constructRuntimeRendererHost } from '../renderer-host';
+import { drawPublished } from './draw-published';
+
+async function readPresentedPixels(canvas: HTMLCanvasElement) {
+  const shot = await page.elementLocator(canvas).screenshot({ base64: true });
+  const base64 = typeof shot === 'string' ? shot : shot.base64;
+  const bytes = Uint8Array.from(atob(base64), (character) => character.charCodeAt(0));
+  const bitmap = await createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+  const surface = new OffscreenCanvas(bitmap.width, bitmap.height);
+  const context = surface.getContext('2d');
+  if (context === null) throw new Error('2D readback is required for pixel assertions');
+  context.drawImage(bitmap, 0, 0);
+  bitmap.close();
+  return context.getImageData(0, 0, surface.width, surface.height);
+}
+
+it.each([
+  false,
+  true,
+])('renders the ai-weapon-spirit child Toon through real WebGPU (Engine shadow: %s)', async (engineShadow) => {
+  if (!navigator.gpu) throw new Error('WebGPU is required for the material regression');
+  const canvas = document.createElement('canvas');
+  canvas.width = 384;
+  canvas.height = 256;
+  document.body.append(canvas);
+  const originalRequestAdapter = navigator.gpu.requestAdapter.bind(navigator.gpu);
+  const validationErrors: string[] = [];
+  const pipelineEntries: string[] = [];
+  const pipelineLabels: string[] = [];
+  const shaderSources = new WeakMap<GPUShaderModule, string>();
+  const shadowPipelineSources: string[] = [];
+  const devices: GPUDevice[] = [];
+  navigator.gpu.requestAdapter = async (options) => {
+    const adapter = await originalRequestAdapter(options);
+    if (adapter === null) return adapter;
+    const requestDevice = adapter.requestDevice.bind(adapter);
+    adapter.requestDevice = async (descriptor) => {
+      const device = await requestDevice(descriptor);
+      devices.push(device);
+      device.addEventListener('uncapturederror', (event) =>
+        validationErrors.push(event.error.message),
+      );
+      const createShaderModule = device.createShaderModule.bind(device);
+      device.createShaderModule = (descriptor) => {
+        const module = createShaderModule(descriptor);
+        shaderSources.set(module, descriptor.code);
+        return module;
+      };
+      const observeShadow = (descriptor: GPURenderPipelineDescriptor) => {
+        if (
+          descriptor.depthStencil?.format === 'depth32float' &&
+          Array.from(descriptor.fragment?.targets ?? []).length === 0
+        ) {
+          const source = shaderSources.get(descriptor.vertex.module);
+          if (source !== undefined) shadowPipelineSources.push(source);
+        }
+      };
+      const createPipeline = device.createRenderPipeline.bind(device);
+      device.createRenderPipeline = (descriptor) => {
+        observeShadow(descriptor);
+        pipelineLabels.push(descriptor.label ?? '<unlabelled>');
+        pipelineEntries.push(descriptor.vertex.entryPoint ?? '<implicit>');
+        return createPipeline(descriptor);
+      };
+      const createPipelineAsync = device.createRenderPipelineAsync.bind(device);
+      device.createRenderPipelineAsync = async (descriptor) => {
+        observeShadow(descriptor);
+        pipelineLabels.push(descriptor.label ?? '<unlabelled>');
+        pipelineEntries.push(descriptor.vertex.entryPoint ?? '<implicit>');
+        return createPipelineAsync(descriptor);
+      };
+      return device;
+    };
+    return adapter;
+  };
+  let renderer: Renderer | undefined;
+  let unsubscribe: (() => void) | undefined;
+  try {
+    const host = await constructRuntimeRendererHost(
+      canvas,
+      {},
+      { shaderManifestUrl: '/shaders/manifest.json' },
+    );
+    if (!host.ok) throw host.error;
+    renderer = host.value.renderer;
+    const errors: string[] = [];
+    unsubscribe = renderer.subscribe((event) => {
+      if (event.kind === 'error') errors.push(event.error.message);
+    });
+    const assets = host.value.assets;
+    assets.configurePackIndex(
+      engineShadow
+        ? '/__weapon-spirit-engine-shadow/pack-index.json'
+        : '/__weapon-spirit/pack-index.json',
+    );
+    const child = await assets.loadByGuid<MaterialAsset>(
+      assets.parseGuid('4846fa5b-8f80-57c0-9cdc-e345102fdb6c'),
+    );
+    if (!child.ok) throw child.error;
+    const readiness = assets.getMaterialReadiness('4846fa5b-8f80-57c0-9cdc-e345102fdb6b');
+    expect(
+      readiness,
+      `root material must publish one complete Ready generation: ${JSON.stringify(readiness)}`,
+    ).toMatchObject({ status: 'Ready' });
+    const projection = assets.getMaterialProjectionForPayload(child.value);
+    const shadowProgram = projection?.passes.find((pass) => pass.name === 'ShadowCaster')
+      ?.programs[0];
+    if (shadowProgram === undefined) throw new Error('published shadow program missing');
+    const shadowArtifact = assets.getMaterialArtifact(shadowProgram.specializationKey);
+    if (shadowArtifact === undefined) throw new Error('installed shadow artifact missing');
+    const expectedShadowSource = new TextDecoder().decode(shadowArtifact.bytes);
+    expect(projection?.specializationKey).toBeTruthy();
+    expect(child.value.values).toMatchObject({
+      emissionStrength: 0,
+      pigmentStrength: 0,
+      surfaceMetallic: 0,
+      sideShade: 0.84,
+    });
+    const world = new World();
+    const toon = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', child.value);
+    const standard = world.allocSharedRef<'MaterialAsset', MaterialAsset>(
+      'MaterialAsset',
+      Materials.standard({ baseColor: [0.6, 0.6, 0.6, 1] }),
+    );
+    const transform = (
+      pos: readonly [number, number, number],
+      scale: readonly [number, number, number] = [1, 1, 1],
+    ) => ({ pos, scale, quat: [0, 0, 0, 1] as const });
+    world
+      .spawn(
+        { component: Transform, data: transform([0, 8, 18]) },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 1.5,
+            near: 0.1,
+            far: 100,
+            clearColor: [0.02, 0.02, 0.03, 1],
+          },
+        },
+      )
+      .unwrap();
+    const light = world
+      .spawn({
+        component: DirectionalLight,
+        data: {
+          direction: [0.25, -1, -0.45],
+          color: [1, 1, 1],
+          intensity: 1,
+          castShadow: true,
+          mapSize: 512,
+          shadowDistance: 50,
+        },
+      })
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: transform([0, 5, 5], [10, 0.1, 10]) },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        { component: MeshRenderer, data: { materials: [standard] } },
+      )
+      .unwrap();
+    for (const [index, material] of [toon, standard, toon].entries()) {
+      world
+        .spawn(
+          { component: Transform, data: transform([(index - 1) * 2, 6, 5]) },
+          { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+          { component: MeshRenderer, data: { materials: [material] } },
+        )
+        .unwrap();
+    }
+    const drawFrames = async (count: number) => {
+      for (let frame = 0; frame < count; frame += 1) {
+        const receipt = drawPublished(host.value.renderer, world);
+        if (!receipt.ok) throw receipt.error;
+        const completed = await receipt.value.completed;
+        if (!completed.ok) throw completed.error;
+        await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+      }
+      await Promise.all(devices.map((device) => device.queue.onSubmittedWorkDone()));
+    };
+    await drawFrames(60);
+    const shadowed = await readPresentedPixels(canvas);
+    world.set(light, DirectionalLight, { castShadow: false }).unwrap();
+    expect(world.get(light, DirectionalLight).unwrap().castShadow).toBe(false);
+    await drawFrames(10);
+    expect(renderer.inspect().perFramePassNames).not.toContain('shadowCascade0');
+    const unshadowed = await readPresentedPixels(canvas);
+    expect([unshadowed.width, unshadowed.height]).toEqual([shadowed.width, shadowed.height]);
+    for (const [startX, endX] of [
+      [0.29, 0.45],
+      [0.55, 0.71],
+    ] as const) {
+      let toonPixels = 0;
+      let shadowPixels = 0;
+      for (let y = 0; y < shadowed.height; y += 1) {
+        for (let x = Math.floor(shadowed.width * startX); x < shadowed.width * endX; x += 1) {
+          const offset = (y * shadowed.width + x) * 4;
+          const red = shadowed.data[offset] ?? 0;
+          const green = shadowed.data[offset + 1] ?? 0;
+          const blue = shadowed.data[offset + 2] ?? 0;
+          if (green > red + 10 && blue > red + 5) toonPixels += 1;
+          // Fixed camera receiver regions under the two Toon cubes exclude
+          // the Standard cube's shadow, so its success cannot mask either caster.
+          if (
+            y > shadowed.height * 0.75 &&
+            y < shadowed.height * 0.85 &&
+            (unshadowed.data[offset] ?? 0) > red + 20
+          )
+            shadowPixels += 1;
+        }
+      }
+      expect(toonPixels, `visible Toon pixels in region ${startX}`).toBeGreaterThan(30);
+      expect(shadowPixels, `shadow contribution in region ${startX}`).toBeGreaterThan(10);
+    }
+    await Promise.all(devices.map((device) => device.queue.onSubmittedWorkDone()));
+    expect(validationErrors, 'raw WebGPU validation messages').toEqual([]);
+    expect(errors, 'renderer errors').toEqual([]);
+    expect(
+      pipelineEntries,
+      `the authored shadow vertex entry must reach a real PSO: ${JSON.stringify(pipelineLabels)}`,
+    ).toContain(engineShadow ? 'vs_main' : 'vs_shadow');
+    expect(
+      shadowPipelineSources,
+      'the published shadow program must reach a depth-only PSO',
+    ).toContain(expectedShadowSource);
+  } finally {
+    navigator.gpu.requestAdapter = originalRequestAdapter;
+    unsubscribe?.();
+    renderer?.dispose();
+    for (const device of devices) device.destroy();
+    canvas.remove();
+  }
+}, 60_000);