@forgeax/engine-runtime 0.1.7 → 0.1.20

package/dist/renderer-host.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/backend-selection.ts","../src/renderer-host.ts"],"names":[],"mappings":"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","file":"renderer-host.mjs","sourcesContent":["import type { RendererOptions } from '@forgeax/engine-render';\nimport type { RhiBackendPack } from '@forgeax/engine-render/internal/construct-renderer';\nimport { err, ok, RhiError } from '@forgeax/engine-rhi';\nimport * as rhiWebgpu from '@forgeax/engine-rhi-webgpu';\n\nexport function loadRhiPack(\n  mod: Record<string, unknown>,\n  instrumentation?: RhiBackendPack['instrumentation'],\n): RhiBackendPack {\n  const rhi = mod.rhi as unknown as RhiBackendPack['rhi'];\n  const createShaderModule = mod.createShaderModule as\n    | RhiBackendPack['createShaderModule']\n    | undefined;\n  const translateErrorEventToRhiError = mod.translateErrorEventToRhiError as\n    | RhiBackendPack['translateErrorEventToRhiError']\n    | undefined;\n  const rawDeviceAccessor = mod._internal_getRawDevice as unknown as\n    | RhiBackendPack['_internal_getRawDevice']\n    | undefined;\n  const backendInstrumentation = mod.instrumentation as\n    | RhiBackendPack['instrumentation']\n    | undefined;\n  const pack: RhiBackendPack = {\n    rhi,\n    ...(createShaderModule === undefined ? {} : { createShaderModule }),\n    ...(translateErrorEventToRhiError === undefined ? {} : { translateErrorEventToRhiError }),\n    ...(rawDeviceAccessor === undefined ? {} : { _internal_getRawDevice: rawDeviceAccessor }),\n  };\n  const resolvedInstrumentation = instrumentation ?? backendInstrumentation;\n  return resolvedInstrumentation === undefined\n    ? pack\n    : { ...pack, instrumentation: resolvedInstrumentation };\n}\n\n/** Selects one backend pack; render receives only this typed owner contract. */\nexport async function loadBackendPack(\n  options: RendererOptions | undefined,\n  preferWgpu = false,\n): Promise<\n  | { readonly ok: true; readonly value: RhiBackendPack }\n  | { readonly ok: false; readonly error: RhiError }\n> {\n  const explicit = options?.rhi;\n  if (explicit !== undefined && explicit !== null) {\n    return ok(loadRhiPack({ rhi: explicit, ...(explicit as object) }, options?.rhiInstrumentation));\n  }\n  const nav =\n    typeof globalThis === 'undefined'\n      ? undefined\n      : (globalThis as { navigator?: { gpu?: unknown } }).navigator;\n  if (!preferWgpu && nav?.gpu !== undefined && nav.gpu !== null) {\n    return ok(\n      loadRhiPack(rhiWebgpu as unknown as Record<string, unknown>, options?.rhiInstrumentation),\n    );\n  }\n  try {\n    const mod = (await import('@forgeax/engine-rhi-wgpu')) as Record<string, unknown>;\n    await (mod.ensureReady as () => Promise<unknown>)();\n    return ok(loadRhiPack(mod, options?.rhiInstrumentation));\n  } catch (cause) {\n    return err(\n      new RhiError({\n        code: 'rhi-not-available',\n        expected: 'a usable RHI backend is available',\n        hint: `failed to load wgpu backend: ${String(cause)}`,\n      }),\n    );\n  }\n}\n","import type { AssetRegistry } from '@forgeax/engine-assets-runtime';\nimport type { RenderError, RendererOptions, RenderResult } from '@forgeax/engine-render';\nimport type {\n  BundlerOptions,\n  RendererHostAssembly,\n} from '@forgeax/engine-render/internal/construct-renderer';\nimport { constructRendererHost } from '@forgeax/engine-render/internal/construct-renderer';\nimport { loadBackendPack } from './backend-selection';\n\nexport type {\n  BundlerOptions,\n  RendererHostAssembly,\n} from '@forgeax/engine-render/internal/construct-renderer';\n\n/** Assemble renderer plus asset services in the Runtime-owned backend host. */\nexport async function constructRuntimeRendererHost(\n  canvas: unknown,\n  options?: RendererOptions,\n  bundler?: BundlerOptions,\n): Promise<RenderResult<RendererHostAssembly, RenderError>> {\n  const first = await loadBackendPack(options);\n  if (!first.ok) throw first.error;\n  const constructed = await constructRendererHost(canvas, options, bundler, first.value);\n  if (constructed.ok || options?.rhi !== undefined || typeof globalThis === 'undefined') {\n    return constructed;\n  }\n  const fallback = await loadBackendPack(options, true);\n  if (!fallback.ok) return constructed;\n  return constructRendererHost(canvas, options, bundler, fallback.value);\n}\n\nexport { loadRhiPack } from './backend-selection';\nexport type { AssetRegistry };\n"]}
+{"version":3,"sources":["../src/backend-selection.ts","../src/renderer-host.ts"],"names":[],"mappings":"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","file":"renderer-host.mjs","sourcesContent":["import type { RendererOptions } from '@forgeax/engine-render';\nimport type { RhiBackendPack } from '@forgeax/engine-render/internal/construct-renderer';\nimport { err, ok, RhiError } from '@forgeax/engine-rhi';\nimport * as rhiWebgpu from '@forgeax/engine-rhi-webgpu';\n\nexport function loadRhiPack(\n  mod: Record<string, unknown>,\n  instrumentation?: RhiBackendPack['instrumentation'],\n): RhiBackendPack {\n  const rhi = mod.rhi as unknown as RhiBackendPack['rhi'];\n  const createShaderModule = mod.createShaderModule as\n    | RhiBackendPack['createShaderModule']\n    | undefined;\n  const createShaderModuleImmediate = mod.createShaderModuleImmediate as\n    | RhiBackendPack['createShaderModuleImmediate']\n    | undefined;\n  const translateErrorEventToRhiError = mod.translateErrorEventToRhiError as\n    | RhiBackendPack['translateErrorEventToRhiError']\n    | undefined;\n  const rawDeviceAccessor = mod._internal_getRawDevice as unknown as\n    | RhiBackendPack['_internal_getRawDevice']\n    | undefined;\n  const backendInstrumentation = mod.instrumentation as\n    | RhiBackendPack['instrumentation']\n    | undefined;\n  const pack: RhiBackendPack = {\n    rhi,\n    ...(createShaderModule === undefined ? {} : { createShaderModule }),\n    ...(createShaderModuleImmediate === undefined ? {} : { createShaderModuleImmediate }),\n    ...(translateErrorEventToRhiError === undefined ? {} : { translateErrorEventToRhiError }),\n    ...(rawDeviceAccessor === undefined ? {} : { _internal_getRawDevice: rawDeviceAccessor }),\n  };\n  const resolvedInstrumentation = instrumentation ?? backendInstrumentation;\n  return resolvedInstrumentation === undefined\n    ? pack\n    : { ...pack, instrumentation: resolvedInstrumentation };\n}\n\n/** Selects one backend pack; render receives only this typed owner contract. */\nexport async function loadBackendPack(\n  options: RendererOptions | undefined,\n  preferWgpu = false,\n): Promise<\n  | { readonly ok: true; readonly value: RhiBackendPack }\n  | { readonly ok: false; readonly error: RhiError }\n> {\n  const explicit = options?.rhi;\n  if (explicit !== undefined && explicit !== null) {\n    return ok(loadRhiPack({ rhi: explicit, ...(explicit as object) }, options?.rhiInstrumentation));\n  }\n  const nav =\n    typeof globalThis === 'undefined'\n      ? undefined\n      : (globalThis as { navigator?: { gpu?: unknown } }).navigator;\n  if (!preferWgpu && nav?.gpu !== undefined && nav.gpu !== null) {\n    return ok(\n      loadRhiPack(rhiWebgpu as unknown as Record<string, unknown>, options?.rhiInstrumentation),\n    );\n  }\n  try {\n    const mod = (await import('@forgeax/engine-rhi-wgpu')) as Record<string, unknown>;\n    await (mod.ensureReady as () => Promise<unknown>)();\n    return ok(loadRhiPack(mod, options?.rhiInstrumentation));\n  } catch (cause) {\n    return err(\n      new RhiError({\n        code: 'rhi-not-available',\n        expected: 'a usable RHI backend is available',\n        hint: `failed to load wgpu backend: ${String(cause)}`,\n      }),\n    );\n  }\n}\n","import type { AssetRegistry } from '@forgeax/engine-assets-runtime';\nimport type { RenderError, RendererOptions, RenderResult } from '@forgeax/engine-render';\nimport type {\n  BundlerOptions,\n  RendererHostAssembly,\n} from '@forgeax/engine-render/internal/construct-renderer';\nimport {\n  constructRendererHost,\n  EngineEnvironmentError,\n} from '@forgeax/engine-render/internal/construct-renderer';\nimport { loadBackendPack } from './backend-selection';\n\nexport type {\n  BundlerOptions,\n  RendererHostAssembly,\n} from '@forgeax/engine-render/internal/construct-renderer';\n\nconst FALLBACK_ERROR_CODES = new Set([\n  'adapter-unavailable',\n  'request-adapter-threw',\n  'feature-not-enabled',\n  'limit-exceeded',\n  'rhi-not-available',\n  'device-lost',\n  'oom',\n]);\n\nfunction canFallbackToWgpu(error: unknown): boolean {\n  if (!(error instanceof EngineEnvironmentError)) return false;\n  const webgpuError = error.detail.webgpuError;\n  if (webgpuError === undefined || typeof webgpuError !== 'object') return false;\n  if (!('code' in webgpuError)) return false;\n  const code = webgpuError.code;\n  return typeof code === 'string' && FALLBACK_ERROR_CODES.has(code);\n}\n\n/** Assemble renderer plus asset services in the Runtime-owned backend host. */\nexport async function constructRuntimeRendererHost(\n  canvas: unknown,\n  options?: RendererOptions,\n  bundler?: BundlerOptions,\n): Promise<RenderResult<RendererHostAssembly, RenderError | EngineEnvironmentError>> {\n  const first = await loadBackendPack(options);\n  if (!first.ok) throw first.error;\n  const constructed = await constructRendererHost(canvas, options, bundler, first.value);\n  if (\n    constructed.ok ||\n    options?.rhi !== undefined ||\n    typeof globalThis === 'undefined' ||\n    !canFallbackToWgpu(constructed.error)\n  ) {\n    return constructed;\n  }\n  const fallback = await loadBackendPack(options, true);\n  if (!fallback.ok) return constructed;\n  return constructRendererHost(canvas, options, bundler, fallback.value);\n}\n\nexport { loadRhiPack } from './backend-selection';\nexport type { AssetRegistry };\n"]}

