@forgeax/engine-render 0.1.28 → 0.1.30

package/src/environment/ibl.ts

@@ -0,0 +1,211 @@
+import type {
+  GraphBuffer,
+  GraphTextureView,
+  RenderGraphBuilder,
+  RenderGraphError,
+} from '@forgeax/engine-render-graph';
+import {
+  type BindGroup,
+  type BindGroupLayout,
+  type RenderPipeline,
+  RhiError,
+  type Sampler,
+} from '@forgeax/engine-rhi';
+import { ok, type Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame } from '../render-pipeline';
+import { atmosphereStorage } from './storage';
+
+/** Graph views of the shared device-owned sky and its lighting products. */
+export interface GraphEnvironment {
+  readonly sky: GraphTextureView;
+  readonly irradiance: GraphTextureView;
+  readonly prefilter: GraphTextureView;
+}
+
+export function addAtmosphereIbl(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  sky: GraphTextureView,
+  vertices: GraphBuffer,
+  dirty: (frame: RenderPipelineFrame) => boolean,
+): Result<GraphEnvironment, RenderGraphError> {
+  const irradiance = graph.importTexture(
+    'atmosphere-irradiance',
+    {
+      format: 'rgba16float',
+      size: { width: 16, height: 16, depthOrArrayLayers: 6 },
+      usage: 0x14,
+    },
+    (frame) => atmosphereStorage(frame).irradiance,
+  );
+  if (!irradiance.ok) return irradiance;
+  const prefilter = graph.importTexture(
+    'atmosphere-prefilter',
+    {
+      format: 'rgba16float',
+      size: { width: 64, height: 64, depthOrArrayLayers: 6 },
+      mipLevelCount: 5,
+      usage: 0x14,
+    },
+    (frame) => atmosphereStorage(frame).prefilter,
+  );
+  if (!prefilter.ok) return prefilter;
+  const irradianceView = graph.view(irradiance.value, { dimension: 'cube', arrayLayerCount: 6 });
+  if (!irradianceView.ok) return irradianceView;
+  const prefilterView = graph.view(prefilter.value, { dimension: 'cube', arrayLayerCount: 6 });
+  if (!prefilterView.ok) return prefilterView;
+  const parameters = graph.importBuffer(
+    'atmosphere-ibl-params',
+    { size: 5 * 256, usage: 0x48 },
+    (frame) => atmosphereStorage(frame).iblParams,
+  );
+  if (!parameters.ok) return parameters;
+  const upload = graph.addCopyPass('atmosphere-ibl-prepare', {
+    accesses: [{ resource: parameters.value, usage: 'copy-dst' }],
+    executeIf: dirty,
+    encode: ({ frame, resources }) => {
+      const values = new Float32Array(5 * 64);
+      for (let mip = 0; mip < 5; mip++) values[mip * 64 + 14] = mip / 4;
+      frame.runtime.device.queue
+        .writeBuffer(resources.buffer(parameters.value).unwrap(), 0, values)
+        .unwrap();
+    },
+  });
+  if (!upload.ok) return upload;
+  let state:
+    | {
+        layout: BindGroupLayout;
+        inputLayout: BindGroupLayout;
+        sampler: Sampler;
+        irradiance: RenderPipeline;
+        prefilter: RenderPipeline;
+        inputs?: BindGroup;
+        parameters: BindGroup[];
+      }
+    | undefined;
+  const ensureState = (frame: RenderPipelineFrame) => {
+    if (state !== undefined) return state;
+    const device = frame.runtime.device;
+    const source = frame.atmosphereShaders?.ibl;
+    const factory = frame.runtime.shaderModuleFactory;
+    if (source === undefined || factory === undefined)
+      throw new RhiError({
+        code: 'shader-compile-failed',
+        expected: 'the compiled Atmosphere IBL program is available',
+        hint: 'rebuild the Engine shader manifest before selecting Atmosphere lighting',
+      });
+    const module = factory.createShaderModule({ code: source, label: 'atmosphere_ibl' }).unwrap();
+    const layout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 2, buffer: { type: 'uniform', minBindingSize: 64 } }],
+      })
+      .unwrap();
+    const inputLayout = device
+      .createBindGroupLayout({
+        entries: [
+          { binding: 0, visibility: 2, texture: { sampleType: 'float', viewDimension: 'cube' } },
+          { binding: 1, visibility: 2, sampler: { type: 'filtering' } },
+        ],
+      })
+      .unwrap();
+    const pipelineLayout = device
+      .createPipelineLayout({ bindGroupLayouts: [layout, inputLayout] })
+      .unwrap();
+    const pipeline = (entryPoint: string) =>
+      device
+        .createRenderPipeline({
+          label: entryPoint,
+          layout: pipelineLayout,
+          vertex: {
+            module,
+            entryPoint: 'atmosphere_ibl_vs',
+            buffers: [
+              {
+                arrayStride: 12,
+                attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+              },
+            ],
+          },
+          fragment: { module, entryPoint, targets: [{ format: 'rgba16float' }] },
+          primitive: { topology: 'triangle-list' },
+        })
+        .unwrap();
+    state = {
+      layout,
+      inputLayout,
+      sampler: device
+        .createSampler({ magFilter: 'linear', minFilter: 'linear', mipmapFilter: 'linear' })
+        .unwrap(),
+      irradiance: pipeline('atmosphere_irradiance_fs'),
+      prefilter: pipeline('atmosphere_prefilter_fs'),
+      parameters: [],
+    };
+    return state;
+  };
+  for (const product of ['irradiance', 'prefilter'] as const) {
+    for (let mip = 0; mip < (product === 'irradiance' ? 1 : 5); mip++)
+      for (let face = 0; face < 6; face++) {
+        const target = graph.view(product === 'irradiance' ? irradiance.value : prefilter.value, {
+          dimension: '2d',
+          baseArrayLayer: face,
+          arrayLayerCount: 1,
+          baseMipLevel: mip,
+          mipLevelCount: 1,
+        });
+        if (!target.ok) return target;
+        const pass = graph.addRasterPass(`atmosphere-${product}-${mip}-${face}`, {
+          accesses: [
+            { resource: sky, usage: 'sampled-read' },
+            { resource: parameters.value, usage: 'uniform-read' },
+            { resource: vertices, usage: 'vertex-read' },
+            { resource: target.value, usage: 'color-attachment' },
+          ],
+          colorAttachments: [{ view: target.value, loadOp: 'clear', storeOp: 'store' }],
+          executeIf: dirty,
+          encode: ({ frame, resources, pass }) => {
+            const current = ensureState(frame);
+            current.inputs ??= frame.runtime.device
+              .createBindGroup({
+                layout: current.inputLayout,
+                entries: [
+                  {
+                    binding: 0,
+                    resource: { kind: 'textureView', value: resources.textureView(sky).unwrap() },
+                  },
+                  { binding: 1, resource: { kind: 'sampler', value: current.sampler } },
+                ],
+              })
+              .unwrap();
+            let parameterGroup = current.parameters[mip];
+            if (parameterGroup === undefined) {
+              parameterGroup = frame.runtime.device
+                .createBindGroup({
+                  layout: current.layout,
+                  entries: [
+                    {
+                      binding: 0,
+                      resource: {
+                        kind: 'buffer',
+                        value: {
+                          buffer: resources.buffer(parameters.value).unwrap(),
+                          offset: mip * 256,
+                          size: 64,
+                        },
+                      },
+                    },
+                  ],
+                })
+                .unwrap();
+              current.parameters[mip] = parameterGroup;
+            }
+            pass.setPipeline(current[product]);
+            pass.setBindGroup(0, parameterGroup);
+            pass.setBindGroup(1, current.inputs);
+            pass.setVertexBuffer(0, resources.buffer(vertices).unwrap());
+            pass.draw(3, 1, face * 3);
+          },
+        });
+        if (!pass.ok) return pass;
+      }
+  }
+  return ok({ sky, irradiance: irradianceView.value, prefilter: prefilterView.value });
+}

