@forgeax/engine-render 0.1.28 → 0.1.30

package/src/post-process-errors.ts

@@ -3,7 +3,7 @@
 //  feat-20260609-learn-render-4-5-framebuffers-demo-offscreen-rt-an M1 / T-2
 //  added 'fullscreen-input-not-found').
 //
-// Closed 7-member PostProcessErrorCode union + PostProcessError discriminated-union class.
+// Closed PostProcessErrorCode union + PostProcessError discriminated-union class.
 //   - 'post-process-already-registered' (programmer error) -> fullscreen effect registration THROWS a
 //     PostProcessError, mirroring ShaderCatalog.installMaterialArtifact's Map.has -> throw
 //     fail-fast (research Finding M2-4). A second register under the same id is a coding
@@ -38,7 +38,7 @@
 /**
  * Closed union of fullscreen post-process error codes.
  *
- * Exactly 7 members; AI users perform exhaustive `switch (err.code)` without a default
+ * AI users perform exhaustive `switch (err.code)` without a default
  * and TS guards completeness (AC-08).
  *
  * | code | channel | trigger |
@@ -134,21 +134,23 @@ export interface PostProcessParamsUpdateSizeMismatchDetail {
  * `detail` parameter to the variant payload at compile time.
  */
 export type PostProcessErrorDetailFor<C extends PostProcessErrorCode> =
-  C extends 'post-process-already-registered'
-    ? PostProcessPreviouslyRegisteredDetail
-    : C extends 'post-process-not-found'
-      ? PostProcessNotFoundDetail
-      : C extends 'fullscreen-input-not-found'
-        ? FullscreenInputNotFoundDetail
-        : C extends 'ssao-radius-non-positive'
-          ? SsaoRadiusNonPositiveDetail
-          : C extends 'ssao-bias-negative'
-            ? SsaoBiasNegativeDetail
-            : C extends 'params-size-mismatch'
-              ? PostProcessParamsSizeMismatchDetail
-              : C extends 'params-update-size-mismatch'
-                ? PostProcessParamsUpdateSizeMismatchDetail
-                : never;
+  C extends 'ssao-parameter-invalid'
+    ? { readonly paramName: string; readonly value: unknown }
+    : C extends 'post-process-already-registered'
+      ? PostProcessPreviouslyRegisteredDetail
+      : C extends 'post-process-not-found'
+        ? PostProcessNotFoundDetail
+        : C extends 'fullscreen-input-not-found'
+          ? FullscreenInputNotFoundDetail
+          : C extends 'ssao-radius-non-positive'
+            ? SsaoRadiusNonPositiveDetail
+            : C extends 'ssao-bias-negative'
+              ? SsaoBiasNegativeDetail
+              : C extends 'params-size-mismatch'
+                ? PostProcessParamsSizeMismatchDetail
+                : C extends 'params-update-size-mismatch'
+                  ? PostProcessParamsUpdateSizeMismatchDetail
+                  : never;
 
 /**
  * Tagged union of `.detail` payloads. The variants are unique by structural fields
@@ -170,7 +172,8 @@ const POST_PROCESS_POLICY = {
     expected: 'typed fullscreen plan references a registered post-process id',
     hint: (detail) =>
       `no post-process is registered for id '${(detail as PostProcessNotFoundDetail).id}'. ` +
-      `Register '${(detail as PostProcessNotFoundDetail).id}' with the feature host ({source, reads?}), ` +
+      'For Engine-owned effects, rebuild the shader manifest with that Engine entry enabled. ' +
+      `For custom effects, register '${(detail as PostProcessNotFoundDetail).id}' with the feature host ({source, reads?}), ` +
       'then reference it from a typed fullscreen RenderFeaturePlan.',
   },
   'fullscreen-input-not-found': {
@@ -187,6 +190,11 @@ const POST_PROCESS_POLICY = {
       );
     },
   },
+  'ssao-parameter-invalid': {
+    expected: 'finite non-negative SSAO intensity and low, medium, or high quality',
+    hint: () =>
+      'Set ssao.intensity to a finite non-negative value and ssao.quality to low, medium, or high.',
+  },
   'ssao-radius-non-positive': {
     expected: 'SSAO radius must be > 0',
     hint: (detail) => {

package/src/prepare/__tests__/extended-lighting-capability.unit.test.ts

@@ -12,7 +12,7 @@ const device = {
     samplerAliasing: true,
   } as RhiCaps,
   limits: {
-    maxSampledTexturesPerShaderStage: 20,
+    maxSampledTexturesPerShaderStage: 21,
     maxTextureDimension2D: 4096,
     maxTextureArrayLayers: 32,
     maxUniformBuffersPerShaderStage: 12,
@@ -50,7 +50,7 @@ describe('extended lighting capability admission', () => {
     expect(deriveExtendedLightingCapability(limited)).toEqual({
       admitted: false,
       topology: 'extendedLighting',
-      reason: 'maxSampledTexturesPerShaderStage 16 < 20',
+      reason: 'maxSampledTexturesPerShaderStage 16 < 21',
     });
   });
 });

package/src/prepare/extended-lighting/resources.ts

@@ -19,13 +19,13 @@ export const COOKIE_SLICE_SIZE = 256;
 export const COOKIE_MATRIX_BYTES = 32 * 16 * Float32Array.BYTES_PER_ELEMENT;
 /**
  * Minimum per-stage sampled-texture limit for the shared PBR + extended-
- * lighting pipeline-layout topology. The current BGL closure reserves 18
- * sampled textures for the URP path and 20 for the HDRP/Probe path after the
+ * lighting pipeline-layout topology. The current BGL closure reserves 19
+ * sampled textures for the URP path and 21 for the HDRP/Probe path after the
  * material IBL and transmission injections; WebGPU validates this pipeline-
  * layout count even when a compiled shader variant does not read every
  * optional entry.
  */
