@forgeax/engine-render 0.1.2

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('../render-system.ts', import.meta.url), 'utf8');
+const rendererFactorySource = readFileSync(
+  new URL('../renderer/renderer-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__/materials.unit.test.ts

@@ -0,0 +1,25 @@
+import { DEFAULT_UNLIT_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import { derive, type ParamSchemaEntry } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { Materials } from '../materials.js';
+
+function authoredParamSchema(material: ReturnType<typeof Materials.unlit>): ParamSchemaEntry[] {
+  return (material.parameters ?? []).map((parameter) => ({
+    name: parameter.name,
+    type: parameter.type === 'texture' ? 'texture2d' : parameter.type,
+  })) as ParamSchemaEntry[];
+}
+
+describe('built-in material authoring contracts', () => {
+  it('keeps unlit authoring order identical to the shader layout', () => {
+    const material = Materials.unlit([1, 1, 1, 1]);
+    const authored = derive(authoredParamSchema(material));
+    const shader = derive(DEFAULT_UNLIT_PARAM_SCHEMA);
+
+    expect(material.parameters?.map((parameter) => parameter.name)).toEqual(
+      DEFAULT_UNLIT_PARAM_SCHEMA.map((parameter) => parameter.name),
+    );
+    expect(authored.layoutIdentity).toBe(shader.layoutIdentity);
+    expect(authored.coordinateRecords.map((record) => record.offset)).toEqual([32]);
+  });
+});

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

@@ -0,0 +1,107 @@
+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('../renderer/renderer-factory.ts', import.meta.url),
+  'utf8',
+);
+const consumerSources = [
+  readFileSync(new URL('../render-data.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../gpu-resource-store.ts', import.meta.url), 'utf8'),
+];
+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('../ibl/face-uniforms.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 and update 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('routes shadow-depth readback staging through the owner', () => {
+    expect(rendererFactorySource).toContain(
+      'GPU_BUFFER_USAGE_COPY_DST | 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*=/);
+  });
+});

package/src/__tests__/morph-culling-reentry.dawn.test.ts

