@hraness/slopcamera 3.2.7 → 3.3.1

package/src/spatial-scene/particle-preparation.ts

@@ -0,0 +1,183 @@
+import { z } from "zod"
+
+import { createSha256HexHasher } from "../code/sha256.js"
+import { SpatialAssetIdSchema, SpatialTimeUsSchema } from "./contracts.js"
+import { parseSpatialValue } from "./identity.js"
+import { parseSpatialParticleSystem, spatialParticleSystemSha256, type SpatialParticleSystem } from "./particle.js"
+
+export const SPATIAL_PARTICLE_INSTANCE_STRIDE_BYTES = 64
+export const SPATIAL_PARTICLE_PREPARATION_LIMITS = Object.freeze({ surfaceSets: 64, trianglesPerSurface: 100_000 })
+
+const coordinate = z.number().finite().min(-1_000_000).max(1_000_000)
+const vec3 = z.tuple([coordinate, coordinate, coordinate])
+const surfaceSchema = z.strictObject({
+  assetId: SpatialAssetIdSchema,
+  triangles: z.array(z.tuple([vec3, vec3, vec3])).min(1).max(SPATIAL_PARTICLE_PREPARATION_LIMITS.trianglesPerSurface),
+})
+const inputSchema = z.strictObject({
+  sampleTimeUs: SpatialTimeUsSchema,
+  surfaces: z.array(surfaceSchema).max(SPATIAL_PARTICLE_PREPARATION_LIMITS.surfaceSets).default([]),
+  system: z.unknown(),
+})
+
+export interface SpatialPreparedParticleInstances {
+  readonly bytes: Uint8Array
+  readonly byteLength: number
+  readonly instanceCount: number
+  readonly sha256: string
+  readonly strideBytes: typeof SPATIAL_PARTICLE_INSTANCE_STRIDE_BYTES
+  readonly systemSha256: string
+  readonly sampleTimeUs: number
+}
+
+type Vec3 = readonly [number, number, number]
+type Random = () => number
+
+function randomGenerator(seed: number): Random {
+  let state = seed >>> 0 || 0x6d2b79f5
+  return () => {
+    state = Math.imul(state ^ state >>> 15, state | 1)
+    state ^= state + Math.imul(state ^ state >>> 7, state | 61)
+    return ((state ^ state >>> 14) >>> 0) / 4_294_967_296
+  }
+}
+
+function particleSeed(seed: number, index: number): number {
+  let value = (seed ^ Math.imul(index + 1, 0x9e3779b1)) >>> 0
+  value = Math.imul(value ^ value >>> 16, 0x85ebca6b)
+  value = Math.imul(value ^ value >>> 13, 0xc2b2ae35)
+  return (value ^ value >>> 16) >>> 0
+}
+
+function interpolate(keys: readonly { readonly t: number; readonly value: number }[], t: number): number {
+  const upper = keys.findIndex(key => key.t >= t)
+  if (upper <= 0) return keys[0]!.value
+  const left = keys[upper - 1]!, right = keys[upper]!
+  const amount = (t - left.t) / (right.t - left.t)
+  return left.value + (right.value - left.value) * amount
+}
+
+function interpolateColor(keys: readonly { readonly t: number; readonly color: readonly [number, number, number, number] }[], t: number): readonly [number, number, number, number] {
+  const upper = keys.findIndex(key => key.t >= t)
+  if (upper <= 0) return keys[0]!.color
+  const left = keys[upper - 1]!, right = keys[upper]!
+  const amount = (t - left.t) / (right.t - left.t)
+  return [0, 1, 2, 3].map(index => left.color[index]! + (right.color[index]! - left.color[index]!) * amount) as [number, number, number, number]
+}
+
+function normalize(value: Vec3): Vec3 {
+  const length = Math.hypot(...value)
+  return length === 0 ? [0, 0, 0] : [value[0] / length, value[1] / length, value[2] / length]
+}
+
+function cross(left: Vec3, right: Vec3): Vec3 {
+  return [left[1] * right[2] - left[2] * right[1], left[2] * right[0] - left[0] * right[2], left[0] * right[1] - left[1] * right[0]]
+}
+
+function addScaled(target: [number, number, number], value: Vec3, scale = 1): void {
+  target[0] += value[0] * scale
+  target[1] += value[1] * scale
+  target[2] += value[2] * scale
+}
+
+function sampleSphere(random: Random, radius: number, volume: boolean): Vec3 {
+  const z = random() * 2 - 1
+  const angle = random() * Math.PI * 2
+  const radial = radius * (volume ? Math.cbrt(random()) : 1)
+  const planar = Math.sqrt(1 - z * z)
+  return [radial * planar * Math.cos(angle), radial * z, radial * planar * Math.sin(angle)]
+}
+
+function trianglePoint(triangle: readonly [Vec3, Vec3, Vec3], random: Random): Vec3 {
+  const first = Math.sqrt(random()), second = random()
+  const a = 1 - first, b = first * (1 - second), c = first * second
+  return [triangle[0][0] * a + triangle[1][0] * b + triangle[2][0] * c, triangle[0][1] * a + triangle[1][1] * b + triangle[2][1] * c, triangle[0][2] * a + triangle[1][2] * b + triangle[2][2] * c]
+}
+
+function shapePosition(shape: SpatialParticleSystem["emitters"][number]["shape"], random: Random, surfaces: ReadonlyMap<string, readonly (readonly [Vec3, Vec3, Vec3])[]>): Vec3 {
+  if (shape.kind === "point") return [0, 0, 0]
+  if (shape.kind === "sphere") return sampleSphere(random, shape.radius, shape.volume)
+  if (shape.kind === "box") {
+    const point: Vec3 = [(random() - 0.5) * shape.size[0], (random() - 0.5) * shape.size[1], (random() - 0.5) * shape.size[2]]
+    if (shape.volume) return point
+    const axis = Math.floor(random() * 3), sign = random() < 0.5 ? -0.5 : 0.5
+    return point.map((value, index) => index === axis ? shape.size[index]! * sign : value) as [number, number, number]
+  }
+  if (shape.kind === "disc") {
+    const angle = random() * Math.PI * 2, radius = Math.sqrt(random()) * shape.radius
+    return [Math.cos(angle) * radius, 0, Math.sin(angle) * radius]
+  }
+  if (shape.kind === "spline") {
+    const scaled = random() * (shape.controlPoints.length - 1), index = Math.min(shape.controlPoints.length - 2, Math.floor(scaled)), amount = scaled - index
+    const left = shape.controlPoints[index]!, right = shape.controlPoints[index + 1]!
+    return [left[0] + (right[0] - left[0]) * amount, left[1] + (right[1] - left[1]) * amount, left[2] + (right[2] - left[2]) * amount]
+  }
+  const triangles = surfaces.get(shape.assetId)
+  if (triangles === undefined) throw new RangeError(`Particle surface ${shape.assetId} has no prepared triangle set.`)
+  return trianglePoint(triangles[Math.floor(random() * triangles.length)]!, random)
+}
+
+function inside(position: Vec3, volume: SpatialParticleSystem["killVolumes"][number]): boolean {
+  if (volume.kind === "box") return position.every((value, index) => value >= volume.min[index]! && value <= volume.max[index]!)
+  return Math.hypot(position[0] - volume.center[0], position[1] - volume.center[1], position[2] - volume.center[2]) <= volume.radius
+}
+
+export function prepareSpatialParticleInstances(input: unknown): SpatialPreparedParticleInstances {
+  const parsed = parseSpatialValue(inputSchema, input, "particle preparation")
+  const system = parseSpatialParticleSystem(parsed.system)
+  const surfaces = new Map<string, readonly (readonly [Vec3, Vec3, Vec3])[]>()
+  for (const surface of parsed.surfaces) {
+    if (surfaces.has(surface.assetId)) throw new RangeError(`Duplicate particle surface ${surface.assetId}.`)
+    surfaces.set(surface.assetId, surface.triangles)
+  }
+  const capacity = new Uint8Array(system.maxCount * SPATIAL_PARTICLE_INSTANCE_STRIDE_BYTES)
+  const view = new DataView(capacity.buffer)
+  let instanceCount = 0
+  const sampleSeconds = parsed.sampleTimeUs / 1_000_000
+  for (const [emitterIndex, emitter] of system.emitters.entries()) {
+    if (!emitter.enabled) continue
+    const maximumLifetimeSeconds = emitter.lifetimeUs[1] / 1_000_000
+    const firstContinuous = Math.max(0, Math.floor((sampleSeconds - maximumLifetimeSeconds) * emitter.rate))
+    const lastContinuous = Math.floor(sampleSeconds * emitter.rate)
+    const births: { index: number; time: number }[] = []
+    for (let index = firstContinuous; index < lastContinuous; index += 1) births.push({ index, time: index / emitter.rate })
+    for (let index = 0; index < (emitter.burst ?? 0); index += 1) births.push({ index: -(index + 1), time: 0 })
+    for (const birth of births) {
+      const random = randomGenerator(particleSeed(emitter.seed, birth.index))
+      const lifetimeSeconds = (emitter.lifetimeUs[0] + random() * (emitter.lifetimeUs[1] - emitter.lifetimeUs[0])) / 1_000_000
+      const ageSeconds = sampleSeconds - birth.time
+      if (ageSeconds < 0 || ageSeconds >= lifetimeSeconds) continue
+      const base = shapePosition(emitter.shape, random, surfaces)
+      const initialVelocity: Vec3 = emitter.velocity.map((value, index) => value + (random() * 2 - 1) * emitter.velocitySpread[index]!) as [number, number, number]
+      const acceleration: [number, number, number] = [0, 0, 0]
+      let drag = 0
+      for (const force of system.forces) {
+        if (force.kind === "gravity") addScaled(acceleration, force.acceleration)
+        else if (force.kind === "drag") drag += force.coefficient
+        else if (force.kind === "vortex") addScaled(acceleration, normalize(cross(normalize(force.axis), base)), force.strength)
+        else {
+          const turbulence = randomGenerator(particleSeed(force.seed, birth.index + Math.round(force.scale * 1000)))
+          addScaled(acceleration, normalize([turbulence() * 2 - 1, turbulence() * 2 - 1, turbulence() * 2 - 1]), force.strength)
+        }
+      }
+      const damping = drag === 0 ? 1 : Math.exp(-drag * ageSeconds)
+      const position = base.map((value, index) => value + initialVelocity[index]! * ageSeconds * damping + 0.5 * acceleration[index]! * ageSeconds * ageSeconds) as [number, number, number]
+      if (system.killVolumes.some(volume => inside(position, volume))) continue
+      const velocity = initialVelocity.map((value, index) => value * damping + acceleration[index]! * ageSeconds) as [number, number, number]
+      const normalizedAge = ageSeconds / lifetimeSeconds
+      const color = interpolateColor(emitter.colorOverLife, normalizedAge)
+      if (instanceCount >= system.maxCount) throw new RangeError(`Prepared particle count exceeds maxCount ${system.maxCount}.`)
+      const row = [
+        ...position, ageSeconds,
+        ...velocity, lifetimeSeconds,
+        interpolate(emitter.sizeOverLife.keys, normalizedAge), interpolate(emitter.opacityOverLife.keys, normalizedAge),
+        ...color, random(), emitterIndex,
+      ]
+      row.forEach((value, column) => view.setFloat32(instanceCount * SPATIAL_PARTICLE_INSTANCE_STRIDE_BYTES + column * 4, value, true))
+      instanceCount += 1
+    }
+  }
+  const bytes = capacity.slice(0, instanceCount * SPATIAL_PARTICLE_INSTANCE_STRIDE_BYTES)
+  const hasher = createSha256HexHasher(); hasher.update(bytes)
+  return Object.freeze({ bytes, byteLength: bytes.length, instanceCount, sha256: hasher.digestHex(), strideBytes: SPATIAL_PARTICLE_INSTANCE_STRIDE_BYTES, systemSha256: spatialParticleSystemSha256(system), sampleTimeUs: parsed.sampleTimeUs })
+}

