@forgeax/engine-runtime 0.1.2

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

@@ -0,0 +1,2265 @@
+// @ts-nocheck — merged file: cross-source type narrowing failures from blocks originally outside src/ rootDir
+// 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=7):
+//   - packages/runtime/src/__tests__/builder-topology-stripIndexFormat.test.ts
+//   - packages/runtime/src/__tests__/frustum-culling.test.ts
+//   - packages/runtime/src/__tests__/instances.test.ts
+//   - packages/runtime/src/__tests__/mesh-gpu-handles-vertex-only.test.ts
+//   - packages/runtime/src/__tests__/mesh-ssbo-grow.test.ts
+//   - packages/runtime/src/__tests__/mesh-update-no-leak.test.ts
+//   - packages/runtime/src/__tests__/instances-with-submeshes.test.ts
+//
+// feat-20260704-runtime-tier1-decomposition (w6): the geometry-pure blocks
+// (geometry-tangent / geometry-winding / geometry / vertex-attribute-layout)
+// moved to packages/geometry/src/__tests__/geometry.unit.test.ts (leaf package
+// must not import runtime -- D-2).
+
+//
+// Paradigm: each block-scoped describe('<source-filename>.test.ts', ...) preserves
+// source as ancestorTitles[0]. Top-level imports merged + deduped.
+
+import type { World as WorldType } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import type { Renderer as RendererType } from '@forgeax/engine-render';
+import type { RenderAssetPort, RenderError, SkinError } from '@forgeax/engine-render/internal';
+import {
+  Camera,
+  createMeshSsboGrowController,
+  Instances,
+  MeshFilter,
+  MeshRenderer,
+} from '@forgeax/engine-render/internal';
+import type { PipelineLayout, RenderPipeline, RhiDevice, ShaderModule } from '@forgeax/engine-rhi';
+import { Transform } from '@forgeax/engine-scene';
+import type { AssetErrorDetail, Handle, MeshAsset } from '@forgeax/engine-types';
+import { ASSET_ERROR_HINTS, type AssetError, unwrapHandle } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// feat-20260704-runtime-tier1-decomposition M2 / w12: reconstitute the
+// eliminated top-level RuntimeError aggregate union (D-3) as a test-local alias
+// so the errorRegistry.fire mock callback signatures below stay byte-identical
+// (AC-09). Equal to RenderError | AssetError | SkinError.
+type RuntimeLayerError = RenderError | AssetError | SkinError;
+
+import type {
+  ExtractedFrame,
+  GpuBuffer,
+  MeshGpuHandles,
+  PipelineBuilderContext,
+  PipelineBuilderShaderModuleFactory,
+} from '@forgeax/engine-render/internal';
+import {
+  buildPipelineForMaterialShader,
+  ensureMeshSsboCapacity,
+  extractFrame,
+  GpuResourceStore,
+  isMeshSsboDevMode,
+  prepareExtractContext,
+  setMeshSsboDevModeProbeForTests,
+} from '@forgeax/engine-render/internal';
+import { propagateTransforms } from '@forgeax/engine-scene';
+import {
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  DEFAULT_UNLIT_PARAM_SCHEMA,
+} from '@forgeax/engine-shader';
+import {
+  canonicalDefaultMaterialVariants,
+  makeMockShaderRegistry,
+} from './helpers/mock-shader-registry';
+import { registerRuntimeComponents } from './helpers/register-runtime-components';
+
+function canonicalMaterialParamSchema(identifier: string): string {
+  if (identifier === 'forgeax::default-standard-pbr') {
+    return JSON.stringify(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
+  }
+  if (identifier === 'forgeax::default-unlit') {
+    return JSON.stringify(DEFAULT_UNLIT_PARAM_SCHEMA);
+  }
+  return '[]';
+}
+
+{
+  // --- from builder-topology-stripIndexFormat.test.ts ---
+  // builder-topology-stripIndexFormat.test.ts
+  // feat-20260604-mesh-topology-debug-draw M3 / w6 (test, TDD red phase).
+  //
+  // Verifies that buildPipelineForMaterialShader (pipeline-builder.ts, the real
+  // exported entry point) bakes the supplied topology into the immutable
+  // GPURenderPipeline `primitive.topology`, and sets `primitive.stripIndexFormat`
+  // for strip topologies while leaving it undefined for non-strip topologies.
+  //
+  // Approach: drive the real `buildPipelineForMaterialShader` with vi.fn mocks
+  // (same harness as renderstate-pipeline-cache.test.ts) and inspect the
+  // descriptor passed to `device.createRenderPipeline`. This is the AC-08
+  // verification surface against the actual builder, not a reproduction.
+  //
+  // Tests:
+  //   (a) AC-08: explicit topology reaches primitive.topology.
+  //   (b) AC-03: omitted geometry -> primitive.topology defaults to
+  //       'triangle-list' (zero-regression).
+  //   (c) AC-08: strip topology + indexFormat -> primitive.stripIndexFormat
+  //       equals the mesh indexFormat.
+  //   (d) AC-08: non-strip topology -> primitive.stripIndexFormat is undefined
+  //       (WebGPU spec: stripIndexFormat is only valid for strip topologies).
+  //
+  // Anchors:
+  //   - requirements AC-03 / AC-08
+  //   - plan-strategy D-A3 (builder topology param) + D-c (stripIndexFormat point)
+  //   - research Finding 3 (stripIndexFormat spec rule) + Finding 5 (:205-209 hardcode)
+
+  function makeMockEntry() {
+    return {
+      source: '@vertex fn vs_main() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+      paramSchema: [],
+    };
+  }
+
+  function makeMocks() {
+    const shaderModule = { __tag: 'mock-shader-module' } as unknown as ShaderModule;
+    const renderPipeline = { __tag: 'mock-render-pipeline' } as unknown as RenderPipeline;
+    const createShaderModule = vi.fn(() => ({
+      ok: true as const,
+      value: shaderModule,
+      unwrap: () => shaderModule,
+      unwrapOr: (_d: unknown) => shaderModule,
+    }));
+    const createRenderPipeline = vi.fn(() => ({
+      ok: true as const,
+      value: renderPipeline,
+      unwrap: () => renderPipeline,
+      unwrapOr: (_d: unknown) => renderPipeline,
+    }));
+    return {
+      factory: { createShaderModule } as unknown as PipelineBuilderShaderModuleFactory,
+      device: { createRenderPipeline } as unknown as Pick<RhiDevice, 'createRenderPipeline'>,
+      createShaderModule,
+      createRenderPipeline,
+    };
+  }
+
+  function makeMockContext(mocks: ReturnType<typeof makeMocks>): PipelineBuilderContext {
+    return {
+      device: mocks.device as unknown as RhiDevice,
+      shaderModuleFactory: mocks.factory,
+      pipelineLayout: { __tag: 'mock-pipeline-layout' } as unknown as PipelineLayout,
+      colorFormat: 'bgra8unorm-srgb',
+      depthFormat: 'depth24plus-stencil8',
+      vertexBuffers: [
+        {
+          arrayStride: 12 * 4,
+          attributes: [
+            { shaderLocation: 0, offset: 0, format: 'float32x3' },
+            { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' },
+            { shaderLocation: 2, offset: 6 * 4, format: 'float32x2' },
+            { shaderLocation: 3, offset: 8 * 4, format: 'float32x4' },
+          ],
+        },
+      ] as unknown as readonly GPUVertexBufferLayout[],
+    };
+  }
+
+  function descOf(mocks: ReturnType<typeof makeMocks>): Record<string, unknown> {
+    return (mocks.createRenderPipeline.mock.calls as unknown[][])[0]?.[0] as Record<
+      string,
+      unknown
+    >;
+  }
+
+  describe('buildPipelineForMaterialShader topology + stripIndexFormat (AC-03/08)', () => {
+    it('(a) AC-08: explicit topology reaches primitive.topology', () => {
+      const mocks = makeMocks();
+      const ctx = makeMockContext(mocks);
+      buildPipelineForMaterialShader('test::lines', makeMockEntry(), ctx, undefined, {
+        topology: 'line-list',
+      });
+
+      const primitive = descOf(mocks).primitive as { topology: string };
+      expect(primitive.topology).toBe('line-list');
+    });
+
+    it('(b) AC-03: omitted geometry -> primitive.topology defaults to triangle-list', () => {
+      const mocks = makeMocks();
+      const ctx = makeMockContext(mocks);
+      buildPipelineForMaterialShader('test::default-topo', makeMockEntry(), ctx);
+
+      const primitive = descOf(mocks).primitive as { topology: string };
+      expect(primitive.topology).toBe('triangle-list');
+    });
+
+    it('(b) AC-03: empty geometry object -> primitive.topology defaults to triangle-list', () => {
+      const mocks = makeMocks();
+      const ctx = makeMockContext(mocks);
+      buildPipelineForMaterialShader('test::empty-geo', makeMockEntry(), ctx, undefined, {});
+
+      const primitive = descOf(mocks).primitive as { topology: string };
+      expect(primitive.topology).toBe('triangle-list');
+    });
+
+    it('(c) AC-08: line-strip + uint16 -> primitive.stripIndexFormat is uint16', () => {
+      const mocks = makeMocks();
+      const ctx = makeMockContext(mocks);
+      buildPipelineForMaterialShader('test::line-strip', makeMockEntry(), ctx, undefined, {
+        topology: 'line-strip',
+        stripIndexFormat: 'uint16',
+      });
+
+      const primitive = descOf(mocks).primitive as { topology: string; stripIndexFormat?: string };
+      expect(primitive.topology).toBe('line-strip');
+      expect(primitive.stripIndexFormat).toBe('uint16');
+    });
+
+    it('(c) AC-08: triangle-strip + uint32 -> primitive.stripIndexFormat is uint32', () => {
+      const mocks = makeMocks();
+      const ctx = makeMockContext(mocks);
+      buildPipelineForMaterialShader('test::tri-strip', makeMockEntry(), ctx, undefined, {
+        topology: 'triangle-strip',
+        stripIndexFormat: 'uint32',
+      });
+
+      const primitive = descOf(mocks).primitive as { topology: string; stripIndexFormat?: string };
+      expect(primitive.topology).toBe('triangle-strip');
+      expect(primitive.stripIndexFormat).toBe('uint32');
+    });
+
+    it('(d) AC-08: triangle-list (non-strip) -> primitive.stripIndexFormat is undefined', () => {
+      const mocks = makeMocks();
+      const ctx = makeMockContext(mocks);
+      buildPipelineForMaterialShader('test::tri-list', makeMockEntry(), ctx, undefined, {
+        topology: 'triangle-list',
+        stripIndexFormat: 'uint16',
+      });
+
+      const primitive = descOf(mocks).primitive as { stripIndexFormat?: string };
+      expect(primitive.stripIndexFormat).toBeUndefined();
+    });
+
+    it('(d) AC-08: line-list (non-strip) -> primitive.stripIndexFormat is undefined', () => {
+      const mocks = makeMocks();
+      const ctx = makeMockContext(mocks);
+      buildPipelineForMaterialShader('test::line-list', makeMockEntry(), ctx, undefined, {
+        topology: 'line-list',
+        stripIndexFormat: 'uint32',
+      });
+
+      const primitive = descOf(mocks).primitive as { stripIndexFormat?: string };
+      expect(primitive.stripIndexFormat).toBeUndefined();
+    });
+
+    it('AC-08: topology + renderState compose (cullMode still honored)', () => {
+      const mocks = makeMocks();
+      const ctx = makeMockContext(mocks);
+      buildPipelineForMaterialShader(
+        'test::compose',
+        makeMockEntry(),
+        ctx,
+        { cullMode: 'none' },
+        { topology: 'line-list' },
+      );
+
+      const primitive = descOf(mocks).primitive as { topology: string; cullMode: string };
+      expect(primitive.topology).toBe('line-list');
+      expect(primitive.cullMode).toBe('none');
+    });
+  });
+}
+
+{
+  // --- from frustum-culling.test.ts ---
+  // frustum-culling.test.ts — feat-20260528-frustum-culling M3 / w9 (TDD red).
+  //
+  // Tests for frustum culling in the extract phase. Frustum culling skips
+  // RenderableSnapshot push for entities whose world-space AABB does not
+  // intersect any camera's view frustum.
+  //
+  // Coverage:
+  //   (1) entity outside frustum → culled (not in renderables)
+  //   (2) entity inside frustum → not culled (in renderables)
+  //   (4) no AABB (undefined/inverted-infinity) → always visible
+  //   (5) instanced mesh → union AABB granularity
+  //   (6) multi-camera → each camera independently culls
+  //   (7) culling runs unconditionally (entity behind camera is culled)
+  //   (8) entity exactly on frustum boundary → not culled
+  //   (9) entity wholly outside all cameras → culled
+  //   (10) mixed scene: inside + outside entities produce correct split
+  //
+  // Anchors: requirements AC-13 (frustum culling during extract);
+  // plan-strategy D-5 (entity-level union AABB, no per-instance expansion);
+  // research §F-5 (Gribb/Hartmann frustum plane extraction).
+
+  // ── helpers ──────────────────────────────────────────────────────────────
+
+  function translateTransform(
+    x: number,
+    y: number,
+    z: number,
+  ): {
+    posX: number;
+    posY: number;
+    posZ: number;
+    quatX: number;
+    quatY: number;
+    quatZ: number;
+    quatW: number;
+    scaleX: number;
+    scaleY: number;
+    scaleZ: number;
+  } {
+    return {
+      pos: [x, y, z],
+      quat: [0, 0, 0, 1],
+      scale: [1, 1, 1],
+    };
+  }
+
+  function perspectiveCameraData(
+    fov = Math.PI / 4,
+    aspect = 1,
+    near = 0.1,
+    far = 100,
+  ): {
+    fov: number;
+    aspect: number;
+    near: number;
+    far: number;
+    projection: number;
+    left: number;
+    right: number;
+    bottom: number;
+    top: number;
+  } {
+    return { fov, aspect, near, far, projection: 0, left: -1, right: 1, bottom: -1, top: 1 };
+  }
+
+  function registerMesh(world: World, aabb: Float32Array): Handle<'MeshAsset', 'shared'> {
+    // Minimal mesh: 1 triangle at origin with AABB
+    const vertices = new Float32Array([
+      0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0,
+      1, 0, 0, 0, 0,
+    ]);
+    return world.allocSharedRef('MeshAsset', {
+      kind: 'mesh',
+      vertices,
+      indices: new Uint16Array([0, 1, 2]),
+      attributes: { position: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]) },
+      aabb,
+      materialSlots: [{ slotName: 'Default' }],
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: vertices.length,
+          materialSlot: 0,
+          topology: 'triangle-list',
+        },
+      ],
+    });
+  }
+
+  function registerUnlitMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
+    return world.allocSharedRef('MaterialAsset', {
+      kind: 'material',
+      passes: [
+        {
+          name: 'Forward',
+          program: { module: 'forgeax::default-unlit' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+        },
+      ],
+      values: { baseColor: [1, 1, 1] },
+    });
+  }
+
+  function makeRenderAssetPort(): RenderAssetPort {
+    const shaderRegistry = makeMockShaderRegistry();
+    return {
+      epoch: 0,
+      shaderRegistry,
+      lookup: () => undefined,
+      guidOf: () => undefined,
+      materialShaderTextureFieldNames: () => [],
+    };
+  }
+
+  function makeWorldWithAssets(): {
+    world: World;
+    assets: RenderAssetPort;
+    meshHandle: Handle<'MeshAsset', 'shared'>;
+    matHandle: Handle<'MaterialAsset', 'shared'>;
+  } {
+    const world = new World();
+    const assets = makeRenderAssetPort();
+
+    // AABB: unit cube [-1,1] in each axis
+    const aabb = new Float32Array([-1, -1, -1, 1, 1, 1]);
+    const meshHandle = registerMesh(world, aabb);
+    const matHandle = registerUnlitMaterial(world);
+    return { world, assets, meshHandle, matHandle };
+  }
+
+  /** Spawn a renderable entity at (x,y,z). */
+  function spawnEntity(
+    world: World,
+    meshHandle: Handle<'MeshAsset', 'shared'>,
+    matHandle: Handle<'MaterialAsset', 'shared'>,
+    x = 0,
+    y = 0,
+    z = 0,
+  ): void {
+    world
+      .spawn(
+        { component: Transform, data: translateTransform(x, y, z) },
+        { component: MeshFilter, data: { assetHandle: meshHandle } },
+        { component: MeshRenderer, data: { materials: [matHandle] } },
+      )
+      .unwrap();
+  }
+
+  /** Add a camera at the given position looking along -Z. */
+  function spawnCameraAt(
+    world: World,
+    x: number,
+    y: number,
+    z: number,
+    fov = Math.PI / 4,
+    aspect = 1,
+    near = 0.1,
+    far = 100,
+  ): void {
+    world
+      .spawn(
+        {
+          component: Transform,
+          data: {
+            pos: [x, y, z],
+            quat: [0, 0, 0, 1],
+            scale: [1, 1, 1],
+          },
+        },
+        { component: Camera, data: perspectiveCameraData(fov, aspect, near, far) },
+      )
+      .unwrap();
+  }
+
+  // ── tests ────────────────────────────────────────────────────────────────
+
+  describe('Extract-stage frustum culling (M3 w9)', () => {
+    it('(1) entity far outside frustum (behind camera) is culled', () => {
+      const { world, assets, meshHandle, matHandle } = makeWorldWithAssets();
+      spawnCameraAt(world, 0, 0, 5); // camera at z=5 looking -Z
+      // entity behind camera (z=6, while camera is at z=5 looking -Z → negative-Z is behind)
+      spawnEntity(world, meshHandle, matHandle, 0, 0, 6);
+
+      propagateTransforms(world);
+
+      const frame: ExtractedFrame = extractFrame(world, prepareExtractContext(world, { assets }));
+      expect(frame.renderables).toHaveLength(0);
+    });
+
+    it('(1b) entity far to the left of frustum is culled', () => {
+      const { world, assets, meshHandle, matHandle } = makeWorldWithAssets();
+      spawnCameraAt(world, 0, 0, 10); // camera at z=10 looking -Z, fov=90, near=0.1, far=100
+      // entity far to the left (x=-50, way outside frustum with aspect=1, fov=90 at z=0)
+      spawnEntity(world, meshHandle, matHandle, -50, 0, 0);
+
+      propagateTransforms(world);
+
+      const frame: ExtractedFrame = extractFrame(world, prepareExtractContext(world, { assets }));
+      expect(frame.renderables).toHaveLength(0);
+    });
+
+    it('(2) entity inside frustum is not culled', () => {
+      const { world, assets, meshHandle, matHandle } = makeWorldWithAssets();
+      spawnCameraAt(world, 0, 0, 5);
+      // entity directly in front of camera at z=0 (between near=0.1 and far=100)
+      spawnEntity(world, meshHandle, matHandle, 0, 0, 0);
+
+      propagateTransforms(world);
+
+      const frame: ExtractedFrame = extractFrame(world, prepareExtractContext(world, { assets }));
+      expect(frame.renderables).toHaveLength(1);
+    });
+
+    it('(4) entity with no position attribute (AABB is inverted-infinity) is always visible', () => {
+      const world = new World();
+      const assets = makeRenderAssetPort();
+
+      // A mesh with no position attribute has no finite culling bounds and is always visible.
+      const vertices = new Float32Array([
+        0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0,
+        1, 0, 0, 0, 0,
+      ]);
+      const meshHandle = world.allocSharedRef('MeshAsset', {
+        kind: 'mesh',
+        vertices,
+        indices: new Uint16Array([0, 1, 2]),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 3,
+            vertexCount: vertices.length,
+            materialSlot: 0,
+            topology: 'triangle-list',
+          },
+        ],
+      });
+      const matHandle = registerUnlitMaterial(world);
+
+      spawnCameraAt(world, 0, 0, 5);
+      world
+        .spawn(
+          { component: Transform, data: translateTransform(100, 100, 100) },
+          { component: MeshFilter, data: { assetHandle: meshHandle } },
+          { component: MeshRenderer, data: { materials: [matHandle] } },
+        )
+        .unwrap();
+
+      propagateTransforms(world);
+
+      const frame: ExtractedFrame = extractFrame(world, prepareExtractContext(world, { assets }));
+      expect(frame.renderables).toHaveLength(1);
+    });
+
+    it('(4b) entity with inverted-infinity AABB (no position attribute) is always visible', () => {
+      const { world, assets, matHandle } = makeWorldWithAssets();
+      // A mesh with no position attribute has no finite culling bounds.
+      const vertices = new Float32Array([
+        0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0,
+        1, 0, 0, 0, 0,
+      ]);
+      const meshHandle = world.allocSharedRef('MeshAsset', {
+        kind: 'mesh',
+        vertices,
+        indices: new Uint16Array([0, 1, 2]),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 3,
+            vertexCount: vertices.length,
+            materialSlot: 0,
+            topology: 'triangle-list',
+          },
+        ],
+      });
+
+      spawnCameraAt(world, 0, 0, 5);
+      spawnEntity(world, meshHandle, matHandle, 100, 100, 100);
+
+      propagateTransforms(world);
+
+      const frame: ExtractedFrame = extractFrame(world, prepareExtractContext(world, { assets }));
+      expect(frame.renderables).toHaveLength(1);
+    });
+
+    it('(7) culling runs unconditionally (entity behind camera is culled)', () => {
+      const { world, assets, meshHandle, matHandle } = makeWorldWithAssets();
+      spawnCameraAt(world, 0, 0, 5);
+      // entity behind camera
+      world
+        .spawn(
+          { component: Transform, data: translateTransform(0, 0, 6) },
+          { component: MeshFilter, data: { assetHandle: meshHandle } },
+          { component: MeshRenderer, data: { materials: [matHandle] } },
+        )
+        .unwrap();
+
+      propagateTransforms(world);
+
+      const frame: ExtractedFrame = extractFrame(world, prepareExtractContext(world, { assets }));
+      // culling is unconditional, so entity behind camera is culled
+      expect(frame.renderables).toHaveLength(0);
+    });
+
+    it('(8) entity exactly on frustum near-plane boundary is not culled', () => {
+      const { world, assets, meshHandle, matHandle } = makeWorldWithAssets();
+      // camera at z=10, near=0.1. Entity at z=9.9 is inside. AABB [-1,1] unit cube → extends
+      // from z=8.9 to z=10.9. The near plane is at cameraZ - near = 9.9. Box extends to 10.9
+      // which is beyond the near plane (in frustum direction) → not culled.
+      spawnCameraAt(world, 0, 0, 10, Math.PI / 4, 1, 0.1, 100);
+      spawnEntity(world, meshHandle, matHandle, 0, 0, 9.9);
+
+      propagateTransforms(world);
+
+      const frame: ExtractedFrame = extractFrame(world, prepareExtractContext(world, { assets }));
+      expect(frame.renderables).toHaveLength(1);
+    });
+
+    it('(10) mixed scene: inside + outside → only inside survive', () => {
+      const { world, assets, meshHandle, matHandle } = makeWorldWithAssets();
+      spawnCameraAt(world, 0, 0, 5);
+
+      // entity in front (should survive)
+      spawnEntity(world, meshHandle, matHandle, 0, 0, 0);
+      // entity far behind (should be culled)
+      spawnEntity(world, meshHandle, matHandle, 0, 0, 100);
+      // entity far right (should be culled with fov=90, aspect=1)
+      spawnEntity(world, meshHandle, matHandle, 50, 0, 0);
+
+      propagateTransforms(world);
+
+      const frame: ExtractedFrame = extractFrame(world, prepareExtractContext(world, { assets }));
+      expect(frame.renderables).toHaveLength(1);
+    });
+
+    it('(6) multi-camera: entity inside one frustum but outside another', () => {
+      const { world, assets, meshHandle, matHandle } = makeWorldWithAssets();
+
+      // Camera A at z=5 looking -Z; entity at (0,0,0) is in front of camera A
+      spawnCameraAt(world, 0, 0, 5);
+
+      // entity in front of both cameras
+      spawnEntity(world, meshHandle, matHandle, 0, 0, 0);
+
+      propagateTransforms(world);
+
+      const frame: ExtractedFrame = extractFrame(world, prepareExtractContext(world, { assets }));
+      // The entity is in front of the camera → should be in renderables
+      expect(frame.renderables).toHaveLength(1);
+    });
+
+    it('(6b) multi-camera: entity outside all camera frusta is culled', () => {
+      const { world, assets, meshHandle, matHandle } = makeWorldWithAssets();
+      // camera A at z=5, camera B at z=-5 looking +Z
+      spawnCameraAt(world, 0, 0, 5);
+      // entity far behind all cameras (z=100, behind camera at z=5 and far from camera at z=-5)
+      spawnCameraAt(world, 0, 0, -5); // looking -Z
+      spawnEntity(world, meshHandle, matHandle, 0, 0, 100);
+
+      propagateTransforms(world);
+
+      const frame: ExtractedFrame = extractFrame(world, prepareExtractContext(world, { assets }));
+      // Entity at z=100 is behind camera at z=5 (looking -Z → behind means >5).
+      // It's also behind camera at z=-5 (looking -Z → greater means behind).
+      // With small AABB [-1,1], it should be outside both frusta.
+      expect(frame.renderables).toHaveLength(0);
+    });
+  });
+}
+
+{
+  // --- from instances.test.ts ---
+  // w14 - Instances component schema migration to `array<f32>` (M3, AC-06).
+  //
+  // Locks AC-06 (requirements.md): the `transforms: 'array<f32>'` field
+  // resolves to a fresh `Float32Array` snapshot at the get-site. The stride
+  // contract (length must be a non-zero multiple of 16) lives at the
+  // RenderSystem extract entry (`packages/runtime/src/render-system-extract.ts`)
+  // + the AI user set-site -- the ECS layer is stride-agnostic
+  // post-feat-20260515-buffer-array-vocab-collapse (decision §2.3).
+  //
+  // feat-20260515-buffer-array-vocab-collapse M3 / w16: the legacy
+  // component-level per-component stride defineComponent option was retired;
+  // stride violations now route the runtime-side
+  // `instance-transforms-stride-mismatch` error through the Layer-3
+  // ErrorHandler from the RenderSystem extract entry rather than from the
+  // ECS write paths. The runtime defensive coverage lives in
+  // `render-system-stride.test.ts` (w14); this file covers the ECS-side
+  // schema + happy-path read invariants only.
+  //
+  // Test path note: project convention places runtime tests under
+  // `src/__tests__/` (see `instances.test-d.ts` header for the rationale).
+
+  function makeHarness(): { world: World } {
+    return { world: new World() };
+  }
+
+  describe('w14 - Instances { transforms: array<f32> } schema (AC-06)', () => {
+    it('componentSchema(Instances).transforms is the array<f32> keyword (no legacy buffer/count fields)', () => {
+      expect(Instances.name).toBe('Instances');
+      expect(Object.keys(componentSchema(Instances)).length).toBe(1);
+      expect((componentSchema(Instances) as Record<string, unknown>).transforms).toBe('array<f32>');
+      // Legacy fields retired in M3.
+      expect((componentSchema(Instances) as Record<string, unknown>).buffer).toBeUndefined();
+      expect((componentSchema(Instances) as Record<string, unknown>).count).toBeUndefined();
+    });
+
+    it('Instances component carries no per-component stride option (decision §2.3 migration)', () => {
+      // The retired component-level stride option key would have surfaced as
+      // a property on the Component token; its absence is the SSOT lock for
+      // "ECS layer is stride-agnostic".
+      expect((Instances as unknown as Record<string, unknown>).arrayStride).toBeUndefined();
+    });
+
+    it('(legal) spawn with 16 f32 multiples succeeds; snapshot length reflects element count', () => {
+      const { world } = makeHarness();
+      const N = 4;
+      const transforms = new Float32Array(N * 16);
+      // Fill column 3 with distinguishable translations so the read path can
+      // assert the bytes survived the BufferPool round-trip.
+      for (let i = 0; i < N; i++) {
+        transforms[i * 16 + 12] = i + 1;
+        transforms[i * 16 + 15] = 1;
+      }
+      const e = world.spawn({ component: Instances, data: { transforms } }).unwrap();
+      const snap = world.get(e, Instances).unwrap().transforms;
+      expect(snap.length).toBe(N * 16);
+      // Sanity: column 3 translation x of instance 2 reads back as 3.
+      expect(snap[2 * 16 + 12]).toBe(3);
+    });
+
+    it('(ECS layer is stride-agnostic) spawn with 17 f32 does NOT route a stride error from ECS', () => {
+      const { world } = makeHarness();
+      world.spawn({ component: Instances, data: { transforms: new Float32Array(17) } });
+      // The runtime-side defensive lives in render-system-extract; the ECS
+      // write path is deliberately stride-agnostic.
+    });
+  });
+}
+
+{
+  // --- from mesh-gpu-handles-vertex-only.test.ts ---
+  // mesh-gpu-handles-vertex-only.test - M2 / w3 (TDD).
+  //
+  // Coverage (vertex-only mesh upload chain through GpuResourceStore):
+  //   (a) MeshGpuHandles type carries `vertexCount: number` + `indexed: boolean`
+  //       and `indexBuffer: Buffer | null` (type-level via a const-assigned literal
+  //       that must compile).
+  //   (b) vertex-only mesh (no `indices`) upload -> `indexed === false`,
+  //       `indexBuffer === null`, and NO index buffer is created (createBuffer is
+  //       called once, for the vbo only -- spy assertion).
+  //   (c) indexed mesh upload -> `indexed === true`, `indexBuffer !== null`,
+  //       `vertexCount === vertices.length / 12`, and two buffers are created.
+  //
+  // (b) exercises the UPLOAD chain (`ensureResident` -> `uploadMeshById`), which
+  // derives GPU buffers from the POD argument, not from a registered asset. The
+  // vertex-only register-time validation relaxation (validateMeshPayload index
+  // guard) is M5 / w13, so we mint a handle from a valid indexed mesh and feed a
+  // vertex-only POD to `ensureResident` -- isolating the M2 upload surface.
+  //
+  // Anchors: requirements AC-02 (indexed unchanged) + AC-07 (vertex-only);
+  //          plan-strategy D-A1 + D-a (vertexCount = vertices.length / 12);
+  //          research Finding 9 (the 3 upload paths read indices unconditionally).
+
+  const mockCaps = {
+    backendKind: 'webgpu' as const,
+    compute: true,
+    timestampQuery: false,
+    timestampPeriodNanoseconds: null,
+    indirectDrawing: false,
+    textureCompressionBc: false,
+    textureCompressionEtc2: false,
+    textureCompressionAstc: false,
+    multiDrawIndirect: false,
+    pushConstants: false,
+    textureBindingArray: false,
+    samplerAliasing: false,
+    firstInstanceIndirect: false,
+    storageBuffer: true,
+    storageTexture: false,
+    rgba16floatRenderable: true,
+    rg11b10ufloatRenderable: false,
+    float32Filterable: false,
+  };
+
+  interface BufferProbe {
+    createdLabels: string[];
+  }
+
+  function canonicalAttributes(vertexCount: number): MeshAsset['attributes'] {
+    return {
+      position: new Float32Array(vertexCount * 3),
+      normal: new Float32Array(vertexCount * 3),
+      uv: new Float32Array(vertexCount * 2),
+      tangent: new Float32Array(vertexCount * 4),
+    };
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: opaque mock device surface
+  function makeMockDevice(probe: BufferProbe): any {
+    const okShim = <T>(v: T) => ({ ok: true as const, value: v });
+    return {
+      // biome-ignore lint/suspicious/noExplicitAny: descriptor shim
+      createBuffer: (desc: any) => {
+        probe.createdLabels.push(String(desc.label ?? ''));
+        return okShim({ __mock: 'buffer', label: desc.label });
+      },
+      queue: {
+        writeBuffer: () => okShim(undefined),
+      },
+    };
+  }
+
+  function makeIndexedMesh(): MeshAsset {
+    const vertices = new Float32Array(4 * 12); // 4 vertices x 12 floats
+    return {
+      kind: 'mesh',
+      vertices,
+      indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
+      attributes: canonicalAttributes(4),
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 6,
+          vertexCount: vertices.length,
+          topology: 'triangle-list',
+        },
+      ],
+    };
+  }
+
+  function makeVertexOnlyMesh(): MeshAsset {
+    const vertices = new Float32Array(2 * 12); // 2 vertices x 12 floats (one line)
+    return {
+      kind: 'mesh',
+      vertices,
+      attributes: canonicalAttributes(2),
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 0,
+          vertexCount: vertices.length,
+          topology: 'line-list',
+        },
+      ],
+    };
+  }
+
+  describe('w3 - MeshGpuHandles vertexCount / indexed / nullable indexBuffer', () => {
+    it('(a) MeshGpuHandles type carries vertexCount / indexed / nullable indexBuffer', () => {
+      // M-3 / w12: MeshGpuHandles.vertexBuffer is now a GpuBuffer wrapper +
+      // vboBytes / iboBytes byte-size fields are required. The fixture
+      // passes a stub GpuBuffer-shaped object (the test only inspects
+      // .indexed / .indexBuffer / .vertexCount, not the wrapper internals).
+      const vertexOnly: MeshGpuHandles = {
+        vertexBuffer: {} as unknown as GpuBuffer,
+        indexBuffer: null,
+        vboBytes: 0,
+        iboBytes: 0,
+        indexCount: 0,
+        indexFormat: 'uint16',
+        layoutProjection: deriveVertexLayoutProjection({
+          position: new Float32Array(6),
+          normal: new Float32Array(6),
+          uv: new Float32Array(4),
+          tangent: new Float32Array(8),
+        }),
+        vertexCount: 2,
+        indexed: false,
+        topology: 'line-list',
+        submeshes: [{ indexOffset: 0, indexCount: 0, vertexCount: 2, topology: 'line-list' }],
+      };
+      expect(vertexOnly.indexed).toBe(false);
+      expect(vertexOnly.indexBuffer).toBeNull();
+      expect(vertexOnly.vertexCount).toBe(2);
+    });
+
+    it('(b) vertex-only mesh upload skips the index buffer (indexed=false, indexBuffer=null)', () => {
+      const probe: BufferProbe = { createdLabels: [] };
+      const device = makeMockDevice(probe);
+      const world = new World();
+      const store = new GpuResourceStore();
+      store.configureGpuDevice(
+        device,
+        undefined,
+        (() => {
+          throw new Error('cube relay not used in mesh upload');
+          // biome-ignore lint/suspicious/noExplicitAny: relay shim
+        }) as any,
+        mockCaps,
+      );
+      // Mint a handle from a valid indexed mesh (register-time index validation
+      // relaxation is M5 / w13); feed a vertex-only POD to ensureResident to
+      // exercise the M2 upload chain in isolation.
+      const handle = world.allocSharedRef('MeshAsset', makeIndexedMesh());
+      const res = store.ensureResident(handle, makeVertexOnlyMesh());
+      expect(res.ok).toBe(true);
+      if (!res.ok) return;
+      const entry = res.value as MeshGpuHandles;
+      expect(entry.indexed).toBe(false);
+      expect(entry.indexBuffer).toBeNull();
+      expect(entry.vertexCount).toBe(2);
+      expect(entry.indexCount).toBe(0);
+      // Only the vertex buffer is created; no ibo create.
+      expect(probe.createdLabels.some((l) => l.includes('ibo'))).toBe(false);
+      expect(probe.createdLabels.some((l) => l.includes('vbo'))).toBe(true);
+    });
+
+    it('(c) indexed mesh upload keeps index buffer (indexed=true) + vertexCount correct', () => {
+      const probe: BufferProbe = { createdLabels: [] };
+      const device = makeMockDevice(probe);
+      const world = new World();
+      const store = new GpuResourceStore();
+      store.configureGpuDevice(
+        device,
+        undefined,
+        (() => {
+          throw new Error('cube relay not used in mesh upload');
+          // biome-ignore lint/suspicious/noExplicitAny: relay shim
+        }) as any,
+        mockCaps,
+      );
+      const handle = world.allocSharedRef('MeshAsset', makeIndexedMesh());
+      const res = store.ensureResident(handle, makeIndexedMesh());
+      expect(res.ok).toBe(true);
+      if (!res.ok) return;
+      const entry = res.value as MeshGpuHandles;
+      expect(entry.indexed).toBe(true);
+      expect(entry.indexBuffer).not.toBeNull();
+      expect(entry.vertexCount).toBe(4); // 48 floats / 12
+      expect(entry.indexCount).toBe(6);
+      expect(probe.createdLabels.some((l) => l.includes('ibo'))).toBe(true);
+    });
+  });
+}
+
+{
+  // --- from mesh-ssbo-grow.test.ts ---
+  // feat-20260608-mesh-ssbo-dynamic-grow-l1-lift-1024-entity-cap M2 / T-M2-02 +
+  // T-M2-03: unit tests for the mesh-SSBO grow controller — pow2 doubling +
+  // sync rebuild + usage parity (T-M2-02) + ceiling + idempotent guard +
+  // capacity-exceeded fallback (T-M2-03).
+  //
+  // Anchors:
+  //   - requirements §AC-05 (nextPow2 one-shot grow + createBuffer ordered
+  //     before the first writeBuffer)
+  //   - requirements §AC-06 (mesh + material rebuilt synchronously, usage flag
+  //     unchanged)
+  //   - requirements §AC-08 (ceiling fires 'mesh-ssbo-ceiling-reached' once,
+  //     0 writeBuffer / 0 draw)
+  //   - requirements §AC-09 (idempotent guard — same needed value calls grow
+  //     1 time then short-circuits)
+  //   - plan-strategy §2.D-1 (ceiling = device.limits.maxStorageBufferBindingSize
+  //     only — no engine-private constant)
+  //   - plan-strategy §2.D-4 (single-file grow factory; closure-local state)
+  //   - plan-strategy §2.D-5 (errorRegistry.fire, never throw)
+  //   - research §F2 (mesh + material createBuffer pair, distinct usage flags)
+  //   - research §F6.c (SkinPaletteAllocator spiritual cousin; 4-field error)
+  //
+  // Tests target the pure factory `createMeshSsboGrowController` (exported by
+  // createRenderer.ts at module scope, T-M2-05). The factory takes a fake
+  // device + errorRegistry and returns { state, growMeshSsbo, initialBuild }
+  // so we can spy createBuffer / errorRegistry.fire without spinning up a
+  // real WebGPU renderer.
+
+  // ── fake device + buffer ───────────────────────────────────────────────────
+
+  interface FakeBuffer {
+    readonly id: number;
+    readonly size: number;
+    readonly usage: number;
+    readonly label: string;
+    destroyed: boolean;
+  }
+
+  interface FakeBufferDescriptor {
+    readonly label?: string;
+    readonly size: number;
+    readonly usage: number;
+    readonly mappedAtCreation?: boolean;
+  }
+
+  interface FakeDeviceLimits {
+    readonly maxStorageBufferBindingSize: number;
+    readonly maxUniformBufferBindingSize: number;
+  }
+
+  function makeFakeDevice(limits: FakeDeviceLimits): {
+    device: { limits: FakeDeviceLimits; createBuffer: (d: FakeBufferDescriptor) => FakeBuffer };
+    createBufferSpy: ReturnType<typeof vi.fn>;
+  } {
+    let nextId = 1;
+    const createBufferSpy = vi.fn((d: FakeBufferDescriptor): FakeBuffer => {
+      const id = nextId;
+      nextId += 1;
+      const buf: FakeBuffer = {
+        id,
+        size: d.size,
+        usage: d.usage,
+        label: d.label ?? '',
+        destroyed: false,
+      };
+      return buf;
+    });
+    return {
+      device: {
+        limits,
+        createBuffer: createBufferSpy as unknown as (d: FakeBufferDescriptor) => FakeBuffer,
+      },
+      createBufferSpy,
+    };
+  }
+
+  function makeFakeErrorRegistry(): {
+    fire: ReturnType<typeof vi.fn>;
+  } {
+    const fireSpy = vi.fn((_e: RuntimeLayerError) => undefined);
+    return { fire: fireSpy };
+  }
+
+  // Spec-aligned constants (mirroring createRenderer.ts module-scope literals).
+  // PER_ENTITY_STRIDE matches plan-strategy §OOS-10 (kept at 256 B for both
+  // mesh + material — grow only changes slotCount, never stride).
+  const PER_ENTITY_STRIDE = 256;
+  const INITIAL_SLOT_COUNT = 1024;
+  const MESH_USAGE = 0x0080 /* STORAGE */ | 0x0008 /* COPY_DST */;
+  const MATERIAL_USAGE = 0x0040 /* UNIFORM */ | 0x0008 /* COPY_DST */;
+  const HIGH_LIMIT = 64 * 1024 * 1024; // 64 MiB — comfortable headroom for default cases
+
+  describe('T-M2-02 growMeshSsbo pow2 doubling + sync rebuild + usage parity', () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('(a) length=1500 from 1024 → grows once to 2048; createBuffer x2 (mesh+material); size ratio 256:256', () => {
+      const { device, createBufferSpy } = makeFakeDevice({
+        maxStorageBufferBindingSize: HIGH_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const { fire } = makeFakeErrorRegistry();
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fire as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      expect(createBufferSpy).toHaveBeenCalledTimes(2);
+      expect(ctrl.state.slotCount).toBe(1024);
+      createBufferSpy.mockClear();
+
+      const result = ctrl.growMeshSsbo(1500);
+      expect(result).toEqual({ ok: true });
+      expect(ctrl.state.slotCount).toBe(2048);
+      // 2 createBuffer calls (mesh + material) for the single grow step
+      expect(createBufferSpy).toHaveBeenCalledTimes(2);
+      const meshCall = createBufferSpy.mock.calls.find(
+        (c) => (c[0] as FakeBufferDescriptor).usage === MESH_USAGE,
+      );
+      const materialCall = createBufferSpy.mock.calls.find(
+        (c) => (c[0] as FakeBufferDescriptor).usage === MATERIAL_USAGE,
+      );
+      expect(meshCall).toBeDefined();
+      expect(materialCall).toBeDefined();
+      const meshDesc = meshCall?.[0] as FakeBufferDescriptor;
+      const materialDesc = materialCall?.[0] as FakeBufferDescriptor;
+      // Both sized at 2048 * 256 = 524288 B; same byte count → 256:256 stride parity
+      expect(meshDesc.size).toBe(2048 * PER_ENTITY_STRIDE);
+      expect(materialDesc.size).toBe(2048 * PER_ENTITY_STRIDE);
+      expect(meshDesc.size).toBe(materialDesc.size);
+      expect(fire).not.toHaveBeenCalled();
+    });
+
+    it('(b) length=3000 from 1024 → nextPow2(3000)=4096 in one step; createBuffer x2', () => {
+      const { device, createBufferSpy } = makeFakeDevice({
+        maxStorageBufferBindingSize: HIGH_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const { fire } = makeFakeErrorRegistry();
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fire as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      createBufferSpy.mockClear();
+
+      const result = ctrl.growMeshSsbo(3000);
+      expect(result).toEqual({ ok: true });
+      expect(ctrl.state.slotCount).toBe(4096);
+      expect(createBufferSpy).toHaveBeenCalledTimes(2);
+      expect(fire).not.toHaveBeenCalled();
+    });
+
+    it('(c) length=5000 from 1024 → nextPow2(5000)=8192 in one step', () => {
+      const { device, createBufferSpy } = makeFakeDevice({
+        maxStorageBufferBindingSize: HIGH_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const { fire } = makeFakeErrorRegistry();
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fire as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      createBufferSpy.mockClear();
+
+      const result = ctrl.growMeshSsbo(5000);
+      expect(result).toEqual({ ok: true });
+      expect(ctrl.state.slotCount).toBe(8192);
+      expect(createBufferSpy).toHaveBeenCalledTimes(2);
+      expect(fire).not.toHaveBeenCalled();
+    });
+
+    it('(d) createBuffer usage flag matches the factory-captured mesh + material usage', () => {
+      const { device, createBufferSpy } = makeFakeDevice({
+        maxStorageBufferBindingSize: HIGH_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const { fire } = makeFakeErrorRegistry();
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fire as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      // Initial build also obeys the usage parity contract.
+      const initialUsages = createBufferSpy.mock.calls
+        .map((c) => (c[0] as FakeBufferDescriptor).usage)
+        .sort((a, b) => a - b);
+      expect(initialUsages).toEqual([MATERIAL_USAGE, MESH_USAGE].sort((a, b) => a - b));
+      createBufferSpy.mockClear();
+
+      ctrl.growMeshSsbo(2500);
+      const growUsages = createBufferSpy.mock.calls
+        .map((c) => (c[0] as FakeBufferDescriptor).usage)
+        .sort((a, b) => a - b);
+      expect(growUsages).toEqual([MATERIAL_USAGE, MESH_USAGE].sort((a, b) => a - b));
+    });
+
+    it('(e) wrapper-object identity stable across grow; inner buffer replaced', () => {
+      const { device } = makeFakeDevice({
+        maxStorageBufferBindingSize: HIGH_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const { fire } = makeFakeErrorRegistry();
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fire as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      const meshWrapperBefore = ctrl.state.mesh;
+      const materialWrapperBefore = ctrl.state.material;
+      const meshBufferBefore = ctrl.state.mesh.buffer;
+      const materialBufferBefore = ctrl.state.material.buffer;
+
+      ctrl.growMeshSsbo(1500);
+
+      // Outer wrapper identity preserved (so PipelineState fields don't dangle).
+      expect(ctrl.state.mesh).toBe(meshWrapperBefore);
+      expect(ctrl.state.material).toBe(materialWrapperBefore);
+      // Inner buffer replaced by the freshly createBuffer'd handle.
+      expect(ctrl.state.mesh.buffer).not.toBe(meshBufferBefore);
+      expect(ctrl.state.material.buffer).not.toBe(materialBufferBefore);
+      // sizeInBytes now reflects the grown buffer.
+      expect(ctrl.state.mesh.sizeInBytes).toBe(2048 * PER_ENTITY_STRIDE);
+      expect(ctrl.state.material.sizeInBytes).toBe(2048 * PER_ENTITY_STRIDE);
+    });
+  });
+
+  // ── T-M2-03: ceiling + idempotent guard + capacity-exceeded fallback ─────
+
+  describe('T-M2-03 growMeshSsbo ceiling + idempotent guard + capacity-exceeded', () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('(a) ceiling — needed slot count past device limit fires once, no createBuffer, ok:false', () => {
+      // 256 KiB cap → ceiling = 256 KiB / 256 B = 1024 slots. needed=2048 trips
+      // the limit, so ceiling is reached.
+      const TIGHT_LIMIT = 256 * 1024; // exactly 1024 slots ceiling
+      const { device, createBufferSpy } = makeFakeDevice({
+        maxStorageBufferBindingSize: TIGHT_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const { fire } = makeFakeErrorRegistry();
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fire as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      createBufferSpy.mockClear();
+
+      const result = ctrl.growMeshSsbo(2048);
+      expect(result.ok).toBe(false);
+      if (result.ok === false) {
+        expect(result.code).toBe('mesh-ssbo-ceiling-reached');
+      }
+      expect(createBufferSpy).not.toHaveBeenCalled();
+      expect(fire).toHaveBeenCalledTimes(1);
+      const fired = fire.mock.calls[0]?.[0] as RuntimeLayerError;
+      expect(fired.code).toBe('mesh-ssbo-ceiling-reached');
+      // detail.requested / capacity / ceiling all present + non-undefined.
+      if (fired.code === 'mesh-ssbo-ceiling-reached') {
+        expect(fired.detail.requested).not.toBeUndefined();
+        expect(fired.detail.capacity).not.toBeUndefined();
+        expect(fired.detail.ceiling).not.toBeUndefined();
+        expect(fired.detail.requested).toBe(2048);
+        // ceiling reported in BYTES (= maxStorageBufferBindingSize), per
+        // plan-strategy §2.D-1 + research §F5.
+        expect(fired.detail.ceiling).toBe(TIGHT_LIMIT);
+      }
+    });
+
+    it('(b) idempotent guard — three same-needed grow calls hit createBuffer x2 only once', () => {
+      const { device, createBufferSpy } = makeFakeDevice({
+        maxStorageBufferBindingSize: HIGH_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const { fire } = makeFakeErrorRegistry();
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fire as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      createBufferSpy.mockClear();
+
+      const r1 = ctrl.growMeshSsbo(1500);
+      const r2 = ctrl.growMeshSsbo(1500);
+      const r3 = ctrl.growMeshSsbo(1500);
+      expect(r1).toEqual({ ok: true });
+      expect(r2).toEqual({ ok: true });
+      expect(r3).toEqual({ ok: true });
+      // Only the first call grows; the next two short-circuit on the guard.
+      expect(createBufferSpy).toHaveBeenCalledTimes(2);
+      expect(fire).not.toHaveBeenCalled();
+    });
+
+    it('(c) defensive capacity-exceeded — needed past ceiling fires either ceiling-reached or capacity-exceeded with full detail', () => {
+      // Plan §2.D-5 picks ceiling-reached as the primary path when the
+      // device.limits.maxStorageBufferBindingSize cannot accommodate the
+      // requested slot count; capacity-exceeded is a defensive fallback.
+      // We assert that ONE of the two structured errors fires with all 3
+      // detail fields populated (requested / capacity / ceiling), per AC-08
+      // narrowing contract — not which one.
+      const TIGHT_LIMIT = INITIAL_SLOT_COUNT * PER_ENTITY_STRIDE; // 1024 slots ceiling
+      const { device, createBufferSpy } = makeFakeDevice({
+        maxStorageBufferBindingSize: TIGHT_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const { fire } = makeFakeErrorRegistry();
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fire as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      createBufferSpy.mockClear();
+
+      const result = ctrl.growMeshSsbo(99999);
+      expect(result.ok).toBe(false);
+      if (result.ok === false) {
+        expect(['mesh-ssbo-ceiling-reached', 'mesh-ssbo-capacity-exceeded']).toContain(result.code);
+      }
+      expect(createBufferSpy).not.toHaveBeenCalled();
+      expect(fire).toHaveBeenCalledTimes(1);
+      const fired = fire.mock.calls[0]?.[0] as RuntimeLayerError;
+      expect(['mesh-ssbo-ceiling-reached', 'mesh-ssbo-capacity-exceeded']).toContain(fired.code);
+      // Whichever code was fired, the 4-field error shape must include the
+      // structured detail with all three numeric fields populated.
+      if (
+        fired.code === 'mesh-ssbo-ceiling-reached' ||
+        fired.code === 'mesh-ssbo-capacity-exceeded'
+      ) {
+        expect(typeof fired.detail.requested).toBe('number');
+        expect(typeof fired.detail.capacity).toBe('number');
+        expect(typeof fired.detail.ceiling).toBe('number');
+      }
+    });
+
+    // bug-20260622 wgpu-wasm-ssbo-ceiling-zero regression: when the device
+    // under-reports `maxStorageBufferBindingSize = 0` (currently happens on
+    // the wgpu-wasm backend because rhi.rs requests its device with
+    // `wgpu::Limits::downlevel_webgl2_defaults()` which zeroes the storage
+    // buffer binding-size limit), the grow controller must fall back to the
+    // WebGPU spec default (128 MiB) rather than refuse every grow with
+    // ceiling=0. Without the fallback any demo whose entity count crosses
+    // initialSlotCount (e.g. asi-world at ~3k+ entities) loops on
+    // MeshSsboCeilingReachedError and produces a black screen.
+    it('(d) ceiling=0 fallback — under-reported limit treated as 128 MiB, grow succeeds', () => {
+      const { device, createBufferSpy } = makeFakeDevice({
+        maxStorageBufferBindingSize: 0,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const { fire } = makeFakeErrorRegistry();
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fire as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      createBufferSpy.mockClear();
+
+      // Pick a slot count well above initialSlotCount=1024 but well below
+      // 128 MiB / 256 B = 512K slots. Matches the asi-world failure-mode
+      // size (~5546 needed slots in the original repro).
+      const result = ctrl.growMeshSsbo(6000);
+      expect(result).toEqual({ ok: true });
+      // mesh + material buffers reallocated once on the grow.
+      expect(createBufferSpy).toHaveBeenCalledTimes(2);
+      expect(fire).not.toHaveBeenCalled();
+      // slotCount lifted to the next pow2 >= 6000 (= 8192).
+      expect(ctrl.state.slotCount).toBe(8192);
+    });
+  });
+
+  // ── T-M3-01: ensureMeshSsboCapacity idempotent + boundary ────────────────
+  //
+  // Anchors:
+  //   - requirements §AC-05 (entry point at recordFrame top, after
+  //     validatedOrdered finalised + before first writeBuffer)
+  //   - requirements §AC-09 (idempotent guard — same-frame multi-call)
+  //   - requirements §boundary table (length=0 / 1024 / 1025 / 5000 / past
+  //     ceiling — first 4 covered here; 5th is T-M3-02)
+  //   - plan-strategy §2.D-4 (ensureMeshSsboCapacity reads internals.growMeshSsbo
+  //     hook + internals.meshSsboState slotCount)
+  //   - plan-strategy §5.3 row 2-4 (idempotent guard, boundary lengths)
+
+  interface FakeInternals {
+    growMeshSsbo?:
+      | ((neededSlots: number) => ReturnType<MeshSsboGrowController['growMeshSsbo']>)
+      | undefined;
+    meshSsboState?: { slotCount: number } | undefined;
+    errorRegistry: { fire: (e: RuntimeLayerError) => void };
+  }
+
+  type MeshSsboGrowController = ReturnType<typeof createMeshSsboGrowController>;
+
+  function makeInternalsWithRealController(): {
+    internals: FakeInternals;
+    ctrl: MeshSsboGrowController;
+    growSpy: ReturnType<typeof vi.fn>;
+    fireSpy: ReturnType<typeof vi.fn>;
+    createBufferSpy: ReturnType<typeof vi.fn>;
+  } {
+    const { device, createBufferSpy } = makeFakeDevice({
+      maxStorageBufferBindingSize: HIGH_LIMIT,
+      maxUniformBufferBindingSize: HIGH_LIMIT,
+    });
+    const fireSpy = vi.fn((_e: RuntimeLayerError) => undefined);
+    const ctrl = createMeshSsboGrowController({
+      device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+      errorRegistry: { fire: fireSpy as unknown as (e: RuntimeLayerError) => void },
+      initialSlotCount: INITIAL_SLOT_COUNT,
+      perEntityStride: PER_ENTITY_STRIDE,
+      meshUsage: MESH_USAGE,
+      materialUsage: MATERIAL_USAGE,
+    });
+    ctrl.initialBuild();
+    // Wrap the real grow so we can spy call count without losing behaviour.
+    const growSpy = vi.fn((n: number) => ctrl.growMeshSsbo(n));
+    const internals: FakeInternals = {
+      growMeshSsbo: growSpy as unknown as FakeInternals['growMeshSsbo'],
+      meshSsboState: ctrl.state,
+      errorRegistry: { fire: fireSpy as unknown as (e: RuntimeLayerError) => void },
+    };
+    return { internals, ctrl, growSpy, fireSpy, createBufferSpy };
+  }
+
+  describe('T-M3-01 ensureMeshSsboCapacity idempotent + boundary', () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('(a) length=512 (<= slotCount 1024) → grow spy NOT called, ok:true', () => {
+      const { internals, growSpy, fireSpy } = makeInternalsWithRealController();
+      const result = ensureMeshSsboCapacity(internals, 512);
+      expect(result).toEqual({ ok: true });
+      expect(growSpy).not.toHaveBeenCalled();
+      expect(fireSpy).not.toHaveBeenCalled();
+    });
+
+    it('(b) idempotent — three same-frame calls @1500 → grow runs 1 time only', () => {
+      const { internals, growSpy, fireSpy, createBufferSpy } = makeInternalsWithRealController();
+      createBufferSpy.mockClear();
+      const r1 = ensureMeshSsboCapacity(internals, 1500);
+      const r2 = ensureMeshSsboCapacity(internals, 1500);
+      const r3 = ensureMeshSsboCapacity(internals, 1500);
+      expect(r1).toEqual({ ok: true });
+      expect(r2).toEqual({ ok: true });
+      expect(r3).toEqual({ ok: true });
+      // grow spy: r1 needs 1500>1024 so spy fires + grows; r2/r3 see slotCount=2048 >= 1500 and short-circuit.
+      expect(growSpy).toHaveBeenCalledTimes(1);
+      // createBuffer fires twice (mesh + material) for the single grow.
+      expect(createBufferSpy).toHaveBeenCalledTimes(2);
+      expect(fireSpy).not.toHaveBeenCalled();
+    });
+
+    it('(c) length=0 (empty scene) → grow NOT called, ok:true, no error', () => {
+      const { internals, growSpy, fireSpy } = makeInternalsWithRealController();
+      const result = ensureMeshSsboCapacity(internals, 0);
+      expect(result).toEqual({ ok: true });
+      expect(growSpy).not.toHaveBeenCalled();
+      expect(fireSpy).not.toHaveBeenCalled();
+    });
+
+    it('(d) length=1024 (== slotCount) → grow NOT called, ok:true', () => {
+      const { internals, growSpy, fireSpy } = makeInternalsWithRealController();
+      const result = ensureMeshSsboCapacity(internals, 1024);
+      expect(result).toEqual({ ok: true });
+      expect(growSpy).not.toHaveBeenCalled();
+      expect(fireSpy).not.toHaveBeenCalled();
+    });
+
+    it('(e) length=1025 (just above) → grow called once, slotCount=2048', () => {
+      const { internals, ctrl, growSpy, fireSpy } = makeInternalsWithRealController();
+      const result = ensureMeshSsboCapacity(internals, 1025);
+      expect(result).toEqual({ ok: true });
+      expect(growSpy).toHaveBeenCalledTimes(1);
+      expect(ctrl.state.slotCount).toBe(2048);
+      expect(fireSpy).not.toHaveBeenCalled();
+    });
+
+    it('(f) hook absent on internals → ok:true (no crash; legacy / pre-grow path)', () => {
+      const internals: FakeInternals = {
+        // growMeshSsbo intentionally undefined (e.g. test fixture without controller)
+        errorRegistry: { fire: vi.fn() as unknown as (e: RuntimeLayerError) => void },
+      };
+      const result = ensureMeshSsboCapacity(internals, 9999);
+      expect(result).toEqual({ ok: true });
+    });
+  });
+
+  // ── T-M3-02: ceiling fires + 0 writeBuffer + 0 draw via ensureMeshSsboCapacity ──
+  //
+  // Anchors:
+  //   - requirements §AC-08 (ceiling fires `mesh-ssbo-ceiling-reached`, frame
+  //     skipped: 0 writeBuffer + 0 draw, no truncation)
+  //   - plan-strategy §5.3 row 5 (256 KiB cap → 1024 slots ceiling → length=2048
+  //     trips it; queue.writeBuffer / draw spies = 0 + fire = 1)
+
+  describe('T-M3-02 ceiling — ensureMeshSsboCapacity returns ok:false, no writeBuffer / draw', () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('(a) device cap = 256 KiB (= 1024 slots), needed=2048 → ok:false code=mesh-ssbo-ceiling-reached', () => {
+      const TIGHT_LIMIT = 256 * 1024; // 1024 slots ceiling at stride 256
+      const { device, createBufferSpy } = makeFakeDevice({
+        maxStorageBufferBindingSize: TIGHT_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const fireSpy = vi.fn((_e: RuntimeLayerError) => undefined);
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fireSpy as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      createBufferSpy.mockClear();
+
+      // Simulate the record-stage frame surface: queue.writeBuffer + draw spies.
+      const writeBufferSpy = vi.fn();
+      const drawSpy = vi.fn();
+
+      const internals: FakeInternals = {
+        growMeshSsbo: ctrl.growMeshSsbo,
+        meshSsboState: ctrl.state,
+        errorRegistry: { fire: fireSpy as unknown as (e: RuntimeLayerError) => void },
+      };
+
+      const capRes = ensureMeshSsboCapacity(internals, 2048);
+      expect(capRes.ok).toBe(false);
+      if (capRes.ok === false) {
+        expect(['mesh-ssbo-ceiling-reached', 'mesh-ssbo-capacity-exceeded']).toContain(capRes.code);
+      }
+      // Caller (record stage) MUST early-return on ok:false: emulate the
+      // contract in the test so spy state matches the real frame skip.
+      if (capRes.ok === false) {
+        // intentionally do NOT call writeBufferSpy / drawSpy
+      }
+
+      expect(writeBufferSpy).not.toHaveBeenCalled();
+      expect(drawSpy).not.toHaveBeenCalled();
+      // Ceiling fired exactly once (by the controller; ensure does not double-fire).
+      expect(fireSpy).toHaveBeenCalledTimes(1);
+      const fired = fireSpy.mock.calls[0]?.[0] as RuntimeLayerError;
+      expect(['mesh-ssbo-ceiling-reached', 'mesh-ssbo-capacity-exceeded']).toContain(fired.code);
+      // No new createBuffer on ceiling (mesh+material reset path skipped).
+      expect(createBufferSpy).not.toHaveBeenCalled();
+    });
+
+    it('(b) ensure does not double-fire — controller fires; ensure passes ok:false through unchanged', () => {
+      const TIGHT_LIMIT = 256 * 1024;
+      const { device } = makeFakeDevice({
+        maxStorageBufferBindingSize: TIGHT_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const fireSpy = vi.fn((_e: RuntimeLayerError) => undefined);
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fireSpy as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      const internals: FakeInternals = {
+        growMeshSsbo: ctrl.growMeshSsbo,
+        meshSsboState: ctrl.state,
+        errorRegistry: { fire: fireSpy as unknown as (e: RuntimeLayerError) => void },
+      };
+      ensureMeshSsboCapacity(internals, 4096);
+      // controller.growMeshSsbo fires once; ensure must NOT add a second fire.
+      expect(fireSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ── T-M3-03: BindGroup cache miss + dev console.info ────────────────────
+  //
+  // Anchors:
+  //   - requirements §AC-07 (BindGroup cache auto-invalidates after grow —
+  // feat-20260622-handle-to-id-allocator-elimination: after grow the
+  //   new inner buffer object is a fresh WeakMap chain key → cache miss)
+  //   - requirements §AC-11 (dev mode console.info with `[mesh-ssbo]` prefix)
+  //   - plan-strategy §2.D-3 (import.meta.env?.DEV optional-chain — dawn smoke
+  //     defaults false)
+  //   - plan-strategy §5.3 rows 7-8
+
+  describe('T-M3-03 BindGroup cache miss + dev console.info', () => {
+    beforeEach(() => {
+      vi.restoreAllMocks();
+    });
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('(a) inner buffer changes after grow — new WeakMap key → cache miss (AC-07)', () => {
+      const { internals, ctrl } = makeInternalsWithRealController();
+      const meshBeforeBuf = ctrl.state.mesh.buffer;
+      // Simulate a WeakMap chain root keyed by the pre-grow inner buffer.
+      const root = new WeakMap<object, unknown>();
+      root.set(meshBeforeBuf as unknown as object, { __leaf: 'bg-old' });
+
+      ensureMeshSsboCapacity(internals, 1500);
+
+      const meshAfterBuf = ctrl.state.mesh.buffer;
+      expect(meshAfterBuf).not.toBe(meshBeforeBuf);
+      // AC-07: the new inner buffer is a different object, so WeakMap chain
+      // lookup naturally misses — no numeric id needed.
+      expect(root.has(meshAfterBuf as unknown as object)).toBe(false);
+      expect(root.has(meshBeforeBuf as unknown as object)).toBe(true);
+    });
+
+    it('(b) dev=true (vitest default) → console.info called once with `[mesh-ssbo]` + old + new + requested', () => {
+      // Vitest default env: import.meta.env.DEV === true ⇒ isMeshSsboDevMode() ⇒ true.
+      // (vitest 4.x cannot toggle import.meta.env.DEV at runtime; that path is
+      // build-time-frozen by the vite transform — we exercise dev=false in (c)
+      // via the spyable isMeshSsboDevMode helper.)
+      const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
+      const { internals } = makeInternalsWithRealController();
+      ensureMeshSsboCapacity(internals, 1500);
+      expect(infoSpy).toHaveBeenCalledTimes(1);
+      const args = infoSpy.mock.calls[0] ?? [];
+      const fmt = args[0] as string;
+      expect(typeof fmt).toBe('string');
+      expect(fmt).toContain('[mesh-ssbo]');
+      // The trailing format args carry old / new / requested in some order; assert
+      // all three numeric values are present in the args list.
+      const numericArgs = args.slice(1).filter((a) => typeof a === 'number') as number[];
+      expect(numericArgs).toContain(1024); // old slotCount
+      expect(numericArgs).toContain(2048); // new slotCount (pow2 from 1024 for 1500)
+      expect(numericArgs).toContain(1500); // requested
+    });
+
+    it('(c) dev=false (probe injected) → console.info NOT called', () => {
+      // ESM module bindings are read-only and `import.meta.env.DEV` is
+      // build-time-frozen by the vite transform — neither `vi.spyOn` on the
+      // module namespace nor `vi.stubEnv('DEV', false)` toggles it at runtime
+      // in vitest 4.x. The injection seam `setMeshSsboDevModeProbeForTests`
+      // swaps the closure-local pointer ensureMeshSsboCapacity reads to
+      // exercise the dev=false path deterministically.
+      setMeshSsboDevModeProbeForTests(() => false);
+      try {
+        const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
+        const { internals } = makeInternalsWithRealController();
+        ensureMeshSsboCapacity(internals, 1500);
+        expect(infoSpy).not.toHaveBeenCalled();
+      } finally {
+        setMeshSsboDevModeProbeForTests(undefined);
+      }
+    });
+
+    it('(c-2) isMeshSsboDevMode helper itself returns true under vitest defaults', () => {
+      // Sanity-check the production probe path: under vitest `import.meta.env.DEV`
+      // is `true`, so `isMeshSsboDevMode()` short-circuits true. This locks the
+      // contract that the OR-of-sources logic respects vite's compile-time inject
+      // (the dev=false branch is exercised in (c) via the injection seam).
+      expect(isMeshSsboDevMode()).toBe(true);
+    });
+
+    it('(d) ceiling path — no console.info even with dev=true (only successful grow logs)', () => {
+      const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
+      const TIGHT_LIMIT = 256 * 1024;
+      const { device } = makeFakeDevice({
+        maxStorageBufferBindingSize: TIGHT_LIMIT,
+        maxUniformBufferBindingSize: HIGH_LIMIT,
+      });
+      const fireSpy = vi.fn((_e: RuntimeLayerError) => undefined);
+      const ctrl = createMeshSsboGrowController({
+        device: device as unknown as Parameters<typeof createMeshSsboGrowController>[0]['device'],
+        errorRegistry: { fire: fireSpy as unknown as (e: RuntimeLayerError) => void },
+        initialSlotCount: INITIAL_SLOT_COUNT,
+        perEntityStride: PER_ENTITY_STRIDE,
+        meshUsage: MESH_USAGE,
+        materialUsage: MATERIAL_USAGE,
+      });
+      ctrl.initialBuild();
+      const internals: FakeInternals = {
+        growMeshSsbo: ctrl.growMeshSsbo,
+        meshSsboState: ctrl.state,
+        errorRegistry: { fire: fireSpy as unknown as (e: RuntimeLayerError) => void },
+      };
+      ensureMeshSsboCapacity(internals, 4096);
+      expect(infoSpy).not.toHaveBeenCalled();
+    });
+  });
+}
+
+{
+  // --- from mesh-update-no-leak.test.ts ---
+  // mesh-update-no-leak.test - updateMesh in-place re-upload + expansion unit test
+  // (feat-20260531-world-space-msdf-text-rendering M3 / w12).
+  //
+  // Coverage:
+  //   (a) No-leak falsification: register a mesh, call updateMesh 50 times
+  //       with same-size data, assert assets Map size + meshGpuHandles size
+  //       is constant (AC-08: if every frame registers new mesh, Map size
+  //       monotonically grows — this assertion can falsify that).
+  //   (b) Expansion: register a small mesh (4 verts), updateMesh with 8-vert
+  //       data (exceeds capacity), assert meshGpuHandles entry vertexBuffer
+  //       changed but handle id unchanged + indexCount updated.
+  //   (c) updateMesh on non-existent handle is a silent no-op (guards check
+  //       meshGpuHandles.has + device existence).
+
+  // feat-20260601-gpu-resource-store-extraction M1: updateMesh moved to the GPU
+  // store. The no-leak invariant is now structural-by-construction (the store
+  // holds no registry reference, D-2), but the test still asserts that driving
+  // updateMesh never grows the registry. Without a wired device the store
+  // updateMesh no-ops, matching the pre-extraction no-device behavior.
+
+  function makeQuadMesh(): MeshAsset {
+    // 4 vertices x 12 floats = 48 entries, 2 triangles (6 indices)
+    const vertices = new Float32Array(4 * 12);
+    const indices = new Uint16Array([0, 1, 2, 0, 2, 3]);
+    return {
+      kind: 'mesh',
+      vertices,
+      indices,
+      attributes: {},
+      aabb: new Float32Array(6),
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: indices.length,
+          vertexCount: vertices.length,
+          topology: 'triangle-list',
+        },
+      ],
+    };
+  }
+
+  function makeOctMesh(): MeshAsset {
+    // 8 vertices x 12 floats = 96 entries, double the quad
+    const vertices = new Float32Array(8 * 12);
+    const indices = new Uint16Array([0, 1, 2, 0, 2, 3, 4, 5, 6, 4, 6, 7]);
+    return {
+      kind: 'mesh',
+      vertices,
+      indices,
+      attributes: {},
+      aabb: new Float32Array(6),
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: indices.length,
+          vertexCount: vertices.length,
+          topology: 'triangle-list',
+        },
+      ],
+    };
+  }
+
+  describe('w12 - updateMesh no-leak + expansion unit', () => {
+    it('(a) 50-frame same-size updateMesh does not grow sharedRefs/meshGpuHandles size', () => {
+      const world = new World();
+      const mesh = makeQuadMesh();
+      const handle = world.allocSharedRef('MeshAsset', mesh);
+      const store = new GpuResourceStore();
+      void unwrapHandle(handle);
+
+      // Save the initial live shared-ref slot count.
+      const initialAssetsSize = world.sharedRefs._liveCount();
+      // meshGpuHandles is only populated after configureGpuDevice.
+      // Without a device, updateMeshById is a no-op (guards check device).
+      // This test verifies the structural invariant: calling updateMesh does
+      // NOT mint a new shared ref (which would grow the live slot count).
+      // The live slot count is the structural indicator of the AC-08
+      // falsification — if every frame minted a handle, it would grow.
+      if (!(mesh.indices instanceof Uint16Array)) return;
+      for (let frame = 0; frame < 50; frame++) {
+        store.updateMesh(handle, mesh.vertices, mesh.indices);
+      }
+      const finalAssetsSize = world.sharedRefs._liveCount();
+      expect(finalAssetsSize).toBe(initialAssetsSize);
+    });
+
+    it('(b) updateMesh on a minted handle does not mint a new shared ref', () => {
+      const world = new World();
+      const mesh = makeQuadMesh();
+      const handle = world.allocSharedRef('MeshAsset', mesh);
+      const store = new GpuResourceStore();
+
+      const before = world.sharedRefs._liveCount();
+      if (!(mesh.indices instanceof Uint16Array)) return;
+      store.updateMesh(handle, mesh.vertices, mesh.indices);
+      const after = world.sharedRefs._liveCount();
+      expect(after).toBe(before);
+    });
+
+    it('(c) expansion path preserves mesh handle id', () => {
+      const world = new World();
+      const mesh = makeQuadMesh();
+      const handle = world.allocSharedRef('MeshAsset', mesh);
+      const store = new GpuResourceStore();
+      const id = unwrapHandle(handle);
+
+      // updateMesh with larger data (expansion path)
+      const bigger = makeOctMesh();
+      if (!(bigger.indices instanceof Uint16Array)) return;
+      store.updateMesh(handle, bigger.vertices, bigger.indices);
+      // The id should still be the same — no new mint was performed.
+      const result = world.sharedRefs.resolve<string, MeshAsset>(handle);
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      // The payload behind the handle is unchanged (updateMesh only touches the
+      // GPU side); the handle's numeric id is the same.
+      const lookupId = unwrapHandle(handle);
+      expect(lookupId).toBe(id);
+    });
+  });
+}
+
+{
+  // --- from instances-with-submeshes.test.ts ---
+  // instances-with-submeshes.test.ts -- unit tests for Instances x submesh
+  // N x M draw dispatch (feat-20260608-mesh-multi-section-primitive-multi-material-slot M4 / w19).
+  //
+  // Anchors: requirements AC-07 (NxM assertions); plan-strategy D-8
+  // (shared instanceCount, not per-submesh); OOS-5 (per-submesh independent
+  // instances explicitly excluded).
+
+  function canonicalAttributes(vertexCount: number): MeshAsset['attributes'] {
+    return {
+      position: new Float32Array(vertexCount * 3),
+      normal: new Float32Array(vertexCount * 3),
+      uv: new Float32Array(vertexCount * 2),
+      tangent: new Float32Array(vertexCount * 4),
+    };
+  }
+
+  const ENGINE = '../createRenderer';
+
+  interface PassSpies {
+    setIndexBuffer: ReturnType<typeof vi.fn>;
+    setVertexBuffer: ReturnType<typeof vi.fn>;
+    draw: ReturnType<typeof vi.fn>;
+    drawIndexed: ReturnType<typeof vi.fn>;
+  }
+
+  function makeMockGL2(): unknown {
+    return {
+      __mockTag: 'webgl2',
+      getExtension: () => null,
+      getParameter: () => 1,
+      isContextLost: () => false,
+    };
+  }
+
+  function makeMockCanvas(): HTMLCanvasElement {
+    const canvas = {
+      width: 800,
+      height: 600,
+      getContext(kind: string): unknown {
+        if (kind === 'webgl2') return makeMockGL2();
+        if (kind === 'webgpu') {
+          return {
+            __mockTag: 'webgpu-canvas-context',
+            configure: () => undefined,
+            unconfigure: () => undefined,
+            getCurrentTexture: () => ({ createView: () => ({}) }),
+          };
+        }
+        return null;
+      },
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+    };
+    return canvas as Partial<HTMLCanvasElement> as HTMLCanvasElement;
+  }
+
+  function makeMockGPUDevice(spies: PassSpies): { device: unknown } {
+    const lost = new Promise<unknown>(() => undefined);
+    const device = {
+      __mockTag: 'gpu-device',
+      lost,
+      features: new Set(),
+      limits: {},
+      queue: {
+        submit: () => undefined,
+        writeBuffer: () => undefined,
+        writeTexture: () => undefined,
+      },
+      createShaderModule: () => ({ getCompilationInfo: async () => ({ messages: [] }) }),
+      createBindGroupLayout: () => ({}),
+      createPipelineLayout: () => ({}),
+      createRenderPipeline: () => ({}),
+      createBindGroup: () => ({}),
+      createBuffer: (desc: { size: number }) => ({
+        size: desc.size,
+        getMappedRange: () => new ArrayBuffer(desc.size > 0 ? desc.size : 64),
+        unmap: () => undefined,
+      }),
+      createCommandEncoder: () => ({
+        beginRenderPass: () => ({
+          setPipeline: () => undefined,
+          setVertexBuffer: spies.setVertexBuffer,
+          setIndexBuffer: spies.setIndexBuffer,
+          setBindGroup: () => undefined,
+          setStencilReference: () => undefined,
+          setViewport: () => undefined,
+          setScissorRect: () => undefined,
+          draw: spies.draw,
+          drawIndexed: spies.drawIndexed,
+          end: () => undefined,
+        }),
+        finish: () => ({}),
+      }),
+      createTexture: () => ({ createView: () => ({}) }),
+      createSampler: () => ({}),
+      destroy: () => undefined,
+    };
+    return { device };
+  }
+
+  function makeMockGPU(deviceObj: unknown): unknown {
+    return {
+      requestAdapter: async () => ({ requestDevice: async () => deviceObj }),
+      getPreferredCanvasFormat: () => 'bgra8unorm',
+    };
+  }
+
+  const baseNavigator: Navigator = {
+    userAgent: 'mock-engine-test',
+  } as Partial<Navigator> as Navigator;
+
+  function buildManifestDataUrl(): string {
+    const materialShaderStub = (identifier: string) => ({
+      identifier,
+      sourcePath: `${identifier}.wgsl`,
+      composedWgsl: '/* stub */',
+      paramSchema: canonicalMaterialParamSchema(identifier),
+      variants: canonicalDefaultMaterialVariants(identifier),
+    });
+    const manifest = {
+      schemaVersion: '1.0.0',
+      entries: [
+        { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },
+        { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+        {
+          hash: 'tonemap0',
+          wgsl: '/* tonemap stub - struct TonemapParams { exposure: f32 }; */',
+          glsl: '',
+          bindings: '',
+        },
+      ],
+      materialShaders: [
+        materialShaderStub('forgeax::default-standard-pbr'),
+        materialShaderStub('forgeax::default-unlit'),
+      ],
+    };
+    return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+  }
+
+  function makePassSpies(): PassSpies {
+    return {
+      setIndexBuffer: vi.fn(),
+      setVertexBuffer: vi.fn(),
+      draw: vi.fn(),
+      drawIndexed: vi.fn(),
+    };
+  }
+
+  interface RendererLike {
+    ready: Promise<void>;
+    draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
+    onError: (cb: (err: { code: string }) => void) => () => void;
+    assets: { register: (asset: unknown) => { ok: boolean; value: unknown } };
+  }
+
+  async function importEngine(): Promise<{
+    createRenderer: (canvas: unknown, opts?: unknown) => Promise<RendererLike>;
+  }> {
+    return (await import(ENGINE)) as never;
+  }
+
+  async function importEcs(): Promise<{
+    World: new () => {
+      spawn: (...componentDatas: unknown[]) => unknown;
+      allocSharedRef: (target: string, payload: unknown) => number;
+    };
+  }> {
+    return (await import('@forgeax/engine-ecs')) as never;
+  }
+
+  async function importComponents(): Promise<{
+    Transform: unknown;
+    MeshFilter: unknown;
+    MeshRenderer: unknown;
+    Camera: unknown;
+    DirectionalLight: unknown;
+    Instances: unknown;
+  }> {
+    return {
+      ...(await import('@forgeax/engine-render/internal')),
+      ...(await import('@forgeax/engine-scene')),
+    } as never;
+  }
+
+  function cameraTransform() {
+    return {
+      pos: [0, 0, 5],
+      quat: [0, 0, 0, 1],
+      scale: [1, 1, 1],
+    };
+  }
+
+  function originTransform() {
+    return {
+      pos: [0, 0, 0],
+      quat: [0, 0, 0, 1],
+      scale: [1, 1, 1],
+    };
+  }
+
+  function unlitMaterial(color: readonly [number, number, number] = [1, 0, 0]) {
+    return {
+      kind: 'material' as const,
+      passes: [
+        {
+          name: 'Forward',
+          program: { module: 'forgeax::default-unlit' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+        },
+      ],
+      values: { baseColor: color },
+    };
+  }
+
+  function twoSubmeshMesh(): MeshAsset {
+    const vertexCount = 6;
+    return {
+      kind: 'mesh',
+      vertices: new Float32Array(vertexCount * 12),
+      indices: new Uint16Array([0, 1, 2, 3, 4, 5]),
+      attributes: canonicalAttributes(vertexCount),
+      materialSlots: [{ slotName: 'First' }, { slotName: 'Second' }],
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          materialSlot: 0,
+          topology: 'triangle-list' as const,
+        },
+        {
+          indexOffset: 3,
+          indexCount: 3,
+          vertexCount: 3,
+          materialSlot: 1,
+          topology: 'triangle-list' as const,
+        },
+      ],
+    };
+  }
+
+  /** Build a packed Float32Array of N identity mat4 transforms (16 f32 each). */
+  function identityTransforms(count: number): Float32Array {
+    const buf = new Float32Array(count * 16);
+    for (let i = 0; i < count; i++) {
+      const base = i * 16;
+      buf[base + 0] = 1;
+      buf[base + 5] = 1;
+      buf[base + 10] = 1;
+      buf[base + 15] = 1;
+    }
+    return buf;
+  }
+
+  async function setupRenderer(spies: PassSpies): Promise<{ renderer: RendererLike }> {
+    const { device } = makeMockGPUDevice(spies);
+    vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
+    const { createRenderer } = await importEngine();
+    const renderer = await createRenderer(
+      makeMockCanvas(),
+      {},
+      {
+        shaderManifestUrl: buildManifestDataUrl(),
+      },
+    );
+    await renderer.ready;
+    return { renderer };
+  }
+
+  async function spawnInstancedScene(
+    _renderer: RendererLike,
+    meshAsset: MeshAsset,
+    materialCount: number,
+    instanceCount: number,
+  ): Promise<unknown> {
+    const { World } = await importEcs();
+    const C = await importComponents();
+    const world = new World();
+    registerRuntimeComponents(world);
+    const meshHandle = world.allocSharedRef('MeshAsset', meshAsset) as Handle<
+      'MeshAsset',
+      'shared'
+    >;
+
+    // Mint N materials (one per submesh).
+    const colors: Array<readonly [number, number, number]> = [
+      [1, 0, 0],
+      [0, 1, 0],
+      [0, 0, 1],
+    ];
+    const materialHandles: Handle<'MaterialAsset', 'shared'>[] = [];
+    for (let i = 0; i < materialCount; i++) {
+      materialHandles.push(
+        world.allocSharedRef('MaterialAsset', unlitMaterial(colors[i])) as Handle<
+          'MaterialAsset',
+          'shared'
+        >,
+      );
+    }
+
+    const transforms = identityTransforms(instanceCount);
+
+    world.spawn(
+      {
+        component: C.Camera,
+        data: {
+          fov: Math.PI / 4,
+          aspect: 16 / 9,
+          near: 0.1,
+          far: 100,
+          projection: 0,
+          left: -1,
+          right: 1,
+          bottom: -1,
+          top: 1,
+        },
+      },
+      { component: C.Transform, data: cameraTransform() },
+    );
+    world.spawn(
+      { component: C.DirectionalLight, data: { direction: [-0.5, -1, -0.3] } },
+      { component: C.Transform, data: cameraTransform() },
+    );
+    world.spawn(
+      { component: C.MeshRenderer, data: { materials: materialHandles } },
+      { component: C.MeshFilter, data: { assetHandle: meshHandle } },
+      { component: C.Transform, data: originTransform() },
+      { component: C.Instances, data: { transforms } },
+    );
+    return world;
+  }
+
+  describe('Instances x submesh NxM assertions (w19, AC-07)', () => {
+    beforeEach(() => {
+      vi.stubGlobal('navigator', baseNavigator);
+    });
+
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    it('(a) M=4 instances x N=2 submeshes: drawIndexed called 8 times', async () => {
+      const spies = makePassSpies();
+      const { renderer } = await setupRenderer(spies);
+      const errors: string[] = [];
+      renderer.onError((e) => errors.push(e.code));
+
+      const world = await spawnInstancedScene(renderer, twoSubmeshMesh(), 2, 4);
+      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
+        throw new Error('World attachment failed');
+      }
+      (world as WorldType).update().unwrap();
+      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+
+      // Each submesh draws M times (4 instances each, shared instanceCount).
+      // N=2 submeshes * M=1 draw each = 2 drawIndexed calls.
+      // But with Instances present, the uniform path may collapse to identity.
+      // Key assertion: drawIndexed is called, and each call uses instanceCount >= 1.
+      const totalDrawCalls = spies.drawIndexed.mock.calls.length + spies.draw.mock.calls.length;
+      expect(totalDrawCalls).toBeGreaterThan(0);
+      expect(errors).toEqual([]);
+    });
+
+    it('(b) each submesh drawIndexed carries the same instanceCount = instance count', async () => {
+      const spies = makePassSpies();
+      const { renderer } = await setupRenderer(spies);
+      const errors: string[] = [];
+      renderer.onError((e) => errors.push(e.code));
+
+      const world = await spawnInstancedScene(renderer, twoSubmeshMesh(), 2, 4);
+      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
+        throw new Error('World attachment failed');
+      }
+      (world as WorldType).update().unwrap();
+      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+
+      // All submesh draws share the same instanceCount (D-8).
+      // Verify drawIndexed calls carry instanceCount parameter at index 1.
+      const indexedCalls = spies.drawIndexed.mock.calls as Array<
+        [number, number, number, number, number]
+      >;
+      const drawCalls = spies.draw.mock.calls as Array<[number, number, number, number]>;
+      const allInstanceCounts = [...indexedCalls.map((c) => c[1]), ...drawCalls.map((c) => c[1])];
+      // All instanceCounts should be identical (shared across submeshes, D-8).
+      if (allInstanceCounts.length >= 2) {
+        const first = allInstanceCounts[0];
+        for (const ic of allInstanceCounts) {
+          expect(ic).toBe(first);
+        }
+      }
+      expect(errors).toEqual([]);
+    });
+
+    it('(c) non-Instances path: instanceCount=1 per submesh', async () => {
+      const spies = makePassSpies();
+      const { renderer } = await setupRenderer(spies);
+      const errors: string[] = [];
+      renderer.onError((e) => errors.push(e.code));
+
+      // Spawn without Instances component.
+      const { World } = await importEcs();
+      const C = await importComponents();
+      const world = new World();
+      registerRuntimeComponents(world);
+      const meshHandle = world.allocSharedRef('MeshAsset', twoSubmeshMesh()) as Handle<
+        'MeshAsset',
+        'shared'
+      >;
+
+      const matHandles: Handle<'MaterialAsset', 'shared'>[] = [];
+      for (let i = 0; i < 2; i++) {
+        matHandles.push(
+          world.allocSharedRef('MaterialAsset', unlitMaterial()) as Handle<
+            'MaterialAsset',
+            'shared'
+          >,
+        );
+      }
+
+      world.spawn(
+        {
+          component: C.Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 16 / 9,
+            near: 0.1,
+            far: 100,
+            projection: 0,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      world.spawn(
+        { component: C.DirectionalLight, data: { direction: [-0.5, -1, -0.3] } },
+        { component: C.Transform, data: cameraTransform() },
+      );
+      world.spawn(
+        { component: C.MeshRenderer, data: { materials: matHandles } },
+        { component: C.MeshFilter, data: { assetHandle: meshHandle } },
+        { component: C.Transform, data: originTransform() },
+      );
+
+      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
+        throw new Error('World attachment failed');
+      }
+
+      (world as WorldType).update().unwrap();
+
+      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+
+      // Without Instances, instanceCount defaults to 1.
+      const indexedCalls = spies.drawIndexed.mock.calls as Array<
+        [number, number, number, number, number]
+      >;
+      expect(indexedCalls.length).toBeGreaterThan(0);
+      for (const call of indexedCalls) {
+        expect(call[1]).toBe(1); // instanceCount
+      }
+      expect(errors).toEqual([]);
+    });
+  });
+}
+
+{
+  // --- from mesh-asset-submeshes-validation.test.ts ---
+  // mesh-asset-submeshes-validation.test.ts — unit tests for mesh registration
+  // write-side validation (empty submeshes + index OOB) and read-side validation
+  // (material count mismatch).
+  // feat-20260608-mesh-multi-section-primitive-multi-material-slot M2 / w10.
+  //
+  // Anchors: requirements AC-05 (a)(b)(c); plan-strategy §2 D-3 (write-side /
+  // read-side interception); plan-strategy §5.3 key test points "AC-05 three
+  // triggers".
+
+  // ── read-side: renderer override diagnostics ─────────────────────────────────
+
+  describe('read-side: MeshRenderer override diagnostics', () => {
+    it('ASSET_ERROR_HINTS contains invalid and overflow override hints', () => {
+      expect(ASSET_ERROR_HINTS['mesh-renderer-material-override-invalid']).toBeTruthy();
+      expect(ASSET_ERROR_HINTS['mesh-renderer-material-override-overflow']).toBeTruthy();
+    });
+
+    it('AssetErrorDetail accepts expectedCount / actualCount / meshAssetGuid shape', () => {
+      // Type-level compiler check: this assignment compiles only if
+      // the { expectedCount, actualCount, meshAssetGuid } shape is in
+      // the AssetErrorDetail discriminated union.
+      const detail: AssetErrorDetail = {
+        expectedCount: 3,
+        actualCount: 1,
+        meshAssetGuid: '550e8400-e29b-41d4-a716-446655440000',
+      };
+      expect(detail.expectedCount).toBe(3);
+      expect(detail.actualCount).toBe(1);
+      expect(detail.meshAssetGuid).toBeTruthy();
+    });
+  });
+}