package/src/environment/storage.ts

@@ -0,0 +1,63 @@
+import type { Buffer, Texture } from '@forgeax/engine-rhi';
+import type { DeviceScope } from '../device/device-scope';
+import type { _InternalRenderPipelineContext } from '../record/render-context';
+import type { RenderPipelineFrame } from '../render-pipeline';
+
+/** Device-generation resources survive unrelated probe/scene graph topology changes. */
+export interface AtmosphereStorage {
+  readonly sky: Texture;
+  readonly irradiance: Texture;
+  readonly prefilter: Texture;
+  readonly params: Buffer;
+  readonly vertices: Buffer;
+  readonly iblParams: Buffer;
+  submittedSignature?: string | undefined;
+}
+const generations = new WeakMap<DeviceScope, AtmosphereStorage>();
+
+export function atmosphereStorage(frame: RenderPipelineFrame): AtmosphereStorage {
+  const runtime = (frame as _InternalRenderPipelineContext).runtime;
+  const owner = runtime.deviceScope;
+  const existing = generations.get(owner);
+  if (existing !== undefined) return existing;
+  const scope = owner.createChild('atmosphere');
+  const device = runtime.device;
+  try {
+    const texture = (name: string, size: number, mipLevelCount = 1) => {
+      const value = device
+        .createTexture({
+          label: name,
+          format: 'rgba16float',
+          size: { width: size, height: size, depthOrArrayLayers: 6 },
+          mipLevelCount,
+          usage: 0x14,
+          textureBindingViewDimension: undefined,
+        })
+        .unwrap();
+      scope._adopt('texture', value, (value) => {
+        device.destroyTexture(value).unwrap();
+      });
+      return value;
+    };
+    const buffer = (name: string, size: number, usage: number) => {
+      const value = device.createBuffer({ label: name, size, usage }).unwrap();
+      scope._adopt('buffer', value, (value) => {
+        device.destroyBuffer(value).unwrap();
+      });
+      return value;
+    };
+    const created: AtmosphereStorage = {
+      sky: texture('atmosphere-sky', 128),
+      irradiance: texture('atmosphere-irradiance', 16),
+      prefilter: texture('atmosphere-prefilter', 64, 5),
+      params: buffer('atmosphere-params', 64, 0x48),
+      vertices: buffer('atmosphere-face-vertices', 216, 0x28),
+      iblParams: buffer('atmosphere-ibl-params', 1280, 0x48),
+    };
+    generations.set(owner, created);
+    return created;
+  } catch (cause) {
+    scope.retire();
+    throw cause;
+  }
+}

