@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,85 @@
+import type { Vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import {
+  BYTES_PER_LIGHT_SLOT,
+  LIGHTSLOT_LAYOUT,
+  LightSlotKind,
+  packLightSlot,
+  packSpotLight,
+} from '../light-buffer-layout';
+import type { SpotLightSnapshot } from '../render-system-extract';
+
+const snapshot: SpotLightSnapshot = {
+  kind: 'spot',
+  entity: 7,
+  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: true,
+  lightViewProj: new Float32Array(16),
+  mapSize: 2048,
+  nearPlane: 0.1,
+  farPlane: 50,
+  shadowAtlasTile: 3,
+};
+
+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]);
+  });
+
+  it('keeps the HDRP LightSlot at 64 bytes and writes raw kind/tile lanes', () => {
+    const packed = packLightSlot(snapshot);
+    const i32 = new Int32Array(packed.buffer);
+    const u32 = new Uint32Array(packed.buffer);
+
+    expect(BYTES_PER_LIGHT_SLOT).toBe(64);
+    expect(LIGHTSLOT_LAYOUT.byteSize).toBe(64);
+    expect(LIGHTSLOT_LAYOUT.shadowPayloadOffset).toBe(52);
+    expect(LIGHTSLOT_LAYOUT.shadowAtlasTileOffset).toBe(52);
+    expect(u32[12]).toBe(LightSlotKind.SPOT);
+    expect(i32[13]).toBe(3);
+    expect(packed[14]).toBe(0);
+    expect(packed[15]).toBe(0);
+  });
+
+  it('keeps the point shadow layer and near/far lanes intact', () => {
+    const point = {
+      kind: 'point' as const,
+      position: new Float32Array([0, 1, 2]) as Vec3,
+      color: new Float32Array([1, 0.5, 0.25]) as Vec3,
+      intensity: 2,
+      invRangeSquared: 0.04,
+    };
+    const packed = packLightSlot(point, { shadowAtlasLayer: 2, near: 0.1, far: 25 });
+    const i32 = new Int32Array(packed.buffer);
+
+    expect(new Uint32Array(packed.buffer)[12]).toBe(LightSlotKind.POINT);
+    expect(i32[13]).toBe(2);
+    expect(packed[14]).toBeCloseTo(0.1, 5);
+    expect(packed[15]).toBe(25);
+  });
+
+  it('preserves -1 for a clipped fifth caster fixture', () => {
+    const clipped = { ...snapshot, shadowAtlasTile: -1 };
+    const packed = packLightSlot(clipped);
+    expect(new Int32Array(packed.buffer)[13]).toBe(-1);
+  });
+});

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,177 @@
+import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import type { ShaderRegistry } from '@forgeax/engine-shader';
+import type { MaterialAsset, ParamSchemaEntry } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import type { RenderAssetPort } from '../assets/render-asset-port.js';
+import { resolveMaterialFromPort } from '../extract/material-interface.js';
+import { assembleMaterialProjection } from '../renderer/material/assembly.js';
+import { projectMaterialPipeline } from '../renderer/material/pipeline-projection.js';
+
+function cookedRecord(): CookedMaterialRecord {
+  return {
+    schemaVersion: 'material-cook/2',
+    guid: 'material-leaf' as never,
+    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/2',
+      sourceClosure: ['project::standard'],
+      profile: 'forgeax-material-wgsl-v1',
+      compilerVersion: 'compiler/1',
+      inputDigest: 'specialization-key',
+      outputDigest: 'sha256:artifact',
+      layoutIdentity: 'sha256:layout',
+      derivedInterface: { layoutIdentity: 'sha256:layout' },
+    },
+  };
+}
+
+describe('cooked material render projection', () => {
+  it('registers the cooked shader at the Render boundary and projects resolved fields', () => {
+    const record = cookedRecord();
+    const installed = new Map<
+      string,
+      { source: string; paramSchema: readonly ParamSchemaEntry[] }
+    >();
+    const shaderRegistry = {
+      findMaterialArtifact(identifier: string) {
+        const entry = installed.get(identifier);
+        return entry === undefined
+          ? { ok: false, error: new Error('not registered') }
+          : { ok: true, value: entry };
+      },
+      installMaterialArtifact(
+        identifier: string,
+        entry: { source: string; paramSchema: readonly ParamSchemaEntry[] },
+      ) {
+        installed.set(identifier, entry);
+      },
+    } as unknown as ShaderRegistry;
+    const assets: RenderAssetPort = {
+      epoch: 0,
+      shaderRegistry,
+      lookup: () => undefined,
+      guidOf: () => 'material-leaf',
+      materialShaderTextureFieldNames: () => [],
+    };
+    const material = {
+      kind: 'material' as const,
+      cooked: record,
+    } as MaterialAsset & { readonly cooked: CookedMaterialRecord };
+
+    const resolved = resolveMaterialFromPort(material, assets);
+
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok) return;
+    expect(resolved.value.passes).toEqual(record.resolved.passes);
+    expect(resolved.value.values).toEqual(record.resolved.values);
+    expect(installed.get('project::standard')).toEqual({
+      source: new TextDecoder().decode(record.artifact.bytes),
+      paramSchema: [{ name: 'baseColor', type: 'color' }],
+    });
+  });
+
+  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',
+      layoutIdentity: 'sha256:layout',
+      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,
+        inputDigest: 'specialization-key-2',
+        outputDigest: 'sha256:artifact-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-derived-error-stop-draw.integration.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type DerivedMaterialPayloadCoordinate,
+  writeDerivedMaterialPayload,
+} from '../record/material-payload.js';
+
+const textureSchema = [{ name: 'albedo', type: 'texture2d' as const }];
+const validCoordinates: Readonly<Record<string, DerivedMaterialPayloadCoordinate>> = {
+  albedo: {
+    set: 0,
+    transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
+    physicalUvScale: [1, 1],
+  },
+};
+
+describe('derived material stop-draw falsification', () => {
+  it('stops before record when the derived interface is absent', () => {
+    const result = writeDerivedMaterialPayload({
+      material: 'missing-layout',
+      schema: undefined,
+      values: {},
+      coordinates: {},
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('material-derived-interface-mismatch');
+  });
+
+  it('resolves omitted coordinates and stops when allocation is insufficient', () => {
+    const missing = writeDerivedMaterialPayload({
+      material: 'missing-coordinate',
+      schema: textureSchema,
+      values: {},
+      coordinates: {},
+    });
+    expect(missing.ok).toBe(true);
+
+    const shortage = writeDerivedMaterialPayload({
+      material: 'short-payload',
+      schema: textureSchema,
+      values: {},
+      coordinates: validCoordinates,
+      capacityBytes: 16,
+    });
+    expect(shortage.ok).toBe(false);
+    if (!shortage.ok) expect(shortage.error.code).toBe('material-payload-bounds');
+  });
+
+  it('stops before submit for non-finite coordinates and never returns a partial payload', () => {
+    const result = writeDerivedMaterialPayload({
+      material: 'non-finite-coordinate',
+      schema: textureSchema,
+      values: {},
+      coordinates: {
+        albedo: {
+          set: 0,
+          transform: { offset: [0, Infinity], scale: [1, 1], rotation: 0 },
+          physicalUvScale: [1, 1],
+        },
+      },
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatchObject({
+        code: 'material-texture-coordinate-invalid',
+        detail: { action: 'recook', reason: 'non-finite' },
+      });
+    }
+  });
+});

package/src/__tests__/material-derived-payload.integration.test.ts

@@ -0,0 +1,164 @@
+import type { ParamSchemaEntry } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { deriveMaterialSlotProjection } from '../extract/material-interface.js';
+import { writeDerivedMaterialPayload } from '../record/material-payload.js';
+
+const schema: readonly ParamSchemaEntry[] = [
+  { name: 'brick', type: 'vec4', default: [0, 0, 0, 0] },
+  { name: 'albedo', type: 'texture2d' },
+  { name: 'noiseScale', type: 'f32', default: 1 },
+  { name: 'normal', type: 'texture2d' },
+];
+
+const coordinates = {
+  albedo: {
+    set: 2,
+    transform: { offset: [0.1, 0.2], scale: [0.8, 0.7], rotation: 0.25 },
+    physicalUvScale: [0.9, 0.95],
+  },
+  normal: {
+    set: 3,
+    transform: { offset: [-0.1, 0.3], scale: [1.2, 0.6], rotation: -0.5 },
+    physicalUvScale: [0.75, 0.875],
+  },
+} as const;
+
+describe('derived material payload integration', () => {
+  it('allocates the exact derived size and writes numeric and coordinate records', () => {
+    const result = writeDerivedMaterialPayload({
+      material: 'slot-a',
+      schema,
+      values: { brick: [0.1, 0.2, 0.3, 0.4], noiseScale: 3 },
+      coordinates,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.byteLength).toBe(96);
+    const bytes = new Uint8Array(result.value);
+    expect(bytes.some((value) => value !== 0)).toBe(true);
+    const floats = new Float32Array(result.value.buffer);
+    expect(floats[0]).toBeCloseTo(0.1);
+    expect(floats[4]).toBeCloseTo(0.1);
+    expect(floats[5]).toBeCloseTo(0.2);
+    expect(floats[6]).toBeCloseTo(0.8);
+    expect(floats[7]).toBeCloseTo(0.7);
+    expect(floats[8]).toBe(2);
+    expect(floats[9]).toBeCloseTo(0.25);
+    expect(floats[10]).toBeCloseTo(0.9);
+    expect(floats[11]).toBeCloseTo(0.95);
+  });
+
+  it('keeps the initially cleared and unwritten bytes zero', () => {
+    const result = writeDerivedMaterialPayload({
+      material: 'slot-default',
+      schema,
+      values: {},
+      coordinates,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const floats = new Float32Array(result.value.buffer);
+    expect(floats[12]).toBe(1);
+    expect(floats[13]).toBe(0);
+    expect(floats[14]).toBe(0);
+    expect(floats[15]).toBe(0);
+  });
+
+  it('inherits omitted vector components from the schema default', () => {
+    const result = writeDerivedMaterialPayload({
+      material: 'color-shorthand',
+      schema: [{ name: 'baseColor', type: 'color', default: [1, 1, 1, 1] }],
+      values: { baseColor: [0.2, 0.3, 0.4] },
+      coordinates: new Map(),
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(Array.from(new Float32Array(result.value.buffer))).toEqual([
+      expect.closeTo(0.2),
+      expect.closeTo(0.3),
+      expect.closeTo(0.4),
+      1,
+    ]);
+  });
+
+  it('isolates two slots that share a schema but not their values', () => {
+    const first = writeDerivedMaterialPayload({
+      material: 'slot-a',
+      schema,
+      values: { brick: [1, 0, 0, 1], noiseScale: 2 },
+      coordinates,
+    });
+    const second = writeDerivedMaterialPayload({
+      material: 'slot-b',
+      schema,
+      values: { brick: [0, 1, 0, 1], noiseScale: 4 },
+      coordinates,
+    });
+    expect(first.ok).toBe(true);
+    expect(second.ok).toBe(true);
+    if (!first.ok || !second.ok) return;
+    expect(first.value).not.toBe(second.value);
+    expect(new Float32Array(first.value.buffer)[0]).toBe(1);
+    expect(new Float32Array(second.value.buffer)[0]).toBe(0);
+    expect(new Float32Array(first.value.buffer)[12]).toBe(2);
+    expect(new Float32Array(second.value.buffer)[12]).toBe(4);
+  });
+
+  it('derives finite physical UV scale from the producer texture extent', () => {
+    const projection = deriveMaterialSlotProjection({
+      material: 'compressed-extent',
+      schema: [{ name: 'albedo', type: 'texture2d' }],
+      values: {},
+      coordinates: new Map([
+        [
+          'albedo',
+          {
+            set: 0,
+            transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
+          },
+        ],
+      ]),
+      textures: new Map([['albedo', { format: 'bc7-rgba-unorm', width: 2085, height: 1573 }]]),
+    });
+
+    expect(projection.ok).toBe(true);
+    if (!projection.ok) return;
+    expect(projection.value.coordinates.get('albedo')?.physicalUvScale).toEqual([
+      2085 / 2088,
+      1573 / 1576,
+    ]);
+    const payload = writeDerivedMaterialPayload({
+      material: projection.value.material,
+      schema: [{ name: 'albedo', type: 'texture2d' }],
+      values: projection.value.numericValues,
+      coordinates: projection.value.coordinates,
+    });
+    expect(payload.ok).toBe(true);
+  });
+
+  it('resolves omitted texture coordinates to an identity record', () => {
+    const projection = deriveMaterialSlotProjection({
+      material: 'default-texture-coordinates',
+      schema: [{ name: 'albedo', type: 'texture2d' }],
+      values: { albedo: 7 },
+      coordinates: new Map(),
+      textures: new Map([['albedo', { format: 'rgba8unorm', width: 512, height: 500 }]]),
+    });
+
+    expect(projection.ok).toBe(true);
+    if (!projection.ok) return;
+    expect(projection.value.coordinates.get('albedo')).toMatchObject({
+      set: 0,
+      transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
+      physicalUvScale: [1, 1],
+    });
+    expect(
+      writeDerivedMaterialPayload({
+        material: projection.value.material,
+        schema: [{ name: 'albedo', type: 'texture2d' }],
+        values: projection.value.numericValues,
+        coordinates: projection.value.coordinates,
+      }).ok,
+    ).toBe(true);
+  });
+});

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

@@ -0,0 +1,58 @@
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import {
+  extractFrames,
+  type MaterialSnapshotCachesByWorld,
+  MeshFilter,
+  MeshRenderer,
+} from '@forgeax/engine-render/internal';
+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 { createRenderAssetPort } from '../assets/render-asset-port';
+
+describe('material snapshot mutation', () => {
+  it('projects in-place material value updates into the next extracted frame', () => {
+    const world = new World();
+    const assets = createRenderAssetPort({
+      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);
+    const meshHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
+
+    world.spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshRenderer, data: { materials: [materialHandle] } },
+    );
+    const materialCaches: MaterialSnapshotCachesByWorld = new WeakMap();
+
+    const first = extractFrames([world], 0, assets, undefined, 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, 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,113 @@
+import { World } from '@forgeax/engine-ecs';
+import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import { describe, expect, it, vi } from 'vitest';
+import { writeDerivedMaterialPayload } from '../record/material-payload.js';
+import { assembleMaterialProjection } from '../renderer/material/assembly.js';
+import {
+  routeMaterialPipeline,
+  updateMaterialRuntimeValues,
+} from '../renderer/material/pipeline-projection.js';
+import { resolveTilesetRuntime } from '../tilemap/resolve-tileset-runtime';
+
+const record: CookedMaterialRecord = {
+  schemaVersion: 'material-cook/2',
+  guid: 'material-route',
+  resolved: {
+    passes: [{ name: 'forward', program: { module: 'project::standard' } }],
+    parameters: [
+      { name: 'baseColor', type: 'color' },
+      { name: 'useNormalMap', type: 'bool', static: true },
+    ],
+    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/2',
+    sourceClosure: ['project::standard'],
+    profile: 'forgeax-material-wgsl-v1',
+    compilerVersion: 'compiler/1',
+    inputDigest: 'route-key',
+    outputDigest: 'sha256:route',
+    layoutIdentity: 'sha256:layout',
+    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: { material: 'material-route', staticSelection: ['useNormalMap'] },
+      },
+    });
+  });
+});
+
+describe('tileset atlas material projection', () => {
+  it('fails closed for a missing or wrong-kind atlas payload', () => {
+    const world = new World();
+    const missing = resolveTilesetRuntime(world, 'missing-atlas', () => undefined);
+    const wrongKind = resolveTilesetRuntime(
+      world,
+      'wrong-atlas',
+      () => ({ kind: 'audio' }) as never,
+    );
+
+    expect(missing).toMatchObject({ ok: false, error: { code: 'tileset-atlas-not-found' } });
+    expect(wrongKind).toMatchObject({ ok: false, error: { code: 'tileset-atlas-kind-mismatch' } });
+  });
+
+  it('reports stale atlas payloads instead of casting them into a handle', () => {
+    const result = resolveTilesetRuntime(new World(), 'stale-atlas', () => ({ code: 'stale' }));
+    expect(result).toMatchObject({ ok: false, error: { code: 'tileset-atlas-stale' } });
+  });
+});
+
+describe('material coordinate projection route', () => {
+  it('keeps coordinate metadata on the derived slot path', () => {
+    const result = writeDerivedMaterialPayload({
+      material: 'route-coordinates',
+      schema: [{ name: 'albedo', type: 'texture2d' }],
+      values: {},
+      coordinates: {
+        albedo: {
+          set: 3,
+          transform: { offset: [0.25, 0.5], scale: [2, 2], rotation: 0.75 },
+          physicalUvScale: [0.9, 0.8],
+        },
+      },
+    });
+    expect(result.ok).toBe(true);
+  });
+});