@forgeax/engine-render 0.1.33 → 0.1.35

package/src/__tests__/instances-store.unit.test.ts

@@ -1,339 +1,131 @@
+import { World } from '@forgeax/engine-ecs';
 import { describe, expect, it } from 'vitest';
-import { InstanceCollectionStore, instanceUploadRangesForResident } from '../instances';
-import { instanceCollectionCacheKey } from '../record/frame-snapshot';
+import { InstanceProjectionStore, validateInstanceTransforms } from '../instances';
 import { packInstanceStorageBuffer } from '../record/mesh-ssbo';
 
-function identityTransforms(count: number): Float32Array {
-  const transforms = new Float32Array(count * 16);
-  for (let index = 0; index < count; index += 1) {
-    const offset = index * 16;
-    transforms[offset] = 1;
-    transforms[offset + 5] = 1;
-    transforms[offset + 10] = 1;
-    transforms[offset + 15] = 1;
-  }
-  return transforms;
+function matrices(x: number): Float32Array {
+  return new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, 0, 0, 1]);
 }
 
-function translatedTransforms(...translations: readonly number[]): Float32Array {
-  const transforms = identityTransforms(translations.length);
-  for (const [index, translation] of translations.entries()) {
-    transforms[index * 16 + 12] = translation;
-  }
-  return transforms;
+function project(
+  store: InstanceProjectionStore,
+  world: World,
+  entity: number,
+  transforms: Float32Array,
+) {
+  const snapshot = store.project(world, entity, transforms);
+  store.accept(world, entity, snapshot);
+  return snapshot;
 }
 
-describe('InstanceCollectionStore', () => {
-  it('keeps large payloads outside ECS-sized storage and preserves one identity', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(20_000) });
-    expect(created.ok).toBe(true);
-    if (!created.ok) return;
-    expect(created.value.count).toBe(20_000);
-    expect(created.value.capacity).toBeGreaterThanOrEqual(20_000);
-    expect(store.snapshot(created.value.collectionId).unwrap().transforms).toHaveLength(
-      20_000 * 16,
-    );
+describe('renderer instance projection', () => {
+  it('derives independent complete snapshots for consumers that skip different updates', () => {
+    const world = new World();
+    const first = new InstanceProjectionStore();
+    const late = new InstanceProjectionStore();
+    const before = project(first, world, 1, matrices(0));
+    project(late, world, 1, matrices(0));
+    project(first, world, 1, matrices(1));
+    project(first, world, 1, matrices(2));
+    const latest = project(late, world, 1, matrices(2));
+    expect(before.transforms[12]).toBe(0);
+    expect(latest.transforms[12]).toBe(2);
+    const stable = project(late, world, 1, matrices(2));
+    expect(stable.transforms).toBe(latest.transforms);
+    expect(stable.revision).toBe(latest.revision);
   });
 
-  it('publishes bounded partial updates as one revision and one dirty interval', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(8) }).unwrap();
-    const before = store.snapshot(created.collectionId).unwrap();
-    const patch = identityTransforms(2);
-    patch[12] = 4;
-    expect(store.update(created.collectionId, { start: 3, transforms: patch }).ok).toBe(true);
-    const after = store.snapshot(created.collectionId).unwrap();
-    expect(after.revision).toBe(before.revision + 1);
-    expect(after.dirtyRanges).toEqual([{ start: 3, end: 5 }]);
-    expect(after.transforms[3 * 16 + 12]).toBe(4);
+  it('does not alias identical entity numbers across World identities', () => {
+    const projection = new InstanceProjectionStore();
+    const a = project(projection, new World(), 1, matrices(10));
+    const b = project(projection, new World(), 1, matrices(99));
+    expect(a.collectionId).not.toBe(b.collectionId);
+    expect(a.transforms[12]).toBe(10);
+    expect(b.transforms[12]).toBe(99);
   });
 
-  it('keeps identity generations stable across pose updates and seeds topology changes', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: translatedTransforms(1, 2) }).unwrap();
-    const before = store.snapshot(created.collectionId).unwrap();
-
-    store
-      .update(created.collectionId, {
-        start: 1,
-        transforms: translatedTransforms(9),
-      })
-      .unwrap();
-    const moved = store.snapshot(created.collectionId).unwrap();
-    expect([...moved.generations]).toEqual([...before.generations]);
-    const movedPayload = packInstanceStorageBuffer(
-      moved.transforms,
-      before.transforms,
-      moved.generations,
-      before.generations,
-    );
-    expect(movedPayload[16 + 12]).toBe(1);
-    expect(movedPayload[32 + 12]).toBe(9);
-    expect(movedPayload[32 + 16 + 12]).toBe(2);
-
-    store.replace(created.collectionId, translatedTransforms(20)).unwrap();
-    const compacted = store.snapshot(created.collectionId).unwrap();
-    expect(compacted.generations[0]).toBeGreaterThan(moved.generations[0] ?? 0);
-    const compactedPayload = packInstanceStorageBuffer(
-      compacted.transforms,
-      moved.transforms,
-      compacted.generations,
-      moved.generations,
+  it('rebuilds from unchanged source after dropping renderer resources', () => {
+    const world = new World();
+    const transforms = matrices(4);
+    const projection = new InstanceProjectionStore();
+    project(projection, world, 1, transforms);
+    projection.dispose();
+    expect(project(projection, world, 1, transforms).transforms).toEqual(transforms);
+    expect(new InstanceProjectionStore().project(world, 1, transforms).transforms).toEqual(
+      transforms,
     );
-    // The surviving ordinal was replaced/compacted, so its previous slot is
-    // seeded from the current pose instead of inheriting instance 0 or 1.
-    expect(compactedPayload[16 + 12]).toBe(20);
   });
 
-  it('maps real previous transforms through an explicit compaction reorder', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: translatedTransforms(1, 2) }).unwrap();
-    const before = store.snapshot(created.collectionId).unwrap();
-    const reordered = store
-      .replace(
-        created.collectionId,
-        translatedTransforms(20, 10),
-        new Uint32Array([before.generations[1] ?? 0, before.generations[0] ?? 0]),
-      )
-      .unwrap();
-    const after = store.snapshot(created.collectionId).unwrap();
-
-    expect(after.generations).toEqual(
-      new Uint32Array([before.generations[1] ?? 0, before.generations[0] ?? 0]),
-    );
+  it('retains pose identity and last submitted matrices while reseeding resized topology', () => {
+    const world = new World();
+    const projection = new InstanceProjectionStore();
+    const before = project(projection, world, 1, matrices(2));
+    const moved = project(projection, world, 1, matrices(9));
+    expect(moved.generations).toEqual(before.generations);
     const payload = packInstanceStorageBuffer(
-      after.transforms,
+      moved.transforms,
       before.transforms,
-      after.generations,
+      moved.generations,
       before.generations,
     );
-    expect(payload[12]).toBe(20);
+    expect(payload[12]).toBe(9);
     expect(payload[16 + 12]).toBe(2);
-    expect(payload[32 + 12]).toBe(10);
-    expect(payload[32 + 16 + 12]).toBe(1);
-    expect(reordered.count).toBe(2);
-  });
-
-  it('keeps the full union when partial updates overlap out of order', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(16) }).unwrap();
-    store.snapshot(created.collectionId).unwrap();
-    store.update(created.collectionId, { start: 10, transforms: identityTransforms(2) }).unwrap();
-    store.update(created.collectionId, { start: 8, transforms: identityTransforms(3) }).unwrap();
-    expect(store.snapshot(created.collectionId).unwrap().dirtyRanges).toEqual([
-      { start: 8, end: 12 },
-    ]);
-  });
-
-  it('keeps renderer dirty ranges intact when inspection peeks between updates', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(2) }).unwrap();
-    store.snapshot(created.collectionId).unwrap();
-
-    store.update(created.collectionId, { start: 0, transforms: identityTransforms(1) }).unwrap();
-    const inspected = store.peek(created.collectionId).unwrap();
-    expect(inspected.dirtyRanges).toEqual([{ start: 0, end: 1 }]);
-    store.update(created.collectionId, { start: 1, transforms: identityTransforms(1) }).unwrap();
-
-    expect(store.snapshot(created.collectionId).unwrap().dirtyRanges).toEqual([
-      { start: 0, end: 2 },
-    ]);
+    const resized = project(
+      projection,
+      world,
+      1,
+      new Float32Array([...matrices(3), ...matrices(4)]),
+    );
+    expect(resized.generations[0]).not.toBe(moved.generations[0]);
+    expect(before.transforms[12]).toBe(2);
   });
 