@@ -0,0 +1,166 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiCommandEncoder } from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderFeatureContributionStaging } from '../features/graph-contribution';
+import {
+  createMorphFeature,
+  createMorphReentryState,
+  deriveMorphBounds,
+  MORPH_COMPUTE_WGSL,
+  morphCullDecision,
+  stepMorphReentry,
+} from '../features/morph';
+import { createRenderFeatureGpuWorkResolver } from '../features/prepared-gpu-work';
+import { createRenderFeatureGraphicsPrepare } from '../features/prepared-graphics';
+import { RenderFeatureComputeGraphProjection } from '../features/render-graph-compute';
+
+const baseBounds = {
+  min: [-1, -1, -1] as const,
+  max: [1, 1, 1] as const,
+};
+
+describe('Morph GPU culling and re-entry', () => {
+  it('expands bounds from weighted target deltas before culling', () => {
+    const bounds = deriveMorphBounds(
+      baseBounds,
+      [{ min: [-2, 0, 0], max: [3, 0, 0] }],
+      new Float32Array([0.5]),
+    );
+
+    expect(bounds).toEqual({ min: [-2, -1, -1], max: [2.5, 1, 1] });
+    expect(
+      morphCullDecision({
+        weights: new Float32Array([0.5]),
+        expectedWeightCount: 1,
+        baseAabbIntersectsFrustum: false,
+      }),
+    ).toBe('draw');
+  });
+
+  it('clears stale weights when a culled instance re-enters', () => {
+    const state = createMorphReentryState();
+    expect(
+      stepMorphReentry(state, {
+        frameNumber: 1,
+        visible: true,
+        generation: 0,
+        weights: new Float32Array([0.25]),
+      }),
+    ).toMatchObject({ reentered: false, clearStale: false });
+    expect(
+      stepMorphReentry(state, {
+        frameNumber: 2,
+        visible: false,
+        generation: 0,
+        weights: new Float32Array([0]),
+      }),
+    ).toMatchObject({ reentered: false, clearStale: false });
+    expect(
+      stepMorphReentry(state, {
+        frameNumber: 3,
+        visible: true,
+        generation: 0,
+        weights: new Float32Array([0.75]),
+      }),
+    ).toMatchObject({ reentered: true, clearStale: true, weights: [0.75] });
+  });
+
+  it('declares compute and storage capability ownership and records 300 frame phases', () => {
+    let frameNumber = 0;
+    const feature = createMorphFeature({
+      collect: () => [
+        {
+          identity: 'format-tier1.face',
+          vertexCount: 3,
+          targetBounds: [{ min: [-2, 0, 0], max: [3, 0, 0] }],
+          baseBounds,
+          weights: new Float32Array([frameNumber >= 200 ? 1 : 0]),
+          baseAabbIntersectsFrustum: frameNumber < 100 || frameNumber >= 200,
+        },
+      ],
+    });
+
+    expect(feature.requiredCapabilities).toEqual(['compute', 'storageBuffer']);
+    let culledFrames = 0;
+    let reentries = 0;
+    for (frameNumber = 0; frameNumber < 300; frameNumber++) {
+      const extracted = feature.extract({ worlds: [], owner: 0, frameNumber });
+      expect(extracted.ok).toBe(true);
+      if (!extracted.ok) continue;
+      culledFrames += extracted.value.culledCount;
+      reentries += extracted.value.reentryCount;
+    }
+
+    expect(culledFrames).toBe(100);
+    expect(reentries).toBe(1);
+  });
+
+  it('submits one real Dawn compute frame through the Morph feature seam', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await createShaderModule(device, { code: MORPH_COMPUTE_WGSL })).unwrap();
+    const resolver = createRenderFeatureGpuWorkResolver({
+      device,
+      generation: 0,
+      featureIdentity: 'forgeax.morph',
+      shaderModuleFactory: { createShaderModule: () => ok(shader) },
+    });
+    const feature = createMorphFeature({
+      collect: () => [
+        {
+          identity: 'dawn-triangle',
+          vertexCount: 3,
+          baseBounds,
+          targetBounds: [{ min: [-1, 0, 0], max: [1, 0, 0] }],
+          weights: new Float32Array([0.5]),
+          baseAabbIntersectsFrustum: true,
+          basePositions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+          targetDeltas: new Float32Array([0, 0, 0, 0.1, 0, 0, 0, 0.1, 0]),
+        },
+      ],
+    });
+    const frame = feature.extract({ worlds: [], owner: 0, frameNumber: 1 });
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+    resolver.beginFrame();
+    const context = {
+      caps: device.caps,
+      frame: { frameNumber: 1 },
+      resources: [],
+      targets: [],
+      reportError: { report: () => undefined },
+      graphics: createRenderFeatureGraphicsPrepare('forgeax.morph', 0),
+      gpu: resolver,
+    } as const;
+    expect(feature.prepare(frame.value, context).ok).toBe(true);
+    const staging = createRenderFeatureContributionStaging(
+      'forgeax.morph',
+      0,
+      undefined,
+      undefined,
+      (descriptor) => resolver.resolveComputePass('forgeax.morph', descriptor),
+    );
+    expect(feature.contribute(frame.value, { ...context, staging }).ok).toBe(true);
+    const contribution = staging.commit();
+    expect(contribution.ok).toBe(true);
+    if (!contribution.ok) return;
+    const encoder = device.createCommandEncoder({ label: 'dawn-morph-frame' }).unwrap();
+    const work = contribution.value.passes[0]?.resolvedGpuCompute;
+    expect(work).toBeDefined();
+    if (work === undefined) return;
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const projection = new RenderFeatureComputeGraphProjection(graph);
+    expect(projection.addPass('forgeax.morph.compute', 'forgeax.morph', 0, work).ok).toBe(true);
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    expect(compiled.execute({ encoder }).ok).toBe(true);
+    const commandBuffer = encoder.finish();
+    expect(commandBuffer.ok).toBe(true);
+    if (!commandBuffer.ok) return;
+    expect(device.queue.submit([commandBuffer.value]).ok).toBe(true);
+    await device.queue.onSubmittedWorkDone();
+    expect((await compiled.retire()).ok).toBe(true);
+    expect(resolver.dispose().ok).toBe(true);
+  });
+});

package/src/__tests__/morph-feature-gpu-work.integration.test.ts