package/package.json

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

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 },
     }),
   },
   {

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__/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__/dawn/hello-sprite-nineslice-section.dawn.test.ts

@@ -89,11 +89,10 @@ function makeCornerCheckerTexture(): TextureAsset {
   }
   return {
     kind: 'texture',
-    width: side,
-    height: side,
+    shape: { viewDimension: '2d', extent: { width: side, height: side } },
     format: 'rgba8unorm-srgb',
     colorSpace: 'srgb',
-    mipmap: false,
+    mips: { kind: 'none' },
     data: bytes,
   };
 }

package/src/__tests__/dawn/instances-per-instance-pbr.dawn.test.ts

@@ -10,11 +10,8 @@
 // AC-01: PBR instances=N vs instances=1 frames differ (diffCount>0).
 // AC-06: single entity + N instance reads meshes[0] (not meshes[instance_index]).
 //
-// Red phase (current): the shader reads meshes[instance_index].worldFromLocal
-// -- all N copies collapse to entity origin. The two frames are identical
-// (diffCount===0) because instance=1 at origin and instances=N all at origin
-// produce the same pixel pattern. GREEN after w4 lands (PBR vs_main reads
-// meshes[0] + instances[idx]).
+// The PBR vertex path must combine the entity transform from meshes[0] with
+// the per-instance transform selected by instance_index.
 //
 // Dual-state methodology: render to two textures (instances=N vs instances=1),
 // read back both, count pixels that differ by more than epsilon. The
