@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/__tests__/light-buffer-layout.unit.test.ts

@@ -0,0 +1,40 @@
+import type { Vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import { packSpotLight } from '../light-buffer-layout';
+import type { SpotLightSnapshot } from '../render-system-extract';
+
+const snapshot: SpotLightSnapshot = {
+  kind: 'spot',
+  position: new Float32Array([2, 3, 4]) as Vec3,
+  direction: new Float32Array([0, 1, 0]) as Vec3,
+  color: new Float32Array([4, 2, 1]) as Vec3,
+  intensity: 4,
+  invRangeSquared: 0.25,
+  cosInner: 0.98,
+  cosOuter: 0.7,
+  castShadow: false,
+  lightViewProj: undefined,
+  mapSize: 2048,
+  nearPlane: 0.1,
+  farPlane: 50,
+  shadowAtlasTile: -1,
+};
+
+describe('direct light snapshot buffer layout', () => {
+  it('packs the normalized snapshot without changing its public semantics', () => {
+    const packed = packSpotLight(snapshot);
+
+    expect([...packed.slice(0, 7)]).toEqual([2, 3, 4, 0.25, 4, 2, 1]);
+    expect(packed[7]).toBeCloseTo(0.98, 5);
+    expect([...packed.slice(8, 11)]).toEqual([0, 1, 0]);
+    expect(packed[11]).toBeCloseTo(0.7, 5);
+  });
+
+  it('does not introduce a pipeline-specific intensity multiplier', () => {
+    const packed = packSpotLight(snapshot);
+
+    expect(packed[4]).toBe(snapshot.color[0]);
+    expect(packed[5]).toBe(snapshot.color[1]);
+    expect(packed[6]).toBe(snapshot.color[2]);
+  });
+});

package/src/__tests__/material-contract-inventory.unit.test.ts

@@ -0,0 +1,24 @@
+import {
+  createBuiltinMaterialAsset,
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  DEFAULT_UNLIT_PARAM_SCHEMA,
+} from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+
+describe('vertex color does not change the material contract', () => {
+  it('keeps colored and plain materials on the same schema and resource identity', () => {
+    const plain = createBuiltinMaterialAsset('standard');
+    const colored = createBuiltinMaterialAsset('standard');
+    expect(colored.parameters).toEqual(plain.parameters);
+    expect(colored.passes).toEqual(plain.passes);
+    expect(DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => entry.name)).toContain('baseColor');
+    expect(DEFAULT_UNLIT_PARAM_SCHEMA.some((entry) => entry.name === 'color')).toBe(false);
+    expect(DEFAULT_STANDARD_PBR_PARAM_SCHEMA.some((entry) => entry.name === 'color')).toBe(false);
+  });
+
+  it('keeps vertex color out of the authored material flags and bindings', () => {
+    const material = createBuiltinMaterialAsset('unlit');
+    expect(JSON.stringify(material)).not.toMatch(/hasColor|VERTEX_COLOR_AVAILABLE|colorBinding/i);
+    expect(material.passes?.[0]?.program).not.toHaveProperty('color');
+  });
+});

package/src/__tests__/material-cooked-projection.unit.test.ts