package/src/errors/gpu-driven.ts

@@ -2,67 +2,105 @@ import type { MaterialShaderArtifactReceipt } from '@forgeax/engine-shader';
 
 export type GpuDrivenPreparationErrorCode =
   | 'missing-material-receipt'
+  | 'material-abi-not-executable'
   | 'missing-uv'
   | 'reflection-mismatch'
   | 'vertex-input-mismatch'
   | 'alpha-mask-mismatch'
   | 'resource-not-ready'
   | 'stale-generation'
-  | 'skin-receipt-mismatch';
+  | 'skin-receipt-mismatch'
+  | 'shadow-ownership';
 
 export type GpuDrivenPreparationReason =
   | 'material-receipt-missing'
+  | 'material-abi-not-executable'
   | 'uv-set-missing'
   | 'reflection-receipt-mismatch'
   | 'vertex-semantic-mismatch'
   | 'alpha-mask-receipt-missing'
   | 'material-resource-missing'
   | 'generation-stale'
-  | 'skin-address-missing';
+  | 'skin-address-missing'
+  | 'shadow-ownership-missing';
+
+/** Closed next action; AI callers never need to parse an error message. */
+export type GpuDrivenRecoveryAction =
+  | 'rebuild-producer'
+  | 'route-cpu-lane'
+  | 'retry-same-draw'
+  | 'rebuild-generation'
+  | 'stop-promotion';
 
 export interface GpuDrivenPreparationErrorDetail {
   readonly reason: GpuDrivenPreparationReason;
-  readonly owner: 'material' | 'geometry' | 'skin' | 'generation';
+  readonly owner: 'material' | 'geometry' | 'skin' | 'generation' | 'shadow';
   readonly expected?: string;
   readonly actual?: string;
   readonly expectedGeneration?: number;
   readonly actualGeneration?: number;
+  readonly recovery?: GpuDrivenRecoveryAction;
 }
 
 const ERROR_POLICY: Readonly<
