@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/particle-material-input-layout.unit.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import { particleMaterialInputVertexBuffers } from '../assembly/factory';
+import { RENDER_FEATURE_VERTEX_LAYOUTS } from '../features/prepared-graphics';
+import { createPreparedGraphicsStore } from '../features/prepared-graphics-store';
+import { buildPipelineDescriptor, cacheKeyOf } from '../pipeline-spec';
+
+const layouts = [
+  {
+    name: RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInputInstance,
+    baseStride: 31 * 4,
+    firstLocation: 9,
+  },
+  {
+    name: RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentMaterialInputInstance,
+    baseStride: 12 * 4,
+    firstLocation: 4,
+  },
+  {
+    name: RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInputInstance,
+    baseStride: 18 * 4,
+    firstLocation: 10,
+  },
+];
+
+describe('particle material input layout', () => {
+  it.each(layouts)('derives the canonical ABI and cache identity for $name', (layout) => {
+    const keys = new Set<string>();
+    for (const lanes of [1, 2, 3, 4]) {
+      const buffers = particleMaterialInputVertexBuffers(layout.name, lanes);
+      if (buffers === undefined) throw new Error('Missing input layout');
+      const instance = buffers.at(-1);
+      if (instance === undefined) throw new Error('Missing instance stream');
+      expect(instance.arrayStride).toBe(layout.baseStride + lanes * 16);
+      const inputAttributes = [...instance.attributes].slice(-lanes);
+      expect(inputAttributes).toEqual(
+        Array.from({ length: lanes }, (_, lane) => ({
+          shaderLocation: layout.firstLocation + lane,
+          offset: layout.baseStride + lane * 16,
+          format: 'float32x4',
+        })),
+      );
+      keys.add(
+        cacheKeyOf({
+          shader: { id: 'test::same-shader', passKind: 'forward', variantSet: undefined },
+          attachments: { colorFormats: ['rgba8unorm'], depthFormat: undefined, sampleCount: 1 },
+          geometry: { topology: 'triangle-list', vertexLayout: {}, vertexBuffers: buffers },
+          renderState: undefined,
+        }),
+      );
+      const descriptor = buildPipelineDescriptor(
+        {
+          shader: { id: 'test::same-shader', passKind: 'forward', variantSet: undefined },
+          attachments: { colorFormats: ['rgba8unorm'], depthFormat: undefined, sampleCount: 1 },
+          geometry: { topology: 'triangle-list', vertexLayout: {}, vertexBuffers: buffers },
+          renderState: undefined,
+        },
+        { vertex: 'vertex-module', fragment: 'fragment-module' },
+      );
+      expect((descriptor.vertex as { buffers: readonly unknown[] }).buffers).toEqual(buffers);
+    }
+    expect(keys.size).toBe(4);
+  });
+
+  it.each([
+    0,
+    -1,
+    5,
+    1.5,
+    Number.NaN,
+  ])('rejects invalid lane count %s before pipeline resolution', (particleInputLanes) => {
+    const transaction = createPreparedGraphicsStore().beginFrame('test', 1);
+    expect(
+      transaction.prepare('pipeline', 'material', {
+        shader: 'test::shader',
+        vertexLayout: RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInputInstance,
+        particleInputLanes,
+        colorFormats: ['rgba8unorm'],
+      }),
+    ).toMatchObject({ ok: false, error: { code: 'render-feature-preparation-failed' } });
+  });
+
+  it('rejects an omitted lane count for material-input layouts', () => {
+    const transaction = createPreparedGraphicsStore().beginFrame('test', 1);
+    expect(
+      transaction.prepare('pipeline', 'material', {
+        shader: 'test::shader',
+        vertexLayout: RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInputInstance,
+        colorFormats: ['rgba8unorm'],
+      }),
+    ).toMatchObject({ ok: false, error: { code: 'render-feature-preparation-failed' } });
+  });
+
+  it('rejects lanes on ordinary vertex layouts', () => {
+    const transaction = createPreparedGraphicsStore().beginFrame('test', 1);
+    expect(
+      transaction.prepare('pipeline', 'material', {
+        shader: 'test::shader',
+        vertexLayout: 'position',
+        particleInputLanes: 1,
+        colorFormats: ['rgba8unorm'],
+      }),
+    ).toMatchObject({ ok: false, error: { code: 'render-feature-preparation-failed' } });
+  });
+});

