@forgeax/engine-runtime 0.1.24 → 0.1.25

package/src/__tests__/point-light-shadow.dawn.test.ts

@@ -14,8 +14,12 @@
 import { describe, expect, it } from 'vitest';
 import { drawPublished } from './draw-published';
 
-const WIDTH = 512;
-const HEIGHT = 512;
+const LIGHTWEIGHT_DAWN = process.env.FORGEAX_DAWN_LIGHTWEIGHT === '1';
+// The comparison-sampler contract only depends on cube topology and depth
+// ordering. Keep the local/nightly 512px atlas for diagnostics, but avoid
+// allocating six 512px lavapipe depth attachments on the overloaded PR lane.
+const WIDTH = LIGHTWEIGHT_DAWN ? 64 : 512;
+const HEIGHT = LIGHTWEIGHT_DAWN ? 64 : 512;
 const LAYERS = 6; // one cube (6 faces)
 
 // WebGPU bitmask constants per spec (avoids needing @webgpu/types globals
@@ -37,6 +41,11 @@ const navWithGpu = globalThis.navigator as unknown as NavigatorWithGpu | undefin
 const dawnReady =
   typeof globalThis.navigator !== 'undefined' && navWithGpu?.gpu?.requestAdapter !== undefined;
 
+// The renderer/readback e2e includes the first full point-shadow setup. Hosted
+// Linux Dawn cold starts can exceed the project-wide 30-second timeout while
+// still completing inside the bounded Dawn job budget.
+const POINT_LIGHT_SHADOW_DAWN_TEST_TIMEOUT_MS = 120_000;
+
 describe('M0 cube_array comparison sampler (dawn)', () => {
   it.skipIf(!dawnReady)("'dawn-binding-missing' -- dawn.node binding injection failed", () => {
     expect(dawnReady).toBe(true);
@@ -536,8 +545,15 @@ async function doReadPixelsM5(
 }
 
 describe('Round-2 F-3 / Issue 3: createRenderer e2e dawn (T-M5-1)', () => {
+  // The isolated fresh-process Dawn lane can spend ~90s constructing the
+  // shader manifest and two renderer states on lavapipe. Keep this owner-
+  // specific budget above that cold-start cost instead of treating a valid
+  // integration probe as a default-30s timeout failure.
   it.skipIf(!dawnReady)(
     "'createRenderer e2e' -- spawn PointLight + PointLightShadow + cube + camera; renderer.draw runs; frame is non-black AND pixel-differs vs no-shadow baseline",
+    {
+      timeout: POINT_LIGHT_SHADOW_DAWN_TEST_TIMEOUT_MS,
+    },
     async () => {
       // Lazy-load the runtime + manifest builder (matches fxaa-pixel-diff
       // pattern). buildEngineShaderManifest produces the data: URL the
@@ -556,8 +572,11 @@ describe('Round-2 F-3 / Issue 3: createRenderer e2e dawn (T-M5-1)', () => {
       const manifestUrl = `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
 
       const TEX_USAGE_E2E = TEX_USAGE_RENDER_ATTACHMENT | TEX_USAGE_COPY_SRC;
-      const FRAME_W = 128;
-      const FRAME_H = 128;
+      // The end-to-end assertion is non-black output, not a resolution
+      // benchmark. Preserve the local 128px target while bounding the PR
+      // readback and point-shadow atlas work on software Vulkan.
+      const FRAME_W = LIGHTWEIGHT_DAWN ? 64 : 128;
+      const FRAME_H = LIGHTWEIGHT_DAWN ? 64 : 128;
 
       let sharedDevice: GPUDevice | undefined;
       const originalRequestAdapter = globalThis.navigator.gpu.requestAdapter.bind(
@@ -762,7 +781,7 @@ describe('Round-2 F-3 / Issue 3: createRenderer e2e dawn (T-M5-1)', () => {
         },
         {
           component: PointLightShadow,
-          data: { mapSize: 256, nearPlane: 0.1, farPlane: 25 },
+          data: { mapSize: LIGHTWEIGHT_DAWN ? 128 : 256, nearPlane: 0.1, farPlane: 25 },
         },
       );
 

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

@@ -45,7 +45,7 @@ function expectWorldEntityKeyAt(
 
   for (let i = start; i < end; i++) {
     const l = lines[i];
-    if (l?.includes('worldEntityKey')) {
+    if (l?.includes('worldEntityKey') || l?.includes('instanceCollectionCacheKey')) {
       // Found — passes
       return;
     }
@@ -156,20 +156,11 @@ const SHADOW_FILE = fileURLToPath(
 );
 
 describe('production-path shadow instanceBuffers worldEntityKey', () => {
-  it('shadowInst.cacheKey get uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
-      SHADOW_FILE,
-      findLine(SHADOW_FILE, 'c.frameState.instanceBuffers.get(', 0),
-      'shadow-pass instanceBuffers.get',
-    );
-  });
-
-  it('shadowInst.cacheKey set uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
-      SHADOW_FILE,
-      findLine(SHADOW_FILE, 'c.frameState.instanceBuffers.set('),
-      'shadow-pass instanceBuffers.set',
-    );
+  it('shares the world-aware geometry instance residency owner', () => {
+    const src = readFileSync(SHADOW_FILE, 'utf8');
+    expect(src).toMatch(/resolveGeometryInstanceBuffer\(\s*c,\s*entry,/);
+    expect(src).not.toContain('instanceBuffers.get(');
+    expect(src).not.toContain('instanceBuffers.set(');
   });
 
   it('spot shadow uses the shared world-aware caster recorder', () => {
@@ -183,16 +174,6 @@ describe('production-path shadow instanceBuffers worldEntityKey', () => {
   });
 });
 
-describe('production-path shadow shared instance bind-group resolver', () => {
-  it('shadow pass resolves the bind group from the world-aware buffer cache', () => {
-    const src = readFileSync(SHADOW_FILE, 'utf8');
-    expect(src).toContain(
-      'const shadowInstancesBg = resolveGeometryInstancesBindGroup(c, shadowInstanceBuffer);',
-    );
-    expect(src).toContain('worldEntityKey(entry.source.worldId, shadowInst.cacheKey)');
-  });
-});
-
 // ── Fold-bucket negative half NOT worldEntityKey (D-1a #1 invariant) ───────
 
 describe('production-path fold-bucket key NOT worldEntityKey', () => {

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

@@ -178,6 +178,81 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       for (const renderable of frame.renderables) expect(renderable.material).toBe(first);
     });
 
+    it('projects the cooked Standard artifact identity into extraction and dispatch', () => {
+      const world = new World();
+      spawnCamera(world);
+      const assets = new AssetRegistry(makeMockShaderRegistry());
+      const mesh = registerMesh(world);
+      const materialGuid = '019ffa97-4000-7000-8000-000000000101';
+      const cookedShaderId = 'sha256:rusted-iron-cooked-specialization';
+      const material = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+        kind: 'material',
+        passes: [
+          {
+            name: 'forward',
+            program: {
+              module: 'forgeax_material::standard',
+              moduleSlots: { surface: 'game_3d::rusted_iron_surface' },
+            },
+            renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+          },
+          {
+            name: 'shadow-caster',
+            program: {
+              module: 'forgeax_material::standard',
+              moduleSlots: { surface: 'game_3d::rusted_iron_surface' },
+            },
+            renderState: { tags: { LightMode: 'ShadowCaster' }, queue: 1000 },
+          },
+        ],
+        parameters: [
+          { name: 'baseColor', type: 'color' },
+          { name: 'metallic', type: 'f32' },
+          { name: 'roughness', type: 'f32' },
+        ],
+        values: { baseColor: [0.4, 0.45, 0.47, 1], metallic: 0.8, roughness: 0.25 },
+      });
+      vi.spyOn(assets, 'getMaterialProjectionForPayload').mockReturnValue({
+        materialGuid,
+        publicationGeneration: 1,
+        specializationKey: cookedShaderId,
+        artifactHash: 'sha256:rusted-iron-artifact',
+        passes: [
+          {
+            name: 'forward',
+            module: 'forgeax_material::standard',
+            moduleSlots: { surface: 'game_3d::rusted_iron_surface' },
+            artifactHash: 'sha256:rusted-iron-artifact',
+          },
+        ],
+        runtimeValues: {},
+        staticSelection: [],
+      });
+      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 }));
+      expect(frame.renderables[0]?.material.materialShaderId).toBe(cookedShaderId);
+      const materialDispatch = frame.dispatch.filter((entry) => entry.materialHandle === material);
+      expect(materialDispatch).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            tags: { LightMode: 'Forward' },
+            materialShaderId: cookedShaderId,
+          }),
+          expect.objectContaining({
+            tags: { LightMode: 'ShadowCaster' },
+            materialShaderId: 'forgeax::default-shadow-caster',
+          }),
+        ]),
+      );
+    });
+
     it('mesh-walk: RenderableSnapshot.transform.world is the resolved world mat4 (parent x child), zero per-snapshot compose', () => {
       const world = new World();
       world
@@ -574,7 +649,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
   ): { handle: Handle<'MaterialAsset', 'shared'>; guid: AssetGuid } {
     const asset: MaterialAsset = {
       kind: 'material',
-      passes,
+      ...(passes === undefined ? {} : { passes }),
       values: values ?? {},
     } as unknown as MaterialAsset;
     if (parentGuid !== undefined) {

package/src/__tests__/shadow-caster-empty-schema.test.ts

@@ -1,16 +1,13 @@
 // @ts-nocheck — node:fs / node:path / node:url imports outside @types/node
 // coverage in runtime tsconfig (mirrors pipeline.unit.test.ts header).
-// shadow-caster-empty-schema.test.ts -- M4 / w21 explicit empty-schema gate.
+// shadow-caster-surface-schema.test.ts -- shared Surface shadow contract.
 //
 // feat-20260613-material-paramschema-driven-binding M4 / w21.
 //
 // Decision anchors (plan-strategy §2 + §3.4):
-//   - D-12  empty schema is graceful: derive([]) -> bglEntries=[],
-//           totalBytes=0, textureFieldNames=empty, samplerForTexture=empty,
-//           userRegionBindingEnd=0. The shadow_caster shader has zero
-//           @group(1) bindings and registers under an empty paramSchema.
-//   - the shadow-caster module has no authored material parameter sidecar;
-//           its empty MaterialAsset parameter list is derived at runtime.
+//   - derive([]) remains a valid generic empty-schema path.
+//   - the shadow-caster module has no authored sidecar; its generated
+//           MaterialParameters contract is the Standard pipeline schema.
 //
 // What this test asserts:
 //   (a) derive([]) produces all-empty / zero output -- the graceful path.
@@ -18,14 +15,13 @@
 //   (c) appendInjection over the empty user-region starts injected
 //       bindings at binding 0 (covered also in append-injection.test.ts;
 //       this test pins the empty-schema path explicitly).
-//   (d) The runtime registers `forgeax::default-shadow-caster` with
-//       paramSchema=[] (createRenderer.ts:3172) -- structural assertion that
-//       no static literal in createRenderer hardcodes a non-empty schema
-//       for this identifier.
+//   (d) The runtime fallback registers `forgeax::default-shadow-caster` with
+//       the shared Standard pipeline schema.
 
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { STANDARD_PIPELINE_PARAM_SCHEMA } from '@forgeax/engine-shader';
 import { derive } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { appendInjection } from '../../../render/src/pbr-pipeline';
@@ -36,7 +32,7 @@ const repoRoot = (() => {
   return join(here, '..', '..', '..', '..');
 })();
 
-describe('shadow_caster empty schema (M4 w21)', () => {
+describe('shadow_caster shared Surface schema', () => {
   it('(a) derive([]) returns all-empty/zero output (D-12 graceful path)', () => {
     const out = derive([]);
     expect(out.bglEntries.length).toBe(0);
@@ -66,7 +62,7 @@ describe('shadow_caster empty schema (M4 w21)', () => {
     expect(injected[0]?.binding).toBe(0);
   });
 
-  it('(d) shadow_caster register call site carries paramSchema: []', () => {
+  it('(d) shadow_caster fallback register call carries the Standard schema', () => {
     const createRendererPath = join(
       repoRoot,
       'packages',
@@ -77,7 +73,8 @@ describe('shadow_caster empty schema (M4 w21)', () => {
     );
     const src = readFileSync(createRendererPath, 'utf8');
     const re =
-      /installMaterialArtifact\(\s*shadowCasterIdentifier\s*,\s*\{[^}]*paramSchema\s*:\s*\[\s*\][^}]*\}\s*\)/s;
+      /installMaterialArtifact\(\s*shadowCasterIdentifier\s*,\s*\{[^}]*paramSchema\s*:\s*STANDARD_PIPELINE_PARAM_SCHEMA[^}]*\}\s*\)/s;
     expect(src).toMatch(re);
+    expect(STANDARD_PIPELINE_PARAM_SCHEMA.length).toBeGreaterThan(0);
   });
 });

package/src/__tests__/shadow-csm-runtime-vary.dawn.test.ts

@@ -83,6 +83,11 @@ describe('M3 RhiNull structural admission', () => {
 
 const WIDTH = 320;
 const HEIGHT = 240;
+const LIGHTWEIGHT_DAWN = process.env.FORGEAX_DAWN_LIGHTWEIGHT === '1';
+// The variation gate only needs to observe graph rebuilds. Keep the full
+// 2048 atlas for local/nightly diagnostics, while avoiding a 4-cascade 16MiB
+// allocation on the overloaded PR lane.
+const LARGE_MAP_SIZE = LIGHTWEIGHT_DAWN ? 1024 : 2048;
 
 interface MockCanvas {
   width: number;
@@ -182,19 +187,19 @@ describe('CSM runtime cascade + mapSize variation (M5/w26)', () => {
     if (!host.ok) throw host.error;
     const { renderer } = host.value;
     expect(renderer.inspect().state).toBe('alive');
-    const { world, shadowEntity } = buildScene(4, 2048);
+    const { world, shadowEntity } = buildScene(4, LARGE_MAP_SIZE);
 
     expect(drawPublished(renderer, world).ok).toBe(true);
 
     world.set(shadowEntity, DirectionalLight, {
-      mapSize: 2048,
+      mapSize: LARGE_MAP_SIZE,
       shadowDistance: 50,
       cascadeCount: 2,
     });
     expect(drawPublished(renderer, world).ok).toBe(true);
 
     world.set(shadowEntity, DirectionalLight, {
-      mapSize: 2048,
+      mapSize: LARGE_MAP_SIZE,
       shadowDistance: 50,
       cascadeCount: 4,
     });
@@ -213,7 +218,7 @@ describe('CSM runtime cascade + mapSize variation (M5/w26)', () => {
     if (!host.ok) throw host.error;
     const { renderer } = host.value;
     expect(renderer.inspect().state).toBe('alive');
-    const { world, shadowEntity } = buildScene(4, 2048);
+    const { world, shadowEntity } = buildScene(4, LARGE_MAP_SIZE);
 
     expect(drawPublished(renderer, world).ok).toBe(true);
 
@@ -225,7 +230,7 @@ describe('CSM runtime cascade + mapSize variation (M5/w26)', () => {
     expect(drawPublished(renderer, world).ok).toBe(true);
 
     world.set(shadowEntity, DirectionalLight, {
-      mapSize: 2048,
+      mapSize: LARGE_MAP_SIZE,
       shadowDistance: 50,
       cascadeCount: 4,
     });

package/src/__tests__/shadow-fields-observable.dawn.test.ts

@@ -32,9 +32,9 @@ import { drawPublished } from './draw-published';
 const LIGHTWEIGHT_DAWN = process.env.FORGEAX_DAWN_LIGHTWEIGHT === '1';
 // The CI observability lane only needs enough settled frames to prove the
 // field-owned pixel/UBO deltas. Keep the full 300-frame, 256x256 window for
-// local and nightly runs, while the isolated PR process uses a bounded 24-frame
+// local and nightly runs, while the isolated PR process uses a bounded 12-frame
 // 128x128 target to avoid retaining a large lavapipe command backlog.
-const SHADOW_FIELDS_RENDER_FRAMES = LIGHTWEIGHT_DAWN ? 24 : 300;
+const SHADOW_FIELDS_RENDER_FRAMES = LIGHTWEIGHT_DAWN ? 12 : 300;
 const WIDTH = LIGHTWEIGHT_DAWN ? 128 : 256;
 const HEIGHT = LIGHTWEIGHT_DAWN ? 128 : 256;
 const BPR = Math.ceil((WIDTH * 4) / 256) * 256;