@nodaro/shared 2.24.0 → 2.27.0

package/src/__tests__/studio-transient.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect } from "vitest"
+
+import {
+  STUDIO_SHOT_TRANSIENT_KEYS,
+  STUDIO_TRANSIENT_KEYS,
+  stripStudioTransientSettings,
+} from "../studio-transient.js"
+
+/**
+ * The public projection of `settings.studio` (D12).
+ *
+ * A shared production is read by anyone holding the link, and the document
+ * carries the OWNER's working state beside the film: the recycle bin (every
+ * shot, still and clip they deleted, prompts and urls intact), the jobs in
+ * flight, and an unsaved editor draft.
+ *
+ * The fixture below is a real saved document, pinned here byte for byte, and
+ * the LEVEL is the whole finding this test exists for: the in-flight markers
+ * are written PER SHOT, inside `settings.studio.shots[]`, and a strip that only
+ * walks the top level hands a viewer all of them while a fixture shaped to the
+ * top level says it does not.
+ */
+
+const PENDING = {
+  jobId: "job-2",
+  provider: "seedance-2",
+  prompt: "a slow dolly in",
+  startedAt: 1_756_000_000_000,
+}
+
+const TRASHED = {
+  kind: "still",
+  id: "trash-1",
+  shotId: "s1",
+  index: 0,
+  deletedAt: "2026-09-01T10:00:00.000Z",
+  stillBase: { nodeId: "img-1", provider: "flux-2", prompt: "a lighthouse at dawn" },
+  result: { url: "https://cdn/deleted.png" },
+}
+
+/** A saved document carrying every marker its writer can write. */
+function written(): Record<string, unknown> {
+  return {
+    studio: {
+      version: 3,
+      shots: [
+        {
+          id: "s1",
+          imageNodeId: "img-1",
+          stillProvider: "flux-2",
+          pendingClips: [{ ...PENDING }],
+        },
+      ],
+      selectedShotId: "s1",
+      shotOrder: ["img-1"],
+      shared: true,
+      freecutDraftUrl: "https://cdn/draft.json",
+      trash: [{ ...TRASHED }],
+    },
+  }
+}
+
+/** `settings.studio` of a stripped document. */
+function studioOf(settings: unknown): Record<string, unknown> {
+  return (settings as { studio: Record<string, unknown> }).studio
+}
+
+describe("stripStudioTransientSettings", () => {
+  it("drops the bin and the draft the writer put at the top level", () => {
+    const settings = written()
+    // The oracle: the document really does carry these two here.
+    expect(studioOf(settings).trash).toHaveLength(1)
+    expect(studioOf(settings).freecutDraftUrl).toBe("https://cdn/draft.json")
+
+    const studio = studioOf(stripStudioTransientSettings(settings))
+    expect(studio.trash).toBeUndefined()
+    expect(studio.freecutDraftUrl).toBeUndefined()
+  })
+
+  it("drops the in-flight markers the writer put PER SHOT", () => {
+    const settings = written()
+    // The oracle again, and the whole point: `pendingClips` is a SHOT's key.
+    const stored = (studioOf(settings).shots as Array<Record<string, unknown>>)[0]
+    expect(stored.pendingClips).toEqual([PENDING])
+
+    const shots = studioOf(stripStudioTransientSettings(settings)).shots as Array<
+      Record<string, unknown>
+    >
+    expect(shots[0].pendingClips).toBeUndefined()
+    // ...and the shot itself survives, film intact.
+    expect(shots[0].id).toBe("s1")
+    expect(shots[0].imageNodeId).toBe("img-1")
+  })
+
+  it("leaves the film — the shots, the order, the share flag — untouched", () => {
+    const studio = studioOf(stripStudioTransientSettings(written()))
+    expect(studio.version).toBe(3)
+    expect(studio.shotOrder).toEqual(["img-1"])
+    expect(studio.shared).toBe(true)
+    expect(studio.selectedShotId).toBe("s1")
+  })
+
+  it("never mutates the caller's document", () => {
+    const settings = written()
+    const before = JSON.stringify(settings)
+    stripStudioTransientSettings(settings)
+    expect(JSON.stringify(settings)).toBe(before)
+  })
+
+  it("hands back the very same object when there is nothing to strip", () => {
+    // An ordinary share read of an ordinary production allocates nothing.
+    const settings: Record<string, unknown> = {
+      studio: { version: 3, shots: [{ id: "s1" }], selectedShotId: "s1", shotOrder: [] },
+    }
+    expect(stripStudioTransientSettings(settings)).toBe(settings)
+  })
+
+  it("drops a shot's pendingStills — the still marker D5 lands there", () => {
+    // `pendingStills` is additive: the generation routes write it onto the same
+    // shot entry `pendingClips` rides on, so the strip has to know the key
+    // before its writer exists — otherwise the first framing batch in flight
+    // ships to every share viewer.
+    const settings = written()
+    const studio = studioOf(settings)
+    const shots = (studio.shots as Array<Record<string, unknown>>).map((s) => ({
+      ...s,
+      pendingStills: [{ jobId: "job-1", batchId: "batch-1", count: 4 }],
+    }))
+    const withStills = { ...settings, studio: { ...studio, shots } }
+
+    const out = studioOf(stripStudioTransientSettings(withStills))
+    expect((out.shots as Array<Record<string, unknown>>)[0].pendingStills).toBeUndefined()
+  })
+
+  it("drops a legacy single `pendingClip` too", () => {
+    // Pre-concurrent-markers saves wrote one marker under the singular key; the
+    // reader still migrates it, so it is still in-flight state a viewer must
+    // not receive.
+    const settings = written()
+    const studio = studioOf(settings)
+    const shots = [{ id: "s2", pendingClip: PENDING }]
+    const legacy = { ...settings, studio: { ...studio, shots } }
+
+    const out = studioOf(stripStudioTransientSettings(legacy))
+    expect((out.shots as Array<Record<string, unknown>>)[0]).toEqual({ id: "s2" })
+  })
+
+  it("leaves a workflow that is not a production alone", () => {
+    const settings = { presentationSettings: { shareReadOnly: true } }
+    expect(stripStudioTransientSettings(settings)).toBe(settings)
+    expect(stripStudioTransientSettings(null)).toBeNull()
+    expect(stripStudioTransientSettings(undefined)).toBeUndefined()
+  })
+
+  it("survives a document whose shots are not what the editor writes", () => {
+    // The strip runs on whatever is in the column, including a row written by
+    // something that is not the studio editor. It must project, never throw.
+    const odd = { studio: { version: 3, shots: ["nonsense", null, 7] } }
+    expect(() => stripStudioTransientSettings(odd)).not.toThrow()
+    expect(studioOf(stripStudioTransientSettings(odd)).shots).toEqual(["nonsense", null, 7])
+  })
+
+  it("drops the DOCUMENT's own pendingMusic and pendingDraft (D5)", () => {
+    // The document-level twin of the per-shot pair: a soundtrack render and a
+    // Director run in flight. Same rule — they name jobs on the owner's
+    // account, and no viewer can read or land one.
+    const settings = written()
+    const studio = studioOf(settings)
+    const inFlight = {
+      ...settings,
+      studio: {
+        ...studio,
+        pendingMusic: { jobId: "job-3", startedAt: 1_756_000_000_000 },
+        pendingDraft: { jobId: "job-4", startedAt: 1_756_000_000_000 },
+      },
+    }
+    // The oracle: the document really does carry both before the public read.
+    expect(studioOf(inFlight).pendingMusic).toBeDefined()
+    expect(studioOf(inFlight).pendingDraft).toBeDefined()
+
+    const out = studioOf(stripStudioTransientSettings(inFlight))
+    expect(out.pendingMusic).toBeUndefined()
+    expect(out.pendingDraft).toBeUndefined()
+    // ...and the film is still there.
+    expect(out.version).toBe(3)
+  })
+
+  it("pins the two lists — a key added to the type alone strips nothing", () => {
+    // The lists are the contract: the codec's own strip re-exports them, so a
+    // key that falls off here falls off there too, silently, on both sides.
+    expect([...STUDIO_TRANSIENT_KEYS]).toEqual([
+      "trash",
+      "pendingStills",
+      "pendingClips",
+      "pendingMusic",
+      "pendingDraft",
+      "freecutDraftUrl",
+    ])
+    expect([...STUDIO_SHOT_TRANSIENT_KEYS]).toEqual([
+      "pendingClips",
+      "pendingClip",
+      "pendingStills",
+    ])
+  })
+})