package/src/__tests__/physical-clearcoat.integration.test.ts

@@ -1,5 +1,6 @@
 import { STANDARD_PIPELINE_PARAM_SCHEMA } from '@forgeax/engine-shader';
 import { describe, expect, it } from 'vitest';
+import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from '../gpu-stage.js';
 import { Materials } from '../materials.js';
 import {
   buildBindGroupLayoutDescriptor,
@@ -74,9 +75,10 @@ describe('Standard clearcoat root contract', () => {
 
     // The canonical seven texture pairs occupy bindings 1..14. IBL remains
     // at 15..21 and transmission at 22..23; authored physical maps append at
-    // 24..27. Compacting the authored root here shifts WGSL IBL bindings and
+    // their canonical fixed slots (26, 27, 30, 31), followed by the
+    // scene-index row at binding 46. Compacting the authored root here shifts WGSL IBL bindings and
     // causes Dawn to reject the pipeline before any pixels are submitted.
-    expect(descriptor.entries).toHaveLength(28);
+    expect(descriptor.entries).toHaveLength(29);
     expect(descriptor.entries.slice(0, 15).map((entry) => entry.binding)).toEqual(
       Array.from({ length: 15 }, (_, binding) => binding),
     );
@@ -84,6 +86,38 @@ describe('Standard clearcoat root contract', () => {
     expect(descriptor.entries[17]?.texture).toMatchObject({ viewDimension: 'cube' });
     expect(descriptor.entries[22]?.sampler).toMatchObject({ type: 'filtering' });
     expect(descriptor.entries[23]?.texture).toMatchObject({ viewDimension: '2d' });
-    expect(descriptor.entries.slice(24).map((entry) => entry.binding)).toEqual([24, 25, 26, 27]);
+    expect(descriptor.entries.slice(24, 28).map((entry) => entry.binding)).toEqual([
+      26, 27, 30, 31,
+    ]);
+    expect(descriptor.entries[28]).toMatchObject({
+      binding: 46,
+      visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+      buffer: { type: 'read-only-storage', hasDynamicOffset: false },
+    });
+  });
+
+  it('reserves the dynamic material UBO for an empty authored schema', () => {
+    const descriptor = buildBindGroupLayoutDescriptor(
+      {
+        shader: { id: 'game::custom', passKind: 'forward', variantSet: undefined },
+        attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
+        geometry: { topology: 'triangle-list', vertexLayout: {} },
+        renderState: undefined,
+      },
+      { kind: 'pbr-material-merged', materialParamSchema: [] },
+    );
+
+    expect(descriptor.entries[0]).toMatchObject({
+      binding: 0,
+      visibility: 3,
+      buffer: { type: 'uniform', hasDynamicOffset: true },
+    });
+    expect(descriptor.entries[1]?.texture).toMatchObject({ viewDimension: 'cube' });
+    // PBR layouts keep the producer-owned scene-material row at binding 46,
+    // even when an authored schema has no numeric parameters.
+    expect(descriptor.entries.map((entry) => entry.binding)).toEqual([
+      ...Array.from({ length: 10 }, (_, binding) => binding),
+      46,
+    ]);
   });
 });

package/src/__tests__/pipeline-texture-specialization.unit.test.ts

@@ -0,0 +1,138 @@
+import { AssetRegistry, HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  standardTextureMask,
+} from '../../../shader/src/material-schemas';
+import { MeshFilter, MeshRenderer } from '../components';
+import { Materials } from '../materials';
+import { buildPipelineDescriptor, cacheKeyOf, type PipelineSpec } from '../pipeline-spec';
+import {
+  extractFrame,
+  prepareExtractContext,
+  resolveMaterialSnapshot,
+} from '../render-system-extract';
+
+function spec(constants?: Readonly<Record<string, number>>): PipelineSpec {
+  return {
+    shader: {
+      id: 'standard',
+      passKind: 'forward',
+      variantSet: undefined,
+      fragmentConstants: constants,
+    },
+    attachments: { colorFormats: ['rgba16float'], depthFormat: undefined, sampleCount: 1 },
+    geometry: { topology: 'triangle-list', vertexLayout: {} },
+    renderState: undefined,
+  };
+}
+
+describe('material pipeline texture specialization', () => {
+  it('preserves authored texture presence separately from the canonical UBO layout', async () => {
+    const assets = new AssetRegistry(
+      new ShaderRegistry({
+        device: {
+          createShaderModule() {
+            throw new Error('Material extraction must not compile shaders');
+          },
+        },
+        manifestUrl: undefined,
+      }),
+    );
+    const world = new World();
+    const plain = world.allocSharedRef(
+      'MaterialAsset',
+      Materials.standard({ baseColor: [1, 1, 1, 1] }),
+    );
+    const mapped = world.allocSharedRef(
+      'MaterialAsset',
+      Materials.standard({
+        baseColor: [1, 1, 1, 1],
+        normalTexture: { texture: '11111111-1111-1111-1111-111111111111' },
+      }),
+    );
+    // A directly allocated canonical material may omit parameter declarations.
+    // The canonical shader still binds these values, so pruning must retain them.
+    const direct = world.allocSharedRef('MaterialAsset', {
+      kind: 'material',
+      passes: [{ name: 'Forward', program: { module: 'forgeax::default-standard-pbr' } }],
+      values: { baseColorTexture: 1, metallicRoughnessTexture: 2 },
+    });
+    const a = resolveMaterialSnapshot(plain, world, assets);
+    const b = resolveMaterialSnapshot(mapped, world, assets);
+    expect(a.materialParamSchema).toEqual(b.materialParamSchema);
+    expect(a.standardTextureMask).toBe(0);
+    expect(b.standardTextureMask).toBe(4);
+    expect(b.normalTexture).toBeUndefined();
+    expect(resolveMaterialSnapshot(direct, world, assets).standardTextureMask).toBe(3);
+    registerPropagateTransforms(world);
+    for (const material of [plain, mapped, direct]) {
+      world
+        .spawn(
+          { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+          { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+          { component: MeshRenderer, data: { materials: [material] } },
+        )
+        .unwrap();
+    }
+    world.update(0).unwrap();
+    const frame = extractFrame(world, prepareExtractContext(world, { assets, cull: 'none' }));
+    expect(frame.renderables.map((item) => item.material.standardTextureMask)).toEqual([0, 4, 3]);
+  });
+  it('derives each of the 17 map bits from declarations, independent of resource readiness', () => {
+    const textures = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter(
+      (entry) => entry.type === 'texture2d',
+    );
+    expect(textures).toHaveLength(17);
+    expect(standardTextureMask([])).toBe(0);
+    expect(standardTextureMask(DEFAULT_STANDARD_PBR_PARAM_SCHEMA)).toBe(2 ** textures.length - 1);
+    for (const [index, texture] of textures.entries()) {
+      expect(standardTextureMask([texture])).toBe(2 ** index);
+    }
+  });
+  it('separates absent, enabled and default texture specializations in the PSO cache', () => {
+    expect(new Set([spec(), spec({ '64000': 0 }), spec({ '64000': 1 })].map(cacheKeyOf)).size).toBe(
+      3,
+    );
+    expect(cacheKeyOf(spec({ '64001': 2, '64000': 1 }))).toBe(
+      cacheKeyOf(spec({ '64000': 1, '64001': 2 })),
+    );
+  });
+
+  it('forwards specialization values to the fragment stage without changing the module', () => {
+    const module = {};
+    const descriptor = buildPipelineDescriptor(spec({ '64000': 0 }), {
+      vertex: module,
+      fragment: module,
+    });
+    expect(descriptor.fragment).toMatchObject({ module, constants: { '64000': 0 } });
+    expect(descriptor.vertex).not.toHaveProperty('constants');
+  });
+
+  it('keeps authored entry points and texture overrides orthogonal in descriptors and cache keys', () => {
+    const base = spec({ '64000': 0 });
+    const authored: PipelineSpec = {
+      ...base,
+      shader: { ...base.shader, vertexEntry: 'custom_vs', fragmentEntry: 'custom_fs' },
+    };
+    const mapped: PipelineSpec = {
+      ...authored,
+      shader: { ...authored.shader, fragmentConstants: { '64000': 4 } },
+    };
+    expect(new Set([base, authored, mapped].map(cacheKeyOf)).size).toBe(3);
+    const module = {};
+    const descriptor = buildPipelineDescriptor(authored, {
+      vertex: module,
+      fragment: module,
+      fragmentEntryPoint: 'fs_main_hdr',
+    });
+    expect(descriptor.vertex).toMatchObject({ entryPoint: 'custom_vs' });
+    expect(descriptor.fragment).toMatchObject({
+      entryPoint: 'custom_fs',
+      constants: { '64000': 0 },
+    });
+  });
+});

package/src/__tests__/point-shadow-inspection.unit.test.ts

@@ -11,6 +11,8 @@ function snapshots(...layers: number[]): PointShadowSnapshot[] {
     mapSize: 512,
     nearPlane: 0.1,
     farPlane: 25,
+    depthBias: 0.005,
+    normalBias: 0.05,
     shadowAtlasLayer,
     shadowMatrices: new Float32Array(96),
   }));

package/src/__tests__/prepared-gpu-driven-pbr-contract.test-d.ts

@@ -0,0 +1,31 @@
+import { expectTypeOf } from 'vitest';
+import type { GpuDrivenPreparationError } from '../errors/gpu-driven.js';
+import type { PreparedGpuDrivenDraw } from '../gpu-driven/prepared-draw.js';
+import type { GpuDrivenPreparationFailureInspection } from '../inspection-types.js';
+
+declare const prepared: PreparedGpuDrivenDraw;
+expectTypeOf(prepared.identity).toMatchTypeOf<{
+  readonly material: string;
+  readonly geometry: string;
+  readonly deformation: 'rigid' | 'skin';
+}>();
+expectTypeOf(prepared.receiptGeneration).toEqualTypeOf<number>();
+expectTypeOf(prepared.resourceSlots).toMatchTypeOf<readonly object[]>();
+
+declare const failure: GpuDrivenPreparationError;
+expectTypeOf(failure.code).toMatchTypeOf<string>();
+expectTypeOf(failure.expected).toEqualTypeOf<string>();
+expectTypeOf(failure.hint).toEqualTypeOf<string>();
+expectTypeOf(failure.detail.reason).toMatchTypeOf<string>();
+expectTypeOf(failure.detail.recovery).toMatchTypeOf<string | undefined>();
+
+declare const inspectionFailure: GpuDrivenPreparationFailureInspection;
+expectTypeOf(inspectionFailure.code).toEqualTypeOf(failure.code);
+expectTypeOf(inspectionFailure.expected).toEqualTypeOf<string>();
+expectTypeOf(inspectionFailure.detail.owner).toMatchTypeOf<
+  'material' | 'geometry' | 'skin' | 'generation' | 'shadow'
+>();
+
+void prepared;
+void failure;
+void inspectionFailure;

package/src/__tests__/prepared-gpu-driven-pbr-contract.unit.test.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const extractSource = readFileSync(
+  fileURLToPath(new URL('../extract/gpu-driven.ts', import.meta.url)),
+  'utf8',
+);
+const shaderArtifactSource = readFileSync(
+  fileURLToPath(new URL('../../../shader/src/material/artifact-types.ts', import.meta.url)),
+  'utf8',
+);
+
+describe('prepared GPU-driven Standard PBR contract', () => {
+  it('requires one receipt to expose direct and scene-index entries', () => {
+    expect(shaderArtifactSource).toContain('direct');
+    expect(shaderArtifactSource).toContain('sceneIndex');
+    expect(shaderArtifactSource).toContain('materialRow');
+    expect(shaderArtifactSource).toContain('resourceSlots');
+  });
+
+  it('keeps the ABI facts explicit instead of inferring them from shader names', () => {
+    for (const field of ['uvSets', 'vertexInputs', 'alphaMask', 'reflection', 'generation']) {
+      expect(shaderArtifactSource, `artifact must expose ${field}`).toContain(field);
+    }
+    expect(extractSource).toContain('PreparedGpuDrivenDraw');
+    expect(extractSource).toContain('GpuDrivenPreparationError');
+  });
+
+  it.each([
+    ['missing UV', 'uv'],
+    ['reflection mismatch', 'reflection'],
+    ['vertex semantic mismatch', 'vertex'],
+    ['missing alpha mask subset', 'alpha'],
+    ['stale generation', 'generation'],
+  ])('has a named rejection path for %s', (_label, token) => {
+    expect(extractSource.toLowerCase()).toContain(token);
+  });
+});

package/src/__tests__/prepared-gpu-driven-pbr.integration.test.ts

@@ -27,6 +27,7 @@ function material(): MaterialSnapshot {
 }
 
 function snapshot(
+  materialSnapshot: MaterialSnapshot = material(),
   draws?: readonly NonNullable<RenderableSnapshot['gpuDrivenDraws']>[number][],
 ): RenderableSnapshot {
   const draw = {
@@ -42,8 +43,8 @@ function snapshot(
   return {
     assetHandle: 1,
     transform: { world: new Float32Array(16) },
-    material: material(),
-    materials: [material()],
+    material: materialSnapshot,
+    materials: [materialSnapshot],
     materialBindingSources: [],
     worldId: 0,
     entityKey: 1,
@@ -105,8 +106,18 @@ describe('prepared Standard PBR producer-to-record integration', () => {
       _label === 'missing resources'
         ? {
             ...baseSnapshot,
-            material: { ...baseSnapshot.material, textureHandles: undefined },
-            materials: [{ ...baseSnapshot.material, textureHandles: undefined }],
+            material: {
+              ...baseSnapshot.material,
+              textureHandles: undefined,
+              authoredTextureFields: new Set(['baseColorTexture']),
+            },
+            materials: [
+              {
+                ...baseSnapshot.material,
+                textureHandles: undefined,
+                authoredTextureFields: new Set(['baseColorTexture']),
+              },
+            ],
           }
         : baseSnapshot;
     const result = resolvePreparedGpuDrivenDraw({
@@ -193,4 +204,24 @@ describe('prepared Standard PBR producer-to-record integration', () => {
     expect(result.error.code).toBe('missing-material-receipt');
     expect(base.gpuDrivenDraws).toHaveLength(1);
   });
+
+  it('admits numeric-only Standard PBR without optional texture resources', () => {
+    const source = artifact();
+    const numericMaterial: MaterialSnapshot = {
+      ...material(),
+      textureHandles: undefined,
+      samplerHandles: undefined,
+    };
+    const baseSnapshot = snapshot(numericMaterial);
+    const result = resolvePreparedGpuDrivenDraw({
+      snapshot: baseSnapshot,
+      artifact: source,
+      geometry: geometry(source),
+      generation: source.receipt.generation,
+      draw: baseSnapshot.gpuDrivenDraws?.[0] as NonNullable<
+        RenderableSnapshot['gpuDrivenDraws']
+      >[number],
+    });
+    expect(result.ok).toBe(true);
+  });
 });

package/src/__tests__/prepared-graphics-capability.unit.test.ts

@@ -3,6 +3,7 @@ import { ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
 import type { RenderFeature } from '../features/types';
+import { admitStandardColorLut } from '../pipeline/standard-output/lut-admission';
 
 const supportedCaps: Readonly<RhiCaps> = {
   backendKind: 'null',
@@ -25,6 +26,26 @@ function preparedFeature(): RenderFeature<{ readonly draw: boolean }> {
 }
 
 describe('prepared graphics capability projection', () => {
+  it('keeps LUT filtering as an independent live capability', () => {
+    const result = admitStandardColorLut({
+      texture: {
+        kind: 'texture',
+        shape: { viewDimension: '3d', extent: { width: 16, height: 16, depth: 16 } },
+        format: 'rgba16float',
+        data: new Uint8Array(16 * 16 * 16 * 8),
+        colorSpace: 'linear',
+        mips: { kind: 'none' },
+      },
+      maxTextureDimension3D: 2048,
+      rgba16floatFilterable: false,
+      bind: () => true,
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('standard-lut-filter-unavailable');
+  });
+
   it('projects supported capability into an accepted machine-readable operation', () => {
     const host = createRenderFeatureHost([preparedFeature()]).unwrap();
     const result = runRenderFeatureFrame(host, {

package/src/__tests__/prepared-graphics-pipeline-warmup.unit.test.ts

@@ -2,6 +2,10 @@ import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 
 const ownerSource = readFileSync(new URL('../render-system.ts', import.meta.url), 'utf8');
+const resolverSource = readFileSync(
+  new URL('../record/prepared-material-bindings.ts', import.meta.url),
+  'utf8',
+);
 
 describe('prepared graphics material pipeline warmup', () => {
   it('does not substitute an unrelated unlit pipeline while the authored shader warms', () => {
@@ -15,7 +19,7 @@ describe('prepared graphics material pipeline warmup', () => {
   });
 
   it('keeps view-only material bindings on the canonical view group with depth', () => {
-    const declaration = ownerSource.indexOf('preparedViewOnlyPipelines: new WeakSet()');
+    const declaration = resolverSource.indexOf('preparedViewOnlyPipelines: new WeakSet()');
     const classification = ownerSource.indexOf('preparedViewOnlyPipelines.add', declaration);
     const bindingResolution = ownerSource.indexOf(
       'preparedViewOnlyPipelines.has(pipeline as object)',
@@ -23,7 +27,7 @@ describe('prepared graphics material pipeline warmup', () => {
     );
 
     expect(declaration).toBeGreaterThan(-1);
-    expect(classification).toBeGreaterThan(declaration);
+    expect(classification).toBeGreaterThan(-1);
     expect(bindingResolution).toBeGreaterThan(classification);
   });
 });

package/src/__tests__/profiler-phase-catalog.test.ts

@@ -27,6 +27,11 @@ describe('Render profiler phase catalog ownership', () => {
         'record/graph-execute/forward/pipeline-selection',
         'record/graph-execute/forward/draw-submit',
         'record/graph-execute/forward/geometry-loop',
+        'record/graph-execute/ssr-hiz',
+        'record/graph-execute/ssr-trace',
+        'record/graph-execute/ssr-temporal',
+        'record/graph-execute/ssr-reflection-mip',
+        'record/graph-execute/ssr-compose',
       ]),
     );
     expect(RENDER_PHASE_CATALOG).toEqual(expect.arrayContaining(['occlusion-prepare']));

package/src/__tests__/public-surface.test-d.ts

@@ -9,6 +9,7 @@ import type {
   RenderInspection,
   RenderIntentInvalidDetail,
   RenderWorldLease,
+  SsrSpatialInspection,
 } from '@forgeax/engine-render';
 import {
   ANTIALIAS_TAA,
@@ -60,6 +61,8 @@ declare const inspection: RenderInspection;
 const reflectionInspection: ReflectionProbeInspection = inspection.reflectionProbes;
 const reflectionSelection: ReflectionProbeSelectionInspection = reflectionInspection.selection;
 void reflectionSelection;
+const ssrInspection: SsrSpatialInspection = inspection.ssr;
+void ssrInspection;
 type IntentError = Extract<PublicRenderError, { readonly code: 'render-intent-invalid' }>;
 expectTypeOf<IntentError['detail']>().toEqualTypeOf<RenderIntentInvalidDetail>();
 const backendKind: RenderInspection['capabilities']['backendKind'] =

package/src/__tests__/recovery-candidate-prepare.contract.test.ts

@@ -6,6 +6,10 @@ const renderSystemSource = readFileSync(
   resolve(import.meta.dirname, '../render-system.ts'),
   'utf8',
 );
+const recoveryRootsSource = readFileSync(
+  resolve(import.meta.dirname, '../recovery/render-system-roots.ts'),
+  'utf8',
+);
 const recoveryCandidateSource = readFileSync(
   resolve(import.meta.dirname, '../recovery/render-system-candidate.ts'),
   'utf8',
@@ -20,6 +24,28 @@ const rendererRecoverySource = readFileSync(
 );
 
 describe('recovery candidate preparation contract', () => {
+  it('does not restore the lost device SSR history when publishing a detached candidate', () => {
+    const start = recoveryCandidateSource.indexOf('const createRecoveryCandidateFrameState');
+    const end = recoveryCandidateSource.indexOf('const publishRecoveryGraphCandidate', start);
+    const candidate = recoveryCandidateSource.slice(start, end);
+    for (const field of [
+      'ssrHistoryOwner',
+      'ssrHistoryCandidate',
+      'ssrSpatialAdmission',
+      'ssrTemporalParamsPayload',
+    ]) {
+      expect(candidate).toContain(`${field}: undefined`);
+    }
+    // Initial readiness and recovery await the same pipeline preparation owner.
+    expect(rendererSource).toContain('await renderSystem.initializeSsr(device)');
+    expect(rendererSource).not.toContain('initializeSsr(internals.device)');
+    expect(rendererRecoverySource).toContain(
+      'await buildPipeline(recoveryScope, device, candidateGpuStore)',
+    );
+    expect(rendererRecoverySource).not.toContain('initializeSsr(');
+    expect(renderSystemSource).toContain('format: ssrFormatReceipts.get(internals.device)');
+  });
+
   it('keeps graph preparation outside draw, record, execute, and submit', () => {
     const start = recoveryCandidateSource.indexOf('const prepareRecoveryGraphCandidate');
     const end = recoveryCandidateSource.indexOf('const submitCandidateSetup', start);
@@ -57,9 +83,8 @@ describe('recovery candidate preparation contract', () => {
   });
 
   it('prepares roots from candidate state and switches environment owner only at publish', () => {
-    const start = renderSystemSource.indexOf('prepareRecoveryRoots(runtime: RecoveryRootRuntime)');
-    const end = renderSystemSource.indexOf('\n    },\n  };', start);
-    const roots = renderSystemSource.slice(start, end);
+    const start = recoveryRootsSource.indexOf('export function prepareRenderSystemRecoveryRoots');
+    const roots = recoveryRootsSource.slice(start);
 
     expect(roots).toContain('runtime.scope');
     expect(roots).toContain('createRecoveryCandidate');
@@ -96,17 +121,10 @@ describe('recovery candidate preparation contract', () => {
     expect(setup).not.toContain('recordFrame');
   });
 
-  it('arms the first published frame only after candidate pipeline preparation', () => {
-    expect(recoveryCandidateSource).toContain(
-      'candidate.recoveryReadiness.assertFirstRecoveryFrame()',
-    );
+  it('checks the candidate cache before publication', () => {
+    expect(recoveryCandidateSource).toContain('candidate.recoveryReadiness.assertPreparedCache()');
     expect(recoveryCandidateSource).toContain('pointsLinesOwner.prepareRecoveryCandidate');
     expect(renderSystemSource).toContain('pointsLinesOwner.abandonForDeviceLoss');
-    expect(rendererSource).toContain(
-      'candidate.producerBindings.gpuStore.setRecoveryColdWorkGuard',
-    );
-    expect(rendererSource).toContain('recoveryColdWorkGuard.arm()');
-    expect(renderSystemSource).toContain('internals.recoveryColdWorkGuard?.notePipelineColdWork()');
     expect(recoveryCandidateSource).toContain('const previousFeatureHost = internals.featureHost');
     expect(recoveryCandidateSource).toContain('const disposed = previousFeatureHost.dispose()');
     expect(recoveryCandidateSource).toContain('previousFeatureHost !== candidate.featureHost');