@forgeax/engine-runtime 0.1.21 → 0.1.24

package/src/__tests__/collect-scene-mount-collapse.test.ts

@@ -119,7 +119,11 @@ describe('m2-t2 — Form 1: deep anchor with ChildOf parent', () => {
     reg.catalog(pg(G1), child as Asset);
     const ch = rs(w, child);
 
-    const outerRes = w.spawn({ component: ChildOf, data: { parent: 0 as EntityHandle } });
+    // Relationship sources now reject stale targets at the public boundary.
+    // Use a real, non-descended host for this fixture so the test still
+    // exercises a deep anchor without manufacturing an invalid public edge.
+    const outerHost = w.spawn().unwrap();
+    const outerRes = w.spawn({ component: ChildOf, data: { parent: outerHost } });
     expect(outerRes.ok).toBe(true);
     if (!outerRes.ok) return;
     const outerE = outerRes.value;

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.
@@ -190,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)', () => {
@@ -414,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) /
@@ -435,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>');
@@ -605,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-
@@ -637,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;
@@ -2415,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]);
@@ -2423,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-fallback-shader-manifest.cases.unit.test.ts

@@ -0,0 +1,345 @@
+// @ts-nocheck — merged file: cross-source node:fs/node:path imports outside @types/node coverage in runtime tsconfig
+// Consolidated by feat-20260609-test-pool-startup-reduction-merge-tiny-test-files
+// biome-ignore-all lint/complexity/noUselessLoneBlockStatements: block-scope isolation between merged source files (consolidation paradigm)
+//
+// Source files (N=33):
+//   - packages/runtime/__tests__/create-renderer-fallback.test.ts
+//   - packages/runtime/src/__tests__/cluster-binner.test.ts
+//   - packages/runtime/src/__tests__/create-renderer-fallback-shader-manifest.test.ts
+//   - packages/runtime/src/__tests__/create-renderer-uniform-fallback.test.ts
+//   - packages/runtime/src/__tests__/createRenderer.test.ts
+//   - packages/runtime/src/__tests__/dispatch-sort.test.ts
+//   - packages/runtime/src/__tests__/engine-metrics.test.ts
+//   - packages/runtime/src/__tests__/device/gpu-residency-caps-guard.test.ts
+//   - packages/runtime/src/__tests__/pass-selector.test.ts
+//   - packages/runtime/src/__tests__/pipeline-builder.test.ts
+//   - packages/runtime/src/__tests__/pipeline-cache-key-topology.test.ts
+//   - packages/runtime/src/__tests__/pipeline-rename-grep-gate.test.ts
+//   - packages/runtime/src/__tests__/pipeline-vertex-stride-branch.test.ts
+//   - packages/runtime/src/__tests__/post-process-register.test.ts
+//   - packages/runtime/src/__tests__/record-all-topology.test.ts
+//   - packages/runtime/src/__tests__/record-draw-branch.test.ts
+//   - packages/runtime/src/__tests__/record-strip-index-format.test.ts
+//   - packages/runtime/src/__tests__/render-query-regression.test.ts
+//   - packages/runtime/src/__tests__/renderer-draw-world.test.ts
+//   - packages/runtime/src/__tests__/renderer-input-snapshot.test.ts
+//   - packages/runtime/src/__tests__/renderer-read-pixels.test.ts
+//   - packages/runtime/src/__tests__/renderer-ready.test.ts
+//   - packages/runtime/src/__tests__/renderstate-pipeline-cache.test.ts
+//   - packages/runtime/src/__tests__/storage-buffer-caps.test.ts
+//   - packages/runtime/src/__tests__/device/gpu-residency.test.ts
+//   - packages/runtime/src/__tests__/render-data.test.ts
+//   - packages/runtime/src/__tests__/hdrp-bgl-slots.test.ts
+//   - packages/runtime/src/__tests__/hdrp-caps-gate.test.ts
+//   - packages/runtime/src/__tests__/hdrp-grid-invalid.test.ts
+//   - packages/runtime/src/__tests__/hdrp-index-list-overflow-once.test.ts
+//   - packages/runtime/src/__tests__/hdrp-light-budget.test.ts
+//   - packages/runtime/src/__tests__/hdrp-pipeline-asset-config.test.ts
+//   - packages/runtime/src/__tests__/m7-hdrp-demo-shape.test.ts
+//
+// Paradigm: each block-scope wraps a source file. ancestorTitles[0] is the
+// source-preserved inner describe (NOT the source filename for these 3 files
+// — recovery path: vitest report ancestorTitles -> grep this file -> upstream
+// `// ─── from <name>.test.ts ───` block separator -> source filename).
+// Top-level imports merged + deduped.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HANDLE_CUBE, HANDLE_TRIANGLE, resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import type { World as WorldType } from '@forgeax/engine-ecs';
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import {
+  buildMeshAttributeMapForUvSets,
+  createBoxGeometry,
+  createConeGeometry,
+  createCylinderGeometry,
+  createPlaneGeometry,
+  createSphereGeometry,
+  createTorusGeometry,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+} from '@forgeax/engine-geometry';
+import { type Mat4, mat4, type Vec3, vec3 } from '@forgeax/engine-math';
+import type { Renderer as RendererType } from '@forgeax/engine-render';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import {
+  err,
+  ok,
+  type PipelineLayout,
+  type RenderPipeline,
+  type Result,
+  type RhiCaps,
+  type RhiDevice,
+  RhiError,
+  ok as rhiOk,
+  type ShaderModule,
+} from '@forgeax/engine-rhi';
+import {
+  acquireCanvasContext as acquireNullCanvasContext,
+  createShaderModule as createNullShaderModule,
+  RhiNullAdapter,
+} from '@forgeax/engine-rhi-null';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import {
+  findVariantByKey,
+  type MaterialShaderEntry,
+  type MaterialShaderManifestEntry,
+  type MaterialShaderManifestVariant,
+} from '@forgeax/engine-shader';
+import {
+  type AssetError,
+  type EquirectAsset,
+  type Handle,
+  type MaterialRenderState,
+  type MeshAsset,
+  type PassSelector,
+  type PrimitiveTopology,
+  type RenderPipelineAsset,
+  type TextureAsset,
+  toShared,
+} from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  bin,
+  type ClusterBinError,
+  calculateSphereClusterBounds,
+  clusterSpaceObjectAabb,
+  deriveCullingRadius,
+  ndcPositionToCluster,
+  viewZToZSlice,
+} from '../../../render/src/cluster-binner';
+import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
+import { createEngineMetrics } from '../../../render/src/engine-metrics';
+import { assertStorageBufferCap } from '../../../render/src/light-buffer-layout';
+import {
+  buildPbrPipelineLayouts,
+  buildPbrViewBglEntries,
+  type PbrCaps,
+} from '../../../render/src/pbr-pipeline';
+import {
+  HdrpInstallError,
+  validateClusterGrid,
+} from '../../../render/src/pipeline/standard-pipeline';
+import {
+  buildPipelineForMaterialShader,
+  type PipelineBuilderContext,
+  type PipelineBuilderShaderModuleFactory,
+} from '../../../render/src/pipeline-builder';
+import {
+  cacheKeyOf,
+  createHdrpBindGroupLayoutDescriptor,
+  type PipelineSpec,
+} from '../../../render/src/pipeline-spec';
+import {
+  deriveRenderDataCubemap,
+  deriveRenderDataMesh,
+  deriveRenderDataTexture,
+} from '../../../render/src/render-data';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+import { matchPass } from '../../../render/src/systems/pass-selector';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
+
+function makeExplicitNullRhi(spies: {
+  setIndexBuffer: ReturnType<typeof vi.fn>;
+  setVertexBuffer: ReturnType<typeof vi.fn>;
+  draw: ReturnType<typeof vi.fn>;
+  drawIndexed: ReturnType<typeof vi.fn>;
+}): unknown {
+  const adapter = new RhiNullAdapter();
+  const requestDevice = adapter.requestDevice.bind(adapter);
+  adapter.requestDevice = async () => {
+    const result = await requestDevice();
+    if (result.ok) {
+      const device = result.value;
+      const createCommandEncoder = device.createCommandEncoder.bind(device);
+      device.createCommandEncoder = (desc) => {
+        const encoderResult = createCommandEncoder(desc);
+        if (!encoderResult.ok) return encoderResult;
+        const encoder = encoderResult.value;
+        const beginRenderPass = encoder.beginRenderPass.bind(encoder);
+        encoder.beginRenderPass = (passDesc) => {
+          const pass = beginRenderPass(passDesc);
+          const draw = pass.draw.bind(pass);
+          const drawIndexed = pass.drawIndexed.bind(pass);
+          const setIndexBuffer = pass.setIndexBuffer.bind(pass);
+          const setVertexBuffer = pass.setVertexBuffer.bind(pass);
+          pass.draw = (...args) => {
+            spies.draw(...args);
+            draw(...args);
+          };
+          pass.drawIndexed = (...args) => {
+            spies.drawIndexed(...args);
+            drawIndexed(...args);
+          };
+          pass.setIndexBuffer = (...args) => {
+            spies.setIndexBuffer(...args);
+            setIndexBuffer(...args);
+          };
+          pass.setVertexBuffer = (...args) => {
+            spies.setVertexBuffer(...args);
+            setVertexBuffer(...args);
+          };
+          return pass;
+        };
+        return { ok: true, value: encoder };
+      };
+    }
+    return result;
+  };
+  return {
+    requestAdapter: async () => ({ ok: true, value: adapter }),
+    acquireCanvasContext: acquireNullCanvasContext,
+    createShaderModule: (device: unknown, desc: { code: string; label?: string }) =>
+      createNullShaderModule(device as never, desc),
+  };
+}
+
+vi.mock('@forgeax/engine-rhi-wgpu', () => {
+  return {
+    rhi: {
+      requestAdapter: async () => ({
+        ok: false,
+        error: {
+          code: 'adapter-unavailable',
+          expected: 'adapter available',
+          hint: 'default mock fail',
+        },
+      }),
+      getPreferredCanvasFormat: () => 'bgra8unorm',
+      acquireCanvasContext: () => ({
+        ok: false,
+        error: {
+          code: 'webgpu-runtime-error',
+          expected: 'context available',
+          hint: 'default mock fail',
+        },
+      }),
+    },
+    ensureReady: async () => undefined,
+  };
+});
+
+void [
+  Camera,
+  ChildOf,
+  GpuResidencyCache,
+  HANDLE_CUBE,
+  HANDLE_TRIANGLE,
+  HdrpInstallError,
+  MeshFilter,
+  MeshRenderer,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+  RhiError,
+  RhiNullAdapter,
+  Transform,
+  World,
+  acquireNullCanvasContext,
+  afterEach,
+  assertStorageBufferCap,
+  beforeEach,
+  bin,
+  buildMeshAttributeMapForUvSets,
+  buildPbrPipelineLayouts,
+  buildPbrViewBglEntries,
+  buildPipelineForMaterialShader,
+  cacheKeyOf,
+  calculateSphereClusterBounds,
+  clusterSpaceObjectAabb,
+  createBoxGeometry,
+  createConeGeometry,
+  createCylinderGeometry,
+  createEngineMetrics,
+  createHdrpBindGroupLayoutDescriptor,
+  createNullShaderModule,
+  createPlaneGeometry,
+  createSphereGeometry,
+  createTorusGeometry,
+  defineComponent,
+  deriveCullingRadius,
+  deriveRenderDataCubemap,
+  deriveRenderDataMesh,
+  deriveRenderDataTexture,
+  describe,
+  dirname,
+  err,
+  existsSync,
+  expect,
+  extractFrame,
+  fileURLToPath,
+  findVariantByKey,
+  it,
+  makeExplicitNullRhi,
+  makeMockShaderRegistry,
+  mat4,
+  matchPass,
+  ndcPositionToCluster,
+  ok,
+  prepareExtractContext,
+  readFileSync,
+  resolve,
+  resolveAssetHandle,
+  rhiOk,
+  standardMaterialShaderVariants,
+  toShared,
+  validateClusterGrid,
+  vec3,
+  vi,
+  viewZToZSlice,
+];
+type __MergedKeep =
+  | AssetError
+  | ClusterBinError
+  | EquirectAsset
+  | Handle
+  | Mat4
+  | MaterialRenderState
+  | MaterialShaderEntry
+  | MaterialShaderManifestEntry
+  | MaterialShaderManifestVariant
+  | MeshAsset
+  | PassSelector
+  | PbrCaps
+  | PipelineBuilderContext
+  | PipelineBuilderShaderModuleFactory
+  | PipelineLayout
+  | PipelineSpec
+  | PrimitiveTopology
+  | RenderPipeline
+  | RenderPipelineAsset
+  | RendererType
+  | Result
+  | RhiCaps
+  | RhiDevice
+  | ShaderModule
+  | TextureAsset
+  | Vec3
+  | WorldType;
+
+{
+  // --- from create-renderer-fallback-shader-manifest.test.ts ---
+  const CREATE_RENDERER_SRC = fileURLToPath(
+    new URL('../../../render/src/assembly/webgpu-renderer.ts', import.meta.url),
+  );
+
+  describe('createRenderer fallback shaderManifestUrl literal (AC-08, D-2 q5-A)', () => {
+    it("preserves the '/shaders/manifest.json' default in createRenderer.ts", () => {
+      const source = readFileSync(CREATE_RENDERER_SRC, 'utf8');
+      // The literal fallback expression is the SSOT: when bundler.shaderManifestUrl
+      // is absent and the explicit options.shaderManifestUrl key is not present,
+      // the fallback resolves to '/shaders/manifest.json'. Locking the literal
+      // here means a future drift (e.g. someone moves it into a constant or
+      // changes the path) shows up as a clear test failure pointing at this AC.
+      expect(source).toContain("'/shaders/manifest.json'");
+    });
+
+    it('references the fallback through the bundler third arg, not RendererOptions', () => {
+      const source = readFileSync(CREATE_RENDERER_SRC, 'utf8');
+      // After M2, the explicit slot is read from the third-arg BundlerOptions.
+      // The grep below pins the contract: BundlerOptions carries the field, and
+      // the createRenderer body looks up `bundler.shaderManifestUrl` (or the
+      // legacy explicit slot via `'shaderManifestUrl' in bundler`).
+      expect(source).toMatch(/bundler\??\.shaderManifestUrl/);
+    });
+  });
+}