package/src/spatial-scene/particle.ts

@@ -0,0 +1,195 @@
+import { z } from "zod"
+
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { SpatialAssetIdSchema, SpatialEntityIdSchema, SpatialTimeUsSchema } from "./contracts.js"
+import { parseSpatialValue, SpatialSceneError, spatialValueSha256 } from "./identity.js"
+
+/**
+ * Bounded deterministic particle systems for Phase 7.
+ * All randomness is seeded; emitters, forces, collision/kill volumes, and
+ * count tiers are validated before any renderer or native bake admission.
+ */
+
+export const SPATIAL_PARTICLE_LIMITS = Object.freeze({
+  collisionVolumes: 16,
+  curveKeys: 16,
+  durationUs: 3_600_000_000,
+  emitters: 64,
+  final: 1_000_000,
+  forces: 16,
+  killVolumes: 16,
+  preview: 100_000,
+  splinePoints: 64,
+})
+
+const finiteCoordinate = z.number().finite().min(-1_000_000).max(1_000_000)
+const positiveDimension = z.number().finite().positive().max(1_000_000)
+const unit = z.number().finite().min(0).max(1)
+const vec3 = z.tuple([finiteCoordinate, finiteCoordinate, finiteCoordinate])
+const rgba = z.tuple([unit, unit, unit, unit])
+const particleId = z.string().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/u)
+
+const scalarCurveKey = z.strictObject({ t: unit, value: unit })
+const scalarCurveKeys = z.array(scalarCurveKey).min(2).max(SPATIAL_PARTICLE_LIMITS.curveKeys).superRefine((keys, context) => {
+  if (keys[0]?.t !== 0 || keys[keys.length - 1]?.t !== 1) {
+    context.addIssue({ code: "custom", message: "Particle curves must cover normalized time from 0 through 1." })
+  }
+  for (let index = 1; index < keys.length; index += 1) {
+    if (keys[index]!.t <= keys[index - 1]!.t) {
+      context.addIssue({ code: "custom", path: [index, "t"], message: "Particle curve keys must have strictly increasing time." })
+    }
+  }
+})
+
+const colorCurveKey = z.strictObject({ t: unit, color: rgba })
+const keyedColorCurve = z.array(colorCurveKey).min(2).max(SPATIAL_PARTICLE_LIMITS.curveKeys).superRefine((keys, context) => {
+  if (keys[0]?.t !== 0 || keys[keys.length - 1]?.t !== 1) {
+    context.addIssue({ code: "custom", message: "Particle color curves must cover normalized time from 0 through 1." })
+  }
+  for (let index = 1; index < keys.length; index += 1) {
+    if (keys[index]!.t <= keys[index - 1]!.t) {
+      context.addIssue({ code: "custom", path: [index, "t"], message: "Particle color keys must have strictly increasing time." })
+    }
+  }
+})
+const legacyColorCurve = z.array(rgba).min(2).max(SPATIAL_PARTICLE_LIMITS.curveKeys).transform(colors => (
+  colors.map((color, index) => ({ t: index / (colors.length - 1), color }))
+))
+
+export const SpatialParticleEmitterShapeSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("point") }),
+  z.strictObject({ kind: z.literal("sphere"), radius: positiveDimension, volume: z.boolean().default(true) }),
+  z.strictObject({ kind: z.literal("box"), size: z.tuple([positiveDimension, positiveDimension, positiveDimension]), volume: z.boolean().default(true) }),
+  z.strictObject({ kind: z.literal("disc"), radius: positiveDimension }),
+  z.strictObject({ kind: z.literal("surface"), assetId: SpatialAssetIdSchema }),
+  z.strictObject({ kind: z.literal("spline"), controlPoints: z.array(vec3).min(2).max(SPATIAL_PARTICLE_LIMITS.splinePoints) }),
+])
+
+export const SpatialParticleForceSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("gravity"), acceleration: vec3 }),
+  z.strictObject({ kind: z.literal("drag"), coefficient: unit }),
+  z.strictObject({ kind: z.literal("vortex"), axis: vec3, strength: z.number().finite().min(-1_000_000).max(1_000_000) }),
+  z.strictObject({ kind: z.literal("turbulence"), seed: z.number().int().min(0).max(2_147_483_647), scale: positiveDimension, strength: positiveDimension }),
+])
+
+const boxVolumeShape = {
+  kind: z.literal("box"),
+  max: vec3,
+  min: vec3,
+}
+const sphereVolumeShape = {
+  center: vec3,
+  kind: z.literal("sphere"),
+  radius: positiveDimension,
+}
+
+export const SpatialParticleKillVolumeSchema = z.discriminatedUnion("kind", [
+  z.strictObject(boxVolumeShape),
+  z.strictObject(sphereVolumeShape),
+])
+
+export const SpatialParticleCollisionVolumeSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ ...boxVolumeShape, response: z.enum(["bounce", "slide"]), restitution: unit }),
+  z.strictObject({ ...sphereVolumeShape, response: z.enum(["bounce", "slide"]), restitution: unit }),
+])
+
+export const SpatialParticleCurveSchema = z.strictObject({ keys: scalarCurveKeys })
+
+export const SpatialParticleEmitterSchema = z.strictObject({
+  burst: z.number().int().min(0).max(SPATIAL_PARTICLE_LIMITS.final).optional(),
+  colorOverLife: z.union([keyedColorCurve, legacyColorCurve]),
+  enabled: z.boolean().default(true),
+  id: particleId,
+  lifetimeUs: z.tuple([
+    SpatialTimeUsSchema.min(1).max(SPATIAL_PARTICLE_LIMITS.durationUs),
+    SpatialTimeUsSchema.min(1).max(SPATIAL_PARTICLE_LIMITS.durationUs),
+  ]),
+  opacityOverLife: SpatialParticleCurveSchema,
+  rate: z.number().int().min(0).max(SPATIAL_PARTICLE_LIMITS.final),
+  seed: z.number().int().min(0).max(2_147_483_647),
+  shape: SpatialParticleEmitterShapeSchema,
+  sizeOverLife: SpatialParticleCurveSchema,
+  velocity: vec3,
+  velocitySpread: z.tuple([unit, unit, unit]),
+}).superRefine((emitter, context) => {
+  if (emitter.lifetimeUs[1] < emitter.lifetimeUs[0]) {
+    context.addIssue({ code: "custom", path: ["lifetimeUs", 1], message: "Maximum particle lifetime must not precede minimum lifetime." })
+  }
+  if (emitter.rate === 0 && (emitter.burst ?? 0) === 0) {
+    context.addIssue({ code: "custom", message: "An emitter must declare a positive rate or burst." })
+  }
+  if (emitter.shape.kind === "spline") {
+    const distinct = new Set(emitter.shape.controlPoints.map(point => point.join(",")))
+    if (distinct.size < 2) context.addIssue({ code: "custom", path: ["shape", "controlPoints"], message: "A spline emitter needs at least two distinct control points." })
+  }
+})
+
+export const SpatialParticleRendererSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("sprite"), assetId: SpatialAssetIdSchema.optional(), billboard: z.boolean().default(true) }),
+  z.strictObject({ kind: z.literal("instanced-mesh"), assetId: SpatialAssetIdSchema }),
+])
+
+export const SpatialParticleSystemSchema = z.strictObject({
+  collisionVolumes: z.array(SpatialParticleCollisionVolumeSchema).max(SPATIAL_PARTICLE_LIMITS.collisionVolumes).default([]),
+  countTier: z.enum(["preview", "final"]),
+  emitters: z.array(SpatialParticleEmitterSchema).min(1).max(SPATIAL_PARTICLE_LIMITS.emitters),
+  entityId: SpatialEntityIdSchema,
+  forces: z.array(SpatialParticleForceSchema).max(SPATIAL_PARTICLE_LIMITS.forces),
+  killVolumes: z.array(SpatialParticleKillVolumeSchema).max(SPATIAL_PARTICLE_LIMITS.killVolumes),
+  kind: z.literal("slopcamera.spatial-particle-system"),
+  maxCount: z.number().int().min(1).max(SPATIAL_PARTICLE_LIMITS.final),
+  preBake: z.boolean().default(false),
+  renderer: SpatialParticleRendererSchema.default({ kind: "sprite", billboard: true }),
+  schemaVersion: z.literal(1),
+})
+
+export type SpatialParticleSystem = Readonly<z.infer<typeof SpatialParticleSystemSchema>>
+export type SpatialParticleEmitter = Readonly<z.infer<typeof SpatialParticleEmitterSchema>>
+
+function assertBoxVolume(volume: { readonly kind: string; readonly min?: readonly number[]; readonly max?: readonly number[] }, label: string): void {
+  if (volume.kind !== "box" || volume.min === undefined || volume.max === undefined) return
+  if (volume.min.some((value, index) => value >= volume.max![index]!)) {
+    throw new SpatialSceneError("invalid-data", `${label} box minimum coordinates must be below maximum coordinates.`, "particle-system")
+  }
+}
+
+export function parseSpatialParticleSystem(input: unknown): SpatialParticleSystem {
+  const system = parseSpatialValue(SpatialParticleSystemSchema, input, "particle system")
+  const tierLimit = system.countTier === "preview" ? SPATIAL_PARTICLE_LIMITS.preview : SPATIAL_PARTICLE_LIMITS.final
+  if (system.maxCount > tierLimit) {
+    throw new SpatialSceneError("invalid-data", `Particle system ${system.entityId} requests ${system.maxCount} particles, exceeding the ${system.countTier} tier limit of ${tierLimit}.`, "particle-system")
+  }
+  const emitterIds = system.emitters.map(emitter => emitter.id)
+  if (new Set(emitterIds).size !== emitterIds.length) {
+    throw new SpatialSceneError("invalid-data", `Particle system ${system.entityId} has duplicate emitter IDs.`, "particle-system")
+  }
+  const simultaneousBound = system.emitters.reduce((sum, emitter) => (
+    emitter.enabled
+      ? sum + (emitter.burst ?? 0) + Math.ceil(emitter.rate * emitter.lifetimeUs[1] / 1_000_000)
+      : sum
+  ), 0)
+  if (simultaneousBound > system.maxCount) {
+    throw new SpatialSceneError("invalid-data", `Particle system ${system.entityId} simultaneous bound (${simultaneousBound}) exceeds maxCount (${system.maxCount}).`, "particle-system")
+  }
+  for (const volume of system.killVolumes) assertBoxVolume(volume, "Kill volume")
+  for (const volume of system.collisionVolumes) assertBoxVolume(volume, "Collision volume")
+  for (const force of system.forces) {
+    if (force.kind === "vortex" && force.axis.every(value => value === 0)) {
+      throw new SpatialSceneError("invalid-data", "Vortex axes must be nonzero.", "particle-system")
+    }
+  }
+  return deepFreezeJson(system)
+}
+
+export function spatialParticleAssetIds(system: SpatialParticleSystem): readonly string[] {
+  const ids = new Set<string>()
+  if ("assetId" in system.renderer && system.renderer.assetId !== undefined) ids.add(system.renderer.assetId)
+  for (const emitter of system.emitters) {
+    if (emitter.shape.kind === "surface") ids.add(emitter.shape.assetId)
+  }
+  return Object.freeze([...ids].sort())
+}
+
+export function spatialParticleSystemSha256(system: SpatialParticleSystem): string {
+  return spatialValueSha256(system)
+}