@@ -0,0 +1,150 @@
+import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import { describe, expect, it } from 'vitest';
+import { assembleMaterialProjection } from '../assembly/material/assembly.js';
+import { projectMaterialPipeline } from '../assembly/material/pipeline-projection.js';
+
+function cookedRecord(): CookedMaterialRecord {
+  return {
+    schemaVersion: 'material-cook/3',
+    guid: 'material-leaf' as never,
+    specializationKey: 'specialization-key',
+    authored: {
+      kind: 'material',
+      parent: 'material-parent' as never,
+      values: { baseColor: [1, 0, 0, 1] },
+    },
+    resolved: {
+      passes: [
+        {
+          name: 'forward',
+          program: {
+            module: 'project::standard',
+            vertexEntry: 'vs_main',
+            fragmentEntry: 'fs_main',
+          },
+          renderState: { blend: 'opaque' },
+        },
+      ],
+      parameters: [{ name: 'baseColor', type: 'color' }],
+      values: { baseColor: [0.2, 0.3, 0.4, 1] },
+    },
+    refs: {
+      parent: ['material-parent'],
+      textures: [],
+      samplers: [],
+      modules: ['project::standard'],
+    },
+    artifact: {
+      mediaType: 'text/wgsl',
+      path: 'material-leaf.wgsl',
+      digest: 'sha256:artifact',
+      bytes: new Uint8Array([1, 2, 3]),
+    },
+    receipt: {
+      schemaVersion: 'material-cook/3',
+      sourceClosure: ['project::standard'],
+      profile: 'forgeax-material-wgsl-v1',
+      compilerVersion: 'compiler/1',
+      identity: {
+        materialContractDigest: 'sha256:contract',
+        sourceRevision: 'sha256:source',
+        sourceClosureDigest: 'sha256:closure',
+        layoutIdentity: 'sha256:layout',
+        programIdentity: 'sha256:program',
+        pipelineIdentity: 'sha256:pipeline',
+        materialPublicationIdentity: 'sha256:publication',
+        cookIdentity: 'sha256:input',
+        compilerFingerprint: 'sha256:compiler',
+        wasm: {
+          sourceContentKey: 'unavailable',
+          artifactSha256: 'unavailable',
+          glueSha256: 'unavailable',
+        },
+        artifactDigest: 'sha256:artifact',
+        valueGeneration: 1,
+        dependencyGeneration: 1,
+        cookGeneration: 1,
+      },
+      derivedInterface: { layoutIdentity: 'sha256:layout' },
+    },
+  };
+}
+
+describe('cooked material render projection', () => {
+  it('projects cooked passes and artifact identity without exposing authored inheritance', () => {
+    const projection = assembleMaterialProjection(cookedRecord());
+
+    expect(projection).toMatchObject({
+      materialGuid: 'material-leaf',
+      specializationKey: 'specialization-key',
+      artifactHash: 'sha256:artifact',
+      passes: [
+        {
+          name: 'forward',
+          module: 'project::standard',
+          vertexEntry: 'vs_main',
+          fragmentEntry: 'fs_main',
+        },
+      ],
+    });
+    expect('authored' in projection).toBe(false);
+    expect(projection.passes[0]?.artifactHash).toBe('sha256:artifact');
+  });
+
+  it('builds a pipeline projection from the cooked artifact, not the parent chain', () => {
+    const projection = assembleMaterialProjection(cookedRecord());
+    const pipeline = projectMaterialPipeline(projection);
+
+    expect(pipeline).toEqual({
+      specializationKey: 'specialization-key',
+      artifactHash: 'sha256:artifact',
+      passes: projection.passes,
+    });
+  });
+
+  it('keeps projections isolated when adjacent slots use different cooked identities', () => {
+    const firstRecord = cookedRecord();
+    const secondRecord: CookedMaterialRecord = {
+      ...firstRecord,
+      guid: 'material-slot-2' as never,
+      authored: {
+        kind: 'material',
+        ...firstRecord.authored,
+        parent: 'material-parent-2' as never,
+        values: { baseColor: [0, 1, 0, 1] },
+      },
+      resolved: {
+        ...firstRecord.resolved,
+        values: { baseColor: [0.8, 0.1, 0.2, 1] },
+      },
+      artifact: {
+        ...firstRecord.artifact,
+        path: 'material-slot-2.wgsl',
+        digest: 'sha256:artifact-2',
+        bytes: new Uint8Array([4, 5, 6]),
+      },
+      receipt: {
+        ...firstRecord.receipt,
+        identity: {
+          ...firstRecord.receipt.identity,
+          cookIdentity: 'sha256:input-2',
+          artifactDigest: 'sha256:artifact-2',
+        },
+      },
+      specializationKey: 'specialization-key-2',
+    };
+
+    const first = assembleMaterialProjection(firstRecord);
+    const second = assembleMaterialProjection(secondRecord);
+
+    expect(second).not.toBe(first);
+    expect(first.materialGuid).toBe('material-leaf');
+    expect(first.specializationKey).toBe('specialization-key');
+    expect(first.artifactHash).toBe('sha256:artifact');
+    expect(second.materialGuid).toBe('material-slot-2');
+    expect(second.specializationKey).toBe('specialization-key-2');
+    expect(second.artifactHash).toBe('sha256:artifact-2');
+    expect(second.runtimeValues).not.toBe(first.runtimeValues);
+    expect('authored' in second).toBe(false);
+  });
+});

