@hraness/slopcamera 3.2.7 → 3.3.1

package/src/spatial-scene/direction.ts

@@ -0,0 +1,122 @@
+import { z } from "zod"
+
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { SpatialDigestSchema, SpatialTimeUsSchema } from "./contracts.js"
+import { parseSpatialValue, SpatialSceneError, spatialValueSha256 } from "./identity.js"
+
+/**
+ * Strict agent direction documents for Phase 8.
+ * Every proposal is marked and never auto-applied; it emits inspectable
+ * scene/cinema patches and receipts for human or agent review.
+ */
+
+export const SPATIAL_DIRECTION_LIMITS = Object.freeze({
+  actions: 256,
+  beats: 64,
+  coverage: 64,
+  durationUs: 3_600_000_000,
+  looks: 32,
+})
+
+const directionId = z.string().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/u)
+const referenceId = z.string().min(1).max(128).regex(/^[a-z][a-z0-9_-]*$/u)
+const intervalShape = {
+  endUs: SpatialTimeUsSchema.max(SPATIAL_DIRECTION_LIMITS.durationUs),
+  startUs: SpatialTimeUsSchema.max(SPATIAL_DIRECTION_LIMITS.durationUs),
+}
+
+export const SpatialDramaticBeatSchema = z.strictObject({
+  id: directionId,
+  ...intervalShape,
+  intent: z.string().trim().min(1).max(256),
+  emotion: z.string().trim().min(1).max(64),
+  verified: z.boolean().default(false),
+})
+
+export const SpatialCharacterActionSchema = z.strictObject({
+  id: directionId,
+  characterId: referenceId,
+  ...intervalShape,
+  action: z.enum(["idle", "walk", "run", "turn", "gesture", "interact", "morph"]),
+  targetId: referenceId.optional(),
+  verified: z.boolean().default(false),
+})
+
+export const SpatialCameraCoverageSchema = z.strictObject({
+  id: directionId,
+  ...intervalShape,
+  rigKind: z.enum(["chase", "crane", "dolly", "handheld", "orbit", "rail", "target-tracking", "tripod"]),
+  framing: z.enum(["extreme-close-up", "close-up", "medium-close-up", "medium", "medium-wide", "wide", "extreme-wide", "over-shoulder", "insert"]),
+  screenDirection: z.enum(["left", "right", "neutral"]).optional(),
+  subjectId: referenceId.optional(),
+  verified: z.boolean().default(false),
+})
+
+export const SpatialLookIntentSchema = z.strictObject({
+  id: directionId,
+  ...intervalShape,
+  lighting: z.string().trim().min(1).max(128),
+  atmosphere: z.string().trim().min(1).max(128),
+  verified: z.boolean().default(false),
+})
+
+export const SpatialDirectionSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-direction"),
+  schemaVersion: z.literal(1),
+  entityId: referenceId,
+  projectDigest: SpatialDigestSchema,
+  beats: z.array(SpatialDramaticBeatSchema).max(SPATIAL_DIRECTION_LIMITS.beats),
+  actions: z.array(SpatialCharacterActionSchema).max(SPATIAL_DIRECTION_LIMITS.actions),
+  coverage: z.array(SpatialCameraCoverageSchema).max(SPATIAL_DIRECTION_LIMITS.coverage),
+  looks: z.array(SpatialLookIntentSchema).max(SPATIAL_DIRECTION_LIMITS.looks),
+}).superRefine((direction, context) => {
+  const ids = new Set<string>()
+  for (const [collectionName, values] of [
+    ["beats", direction.beats],
+    ["actions", direction.actions],
+    ["coverage", direction.coverage],
+    ["looks", direction.looks],
+  ] as const) {
+    let previousStartUs = -1
+    let previousId = ""
+    for (const [index, value] of values.entries()) {
+      if (value.endUs <= value.startUs) {
+        context.addIssue({ code: "custom", path: [collectionName, index, "endUs"], message: "Direction intervals must have positive duration." })
+      }
+      if (ids.has(value.id)) {
+        context.addIssue({ code: "custom", path: [collectionName, index, "id"], message: `Direction id ${value.id} must be globally unique.` })
+      }
+      ids.add(value.id)
+      if (value.startUs < previousStartUs || value.startUs === previousStartUs && value.id.localeCompare(previousId) <= 0) {
+        context.addIssue({ code: "custom", path: [collectionName, index], message: "Direction entries must be ordered by startUs then id." })
+      }
+      previousStartUs = value.startUs
+      previousId = value.id
+    }
+  }
+  for (const [index, action] of direction.actions.entries()) {
+    if ((action.action === "interact") !== (action.targetId !== undefined)) {
+      context.addIssue({ code: "custom", path: ["actions", index, "targetId"], message: "Only interact actions require a targetId." })
+    }
+  }
+  for (let index = 1; index < direction.coverage.length; index += 1) {
+    if (direction.coverage[index]!.startUs < direction.coverage[index - 1]!.endUs) {
+      context.addIssue({ code: "custom", path: ["coverage", index], message: "Camera coverage intervals must not overlap." })
+    }
+  }
+})
+
+export type SpatialDirection = Readonly<z.infer<typeof SpatialDirectionSchema>>
+
+export function parseSpatialDirection(input: unknown): SpatialDirection {
+  try {
+    return deepFreezeJson(parseSpatialValue(SpatialDirectionSchema, input, "direction"))
+  } catch (error) {
+    if (error instanceof SpatialSceneError) throw error
+    throw new SpatialSceneError("invalid-data", error instanceof Error ? error.message : String(error), "direction")
+  }
+}
+
+export function spatialDirectionSha256(direction: SpatialDirection): string {
+  return spatialValueSha256(direction)
+}

