@forgeax/engine-render 0.1.19 → 0.1.21

package/src/record/view-ubo.ts

@@ -8,6 +8,7 @@
 
 import { mat4 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
+import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
 import type { FogFrame } from '../extract/environment';
 import type { PointsLinesStyle } from '../points-lines/snapshot';
 import type { CameraSnapshot } from '../render-contract';
@@ -16,9 +17,9 @@ import type {
   ExtractedLights,
   SpotLightSnapshot,
 } from '../render-system-extract';
+import { SHADOW_ATLAS_DEFAULT_LAYERS } from '../shadow-atlas';
 import type { TemporalView as LegacyTemporalView } from '../temporal/temporal-view';
 import type { TemporalView } from '../temporal/view';
-import { clampPcfKernelSize } from './frame-snapshot';
 import { computeProjectionMatrix, computeViewMatrix } from './helpers';
 
 export const VIEW_UNIFORM_BYTES = 960;
@@ -29,13 +30,39 @@ export const POINTS_LINES_VIEW_BUFFER_SIZE =
   POINTS_LINES_VIEW_SLOT_STRIDE * POINTS_LINES_VIEW_SLOT_COUNT;
 export const VIEW_UNIFORM_SLOT_STRIDE = 1024;
 export const POINT_SHADOW_VIEW_SLOT_COUNT = 24;
+export const CUBE_CAPTURE_VIEW_SLOT_BASE = 1 + POINT_SHADOW_VIEW_SLOT_COUNT;
+export const REFLECTION_PROBE_VIEW_SLOT_BASE = CUBE_CAPTURE_VIEW_SLOT_BASE + 6;
+export const REFLECTION_PROBE_VIEW_SLOT_COUNT = 16;
 export const VIEW_UNIFORM_BUFFER_SIZE =
-  VIEW_UNIFORM_SLOT_STRIDE * (1 + POINT_SHADOW_VIEW_SLOT_COUNT);
+  VIEW_UNIFORM_SLOT_STRIDE * (REFLECTION_PROBE_VIEW_SLOT_BASE + REFLECTION_PROBE_VIEW_SLOT_COUNT);
 
 export function pointShadowViewOffset(layer: number, face: number): number {
   return VIEW_UNIFORM_SLOT_STRIDE * (1 + layer * 6 + face);
 }
 
+/** Project the accepted Directional quality union into the frozen View ABI. */
+function directionalShadowFilterCarrier(
+  quality: DirectionalShadowQuality | undefined,
+): readonly [number, number, number, number] {
+  if (quality === undefined) return [0, 0, 0, 0];
+  if (quality.kind === 'pcss') {
+    return [
+      quality.preset === 'medium' ? 4 : 5,
+      quality.angularRadiusRadians,
+      quality.maxPenumbraTexels,
+      0,
+    ];
+  }
+  switch (quality.kernel) {
+    case 1:
+      return [1, 0, 0, 0];
+    case 3:
+      return [2, 0, 0, 0];
+    case 5:
+      return [3, 0, 0, 0];
+  }
+}
+
 export function writePointsLinesViewUbo(
   queue: RhiQueue,
   buffer: Buffer,
@@ -95,10 +122,10 @@ export function writePointsLinesViewUbo(
  *   [24..26] cameraPos, [28..43] lightViewProj0 (was lightSpaceMatrix),
  *   [44..59] inverseViewProj, [60..75] lightViewProj1,
  *   [76..91] lightViewProj2, [92..107] lightViewProj3,
- *   [108]/[112]/[116]/[120] splitPlanes (vec4 stride),
+ *   [108..123] splitPlanes (vec4 lanes: split/world texel/depth span/reserved),
  *   [124] cascadeCount, [125] cascadeBlend,
- *   [126] depthBias, [127] normalBias, [128] pcfKernelSize (feat-20260621
- *   M3 / m3-t2-t3), [129..131] align pad,
+ *   [126] depthBias, [127] normalBias,
+ *   [128..131] directionalShadowFilter (profile/radius/max penumbra/reserved),
  *   [132..195] spotLightViewProj array<mat4x4<f32>, 4> (feat-20260625 w25:
  *   folded from standalone binding 9 to fix WebGL2 fragment uniform-buffer
  *   overflow; lane N = spot with shadowAtlasTile === N, 16 f32 / lane,
@@ -113,9 +140,13 @@ export function writeViewUbo(
   light: DirectionalLightSnapshot,
   lights: ExtractedLights,
   spotShadowSnapshots: readonly SpotLightSnapshot[],
-  fogOrTemporal?: FogFrame | TemporalView | LegacyTemporalView,
+  fogOrTemporalOrOffset?: FogFrame | TemporalView | LegacyTemporalView | number,
   temporal?: TemporalView,
+  projectorSpotIndex?: number,
 ): void {
+  const byteOffset = typeof fogOrTemporalOrOffset === 'number' ? fogOrTemporalOrOffset : 0;
+  const fogOrTemporal =
+    typeof fogOrTemporalOrOffset === 'number' ? undefined : fogOrTemporalOrOffset;
   const isTemporal =
     fogOrTemporal !== undefined &&
     ('currentJitterUv' in fogOrTemporal || 'currentUnjitteredViewProjection' in fogOrTemporal);
@@ -185,38 +216,39 @@ export function writeViewUbo(
   viewPayload[228] = camera.near;
   viewPayload[229] = camera.far;
   viewPayload[230] = camera.projection === 'orthographic' ? 1 : 0;
-  // splitPlanes at [108], [112], [116], [120] (vec4 stride = 4 floats).
+  // splitPlanes at [108..123] (four vec4 lanes: split/world texel/depth span/reserved).
   if (lights.splitPlanes !== undefined) {
     for (let s = 0; s < 4; s++) {
-      viewPayload[108 + s * 4] = lights.splitPlanes[s] ?? 0;
+      for (let lane = 0; lane < 4; lane++) {
+        viewPayload[108 + s * 4 + lane] = lights.splitPlanes[s * 4 + lane] ?? 0;
+      }
     }
   }
   // cascadeCount / cascadeBlend at [124..125].
   viewPayload[124] = lights.cascadeCount ?? 0;
   viewPayload[125] = lights.cascadeBlend ?? 0;
-  // feat-20260621-merge-directionallightshadow-into-directionallight M3 /
-  // m3-t2: shadow bias + PCF kernel width from the merged DirectionalLight
-  // land in the formerly-free tail pad at floats [126/127/128] (bytes
-  // 504/508/512). VIEW_PAYLOAD_FLOATS / VIEW_UBO_BYTES are unchanged --
-  // the WGSL View struct (common.wgsl) appends matching f32 at the same
-  // slots; the host tail pad shrinks 88 B -> 64 B, rest stays zero.
-  // pcfKernelSize is host-clamped to the nearest valid odd kernel {1,3,5}
-  // (cap 5, matching lighting-directional.wgsl MAX_PCF_HALF=2 from the
-  // merged 5.3-production-shadow-demos AC-14 variant-free loop) so the
-  // per-iteration radius clip has a fixed, legal bound; undefined
-  // (no cast-shadow / no shadow fields) defaults to 3.
+  // M1 directional shadow carrier: bias remains at [126]/[127], while the
+  // accepted quality union occupies the existing four-float tail [128..131].
+  // Point and Spot pcfKernelSize stay in their own snapshot paths and never
+  // enter this Directional View projection.
   viewPayload[126] = lights.depthBias ?? 0.005;
   viewPayload[127] = lights.normalBias ?? 0.05;
-  viewPayload[128] = clampPcfKernelSize(lights.pcfKernelSize);
+  const filterCarrier = directionalShadowFilterCarrier(lights.directionalShadowQuality);
+  viewPayload[128] = filterCarrier[0] ?? 0;
+  viewPayload[129] = filterCarrier[1] ?? 0;
+  viewPayload[130] = filterCarrier[2] ?? 0;
+  viewPayload[131] = filterCarrier[3] ?? 0;
 
   // feat-20260625-spot-light-shadow-mapping w25 (scope-amend webkit-fallback):
   // spotLightViewProj array<mat4x4<f32>, 4> at floats [132..195] (byte 528,
-  // 16 B-aligned after pcfKernelSize). Lane N = the spot with
+  // 16 B-aligned after directionalShadowFilter). Lane N = the spot with
   // `shadowAtlasTile === N` (cap = 4); the perspective matrix was already
   // computed by the extract stage (SpotLightSnapshot.lightViewProj) — record
-  // never recomputes it (Derive). Lanes for non-shadow / clipped spots (tile
-  // < 0 or lightViewProj undefined) stay zeroed; the WGSL sample path gates
-  // on `SpotLight.shadowAtlasTile >= 0` so zeroed lanes are never read.
+  // never recomputes it (Derive). The accepted projector is identified by its
+  // spot index, not by a negative shadow tile: a projector-only spot publishes
+  // its matrix in lane 0 so the shader never samples a zero matrix. Shadowed
+  // projector spots keep their shadow tile lane and carry the projector bit in
+  // the LightSlot identity word.
   // Folded from the former standalone binding 9 UBO to keep the WebGL2
   // fallback fragment uniform-buffer count <= 11 (GLES 3.0).
   {
@@ -228,10 +260,12 @@ export function writeViewUbo(
       const ss = spotSnaps[i];
       if (ss === undefined) continue;
       const tile = ss.shadowAtlasTile;
-      if (tile < 0 || tile >= SPOT_LVP_LANE_COUNT) continue;
       const lvp = ss.lightViewProj;
       if (lvp === undefined) continue;
-      const base = SPOT_LVP_BASE_FLOAT + tile * SPOT_LVP_FLOATS_PER_LANE;
+      const lane =
+        tile >= 0 && tile < SPOT_LVP_LANE_COUNT ? tile : i === projectorSpotIndex ? 0 : -1;
+      if (lane < 0) continue;
+      const base = SPOT_LVP_BASE_FLOAT + lane * SPOT_LVP_FLOATS_PER_LANE;
       for (let f = 0; f < SPOT_LVP_FLOATS_PER_LANE; f++) {
         viewPayload[base + f] = lvp[f] ?? 0;
       }
@@ -250,11 +284,12 @@ export function writeViewUbo(
     viewPayload[237] = fog.maxOpacity;
   }
 
-  const viewUploadResult = queue.writeBuffer(viewUniformBuffer, 0, viewPayload);
+  const viewUploadResult = queue.writeBuffer(viewUniformBuffer, byteOffset, viewPayload);
   if (!viewUploadResult.ok) throw viewUploadResult.error;
 
   for (const snapshot of lights.pointShadow ?? []) {
-    if (snapshot.shadowAtlasLayer < 0 || snapshot.shadowAtlasLayer >= 4) continue;
+    if (snapshot.shadowAtlasLayer < 0 || snapshot.shadowAtlasLayer >= SHADOW_ATLAS_DEFAULT_LAYERS)
+      continue;
     for (let face = 0; face < 6; face += 1) {
       const facePayload = viewPayload.slice();
       const matrix = snapshot.shadowMatrices.subarray(face * 16, (face + 1) * 16);

package/src/reflection/filter.ts

@@ -0,0 +1,81 @@
+export interface ProbeFilterState {
+  readonly probeIndex: number;
+  readonly faceCount: number;
+  readonly mipCount: number;
+  readonly cursor: number;
+  readonly activeGeneration: number;
+}
+
+export function createProbeFilterState(input: {
+  readonly probeIndex: number;
+  readonly faceCount?: number;
+  readonly mipCount: number;
+  readonly activeGeneration?: number;
+}): ProbeFilterState {
+  return {
+    probeIndex: input.probeIndex,
+    faceCount: input.faceCount ?? 6,
+    mipCount: input.mipCount,
+    cursor: 0,
+    activeGeneration: input.activeGeneration ?? 0,
+  };
+}
+
+export function advanceProbeFilter(
+  state: ProbeFilterState,
+):
+  | { readonly probeIndex: number; readonly faceIndex: number; readonly mipLevel: number }
+  | undefined {
+  const total = state.faceCount * state.mipCount;
+  if (state.cursor >= total) return undefined;
+  return {
+    probeIndex: state.probeIndex,
+    faceIndex: state.cursor % state.faceCount,
+    mipLevel: Math.floor(state.cursor / state.faceCount),
+  };
+}
+
+export function commitProbeFilterStep(state: ProbeFilterState, success: boolean): ProbeFilterState {
+  if (!success) return state;
+  const nextCursor = state.cursor + 1;
+  const complete = nextCursor >= state.faceCount * state.mipCount;
+  return {
+    ...state,
+    cursor: nextCursor,
+    activeGeneration: complete ? state.activeGeneration + 1 : state.activeGeneration,
+  };
+}
+
+export function probeFilterIsSteady(state: ProbeFilterState): boolean {
+  return state.cursor >= state.faceCount * state.mipCount;
+}
+
+function normalize(vector: readonly [number, number, number]): [number, number, number] {
+  const length = Math.hypot(vector[0], vector[1], vector[2]);
+  if (length === 0) return [0, 0, 1];
+  return [vector[0] / length, vector[1] / length, vector[2] / length];
+}
+
+export function boxProjectReflectionDirection(
+  direction: readonly [number, number, number],
+  boxCenter: readonly [number, number, number],
+  halfExtents: readonly [number, number, number],
+  point: readonly [number, number, number],
+): [number, number, number] {
+  const ray = normalize(direction);
+  let distance = Number.POSITIVE_INFINITY;
+  for (let axis = 0; axis < 3; axis += 1) {
+    const component = ray[axis] ?? 0;
+    if (component === 0) continue;
+    const extent = halfExtents[axis] ?? 0;
+    const edge = component > 0 ? (boxCenter[axis] ?? 0) + extent : (boxCenter[axis] ?? 0) - extent;
+    const candidate = (edge - (point[axis] ?? 0)) / component;
+    if (candidate > 0) distance = Math.min(distance, candidate);
+  }
+  if (!Number.isFinite(distance)) return ray;
+  return normalize([
+    (point[0] ?? 0) + ray[0] * distance - (boxCenter[0] ?? 0),
+    (point[1] ?? 0) + ray[1] * distance - (boxCenter[1] ?? 0),
+    (point[2] ?? 0) + ray[2] * distance - (boxCenter[2] ?? 0),
+  ]);
+}

package/src/reflection/gpu-table.ts

@@ -0,0 +1,44 @@
+import type { Buffer, Sampler, TextureView } from '@forgeax/engine-rhi';
+
+export interface ReflectionProbeTableRow {
+  readonly primitiveKey?: string;
+  readonly index: number;
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly center: readonly [number, number, number];
+  readonly halfExtents: readonly [number, number, number];
+  readonly intensity: number;
+  readonly generation: number;
+  /** Renderer-owned filtered cube used by the Standard material lane. */
+  readonly filteredView?: TextureView;
+  /** Renderer-owned sampler paired with filteredView. */
+  readonly sampler?: Sampler;
+  /** Per-probe uniform payload; keeps MaterialAsset ABI unchanged. */
+  readonly uniformBuffer?: Buffer;
+}
+
+export interface ReflectionProbeTable {
+  readonly rows: readonly ReflectionProbeTableRow[];
+  readonly cpuIndexByPrimitive: (primitiveKey: string) => number | undefined;
+  readonly gpuIndexByPrimitive: (primitiveKey: string) => number | undefined;
+}
+
+export function buildReflectionProbeTable(
+  rows: readonly ReflectionProbeTableRow[],
+): ReflectionProbeTable {
+  const ordered = rows.slice().sort((a, b) => a.index - b.index);
+  const indices = new Map<string, number>();
+  for (const row of ordered) {
+    if (row.primitiveKey !== undefined) indices.set(row.primitiveKey, row.index);
+  }
+  const indexFor = (primitiveKey: string): number | undefined => indices.get(primitiveKey);
+  return {
+    rows: Object.freeze(ordered),
+    cpuIndexByPrimitive: indexFor,
+    gpuIndexByPrimitive: indexFor,
+  };
+}
+
+export function reflectionProbeTableBytes(table: ReflectionProbeTable): number {
+  return table.rows.length * 48;
+}

package/src/reflection/projection.ts

@@ -0,0 +1,281 @@
+import type { ReflectionProbeUpdateIntent } from '../components/reflection-probe';
+
+export const REFLECTION_PROBE_BYTES_PER_TEXEL = 8;
+export const DEFAULT_REFLECTION_PROBE_LIMITS = Object.freeze({
+  maxProbes: 16,
+  maxResolution: 256,
+  maxBytes: 64 * 1024 * 1024,
+});
+
+export interface ReflectionProbeInput {
+  readonly halfExtents: readonly [number, number, number];
+  readonly priority: number;
+  readonly intensity: number;
+  readonly resolution: number;
+}
+
+export interface ReflectionProbeFact extends ReflectionProbeInput {
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly center: readonly [number, number, number];
+  readonly revision: number;
+  readonly updateIntent?: ReflectionProbeUpdateIntent;
+  readonly invalidationVersion?: number;
+}
+
+export interface ReflectionProbeAdmissionLimits {
+  readonly maxProbes?: number;
+  readonly maxResolution?: number;
+  readonly maxBytes?: number;
+}
+
+export interface ReflectionProbeInvalidInput {
+  readonly code: 'reflection-probe-input-invalid';
+  readonly field: string;
+  readonly value: unknown;
+  readonly expected: string;
+}
+
+export interface ReflectionProbeBudgetFailure {
+  readonly code: 'reflection-probe-budget-exceeded';
+  readonly requested: number;
+  readonly activeCount: number;
+  readonly activeBytes: number;
+  readonly maxProbes: number;
+  readonly maxBytes: number;
+}
+
+export type ReflectionProbeAdmission =
+  | { readonly ok: true; readonly acceptedBytes: number }
+  | { readonly ok: false; readonly error: ReflectionProbeBudgetFailure };
+
+export function validateReflectionProbeInput(
+  input: ReflectionProbeInput,
+): { readonly ok: true } | { readonly ok: false; readonly error: ReflectionProbeInvalidInput } {
+  for (let index = 0; index < input.halfExtents.length; index += 1) {
+    const value = input.halfExtents[index];
+    if (value === undefined || !Number.isFinite(value) || value <= 0) {
+      return {
+        ok: false,
+        error: {
+          code: 'reflection-probe-input-invalid',
+          field: `halfExtents[${index}]`,
+          value,
+          expected: 'a finite number greater than zero',
+        },
+      };
+    }
+  }
+  if (!Number.isFinite(input.priority)) {
+    return {
+      ok: false,
+      error: {
+        code: 'reflection-probe-input-invalid',
+        field: 'priority',
+        value: input.priority,
+        expected: 'a finite number',
+      },
+    };
+  }
+  if (!Number.isFinite(input.intensity) || input.intensity < 0) {
+    return {
+      ok: false,
+      error: {
+        code: 'reflection-probe-input-invalid',
+        field: 'intensity',
+        value: input.intensity,
+        expected: 'a finite number greater than or equal to zero',
+      },
+    };
+  }
+  if (!Number.isInteger(input.resolution) || input.resolution <= 0) {
+    return {
+      ok: false,
+      error: {
+        code: 'reflection-probe-input-invalid',
+        field: 'resolution',
+        value: input.resolution,
+        expected: 'a positive integer',
+      },
+    };
+  }
+  return { ok: true };
+}
+
+export function estimateReflectionProbeBytes(
+  resolution: number,
+  limits: ReflectionProbeAdmissionLimits = DEFAULT_REFLECTION_PROBE_LIMITS,
+): number {
+  const maxResolution = limits.maxResolution ?? DEFAULT_REFLECTION_PROBE_LIMITS.maxResolution;
+  const clamped = Math.min(resolution, maxResolution);
+  let mipTexels = 0;
+  for (let size = clamped; size >= 1; size = Math.floor(size / 2)) {
+    mipTexels += size * size;
+  }
+  return mipTexels * 6 * REFLECTION_PROBE_BYTES_PER_TEXEL;
+}
+
+export function admitReflectionProbe(
+  input: ReflectionProbeInput,
+  current: { readonly acceptedCount: number; readonly acceptedBytes: number },
+  limits: ReflectionProbeAdmissionLimits = DEFAULT_REFLECTION_PROBE_LIMITS,
+): ReflectionProbeAdmission {
+  const maxProbes = limits.maxProbes ?? DEFAULT_REFLECTION_PROBE_LIMITS.maxProbes;
+  const maxBytes = limits.maxBytes ?? DEFAULT_REFLECTION_PROBE_LIMITS.maxBytes;
+  const maxResolution = limits.maxResolution ?? DEFAULT_REFLECTION_PROBE_LIMITS.maxResolution;
+  const requested = estimateReflectionProbeBytes(input.resolution, { maxResolution });
+  if (
+    input.resolution > maxResolution ||
+    current.acceptedCount >= maxProbes ||
+    current.acceptedBytes + requested > maxBytes
+  ) {
+    return {
+      ok: false,
+      error: {
+        code: 'reflection-probe-budget-exceeded',
+        requested,
+        activeCount: current.acceptedCount,
+        activeBytes: current.acceptedBytes,
+        maxProbes,
+        maxBytes,
+      },
+    };
+  }
+  return { ok: true, acceptedBytes: current.acceptedBytes + requested };
+}
+
+export interface ReflectionProbeSelection {
+  readonly kind: 'probe';
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly normalizedDistance: number;
+}
+
+export interface SkylightSelection {
+  readonly kind: 'skylight';
+}
+
+export type ReflectionProbeSelectionResult = ReflectionProbeSelection | SkylightSelection;
+
+function contains(fact: ReflectionProbeFact, point: readonly [number, number, number]): boolean {
+  return fact.halfExtents.every((extent, axis) => {
+    const center = fact.center[axis] ?? 0;
+    const coordinate = point[axis] ?? 0;
+    return Math.abs(coordinate - center) <= extent;
+  });
+}
+
+function normalizedDistance(
+  fact: ReflectionProbeFact,
+  point: readonly [number, number, number],
+): number {
+  let squared = 0;
+  for (let axis = 0; axis < 3; axis += 1) {
+    const delta = (point[axis] ?? 0) - (fact.center[axis] ?? 0);
+    const extent = fact.halfExtents[axis] ?? 1;
+    squared += (delta / extent) ** 2;
+  }
+  return squared;
+}
+
+function isBetter(
+  candidate: ReflectionProbeSelection,
+  current: ReflectionProbeSelection,
+  facts: readonly ReflectionProbeFact[],
+): boolean {
+  const candidateFact = facts.find(
+    (fact) => fact.worldId === candidate.worldId && fact.entityKey === candidate.entityKey,
+  );
+  const currentFact = facts.find(
+    (fact) => fact.worldId === current.worldId && fact.entityKey === current.entityKey,
+  );
+  if (candidateFact === undefined || currentFact === undefined) return false;
+  if (candidateFact.priority !== currentFact.priority)
+    return candidateFact.priority > currentFact.priority;
+  if (candidate.normalizedDistance !== current.normalizedDistance) {
+    return candidate.normalizedDistance < current.normalizedDistance;
+  }
+  return (
+    candidate.worldId < current.worldId ||
+    (candidate.worldId === current.worldId && candidate.entityKey < current.entityKey)
+  );
+}
+
+export function selectReflectionProbe(
+  facts: readonly ReflectionProbeFact[],
+  primitiveCenter: readonly [number, number, number],
+): ReflectionProbeSelectionResult {
+  let selected: ReflectionProbeSelection | undefined;
+  for (const fact of facts) {
+    if (!contains(fact, primitiveCenter)) continue;
+    const candidate: ReflectionProbeSelection = {
+      kind: 'probe',
+      worldId: fact.worldId,
+      entityKey: fact.entityKey,
+      normalizedDistance: normalizedDistance(fact, primitiveCenter),
+    };
+    if (selected === undefined || isBetter(candidate, selected, facts)) selected = candidate;
+  }
+  return selected ?? { kind: 'skylight' };
+}
+
+export interface ReflectionProbePrimitive {
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly center: readonly [number, number, number];
+}
+
+export interface ReflectionProbeProjectionSnapshot {
+  readonly revision: number;
+  readonly facts: readonly ReflectionProbeFact[];
+  readonly selected: ReadonlyMap<string, ReflectionProbeSelectionResult>;
+  readonly scannedPrimitives: number;
+}
+
+function primitiveKey(worldId: number, entityKey: number): string {
+  return `${worldId}:${entityKey}`;
+}
+
+export class ReflectionProbeProjection {
+  private revision = 0;
+  private facts: readonly ReflectionProbeFact[] = [];
+  private selected = new Map<string, ReflectionProbeSelectionResult>();
+  private signature = '';
+  private scannedPrimitives = 0;
+
+  update(
+    facts: readonly ReflectionProbeFact[],
+    primitives: readonly ReflectionProbePrimitive[],
+  ): ReflectionProbeProjectionSnapshot {
+    const nextFacts = facts
+      .slice()
+      .sort((a, b) => a.worldId - b.worldId || a.entityKey - b.entityKey);
+    const signature = JSON.stringify({ facts: nextFacts, primitives });
+    if (signature === this.signature) return this.snapshot();
+    this.signature = signature;
+    this.facts = nextFacts;
+    this.selected = new Map();
+    for (const primitive of primitives) {
+      this.selected.set(
+        primitiveKey(primitive.worldId, primitive.entityKey),
+        selectReflectionProbe(nextFacts, primitive.center),
+      );
+    }
+    this.scannedPrimitives = primitives.length;
+    this.revision += 1;
+    return this.snapshot();
+  }
+
+  snapshot(): ReflectionProbeProjectionSnapshot {
+    return {
+      revision: this.revision,
+      facts: this.facts,
+      selected: this.selected,
+      scannedPrimitives: this.scannedPrimitives,
+    };
+  }
+
+  selection(worldId: number, entityKey: number): ReflectionProbeSelectionResult {
+    return this.selected.get(primitiveKey(worldId, entityKey)) ?? { kind: 'skylight' };
+  }
+}