-export const EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES = 20;
+export const EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES = 21;
 
 /**
  * Keep shader-variant selection and resource admission on one capability fact.

package/src/prepare/prepared-graphics-resolver.ts

@@ -44,6 +44,8 @@ export type PreparedGraphicsResolvedResource =
       readonly kind: 'pipeline';
       readonly reference: RenderFeaturePreparedRef;
       readonly handle: RenderPipeline;
+      /** Renderer-selected context; never authored by a RenderFeature. */
+      readonly standardLighting?: boolean;
     }
   | {
       readonly kind: 'bindings';
@@ -70,7 +72,10 @@ export interface PreparedGraphicsResolverInput {
   readonly lookup: (reference: RenderFeaturePreparedRef) => PreparedGraphicsItem | undefined;
   readonly resolvePipeline: (
     descriptor: PreparedGraphicsNormalizedDescriptor & { readonly kind: 'pipeline' },
-  ) => Result<RenderPipeline, unknown>;
+  ) => Result<
+    RenderPipeline | { readonly handle: RenderPipeline; readonly standardLighting: boolean },
+    unknown
+  >;
   readonly resolveBindings: (
     descriptor: RenderFeatureBindingsDescriptor,
     pipeline: RenderPipeline,
@@ -304,7 +309,9 @@ export function createPreparedGraphicsResolver(
     const resource: PreparedGraphicsResolvedResource = {
       kind: 'pipeline',
       reference,
-      handle: created.value,
+      ...('handle' in created.value
+        ? { handle: created.value.handle, standardLighting: created.value.standardLighting }
+        : { handle: created.value }),
     };
     resolved.set(reference, resource);
     return ok(resource);

package/src/record/__tests__/main-pass-geometry.unit.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, it } from 'vitest';
+import type { DispatchEntry } from '../../render-system-extract';
 import {
   geometryRenderStateForPass,
   requestsStandardTransmissionVariant,
+  sameOpaqueTemporalDraw,
 } from '../main-pass-geometry';
 
 describe('geometry pass render state', () => {
@@ -70,3 +72,69 @@ describe('Standard transmission variant selection', () => {
     ).toBe(false);
   });
 });
+
+describe('temporal projection of multipass materials', () => {
+  const forward: DispatchEntry = {
+    entityIndex: 0,
+    materialHandle: 1,
+    renderableIndex: 0,
+    passIndex: 0,
+    queue: 2000,
+    layer: 0,
+    tags: { LightMode: 'Forward' },
+    renderState: { cullMode: 'back' },
+    defines: undefined,
+    vertexEntry: 'vs_main',
+    fragmentEntry: 'fs_forward',
+    materialShaderId: 'forgeax::default-standard-pbr',
+    paramSnapshot: undefined,
+  };
+  const deferred = {
+    ...forward,
+    passIndex: 1,
+    tags: { LightMode: 'Deferred' },
+    fragmentEntry: 'fs_gbuffer',
+  };
+  it('projects identical opaque Forward and Deferred geometry only once', () => {
+    expect(sameOpaqueTemporalDraw(forward, deferred)).toBe(true);
+    const surface = {
+      ...forward,
+      materialShaderId: 'generated::surface',
+      tags: {
+        LightMode: 'Forward',
+        SurfaceKind: 'standard',
+        SurfaceModule: 'author::surface',
+      },
+    };
+    expect(
+      sameOpaqueTemporalDraw(surface, {
+        ...surface,
+        tags: { ...surface.tags, LightMode: 'Deferred' },
+      }),
+    ).toBe(true);
+    const fullCustom = { ...forward, materialShaderId: 'custom::full' };
+    expect(sameOpaqueTemporalDraw(fullCustom, fullCustom)).toBe(false);
+  });
+  it('preserves different shader, culling, stencil and blending semantics', () => {
+    expect(sameOpaqueTemporalDraw(forward, { ...deferred, materialShaderId: 'other' })).toBe(false);
+    expect(
+      sameOpaqueTemporalDraw(forward, { ...deferred, renderState: { cullMode: 'front' } }),
+    ).toBe(false);
+    expect(sameOpaqueTemporalDraw(forward, { ...deferred, stencilReference: 1 })).toBe(false);
+    const blended = {
+      ...forward,
+      renderState: {
+        blend: {
+          color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha' },
+          alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+        },
+      },
+    } as const;
+    expect(sameOpaqueTemporalDraw(blended, blended)).toBe(false);
+    const stencil = {
+      ...forward,
+      renderState: { stencil: { passOp: 'increment-clamp' } },
+    } as const;
+    expect(sameOpaqueTemporalDraw(stencil, stencil)).toBe(false);
+  });
+});

package/src/record/__tests__/material-bg-cache.unit.test.ts

@@ -34,6 +34,51 @@ describe('material bind-group assembly cache', () => {
     expect(
       isMaterialBgAssemblyCacheHit(cached, material, materialBgl, newBuffer, skylightResources, 7),
     ).toBe(false);
+    expect(
+      isMaterialBgAssemblyCacheHit(
+        cached,
+        material,
+        materialBgl,
+        oldBuffer,
+        { ...skylightResources, skylightPrefilterView: {} as TextureView },
+        7,
+      ),
+    ).toBe(false);
+    const sceneCached = { ...cached, sceneMaterialBuffer: oldBuffer };
+    expect(
+      isMaterialBgAssemblyCacheHit(
+        sceneCached,
+        material,
+        materialBgl,
+        oldBuffer,
+        skylightResources,
+        7,
+        undefined,
+        oldBuffer,
+      ),
+    ).toBe(true);
+    expect(
+      isMaterialBgAssemblyCacheHit(
+        sceneCached,
+        material,
+        materialBgl,
+        oldBuffer,
+        skylightResources,
+        7,
+        undefined,
+        newBuffer,
+      ),
+    ).toBe(false);
+    expect(
+      isMaterialBgAssemblyCacheHit(
+        sceneCached,
+        material,
+        materialBgl,
+        oldBuffer,
+        skylightResources,
+        7,
+      ),
+    ).toBe(false);
     expect(
       isMaterialBgAssemblyCacheHit(cached, material, materialBgl, oldBuffer, skylightResources, 8),
     ).toBe(false);

package/src/record/__tests__/material-slot-plan.unit.test.ts

@@ -1,10 +1,35 @@
 import { describe, expect, it } from 'vitest';
 import {
+  buildDispatchPlan,
   buildMaterialSlotPlan,
   findRenderablePrefixForSlotCapacity,
   materialSlotCountForPrefix,
 } from '../frame';
 
+function validatedRow(renderableIndex: number) {
+  return {
+    source: {
+      material: { materialShaderId: 'forgeax::default-unlit' },
+      materials: [{ materialShaderId: 'forgeax::default-unlit' }],
+    },
+    mesh: {},
+    renderableIndex,
+    renderState: undefined,
+    stencilReference: undefined,
+  } as never;
+}
+
+function ceilingInternals(slotCount: number) {
+  return {
+    growMeshSsbo: () => ({
+      ok: false as const,
+      code: 'mesh-ssbo-ceiling-reached' as const,
+      degradedToSlotCount: slotCount,
+    }),
+    meshSsboState: { slotCount },
+  } as never;
+}
+
 describe('material slot plan', () => {
   it('interns repeated snapshot identities across renderables', () => {
     const a = {};
@@ -27,6 +52,15 @@ describe('material slot plan', () => {
     });
   });
 
+  it('separates per-object probe/pass bindings while interning the same resource class', () => {
+    const material = {};
+    expect(
+      buildMaterialSlotPlan([[material], [material], [material]], (_, owner) =>
+        owner === 1 ? 'probe:1' : 'probe:0',
+      ),
+    ).toEqual({ slotIndices: [[0], [1], [0]], slots: [material, material], slotOwners: [0, 1] });
+  });
+
   it('does not merge equal-looking snapshots with distinct identities', () => {
     expect(buildMaterialSlotPlan([[{}], [{}]])).toMatchObject({
       slotIndices: [[0], [1]],
@@ -41,4 +75,27 @@ describe('material slot plan', () => {
     expect(findRenderablePrefixForSlotCapacity(indices, 5)).toBe(3);
     expect(materialSlotCountForPrefix(indices, 3)).toBe(5);
   });
+
+  it('keeps retained shadow rows inside the ceiling when the primary view is empty', () => {
+    const shadowRows = [validatedRow(0), validatedRow(1), validatedRow(2)];
+    const plan = buildDispatchPlan(ceilingInternals(2), [], [], [], shadowRows);
+
+    expect(plan.validatedOrdered).toHaveLength(0);
+    expect(plan.shadowValidatedOrdered).toEqual(shadowRows.slice(0, 2));
+    expect(plan.validatedOrdered.length + plan.shadowValidatedOrdered.length).toBeLessThanOrEqual(
+      2,
+    );
+  });
+
+  it('reserves the primary rows before retained shadow rows on a mixed ceiling', () => {
+    const primaryRows = [validatedRow(0), validatedRow(1)];
+    const shadowRows = [validatedRow(2), validatedRow(3)];
+    const plan = buildDispatchPlan(ceilingInternals(3), primaryRows, [], [], shadowRows);
+
+    expect(plan.validatedOrdered).toEqual(primaryRows);
+    expect(plan.shadowValidatedOrdered).toEqual(shadowRows.slice(0, 1));
+    expect(plan.validatedOrdered.length + plan.shadowValidatedOrdered.length).toBeLessThanOrEqual(
+      3,
+    );
+  });
 });

package/src/record/__tests__/mesh-ssbo.unit.test.ts

@@ -1,5 +1,6 @@
+import { err, ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { getOrCreateFromChain } from '../mesh-ssbo';
+import { getOrCreateFromChain, getOrCreateFromChainResult } from '../mesh-ssbo';
 
 describe('mesh bind-group cache chains', () => {
   it('keeps variable-depth material resource chains isolated', () => {
@@ -35,4 +36,42 @@ describe('mesh bind-group cache chains', () => {
     expect(long).not.toBe(short);
     expect(counts.createBindGroup).toBe(2);
   });
+
+  it('propagates bind-group creation failures without poisoning the cache', () => {
+    const root = new WeakMap<object, unknown>();
+    const resource = {};
+    const counts = { createBindGroup: 0, keys: [] as string[] };
+    const failure = { code: 'rhi-device-lost' };
+    const failed = getOrCreateFromChainResult(
+      root,
+      [resource],
+      'retryable',
+      () => err(failure),
+      counts,
+    );
+    expect(failed).toEqual({ ok: false, error: failure });
+    expect(counts.createBindGroup).toBe(0);
+
+    const created = { id: 'created' } as never;
+    const recovered = getOrCreateFromChainResult(
+      root,
+      [resource],
+      'retryable',
+      () => ok(created),
+      counts,
+    );
+    expect(recovered).toEqual({ ok: true, value: created });
+    expect(counts.createBindGroup).toBe(1);
+    expect(
+      getOrCreateFromChainResult(
+        root,
+        [resource],
+        'retryable',
+        () => {
+          throw new Error('cache miss after recovery');
+        },
+        counts,
+      ),
+    ).toEqual({ ok: true, value: created });
+  });
 });

package/src/record/__tests__/recovery-pipeline.unit.test.ts

@@ -69,7 +69,7 @@ function recoveryReadinessFor(
   });
 }
 
-describe('recovery first-frame cold-work guard', () => {
+describe('recovery prepared pipeline cache', () => {
   it('prepares the probe-enabled Standard PBR variant used by the live record path', () => {
     const readiness = recoveryReadinessFor(probeRenderable(true));
     const standardPbr = readiness.pipelineSpecs.find(
@@ -97,11 +97,29 @@ describe('recovery first-frame cold-work guard', () => {
     expect(standardPbr?.shader.variantSet).toContain('REFLECTION_FALLBACK_AVAILABLE=true');
     expect(standardPbr?.attachments.colorFormats).toEqual(['rgba16float', 'rgba16float']);
   });
+  it('allows explicit candidate uploads between recovery publication and the first draw', () => {
+    const guard = createRecoveryColdWorkGuard();
+    guard.arm();
+    expect(() => guard.noteUploadColdWork()).not.toThrow();
+  });
+
+  it('keeps the first-submit assertion across a skipped draw and releases its recording scope', () => {
+    const guard = createRecoveryColdWorkGuard();
+    guard.arm();
+    guard.beginFrame();
+    guard.endFrame();
+    expect(() => guard.noteUploadColdWork()).not.toThrow();
+    guard.beginFrame();
+    expect(() => guard.noteUploadColdWork()).toThrow(/cold upload/);
+    guard.endFrame();
+    expect(() => guard.noteUploadColdWork()).not.toThrow();
+  });
 
   it('accepts a prepared candidate with no first-frame cold work', () => {
     const guard = createRecoveryColdWorkGuard();
 
     guard.arm();
+    guard.beginFrame();
     expect(() => guard.finish()).not.toThrow();
     expect(() => guard.finish()).not.toThrow();
   });
@@ -119,6 +137,7 @@ describe('recovery first-frame cold-work guard', () => {
     const guard = createRecoveryColdWorkGuard();
 
     guard.arm();
+    guard.beginFrame();
     expect(() => note(guard)).toThrow(/recovery first frame performed cold/);
   });
 });

package/src/record/__tests__/sprite-material-abi.unit.test.ts

@@ -1,8 +1,10 @@
-import type { Buffer, Sampler, TextureView } from '@forgeax/engine-rhi';
+import type { BindGroupEntry, Buffer, Sampler, TextureView } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
 import { assembleMaterialWithSkylightEntries } from '../../ibl/skylight-bind-group';
-import { defaultViewForUserRegionField } from '../main-pass-material';
-import { buildSpritePassBaseMaterialEntries } from '../main-pass-sprite-draws';
+import {
+  BUILTIN_USER_REGION_TEXTURE_FIELDS,
+  defaultViewForUserRegionField,
+} from '../main-pass-material';
 import type { PipelineState } from '../render-context';
 
 describe('sprite Standard material ABI', () => {
@@ -27,7 +29,6 @@ describe('sprite Standard material ABI', () => {
     const white = {} as TextureView;
     const pipelineState = {
       materialUniformBuffer: { buffer: {} },
-      nearestSampler: sampler,
       defaultSampler: sampler,
       defaultWhiteTextureView: white,
       defaultNormalTextureView: {} as TextureView,
@@ -35,7 +36,27 @@ describe('sprite Standard material ABI', () => {
     } as PipelineState;
     const spriteTexture = {} as TextureView;
 
-    const entries = buildSpritePassBaseMaterialEntries(pipelineState, spriteTexture);
+    // Sprite no longer owns a parallel material-entry builder. Preserve the
+    // shared user-region/IBL layout gate; actual sampler selection is covered
+    // by the source-derived 300-frame Sprite raster smoke in both tone lanes.
+    const entries: BindGroupEntry[] = [
+      { binding: 0, resource: { kind: 'buffer', value: { buffer: {} as Buffer } } },
+    ];
+    for (const [index, field] of BUILTIN_USER_REGION_TEXTURE_FIELDS.entries()) {
+      entries.push(
+        { binding: 1 + index * 2, resource: { kind: 'sampler', value: sampler } },
+        {
+          binding: 2 + index * 2,
+          resource: {
+            kind: 'textureView',
+            value:
+              field === 'baseColorTexture'
+                ? spriteTexture
+                : defaultViewForUserRegionField(field, pipelineState),
+          },
+        },
+      );
+    }
 
     expect(entries.map((entry) => entry.binding)).toEqual([
       0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
@@ -66,7 +87,21 @@ describe('sprite Standard material ABI', () => {
       binding: 23,
       resource: { kind: 'textureView' },
     });
-    expect(merged).toHaveLength(24);
+    expect(merged).toHaveLength(25);
+    expect(merged.find((entry) => entry.binding === 47)?.resource.kind).toBe('textureView');
+
+    const complete = [
+      ...merged,
+      {
+        binding: 46,
+        resource: { kind: 'buffer' as const, value: { buffer: {} as Buffer } },
+      },
+    ];
+    expect(complete).toHaveLength(26);
+    expect(complete.find((entry) => entry.binding === 46)).toMatchObject({
+      binding: 46,
+      resource: { kind: 'buffer' },
+    });
 
     const backdrop = {} as TextureView;
     const active = assembleMaterialWithSkylightEntries(

package/src/record/__tests__/temporal-payload.unit.test.ts

@@ -84,6 +84,8 @@ function temporalView(): TemporalView {
     viewId: '0:1:0',
     historyVersion: 0,
     temporalFrameIndex: 1,
+    internalWidth: 4,
+    internalHeight: 4,
     historyValid: true,
     resetReason: undefined,
     currentJitterUv: [0, 0],

package/src/record/__tests__/typed-frame-graph-plan.unit.test.ts

@@ -2,11 +2,13 @@ import { ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import type { RenderFeaturePlannedFrame } from '../../features/plan';
 import { GPU_TEXTURE_USAGE_COPY_SRC } from '../../gpu-texture-usage';
+import { createAutoExposureGraphPlan } from '../../pipeline/standard-output/auto-exposure/graph';
 import { getTextureIdentity, validateGraphTargetCaptureReadback } from '../frame-snapshot';
 import {
   executeCompiledFrameGraph,
   type RenderFeatureGraphCandidate,
   renderFeatureGraphPlanSignature,
+  updateRenderFeaturePlanRevision,
 } from '../typed-frame-graph';
 
 const captureDescriptor = {
@@ -101,6 +103,13 @@ function planned(generation: number, signature: string): RenderFeaturePlannedFra
 }
 
 describe('typed frame graph feature plan authority', () => {
+  it('carries auto exposure as one frame-local candidate plan', () => {
+    const plan = createAutoExposureGraphPlan({ width: 17, height: 9 });
+    expect(plan.candidateAvailableSameFrame).toBe(true);
+    expect(plan.cpuReadbackCount).toBe(0);
+    expect(plan.cpuUploadCount).toBe(0);
+  });
+
   it('keys topology and last-known-good candidates by stable plan signature and generation', () => {
     const first = renderFeatureGraphPlanSignature([planned(1, 'plan-a')]);
     expect(renderFeatureGraphPlanSignature([planned(1, 'plan-a')])).toBe(first);
@@ -116,6 +125,42 @@ describe('typed frame graph feature plan authority', () => {
     expect(candidate.plans).toHaveLength(1);
   });
 
+  it('keeps the compact revision stable for equivalent plan objects', () => {
+    const first = updateRenderFeaturePlanRevision(
+      { revision: 0, entries: [] },
+      [planned(1, 'plan-a')],
+      [{ featureIdentity: 'synthetic.feature', order: 0, passes: [] }],
+    );
+    const equivalent = updateRenderFeaturePlanRevision(
+      first,
+      [planned(1, 'plan-a')],
+      [{ featureIdentity: 'synthetic.feature', order: 0, passes: [] }],
+    );
+    expect(equivalent).toBe(first);
+    expect(equivalent.revision).toBe(1);
+
+    const changedSignature = updateRenderFeaturePlanRevision(
+      equivalent,
+      [planned(1, 'plan-b')],
+      [{ featureIdentity: 'synthetic.feature', order: 0, passes: [] }],
+    );
+    expect(changedSignature.revision).toBe(2);
+    expect(
+      updateRenderFeaturePlanRevision(
+        changedSignature,
+        [planned(2, 'plan-b')],
+        [{ featureIdentity: 'synthetic.feature', order: 0, passes: [] }],
+      ).revision,
+    ).toBe(3);
+    expect(
+      updateRenderFeaturePlanRevision(
+        changedSignature,
+        [planned(1, 'plan-b')],
+        [{ featureIdentity: 'synthetic.feature', order: 1, passes: [] }],
+      ).revision,
+    ).toBe(3);
+  });
+
   it('keeps execution projection out of the public planned-frame vocabulary', () => {
     const invalid: RenderFeaturePlannedFrame = {
       ...planned(1, 'plan-a'),

package/src/record/__tests__/view-ubo-layout.unit.test.ts

@@ -34,6 +34,11 @@ describe('View UBO directional shadow ABI', () => {
   it('declares one shared View binding with a vec4 directional filter carrier', () => {
     const viewStruct = commonWgslSrc.match(/struct View \{[\s\S]*?\n\};/)?.[0] ?? '';
     expect(viewStruct).toMatch(/directionalShadowFilter\s*:\s*vec4<f32>/);
+    expect(viewStruct).toMatch(/ssrParams\s*:\s*vec4<f32>/);
+    expect(viewUboSrc).toMatch(/viewPayload\[236\]\s*=\s*ssr\.maxDistance/);
+    expect(viewUboSrc).toMatch(/viewPayload\[237\]\s*=\s*ssr\.thickness/);
+    expect(viewUboSrc).toMatch(/viewPayload\[238\]\s*=\s*ssr\.maxRoughness/);
+    expect(viewUboSrc).toMatch(/viewPayload\[239\]\s*=\s*1/);
     expect(viewStruct).not.toMatch(/pcfKernelSize/);
     expect(commonWgslSrc.match(/@group\(0\) @binding\(0\) var<uniform> view/g)).toHaveLength(1);
   });