package/src/__tests__/material-snapshot-mutation.integration.test.ts

@@ -0,0 +1,53 @@
+import { AssetRegistry, HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import type { ShaderRegistry } from '@forgeax/engine-shader';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { extractFrames, type MaterialSnapshotCachesByWorld } from '../render-system-extract';
+
+describe('material snapshot mutation', () => {
+  it('projects in-place material value updates into the next extracted frame', () => {
+    const world = new World();
+    const assets = new AssetRegistry({
+      findMaterialArtifact: () => ({ ok: false, error: new Error('not registered') }),
+    } as unknown as ShaderRegistry);
+    const values: Record<string, unknown> = {
+      baseColor: [1, 0, 0, 1],
+      metallic: 0,
+      roughness: 0.5,
+    };
+    const material: MaterialAsset = {
+      kind: 'material',
+      passes: [
+        {
+          name: 'Forward',
+          program: { module: 'forgeax::default-standard-pbr' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+        },
+      ],
+      values: values as NonNullable<MaterialAsset['values']>,
+    };
+    const materialHandle = world.allocSharedRef('MaterialAsset', material);
+
+    world.spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [materialHandle] } },
+    );
+    const materialCaches: MaterialSnapshotCachesByWorld = new WeakMap();
+
+    const first = extractFrames([world], 0, assets, undefined, materialCaches).renderables[0]
+      ?.material;
+    expect(first?.baseColor).toEqual(new Float32Array([1, 0, 0]));
+
+    values.baseColor = [0, 1, 0, 1];
+
+    const second = extractFrames([world], 0, assets, undefined, materialCaches).renderables[0]
+      ?.material;
+    expect(second?.baseColor).toEqual(new Float32Array([0, 1, 0]));
+    expect(second).not.toBe(first);
+  });
+});

package/src/__tests__/material-static-dynamic-route.unit.test.ts

@@ -0,0 +1,94 @@
+import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import { describe, expect, it, vi } from 'vitest';
+import { assembleMaterialProjection } from '../assembly/material/assembly.js';
+import {
+  routeMaterialPipeline,
+  updateMaterialRuntimeValues,
+} from '../assembly/material/pipeline-projection.js';
+
+const record: CookedMaterialRecord = {
+  schemaVersion: 'material-cook/3',
+  guid: 'material-route',
+  specializationKey: 'route-key',
+  authored: {
+    kind: 'material',
+    values: { useNormalMap: false },
+  },
+  resolved: {
+    passes: [{ name: 'forward', program: { module: 'project::standard' } }],
+    parameters: [
+      { name: 'baseColor', type: 'color' },
+      { name: 'useNormalMap', type: 'bool' },
+    ],
+    values: { baseColor: [1, 1, 1, 1], useNormalMap: false },
+  },
+  refs: { parent: [], textures: [], samplers: [], modules: ['project::standard'] },
+  artifact: {
+    mediaType: 'text/wgsl',
+    path: 'material-route.wgsl',
+    digest: 'sha256:route',
+    bytes: new Uint8Array([4]),
+  },
+  receipt: {
+    schemaVersion: 'material-cook/3',
+    sourceClosure: ['project::standard'],
+    profile: 'forgeax-material-wgsl-v1',
+    compilerVersion: 'compiler/1',
+    identity: {
+      materialContractDigest: 'sha256:contract',
+      sourceRevision: 'sha256:source',
+      sourceClosureDigest: 'sha256:closure',
+      layoutIdentity: 'sha256:layout',
+      programIdentity: 'sha256:program',
+      pipelineIdentity: 'sha256:pipeline',
+      materialPublicationIdentity: 'sha256:publication',
+      cookIdentity: 'sha256:input',
+      compilerFingerprint: 'sha256:compiler',
+      wasm: {
+        sourceContentKey: 'unavailable',
+        artifactSha256: 'unavailable',
+        glueSha256: 'unavailable',
+      },
+      artifactDigest: 'sha256:route',
+      valueGeneration: 1,
+      dependencyGeneration: 1,
+      cookGeneration: 1,
+    },
+    derivedInterface: { layoutIdentity: 'sha256:layout' },
+  },
+};
+
+describe('cooked material static and dynamic routing', () => {
+  it('updates runtime values without requesting a compile or changing the artifact key', () => {
+    const projection = assembleMaterialProjection(record);
+    const updated = updateMaterialRuntimeValues(projection, {
+      baseColor: [0.25, 0.5, 0.75, 1],
+    });
+
+    expect(updated.runtimeValues.baseColor).toEqual([0.25, 0.5, 0.75, 1]);
+    expect(updated.specializationKey).toBe(projection.specializationKey);
+  });
+
+  it('selects a cooked static specialization and returns a structured miss', () => {
+    const projection = assembleMaterialProjection(record);
+    const lookup = vi.fn((key: string) =>
+      key === 'route-key' ? { key, bytes: new Uint8Array([4]), digest: 'sha256:route' } : undefined,
+    );
+
+    const ready = routeMaterialPipeline({ projection, lookupArtifact: lookup });
+    expect(ready).toMatchObject({ kind: 'ready', specializationKey: 'route-key' });
+    expect(lookup).toHaveBeenCalledWith('route-key');
+
+    const missing = routeMaterialPipeline({
+      projection: { ...projection, specializationKey: 'uncooked-static-selection' },
+      lookupArtifact: lookup,
+    });
+    expect(missing).toMatchObject({
+      kind: 'error',
+      error: {
+        code: 'material-specialization-not-cooked',
+        detail: { specializationKey: 'uncooked-static-selection' },
+      },
+    });
+  });
+});