-  it('keeps collection identity in the renderer cache key', () => {
-    const first = instanceCollectionCacheKey(0, { cacheKey: 9, collectionId: 1 });
-    const second = instanceCollectionCacheKey(0, { cacheKey: 9, collectionId: 2 });
-    expect(first).not.toBe(second);
-    expect(instanceCollectionCacheKey(1, { cacheKey: 9, collectionId: 1 })).not.toBe(first);
-    expect(first).toBeLessThan(-0x1_0000_0000);
+  it('releases removed identities and never aliases a replacement to retained temporal data', () => {
+    const world = new World();
+    const projection = new InstanceProjectionStore();
+    const a = project(projection, world, 1, matrices(1));
+    const b = project(projection, world, 2, matrices(2));
+    projection.retain(new Set([b.collectionId]));
+    expect(projection._inspections(0).map((value) => value.collectionId)).toEqual([b.collectionId]);
+    const replacement = project(projection, world, 1, matrices(3));
+    expect(replacement.collectionId).not.toBe(a.collectionId);
+    projection.release(world, 1);
+    projection.release(world, 1);
+    expect(projection._inspections(0)).toHaveLength(1);
   });
 
-  it('projects resident and failure facts without exposing GPU handles', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(256) }).unwrap();
-    store._reportResidency({
-      collectionId: created.collectionId,
-      frameNumber: 1,
-      residentGeneration: 7,
-      lane: 'chunked-uniform',
-      requestedBytes: 256 * 64,
-      supportedBytes: 128 * 64,
-      uploadRanges: [{ start: 0, end: 128 }],
-      uploadedBytes: 128 * 64,
-      backend: 'webgpu',
-    });
-    expect(store._inspections()[0]).toMatchObject({
-      collectionId: created.collectionId,
-      residentGeneration: 7,
-      lane: 'chunked-uniform',
-      uploadRanges: [{ start: 0, end: 128 }],
-      uploadedBytes: 128 * 64,
-      requestedBytes: 256 * 64,
-      supportedBytes: 128 * 64,
-      backend: 'webgpu',
-      owner: 'renderer.instances',
-    });
-    store._reportFailure({
-      collectionId: created.collectionId,
-      code: 'limit-exceeded',
-      expected: 'the requested payload fits',
-      hint: 'use a storage-capable backend',
-      facts: {
-        requestedBytes: 256 * 64,
-        supportedBytes: 128 * 64,
-        backend: 'webgpu',
-        owner: 'renderer.instances',
-        cause: 'limit-exceeded',
-        recovery: 'use a storage-capable backend',
-      },
-    });
-    const failed = store._inspections()[0];
-    expect(failed?.lane).toBe('unavailable');
-    expect(failed?.error?.detail).toMatchObject({
-      requestedBytes: 256 * 64,
-      supportedBytes: 128 * 64,
-      owner: 'renderer.instances',
-      cause: 'limit-exceeded',
-      recovery: 'use a storage-capable backend',
-    });
-  });
-
-  it('aggregates upload evidence within one frame and resets it on a stable frame', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(4) }).unwrap();
-    store._reportResidency({
-      collectionId: created.collectionId,
-      frameNumber: 1,
-      residentGeneration: 3,
-      lane: 'direct-storage',
-      requestedBytes: 4 * 80,
-      supportedBytes: 1 << 20,
-      uploadRanges: [{ start: 0, end: 2 }],
-      uploadedBytes: 2 * 80,
-      backend: 'webgpu',
-    });
-    store._reportResidency({
-      collectionId: created.collectionId,
+  it('reports only current-frame uploads and drops old device residency on recovery', () => {
+    const projection = new InstanceProjectionStore();
+    const value = project(projection, new World(), 1, matrices(2));
+    projection._reportResidency({
+      collectionId: value.collectionId,
       frameNumber: 1,
       residentGeneration: 3,
       lane: 'direct-storage',
-      requestedBytes: 4 * 80,
-      supportedBytes: 1 << 20,
-      uploadRanges: [{ start: 2, end: 4 }],
-      uploadedBytes: 2 * 80,
+      uploadRanges: [{ start: 0, end: 1 }],
+      uploadedBytes: 128,
+      requestedBytes: 128,
+      supportedBytes: 1024,
       backend: 'webgpu',
     });
-    expect(store._inspections()[0]).toMatchObject({
-      uploadRanges: [{ start: 0, end: 4 }],
-      uploadedBytes: 4 * 80,
-    });
-    store._reportResidency({
-      collectionId: created.collectionId,
-      frameNumber: 2,
-      residentGeneration: 3,
-      lane: 'direct-storage',
-      requestedBytes: 4 * 80,
-      supportedBytes: 1 << 20,
-      uploadRanges: [],
-      uploadedBytes: 0,
-      backend: 'webgpu',
-    });
-    expect(store._inspections()[0]).toMatchObject({ uploadRanges: [], uploadedBytes: 0 });
+    expect(projection._inspections(1)[0]?.uploadedBytes).toBe(128);
+    expect(projection._inspections(2)[0]?.uploadedBytes).toBe(0);
+    expect(projection._inspections(2)[0]?.uploadRanges).toEqual([]);
+    projection._resetResidency();
+    expect(projection._inspections(2)[0]).toMatchObject({ lane: 'unresident', revision: 1 });
   });
 
-  it('forces a full canonical upload for a new resident after partial mutation and recovery', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(4) }).unwrap();
-    store.snapshot(created.collectionId).unwrap();
-    store
-      .update(created.collectionId, {
-        start: 2,
-        transforms: identityTransforms(1),
-      })
-      .unwrap();
-    expect(store.snapshot(created.collectionId).unwrap().dirtyRanges).toEqual([
-      { start: 2, end: 3 },
-    ]);
-
-    store._reportResidency({
-      collectionId: created.collectionId,
-      frameNumber: 1,
-      residentGeneration: 4,
-      lane: 'direct-storage',
-      requestedBytes: 4 * 80,
-      supportedBytes: 1 << 20,
-      uploadRanges: [{ start: 2, end: 3 }],
-      uploadedBytes: 80,
-      backend: 'webgpu',
-    });
-    store._resetResidency();
-    expect(store._inspections()[0]).toMatchObject({
-      lane: 'unresident',
-      uploadedBytes: 0,
-      uploadRanges: [],
-    });
-
-    expect(
-      instanceUploadRangesForResident(true, [{ start: 2, end: 3 }], { start: 0, end: 4 }),
-    ).toEqual([{ start: 0, end: 4 }]);
-    expect(
-      instanceUploadRangesForResident(false, [{ start: 2, end: 3 }], { start: 0, end: 4 }),
-    ).toEqual([{ start: 2, end: 3 }]);
-  });
-
-  it('rejects malformed stride, out-of-range writes and released ids structurally', () => {
-    const store = new InstanceCollectionStore();
-    const malformed = store.create({ transforms: new Float32Array(17) });
-    expect(malformed.ok).toBe(false);
-    if (malformed.ok) return;
-    expect(malformed.error.code).toBe('instance-collection-invalid');
-    expect(malformed.error.facts).toMatchObject({
-      requestedBytes: 17 * Float32Array.BYTES_PER_ELEMENT,
-      supportedBytes: undefined,
-      backend: 'unknown',
-      owner: 'renderer.instances',
-      cause: 'invalid-transform-stride',
-      recovery: malformed.error.hint,
-    });
-    const created = store.create({ transforms: identityTransforms(1) }).unwrap();
-    const range = store.update(created.collectionId, {
-      start: 1,
-      transforms: identityTransforms(1),
-    });
-    expect(range.ok).toBe(false);
-    if (range.ok) return;
-    expect(range.error.code).toBe('instance-collection-invalid');
-    expect(range.error.facts).toMatchObject({
-      requestedBytes: 2 * 16 * Float32Array.BYTES_PER_ELEMENT,
-      supportedBytes: 16 * Float32Array.BYTES_PER_ELEMENT,
-      backend: 'unknown',
-      owner: 'renderer.instances',
-      cause: 'invalid-update-range-end',
-      recovery: range.error.hint,
-    });
-    expect(store.release(created.collectionId).ok).toBe(true);
-    const released = store.inspect(created.collectionId);
-    expect(released.ok).toBe(false);
-    if (!released.ok) expect(released.error.code).toBe('instance-collection-not-found');
-  });
-
-  it('reports the logical authoring boundary when physical capacity has spare slots', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(3) }).unwrap();
-    expect(created.capacity).toBe(4);
-
-    const range = store.update(created.collectionId, {
-      start: 3,
-      transforms: identityTransforms(1),
+  it('rejects incomplete and non-finite matrices before they reach rendering', () => {
+    expect(validateInstanceTransforms(new Float32Array(17))).toMatchObject({
+      code: 'instance-transforms-stride-mismatch',
+      detail: { actualLength: 17, expectedStride: 16 },
     });
-    expect(range.ok).toBe(false);
-    if (range.ok) return;
-    expect(range.error.facts).toMatchObject({
-      requestedBytes: 4 * 16 * Float32Array.BYTES_PER_ELEMENT,
-      supportedBytes: 3 * 16 * Float32Array.BYTES_PER_ELEMENT,
-      cause: 'invalid-update-range-end',
-      owner: 'renderer.instances',
+    const invalid = matrices(0);
+    invalid[12] = NaN;
+    expect(validateInstanceTransforms(invalid)).toMatchObject({
+      code: 'instance-transforms-invalid',
+      detail: { actualLength: 16, nonFiniteIndex: 12 },
     });
+    expect(validateInstanceTransforms(new Float32Array())).toBeUndefined();
   });
 });

package/src/__tests__/instances-world-ownership.integration.test.ts

@@ -0,0 +1,62 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { Camera } from '../components/camera';
+import { Instances } from '../components/instances';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { extractFrames } from '../render-system-extract';
+
+function matrices(count: number, x: number): Float32Array {
+  const out = new Float32Array(count * 16);
+  for (let i = 0; i < count; i++) {
+    out[i * 16] = out[i * 16 + 5] = out[i * 16 + 10] = out[i * 16 + 15] = 1;
+    out[i * 16 + 12] = x;
+  }
+  return out;
+}
+
+function scene(count: number, x: number) {
+  const world = new World();
+  registerPropagateTransforms(world);
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    )
+    .unwrap();
+  const entity = world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Instances, data: { transforms: matrices(count, x) } },
+    )
+    .unwrap();
+  world.update(0).unwrap();
+  return { world, entity };
+}
+
+describe('World-owned instance authoring', () => {
+  it.each([1500, 10000, 20000])('extracts %s matrices without creating a Renderer', (count) => {
+    const { world } = scene(count, 0);
+    const snapshot = extractFrames([world], 0).renderables[0]?.instances;
+    expect(snapshot?.instanceCount).toBe(count);
+    expect(snapshot?.transforms).toEqual(matrices(count, 0));
+  });
+
+  it('keeps worlds isolated and lets independent consumers observe skipped updates', () => {
+    const a = scene(2, 0);
+    const b = scene(2, 1);
+    const before = extractFrames([a.world], 0).renderables[0]?.instances;
+    expect(extractFrames([b.world], 0).renderables[0]?.instances?.transforms[12]).toBe(1);
+    a.world.set(a.entity, Instances, { transforms: matrices(2, 0.5) }).unwrap();
+    extractFrames([a.world], 0);
+    a.world.set(a.entity, Instances, { transforms: matrices(2, -0.5) }).unwrap();
+    const late = extractFrames([a.world], 0).renderables[0]?.instances;
+    expect(late?.transforms[12]).toBe(-0.5);
+    expect(before?.transforms[12]).toBe(0);
+    expect(extractFrames([b.world], 0).renderables[0]?.instances?.transforms[12]).toBe(1);
+  });
+});