-  Record<GpuDrivenPreparationErrorCode, { readonly expected: string; readonly hint: string }>
+  Record<
+    GpuDrivenPreparationErrorCode,
+    {
+      readonly expected: string;
+      readonly hint: string;
+      readonly recovery: GpuDrivenRecoveryAction;
+    }
+  >
 > = {
   'missing-material-receipt': {
-    expected: 'a producer-owned Standard PBR material receipt is present',
-    hint: 'cook and load the Standard PBR artifact, then retry preparation',
+    expected: 'a producer-owned material program receipt is present',
+    hint: 'cook and load the selected material program artifact, then retry preparation',
+    recovery: 'rebuild-producer',
+  },
+  'material-abi-not-executable': {
+    expected: 'the published material ABI fits the GPU Scene submission layout',
+    hint: 'recook the material with a scene-index ABI supported by the GPU-driven owner or keep it on its authored lane',
+    recovery: 'route-cpu-lane',
   },
   'missing-uv': {
     expected: 'the geometry exposes every UV set named by the material receipt',
     hint: 'repair the geometry UV semantic or route the draw to the CPU semantic lane',
+    recovery: 'route-cpu-lane',
   },
   'reflection-mismatch': {
     expected: 'the loaded reflection receipt matches the artifact layout identity',
     hint: 'rebuild the material artifact and reflection from one source, then retry',
+    recovery: 'rebuild-producer',
   },
   'vertex-input-mismatch': {
     expected: 'geometry vertex semantics match the material reflection receipt',
     hint: 'repair the geometry vertex semantic layout or route the draw to the CPU lane',
+    recovery: 'route-cpu-lane',
   },
   'alpha-mask-mismatch': {
     expected: 'the Alpha Mask cutoff is present in the material receipt',
-    hint: 'declare alphaCutoff in the Standard PBR material schema and recook it',
+    hint: 'declare the pass coverage cutoff in the material schema and recook it',
+    recovery: 'rebuild-producer',
   },
   'resource-not-ready': {
     expected: 'all material resource slots have resolved handles',
     hint: 'resolve the declared texture and sampler resources before recording',
+    recovery: 'retry-same-draw',
   },
   'stale-generation': {
     expected: 'receipt and prepared inputs belong to the requested generation',
     hint: 'discard stale GPU facts, rebuild the producer receipt, and retry the same draw',
+    recovery: 'rebuild-generation',
   },
   'skin-receipt-mismatch': {
     expected: 'skinned geometry has a current palette address receipt',
     hint: 'rebuild the Skin palette receipt for this generation before recording',
+    recovery: 'rebuild-producer',
+  },
+  'shadow-ownership': {
+    expected: 'every declared ShadowCaster pass has one GPU-compatible draw-item owner',
+    hint: 'repair the ShadowCaster producer membership or keep the residual on its explicit CPU lane',
+    recovery: 'route-cpu-lane',
   },
 };
 
@@ -79,7 +117,10 @@ export class GpuDrivenPreparationError extends Error {
     this.code = code;
     this.expected = policy.expected;
     this.hint = policy.hint;
-    this.detail = detail;
+    this.detail = Object.freeze({
+      ...detail,
+      recovery: detail.recovery ?? policy.recovery,
+    });
   }
 }
 

package/src/errors/render.ts

@@ -25,6 +25,7 @@ import type {
   RenderFeatureRecovery,
   RenderFeatureStage,
 } from '../features/vocabulary';
+import type { AutoExposureError } from '../pipeline/standard-output/auto-exposure/inspection';
 import type { SceneDataLane, SceneDataSchemaId } from '../temporal/scene-data';
 import type { TransmissionCapabilityFact } from '../transmission/backdrop';
 import type { RecoveryOutcome, RecoveryPhase } from './recover';
@@ -33,6 +34,28 @@ import type { RecoveryOutcome, RecoveryPhase } from './recover';
 // expected state, actionable `hint`, then typed `detail`. Consumers branch on
 // that shape and never use Error.message as a protocol.
 
+export type {
+  AutoExposureCapabilityUnavailableDetail,
+  AutoExposureError,
+  AutoExposureErrorCode,
+  AutoExposureErrorDetail,
+  AutoExposureErrorDetailByCode,
+  AutoExposureErrorRecord,
+  AutoExposureInspection,
+  AutoExposureInspectionInput,
+  AutoExposureInvalidParameterDetail,
+  AutoExposureReceipt,
+  AutoExposureResetReason,
+  AutoExposureStageFailedDetail,
+  AutoExposureStaleGenerationDetail,
+} from '../pipeline/standard-output/auto-exposure/inspection';
+export {
+  AutoExposureCapabilityUnavailableError,
+  AutoExposureInvalidParameterError,
+  AutoExposureStageFailedError,
+  AutoExposureStaleGenerationError,
+} from '../pipeline/standard-output/auto-exposure/inspection';
+
 export interface LifecycleConstructionFailureDetail {
   readonly owner: string;
   readonly generation: number;
@@ -1177,7 +1200,7 @@ export class FrameReceiptStaleError extends Error {
 }
 
 export interface RendererContractFailureDetail {
-  readonly operation: 'construct' | 'attach' | 'draw' | 'observe';
+  readonly operation: 'construct' | 'attach' | 'draw' | 'request-observation' | 'observe';
   readonly cause: string;
 }
 
@@ -1297,6 +1320,67 @@ export class AtmosphereInvalidParameterError extends Error {
   }
 }
 