package/src/index.ts

@@ -1052,11 +1052,15 @@ export {
 export { ENTITY_NODE_KINDS } from "./entity-node-fields.js"
 export type { EntityNodeKind } from "./entity-node-fields.js"
 
-// --- wire contract of /v1/studio/productions — types only ---
-// The studio production CODEC (the reader/writer of `settings.studio`, the
-// plan format, the catalogs and the reducers) lives in the FSL-licensed
-// `@nodaro/studio-production`. What crosses into this Apache package is the
-// envelope those routes return and the bodies they take, so the SDK can be
-// typed against it — the document's own sub-objects stay named JSON here and
-// are narrowed, and pinned, by the package that owns them.
-export type * from "./studio-production-wire.js"
+// --- Scene3D previsualization (v1): the frozen wire contract shared by the
+//     authoring LLM jobs, the Three.js/Remotion renderer, the canvas and the
+//     SDK/MCP surface. Structure only — no prompts, no pricing. ---
+export * from "./scene3d.js"
+export * from "./scene3d-edit.js"
+
+// --- transient studio keys — the public share read strips them ---
+export {
+  STUDIO_TRANSIENT_KEYS,
+  STUDIO_SHOT_TRANSIENT_KEYS,
+  stripStudioTransientSettings,
+} from "./studio-transient.js"

package/src/llm-models.ts

@@ -642,6 +642,12 @@ export type LlmFeature =
   | "motion-graphics-lottie"
   | "lottie-overlay"
   | "3d-title"
+  // Scene3D previz authoring — generate-3d-scene AND edit-3d-scene share one
+  // feature: both send the model a scene (the edit sends the WHOLE plan in) and
+  // both get back structured geometry, so the token profile is the same shape.
+  // The deterministic edit lane never reaches an LLM and bills the separate
+  // zero-cost `3d-scene-ops` identifier instead.
+  | "3d-scene"
   | "image-to-text"
   | "describe-to-picker"
   | "qa-check"
@@ -672,6 +678,7 @@ export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
   "motion-graphics-lottie": "claude-sonnet-4.6",
   "lottie-overlay": "claude-sonnet-4.6",
   "3d-title": "claude-sonnet-4.6",
+  "3d-scene": "claude-sonnet-4.6",
   "image-to-text": "claude-sonnet-4.6",
   "describe-to-picker": "claude-opus-5",
   "qa-check": "gemini-3.6-flash",
@@ -849,6 +856,9 @@ export const LLM_ROUTE_DEFAULTS: Record<string, LlmRouteDefaults> = {
   "motion-graphics":         { temperature: 0.3,  maxTokens: 2048, structuredOutput: true },
   "motion-graphics-lottie":  { temperature: 0.3,  maxTokens: 8192, structuredOutput: true },
   "3d-title":                { temperature: 0.4,  maxTokens: 3072, structuredOutput: true },
+  // A 100-object plan with keyframe tracks is the biggest structured payload
+  // any composer feature emits — 3072 (3d-title's cap) truncates it mid-array.
+  "3d-scene":                { temperature: 0.3,  maxTokens: 8192, structuredOutput: true },
 }
 
 /** Route defaults for a feature; `{}` for an unknown one. */

package/src/model-constants.ts

@@ -2632,6 +2632,11 @@ export const COMPOSER_PLAN_MAP: Readonly<Record<string, { planType: string; plan
   "3d-title": { planType: "3d-title", planField: "titlePlan" },
   "motion-graphics": { planType: "motion-graphics", planField: "motionPlan" },
   "composite": { planType: "composite", planField: "compositePlan" },
+  // Scene3D previz (v1) — both the generator and the editor emit the SAME
+  // validated `Scene3DPlan` revision on their `composition` handle, so
+  // render-video routes either one to the `3d-scene` renderer unchanged.
+  "generate-3d-scene": { planType: "3d-scene", planField: "scenePlan" },
+  "edit-3d-scene": { planType: "3d-scene", planField: "scenePlan" },
 }
 
 /** Every composer plan-field name, derived from COMPOSER_PLAN_MAP (single source

package/src/node-mappable-fields.ts

@@ -44,6 +44,8 @@ export const NODE_MAPPABLE_FIELDS: Readonly<Record<string, readonly string[]>> =
   "after-effects":       ["effectPrompt"],
   "lottie-overlay":      ["overlayPrompt"],
   "3d-title":            ["titlePrompt"],
+  "generate-3d-scene":   ["scenePrompt"],
+  "edit-3d-scene":       ["editPrompt"],
   "motion-graphics":     ["motionPrompt"],
   "generate-script":     ["styleGuide"],
   "speech-to-video":     ["prompt", "negativePrompt"],

package/src/node-preset-extract.ts

@@ -25,13 +25,19 @@ import { PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY } from "./prompt-affixes.js"
  *     blob (~tens of KB) + a stale url, re-injecting them on every apply and
  *     bloating the preset row. These keys are in the capture-exclusion set below.
  */
-export const PRESET_APPLY_CLEAR_KEYS: readonly string[] = [...COMPOSER_PLAN_FIELDS, "lottieUrl"]
+export const PRESET_APPLY_CLEAR_KEYS: readonly string[] = [
+  ...COMPOSER_PLAN_FIELDS, "lottieUrl",
+  // Scene revision history contains old plans and their reference/prompt context.
+  // Preserve it in workflows, never capture or resurrect it through a preset.
+  "sceneHistory", "scenePendingPlan", "sceneJobBaseRevisionId", "expectedRevisionId",
+  "changeSummary", "selectedObjectIds", "lockedObjectIds", "referenceObjectIds", "referenceRoles",
+]
 
 /**
  * The three keys that carry a preset's PROMPT CONTENT: the prompt itself plus the pre/post text
  * wrapped around it at run time. A preset "owns prompt content" iff its data defines any of them.
  */
-const PROMPT_CONTENT_KEYS: readonly string[] = ["prompt", PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY]
+const PROMPT_CONTENT_KEYS: readonly string[] = ["prompt", "scenePrompt", "editPrompt", PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY]
 
 /**
  * The keys applying THIS preset must clear on the node: always `PRESET_APPLY_CLEAR_KEYS`, plus

package/src/scene3d-edit.ts

@@ -0,0 +1,311 @@
+/**
+ * Scene3D edit operations — the ONLY way a Scene3D plan changes.
+ *
+ * Split out of `scene3d.ts` (which owns the shape) because this file owns the
+ * TRANSITION: given a plan, a list of operations and the caller's locks, it
+ * produces the next immutable revision or an explained refusal. Both edit
+ * lanes go through it — the deterministic one (the caller sent operations) and
+ * the instruction one (an LLM authored the operations from a sentence) — so
+ * locks, staleness and whole-scene validation cannot be enforced twice and
+ * differently. The model never writes a plan and never writes code; it writes
+ * operations that this function is free to refuse.
+ */
+import { z } from "zod"
+import {
+  SCENE3D_LIMITS,
+  newScene3DRevisionId,
+  rotationVec3Schema,
+  scaleVec3Schema,
+  scene3DCameraKeyframeSchema,
+  scene3DColorSchema,
+  scene3DDeepEqual,
+  scene3DIdSchema,
+  scene3DObjectKeyframeSchema,
+  scene3DObjectSchema,
+  scene3DPlanSchema,
+  scene3DPrimitiveSchema,
+  sizeVec3Schema,
+  vec3Schema,
+  type Scene3DObject,
+  type Scene3DPlan,
+} from "./scene3d.js"
+
+
+/** Everything about an object EXCEPT its identity. `id` is deliberately absent
+ *  (and the schema is strict) so no operation can rename an object out from
+ *  under a lock, a parent link or a reference. */
+export const scene3DObjectChangesSchema = z
+  .object({
+    name: z.string().min(1).max(SCENE3D_LIMITS.maxNameLength).optional(),
+    primitive: scene3DPrimitiveSchema.optional(),
+    /** `null` detaches from the parent; omitted leaves it as-is. */
+    parentId: scene3DIdSchema.nullable().optional(),
+    dimensions: sizeVec3Schema.optional(),
+    position: vec3Schema.optional(),
+    rotation: rotationVec3Schema.optional(),
+    scale: scaleVec3Schema.optional(),
+    color: scene3DColorSchema.optional(),
+    keyframes: z.array(scene3DObjectKeyframeSchema).max(SCENE3D_LIMITS.maxKeyframes).optional(),
+  })
+  .strict()
+
+export const scene3DCameraChangesSchema = z
+  .object({
+    position: vec3Schema.optional(),
+    target: vec3Schema.optional(),
+    focalLengthMm: z
+      .number()
+      .min(SCENE3D_LIMITS.minFocalLengthMm)
+      .max(SCENE3D_LIMITS.maxFocalLengthMm)
+      .optional(),
+    sensorWidthMm: z
+      .number()
+      .min(SCENE3D_LIMITS.minSensorWidthMm)
+      .max(SCENE3D_LIMITS.maxSensorWidthMm)
+      .optional(),
+    keyframes: z.array(scene3DCameraKeyframeSchema).max(SCENE3D_LIMITS.maxKeyframes).optional(),
+  })
+  .strict()
+
+export const scene3DLightingChangesSchema = z
+  .object({
+    ambientIntensity: z.number().min(0).max(SCENE3D_LIMITS.maxIntensity).optional(),
+    keyIntensity: z.number().min(0).max(SCENE3D_LIMITS.maxIntensity).optional(),
+    keyPosition: vec3Schema.optional(),
+  })
+  .strict()
+
+export const scene3DEditOperationSchema = z.discriminatedUnion("op", [
+  z.object({ op: z.literal("set-object"), objectId: scene3DIdSchema, changes: scene3DObjectChangesSchema }).strict(),
+  z.object({ op: z.literal("add-object"), object: scene3DObjectSchema }).strict(),
+  z.object({ op: z.literal("remove-object"), objectId: scene3DIdSchema }).strict(),
+  z.object({ op: z.literal("set-camera"), changes: scene3DCameraChangesSchema }).strict(),
+  z.object({ op: z.literal("set-lighting"), changes: scene3DLightingChangesSchema }).strict(),
+  z.object({ op: z.literal("set-background"), color: scene3DColorSchema }).strict(),
+])
+
+export const scene3DEditOperationsSchema = z
+  .array(scene3DEditOperationSchema)
+  .min(1)
+  .max(SCENE3D_LIMITS.maxOperations)
+
+export type Scene3DObjectChanges = z.infer<typeof scene3DObjectChangesSchema>
+export type Scene3DCameraChanges = z.infer<typeof scene3DCameraChangesSchema>
+export type Scene3DLightingChanges = z.infer<typeof scene3DLightingChangesSchema>
+export type Scene3DEditOperation = z.infer<typeof scene3DEditOperationSchema>
+
+export type Scene3DEditErrorCode =
+  /** `expectedRevisionId` did not match the plan handed in. */
+  | "stale_revision"
+  /** The operation list itself is malformed or over the cap. */
+  | "invalid_operations"
+  /** An operation targets an object that is not in the scene. */
+  | "unknown_object"
+  /** `add-object` collided with an existing id. */
+  | "duplicate_object"
+  /** An operation touched an id the caller declared locked. */
+  | "locked_object"
+  /** The plan handed in, or the plan the operations produced, is invalid. */
+  | "invalid_plan"
+
+export interface Scene3DEditOptions {
+  /** Optimistic concurrency: reject unless the plan is still this revision. */
+  expectedRevisionId?: string
+  /** Object ids the caller declared untouchable. Enforced as a POST-condition
+   *  (see `applyScene3DEditOperations`), which is what makes it total. */
+  lockedObjectIds?: readonly string[]
+  /** Pin the produced revision id — tests and deterministic replay only. */
+  revisionId?: string
+}
+
+export type Scene3DEditResult =
+  | { ok: true; plan: Scene3DPlan; changedObjectIds: string[]; changeSummary: string }
+  | { ok: false; code: Scene3DEditErrorCode; message: string; operationIndex?: number }
+
+/** Structural clone that cannot share a reference with its input. `structured-
+ *  Clone` is not available in every consumer runtime we ship to, and a plan is
+ *  pure JSON by construction. */
+function clonePlan(plan: Scene3DPlan): Scene3DPlan {
+  return JSON.parse(JSON.stringify(plan)) as Scene3DPlan
+}
+
+/** One human sentence per operation — the deterministic lane's answer to the
+ *  LLM lane's `changeSummary`, so both edit paths return the same shape. */
+export function summarizeScene3DOperations(operations: readonly Scene3DEditOperation[]): string {
+  const lines = operations.map((operation) => {
+    switch (operation.op) {
+      case "set-object": {
+        const fields = Object.keys(operation.changes)
+        return `Updated ${fields.length > 0 ? fields.join(", ") : "nothing"} on "${operation.objectId}"`
+      }
+      case "add-object":
+        return `Added ${operation.object.primitive} "${operation.object.name}" (${operation.object.id})`
+      case "remove-object":
+        return `Removed "${operation.objectId}"`
+      case "set-camera":
+        return `Updated camera ${Object.keys(operation.changes).join(", ") || "nothing"}`
+      case "set-lighting":
+        return `Updated lighting ${Object.keys(operation.changes).join(", ") || "nothing"}`
+      case "set-background":
+        return `Set background to ${operation.color}`
+    }
+  })
+  return lines.join("; ").slice(0, SCENE3D_LIMITS.maxChangeSummaryLength)
+}
+
+function firstIssueMessage(error: z.ZodError): string {
+  const issue = error.issues[0]
+  if (!issue) return "invalid"
+  const path = issue.path.join(".")
+  return path ? `${path}: ${issue.message}` : issue.message
+}
+
+/**
+ * Apply an operation list to a plan, producing a NEW revision.
+ *
+ * Guarantees, in this order — each one is a distinct failure mode that was
+ * cheap to get wrong:
+ *
+ * 1. The input plan is never mutated (deep clone before the first write).
+ * 2. A stale `expectedRevisionId` is refused before anything is applied, so a
+ *    late async completion can never overwrite a newer manual edit.
+ * 3. Operations are schema-validated as a list; the failing INDEX is reported.
+ * 4. Locks are enforced as a POST-CONDITION — every locked object must still
+ *    exist and be deep-equal to the original. Reasoning per-operation would
+ *    have to anticipate remove + re-add, a reparent from a sibling's `set-
+ *    object`, and whatever the next operation kind turns out to be; the
+ *    post-condition covers all of them by construction. (`selectedObjectIds`
+ *    is CONTEXT for the model, never permission — the caller passes locks
+ *    explicitly and they are checked here, after the model has spoken.)
+ * 5. The WHOLE resulting plan is re-validated, which is what makes "no silent
+ *    orphaning" free: removing a parent leaves a dangling `parentId` and the
+ *    plan validator rejects it, as does removing an object a reference points
+ *    at.
+ */
+export function applyScene3DEditOperations(
+  plan: Scene3DPlan,
+  operations: readonly Scene3DEditOperation[] | unknown,
+  options: Scene3DEditOptions = {},
+): Scene3DEditResult {
+  const parsedPlan = scene3DPlanSchema.safeParse(plan)
+  if (!parsedPlan.success) {
+    return { ok: false, code: "invalid_plan", message: `scenePlan is invalid — ${firstIssueMessage(parsedPlan.error)}` }
+  }
+  const source = parsedPlan.data as Scene3DPlan
+
+  if (options.expectedRevisionId !== undefined && options.expectedRevisionId !== source.revisionId) {
+    return {
+      ok: false,
+      code: "stale_revision",
+      message: `This scene has moved on — expected revision ${options.expectedRevisionId}, the plan is at ${source.revisionId}.`,
+    }
+  }
+
+  const parsedOps = scene3DEditOperationsSchema.safeParse(operations)
+  if (!parsedOps.success) {
+    const issue = parsedOps.error.issues[0]
+    const index = typeof issue?.path[0] === "number" ? (issue.path[0] as number) : undefined
+    return {
+      ok: false,
+      code: "invalid_operations",
+      message: `operations are invalid — ${firstIssueMessage(parsedOps.error)}`,
+      ...(index === undefined ? {} : { operationIndex: index }),
+    }
+  }
+  const ops = parsedOps.data
+
+  const next = clonePlan(source)
+  const changed = new Set<string>()
+
+  for (let index = 0; index < ops.length; index++) {
+    const operation = ops[index]
+    switch (operation.op) {
+      case "set-object": {
+        const target = next.objects.findIndex((o) => o.id === operation.objectId)
+        if (target === -1) {
+          return {
+            ok: false,
+            code: "unknown_object",
+            message: `no object "${operation.objectId}" in this scene`,
+            operationIndex: index,
+          }
+        }
+        const { parentId, ...rest } = operation.changes
+        const updated: Scene3DObject = { ...next.objects[target], ...rest }
+        if (parentId !== undefined) {
+          if (parentId === null) delete updated.parentId
+          else updated.parentId = parentId
+        }
+        next.objects = next.objects.map((o, i) => (i === target ? updated : o))
+        changed.add(operation.objectId)
+        break
+      }
+      case "add-object": {
+        if (next.objects.some((o) => o.id === operation.object.id)) {
+          return {
+            ok: false,
+            code: "duplicate_object",
+            message: `an object with id "${operation.object.id}" already exists`,
+            operationIndex: index,
+          }
+        }
+        next.objects = [...next.objects, operation.object as Scene3DObject]
+        changed.add(operation.object.id)
+        break
+      }
+      case "remove-object": {
+        if (!next.objects.some((o) => o.id === operation.objectId)) {
+          return {
+            ok: false,
+            code: "unknown_object",
+            message: `no object "${operation.objectId}" in this scene`,
+            operationIndex: index,
+          }
+        }
+        next.objects = next.objects.filter((o) => o.id !== operation.objectId)
+        changed.add(operation.objectId)
+        break
+      }
+      case "set-camera":
+        next.camera = { ...next.camera, ...operation.changes }
+        break
+      case "set-lighting":
+        next.lighting = { ...next.lighting, ...operation.changes }
+        break
+      case "set-background":
+        next.backgroundColor = operation.color
+        break
+    }
+  }
+
+  for (const lockedId of options.lockedObjectIds ?? []) {
+    const before = source.objects.find((o) => o.id === lockedId)
+    const after = next.objects.find((o) => o.id === lockedId)
+    if (before === undefined) continue // not in the scene to begin with — nothing to protect
+    if (after === undefined) {
+      return { ok: false, code: "locked_object", message: `object "${lockedId}" is locked and cannot be removed` }
+    }
+    if (!scene3DDeepEqual(before, after)) {
+      return { ok: false, code: "locked_object", message: `object "${lockedId}" is locked and cannot be modified` }
+    }
+  }
+
+  next.parentRevisionId = source.revisionId
+  next.revisionId = options.revisionId ?? newScene3DRevisionId()
+
+  const validated = scene3DPlanSchema.safeParse(next)
+  if (!validated.success) {
+    return {
+      ok: false,
+      code: "invalid_plan",
+      message: `the edit would leave the scene invalid — ${firstIssueMessage(validated.error)}`,
+    }
+  }
+
+  return {
+    ok: true,
+    plan: validated.data as Scene3DPlan,
+    changedObjectIds: [...changed],
+    changeSummary: summarizeScene3DOperations(ops),
+  }
+}