package/src/__tests__/ktx2-basis-gpu-consumer.dawn.test.ts

@@ -560,7 +560,10 @@ describe.skipIf(!pkgBuilt)('KTX2/Basis real GPU texture consumer matrix', () =>
     store.configureGpuDevice(
       device as never,
       undefined,
-      (world, pod) => ok(world.allocSharedRef('EquirectAsset', pod)),
+      (source, pod) => {
+        if ('resolveAsset' in source) throw new Error('This fixture only allocates World assets');
+        return ok(source.allocSharedRef('EquirectAsset', pod));
+      },
       device.caps,
     );
     const rows: GpuCell[] = [];

package/src/__tests__/main-pass-material-medium-selection.unit.test.ts

@@ -0,0 +1,145 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import {
+  buildPerSubmeshMaterialBg,
+  type PerSubmeshMaterialBgDeps,
+} from '../record/main-pass-material';
+
+const SHA_MEDIUM_SHADER = 'sha256:464bbf-single-layer-medium';
+
+interface TestBindGroupEntry {
+  readonly binding: number;
+}
+
+interface TestDependencies extends PerSubmeshMaterialBgDeps {
+  readonly bindGroupEntries: Array<readonly TestBindGroupEntry[]>;
+}
+
+function dependencies(
+  options: { readonly selectedShader?: string; readonly surfaceResources?: boolean } = {},
+): TestDependencies {
+  const resource = () => ({}) as never;
+  const bindGroupEntries: Array<readonly TestBindGroupEntry[]> = [];
+  const runtime = {
+    device: {
+      caps: { storageBuffer: false },
+      limits: { maxSampledTexturesPerShaderStage: 16 },
+      createBindGroup: (descriptor: { readonly entries: readonly TestBindGroupEntry[] }) => {
+        bindGroupEntries.push(descriptor.entries);
+        return { ok: true, value: resource() };
+      },
+    },
+    ...(options.selectedShader === SHA_MEDIUM_SHADER
+      ? {
+          getMaterialShaderArtifact: (shaderId: string) =>
+            shaderId === SHA_MEDIUM_SHADER
+              ? ({ receipt: { surface: { model: 'single-layer-medium' } } } as never)
+              : undefined,
+        }
+      : {}),
+  };
+  const pipelineState = {
+    materialBindGroupLayout: resource(),
+    materialUniformBuffer: { buffer: resource() },
+    meshStorageBuffer: { buffer: resource() },
+    defaultSampler: resource(),
+    defaultWhiteTextureView: resource(),
+    defaultNormalTextureView: resource(),
+    fallbackTextureView: resource(),
+    defaultAnisotropyTextureView: resource(),
+    ...(options.surfaceResources ? { surfaceMediumDepthSampler: resource() } : {}),
+  };
+  const deps = {
+    runtime,
+    pipelineState,
+    world: new World(),
+    store: { materialResourceEpoch: 0 },
+    materialSlice: 256,
+    videoHighPerfAvailable: false,
+    skylightResources: {
+      irradianceView: resource(),
+      irradianceSampler: resource(),
+      prefilterView: resource(),
+      skylightPrefilterView: resource(),
+      prefilterSampler: resource(),
+      brdfLutView: resource(),
+      intensityBuffer: resource(),
+    },
+    materialBgShared: new Map(),
+    materialBgAssemblyCache: new Map(),
+    bindGroupCounts: { createBindGroup: 0, keys: [] },
+    frameState: {},
+    ...(options.surfaceResources
+      ? {
+          surfaceRawDepthView: resource(),
+          surfaceNearestLayerView: resource(),
+          surfaceNearestDepthView: resource(),
+        }
+      : {}),
+    bindGroupEntries,
+  };
+  return deps as unknown as TestDependencies;
+}
+
+function mediumSnapshot() {
+  return {
+    materialShaderId: 'forgeax::selected-shadow',
+    surfaceModel: 'single-layer-medium',
+  } as never;
+}
+
+describe('main-pass Surface material selection', () => {
+  it('does not request raw depth when a non-medium pass shader is selected', () => {
+    expect(() =>
+      buildPerSubmeshMaterialBg(
+        dependencies(),
+        mediumSnapshot(),
+        4,
+        undefined,
+        'forgeax::selected-shadow',
+      ),
+    ).not.toThrow();
+  });
+
+  it('requires raw depth for the selected single-layer-medium shader', () => {
+    expect(() =>
+      buildPerSubmeshMaterialBg(
+        dependencies(),
+        mediumSnapshot(),
+        4,
+        undefined,
+        'forgeax::single-layer-medium',
+      ),
+    ).toThrow('single-layer medium material bind group has producer-owned raw depth');
+  });
+
+  it('uses the selected SHA medium artifact ABI instead of authored metadata', () => {
+    const missingResources = dependencies({ selectedShader: SHA_MEDIUM_SHADER });
+    expect(() =>
+      buildPerSubmeshMaterialBg(
+        missingResources,
+        mediumSnapshot(),
+        4,
+        undefined,
+        SHA_MEDIUM_SHADER,
+      ),
+    ).toThrow('single-layer medium material bind group has producer-owned raw depth');
+
+    const completeResources = dependencies({
+      selectedShader: SHA_MEDIUM_SHADER,
+      surfaceResources: true,
+    });
+    expect(() =>
+      buildPerSubmeshMaterialBg(
+        completeResources,
+        mediumSnapshot(),
+        4,
+        undefined,
+        SHA_MEDIUM_SHADER,
+      ),
+    ).not.toThrow();
+    const entries = completeResources.bindGroupEntries[0] ?? [];
+    expect(entries.length).toBeGreaterThan(0);
+    expect(entries.some(({ binding }) => binding === 47)).toBe(false);
+  });
+});