+export interface DynamicResolutionInvalidParameterDetail {
+  readonly field: 'targetGpuMs' | 'minScale' | 'maxScale';
+  readonly value: number;
+  readonly expected: string;
+}
+
+export class DynamicResolutionInvalidParameterError extends Error {
+  readonly code = 'dynamic-resolution-invalid-parameter' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: DynamicResolutionInvalidParameterDetail;
+
+  constructor(detail: DynamicResolutionInvalidParameterDetail) {
+    super(`DynamicResolution.${detail.field} is invalid`);
+    this.name = 'DynamicResolutionInvalidParameterError';
+    this.expected = `DynamicResolution.${detail.field} must be ${detail.expected}`;
+    this.hint = `set DynamicResolution.${detail.field} to a value that is ${detail.expected}`;
+    this.detail = detail;
+  }
+}
+
+export interface DynamicResolutionRequiresTaaDetail {
+  readonly antialias: 'none' | 'fxaa' | 'msaa';
+}
+
+export class DynamicResolutionRequiresTaaError extends Error {
+  readonly code = 'dynamic-resolution-requires-taa' as const;
+  readonly expected = "DynamicResolution requires Camera.antialias to be 'taa'";
+  readonly hint = "set Camera.antialias to 'taa' or remove DynamicResolution before retrying";
+  readonly detail: DynamicResolutionRequiresTaaDetail;
+
+  constructor(detail: DynamicResolutionRequiresTaaDetail) {
+    super('DynamicResolution requires TAA');
+    this.name = 'DynamicResolutionRequiresTaaError';
+    this.detail = detail;
+  }
+}
+
+export interface DynamicResolutionTimingUnavailableDetail {
+  readonly generation: number;
+  readonly operation: 'timestamp-query';
+}
+
+export class DynamicResolutionTimingUnavailableError extends Error {
+  readonly code = 'dynamic-resolution-timing-unavailable' as const;
+  readonly expected = 'adaptive resolution receives a completed GPU timing sample';
+  readonly hint = 'use fixed minScale=maxScale or retry after timestamp support is available';
+  readonly detail: DynamicResolutionTimingUnavailableDetail;
+
+  constructor(detail: DynamicResolutionTimingUnavailableDetail) {
+    super(`DynamicResolution timing is unavailable for generation ${detail.generation}`);
+    this.name = 'DynamicResolutionTimingUnavailableError';
+    this.detail = detail;
+  }
+}
+
+export type DynamicResolutionError =
+  | DynamicResolutionInvalidParameterError
+  | DynamicResolutionRequiresTaaError
+  | DynamicResolutionTimingUnavailableError;
+
 export interface OwnerStageFailedDetail {
   readonly owner: 'environment' | 'temporal' | 'fog' | 'renderer';
   readonly stage: 'extract' | 'prepare' | 'record' | 'finish' | 'submit';
@@ -1328,7 +1412,7 @@ export interface RendererOperationDetailByCode {
     readonly cause: RendererOperationCause;
   };
   readonly 'frame-input-invalid': {
-    readonly operation: 'draw' | 'set-profile';
+    readonly operation: 'draw' | 'set-profile' | 'request-observation';
     readonly cause: RendererOperationCause;
   };
   readonly 'scene-projection-failed': {
@@ -1358,7 +1442,7 @@ export interface RendererOperationDetailByCode {
     readonly cause: RendererOperationCause;
   };
   readonly 'renderer-state-invalid': {
-    readonly operation: 'draw' | 'set-profile' | 'recover' | 'dispose';
+    readonly operation: 'draw' | 'set-profile' | 'request-observation' | 'recover' | 'dispose';
     readonly state: string;
     readonly cause?: RendererOperationCause;
   };
@@ -1851,6 +1935,7 @@ export type RenderErrorCode = RenderError['code'];
  */
 export type RenderError =
   | LifecycleConstructionError
+  | AutoExposureError
   | RendererExpectedOperationError
   | FrameReceiptStaleError
   | RendererContractFailureError
@@ -1884,6 +1969,9 @@ export type RenderError =
   | TaaCapsInsufficientError
   | EnvironmentGenerationFailedError
   | AtmosphereInvalidParameterError
+  | DynamicResolutionInvalidParameterError
+  | DynamicResolutionRequiresTaaError
+  | DynamicResolutionTimingUnavailableError
   | OwnerStageFailedError
   | PointsLinesInvalidStyleError
   | PointsLinesTopologyMismatchError

package/src/extract/camera.ts

@@ -6,10 +6,17 @@ import {
   antialiasFromF32,
   bloomEnabledFromF32,
   Camera,
+  cameraExposureFromColumns,
   cameraProjectionFromF32,
   tonemapFromF32,
+  validateCameraColorGrading,
 } from '../components/camera';
+import {
+  DynamicResolution,
+  validateDynamicResolutionCamera,
+} from '../components/dynamic-resolution';
 import { MotionBlur } from '../components/motion-blur';
+import { ScreenSpaceReflection } from '../components/screen-space-reflection';
 import type { CameraSnapshot } from '../render-contract';
 import { getActiveCamera, selectActiveCameraIndex } from '../systems/active-camera';
 
@@ -23,14 +30,24 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
   const cameras: CameraSnapshot[] = [];
   const cameraEntities: number[] = [];
   const cameraQuery = world
-    .query({ read: [Camera], optional: [MotionBlur], with: [GlobalTransform] })
+    .query({
+      read: [Camera],
+      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection],
+      with: [GlobalTransform],
+    })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    validateCameraColorGrading(cam.temperature, cam.tint, cam.colorLutStrength);
+    const dynamicResolution = row.get(DynamicResolution);
+    const screenSpaceReflection = row.get(ScreenSpaceReflection);
     const entity = row.entity as EntityHandle;
     const worldMat = readWorldMatrix(world, entity);
     if (worldMat === undefined) continue;
+    const antialias = antialiasFromF32(cam.antialias);
+    const dynamicResolutionResult = validateDynamicResolutionCamera(dynamicResolution, antialias);
+    if (!dynamicResolutionResult.ok) throw dynamicResolutionResult.error;
     cameras.push({
       entityKey: entity as number,
       historyVersion: cam.historyVersion,
@@ -48,7 +65,17 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
       tonemap: tonemapFromF32(cam.tonemap),
       exposure: cam.exposure,
       whitePoint: cam.whitePoint,
+      output: {
+        exposure: cameraExposureFromColumns(cam),
+        temperature: cam.temperature,
+        tint: cam.tint,
+        colorLut: cam.colorLut,
+        colorLutStrength: cam.colorLutStrength,
+      },
       antialias: antialiasFromF32(cam.antialias),
+      ...(dynamicResolutionResult.value === undefined
+        ? {}
+        : { dynamicResolution: dynamicResolutionResult.value }),
       bloom: bloomEnabledFromF32(cam.bloom),
       bloomThreshold: cam.bloomThreshold,
       bloomIntensity: cam.bloomIntensity,
@@ -68,6 +95,15 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
               sampleCount: motionBlur.sampleCount,
             },
           }),