package/src/__tests__/material-stride-surface.unit.test.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { MATERIAL_PER_ENTITY_STRIDE } from '../render-system';
+
+const ownerSource = readFileSync(new URL('../record/render-context.ts', import.meta.url), 'utf8');
+const rendererFactorySource = readFileSync(
+  new URL('../assembly/factory.ts', import.meta.url),
+  'utf8',
+);
+const recordSources = [
+  readFileSync(new URL('../record/main-pass.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../record/main-pass-geometry.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../record/main-pass-sprite-draws.ts', import.meta.url), 'utf8'),
+  rendererFactorySource,
+];
+
+describe('material dynamic-offset stride surface', () => {
+  it('keeps one internal owner and routes every record path through it', () => {
+    expect(MATERIAL_PER_ENTITY_STRIDE).toBe(512);
+    expect(ownerSource.match(/export const MATERIAL_PER_ENTITY_STRIDE\s*=\s*512/g)).toHaveLength(1);
+
+    for (const source of recordSources) {
+      expect(source).toContain('MATERIAL_PER_ENTITY_STRIDE');
+      expect(source).not.toMatch(/const MATERIAL_PER_ENTITY_STRIDE\s*=/);
+    }
+  });
+
+  it('routes shared renderer allocation through the owner', () => {
+    expect(rendererFactorySource).toContain('perEntityStride: MATERIAL_PER_ENTITY_STRIDE');
+    expect(rendererFactorySource).not.toMatch(/const PER_ENTITY_STRIDE\s*=/);
+  });
+});

package/src/__tests__/mesh-buffer-usage-surface.unit.test.ts