@@ -0,0 +1,78 @@
+import { rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  createRenderFeatureContributionStaging,
+  createRenderFeatureGpuWorkResolver,
+} from '../features';
+import { createMorphFeature, MORPH_COMPUTE_WGSL } from '../features/morph';
+import { encodeRenderFeatureGpuComputePass } from '../features/prepared-gpu-work';
+import { createRenderFeatureGraphicsPrepare } from '../features/prepared-graphics';
+
+describe('Morph RenderFeature GPU work', () => {
+  it('prepares persistent buffers and records a compute pass through the feature seam', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: MORPH_COMPUTE_WGSL })).unwrap();
+    const resolver = createRenderFeatureGpuWorkResolver({
+      device,
+      generation: 0,
+      featureIdentity: 'forgeax.morph',
+      shaderModuleFactory: { createShaderModule: () => ok(shader) },
+    });
+    const feature = createMorphFeature({
+      collect: () => [
+        {
+          identity: 'triangle',
+          vertexCount: 3,
+          baseBounds: { min: [-1, -1, -1], max: [1, 1, 1] },
+          targetBounds: [{ min: [-1, 0, 0], max: [1, 0, 0] }],
+          weights: new Float32Array([0.5]),
+          baseAabbIntersectsFrustum: true,
+          basePositions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+          targetDeltas: new Float32Array([0, 0, 0, 0.1, 0, 0, 0, 0.1, 0]),
+        },
+      ],
+    });
+    const frame = feature.extract({ worlds: [], owner: 0, frameNumber: 1 });
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+
+    resolver.beginFrame();
+    const context = {
+      caps: device.caps,
+      frame: { frameNumber: 1 },
+      resources: [],
+      targets: [],
+      reportError: { report: () => undefined },
+      graphics: createRenderFeatureGraphicsPrepare('forgeax.morph', 0),
+      gpu: resolver,
+    } as const;
+    expect(feature.prepare(frame.value, context).ok).toBe(true);
+    const staging = createRenderFeatureContributionStaging(
+      'forgeax.morph',
+      0,
+      undefined,
+      undefined,
+      (descriptor) => resolver.resolveComputePass('forgeax.morph', descriptor),
+    );
+    expect(feature.contribute(frame.value, { ...context, staging }).ok).toBe(true);
+    const contribution = staging.commit();
+    expect(contribution.ok).toBe(true);
+    if (!contribution.ok) return;
+    expect(contribution.value.passes).toHaveLength(1);
+    expect(contribution.value.passes[0]?.gpuCompute?.program).toBeDefined();
+    expect(contribution.value.passes[0]?.resolvedGpuCompute).toBeDefined();
+    expect(MORPH_COMPUTE_WGSL).toContain('@compute');
+
+    const encoder = device.createCommandEncoder({ label: 'morph-feature' }).unwrap();
+    const work = contribution.value.passes[0]?.resolvedGpuCompute;
+    expect(work).toBeDefined();
+    if (work === undefined) return;
+    const pass = encoder.beginComputePass({ label: 'forgeax.morph.compute' });
+    encodeRenderFeatureGpuComputePass(pass, work);
+    pass.end();
+    expect(encoder.finish().ok).toBe(true);
+    expect(resolver.dispose().ok).toBe(true);
+  });
+});

package/src/__tests__/morph-visual-evidence.integration.test.ts