package/src/spatial-scene/effects.ts

@@ -0,0 +1,149 @@
+import { z } from "zod"
+
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { SpatialAssetIdSchema } from "./contracts.js"
+import { parseSpatialValue, SpatialSceneError, spatialValueSha256 } from "./identity.js"
+
+export const positiveDimension = z.number().finite().positive().max(1_000_000)
+export const unit = z.number().finite().min(0).max(1)
+
+/**
+ * Bounded post-processing and render-quality contracts for Phase 7.
+ * Beauty finishing passes are lowered behind the desktop host; diagnostic
+ * AOVs (object-ID, depth, motion) never pass through these operators.
+ */
+
+export const SPATIAL_EFFECT_LIMITS = Object.freeze({
+  dust: 500_000,
+  embers: 1_000_000,
+  luts: 4,
+  outputBytes: 8_000_000_000,
+  postProcessStack: 8,
+  previewParticles: 100_000,
+  rain: 100_000,
+  renderPixels: 67_108_864,
+  simulationFrames: 10_000,
+  simulationSteps: 10_000,
+  texturePixels: 268_435_456,
+})
+
+const boundedPixels = z.number().int().safe().positive()
+
+export const SpatialRenderQualitySchema = z.strictObject({
+  outputBytes: z.number().int().safe().positive().max(SPATIAL_EFFECT_LIMITS.outputBytes),
+  particleCount: z.number().int().safe().min(0).max(SPATIAL_EFFECT_LIMITS.embers),
+  pixelBudget: boundedPixels.max(SPATIAL_EFFECT_LIMITS.renderPixels),
+  simulationSteps: z.number().int().safe().min(0).max(SPATIAL_EFFECT_LIMITS.simulationSteps),
+  texturePixelBudget: boundedPixels.max(SPATIAL_EFFECT_LIMITS.texturePixels),
+  tier: z.enum(["preview", "final"]),
+})
+
+export const SpatialBloomSchema = z.strictObject({
+  intensity: unit,
+  kind: z.literal("bloom"),
+  radius: z.number().finite().min(0).max(64),
+  threshold: unit,
+})
+
+export const SpatialDepthOfFieldSchema = z.strictObject({
+  aperture: z.number().finite().positive().max(256),
+  focalLength: z.number().finite().positive().max(10_000),
+  focusDistance: positiveDimension,
+  kind: z.literal("depth-of-field"),
+})
+
+export const SpatialMotionBlurSchema = z.strictObject({
+  kind: z.literal("motion-blur"),
+  samples: z.number().int().min(1).max(64),
+  shutterAngle: z.number().finite().min(0).max(360),
+})
+
+export const SpatialToneMapSchema = z.strictObject({
+  exposure: z.number().finite().min(-20).max(20),
+  kind: z.literal("tone-map"),
+  whitePoint: z.number().finite().positive().max(1_000_000),
+})
+
+export const SpatialVignetteSchema = z.strictObject({
+  intensity: unit,
+  kind: z.literal("vignette"),
+  radius: unit,
+})
+
+export const SpatialChromaticAberrationSchema = z.strictObject({
+  kind: z.literal("chromatic-aberration"),
+  offsetPixels: z.number().finite().min(0).max(64),
+  radialFalloff: unit,
+})
+
+export const SpatialGrainSchema = z.strictObject({
+  intensity: unit,
+  kind: z.literal("grain"),
+  seed: z.number().int().min(0).max(2_147_483_647),
+})
+
+export const SpatialFlareSchema = z.strictObject({
+  ghosts: z.number().int().min(0).max(16),
+  haloWidth: unit,
+  intensity: unit,
+  kind: z.literal("flare"),
+  threshold: unit,
+})
+
+export const SpatialLutGradeSchema = z.strictObject({
+  assetId: SpatialAssetIdSchema,
+  intensity: unit,
+  kind: z.literal("lut-grade"),
+})
+
+export const SpatialPostProcessStepSchema = z.discriminatedUnion("kind", [
+  SpatialBloomSchema,
+  SpatialDepthOfFieldSchema,
+  SpatialMotionBlurSchema,
+  SpatialToneMapSchema,
+  SpatialVignetteSchema,
+  SpatialChromaticAberrationSchema,
+  SpatialGrainSchema,
+  SpatialFlareSchema,
+  SpatialLutGradeSchema,
+])
+
+export const SpatialPostProcessStackSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-post-process"),
+  schemaVersion: z.literal(1),
+  steps: z.array(SpatialPostProcessStepSchema).min(1).max(SPATIAL_EFFECT_LIMITS.postProcessStack),
+}).superRefine((stack, context) => {
+  if (stack.steps.filter(step => step.kind === "lut-grade").length > SPATIAL_EFFECT_LIMITS.luts) {
+    context.addIssue({ code: "custom", path: ["steps"], message: `Post-process stacks support at most ${SPATIAL_EFFECT_LIMITS.luts} LUT grades.` })
+  }
+})
+
+export const SpatialRenderPlanSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-render-plan"),
+  postProcess: SpatialPostProcessStackSchema.optional(),
+  quality: SpatialRenderQualitySchema,
+  schemaVersion: z.literal(1),
+})
+
+export type SpatialRenderQuality = Readonly<z.infer<typeof SpatialRenderQualitySchema>>
+export type SpatialPostProcessStack = Readonly<z.infer<typeof SpatialPostProcessStackSchema>>
+export type SpatialRenderPlan = Readonly<z.infer<typeof SpatialRenderPlanSchema>>
+
+export function parseSpatialRenderPlan(input: unknown): SpatialRenderPlan {
+  const plan = parseSpatialValue(SpatialRenderPlanSchema, input, "render plan")
+  if (plan.quality.tier === "preview" && plan.quality.particleCount > SPATIAL_EFFECT_LIMITS.previewParticles) {
+    throw new SpatialSceneError("invalid-data", `Preview tier cannot request more than ${SPATIAL_EFFECT_LIMITS.previewParticles.toLocaleString("en-US")} particles.`, "render-plan.quality.particleCount")
+  }
+  if (plan.quality.outputBytes < plan.quality.particleCount * 64) {
+    throw new SpatialSceneError("invalid-data", "Output byte budget is too small for declared particle count.", "render-plan.quality.outputBytes")
+  }
+  return deepFreezeJson(plan)
+}
+
+export function spatialRenderPlanAssetIds(plan: SpatialRenderPlan): readonly string[] {
+  return Object.freeze([...new Set(plan.postProcess?.steps.flatMap(step => step.kind === "lut-grade" ? [step.assetId] : []) ?? [])].sort())
+}
+
+export function spatialRenderPlanSha256(plan: SpatialRenderPlan): string {
+  return spatialValueSha256(plan)
+}