@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_INDEX,
+  GPU_BUFFER_USAGE_INDIRECT,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+  GPU_BUFFER_USAGE_VERTEX,
+} from '../gpu-usage';
+
+const ownerSource = readFileSync(new URL('../gpu-usage.ts', import.meta.url), 'utf8');
+const meshSsboSource = readFileSync(new URL('../record/mesh-ssbo.ts', import.meta.url), 'utf8');
+const rendererFactorySource = readFileSync(
+  new URL('../assembly/factory.ts', import.meta.url),
+  'utf8',
+);
+const consumerSources = [
+  readFileSync(new URL('../render-data.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../device/gpu-residency.ts', import.meta.url), 'utf8'),
+  rendererFactorySource,
+];
+const featureBufferSources = [
+  {
+    source: readFileSync(new URL('../hdrp-buffers.ts', import.meta.url), 'utf8'),
+    names: ['GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_STORAGE', 'GPU_BUFFER_USAGE_COPY_DST'],
+  },
+  {
+    source: readFileSync(new URL('../ssao-buffers.ts', import.meta.url), 'utf8'),
+    names: ['GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],
+  },
+  {
+    source: readFileSync(new URL('../device/gpu-residency.ts', import.meta.url), 'utf8'),
+    names: ['GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],
+  },
+  {
+    source: readFileSync(new URL('../ibl/skylight-bind-group.ts', import.meta.url), 'utf8'),
+    names: ['GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],
+  },
+  {
+    source: readFileSync(new URL('../record/main-pass-geometry.ts', import.meta.url), 'utf8'),
+    names: ['GPU_BUFFER_USAGE_STORAGE', 'GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],
+  },
+  {
+    source: readFileSync(new URL('../record/main-pass-sprite-draws.ts', import.meta.url), 'utf8'),
+    names: ['GPU_BUFFER_USAGE_STORAGE', 'GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],
+  },
+  {
+    source: readFileSync(new URL('../record/shadow-pass.ts', import.meta.url), 'utf8'),
+    names: ['GPU_BUFFER_USAGE_STORAGE', 'GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],
+  },
+  {
+    source: readFileSync(new URL('../systems/skin-palette-allocator.ts', import.meta.url), 'utf8'),
+    names: ['GPU_BUFFER_USAGE_STORAGE', 'GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],
+  },
+  {
+    source: readFileSync(new URL('../render-system.ts', import.meta.url), 'utf8'),
+    names: ['GPU_BUFFER_USAGE_UNIFORM', 'GPU_BUFFER_USAGE_COPY_DST'],
+  },
+];
+
+describe('render buffer usage owner', () => {
+  it('keeps the render buffer bits in one owner', () => {
+    expect(GPU_BUFFER_USAGE_VERTEX).toBe(0x20);
+    expect(GPU_BUFFER_USAGE_INDEX).toBe(0x10);
+    expect(GPU_BUFFER_USAGE_COPY_DST).toBe(0x08);
+    expect(GPU_BUFFER_USAGE_COPY_SRC).toBe(0x04);
+    expect(GPU_BUFFER_USAGE_INDIRECT).toBe(0x100);
+    expect(GPU_BUFFER_USAGE_UNIFORM).toBe(0x40);
+    expect(GPU_BUFFER_USAGE_STORAGE).toBe(0x80);
+    expect(GPU_BUFFER_USAGE_MAP_READ).toBe(0x01);
+    expect(ownerSource.match(/export const GPU_BUFFER_USAGE_/g)).toHaveLength(8);
+  });
+
+  it('routes mesh descriptor, update, and bootstrap consumers through the owner', () => {
+    for (const source of consumerSources) {
+      expect(source).toContain('GPU_BUFFER_USAGE_VERTEX');
+      expect(source).toContain('GPU_BUFFER_USAGE_INDEX');
+      expect(source).toContain('GPU_BUFFER_USAGE_COPY_DST');
+      expect(source).not.toMatch(/const GPU_BUFFER_USAGE_(VERTEX|INDEX|COPY_DST)\s*=/);
+      expect(source).not.toMatch(/usage:\s*0x[0-9a-f]+/i);
+    }
+  });
+
+  it('routes feature-local buffer consumers through the owner', () => {
+    for (const { source, names } of featureBufferSources) {
+      for (const name of names) {
+        expect(source).toContain(name);
+        expect(source).not.toMatch(new RegExp(`const ${name}\\s*=`));
+      }
+    }
+  });
+
+  it('keeps shadow-depth readback out of the renderer factory', () => {
+    expect(rendererFactorySource).not.toContain('GPU_BUFFER_USAGE_MAP_READ');
+    expect(rendererFactorySource).not.toMatch(/const (COPY_DST|MAP_READ)\s*=\s*0x/);
+  });
+
+  it('removes the record cluster buffer usage aliases', () => {
+    expect(meshSsboSource).not.toMatch(
+      /export const (STORAGE_USAGE|UNIFORM_USAGE|COPY_DST_USAGE)\s*=/,
+    );
+  });
+});

package/src/__tests__/mesh-material-bindings.unit.test.ts

@@ -0,0 +1,89 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { resolveMeshMaterialBindings } from '../mesh-material-bindings';
+
+function guid(value: string) {
+  const parsed = AssetGuid.parse(value);
+  if (!parsed.ok) throw new Error(`invalid fixture guid: ${value}`);
+  return parsed.value;
+}
+
+const DEFAULT_A = guid('019d0000-0000-7000-8000-000000000001');
+const DEFAULT_B = guid('019d0000-0000-7000-8000-000000000002');
+
+function mesh(): MeshAsset {
+  return {
+    kind: 'mesh',
+    vertices: new Float32Array(0),
+    attributes: {},
+    submeshes: [
+      { indexOffset: 0, indexCount: 0, vertexCount: 0, topology: 'triangle-list', materialSlot: 0 },
+      { indexOffset: 0, indexCount: 0, vertexCount: 0, topology: 'triangle-list', materialSlot: 1 },
+      { indexOffset: 0, indexCount: 0, vertexCount: 0, topology: 'triangle-list', materialSlot: 0 },
+    ],
+    materialSlots: [
+      { slotName: 'Body', defaultMaterial: DEFAULT_A },
+      { slotName: 'Trim', defaultMaterial: DEFAULT_B },
+    ],
+  };
+}
+
+describe('resolveMeshMaterialBindings', () => {
+  it('fails closed instead of throwing when a runtime producer omits materialSlots', () => {
+    const result = resolveMeshMaterialBindings(
+      { ...mesh(), materialSlots: undefined } as unknown as MeshAsset,
+      [],
+      deps,
+    );
+    expect(result).toEqual({ ok: false, code: 'mesh-material-slots-missing' });
+  });
+  const deps = {
+    isValidOverride: (handle: number) => handle === 11,
+    resolveMeshDefault: (guid: typeof DEFAULT_A) =>
+      AssetGuid.format(guid) === AssetGuid.format(DEFAULT_A) ? 21 : 22,
+  };
+
+  it('inherits every mesh default for an empty override vector', () => {
+    expect(resolveMeshMaterialBindings(mesh(), [], deps)).toEqual({
+      ok: true,
+      bindings: [
+        { handle: 21, source: 'mesh-default' },
+        { handle: 22, source: 'mesh-default' },
+      ],
+      diagnostics: [],
+    });
+  });
+
+  it('supports partial overrides and treats zero as inherit', () => {
+    expect(resolveMeshMaterialBindings(mesh(), [11, 0], deps)).toMatchObject({
+      ok: true,
+      bindings: [
+        { handle: 11, source: 'renderer-override' },
+        { handle: 22, source: 'mesh-default' },
+      ],
+    });
+  });
+
+  it('falls back from an invalid override and reports overflow without changing slot count', () => {
+    expect(resolveMeshMaterialBindings(mesh(), [99, 0, 11], deps)).toEqual({
+      ok: true,
+      bindings: [
+        { handle: 21, source: 'mesh-default' },
+        { handle: 22, source: 'mesh-default' },
+      ],
+      diagnostics: [
+        { code: 'mesh-renderer-material-override-overflow', slotIndex: 2 },
+        { code: 'mesh-renderer-material-override-invalid', slotIndex: 0, handle: 99 },
+      ],
+    });
+  });
+
+  it('fails closed when a declared mesh default is unavailable', () => {
+    const result = resolveMeshMaterialBindings(mesh(), [], {
+      isValidOverride: () => false,
+      resolveMeshDefault: () => undefined,
+    });
+    expect(result).toMatchObject({ ok: false, slotIndex: 0 });
+  });
+});

package/src/__tests__/mesh-stride-surface.unit.test.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { MESH_PER_ENTITY_STRIDE } from '../record/mesh-ssbo';
+
+const ownerSource = readFileSync(new URL('../record/mesh-ssbo.ts', import.meta.url), 'utf8');
+const hdrpSource = readFileSync(new URL('../hdrp-buffers.ts', import.meta.url), 'utf8');
+
+describe('mesh dynamic-offset stride surface', () => {
+  it('keeps the HDRP storage binding on the mesh-SSBO owner', () => {
+    expect(MESH_PER_ENTITY_STRIDE).toBe(256);
+    expect(ownerSource.match(/export const MESH_PER_ENTITY_STRIDE\s*=\s*256/g)).toHaveLength(1);
+    expect(hdrpSource).toContain('MESH_PER_ENTITY_STRIDE');
+    expect(hdrpSource).not.toContain('MESH_SSBO_PER_ENTITY_STRIDE');
+    expect(hdrpSource).not.toMatch(/const MESH_PER_ENTITY_STRIDE\s*=/);
+  });
+});