@forgeax/engine-runtime 0.1.19 → 0.1.21

package/package.json

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

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__/asset-registry.recursive.spec.ts

@@ -374,12 +374,11 @@ describe('mesh default material ready boundary', () => {
     if (refs.length > 0) {
       reg.catalog(parseGuid(WRONG_DEFAULT_KIND_GUID), {
         kind: 'texture' as const,
-        width: 1,
-        height: 1,
+        shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
         format: 'rgba8unorm' as const,
         data: new Uint8Array([255, 255, 255, 255]),
         colorSpace: 'srgb' as const,
-        mipmap: false,
+        mips: { kind: 'none' as const },
       });
     }
     const omittedDefaultGuid = 'b0000000-0000-4000-b000-000000000099';
@@ -445,12 +444,11 @@ describe('mesh default material ready boundary', () => {
     const reg = makeRegistry();
     reg.catalog(parseGuid(WRONG_DEFAULT_KIND_GUID), {
       kind: 'texture' as const,
-      width: 1,
-      height: 1,
+      shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
       format: 'rgba8unorm' as const,
       data: new Uint8Array([255, 255, 255, 255]),
       colorSpace: 'srgb' as const,
-      mipmap: false,
+      mips: { kind: 'none' as const },
     });
 
     const packIndex = [
@@ -740,21 +738,19 @@ describe('AC-02 — material recursive loadByGuid', () => {
     // Pre-register textures in dev mode (fast-path compatible)
     reg.catalog(parseGuid(TEXTURE_A_GUID), {
       kind: 'texture' as const,
-      width: 4,
-      height: 4,
+      shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
       format: 'rgba8unorm' as const,
       data: new Uint8Array(64),
       colorSpace: 'srgb' as const,
-      mipmap: false,
+      mips: { kind: 'none' as const },
     });
     reg.catalog(parseGuid(TEXTURE_B_GUID), {
       kind: 'texture' as const,
-      width: 4,
-      height: 4,
+      shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
       format: 'rgba8unorm' as const,
       data: new Uint8Array(64),
       colorSpace: 'srgb' as const,
-      mipmap: false,
+      mips: { kind: 'none' as const },
     });
 
     const packIndex = [
@@ -900,12 +896,11 @@ describe('AC-03 — gltf-shaped scene composite (via SceneAsset, D-9)', () => {
     // Pre-register texture in dev mode.
     reg.catalog(parseGuid(TEXTURE_C_GUID), {
       kind: 'texture' as const,
-      width: 4,
-      height: 4,
+      shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
       format: 'rgba8unorm' as const,
       data: new Uint8Array(64),
       colorSpace: 'srgb' as const,
-      mipmap: false,
+      mips: { kind: 'none' as const },
     });
 
     const packIndex = [
@@ -1103,12 +1098,11 @@ const LEAF_FIXTURES: readonly LeafFixture[] = [
     kind: 'texture',
     makeAsset: () => ({
       kind: 'texture' as const,
-      width: 4,
-      height: 4,
+      shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
       format: 'rgba8unorm' as const,
       data: new Uint8Array(64),
       colorSpace: 'srgb' as const,
-      mipmap: false,
+      mips: { kind: 'none' as const },
     }),
   },
   {
@@ -1172,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

@@ -689,11 +689,10 @@ function _makeStubGPU(): unknown {
         kind: 'texture',
         payload: {
           kind: 'texture',
-          width: 2,
-          height: 2,
+          shape: { viewDimension: '2d', extent: { width: 2, height: 2 } },
           format: 'rgba8unorm',
           colorSpace: 'srgb',
-          mipmap: false,
+          mips: { kind: 'none' },
         },
         refs: [],
         artifacts: {
@@ -706,7 +705,11 @@ function _makeStubGPU(): unknown {
       const out = await textureLoader.loadPack?.(input, mockCtx());
       expect(out.ok).toBe(true);
       if (out.ok) {
-        expect(out.value).toMatchObject({ kind: 'texture', width: 2, height: 2 });
+        expect(out.value).toMatchObject({
+          kind: 'texture',
+          shape: { viewDimension: '2d', extent: { width: 2, height: 2 } },
+          mips: { kind: 'none' },
+        });
       }
     });
 
@@ -3414,11 +3417,10 @@ function _makeStubGPU(): unknown {
 
   const TEXTURE_METADATA = {
     kind: 'texture',
-    width: 2,
-    height: 2,
+    shape: { viewDimension: '2d', extent: { width: 2, height: 2 } },
     format: 'rgba8unorm',
     colorSpace: 'srgb',
-    mipmap: false,
+    mips: { kind: 'none' },
   } as const;
 
   function unimportedTextureRow() {
@@ -3731,10 +3733,13 @@ function _makeStubGPU(): unknown {
                   guid: GUID_IMPORTED,
                   kind: 'texture',
                   payload: {
-                    width: binWidth,
-                    height: binHeight,
+                    shape: {
+                      viewDimension: '2d',
+                      extent: { width: binWidth, height: binHeight },
+                    },
                     format: 'rgba16float',
                     colorSpace: 'linear',
+                    mips: { kind: 'none' },
                   },
                   refs: [],
                   artifacts: {
@@ -3771,8 +3776,10 @@ function _makeStubGPU(): unknown {
       const tex: TextureAsset = result.value;
       expect(tex.format).toBe('rgba16float');
       expect(tex.colorSpace).toBe('linear');
-      expect(tex.width).toBe(binWidth);
-      expect(tex.height).toBe(binHeight);
+      expect(tex.shape).toEqual({
+        viewDimension: '2d',
+        extent: { width: binWidth, height: binHeight },
+      });
       expect(tex.data.length).toBe(binWidth * binHeight * 4 * 2);
     });
   });
@@ -5544,11 +5551,10 @@ function _makeStubGPU(): unknown {
                   kind: 'texture',
                   payload: {
                     kind: 'texture',
-                    width: 4,
-                    height: 4,
+                    shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
                     format: 'rgba8unorm',
                     colorSpace: 'linear',
-                    mipmap: false,
+                    mips: { kind: 'none' },
                   },
                   refs: [],
                   artifacts: {
@@ -5577,11 +5583,10 @@ function _makeStubGPU(): unknown {
       // loadByGuid returns the payload directly.
       const asset = result.value;
       expect(asset.kind).toBe('texture');
-      expect(asset.width).toBe(4);
-      expect(asset.height).toBe(4);
+      expect(asset.shape).toEqual({ viewDimension: '2d', extent: { width: 4, height: 4 } });
       expect(asset.format).toBe('rgba8unorm');
       expect(asset.colorSpace).toBe('linear');
-      expect(asset.mipmap).toBe(false);
+      expect(asset.mips).toEqual({ kind: 'none' });
       expect(asset.data.byteLength).toBe(4 * 4 * 4);
       expect(asset.data[0]).toBe(0);
       expect(asset.data[63]).toBe(63);
@@ -6040,12 +6045,11 @@ function _makeStubGPU(): unknown {
 
     return {
       kind: 'texture' as const,
-      width: 1,
-      height: 1,
+      shape: { viewDimension: '2d' as const, extent: { width: 1, height: 1 } },
       format: 'rgba16float',
       data,
       colorSpace: 'linear' as const,
-      mipmap: false,
+      mips: { kind: 'none' as const },
     };
   }
 
@@ -6065,8 +6069,8 @@ function _makeStubGPU(): unknown {
       if (got === undefined) return;
       expect(got.format).toBe('rgba16float');
       expect(got.colorSpace).toBe('linear');
-      expect(got.width).toBe(1);
-      expect(got.height).toBe(1);
+      expect(got.shape).toEqual({ viewDimension: '2d', extent: { width: 1, height: 1 } });
+      expect(got.mips).toEqual({ kind: 'none' });
       expect(got.data.length).toBe(8);
     });
 
@@ -6815,12 +6819,11 @@ function _makeStubGPU(): unknown {
   function makeTexture(format: GPUTextureFormat, colorSpace: 'srgb' | 'linear'): TextureAsset {
     return {
       kind: 'texture',
-      width: 1,
-      height: 1,
+      shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
       format,
       data: new Uint8Array([255, 255, 255, 255]),
       colorSpace,
-      mipmap: false,
+      mips: { kind: 'none' },
     };
   }
 

package/src/__tests__/basis-catalog-dispatch.integration.test.ts

@@ -166,10 +166,10 @@ function wireFetch(
                 guid: GUID_TEX,
                 kind: 'texture',
                 payload: {
-                  width: W,
-                  height: H,
+                  shape: { viewDimension: '2d', extent: { width: W, height: H } },
                   format: fixture.colorSpace === 'srgb' ? 'rgba8unorm-srgb' : 'rgba16float',
                   colorSpace: fixture.colorSpace,
+                  mips: { kind: 'none' },
                 },
                 refs: [],
                 artifacts: {
@@ -238,10 +238,13 @@ describe.skipIf(!pkgBuilt)('Basis catalog dispatch round-trip (M6 fix)', () => {
     const result = await loadWith(true);
     expect(result.ok).toBe(true);
     if (!result.ok) throw new Error(`load failed: ${result.error.code}`);
-    const tex = result.value as { kind: string; width: number; height: number; format: string };
+    const tex = result.value as {
+      kind: string;
+      shape: { viewDimension: string; extent: { width: number; height: number } };
+      format: string;
+    };
     expect(tex.kind).toBe('texture');
-    expect(tex.width).toBe(W);
-    expect(tex.height).toBe(H);
+    expect(tex.shape).toEqual({ viewDimension: '2d', extent: { width: W, height: H } });
     // NO_CAPS -> the transcode arm degrades to the uncompressed sRGB fallback
     // (section 8 P3), never a scheme=1 reject.
     expect(tex.format).toBe('rgba8unorm-srgb');
@@ -290,15 +293,13 @@ describe.skipIf(!pkgBuilt)('Basis catalog dispatch round-trip (M6 fix)', () => {
         if (!result.ok) continue;
         const texture = result.value as {
           kind: string;
-          width: number;
-          height: number;
+          shape: { viewDimension: string; extent: { width: number; height: number } };
           format: string;
           data: Uint8Array;
           colorSpace: string;
         };
         expect(texture.kind).toBe('texture');
-        expect(texture.width).toBe(W);
-        expect(texture.height).toBe(H);
+        expect(texture.shape).toEqual({ viewDimension: '2d', extent: { width: W, height: H } });
         expect(texture.data.byteLength).toBeGreaterThan(0);
         expect(texture.colorSpace).toBe(fixture.colorSpace);
         const expected =

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__/components.test-d.ts

@@ -67,7 +67,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 +90,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 +108,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 +128,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>();
   });
 });
 

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

@@ -176,9 +176,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 +211,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 +231,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', () => {
@@ -1408,7 +1411,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 +1431,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
         'near',
         'projection',
         'right',
+        'target',
         'tonemap',
         'top',
         'whitePoint',
@@ -1443,7 +1447,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);
       }
     });

package/src/__tests__/compressed-texture-physical-extent.integration.test.ts

@@ -79,13 +79,11 @@ function compressedPod(): TextureAsset {
     bytes.fill(level.level + 1, level.byteOffset, level.byteOffset + level.byteLength);
   return {
     kind: 'texture',
-    width: 2085,
-    height: 1573,
+    shape: { viewDimension: '2d', extent: { width: 2085, height: 1573 } },
     format: 'bc7-rgba-unorm',
     data: bytes,
     colorSpace: 'linear',
-    mipmap: true,
-    mipLevelCount: layout.length,
+    mips: { kind: 'packed', levelCount: layout.length },
   };
 }
 
@@ -93,13 +91,18 @@ describe('compressed texture physical extent recorded-RHI witness [w36]', () =>
   it('allocates and uploads BC7 physical extents while preserving logical asset metadata', () => {
     const calls = { create: [] as TextureCall[], writes: [] as WriteCall[] };
     const pod = compressedPod();
-    const expected = deriveMipUploadLayout(pod.format, pod.width, pod.height, numMipLevels(pod));
+    const expected = deriveMipUploadLayout(
+      pod.format,
+      pod.shape.extent.width,
+      pod.shape.extent.height,
+      pod.mips.kind === 'packed' ? pod.mips.levelCount : 1,
+    );
 
     const result = makeStore(calls).ensureResident(toShared<'TextureAsset'>(36), pod);
     if (!result.ok) throw result.error;
 
-    expect(pod.width).toBe(2085);
-    expect(pod.height).toBe(1573);
+    expect(pod.shape.extent.width).toBe(2085);
+    expect(pod.shape.extent.height).toBe(1573);
     expect(calls.create).toHaveLength(1);
     expect(calls.create[0]?.size).toMatchObject({ width: 2088, height: 1576 });
     expect(calls.writes).toHaveLength(expected.length);
@@ -122,12 +125,11 @@ describe('compressed texture physical extent recorded-RHI witness [w36]', () =>
     const calls = { create: [] as TextureCall[], writes: [] as WriteCall[] };
     const pod: TextureAsset = {
       kind: 'texture',
-      width: 17,
-      height: 9,
+      shape: { viewDimension: '2d', extent: { width: 17, height: 9 } },
       format: 'rgba8unorm',
       data: new Uint8Array(17 * 9 * 4),
       colorSpace: 'linear',
-      mipmap: false,
+      mips: { kind: 'none' },
     };
 
     expect(makeStore(calls).ensureResident(toShared<'TextureAsset'>(37), pod).ok).toBe(true);

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');
+  });
+});