@nodaro/shared 2.24.0 → 2.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.24.0",
+  "version": "2.26.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__/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,9 @@ 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"
+// --- transient studio keys — the public share read strips them ---
+export {
+  STUDIO_TRANSIENT_KEYS,
+  STUDIO_SHOT_TRANSIENT_KEYS,
+  stripStudioTransientSettings,
+} from "./studio-transient.js"

package/src/studio-transient.ts

@@ -0,0 +1,124 @@
+/**
+ * The parts of `settings.studio` that must not leave the owner's account.
+ *
+ * A shared production is read by anyone with the link. Three things inside the
+ * document are the OWNER'S working state and nobody else's business:
+ *
+ * - `trash` — the recycle bin, which holds every shot, still and clip they
+ *   deleted, with prompts and urls intact. A share viewer receiving the bin is
+ *   the sharpest of the three: it hands out work the owner explicitly threw away.
+ * - the in-flight job markers — `pendingClips` / `pendingStills` per shot, and
+ *   `pendingMusic` / `pendingDraft` on the document. A viewer cannot land any
+ *   of them and does not own them; all they carry across is job ids.
+ * - `freecutDraftUrl` — an unsaved editor draft.
+ *
+ * They do NOT all live at the same level, and that is the whole reason this
+ * file exists rather than one array: the writer puts `trash` and
+ * `freecutDraftUrl` on `settings.studio` itself, and puts the per-shot markers
+ * on the `settings.studio.shots[]` entry. A strip that walked only the top
+ * level would pass its own test and still hand a share viewer every marker in
+ * the production.
+ *
+ * It lives in `@nodaro/shared` because two independent readers need the SAME
+ * list: the public share read (which is the reason the list exists) and the
+ * production writer's own bundle projection. A second copy of a list like this
+ * does not stay equal — it goes one key stale and the stale side is the one
+ * that publishes.
+ *
+ * This is a plain JSON walker on purpose. `settings` is a free-form column that
+ * a client owns end to end; the projection reads the keys it must drop and
+ * nothing else, so it never needs — and must never grow — a dependency on
+ * whatever writes the rest of the document.
+ */
+
+/**
+ * `settings.studio`'s OWN transient keys.
+ *
+ * The per-shot pending lists are on this list as well as the shot one on
+ * purpose: nothing writes them here today, and a stray one from an older
+ * client — or from a client that is not the studio editor at all — still must
+ * not ride out to a viewer.
+ */
+export const STUDIO_TRANSIENT_KEYS = [
+  "trash",
+  "pendingStills",
+  "pendingClips",
+  // The two markers that genuinely DO live at this level: a soundtrack render
+  // and a story-planning run in flight. Same rule as the per-shot pair — they
+  // name jobs on the owner's account and nobody else can land them.
+  "pendingMusic",
+  "pendingDraft",
+  "freecutDraftUrl",
+] as const
+
+/**
+ * ...and a SHOT entry's, which is where the per-shot markers actually are.
+ *
+ * `pendingClip` (singular) is the pre-concurrent-markers shape; the editor's
+ * reader still migrates it on parse, so a row can still be carrying one and it
+ * is still in-flight state.
+ */
+export const STUDIO_SHOT_TRANSIENT_KEYS = ["pendingClips", "pendingClip", "pendingStills"] as const
+
+function withoutKeys(
+  source: Record<string, unknown>,
+  drop: ReadonlyArray<string>,
+): Record<string, unknown> {
+  const kept: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(source)) {
+    if (drop.includes(key)) continue
+    kept[key] = value
+  }
+  return kept
+}
+
+/**
+ * `settings.studio.shots` with every shot's in-flight markers removed.
+ *
+ * Returns the SAME array when no shot carried one, so an idle production's
+ * share read allocates nothing. Anything that is not a shot-shaped object rides
+ * through untouched: this runs on whatever is in the column, and a projection
+ * that threw on an unexpected row would take the share read down with it.
+ */
+function stripShots(value: unknown): unknown {
+  if (!Array.isArray(value)) return value
+  let changed = false
+  const out = value.map((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return entry
+    const shot = entry as Record<string, unknown>
+    if (!STUDIO_SHOT_TRANSIENT_KEYS.some((key) => key in shot)) return entry
+    changed = true
+    return withoutKeys(shot, STUDIO_SHOT_TRANSIENT_KEYS)
+  })
+  return changed ? out : value
+}
+
+/**
+ * A production's `settings` with the owner's working state removed.
+ *
+ * Copy-on-write, and structurally: it rebuilds the objects without those keys
+ * rather than deleting from the caller's, so the stored row is untouched. A
+ * `settings` with no `studio` comes back unchanged — this is a studio concern,
+ * and a workflow that is not a production has nothing here to strip.
+ *
+ * Takes and returns `unknown` because the column is free-form and every caller
+ * already holds it as whatever its own layer calls JSON; narrowing here would
+ * only move the cast one line up.
+ */
+export function stripStudioTransientSettings(settings: unknown): unknown {
+  if (!settings || typeof settings !== "object") return settings
+  const studio = (settings as { studio?: unknown }).studio
+  if (!studio || typeof studio !== "object" || Array.isArray(studio)) return settings
+
+  const source = studio as Record<string, unknown>
+  const kept = withoutKeys(source, STUDIO_TRANSIENT_KEYS)
+  const shots = stripShots(source.shots)
+  if (source.shots !== undefined) kept.shots = shots
+
+  // Nothing to drop at either level — hand back the original object so an
+  // ordinary share read allocates nothing.
+  if (Object.keys(kept).length === Object.keys(source).length && shots === source.shots) {
+    return settings
+  }
+  return { ...(settings as Record<string, unknown>), studio: kept }
+}