+      ...(screenSpaceReflection === undefined
+        ? {}
+        : {
+            screenSpaceReflection: {
+              maxDistance: screenSpaceReflection.maxDistance,
+              thickness: screenSpaceReflection.thickness,
+              maxRoughness: screenSpaceReflection.maxRoughness,
+            },
+          }),
     });
     cameraEntities.push(entity as number);
   }

package/src/extract/contracts.ts

@@ -660,6 +660,10 @@ export interface MaterialSnapshot {
    */
   readonly materialShaderId?: string | undefined;
   readonly materialProgramKeys?: Readonly<Record<string, string>> | undefined;
+  /** Producer-selected scene-index program keys, when a cooked publication carries them. */
+  readonly materialSceneIndexProgramKeys?:
+    | Readonly<Record<string, MaterialSceneIndexProgramKey>>
+    | undefined;
   /**
    * Stable source handle for the material asset. Record uses this only for
    * same-frame assembly reuse; GPU bind-group validity still comes from the
@@ -776,6 +780,12 @@ export interface MaterialSnapshot {
   readonly transparent?: boolean | undefined;
 }
 
+/** Producer-selected scene-index key plus the Pass kind that owns it. */
+export interface MaterialSceneIndexProgramKey {
+  readonly specializationKey: string;
+  readonly pass: 'forward' | 'shadow' | 'depth';
+}
+
 export interface MaterialCacheChainIdentity {
   readonly asset: MaterialAsset;
   readonly parentGuid: string | undefined;