@nodaro/shared 2.27.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.27.0",
+  "version": "3.0.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/scene3d-camera-track.test.ts

@@ -0,0 +1,235 @@
+import { describe, expect, it } from "vitest"
+import {
+  SCENE3D_CAMERA_TRACK_LIMITS,
+  isScene3DCameraTrack,
+  parseScene3DCameraTrackJson,
+  scene3DCameraTrackIssues,
+  scene3DCameraTrackPlanIssues,
+  scene3DCameraTrackSchema,
+  scene3DProjectionIssues,
+  scene3DSampleForFrame,
+} from "../scene3d-camera-track.js"
+import {
+  FIXTURE_FPS,
+  FIXTURE_FRAMES,
+  FIXTURE_HEIGHT,
+  FIXTURE_WIDTH,
+  cameraSample,
+  cameraTrack,
+  orthographicMatrix,
+  perspectiveMatrix,
+  planV2,
+} from "./scene3d-v2-fixtures.js"
+
+function joined(track: unknown): string {
+  const result = scene3DCameraTrackSchema.safeParse(track)
+  return result.success ? "" : result.error.issues.map((issue) => issue.message).join(" | ")
+}
+
+describe("scene3d camera track — structure", () => {
+  it("accepts a full 720-sample track", () => {
+    const track = cameraTrack()
+    expect(scene3DCameraTrackSchema.safeParse(track).success).toBe(true)
+    expect(isScene3DCameraTrack(track)).toBe(true)
+    expect(scene3DCameraTrackIssues(track)).toEqual([])
+  })
+
+  it("accepts the maximum frame count and rejects one more", () => {
+    expect(SCENE3D_CAMERA_TRACK_LIMITS.maxFrameCount).toBe(3600)
+    expect(scene3DCameraTrackSchema.safeParse(cameraTrack(3600)).success).toBe(true)
+    expect(scene3DCameraTrackSchema.safeParse(cameraTrack(3601)).success).toBe(false)
+  })
+
+  it("requires exactly one sample per frame", () => {
+    const short = cameraTrack(10)
+    short.samples = short.samples.slice(0, 9)
+    expect(joined(short)).toContain("exactly one sample per frame is required")
+
+    const long = cameraTrack(10)
+    long.samples.push(cameraSample())
+    expect(joined(long)).toContain("exactly one sample per frame is required")
+  })
+
+  it("pins the format, version and zero-based frame start", () => {
+    expect(joined({ ...cameraTrack(2), format: "something-else" })).not.toBe("")
+    expect(joined({ ...cameraTrack(2), version: 2 })).not.toBe("")
+    expect(joined({ ...cameraTrack(2), frameStart: 1 })).not.toBe("")
+  })
+
+  it("rejects unknown keys on the track and on a sample", () => {
+    expect(joined({ ...cameraTrack(2), extra: true })).not.toBe("")
+    const track = cameraTrack(2)
+    ;(track.samples[0] as unknown as Record<string, unknown>).lookAtOverride = [0, 0, 0]
+    expect(joined(track)).not.toBe("")
+  })
+
+  it("rejects a foreign value outright", () => {
+    for (const bad of [null, 7, "track", [], {}]) {
+      expect(isScene3DCameraTrack(bad)).toBe(false)
+    }
+  })
+})
+
+describe("scene3d camera track — quaternions", () => {
+  it("rejects an unnormalized quaternion", () => {
+    const track = cameraTrack(3)
+    track.samples[1] = cameraSample({ quaternion: [0, 0, 0, 2] })
+    expect(joined(track)).toContain("it must be normalized")
+  })
+
+  it("accepts float noise inside the tolerance", () => {
+    const track = cameraTrack(3)
+    track.samples[1] = cameraSample({ quaternion: [0, 0, 0, 1 + 1e-6] })
+    expect(scene3DCameraTrackSchema.safeParse(track).success).toBe(true)
+  })
+
+  it("rejects a non-finite quaternion component", () => {
+    const track = cameraTrack(2)
+    track.samples[0] = cameraSample({ quaternion: [0, 0, 0, Number.NaN] })
+    expect(scene3DCameraTrackSchema.safeParse(track).success).toBe(false)
+  })
+})
+
+describe("scene3d camera track — projection", () => {
+  const aspect = FIXTURE_WIDTH / FIXTURE_HEIGHT
+
+  it("accepts a real perspective matrix", () => {
+    expect(scene3DProjectionIssues(perspectiveMatrix(35, aspect, 0.1, 200), 0.1, 200, ["m"])).toEqual([])
+  })
+
+  it("names orthographic instead of mis-reading it as a broken perspective", () => {
+    const issues = scene3DProjectionIssues(orthographicMatrix(0.1, 200), 0.1, 200, ["m"])
+    expect(issues).toHaveLength(1)
+    expect(issues[0].message).toContain("orthographic")
+  })
+
+  it("rejects the wrong number of entries and non-finite entries", () => {
+    expect(scene3DProjectionIssues([1, 2, 3], 0.1, 200, ["m"])[0].message).toContain("exactly 16 entries")
+    const broken = perspectiveMatrix(35, aspect, 0.1, 200)
+    broken[0] = Number.POSITIVE_INFINITY
+    expect(scene3DProjectionIssues(broken, 0.1, 200, ["m"])[0].message).toContain("non-finite")
+  })
+
+  it("rejects a matrix whose fixed entries are not fixed", () => {
+    for (const index of [1, 2, 3, 4, 6, 7, 12, 13, 15]) {
+      const matrix = perspectiveMatrix(35, aspect, 0.1, 200)
+      matrix[index] = 0.5
+      const issues = scene3DProjectionIssues(matrix, 0.1, 200, ["m"])
+      expect(issues.length).toBeGreaterThan(0)
+    }
+    const notPerspective = perspectiveMatrix(35, aspect, 0.1, 200)
+    notPerspective[11] = -0.5
+    expect(scene3DProjectionIssues(notPerspective, 0.1, 200, ["m"])[0].message).toContain("must be -1")
+  })
+
+  it("rejects a matrix that disagrees with its own declared near/far", () => {
+    const matrix = perspectiveMatrix(35, aspect, 0.1, 200)
+    const nearIssues = scene3DProjectionIssues(matrix, 0.5, 200, ["m"])
+    expect(nearIssues.map((issue) => issue.message).join(" ")).toContain("implies near")
+
+    const farIssues = scene3DProjectionIssues(matrix, 0.1, 500, ["m"])
+    expect(farIssues.map((issue) => issue.message).join(" ")).toContain("implies far")
+  })
+
+  it("rejects an infinite-far matrix that declares a finite far plane", () => {
+    const matrix = perspectiveMatrix(35, aspect, 0.1, 200)
+    matrix[10] = -1
+    matrix[14] = -0.2
+    expect(scene3DProjectionIssues(matrix, 0.1, 200, ["m"]).map((i) => i.message).join(" ")).toContain(
+      "infinite far plane",
+    )
+  })
+
+  it("rejects near/far that are not strictly ordered", () => {
+    const track = cameraTrack(2)
+    track.samples[0] = cameraSample({ near: 200, far: 200 })
+    expect(joined(track)).toContain("must be greater than near")
+  })
+})
+
+describe("scene3d camera track — agreement with the manifest", () => {
+  const plan = planV2()
+
+  it("accepts a matching track", () => {
+    expect(scene3DCameraTrackPlanIssues(cameraTrack(), plan)).toEqual([])
+  })
+
+  it("rejects a different fps — retiming needs a new revision", () => {
+    const track = cameraTrack(FIXTURE_FRAMES, { fps: 30 })
+    const messages = scene3DCameraTrackPlanIssues(track, plan).map((issue) => issue.message)
+    expect(messages.join(" ")).toContain("changing fps requires an explicit resample")
+    expect(FIXTURE_FPS).toBe(24)
+  })
+
+  it("rejects a different length", () => {
+    const messages = scene3DCameraTrackPlanIssues(cameraTrack(600), plan).map((issue) => issue.message)
+    expect(messages.join(" ")).toContain("covers 600 frames but the scene is 720 frames")
+  })
+
+  it("rejects a projection baked for another aspect ratio", () => {
+    const track = cameraTrack(4)
+    track.samples[2] = cameraSample({ projectionMatrix: perspectiveMatrix(35, 16 / 9, 0.1, 200) })
+    const messages = scene3DCameraTrackPlanIssues(track, {
+      fps: FIXTURE_FPS,
+      durationInFrames: 4,
+      width: FIXTURE_WIDTH,
+      height: FIXTURE_HEIGHT,
+    }).map((issue) => issue.message)
+    expect(messages.join(" ")).toContain("reprojection requires a new revision")
+  })
+})
+
+describe("scene3d camera track — deterministic sampling", () => {
+  it("maps frame f to samples[f], and refuses to clamp", () => {
+    const track = cameraTrack(10)
+    for (const frame of [0, 4, 9]) {
+      expect(scene3DSampleForFrame(track, frame)).toBe(track.samples[frame])
+    }
+    expect(scene3DSampleForFrame(track, 10)).toBeUndefined()
+    expect(scene3DSampleForFrame(track, -1)).toBeUndefined()
+    expect(scene3DSampleForFrame(track, 2.5)).toBeUndefined()
+  })
+
+  it("is order-independent: backwards and shuffled reads give identical samples", () => {
+    const track = cameraTrack(24)
+    const forward = Array.from({ length: 24 }, (_unused, frame) => scene3DSampleForFrame(track, frame))
+    const backward = Array.from({ length: 24 }, (_unused, index) => scene3DSampleForFrame(track, 23 - index)).reverse()
+    const shuffled = [7, 0, 23, 12, 3].map((frame) => scene3DSampleForFrame(track, frame))
+    expect(backward).toEqual(forward)
+    expect(shuffled).toEqual([7, 0, 23, 12, 3].map((frame) => forward[frame]))
+  })
+})
+
+describe("scene3d camera track — JSON admission", () => {
+  it("accepts a well-formed payload", () => {
+    const result = parseScene3DCameraTrackJson(JSON.stringify(cameraTrack(12)))
+    expect(result.ok).toBe(true)
+  })
+
+  it("refuses an oversized payload before parsing it", () => {
+    const padding = "x".repeat(SCENE3D_CAMERA_TRACK_LIMITS.maxJsonBytes + 1)
+    const result = parseScene3DCameraTrackJson(padding)
+    expect(result.ok).toBe(false)
+    expect(result.ok ? "" : result.issues[0].message).toContain("the limit is")
+  })
+
+  it("reports malformed JSON as an issue rather than throwing", () => {
+    const result = parseScene3DCameraTrackJson("{ not json")
+    expect(result.ok).toBe(false)
+    expect(result.ok ? "" : result.issues[0].message).toContain("not valid JSON")
+  })
+
+  it("reports schema failures with paths", () => {
+    const track = cameraTrack(3)
+    track.samples[1] = cameraSample({ quaternion: [1, 1, 1, 1] })
+    const result = parseScene3DCameraTrackJson(JSON.stringify(track))
+    expect(result.ok).toBe(false)
+    expect(result.ok ? [] : result.issues.map((issue) => issue.path.join("."))).toContain("samples.1.quaternion")
+  })
+
+  it("counts bytes, not characters", () => {
+    // A multi-byte name must not slip past a length check that counted chars.
+    const text = JSON.stringify({ note: "é".repeat(10) })
+    expect(text.length).toBeLessThan(new TextEncoder().encode(text).length)
+  })
+})