package/src/spatial-scene/patch.ts

@@ -1,7 +1,8 @@
 import { deepFreezeJson } from "../code/json-snapshot.js"
 import { SpatialScenePatchV1Schema, type SpatialEntity, type SpatialSceneV1 } from "./contracts.js"
 import { applySpatialEntityOverride } from "./evaluate.js"
-import { parseSpatialScene, parseSpatialValue, SpatialSceneError, spatialAssetClosureDigests, spatialValueSha256 } from "./identity.js"
+import { parseSpatialScene, parseSpatialValue, SpatialSceneError, spatialAssetClosureDigests, spatialPropertySupported, spatialValueSha256 } from "./identity.js"
+import { pbrMaterialMapAssetIds } from "./material-lighting.js"
 
 export interface SpatialSceneDiffEntry {
   readonly kind: "added" | "removed" | "changed"
@@ -33,6 +34,20 @@ function diffCollection<T extends object>(collection: SpatialSceneDiffEntry["col
   return result
 }
 
+/** Structural comparison of two parsed scenes, in canonical collection order. */
+export function diffSpatialScenes(beforeInput: unknown, afterInput: unknown): readonly SpatialSceneDiffEntry[] {
+  const before = parseSpatialScene(beforeInput)
+  const after = parseSpatialScene(afterInput)
+  return deepFreezeJson([
+    ...diffCollection("assets", before.assets, after.assets, asset => asset.assetId),
+    ...diffCollection("entities", before.entities, after.entities, entity => entity.entityId),
+    ...diffCollection("cameras", before.cameras, after.cameras, camera => camera.cameraId),
+    ...diffCollection("animations", before.animations, after.animations, channel => channel.channelId),
+    ...diffCollection("generators", before.generators, after.generators, generator => generator.generatorId),
+    ...diffCollection("overrides", before.overrides, after.overrides, override => `${override.entityId}:${override.property}`),
+  ])
+}
+
 /** Atomic in-memory transaction. Final closure is checked once, before publishing any result. */
 export function applySpatialScenePatch(sceneInput: unknown, patchInput: unknown): SpatialScenePatchResult {
   const original = parseSpatialScene(sceneInput)
@@ -55,10 +70,15 @@ export function applySpatialScenePatch(sceneInput: unknown, patchInput: unknown)
     switch (operation.kind) {
       case "add-asset":
         if (assets.has(operation.asset.assetId)) throw new SpatialSceneError("conflict", `Asset ${operation.asset.assetId} already exists.`)
+        if (operation.asset.provenance.source === "generated") throw new SpatialSceneError("conflict", "Generated assets enter only through retained generator output replacement.")
         assets.set(operation.asset.assetId, operation.asset)
         break
       case "replace-asset":
         if (!assets.has(operation.asset.assetId)) throw new SpatialSceneError("not-found", `Asset ${operation.asset.assetId} does not exist.`)
+        if (operation.asset.provenance.source === "generated") throw new SpatialSceneError("conflict", "Generated assets change only through retained generator output replacement.")
+        if (original.generators.some(generator => generator.assets?.includes(operation.asset.assetId))) {
+          throw new SpatialSceneError("conflict", `Asset ${operation.asset.assetId} is owned by a generator; replace its retained output.`)
+        }
         assets.set(operation.asset.assetId, operation.asset)
         break
       case "set-mesh-geometry": {
@@ -68,11 +88,63 @@ export function applySpatialScenePatch(sceneInput: unknown, patchInput: unknown)
         addressedGeometry.add(operation.entityId)
         break
       }
+      case "set-material": {
+        const entity = authored(operation.entityId)
+        if (entity.kind !== "mesh") throw new SpatialSceneError("conflict", "Material replacement requires an authored mesh entity.")
+        if (entity.geometry.kind === "asset" && entity.geometry.materialMode === "source") throw new SpatialSceneError("conflict", "Source-material meshes consume source materials only; the entity material is inert.")
+        entities.set(operation.entityId, { ...entity, material: operation.material })
+        break
+      }
       case "rename-entity": entities.set(operation.entityId, { ...authored(operation.entityId), name: operation.name }); break
       case "reparent-entity": entities.set(operation.entityId, { ...authored(operation.entityId), parentId: operation.parentId }); break
       case "set-transform": entities.set(operation.entityId, { ...authored(operation.entityId), transform: operation.transform }); break
       case "set-color": entities.set(operation.entityId, applySpatialEntityOverride(authored(operation.entityId), { entityId: operation.entityId, property: "color", value: operation.color })); break
       case "set-opacity": entities.set(operation.entityId, applySpatialEntityOverride(authored(operation.entityId), { entityId: operation.entityId, property: "opacity", value: operation.opacity })); break
+      case "set-emissive": {
+        const entity = authored(operation.entityId)
+        if (entity.kind !== "mesh" || (entity.material.kind !== "standard" && entity.material.kind !== "pbr")) throw new SpatialSceneError("conflict", "Emissive edits require an authored mesh with a standard or pbr material.", "operations")
+        if (!spatialPropertySupported(entity, "color")) throw new SpatialSceneError("conflict", "Source-material mode leaves emissive control to the retained GLB material.", "operations")
+        if (entity.material.kind === "pbr") {
+          const { emissive: _cleared, ...material } = entity.material
+          entities.set(operation.entityId, { ...entity, material: operation.emissive === null ? material : { ...material, emissive: { color: operation.emissive.color, intensity: operation.emissive.intensity } } })
+        } else {
+          const { emissive: _cleared, ...material } = entity.material
+          entities.set(operation.entityId, { ...entity, material: operation.emissive === null ? material : { ...material, emissive: operation.emissive } })
+        }
+        break
+      }
+      case "set-spot": {
+        const entity = authored(operation.entityId)
+        if (entity.kind !== "light" || entity.light !== "spot") throw new SpatialSceneError("conflict", "Spot cone edits require an authored spot light.", "operations")
+        entities.set(operation.entityId, { ...entity, spot: operation.spot })
+        break
+      }
+      case "set-instances": {
+        const entity = authored(operation.entityId)
+        if (entity.kind !== "mesh") throw new SpatialSceneError("conflict", "Instance edits apply to authored mesh entities.", "operations")
+        const { instances: _cleared, ...rest } = entity
+        entities.set(operation.entityId, operation.instances === null ? rest : { ...rest, instances: operation.instances })
+        break
+      }
+      case "set-mesh-shadow": {
+        const entity = authored(operation.entityId)
+        if (entity.kind !== "mesh") throw new SpatialSceneError("conflict", "Mesh shadow flags apply to authored mesh entities.", "operations")
+        const { castShadow: _cast, receiveShadow: _receive, ...rest } = entity
+        entities.set(operation.entityId, {
+          ...rest,
+          ...(operation.castShadow === null ? {} : { castShadow: operation.castShadow }),
+          ...(operation.receiveShadow === null ? {} : { receiveShadow: operation.receiveShadow }),
+        })
+        break
+      }
+      case "set-light-shadow": {
+        const entity = authored(operation.entityId)
+        if (entity.kind !== "light") throw new SpatialSceneError("conflict", "Light shadow flags apply to authored light entities.", "operations")
+        if (entity.light === "ambient" && operation.shadow !== null) throw new SpatialSceneError("conflict", "Ambient lights cannot cast shadows.", "operations")
+        const { shadow: _shadow, ...rest } = entity
+        entities.set(operation.entityId, operation.shadow === null ? rest : { ...rest, shadow: operation.shadow })
+        break
+      }
       case "set-camera": cameras.set(operation.camera.cameraId, operation.camera); break
       case "set-channel": animations.set(operation.channel.channelId, operation.channel); break
       case "remove-channel":
@@ -92,10 +164,34 @@ export function applySpatialScenePatch(sceneInput: unknown, patchInput: unknown)
       case "replace-generator-output": {
         const generatorId = operation.generator.generatorId
         replacedGenerators.add(generatorId)
+        // Owned assets are swapped atomically with retained output: drop the
+        // previous owned set, require the declared new set, then add manifests.
+        const previous = generators.get(generatorId)?.assets ?? []
+        const provided = operation.assets ?? []
+        const declared = operation.generator.assets ?? []
+        if ([...provided.map(asset => asset.assetId)].sort().join("") !== [...declared].sort().join("")) {
+          throw new SpatialSceneError("conflict", "Generator replacement must carry exactly the manifests its record declares.")
+        }
+        for (const asset of provided) {
+          if (asset.provenance.source !== "generated" && asset.provenance.source !== "derived") {
+            throw new SpatialSceneError("conflict", "Generator-owned assets require generated or derived provenance.")
+          }
+          if (assets.has(asset.assetId) && !previous.includes(asset.assetId)) throw new SpatialSceneError("conflict", `Generator asset ${asset.assetId} collides with an existing asset.`)
+        }
+        for (const assetId of previous) assets.delete(assetId)
         for (const entity of entities.values()) if (entity.origin.kind === "generated" && entity.origin.generatorId === generatorId) entities.delete(entity.entityId)
+        for (const asset of provided) assets.set(asset.assetId, asset)
+        const owned = new Set(provided.map(asset => asset.assetId))
+        const remainingAssets = new Set(assets.keys())
         for (const entity of operation.entities) {
           if (entity.origin.kind !== "generated" || entity.origin.generatorId !== generatorId) throw new SpatialSceneError("conflict", "Generator replacement must contain only its own retained output.")
           if (entities.has(entity.entityId)) throw new SpatialSceneError("conflict", `Generator output collides with ${entity.entityId}.`)
+          const referenced: string[] = entity.kind === "mesh" && entity.geometry.kind === "asset" ? [entity.geometry.assetId]
+            : entity.kind === "text" ? [entity.fontAssetId] : "assetId" in entity ? [entity.assetId] : []
+          if (entity.kind === "mesh" && entity.material.kind !== "pbr" && entity.material.map !== undefined) referenced.push(entity.material.map)
+          for (const assetId of referenced) {
+            if (!owned.has(assetId) && !remainingAssets.has(assetId)) throw new SpatialSceneError("conflict", `Generator output references missing asset ${assetId}.`)
+          }
           entities.set(entity.entityId, entity)
         }
         generators.set(generatorId, operation.generator)
@@ -107,25 +203,23 @@ export function applySpatialScenePatch(sceneInput: unknown, patchInput: unknown)
   const beforeAssets = new Map(original.assets.map(asset => [asset.assetId, asset]))
   const oldClosure = spatialAssetClosureDigests(original.assets), newClosure = spatialAssetClosureDigests(scene.assets)
   for (const entity of scene.entities) {
-    const assetId = entity.kind === "mesh" && entity.geometry.kind === "asset" ? entity.geometry.assetId
-      : entity.kind === "text" ? entity.fontAssetId : "assetId" in entity ? entity.assetId : undefined
-    if (assetId === undefined) continue
-    if (entity.origin.kind === "generated" && oldClosure[assetId] !== undefined && oldClosure[assetId] !== newClosure[assetId] && !replacedGenerators.has(entity.origin.generatorId)) {
-      throw new SpatialSceneError("conflict", "Changing a generated part's asset closure requires explicit retained generator output replacement.")
+    const referenced: string[] = entity.kind === "mesh" && entity.geometry.kind === "asset" ? [entity.geometry.assetId]
+      : entity.kind === "text" ? [entity.fontAssetId] : "assetId" in entity ? [entity.assetId] : []
+    if (entity.kind === "mesh") {
+      if (entity.material.kind === "pbr") referenced.push(...pbrMaterialMapAssetIds(entity.material))
+      else if (entity.material.map !== undefined) referenced.push(entity.material.map)
+    }
+    for (const assetId of referenced) {
+      if (entity.origin.kind === "generated" && oldClosure[assetId] !== undefined && oldClosure[assetId] !== newClosure[assetId] && !replacedGenerators.has(entity.origin.generatorId)) {
+        throw new SpatialSceneError("conflict", "Changing a generated part's asset closure requires explicit retained generator output replacement.")
+      }
     }
     if (entity.kind === "mesh" && entity.geometry.kind === "asset" && (entity.geometry.nodeIndex !== undefined || entity.geometry.clip !== undefined)
-      && beforeAssets.has(assetId) && beforeAssets.get(assetId)!.payload.sha256 !== assets.get(assetId)!.payload.sha256
+      && beforeAssets.has(entity.geometry.assetId) && beforeAssets.get(entity.geometry.assetId)!.payload.sha256 !== assets.get(entity.geometry.assetId)!.payload.sha256
       && !addressedGeometry.has(entity.entityId) && !(entity.origin.kind === "generated" && replacedGenerators.has(entity.origin.generatorId))) {
       throw new SpatialSceneError("conflict", "Replacing addressed GLB bytes requires explicit set-mesh-geometry with the new local node/clip addresses; internal correspondence is not inferred.")
     }
   }
-  const diff = [
-    ...diffCollection("assets", original.assets, scene.assets, asset => asset.assetId),
-    ...diffCollection("entities", original.entities, scene.entities, entity => entity.entityId),
-    ...diffCollection("cameras", original.cameras, scene.cameras, camera => camera.cameraId),
-    ...diffCollection("animations", original.animations, scene.animations, channel => channel.channelId),
-    ...diffCollection("generators", original.generators, scene.generators, generator => generator.generatorId),
-    ...diffCollection("overrides", original.overrides, scene.overrides, override => `${override.entityId}:${override.property}`),
-  ]
+  const diff = diffSpatialScenes(original, scene)
   return deepFreezeJson({ scene, sceneSha256: spatialValueSha256(scene), diff })
 }