@nodaro/shared 2.27.0 → 3.0.0

package/src/__tests__/scene3d.test.ts

@@ -14,14 +14,14 @@ import {
   SCENE3D_PLAN_TYPE,
   SCENE3D_SCHEMA_VERSION,
   applyScene3DEditOperations,
-  isScene3DPlan,
+  isScene3DPlanV1,
   newScene3DRevisionId,
   scene3DDeepEqual,
   scene3DEditOperationSchema,
   scene3DPlanSchema,
   summarizeScene3DOperations,
   type Scene3DObject,
-  type Scene3DPlan,
+  type Scene3DPlanV1,
 } from "../index.js"
 
 const REV_A = "11111111-2222-4333-8444-555555555555"
@@ -41,7 +41,7 @@ function object(id: string, over: Partial<Scene3DObject> = {}): Scene3DObject {
   }
 }
 
-function plan(over: Partial<Scene3DPlan> = {}): Scene3DPlan {
+function plan(over: Partial<Scene3DPlanV1> = {}): Scene3DPlanV1 {
   return {
     planType: SCENE3D_PLAN_TYPE,
     schemaVersion: SCENE3D_SCHEMA_VERSION,
@@ -61,7 +61,7 @@ function plan(over: Partial<Scene3DPlan> = {}): Scene3DPlan {
 describe("scene3DPlanSchema — structure", () => {
   it("accepts a minimal well-formed plan", () => {
     expect(scene3DPlanSchema.safeParse(plan()).success).toBe(true)
-    expect(isScene3DPlan(plan())).toBe(true)
+    expect(isScene3DPlanV1(plan())).toBe(true)
   })
 
   it("defaults sensorWidthMm to full frame", () => {
@@ -345,7 +345,7 @@ describe("applyScene3DEditOperations", () => {
   })
 
   it("refuses to remove an object a reference points at", () => {
-    const referenced: Scene3DPlan = {
+    const referenced: Scene3DPlanV1 = {
       ...plan({ objects: [object("hero"), object("prop")] }),
       references: [{ id: "r1", url: "https://x.test/a.png", kind: "image", role: "appearance", objectId: "prop" }],
     }
@@ -378,7 +378,7 @@ describe("applyScene3DEditOperations", () => {
   })
 
   it("rejects an invalid input plan without applying anything", () => {
-    const result = applyScene3DEditOperations({ ...base, objects: [] } as Scene3DPlan, [
+    const result = applyScene3DEditOperations({ ...base, objects: [] } as Scene3DPlanV1, [
       { op: "set-background", color: "#000000" },
     ])
     expect(result.ok).toBe(false)

package/src/index.ts

@@ -1057,6 +1057,10 @@ export type { EntityNodeKind } from "./entity-node-fields.js"
 //     SDK/MCP surface. Structure only — no prompts, no pricing. ---
 export * from "./scene3d.js"
 export * from "./scene3d-edit.js"
+export * from "./scene3d-v2.js"
+export * from "./scene3d-v2-plan.js"
+export * from "./scene3d-v2-resources.js"
+export * from "./scene3d-camera-track.js"
 
 // --- transient studio keys — the public share read strips them ---
 export {
@@ -1064,3 +1068,5 @@ export {
   STUDIO_SHOT_TRANSIENT_KEYS,
   stripStudioTransientSettings,
 } from "./studio-transient.js"
+
+export * from "./scene3d-v2-edit.js"

package/src/scene3d-camera-track.ts

@@ -0,0 +1,369 @@
+/**
+ * The Scene3D v2 camera sidecar — one baked sample per frame.
+ *
+ * A 30-second scene is 720 camera samples. V1's 240-keyframe interpolated track
+ * cannot carry that, and interpolating a sparse track across a hard cut blends
+ * two shots into a frame that belongs to neither. So v2 moves the camera out of
+ * the manifest into this dense JSON asset, and the rule becomes trivial:
+ *
+ *   **at integer frame `f`, use `samples[f]`.**
+ *
+ * No interpolation, no easing, no "nearest key". Pausing, scrubbing backwards
+ * and rendering frames out of order therefore produce identical state, which is
+ * the whole reason preview and export can be trusted to agree.
+ *
+ * Two things this format refuses to guess at:
+ *
+ * - **Orientation is a quaternion, not a look-at.** A renderer that replaces the
+ *   exported quaternion with `lookAt(target)` throws away the authored roll and
+ *   the handheld component. `target` is carried for inspection and intent only.
+ * - **Projection is a matrix, not a lens number.** A focal length cannot express
+ *   sensor fit or lens shift, and re-deriving a projection at a different aspect
+ *   silently reframes every shot. `focalLengthMm` is metadata; the 16-element
+ *   column-major matrix is authoritative.
+ *
+ * Changing fps or aspect ratio is an explicit resample/reprojection producing a
+ * NEW revision — never a render-time override. `scene3DCameraTrackPlanIssues`
+ * is what makes that non-negotiable.
+ */
+import { z } from "zod"
+import {
+  SCENE3D_V2_LIMITS,
+  scene3DJsonByteLength,
+  scene3DZodIssues,
+  type Scene3DParseResult,
+  type Scene3DPlanV2,
+} from "./scene3d-v2.js"
+import { SCENE3D_LIMITS, type Scene3DSemanticIssue, type Vec3 } from "./scene3d.js"
+
+export const SCENE3D_CAMERA_TRACK_FORMAT = "scene3d-camera-track"
+export const SCENE3D_CAMERA_TRACK_VERSION = 1
+
+export const SCENE3D_CAMERA_TRACK_LIMITS = {
+  maxJsonBytes: SCENE3D_V2_LIMITS.maxCameraTrackBytes,
+  maxFrameCount: SCENE3D_V2_LIMITS.maxDurationInFrames,
+  minFps: SCENE3D_V2_LIMITS.minFps,
+  maxFps: SCENE3D_V2_LIMITS.maxFps,
+  /** A unit quaternion off by more than this is a bug, not float noise. */
+  quaternionTolerance: 1e-4,
+  /** Absolute tolerance on the projection entries that must be exactly zero
+   *  (or exactly ∓1) in a perspective matrix. */
+  projectionEpsilon: 1e-6,
+  /** Relative tolerance when comparing declared near/far against the values the
+   *  projection matrix implies. */
+  nearFarRelativeTolerance: 1e-3,
+  /** Relative tolerance on `m[0]/m[5]` vs the manifest's `height/width`. */
+  aspectRelativeTolerance: 1e-3,
+  minNear: 1e-4,
+  maxFar: 1e7,
+} as const
+
+export interface Scene3DCameraSample {
+  position: Vec3
+  /** `[x, y, z, w]` — that order, normalized. */
+  quaternion: [number, number, number, number]
+  /** Exactly 16 entries, COLUMN-MAJOR (Three.js `Matrix4.elements` order). */
+  projectionMatrix: number[]
+  near: number
+  far: number
+  /** Authoring intent, for inspection and validation reporting. A renderer must
+   *  never feed this back through `lookAt()`. */
+  target?: Vec3
+  /** Metadata only; the projection matrix wins. */
+  focalLengthMm?: number
+}
+
+export interface Scene3DCameraTrackV1 {
+  format: typeof SCENE3D_CAMERA_TRACK_FORMAT
+  version: typeof SCENE3D_CAMERA_TRACK_VERSION
+  /** Always 0: public frames are zero-based, and the exporter has already
+   *  subtracted the authoring package's start frame. */
+  frameStart: 0
+  frameCount: number
+  fps: number
+  samples: Scene3DCameraSample[]
+}
+
+const coordinate = z.number().min(-SCENE3D_LIMITS.maxCoordinate).max(SCENE3D_LIMITS.maxCoordinate)
+const positionSchema = z.tuple([coordinate, coordinate, coordinate])
+
+export const scene3DCameraSampleSchema = z
+  .object({
+    position: positionSchema,
+    quaternion: z.tuple([z.number(), z.number(), z.number(), z.number()]),
+    projectionMatrix: z.array(z.number()).length(16),
+    near: z.number().min(SCENE3D_CAMERA_TRACK_LIMITS.minNear).max(SCENE3D_CAMERA_TRACK_LIMITS.maxFar),
+    far: z.number().min(SCENE3D_CAMERA_TRACK_LIMITS.minNear).max(SCENE3D_CAMERA_TRACK_LIMITS.maxFar),
+    target: positionSchema.optional(),
+    focalLengthMm: z
+      .number()
+      .min(SCENE3D_LIMITS.minFocalLengthMm)
+      .max(SCENE3D_LIMITS.maxFocalLengthMm)
+      .optional(),
+  })
+  .strict()
+
+/** Structure only; `scene3DCameraTrackIssues` carries the numeric rules. */
+export const scene3DCameraTrackObjectSchema = z
+  .object({
+    format: z.literal(SCENE3D_CAMERA_TRACK_FORMAT),
+    version: z.literal(SCENE3D_CAMERA_TRACK_VERSION),
+    frameStart: z.literal(0),
+    frameCount: z.number().int().min(1).max(SCENE3D_CAMERA_TRACK_LIMITS.maxFrameCount),
+    fps: z.number().int().min(SCENE3D_CAMERA_TRACK_LIMITS.minFps).max(SCENE3D_CAMERA_TRACK_LIMITS.maxFps),
+    samples: z.array(scene3DCameraSampleSchema).min(1).max(SCENE3D_CAMERA_TRACK_LIMITS.maxFrameCount),
+  })
+  .strict()
+
+type Issue = Scene3DSemanticIssue
+
+/**
+ * Is this a real PERSPECTIVE projection, and does it agree with the declared
+ * near/far?
+ *
+ * Column-major layout produced by every Three.js/glTF perspective camera:
+ *
+ * ```text
+ *   m0   0   m8   0
+ *    0  m5   m9   0
+ *    0   0  m10  m14
+ *    0   0   -1   0
+ * ```
+ *
+ * `m8`/`m9` carry lens shift and are free. Everything else is pinned. Inverting
+ * the two depth terms recovers `near = m14 / (m10 - 1)` and
+ * `far = m14 / (m10 + 1)`, which is how a matrix that quietly disagrees with its
+ * own declared clip planes gets caught.
+ *
+ * Exported because the builder validates its export with the same function the
+ * renderer admits it with.
+ */
+export function scene3DProjectionIssues(
+  matrix: readonly number[],
+  near: number,
+  far: number,
+  path: (string | number)[],
+): Issue[] {
+  const issues: Issue[] = []
+  const eps = SCENE3D_CAMERA_TRACK_LIMITS.projectionEpsilon
+
+  if (matrix.length !== 16) {
+    issues.push({ path, message: `projection matrix must have exactly 16 entries (got ${matrix.length})` })
+    return issues
+  }
+  if (matrix.some((value) => !Number.isFinite(value))) {
+    issues.push({ path, message: "projection matrix contains a non-finite entry" })
+    return issues
+  }
+
+  // Orthographic is a future explicit capability. Name it, so it is never
+  // mis-read as a broken perspective matrix.
+  if (Math.abs(matrix[11]) < eps && Math.abs(matrix[15] - 1) < eps) {
+    issues.push({
+      path,
+      message: "projection matrix is orthographic; only perspective cameras are supported by this schema version",
+    })
+    return issues
+  }
+
+  for (const index of [1, 2, 3, 4, 6, 7, 12, 13, 15]) {
+    if (Math.abs(matrix[index]) > eps) {
+      issues.push({ path: [...path, index], message: `projection matrix entry ${index} must be 0 (got ${matrix[index]})` })
+    }
+  }
+  if (Math.abs(matrix[11] + 1) > eps) {
+    issues.push({ path: [...path, 11], message: `projection matrix entry 11 must be -1 for a perspective camera (got ${matrix[11]})` })
+  }
+  if (!(matrix[0] > 0)) {
+    issues.push({ path: [...path, 0], message: `projection matrix entry 0 must be positive (got ${matrix[0]})` })
+  }
+  if (!(matrix[5] > 0)) {
+    issues.push({ path: [...path, 5], message: `projection matrix entry 5 must be positive (got ${matrix[5]})` })
+  }
+  if (!(matrix[10] < 0)) {
+    issues.push({ path: [...path, 10], message: `projection matrix entry 10 must be negative (got ${matrix[10]})` })
+  }
+  if (!(matrix[14] < 0)) {
+    issues.push({ path: [...path, 14], message: `projection matrix entry 14 must be negative (got ${matrix[14]})` })
+  }
+  if (issues.length > 0) return issues
+
+  if (!(near > 0) || !(far > near)) {
+    issues.push({ path, message: `near/far must satisfy 0 < near < far (got near ${near}, far ${far})` })
+    return issues
+  }
+
+  const tolerance = SCENE3D_CAMERA_TRACK_LIMITS.nearFarRelativeTolerance
+  const impliedNear = matrix[14] / (matrix[10] - 1)
+  if (Math.abs(impliedNear - near) > Math.abs(near) * tolerance) {
+    issues.push({
+      path,
+      message: `projection matrix implies near ${impliedNear.toPrecision(6)}, but the sample declares ${near}`,
+    })
+  }
+  const farDenominator = matrix[10] + 1
+  if (Math.abs(farDenominator) < eps) {
+    issues.push({
+      path,
+      message: `projection matrix implies an infinite far plane, but the sample declares ${far}`,
+    })
+  } else {
+    const impliedFar = matrix[14] / farDenominator
+    if (Math.abs(impliedFar - far) > Math.abs(far) * tolerance) {
+      issues.push({
+        path,
+        message: `projection matrix implies far ${impliedFar.toPrecision(6)}, but the sample declares ${far}`,
+      })
+    }
+  }
+
+  return issues
+}
+
+/**
+ * The numeric rules the schema cannot express: exact sample count, normalized
+ * quaternions, and a real perspective projection on every frame.
+ *
+ * Split out of the schema (as v1 does) so a caller holding a parsed track can
+ * re-check it, and so the per-sample walk stays one readable loop over up to
+ * 3,600 samples.
+ */
+export function scene3DCameraTrackIssues(track: Scene3DCameraTrackV1): Issue[] {
+  const issues: Issue[] = []
+
+  if (track.samples.length !== track.frameCount) {
+    issues.push({
+      path: ["samples"],
+      message: `track declares ${track.frameCount} frames but carries ${track.samples.length} samples; exactly one sample per frame is required`,
+    })
+  }
+
+  const quaternionTolerance = SCENE3D_CAMERA_TRACK_LIMITS.quaternionTolerance
+  track.samples.forEach((sample, index) => {
+    const [x, y, z, w] = sample.quaternion
+    const norm = Math.sqrt(x * x + y * y + z * z + w * w)
+    if (Math.abs(norm - 1) > quaternionTolerance) {
+      issues.push({
+        path: ["samples", index, "quaternion"],
+        message: `quaternion at frame ${index} has length ${norm.toPrecision(6)}; it must be normalized`,
+      })
+    }
+    if (!(sample.far > sample.near)) {
+      issues.push({
+        path: ["samples", index, "far"],
+        message: `frame ${index}: far (${sample.far}) must be greater than near (${sample.near})`,
+      })
+    }
+    for (const issue of scene3DProjectionIssues(
+      sample.projectionMatrix,
+      sample.near,
+      sample.far,
+      ["samples", index, "projectionMatrix"],
+    )) {
+      issues.push(issue)
+    }
+  })
+
+  return issues
+}
+
+/** THE camera-track validator: structure, then the numeric rules. */
+export const scene3DCameraTrackSchema = scene3DCameraTrackObjectSchema.superRefine((track, ctx) => {
+  for (const issue of scene3DCameraTrackIssues(track as Scene3DCameraTrackV1)) {
+    ctx.addIssue({ code: "custom", path: issue.path, message: issue.message })
+  }
+})
+
+export function isScene3DCameraTrack(value: unknown): value is Scene3DCameraTrackV1 {
+  return scene3DCameraTrackSchema.safeParse(value).success
+}
+
+/**
+ * Track ↔ manifest agreement. A track that is valid on its own can still be the
+ * WRONG track for this scene: a different fps, a different length, or a
+ * projection baked for another aspect ratio. Each of those silently reframes or
+ * retimes every shot, so each is an error here rather than a render-time
+ * surprise.
+ */
+export function scene3DCameraTrackPlanIssues(
+  track: Scene3DCameraTrackV1,
+  plan: Pick<Scene3DPlanV2, "fps" | "durationInFrames" | "width" | "height">,
+): Issue[] {
+  const issues: Issue[] = []
+
+  if (track.fps !== plan.fps) {
+    issues.push({
+      path: ["fps"],
+      message: `camera track is ${track.fps} fps but the scene is ${plan.fps} fps; changing fps requires an explicit resample and a new revision`,
+    })
+  }
+  if (track.frameCount !== plan.durationInFrames) {
+    issues.push({
+      path: ["frameCount"],
+      message: `camera track covers ${track.frameCount} frames but the scene is ${plan.durationInFrames} frames`,
+    })
+  }
+
+  // m[0]/m[5] === (t-b)/(r-l) === height/width for any perspective matrix,
+  // including a shifted one (shift moves m[8]/m[9], not the frustum extents).
+  const expected = plan.height / plan.width
+  const tolerance = SCENE3D_CAMERA_TRACK_LIMITS.aspectRelativeTolerance
+  track.samples.forEach((sample, index) => {
+    const m0 = sample.projectionMatrix[0]
+    const m5 = sample.projectionMatrix[5]
+    if (!Number.isFinite(m0) || !Number.isFinite(m5) || m5 === 0) return
+    const actual = m0 / m5
+    if (Math.abs(actual - expected) > expected * tolerance) {
+      issues.push({
+        path: ["samples", index, "projectionMatrix"],
+        message: `frame ${index}: projection is baked for aspect ${(1 / actual).toPrecision(6)} but the scene renders ${plan.width}×${plan.height}; reprojection requires a new revision`,
+      })
+    }
+  })
+
+  return issues
+}
+
+/**
+ * The sample for an integer frame. `undefined` outside `[0, frameCount)` — a
+ * caller must fail rather than clamp, because a clamped frame is a wrong frame
+ * that looks plausible.
+ */
+export function scene3DSampleForFrame(
+  track: Scene3DCameraTrackV1,
+  frame: number,
+): Scene3DCameraSample | undefined {
+  if (!Number.isInteger(frame) || frame < 0 || frame >= track.frameCount) return undefined
+  return track.samples[frame]
+}
+
+/**
+ * Size-gate, then parse, then validate. This is the admission path for a
+ * downloaded camera track: an 80 MiB "8 MiB" track is refused before
+ * `JSON.parse` gets a chance to allocate it.
+ */
+export function parseScene3DCameraTrackJson(text: string): Scene3DParseResult<Scene3DCameraTrackV1> {
+  const bytes = scene3DJsonByteLength(text)
+  if (bytes > SCENE3D_CAMERA_TRACK_LIMITS.maxJsonBytes) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: [],
+          message: `camera track is ${bytes} bytes; the limit is ${SCENE3D_CAMERA_TRACK_LIMITS.maxJsonBytes}`,
+        },
+      ],
+    }
+  }
+  let decoded: unknown
+  try {
+    decoded = JSON.parse(text)
+  } catch {
+    return { ok: false, issues: [{ path: [], message: "camera track is not valid JSON" }] }
+  }
+  const parsed = scene3DCameraTrackSchema.safeParse(decoded)
+  if (!parsed.success) {
+    return { ok: false, issues: scene3DZodIssues(parsed.error) }
+  }
+  return { ok: true, value: parsed.data as Scene3DCameraTrackV1 }
+}

package/src/scene3d-edit.ts

@@ -22,12 +22,12 @@ import {
   scene3DIdSchema,
   scene3DObjectKeyframeSchema,
   scene3DObjectSchema,
-  scene3DPlanSchema,
+  scene3DPlanV1Schema,
   scene3DPrimitiveSchema,
   sizeVec3Schema,
   vec3Schema,
   type Scene3DObject,
-  type Scene3DPlan,
+  type Scene3DPlanV1,
 } from "./scene3d.js"
 
 
@@ -119,14 +119,14 @@ export interface Scene3DEditOptions {
 }
 
 export type Scene3DEditResult =
-  | { ok: true; plan: Scene3DPlan; changedObjectIds: string[]; changeSummary: string }
+  | { ok: true; plan: Scene3DPlanV1; 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
+function clonePlan(plan: Scene3DPlanV1): Scene3DPlanV1 {
+  return JSON.parse(JSON.stringify(plan)) as Scene3DPlanV1
 }
 
 /** One human sentence per operation — the deterministic lane's answer to the
@@ -183,15 +183,15 @@ function firstIssueMessage(error: z.ZodError): string {
  *    at.
  */
 export function applyScene3DEditOperations(
-  plan: Scene3DPlan,
+  plan: Scene3DPlanV1,
   operations: readonly Scene3DEditOperation[] | unknown,
   options: Scene3DEditOptions = {},
 ): Scene3DEditResult {
-  const parsedPlan = scene3DPlanSchema.safeParse(plan)
+  const parsedPlan = scene3DPlanV1Schema.safeParse(plan)
   if (!parsedPlan.success) {
     return { ok: false, code: "invalid_plan", message: `scenePlan is invalid — ${firstIssueMessage(parsedPlan.error)}` }
   }
-  const source = parsedPlan.data as Scene3DPlan
+  const source = parsedPlan.data as Scene3DPlanV1
 
   if (options.expectedRevisionId !== undefined && options.expectedRevisionId !== source.revisionId) {
     return {
@@ -293,7 +293,7 @@ export function applyScene3DEditOperations(
   next.parentRevisionId = source.revisionId
   next.revisionId = options.revisionId ?? newScene3DRevisionId()
 
-  const validated = scene3DPlanSchema.safeParse(next)
+  const validated = scene3DPlanV1Schema.safeParse(next)
   if (!validated.success) {
     return {
       ok: false,
@@ -304,7 +304,7 @@ export function applyScene3DEditOperations(
 
   return {
     ok: true,
-    plan: validated.data as Scene3DPlan,
+    plan: validated.data as Scene3DPlanV1,
     changedObjectIds: [...changed],
     changeSummary: summarizeScene3DOperations(ops),
   }

package/src/scene3d-v2-edit.ts

@@ -0,0 +1,156 @@
+/** Immutable, deterministic edits over a baked scene. No asset bytes are mutated. */
+import { z } from "zod"
+import {
+  newScene3DRevisionId, rotationVec3Schema, scaleVec3Schema,
+  scene3DColorSchema, scene3DIdSchema, vec3Schema,
+} from "./scene3d.js"
+import {
+  SCENE3D_V2_OVERRIDE_OPERATION_VERSION, scene3DMaterialRoleSchema,
+  type Scene3DEntityCapability, type Scene3DOverride, type Scene3DPlanV2,
+} from "./scene3d-v2.js"
+import { scene3DPlanV2Schema } from "./scene3d-v2-plan.js"
+import { computeScene3DPlanV2ContentHash, verifyScene3DPlanV2ContentHash } from "./scene3d-v2-resources.js"
+
+/** Callers describe values. Revision identity and provenance are assigned here. */
+export const scene3DV2OverrideInputSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("entity-transform"), entityId: scene3DIdSchema,
+    space: z.enum(["local", "world"]), position: vec3Schema.optional(),
+    rotation: rotationVec3Schema.optional(), scale: scaleVec3Schema.optional(),
+  }).strict(),
+  z.object({ kind: z.literal("entity-color"), entityId: scene3DIdSchema,
+    materialRole: scene3DMaterialRoleSchema, color: scene3DColorSchema,
+  }).strict(),
+  z.object({ kind: z.literal("entity-visibility"), entityId: scene3DIdSchema, visible: z.boolean() }).strict(),
+  z.object({ kind: z.literal("camera-shot-offset"), shotId: scene3DIdSchema,
+    positionOffset: vec3Schema.optional(), targetOffset: vec3Schema.optional(),
+  }).strict(),
+])
+export const scene3DV2EditOperationSchema = z.discriminatedUnion("op", [
+  z.object({ op: z.literal("set-override"), override: scene3DV2OverrideInputSchema }).strict(),
+  z.object({ op: z.literal("remove-override"), overrideId: scene3DIdSchema }).strict(),
+])
+export const scene3DV2EditOperationsSchema = z.array(scene3DV2EditOperationSchema).min(1).max(100)
+export type Scene3DV2OverrideInput = z.infer<typeof scene3DV2OverrideInputSchema>
+export type Scene3DV2EditOperation = z.infer<typeof scene3DV2EditOperationSchema>
+
+export interface Scene3DV2EditOptions {
+  expectedRevisionId: string
+  expectedContentHash?: string
+  lockedObjectIds?: readonly string[]
+  /** Hosts may allocate identity at admission for idempotent job replay. */
+  newRevisionId?: string
+}
+export type Scene3DV2EditResult =
+  | { ok: true; plan: Scene3DPlanV2; changeSummary: string }
+  | { ok: false; code: "invalid_plan" | "invalid_operations" | "stale_revision" | "locked"; message: string }
+
+function channel(override: Scene3DV2OverrideInput): string {
+  switch (override.kind) {
+    case "entity-transform": return `transform:${override.entityId}`
+    case "entity-color": return `color:${override.entityId}:${override.materialRole}`
+    case "entity-visibility": return `visibility:${override.entityId}`
+    case "camera-shot-offset": return `camera:${override.shotId}`
+  }
+}
+function capability(override: Scene3DV2OverrideInput): Scene3DEntityCapability | null {
+  switch (override.kind) {
+    case "entity-transform": return "transform"
+    case "entity-color": return "color"
+    case "entity-visibility": return "visibility"
+    case "camera-shot-offset": return null
+  }
+}
+
+/** A parent's transform or visibility changes its descendants too. */
+function lockIssue(plan: Scene3DPlanV2, override: Scene3DV2OverrideInput, externalLocks: ReadonlySet<string>): string | null {
+  if (override.kind === "camera-shot-offset") return null
+  const target = plan.objects.find((o) => o.id === override.entityId)
+  if (!target) return `Unknown entity: ${override.entityId}`
+  const cap = capability(override)!
+  if (target.capabilities && !target.capabilities.includes(cap)) return `Entity ${target.id} does not allow ${cap} edits`
+  if (externalLocks.has(target.id) || target.locks?.includes(cap)) return `Entity ${target.id} is locked for ${cap}`
+  if (cap !== "transform" && cap !== "visibility") return null
+  const byId = new Map(plan.objects.map((entity) => [entity.id, entity]))
+  for (const entity of plan.objects) {
+    if (!externalLocks.has(entity.id) && !entity.locks?.includes(cap)) continue
+    let parent = entity.parentId
+    while (parent) {
+      if (parent === target.id) return `Changing ${target.id} would change locked descendant ${entity.id}`
+      parent = byId.get(parent)?.parentId
+    }
+  }
+  return null
+}
+
+/**
+ * Edits are all-or-nothing. The expected revision and content hash are checked
+ * before writing, and the result is validated and hashed before acceptance.
+ * A source file belongs to its exact base revision: until the host materializes
+ * these edits, the new revision must not advertise the old native download.
+ */
+export async function applyScene3DV2EditOperations(
+  input: Scene3DPlanV2,
+  operations: readonly Scene3DV2EditOperation[],
+  options: Scene3DV2EditOptions,
+): Promise<Scene3DV2EditResult> {
+  const parsed = scene3DPlanV2Schema.safeParse(input)
+  if (!parsed.success) return { ok: false, code: "invalid_plan", message: parsed.error.issues[0]?.message ?? "Invalid scene" }
+  const base = parsed.data as Scene3DPlanV2
+  if (base.revisionId !== options.expectedRevisionId ||
+      (options.expectedContentHash !== undefined && base.provenance.contentHash !== options.expectedContentHash)) {
+    return { ok: false, code: "stale_revision", message: "The scene changed since this edit was prepared" }
+  }
+  if (!await verifyScene3DPlanV2ContentHash(base)) {
+    return { ok: false, code: "invalid_plan", message: "The scene content does not match its digest" }
+  }
+  const ops = scene3DV2EditOperationsSchema.safeParse(operations)
+  if (!ops.success) return { ok: false, code: "invalid_operations", message: ops.error.issues[0]?.message ?? "Invalid edit" }
+  const revisionId = options.newRevisionId ?? newScene3DRevisionId()
+  if (revisionId === base.revisionId) return { ok: false, code: "invalid_operations", message: "An edit requires a new revision identity" }
+  const externalLocks = new Set(options.lockedObjectIds ?? [])
+  for (const id of externalLocks) {
+    if (!base.objects.some((entity) => entity.id === id)) return { ok: false, code: "invalid_operations", message: `Unknown locked entity: ${id}` }
+  }
+  let overrides = [...(base.overrides ?? [])]
+  for (const [index, operation] of ops.data.entries()) {
+    if (operation.op === "remove-override") {
+      const existing = overrides.find((override) => override.id === operation.overrideId)
+      if (!existing) return { ok: false, code: "invalid_operations", message: `Unknown override: ${operation.overrideId}` }
+      const issue = lockIssue(base, existing, externalLocks)
+      if (issue) return { ok: false, code: "locked", message: issue }
+      overrides = overrides.filter((override) => override.id !== existing.id)
+      continue
+    }
+    const issue = lockIssue(base, operation.override, externalLocks)
+    if (issue) return { ok: false, code: "locked", message: issue }
+    const previous = overrides.find((override) => channel(override) === channel(operation.override))
+    const compatible = previous && (previous.kind !== "entity-transform" ||
+      (operation.override.kind === "entity-transform" && previous.space === operation.override.space))
+    const next: Scene3DOverride = {
+      ...(compatible ? previous : {}),
+      ...operation.override,
+      id: `edit-${revisionId}-${index}`,
+      sourceRevisionId: base.revisionId,
+      sourceContentHash: base.provenance.contentHash,
+      operationVersion: SCENE3D_V2_OVERRIDE_OPERATION_VERSION,
+    }
+    const key = channel(next)
+    overrides = [...overrides.filter((override) => channel(override) !== key), next]
+  }
+  const { sourceArtifactId: _sourceArtifactId, ...provenance } = base.provenance
+  const next: Scene3DPlanV2 = {
+    ...base, revisionId, parentRevisionId: base.revisionId,
+    // Geometry and cameras are reused; derived images, validation and native
+    // exports describe the old revision until regenerated for these overlays.
+    assets: base.assets.filter((asset) => asset.kind === "glb" || asset.kind === "camera-track-json").map((asset) => ({
+      ...asset, originRevisionId: asset.originRevisionId ?? base.revisionId,
+    })),
+    overrides,
+    provenance: { ...provenance, sourceRevisionId: base.revisionId },
+  }
+  const validated = scene3DPlanV2Schema.safeParse(next)
+  if (!validated.success) return { ok: false, code: "invalid_operations", message: validated.error.issues[0]?.message ?? "Invalid edited scene" }
+  const plan = validated.data as Scene3DPlanV2
+  const contentHash = await computeScene3DPlanV2ContentHash(plan)
+  return { ok: true, plan: { ...plan, provenance: { ...plan.provenance, contentHash } }, changeSummary: `Applied ${ops.data.length} scene edit${ops.data.length === 1 ? "" : "s"}` }
+}