package/src/__tests__/scene3d-v2-edit.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest"
+import { applyScene3DV2EditOperations } from "../scene3d-v2-edit.js"
+import { computeScene3DPlanV2ContentHash, verifyScene3DPlanV2ContentHash } from "../scene3d-v2-resources.js"
+import { planV2 } from "./scene3d-v2-fixtures.js"
+
+async function fixture() {
+  const p = planV2()
+  return { ...p, provenance: { ...p.provenance, contentHash: await computeScene3DPlanV2ContentHash(p) } }
+}
+const move = { op: "set-override" as const, override: { kind: "entity-transform" as const, entityId: "e2", space: "world" as const, position: [4, 0, 0] as [number, number, number] } }
+const revision = "c94b9f2f-4f10-48a6-a0bf-3ca4c2653b5a"
+
+describe("baked scene edits", () => {
+  it("preserves unrelated state, stamps an immutable revision, and withdraws a stale native download", async () => {
+    const p = await fixture()
+    const before = JSON.stringify(p)
+    const result = await applyScene3DV2EditOperations(p, [move], { expectedRevisionId: p.revisionId, newRevisionId: revision })
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.plan.revisionId).toBe(revision)
+    expect(result.plan.parentRevisionId).toBe(p.revisionId)
+    expect(result.plan.objects).toEqual(p.objects)
+    expect(result.plan.assets).toEqual(p.assets.filter((a) => a.kind === "glb" || a.kind === "camera-track-json").map((a) => ({ ...a, originRevisionId: a.originRevisionId ?? p.revisionId })))
+    expect(result.plan.provenance.sourceArtifactId).toBeUndefined()
+    expect(result.plan.overrides?.find((o) => o.kind === "entity-color")).toEqual(p.overrides?.find((o) => o.kind === "entity-color"))
+    expect(result.plan.overrides?.find((o) => o.kind === "entity-transform")).toMatchObject({ position: [4, 0, 0], sourceRevisionId: p.revisionId, sourceContentHash: p.provenance.contentHash })
+    expect(await verifyScene3DPlanV2ContentHash(result.plan)).toBe(true)
+    expect(JSON.stringify(p)).toBe(before)
+  })
+  it("replays identically with an admission-allocated revision", async () => {
+    const p = await fixture()
+    const options = { expectedRevisionId: p.revisionId, newRevisionId: revision }
+    expect(await applyScene3DV2EditOperations(p, [move], options)).toEqual(await applyScene3DV2EditOperations(p, [move], options))
+  })
+  it("withdraws images and validation that describe the previous revision", async () => {
+    const p = await fixture()
+    p.assets.push(
+      { assetId: "12b3a7d6-3aef-4e5f-b388-e6b96dcaa0f1", kind: "poster", role: "poster", sha256: "a".repeat(64), byteLength: 100 },
+      { assetId: "12b3a7d6-3aef-4e5f-b388-e6b96dcaa0f2", kind: "validation-report", role: "validation-report", sha256: "b".repeat(64), byteLength: 100 },
+    )
+    p.provenance.contentHash = await computeScene3DPlanV2ContentHash(p)
+    const result = await applyScene3DV2EditOperations(p, [move], { expectedRevisionId: p.revisionId })
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.plan.assets.every((a) => a.kind === "glb" || a.kind === "camera-track-json")).toBe(true)
+  })
+  it("rejects stale identity and content, and tampered manifests", async () => {
+    const p = await fixture()
+    expect(await applyScene3DV2EditOperations(p, [move], { expectedRevisionId: revision })).toMatchObject({ ok: false, code: "stale_revision" })
+    expect(await applyScene3DV2EditOperations(p, [move], { expectedRevisionId: p.revisionId, expectedContentHash: "a".repeat(64) })).toMatchObject({ ok: false, code: "stale_revision" })
+    expect(await applyScene3DV2EditOperations({ ...p, backgroundColor: "#ffffff" }, [move], { expectedRevisionId: p.revisionId })).toMatchObject({ ok: false, code: "invalid_plan" })
+  })
+  it("blocks changes and removal of changes on locked entities", async () => {
+    const p = await fixture()
+    const options = { expectedRevisionId: p.revisionId, lockedObjectIds: ["e2"] }
+    expect(await applyScene3DV2EditOperations(p, [move], options)).toMatchObject({ ok: false, code: "locked" })
+    expect(await applyScene3DV2EditOperations(p, [{ op: "remove-override", overrideId: "ov-1" }], options)).toMatchObject({ ok: false, code: "locked" })
+  })
+  it("cannot evade a descendant lock by moving or hiding its parent", async () => {
+    const p = await fixture()
+    const options = { expectedRevisionId: p.revisionId, lockedObjectIds: ["e2"] }
+    expect(await applyScene3DV2EditOperations(p, [{ ...move, override: { ...move.override, entityId: "e1" } }], options)).toMatchObject({ ok: false, code: "locked" })
+    expect(await applyScene3DV2EditOperations(p, [{ op: "set-override", override: { kind: "entity-visibility", entityId: "e1", visible: false } }], options)).toMatchObject({ ok: false, code: "locked" })
+  })
+  it("preserves edited pose components when another component changes", async () => {
+    const p = await fixture()
+    const result = await applyScene3DV2EditOperations(p, [move, { ...move, override: { kind: "entity-transform", entityId: "e2", space: "world", rotation: [0, 1, 0] } }], { expectedRevisionId: p.revisionId })
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.plan.overrides?.find((o) => o.kind === "entity-transform")).toMatchObject({ position: [4, 0, 0], rotation: [0, 1, 0] })
+  })
+  it("does not carry coordinates across a space change", async () => {
+    const p = await fixture()
+    const result = await applyScene3DV2EditOperations(p, [{ ...move, override: { kind: "entity-transform", entityId: "e2", space: "local", rotation: [0, 1, 0] } }], { expectedRevisionId: p.revisionId })
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.plan.overrides?.find((o) => o.kind === "entity-transform")).not.toHaveProperty("position")
+  })
+  it("rejects missing targets, unknown material roles, and invalid later operations atomically", async () => {
+    const p = await fixture()
+    const before = JSON.stringify(p)
+    expect(await applyScene3DV2EditOperations(p, [move, { op: "set-override", override: { kind: "entity-color", entityId: "e2", materialRole: "chair", color: "#ffffff" } }], { expectedRevisionId: p.revisionId })).toMatchObject({ ok: false, code: "invalid_operations" })
+    expect(await applyScene3DV2EditOperations(p, [{ op: "remove-override", overrideId: "missing" }], { expectedRevisionId: p.revisionId })).toMatchObject({ ok: false, code: "invalid_operations" })
+    expect(JSON.stringify(p)).toBe(before)
+  })
+})