@@ -52,6 +49,11 @@ const INSTANCE_GRID_Y = 3;
 const INSTANCE_GRID_Z = 2;
 const INSTANCE_COUNT = INSTANCE_GRID_X * INSTANCE_GRID_Y * INSTANCE_GRID_Z; // 30
 const SPACING = 2.5;
+// Windows Dawn first-touch attempts have reached about 80 seconds for this
+// two-renderer PBR/readback probe. Keep the test bounded, but above the
+// project-wide 30-second budget so retries do not turn a slow valid probe into
+// a cancelled nightly job.
+const PBR_DAWN_TEST_TIMEOUT_MS = 120_000;
 
 function buildTranslationGrid(): Float32Array {
   const out = new Float32Array(INSTANCE_COUNT * 16);
@@ -85,8 +87,10 @@ const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(
   JSON.stringify(ENGINE_MANIFEST),
 )}`;
 
-describe('w2 -- PBR dual-state dawn smoke (AC-01 / AC-06, RED before w4)', () => {
-  it('instances=N vs instances=1: frames differ in pixel diff count (currently RED)', async () => {
+describe('w2 -- PBR dual-state dawn smoke (AC-01 / AC-06)', () => {
+  it('instances=N vs instances=1: frames differ in pixel diff count', {
+    timeout: PBR_DAWN_TEST_TIMEOUT_MS,
+  }, async () => {
     const dawnAvailable = typeof globalThis.navigator?.gpu?.requestAdapter === 'function';
     if (!dawnAvailable) {
       throw new Error('dawn-node navigator.gpu not injected; vitest.setup-webgpu.ts regressed');
@@ -366,9 +370,6 @@ describe('w2 -- PBR dual-state dawn smoke (AC-01 / AC-06, RED before w4)', () =>
 
     // AC-01: diffCount>0 -- the two frames must differ (instances=N spreads
     // to distinct positions, instances=1 renders at entity origin only).
-    // RED before w4: all N copies collapse to entity origin, so both frames
-    // render the same cube at the same position -> diffCount===0.
-    // Currently RED: diffCount===0 because shader doesn't read @group(3)
     expect(diffCount).toBeGreaterThan(0);
     // Also verify the N-instance frame has substantial non-clear pixels
     // (proves instances rendered, not just an empty frame)
@@ -377,7 +378,7 @@ describe('w2 -- PBR dual-state dawn smoke (AC-01 / AC-06, RED before w4)', () =>
   });
 
   // w5 -- unlit dual-state: N unlit instances at distinct NDC positions (AC-02)
-  it('unlit Instances=N vs instances=1: frames differ (RED before w5)', async () => {
+  it('unlit Instances=N vs instances=1: frames differ', async () => {
     const dawnAvailable_2 = typeof globalThis.navigator?.gpu?.requestAdapter === 'function';
     if (!dawnAvailable_2) {
       throw new Error('dawn-node navigator.gpu not injected');

package/src/__tests__/dawn/material-alpha.dawn.test.ts

@@ -99,12 +99,11 @@ function textureBytes(color: readonly [number, number, number, number]): Uint8Ar
 function makeTexture(color: readonly [number, number, number, number]): TextureAsset {
   return {
     kind: 'texture',
-    width: 1,
-    height: 1,
+    shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
     format: 'rgba8unorm-srgb',
     data: textureBytes(color),
     colorSpace: 'srgb',
-    mipmap: false,
+    mips: { kind: 'none' },
   };
 }
 

package/src/__tests__/dawn/mipmap-srgb-linear.dawn.test.ts

@@ -42,12 +42,11 @@ function makeTexture(
 ): TextureAsset {
   return {
     kind: 'texture',
-    width,
-    height,
+    shape: { viewDimension: '2d', extent: { width, height } },
     format,
     data: new Uint8Array(width * height * 4),
     colorSpace,
-    mipmap,
+    mips: mipmap ? { kind: 'generate' } : { kind: 'none' },
   };
 }
 

package/src/__tests__/dawn/per-entity-material-texture-isolation.dawn.test.ts

@@ -60,12 +60,11 @@ function makeChequerTexture(primaryR: number, primaryG: number, primaryB: number
   }
   return {
     kind: 'texture',
-    width: side,
-    height: side,
+    shape: { viewDimension: '2d', extent: { width: side, height: side } },
     format: 'rgba8unorm',
     data: bytes,
     colorSpace: 'srgb',
-    mipmap: false,
+    mips: { kind: 'none' },
   };
 }
 

package/src/__tests__/dawn/sprite-nineslice-mesh-bind.dawn.test.ts

@@ -126,11 +126,10 @@ describe('feat-20260527-sprite-nineslice w13 dawn smoke (HANDLE_NINESLICE_QUAD b
     }
     const texAsset: TextureAsset = {
       kind: 'texture',
-      width: 4,
-      height: 4,
+      shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
       format: 'rgba8unorm-srgb',
       colorSpace: 'srgb',
-      mipmap: false,
+      mips: { kind: 'none' },
       data: pixels,
     };
     const texHandle = world.allocSharedRef<'TextureAsset', TextureAsset>('TextureAsset', texAsset);

package/src/__tests__/dawn/upload-texture.dawn.test.ts

@@ -72,12 +72,11 @@ function makeTexture(
 ): TextureAsset {
   return {
     kind: 'texture',
-    width,
-    height,
+    shape: { viewDimension: '2d', extent: { width, height } },
     format,
     data: new Uint8Array(width * height * 4),
     colorSpace,
-    mipmap,
+    mips: mipmap ? { kind: 'generate' } : { kind: 'none' },
   };
 }
 
@@ -182,12 +181,11 @@ describe('AC-04: uploadTexture non-256-aligned width (real GPU path)', () => {
 
     const tex: TextureAsset = {
       kind: 'texture',
-      width,
-      height,
+      shape: { viewDimension: '2d', extent: { width, height } },
       format: 'rgba8unorm',
       data: buf,
       colorSpace: 'linear',
-      mipmap: false,
+      mips: { kind: 'none' },
     };
 
     const handle = world.allocSharedRef('TextureAsset', tex);

package/src/__tests__/derive-bgl-integration.test.ts

@@ -87,6 +87,17 @@ const builtinSchemas: ReadonlyArray<{ id: string; schema: readonly ParamSchemaEn
 ];
 
 describe('derive(schema) integration over 5 built-in shader families (M3 w11)', () => {
+  it('derives array and volume texture schemas without a second binding path', () => {
+    for (const schema of [
+      [{ name: 'layers', type: 'texture2d_array' as const }],
+      [{ name: 'volume', type: 'texture3d' as const }],
+    ]) {
+      const out = derive(schema);
+      expect(out.bglEntries.map((entry) => entry.binding)).toEqual([0, 1, 2]);
+      expect(out.resourceBindings[1]?.name).toBe(schema[0]?.name);
+      expect(out.textureFieldNames).toContain(schema[0]?.name);
+    }
+  });
   it('(a) every built-in shader derives a well-formed BGL with consistent userRegionBindingEnd', () => {
     for (const { id, schema } of builtinSchemas) {
       const out = derive(schema);

package/src/__tests__/equirect-bc6h.integration.test.ts

@@ -145,12 +145,14 @@ describe.skipIf(!hasGpu)('equirect renderable-source integration (feat-20260707
     // POD mirrors that 2D surface.
     const source = {
       kind: 'texture' as const,
-      width: asset.width,
-      height: asset.height,
+      shape: { viewDimension: '2d' as const, extent: { width: asset.width, height: asset.height } },
       format: asset.format,
-      data: asset.data,
+      data:
+        asset.data instanceof Uint8ClampedArray
+          ? new Uint8Array(asset.data.buffer, asset.data.byteOffset, asset.data.byteLength)
+          : asset.data,
       colorSpace: asset.colorSpace,
-      mipmap: false,
+      mips: { kind: 'none' as const },
     };
     const res = deriveRenderDataCubemap(source);
     expect(res.ok).toBe(true);