package/src/spatial-scene/evaluate.ts

@@ -4,7 +4,7 @@ import {
   EvaluatedSpatialSceneSchema, SPATIAL_SCENE_LIMITS, SpatialCameraIdSchema, SpatialOverrideSchema, SpatialPoseSchema,
   SpatialShotV1Schema, SpatialTimeUsSchema,
   type EvaluatedSpatialScene, type SpatialAnimation, type SpatialCamera, type SpatialEntity,
-  type SpatialOverride, type SpatialPose, type SpatialShotV1,
+  type SpatialOverride, type SpatialPose, type SpatialSceneV1, type SpatialShotV1,
 } from "./contracts.js"
 import {
   parseSpatialScene, parseSpatialValue, sortSpatialBy, spatialAssetClosureDigests,
@@ -19,6 +19,38 @@ export interface EvaluateSpatialSceneOptions {
   readonly cameraPoseOverride?: SpatialPose
 }
 
+/**
+ * Immutable per-scene evaluation context: every index, ordering, digest and
+ * merged-override value that absolute-time evaluation re-derives identically
+ * for each sample. Built once by `createSpatialEvaluationContext`, then shared
+ * by any number of `evaluateSpatialSceneInContext` calls — audits, renders and
+ * camera tracks sample one scene repeatedly, so the parse and indexing happen
+ * once per scene rather than once per sample.
+ *
+ * The context is the optional memo seam of `evaluateSpatialScene`; both public
+ * signatures and snapshot bytes are unchanged whether or not a caller builds
+ * one. Treat it as opaque and immutable: it shares the parsed scene's frozen
+ * values and must never be mutated between calls.
+ */
+export interface SpatialEvaluationContext {
+  /** The parsed, normalized, deep-frozen scene this context is bound to. */
+  readonly scene: SpatialSceneV1
+  readonly sceneSha256: string
+  readonly entitiesById: ReadonlyMap<string, SpatialEntity>
+  readonly camerasById: ReadonlyMap<string, SpatialCamera>
+  /** Entity ids in parent-before-child order; hierarchy is evaluation-invariant. */
+  readonly entityOrder: readonly string[]
+  /** Effective authored visibility; channels and overrides never write `visible`. */
+  readonly visibilityById: ReadonlyMap<string, boolean>
+  /** Animation channels targeting entities, in canonical order. */
+  readonly entityChannels: readonly SpatialAnimation[]
+  /** Animation channels targeting cameras, keyed by camera id. */
+  readonly cameraChannelsById: ReadonlyMap<string, readonly SpatialAnimation[]>
+  /** Scene-level overrides already merged and validated by the scene parse. */
+  readonly baseOverrides: readonly SpatialOverride[]
+  readonly assetDigests: Readonly<Record<string, string>>
+}
+
 const EvaluatedOptionsSchema = z.strictObject({
   timeUs: SpatialTimeUsSchema, cameraId: SpatialCameraIdSchema,
   overrides: z.array(SpatialOverrideSchema).max(SPATIAL_SCENE_LIMITS.entities).optional(),
@@ -74,20 +106,62 @@ function sampleChannel(channel: SpatialAnimation, timeUs: number): number | read
 }
 
 export function validateSpatialShot(sceneInput: unknown, shotInput: unknown): SpatialShotV1 {
-  const scene = parseSpatialScene(sceneInput)
+  const context = createSpatialEvaluationContext(sceneInput)
+  const scene = context.scene
   const shot = parseSpatialValue(SpatialShotV1Schema, shotInput, "shot")
-  if (shot.sceneSha256 !== spatialValueSha256(scene)) throw new SpatialSceneError("conflict", "Shot pins another scene revision.", "shot.sceneSha256")
-  if (!scene.cameras.some(camera => camera.cameraId === shot.cameraId)) throw new SpatialSceneError("invalid-data", "Shot camera is absent from its scene.", "shot.cameraId")
+  if (shot.sceneSha256 !== context.sceneSha256) throw new SpatialSceneError("conflict", "Shot pins another scene revision.", "shot.sceneSha256")
+  if (!context.camerasById.has(shot.cameraId)) throw new SpatialSceneError("invalid-data", "Shot camera is absent from its scene.", "shot.cameraId")
   if (shot.sceneStartUs >= scene.durationUs) throw new SpatialSceneError("invalid-data", "Shot scene start must precede scene duration.", "shot.sceneStartUs")
   if (shot.playback === "once" && shot.sceneStartUs + shot.range.endUs - shot.range.startUs > scene.durationUs) throw new SpatialSceneError("invalid-data", "Once playback exceeds scene duration.", "shot.range")
   validateSpatialOverrides(scene, mergeSpatialOverrides(scene.overrides, shot.overrides))
-  if (shot.cameraPoseOverride && scene.animations.some(channel => channel.targetId === shot.cameraId)) throw new SpatialSceneError("conflict", "Camera animation and shot pose override both own camera pose.", "shot.cameraPoseOverride")
+  if (shot.cameraPoseOverride && context.cameraChannelsById.has(shot.cameraId)) throw new SpatialSceneError("conflict", "Camera animation and shot pose override both own camera pose.", "shot.cameraPoseOverride")
   return deepFreezeJson(shot)
 }
 
-/** Absolute time evaluation produces one immutable snapshot; calls share no mutable state. */
-export function evaluateSpatialScene(sceneInput: unknown, options: EvaluateSpatialSceneOptions): EvaluatedSpatialScene {
+/**
+ * Parses and indexes a scene once so repeated absolute-time evaluations share
+ * the constant work: entity and camera lookup maps, the parent-before-child
+ * entity order, effective authored visibility, per-target channel lists, merged
+ * scene-level overrides, the asset closure digests and the scene digest.
+ * The result is immutable; callers never mutate it and may share it across any
+ * number of `evaluateSpatialSceneInContext` calls and audit runs.
+ */
+export function createSpatialEvaluationContext(sceneInput: unknown): SpatialEvaluationContext {
   const scene = parseSpatialScene(sceneInput)
+  const entitiesById = new Map(scene.entities.map(entity => [entity.entityId, entity]))
+  const camerasById = new Map(scene.cameras.map(camera => [camera.cameraId, camera]))
+  const entityOrder = spatialTopologicalIds(new Map(scene.entities.map(entity => [entity.entityId, entity.parentId === null ? [] : [entity.parentId]])), "entity hierarchy")
+  const visibilityById = new Map<string, boolean>()
+  for (const id of entityOrder) {
+    const entity = entitiesById.get(id)!
+    visibilityById.set(id, entity.visible && (entity.parentId === null || visibilityById.get(entity.parentId) === true))
+  }
+  const entityChannels: SpatialAnimation[] = []
+  const cameraChannelsById = new Map<string, SpatialAnimation[]>()
+  for (const channel of scene.animations) {
+    if (entitiesById.has(channel.targetId)) entityChannels.push(channel)
+    else {
+      const list = cameraChannelsById.get(channel.targetId) ?? []
+      list.push(channel)
+      cameraChannelsById.set(channel.targetId, list)
+    }
+  }
+  return Object.freeze({
+    scene, sceneSha256: spatialValueSha256(scene), entitiesById, camerasById,
+    entityOrder, visibilityById, entityChannels,
+    cameraChannelsById, baseOverrides: mergeSpatialOverrides(scene.overrides, []),
+    assetDigests: spatialAssetClosureDigests(scene.assets),
+  })
+}
+
+/**
+ * Evaluates one immutable snapshot against a shared evaluation context. This is
+ * the hot path `evaluateSpatialScene` delegates to after building the context;
+ * per-sample work is channel sampling, transform composition and the emitted
+ * snapshot's own identity, schema parse and freeze.
+ */
+export function evaluateSpatialSceneInContext(context: SpatialEvaluationContext, options: EvaluateSpatialSceneOptions): EvaluatedSpatialScene {
+  const scene = context.scene
   // Capture the complete options object before inspecting optional properties.
   const capturedOptions = parseSpatialValue(
     // Explicit object schema also rejects unsupported simulation or executable fields.
@@ -95,29 +169,31 @@ export function evaluateSpatialScene(sceneInput: unknown, options: EvaluateSpati
   )
   const timeUs = capturedOptions.timeUs
   if (timeUs > scene.durationUs) throw new SpatialSceneError("invalid-data", "Evaluation time exceeds scene duration.", "timeUs")
-  let camera = scene.cameras.find(item => item.cameraId === capturedOptions.cameraId)
+  let camera = context.camerasById.get(capturedOptions.cameraId)
   if (!camera) throw new SpatialSceneError("not-found", `Unknown camera ${capturedOptions.cameraId}.`, "cameraId")
-  const overrides = mergeSpatialOverrides(scene.overrides, capturedOptions.overrides ?? [])
-  validateSpatialOverrides(scene, overrides)
-  if (capturedOptions.cameraPoseOverride && scene.animations.some(channel => channel.targetId === camera!.cameraId)) throw new SpatialSceneError("conflict", "Camera animation conflicts with camera pose override.", "cameraPoseOverride")
-  const entities = new Map(scene.entities.map(entity => [entity.entityId, entity]))
-  for (const channel of scene.animations) {
+  // Without per-call overrides the merged scene-level set is a context constant
+  // already validated by the scene parse; per-call overrides re-merge and
+  // re-validate against the parsed scene exactly as a standalone call would.
+  const overrides = capturedOptions.overrides === undefined ? context.baseOverrides : mergeSpatialOverrides(scene.overrides, capturedOptions.overrides)
+  if (capturedOptions.overrides !== undefined) validateSpatialOverrides(scene, overrides)
+  if (capturedOptions.cameraPoseOverride && context.cameraChannelsById.has(camera.cameraId)) throw new SpatialSceneError("conflict", "Camera animation conflicts with camera pose override.", "cameraPoseOverride")
+  const entities = new Map(context.entitiesById)
+  // Entity and camera channels write disjoint slots, so applying the entity
+  // subset first and then this camera's channels matches interleaved order.
+  for (const channel of context.entityChannels) {
     const value = sampleChannel(channel, timeUs)
-    if (channel.targetId === camera.cameraId) {
-      camera = { ...camera, pose: { ...camera.pose, [channel.property]: value } } as SpatialCamera
-    } else {
-      const entity = entities.get(channel.targetId)
-      if (!entity) continue // Other cameras do not affect the requested view.
-      if (channel.property === "opacity") entities.set(entity.entityId, applySpatialEntityOverride(entity, { entityId: entity.entityId, property: "opacity", value: value as number }))
-      else entities.set(entity.entityId, { ...entity, transform: { ...entity.transform, [channel.property]: value } } as SpatialEntity)
-    }
+    const entity = entities.get(channel.targetId)!
+    if (channel.property === "opacity") entities.set(entity.entityId, applySpatialEntityOverride(entity, { entityId: entity.entityId, property: "opacity", value: value as number }))
+    else entities.set(entity.entityId, { ...entity, transform: { ...entity.transform, [channel.property]: value } } as SpatialEntity)
+  }
+  for (const channel of context.cameraChannelsById.get(camera.cameraId) ?? []) {
+    const value = sampleChannel(channel, timeUs)
+    camera = { ...camera, pose: { ...camera.pose, [channel.property]: value } } as SpatialCamera
   }
   for (const override of overrides) entities.set(override.entityId, applySpatialEntityOverride(entities.get(override.entityId)!, override))
   if (capturedOptions.cameraPoseOverride) camera = { ...camera, pose: capturedOptions.cameraPoseOverride }
   const matrices = new Map<string, Mat4>()
-  const visibility = new Map<string, boolean>()
-  const order = spatialTopologicalIds(new Map(scene.entities.map(entity => [entity.entityId, entity.parentId === null ? [] : [entity.parentId]])), "entity hierarchy")
-  for (const id of order) {
+  for (const id of context.entityOrder) {
     const entity = entities.get(id)!
     try {
       const local = composeTransform(entity.transform)
@@ -125,21 +201,25 @@ export function evaluateSpatialScene(sceneInput: unknown, options: EvaluateSpati
     } catch (error) {
       throw new SpatialSceneError("invalid-data", error instanceof Error ? error.message : "Invalid evaluated transform.", `entities.${id}.transform`)
     }
-    visibility.set(id, entity.visible && (entity.parentId === null || visibility.get(entity.parentId) === true))
   }
   const evaluated = scene.entities.map((source, index) => ({
     entity: entities.get(source.entityId)!, worldMatrix: matrices.get(source.entityId)!,
-    visible: visibility.get(source.entityId)!, selectionId: index + 1,
+    visible: context.visibilityById.get(source.entityId)!, selectionId: index + 1,
   }))
   // The state identity excludes camera choice, camera pose, asset locator and provenance.
-  const assetDigests = spatialAssetClosureDigests(scene.assets)
-  const stateSha256 = spatialStateValueSha256({ domain: "slopcamera.spatial-state.v1", timeUs, entities: evaluated, assetDigests })
+  const stateSha256 = spatialStateValueSha256({ domain: "slopcamera.spatial-state.v1", timeUs, entities: evaluated, assetDigests: context.assetDigests })
   const viewSha256 = spatialValueSha256({ domain: "slopcamera.spatial-view.v1", stateSha256, camera })
   const result = EvaluatedSpatialSceneSchema.parse({
-    kind: "slopcamera.spatial-snapshot", schemaVersion: 1, sceneSha256: spatialValueSha256(scene),
+    kind: "slopcamera.spatial-snapshot", schemaVersion: 1, sceneSha256: context.sceneSha256,
     stateSha256, viewSha256, timeUs, camera,
     entities: evaluated.map(item => ({ ...item, visible: item.visible && (item.entity.placement.kind === "world" || item.entity.placement.cameraId === camera.cameraId) })),
     assets: scene.assets,
+    ...(scene.fog === undefined ? {} : { fog: scene.fog }),
   })
   return deepFreezeJson(result)
 }
+
+/** Absolute time evaluation produces one immutable snapshot; calls share no mutable state. */
+export function evaluateSpatialScene(sceneInput: unknown, options: EvaluateSpatialSceneOptions): EvaluatedSpatialScene {
+  return evaluateSpatialSceneInContext(createSpatialEvaluationContext(sceneInput), options)
+}