@forgeax/engine-runtime 0.1.20 → 0.1.23

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

@@ -147,16 +147,14 @@ describe('w7 — getActiveCamera / setActiveCamera', () => {
 // ═══════════════════════════════════════════════════════════════════════════════
 
 describe('w7 — extractFrame ActiveCamera selection', () => {
-  it('(2) no ActiveCamera + multiple cameras -> all cameras surface (first-hit fallback preserved)', () => {
+  it('(2) no ActiveCamera + multiple display cameras -> first display camera surfaces', () => {
     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);
+    // No selection -> the first display camera remains the display authority.
+    expect(frame.cameras.length).toBe(1);
   });
 
   it('(1) ActiveCamera pointing at 2nd camera -> only that camera surfaces', () => {
@@ -171,15 +169,15 @@ describe('w7 — extractFrame ActiveCamera selection', () => {
     expect(frame.cameras[0]?.fov).toBeCloseTo(2.0, 5);
   });
 
-  it('(3) ActiveCamera pointing at non-existent entity -> fallback to first-hit (all cameras)', () => {
+  it('(3) ActiveCamera pointing at non-existent entity -> fallback to first display camera', () => {
     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);
+    // Unresolvable -> behave as if no ActiveCamera.
+    expect(frame.cameras.length).toBe(1);
   });
 
   it('(4) single camera + ActiveCamera pointing at it -> behavior unchanged (one camera)', () => {

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

@@ -68,6 +68,8 @@ describe('AnimationGraph POD in the Asset union (M2 / w12)', () => {
           return 'video';
         case 'particle-effect':
           return 'particle-effect';
+        case 'ies-profile':
+          return 'ies-profile';
         default: {
           const _exhaustive: never = a;
           return _exhaustive;

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

@@ -2,8 +2,9 @@
 //
 //   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.
+//          display-name derivation (stored-name precedence / package basename
+//          fallback / no-package '' fallback / promotion freeze) must remain
+//          coherent.
 //   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;
@@ -19,7 +20,7 @@ function makeReg(): AssetRegistry {
 
 const sampler = { kind: 'sampler' as const };
 
-// ── AC-05: resolveName XOR derivation unchanged after storedNameOf retirement ──
+// ── AC-05: resolveName remains coherent after storedNameOf retirement ──
 
 describe('AC-05 resolveName regression (storedNameOf retired, name on envelope)', () => {
   it('single-asset package -> basename(path), no stored name needed', () => {

package/src/__tests__/asset-registry-scene.test-d.ts

@@ -44,6 +44,7 @@ describe('AssetUnion exhaustive switch covers all 15 members (feat-20260608 M0 b
       | 'tileset'
       | 'video'
       | 'particle-effect'
+      | 'ies-profile'
     >();
   });
 });

package/src/__tests__/asset-registry.recursive.spec.ts

@@ -1166,7 +1166,7 @@ const LEAF_FIXTURES: readonly LeafFixture[] = [
     kind: 'render-pipeline',
     makeAsset: () => ({
       kind: 'render-pipeline' as const,
-      pipelineId: 'forgeax::urp' as const,
+      pipelineId: 'forgeax::standard' as const,
     }),
   },
 ];

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

@@ -784,6 +784,7 @@ function _makeStubGPU(): unknown {
     'ui',
     'audio',
     'particle-effect',
+    'ies-profile',
   ] as const;
 
   const UNREGISTERED_STUBS = ['shader'] as const;
@@ -795,13 +796,15 @@ function _makeStubGPU(): unknown {
       for (const kind of REGISTERED_KINDS) {
         expect(reg.get(kind), `expected loader for kind '${kind}'`).toBeDefined();
       }
-      expect(reg.registeredKinds()).toHaveLength(17);
+      expect(reg.registeredKinds()).toHaveLength(18);
+      expect(reg.get('ies-profile'), 'ies-profile is wired internally').toBeDefined();
     });
 
     it('default set includes audio, video, and UI', () => {
       const reg = new LoaderRegistry();
       wireDefaultLoaders(reg);
-      expect(reg.registeredKinds()).toHaveLength(17);
+      expect(reg.registeredKinds()).toHaveLength(18);
+      expect(reg.get('ies-profile'), 'ies-profile is wired internally').toBeDefined();
       expect(reg.get('video'), 'video is wired internally (graphics-extras)').toBeDefined();
       expect(reg.get('ui'), 'ui is wired internally (engine-ui)').toBeDefined();
       expect(reg.get('audio'), 'audio is an ordinary default asset kind').toBeDefined();

package/src/__tests__/clamp-to-last.e2e.browser.test.ts

@@ -61,8 +61,8 @@ const SUT_ATTRIBUTABLE_RENDER_CODES: ReadonlySet<string> = new Set([
   'vertex-storage-buffer-unavailable',
   'mesh-ssbo-capacity-exceeded',
   'mesh-ssbo-ceiling-reached',
-  'hdrp-light-budget-exceeded',
-  'hdrp-index-list-overflow',
+  'standard-light-budget-exceeded',
+  'standard-cluster-index-overflow',
 ]);
 
 // Suppress WebGPU teardown race: chromium fires unhandled OperationError

package/src/__tests__/collect-transient-roundtrip.test.ts

@@ -14,9 +14,15 @@ import * as SceneOwner from '@forgeax/engine-scene';
 
 import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle } from '@forgeax/engine-ecs';
-import { World } from '@forgeax/engine-ecs';
+import { componentDefinition, World } from '@forgeax/engine-ecs';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
-import { ChildOf, Children, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import {
+  ChildOf,
+  Children,
+  GlobalTransform,
+  propagateTransforms,
+  Transform,
+} from '@forgeax/engine-scene';
 import type { LocalEntityId, SceneAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { rootsToSceneAsset } from '../collect-scene-asset';
@@ -26,7 +32,7 @@ import { registerSceneComponents } from './helpers/register-scene-components';
 // Read the resolved world mat4 (column-major 16 floats) from the Transform
 // world column array view.
 function worldOf(world: World, entity: EntityHandle): Float32Array {
-  return world.get(entity, Transform).unwrap().world;
+  return world.get(entity, GlobalTransform).unwrap().world;
 }
 
 function makeRegistry(): AssetRegistry {
@@ -210,6 +216,7 @@ describe('w1 — AC-04 transient world roundtrip numeric equivalence', () => {
     for (const ent of collected.value.entities) {
       const t = (ent.components as Record<string, Record<string, unknown>>).Transform;
       if (t !== undefined) expect('world' in t).toBe(false);
+      expect((ent.components as Record<string, unknown>).GlobalTransform).toBeUndefined();
     }
 
     // Round-trip into a fresh world.
@@ -266,4 +273,8 @@ describe('w1 — AC-04 transient world roundtrip numeric equivalence', () => {
     expect(wDst[13] as number).toBeCloseTo(4, 5);
     expect(wDst[14] as number).toBeCloseTo(5, 5);
   });
+
+  it('declares GlobalTransform transient and reconstructs it from the authored pair', () => {
+    expect(componentDefinition(GlobalTransform).policy.transient).toBe(true);
+  });
 });

package/src/__tests__/components.test-d.ts

@@ -16,18 +16,20 @@
 
 import type { InputShapeOf, SchemaOf, ShapeOf } from '@forgeax/engine-ecs';
 import type { Camera, DirectionalLight, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
-import type { ChildOf, Transform } from '@forgeax/engine-scene';
+import type { ChildOf, GlobalTransform, Transform } from '@forgeax/engine-scene';
 import type { Handle } from '@forgeax/engine-types';
 import { describe, expectTypeOf, it } from 'vitest';
 
 describe('w7 type-level - 5 component schemas yield exact data shapes via ShapeOf', () => {
-  it('Transform data shape has 3 local inline-array fields + world array<f32,16>', () => {
+  it('Transform data shape has 3 local inline-array fields', () => {
     type Data = ShapeOf<SchemaOf<typeof Transform>>;
-    expectTypeOf<keyof Data>().toEqualTypeOf<'pos' | 'quat' | 'scale' | 'world'>();
+    expectTypeOf<keyof Data>().toEqualTypeOf<'pos' | 'quat' | 'scale'>();
     expectTypeOf<Data['pos']>().toEqualTypeOf<Float32Array>();
     expectTypeOf<Data['quat']>().toEqualTypeOf<Float32Array>();
     expectTypeOf<Data['scale']>().toEqualTypeOf<Float32Array>();
-    expectTypeOf<Data['world']>().toEqualTypeOf<Float32Array>();
+    type GlobalData = ShapeOf<SchemaOf<typeof GlobalTransform>>;
+    expectTypeOf<keyof GlobalData>().toEqualTypeOf<'world'>();
+    expectTypeOf<GlobalData['world']>().toEqualTypeOf<Float32Array>();
     // Write side widens `array<f32, N>` to also accept plain number[] literals
     // (InputShapeOf asymmetry): `pos: [1, 2, 3]` spawns without a
     // Float32Array wrapper at the call site.
@@ -67,7 +69,7 @@ describe('w7 type-level - 5 component schemas yield exact data shapes via ShapeO
     expectTypeOf<{ materials: readonly [0] }>().not.toMatchTypeOf<SpawnData>();
   });
 
-  it('Camera data shape has 20 fields (18 number + clearColor array + autoAspect boolean)', () => {
+  it('Camera data shape has 21 fields (18 number + clearColor array + autoAspect boolean + target)', () => {
     type Data = ShapeOf<SchemaOf<typeof Camera>>;
     expectTypeOf<keyof Data>().toEqualTypeOf<
       | 'fov'
@@ -90,6 +92,7 @@ describe('w7 type-level - 5 component schemas yield exact data shapes via ShapeO
       | 'bloomBlurRadius'
       | 'clearColor'
       | 'autoAspect'
+      | 'target'
     >();
     expectTypeOf<Data['fov']>().toEqualTypeOf<number>();
     expectTypeOf<Data['far']>().toEqualTypeOf<number>();
@@ -107,9 +110,10 @@ describe('w7 type-level - 5 component schemas yield exact data shapes via ShapeO
     expectTypeOf<Data['clearColor']>().toEqualTypeOf<Float32Array>();
     // feat-20260617 / M3: AC-09 -- bool column narrows to boolean, not number.
     expectTypeOf<Data['autoAspect']>().toEqualTypeOf<boolean>();
+    expectTypeOf<Data['target']>().toEqualTypeOf<Handle<'RenderTarget', 'shared'>>();
   });
 
-  it('DirectionalLight data shape: 3 light fields + castShadow bool + 8 merged shadow fields', () => {
+  it('DirectionalLight data shape includes closed shadow quality fields', () => {
     // feat-20260621: DirectionalLightShadow merged into DirectionalLight via castShadow toggle.
     // shadowDistance replaced the nearPlane/farPlane pair (near derives from camera).
     // feat-20260709 M2: direction/color collapsed to array<f32,3> columns.
@@ -126,13 +130,18 @@ describe('w7 type-level - 5 component schemas yield exact data shapes via ShapeO
       | 'depthBias'
       | 'normalBias'
       | 'shadowDistance'
-      | 'pcfKernelSize'
+      | 'shadowFilter'
+      | 'shadowAngularRadius'
+      | 'maxPenumbraTexels'
     >();
     expectTypeOf<Data['direction']>().toEqualTypeOf<Float32Array>();
     expectTypeOf<Data['color']>().toEqualTypeOf<Float32Array>();
     expectTypeOf<Data['intensity']>().toEqualTypeOf<number>();
     // bool column narrows to boolean, not number.
     expectTypeOf<Data['castShadow']>().toEqualTypeOf<boolean>();
+    expectTypeOf<Data['shadowFilter']>().toEqualTypeOf<number>();
+    expectTypeOf<Data['shadowAngularRadius']>().toEqualTypeOf<number>();
+    expectTypeOf<Data['maxPenumbraTexels']>().toEqualTypeOf<number>();
   });
 });
 
@@ -183,12 +192,13 @@ describe('w7 type-level - component name literal types are preserved', () => {
 // ────────────────────────────────────────────────────────────────────────────
 
 describe('w15 AC-04 type constraint — ShapeOf derivation from field-payload', () => {
-  it("ShapeOf<SchemaOf<typeof Transform>> yields Float32Array views (all 'array<f32, N>' -> Float32Array)", () => {
+  it('ShapeOf<SchemaOf<typeof Transform>> yields local Float32Array views', () => {
     type T = ShapeOf<SchemaOf<typeof Transform>>;
     expectTypeOf<T['pos']>().toEqualTypeOf<Float32Array>();
     expectTypeOf<T['quat']>().toEqualTypeOf<Float32Array>();
     expectTypeOf<T['scale']>().toEqualTypeOf<Float32Array>();
-    expectTypeOf<T['world']>().toEqualTypeOf<Float32Array>();
+    type GlobalData = ShapeOf<SchemaOf<typeof GlobalTransform>>;
+    expectTypeOf<GlobalData['world']>().toEqualTypeOf<Float32Array>();
   });
 
   it("ShapeOf<SchemaOf<typeof Camera>> yields 21 number fields ('f32' -> number) + autoAspect boolean ('bool' -> boolean)", () => {

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

@@ -65,7 +65,13 @@ import {
   Tilemap,
 } from '@forgeax/engine-render/authoring';
 import * as SceneOwner from '@forgeax/engine-scene';
-import { ChildOf, Children, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import {
+  ChildOf,
+  Children,
+  GlobalTransform,
+  propagateTransforms,
+  Transform,
+} from '@forgeax/engine-scene';
 import type { Handle, LocalEntityId, SceneAsset, SceneEntity } from '@forgeax/engine-types';
 import { toShared } from '@forgeax/engine-types';
 import { describe, expect, expectTypeOf, it } from 'vitest';
@@ -150,17 +156,17 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
   // abstraction: components are flat-scalar SoA columns, not nested objects).
 
   describe('w7 - 5 component schemas register through defineComponent', () => {
-    it('Transform has pos/quat/scale inline array fields + world array<f32,16>', () => {
+    it('Transform has the three authored local array fields', () => {
       expect(Transform.name).toBe('Transform');
-      expect(Object.keys(componentSchema(Transform)).length).toBe(4);
+      expect(Object.keys(componentSchema(Transform)).length).toBe(3);
       // pos: inline [x, y, z]
       expect(componentSchema(Transform).pos).toBe('array<f32, 3>');
       // quat: inline [x, y, z, w] quaternion
       expect(componentSchema(Transform).quat).toBe('array<f32, 4>');
       // scale: inline [x, y, z]
       expect(componentSchema(Transform).scale).toBe('array<f32, 3>');
-      // world: resolved mat4 (column-major 16 floats)
-      expect(componentSchema(Transform).world).toBe('array<f32, 16>');
+      expect(GlobalTransform.name).toBe('GlobalTransform');
+      expect(componentSchema(GlobalTransform).world).toBe('array<f32, 16>');
     });
 
     it('MeshFilter has 1 shared<MeshAsset> field (assetHandle; M5 / w14)', () => {
@@ -176,9 +182,9 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       expect(schemaRecord.materials).toBe('array<shared<MaterialAsset>>');
     });
 
-    it('Camera has 20 fields (17 f32 + historyVersion u32 + clearColor array<f32,4> + autoAspect bool)', () => {
+    it('Camera has 21 fields (17 f32 + historyVersion u32 + clearColor array<f32,4> + autoAspect bool + target)', () => {
       expect(Camera.name).toBe('Camera');
-      expect(Object.keys(componentSchema(Camera)).length).toBe(20);
+      expect(Object.keys(componentSchema(Camera)).length).toBe(21);
       expect(componentSchema(Camera).fov).toBe('f32');
       expect(componentSchema(Camera).aspect).toBe('f32');
       expect(componentSchema(Camera).near).toBe('f32');
@@ -211,13 +217,13 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       expect(componentSchema(Camera).autoAspect).toBe('bool');
     });
 
-    it('DirectionalLight has 12 fields: 3 light + castShadow bool + 8 merged shadow f32', () => {
+    it('DirectionalLight has 14 fields: 3 light + castShadow bool + closed shadow quality fields', () => {
       // feat-20260621: DirectionalLightShadow merged into DirectionalLight via castShadow toggle.
       // shadowDistance replaced the nearPlane/farPlane pair (near derives from camera).
       // feat-20260709 M2: direction/color collapsed from 6 per-axis scalars to
       // two array<f32,3> columns (3 light fields: direction + color + intensity).
       expect(DirectionalLight.name).toBe('DirectionalLight');
-      expect(Object.keys(componentSchema(DirectionalLight)).length).toBe(12);
+      expect(Object.keys(componentSchema(DirectionalLight)).length).toBe(14);
       // 3 light fields
       expect(componentSchema(DirectionalLight).direction).toBe('array<f32, 3>');
       expect(componentSchema(DirectionalLight).color).toBe('array<f32, 3>');
@@ -231,7 +237,10 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       expect(componentSchema(DirectionalLight).depthBias).toBe('f32');
       expect(componentSchema(DirectionalLight).normalBias).toBe('f32');
       expect(componentSchema(DirectionalLight).shadowDistance).toBe('f32');
-      expect(componentSchema(DirectionalLight).pcfKernelSize).toBe('f32');
+      expect(componentSchema(DirectionalLight).shadowFilter).toBe('enum');
+      expect(componentSchema(DirectionalLight).shadowAngularRadius).toBe('f32');
+      expect(componentSchema(DirectionalLight).maxPenumbraTexels).toBe('f32');
+      expect('pcfKernelSize' in componentSchema(DirectionalLight)).toBe(false);
     });
 
     it('all 5 components are frozen tokens with owner-assigned identities', () => {
@@ -411,9 +420,10 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
   //                    file keeps an integration-shape spawn smoke for the
   //                    archetype-with-Children path.
   //
-  // feat-20260601 M4: GlobalTransform is retired. The resolved world transform
-  // is the `Transform.world` mat4 column; propagate + hierarchy compose coverage
-  // lives in render-system-extract.test.ts (Transform.world parent x child).
+  // The resolved world transform is the `GlobalTransform.world` mat4 column;
+  // Transform's generic ECS requirement materializes that carrier on normal
+  // spawn/add paths. Propagation + hierarchy compose coverage lives in
+  // render-system-extract.test.ts (GlobalTransform.world parent x child).
   //
   // charter mapping: proposition 2 (Bevy ChildOf/Children industry analog) +
   // proposition 3 (machine-readable schema > prose: grep componentSchema(ChildOf) /
@@ -432,14 +442,10 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       expect((componentSchema(Children) as Record<string, unknown>).entities).toBe('array<entity>');
     });
 
-    it('Transform carries the resolved world mat4 column (array<f32, 16>)', () => {
-      // feat-20260601 M4: the world transform lives on Transform.world, not a
-      // separate GlobalTransform component. The 3 local-TRS inline array
-      // columns (pos/quat/scale) plus the `world: array<f32, 16>` resolved
-      // mat4 are the full shape.
-      const tKeys = Object.keys(componentSchema(Transform));
+    it('GlobalTransform carries the resolved world mat4 column', () => {
+      const tKeys = Object.keys(componentSchema(GlobalTransform));
       expect(tKeys).toContain('world');
-      expect(componentSchema(Transform).world).toBe('array<f32, 16>');
+      expect(componentSchema(GlobalTransform).world).toBe('array<f32, 16>');
       expect(componentSchema(Transform).pos).toBe('array<f32, 3>');
       expect(componentSchema(Transform).quat).toBe('array<f32, 4>');
       expect(componentSchema(Transform).scale).toBe('array<f32, 3>');
@@ -602,7 +608,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
   //
   // Two orthogonal guarantees after ChildOf gained its `relationship` block:
   //   AC-25 reader path unchanged -- propagateTransforms still walks ChildOf.parent
-  //     upward and composes child.Transform.world = parent.world x
+  //     upward and composes child.GlobalTransform.world = parent.world x
   //     compose(child local). The migration must NOT alter this output.
   //   AC-25 mirror auto-maintained -- spawning / removing / reparenting ChildOf
   //     now auto-updates the parent's Children.entities list (the OOS-10 manual-
@@ -634,9 +640,9 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       const r = propagateTransforms(world);
       expect(r.ok).toBe(true);
 
-      // feat-20260601: the resolved world transform lives on Transform.world
+      // feat-20260601: the resolved world transform lives on GlobalTransform.world
       // (a 16-float column-major mat4); the translation column is m[12,13,14].
-      const t = world.get(child, Transform);
+      const t = world.get(child, GlobalTransform);
       expect(t.ok).toBe(true);
       if (!t.ok) return;
       const w = t.value.world;
@@ -1408,7 +1414,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
   // ────────────────────────────────────────────────────────────────────────────
 
   describe('Camera.fields reflection (w14 AC-07 SSOT)', () => {
-    it('Camera.fields has exactly 20 keys matching the Camera column set', () => {
+    it('Camera.fields has exactly 21 keys matching the Camera column set', () => {
       const keys = Object.keys(Camera.fields).sort();
       expect(keys).toEqual([
         'antialias',
@@ -1428,6 +1434,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
         'near',
         'projection',
         'right',
+        'target',
         'tonemap',
         'top',
         'whitePoint',
@@ -1443,7 +1450,9 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
               ? 'array<f32, 4>'
               : key === 'historyVersion'
                 ? 'u32'
-                : 'f32';
+                : key === 'target'
+                  ? 'shared<RenderTarget>'
+                  : 'f32';
         expect(Camera.fields[key].type).toBe(expected);
       }
     });
@@ -2409,6 +2418,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       const world = new World();
       const e = world.spawn({ component: Transform, data: {} }).unwrap();
       const row = world.get(e, Transform).unwrap();
+      const global = world.get(e, GlobalTransform).unwrap();
 
       // local pos/quat/scale inline array columns at identity.
       expect(Array.from(row.pos)).toEqual([0, 0, 0]);
@@ -2417,7 +2427,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
 
       // world array<f32,16> resolves to a Float32Array view of 16 contiguous
       // floats. Default fill is the identity mat4 (column-major).
-      const w = row.world as Float32Array;
+      const w = global.world as Float32Array;
       expect(w).toBeInstanceOf(Float32Array);
       expect(w.length).toBe(16);
       const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];

package/src/__tests__/create-renderer-assembly.integration.test.ts

@@ -36,6 +36,30 @@ describe('runtime renderer host assembly', () => {
     host.value.renderer.dispose();
   });
 
+  it('repeats null-device assembly and frame observation without device loss', async () => {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const host = await constructRendererHost(canvas(), { rhi }, { shaderManifestUrl: manifest });
+      expect(host.ok).toBe(true);
+      if (!host.ok) continue;
+      const world = new World();
+      const attached = host.value.renderer.attach(world);
+      expect(attached.ok).toBe(true);
+      if (!attached.ok) {
+        host.value.renderer.dispose();
+        continue;
+      }
+      expect(world.update().ok).toBe(true);
+      const frame = host.value.renderer.draw(frameRequest(attached.value));
+      expect(frame.ok).toBe(true);
+      if (frame.ok) {
+        expect((await host.value.renderer.observe(frame.value, { include: ['timings'] })).ok).toBe(
+          true,
+        );
+      }
+      host.value.renderer.dispose();
+    }
+  });
+
   it('keeps runtime construction errors structured', async () => {
     const result = await createRenderer(canvas(), { rhi: undefined });
     expect(result.ok).toBe(false);

package/src/__tests__/create-renderer-gpu-pass-timing.unit.test.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import type { GpuPassTimingOptions, RendererOptions } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+describe('runtime GPU pass timing forwarding', () => {
+  it('keeps one option object and projects the exact field to Render', () => {
+    const gpuPassTiming = { maxPassesPerFrame: 8 } satisfies GpuPassTimingOptions;
+    const options = { gpuPassTiming } satisfies RendererOptions;
+    expect(options.gpuPassTiming).toBe(gpuPassTiming);
+  });
+
+  it('forwards without owning admission, sessions, handles, or CPU capture', () => {
+    const source = readFileSync(
+      fileURLToPath(new URL('../createRenderer.ts', import.meta.url)),
+      'utf8',
+    );
+    expect(source).toContain('gpuPassTiming: options.gpuPassTiming');
+    expect(source).not.toContain('createGpuPassTimingSession');
+    expect(source).not.toContain('ProfileCapture');
+    expect(source).not.toContain('passCatalog');
+  });
+
+  it('keeps the no-option path free of a timing field', () => {
+    const source = readFileSync(
+      fileURLToPath(new URL('../createRenderer.ts', import.meta.url)),
+      'utf8',
+    );
+    expect(source).toContain('options === undefined');
+    expect(source).toContain('gpuPassTiming: options.gpuPassTiming');
+  });
+});

package/src/__tests__/createRenderer.browser-no-webgpu.test.ts

@@ -13,8 +13,74 @@
 
 import { createRenderer, EngineEnvironmentError } from '@forgeax/engine-runtime';
 import { describe, expect, it } from 'vitest';
+import { projectDirectionalShadowInspection } from '../../../render/src/assembly/directional-shadow-inspection';
+import { resolveDirectionalShadowBackendAdmission } from '../../../render/src/render-pipeline';
 
 describe('createRenderer without navigator.gpu (browser-no-webgpu)', () => {
+  it('requires the shared backend admission truth table for WebGL2 fallback and capable failure', async () => {
+    const module = (await import('../../../render/src/render-pipeline')) as Record<string, unknown>;
+    const resolver = module.resolveDirectionalShadowBackendAdmission;
+    expect(typeof resolver).toBe('function');
+    const resolve = resolver as (input: {
+      backendKind: 'webgpu' | 'wgpu-webgl2';
+      requested: 'pcssMedium' | 'pcssHigh';
+      candidate: 'accepted' | 'failed';
+      lastKnownGood?: 'pcf3' | 'pcf5';
+    }) => {
+      effective: string;
+      status: string;
+      fallbackReason?: string;
+    };
+    expect(
+      resolve({ backendKind: 'wgpu-webgl2', requested: 'pcssMedium', candidate: 'accepted' }),
+    ).toMatchObject({
+      effective: 'pcf3',
+      status: 'fallback',
+      fallbackReason: 'webgl2-unsupported',
+    });
+    expect(
+      resolve({
+        backendKind: 'webgpu',
+        requested: 'pcssHigh',
+        candidate: 'failed',
+        lastKnownGood: 'pcf3',
+      }),
+    ).toMatchObject({ effective: 'pcf3', status: 'rejected', fallbackReason: 'candidate-failed' });
+  });
+
+  it('keeps capable candidate failure explicit while retaining the LKG inspection facts', () => {
+    const inspection = projectDirectionalShadowInspection({
+      admission: resolveDirectionalShadowBackendAdmission({
+        backendKind: 'webgpu',
+        requested: 'pcssHigh',
+        candidate: 'failed',
+        lastKnownGood: 'pcf3',
+      }),
+      cascadeCount: 4,
+      mapSize: 2048,
+      atlasBytes: 67_108_864,
+      writerPasses: 4,
+      blockerTaps: 0,
+      filterTapUpperBound: 9,
+      seamTapUpperBound: 9,
+      deviceGeneration: 2,
+      graphGeneration: 6,
+      error: {
+        code: 'shadow-candidate-failed',
+        expected: 'the capable backend candidate compiles and validates',
+        hint: 'fix the authoring input, then retry or recover',
+      },
+    });
+    expect(inspection).toMatchObject({
+      effective: 'pcf3',
+      status: 'rejected',
+      fallbackReason: 'candidate-failed',
+      lastKnownGood: true,
+      graphGeneration: 6,
+      error: { hint: expect.stringContaining('retry') },
+    });
+  });
+
   it('navigator.gpu is absent or non-functional in this browser environment', async () => {
     const nav = globalThis.navigator as { gpu?: GPU };
     if (nav.gpu === undefined) return;

package/src/__tests__/dawn/hello-sprite-nineslice-section.dawn.test.ts

@@ -62,6 +62,12 @@ const BUFFER_USAGE_MAP_READ = 0x0001;
 const BUFFER_USAGE_COPY_DST = 0x0008;
 const MAP_MODE_READ = 0x0001;
 
+// Windows Dawn first-touch construction for the two renderer/readback probes
+// can exceed Vitest's project-wide 30-second timeout while still completing
+// well inside the nightly platform budget. Keep this owner-specific gate
+// bounded so a valid cold-start probe is not retried as a false failure.
+const SPRITE_NINESLICE_DAWN_TEST_TIMEOUT_MS = 120_000;
+
 // Distinctive 4x4 texture: corners RED (cells (0,0)/(3,0)/(0,3)/(3,3)),
 // remaining cells BLUE. With slices=[0.25,0.25,0.25,0.25] in atlas-uv space
 // the 4 corners line up with the 4 corner texels -- making the central band
@@ -325,7 +331,9 @@ function midBandDistance(a: CapturedFrame, b: CapturedFrame): number {
 }
 
 describe('feat-20260527-sprite-nineslice w14 dawn smoke (stretch vs tile divergence)', () => {
-  it('stretch + tile sprite frames diverge in the mid-band after w15 (red until w15 lands)', async () => {
+  it('stretch + tile sprite frames diverge in the mid-band after w15 (red until w15 lands)', {
+    timeout: SPRITE_NINESLICE_DAWN_TEST_TIMEOUT_MS,
+  }, async () => {
     // Asymmetric scale: x=4 vs y=1. With slices=[0.25,0.25,0.25,0.25] and the
     // 4x4 corner-checker texture, the post-w15 9-slice path keeps corner
     // zones at fixed world dimensions while the legacy pre-w15 path stretches

package/src/__tests__/dawn/instances-shadow.dawn.test.ts

@@ -55,6 +55,17 @@ const MAP_MODE_READ = 0x0001;
 const INSTANCE_COUNT = 5;
 const SPACING = 2.5;
 
+const SHADOW_FILTER = (() => {
+  const value = (
+    globalThis as unknown as { process?: { env?: Record<string, string | undefined> } }
+  ).process?.env?.FORGEAX_SHADOW_FILTER;
+  if (value === 'pcssMedium') return 4;
+  if (value === 'pcssHigh') return 5;
+  if (value === 'pcf1') return 1;
+  if (value === 'pcf5') return 3;
+  return 2;
+})();
+
 function buildTranslationGrid(): Float32Array {
   const out = new Float32Array(INSTANCE_COUNT * 16);
   const half = ((INSTANCE_COUNT - 1) * SPACING) / 2;
@@ -263,7 +274,9 @@ describe('w10 -- shadow instanced dawn smoke (AC-05 behavioral)', () => {
         depthBias: 0.005,
         normalBias: 0.05,
         shadowDistance: 50,
-        pcfKernelSize: 3,
+        shadowFilter: SHADOW_FILTER,
+        shadowAngularRadius: 0.00465,
+        maxPenumbraTexels: 32,
       },
     });
 
@@ -285,7 +298,7 @@ describe('w10 -- shadow instanced dawn smoke (AC-05 behavioral)', () => {
       { component: Instances, data: { transforms: instanceTransforms } },
     );
 
-    // Render 300 frames for temporal stability (PCF shadow, light accumulation)
+    // Render 300 frames for temporal stability (PCF or PCSS shadow, light accumulation)
     const attachment = renderer.attach(world);
     expect(attachment.ok).toBe(true);
     if (!attachment.ok) throw attachment.error;