package/src/__tests__/scene3d-v2-fixtures.ts

@@ -0,0 +1,232 @@
+/**
+ * Shared v2 fixtures. Deliberately generic (`e1`, `shot-1`, one car-ish
+ * assembly) — the contract has no opinion about what a scene contains, and a
+ * fixture that encodes one would quietly become a spec.
+ *
+ * The one non-arbitrary thing here is the SHAPE of the timeline: 720 frames at
+ * 24 fps cut into `[0,360) [360,432) [432,492) [492,720)`. That is the exact
+ * multi-shot arrangement the format has to carry, so every coverage test uses
+ * it rather than a two-shot toy.
+ */
+import {
+  SCENE3D_CAMERA_TRACK_FORMAT,
+  SCENE3D_CAMERA_TRACK_VERSION,
+  type Scene3DCameraSample,
+  type Scene3DCameraTrackV1,
+} from "../scene3d-camera-track.js"
+import { SCENE3D_SCHEMA_VERSION_V2, type Scene3DPlanV2, type Scene3DShot } from "../scene3d-v2.js"
+import { SCENE3D_PLAN_TYPE } from "../scene3d.js"
+
+export const FIXTURE_WIDTH = 1680
+export const FIXTURE_HEIGHT = 720
+export const FIXTURE_FPS = 24
+export const FIXTURE_FRAMES = 720
+
+/** The cut plan the format must be able to express exactly. */
+export const FIXTURE_CUTS: ReadonlyArray<readonly [number, number]> = [
+  [0, 360],
+  [360, 432],
+  [432, 492],
+  [492, 720],
+]
+
+const REVISION_ID = "6d5b0b64-2b6c-4d4a-9e4f-2f4b7f6a1c01"
+const PARENT_REVISION_ID = "6d5b0b64-2b6c-4d4a-9e4f-2f4b7f6a1c00"
+const HASH_A = "a".repeat(64)
+const HASH_B = "b".repeat(64)
+const HASH_C = "c".repeat(64)
+const HASH_D = "d".repeat(64)
+
+/**
+ * A symmetric column-major perspective matrix, exactly as Three.js and every
+ * glTF camera build one. `m[0]/m[5]` is `height/width`, which is what the
+ * manifest cross-check reads.
+ */
+export function perspectiveMatrix(
+  fovYDegrees: number,
+  aspect: number,
+  near: number,
+  far: number,
+): number[] {
+  const top = near * Math.tan((fovYDegrees * Math.PI) / 360)
+  const height = 2 * top
+  const width = height * aspect
+  const matrix = new Array<number>(16).fill(0)
+  matrix[0] = (2 * near) / width
+  matrix[5] = (2 * near) / height
+  matrix[10] = -(far + near) / (far - near)
+  matrix[11] = -1
+  matrix[14] = (-2 * far * near) / (far - near)
+  return matrix
+}
+
+/** An orthographic matrix — the thing the projection validator must NAME rather
+ *  than mis-read as a broken perspective. */
+export function orthographicMatrix(near: number, far: number): number[] {
+  const matrix = new Array<number>(16).fill(0)
+  matrix[0] = 1
+  matrix[5] = 1
+  matrix[10] = -2 / (far - near)
+  matrix[14] = -(far + near) / (far - near)
+  matrix[15] = 1
+  return matrix
+}
+
+export function cameraSample(overrides: Partial<Scene3DCameraSample> = {}): Scene3DCameraSample {
+  return {
+    position: [0, 1.5, 4],
+    quaternion: [0, 0, 0, 1],
+    projectionMatrix: perspectiveMatrix(35, FIXTURE_WIDTH / FIXTURE_HEIGHT, 0.1, 200),
+    near: 0.1,
+    far: 200,
+    ...overrides,
+  }
+}
+
+export function cameraTrack(
+  frameCount = FIXTURE_FRAMES,
+  overrides: Partial<Scene3DCameraTrackV1> = {},
+): Scene3DCameraTrackV1 {
+  return {
+    format: SCENE3D_CAMERA_TRACK_FORMAT,
+    version: SCENE3D_CAMERA_TRACK_VERSION,
+    frameStart: 0,
+    frameCount,
+    fps: FIXTURE_FPS,
+    samples: Array.from({ length: frameCount }, (_unused, frame) =>
+      cameraSample({ position: [frame / 100, 1.5, 4] }),
+    ),
+    ...overrides,
+  }
+}
+
+export function fixtureShots(): Scene3DShot[] {
+  return FIXTURE_CUTS.map(([startFrame, endFrameExclusive], index) => ({
+    id: `shot-${index + 1}`,
+    startFrame,
+    endFrameExclusive,
+    subjectEntityIds: ["e2"],
+    foregroundEntityIds: ["e3"],
+  }))
+}
+
+/**
+ * A complete, valid v2 manifest: one group assembly with an asset child and a
+ * primitive sibling, three renderer-visible assets plus a retained source, four
+ * contiguous shots, one of each override kind.
+ */
+export function planV2(overrides: Partial<Scene3DPlanV2> = {}): Scene3DPlanV2 {
+  return {
+    planType: SCENE3D_PLAN_TYPE,
+    schemaVersion: SCENE3D_SCHEMA_VERSION_V2,
+    revisionId: REVISION_ID,
+    parentRevisionId: PARENT_REVISION_ID,
+    width: FIXTURE_WIDTH,
+    height: FIXTURE_HEIGHT,
+    fps: FIXTURE_FPS,
+    durationInFrames: FIXTURE_FRAMES,
+    units: "meters",
+    upAxis: "Y",
+    handedness: "right",
+    objects: [
+      {
+        id: "e1",
+        name: "Assembly",
+        role: "other",
+        position: [0, 0, 0],
+        rotation: [0, 0, 0],
+        scale: [1, 1, 1],
+        visual: { kind: "group" },
+      },
+      {
+        id: "e2",
+        name: "Vehicle",
+        parentId: "e1",
+        role: "vehicle",
+        identityColor: "#3355ff",
+        anchors: [
+          { name: "roof", position: [0, 1.4, 0] },
+          { name: "wheel.frontLeft", position: [0.8, 0.3, 1.2] },
+        ],
+        capabilities: ["transform", "color", "visibility"],
+        materialBindings: [
+          { role: "bodyPaint", materialName: "Body Paint", color: "#3355ff" },
+          { role: "tires", materialName: "Rubber", roughness: 0.9 },
+        ],
+        visual: {
+          kind: "asset",
+          assetId: "asset-vehicle",
+          rootNodeId: "vehicle_root",
+          animation: { clipName: "drive", startFrame: 0, endFrameExclusive: 720 },
+        },
+      },
+      {
+        id: "e3",
+        name: "Marker",
+        role: "prop",
+        position: [2, 0, 0],
+        rotation: [0, 0, 0],
+        scale: [1, 1, 1],
+        visual: { kind: "primitive", primitive: "box", dimensions: [1, 1, 1], color: "#22cc88" },
+      },
+    ],
+    assets: [
+      { assetId: "asset-vehicle", kind: "glb", role: "entity-geometry", byteLength: 1_200_000, sha256: HASH_A },
+      { assetId: "asset-track", kind: "camera-track-json", role: "camera-track", byteLength: 640_000, sha256: HASH_B },
+      { assetId: "asset-poster", kind: "poster", role: "poster", byteLength: 90_000, sha256: HASH_C },
+      { assetId: "asset-source", kind: "blend-source", role: "source", byteLength: 40_000_000, sha256: HASH_D },
+    ],
+    cameraTrackAssetId: "asset-track",
+    shots: fixtureShots(),
+    lighting: {
+      preset: "clay-studio-v1",
+      ambientIntensity: 0.6,
+      keyIntensity: 2.4,
+      keyPosition: [4, 6, 3],
+    },
+    backgroundColor: "#101014",
+    overrides: [
+      {
+        id: "ov-1",
+        sourceRevisionId: PARENT_REVISION_ID,
+        sourceContentHash: HASH_A,
+        operationVersion: 1,
+        kind: "entity-transform",
+        entityId: "e2",
+        space: "world",
+        position: [1, 0, 0],
+      },
+      {
+        id: "ov-2",
+        sourceRevisionId: PARENT_REVISION_ID,
+        sourceContentHash: HASH_A,
+        operationVersion: 1,
+        kind: "entity-color",
+        entityId: "e2",
+        materialRole: "bodyPaint",
+        color: "#ff2200",
+      },
+      {
+        id: "ov-3",
+        sourceRevisionId: PARENT_REVISION_ID,
+        sourceContentHash: HASH_A,
+        operationVersion: 1,
+        kind: "camera-shot-offset",
+        shotId: "shot-2",
+        positionOffset: [0, 0.1, 0],
+      },
+    ],
+    provenance: {
+      engine: "blender-cloud",
+      engineVersion: "1.4.0",
+      recipeVersion: "1.0.0",
+      compilerVersion: "0.9.2",
+      exporterVersion: "0.9.2",
+      rendererVersion: "3.1.0",
+      sourceRevisionId: PARENT_REVISION_ID,
+      sourceArtifactId: "asset-source",
+      contentHash: "0".repeat(64),
+    },
+    ...overrides,
+  }
+}