@@ -0,0 +1,66 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const repoRoot = resolve(fileURLToPath(new URL('../../../../', import.meta.url)));
+const evidencePath = resolve(
+  repoRoot,
+  'apps/hello/format-tier1/evidence/morph-visual-evidence.json',
+);
+
+describe('Morph Dawn evidence contract', () => {
+  it('binds the 300-frame GPU result to the immutable source and readback', async () => {
+    const evidence = JSON.parse(await readFile(evidencePath, 'utf8')) as {
+      schemaVersion?: string;
+      featureId?: string;
+      source?: { csvSha256?: string; firstTierRows?: number[]; sourceCodeSha?: string };
+      environment?: { backend?: string };
+      requiredFrames?: number;
+      framesObserved?: number;
+      phases?: { zero?: number; culled?: number; reentry?: number; staleClears?: number };
+      readback?: { status?: string; path?: string; maxAbsError?: number };
+      screenshot?: { status?: string; path?: string | null; reason?: string };
+      falsifiers?: { zeroWeights?: string; cullReentry?: string; staleWeights?: string };
+      observed?: string;
+      producer?: { status?: string; kind?: string };
+      verdict?: string;
+      confidence?: string;
+      capabilityRefusal?: unknown;
+    };
+
+    expect(evidence.schemaVersion).toBe('morph-visual-evidence/1');
+    expect(evidence.featureId).toBe('feat-20260812-format-classification-tier1');
+    expect(evidence.source?.csvSha256).toBe(
+      'a87159400f5de776ce46304540999c2e7f84cec07defceaa661d0a0926a9c2d5',
+    );
+    expect(evidence.source?.firstTierRows).toEqual([8, 18, 26]);
+    expect(evidence.source?.sourceCodeSha).toMatch(/^[a-f0-9]{40,64}$/);
+    expect(evidence.environment?.backend).toBe('dawn');
+    expect(evidence.requiredFrames).toBe(300);
+    expect(evidence.framesObserved).toBe(300);
+    expect(evidence.phases).toEqual({ zero: 100, culled: 100, reentry: 1, staleClears: 1 });
+    expect(evidence.readback?.status).toBe('pass');
+    expect(evidence.readback?.path).toContain('MAP_READ');
+    expect(evidence.readback?.maxAbsError).toBeLessThanOrEqual(0.001);
+    expect(evidence.screenshot?.status).toBe('captured');
+    if (typeof evidence.screenshot?.path === 'string') {
+      expect(evidence.screenshot.path).toContain('format-tier1-morph-static-animation-output.png');
+    } else {
+      expect(evidence.screenshot?.path).toBeNull();
+      expect(evidence.screenshot?.reason).toEqual(expect.any(String));
+    }
+    expect(evidence.falsifiers).toEqual({
+      zeroWeights: 'pass',
+      cullReentry: 'pass',
+      staleWeights: 'pass',
+    });
+    expect(evidence.observed).toEqual(expect.any(String));
+    expect(evidence.producer).toMatchObject({ status: 'pass', kind: 'imported-typed-load' });
+    expect(evidence.verdict).toBe('pass');
+    expect(evidence.confidence).toBe('high');
+    expect(evidence.capabilityRefusal).toMatchObject({
+      code: 'format-tier1-browser-gpu-consumer-blocked',
+    });
+  });
+});

package/src/__tests__/nineslice-handle-surface.unit.test.ts

@@ -0,0 +1,14 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'vitest';
+
+const frameSource = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
+
+describe('World-owned mesh handle surface', () => {
+  it('records the extracted handle without a global primitive remap', () => {
+    expect(frameSource).toContain('resolveRenderAsset<MeshAsset>');
+    expect(frameSource).toContain('mesh: meshHandles');
+    expect(frameSource).toContain('priorWorld !== entry.source.worldId');
+    expect(frameSource).toContain('residentMeshes.delete(handle)');
+  });
+});

package/src/__tests__/param-schema-projection-census.unit.test.ts

@@ -0,0 +1,40 @@
+import { type ParamSchemaEntry, ParamSchemaProjectionOwner } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createEngineMetrics } from '../engine-metrics';
+import {
+  createParamSchemaProjectionCensus,
+  deriveParamSchemaForCensus,
+} from '../param-schema-projection-census';
+
+describe('ParamSchema compatibility census', () => {
+  it('distinguishes admitted identity reads from unregistered fallback derivation', () => {
+    const metrics = createEngineMetrics();
+    const census = createParamSchemaProjectionCensus(metrics, true);
+    const schema: readonly ParamSchemaEntry[] = [{ name: 'roughness', type: 'f32' }];
+
+    deriveParamSchemaForCensus(schema, census, 'entity-extract');
+    const owner = new ParamSchemaProjectionOwner();
+    const admitted = owner.admit({ ownerId: 'test-shader', revision: 1, schema });
+    deriveParamSchemaForCensus(admitted.schema, census, 'submesh');
+    census.record('empty-schema-legacy-inference', 'prepared-material');
+
+    expect(metrics.snapshot()).toMatchObject({
+      'paramschema.unregistered-fallback-derive': 1,
+      'paramschema.unregistered-fallback-derive.entity-extract': 1,
+      'paramschema.fallback-layout-sha': 1,
+      'paramschema.fallback-layout-sha.entity-extract': 1,
+      'paramschema.admitted-identity-hit': 1,
+      'paramschema.admitted-identity-hit.submesh': 1,
+      'paramschema.empty-schema-legacy-inference': 1,
+      'paramschema.empty-schema-legacy-inference.prepared-material': 1,
+    });
+  });
+
+  it('does no metric work when debug observation is disabled', () => {
+    const metrics = createEngineMetrics();
+    const census = createParamSchemaProjectionCensus(metrics, false);
+    deriveParamSchemaForCensus([{ name: 'roughness', type: 'f32' }], census, 'entity-extract');
+    census.record('registered-projection-read', 'record-payload');
+    expect(metrics.snapshot()).toEqual({});
+  });
+});