@nodaro/shared 2.24.0 → 2.27.0

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 }
+}

package/src/studio-production-wire.ts

@@ -1,344 +0,0 @@
-/**
- * The wire contract of `/v1/studio/productions` — TYPES ONLY.
- *
- * A studio production is a Nodaro workflow whose `settings.studio` holds the
- * shots. Its CODE — the codec that reads and writes that document, the plan
- * format, the catalogs and the reducers — lives in `@nodaro/studio-production`,
- * which is FSL-licensed. What lives here is the ENVELOPE the routes return and
- * the bodies they take, because the SDK is typed against this package and an
- * SDK caller has to know the shape of a reply.
- *
- * The document's own sub-objects (the cast, the looks, the scene plan, the
- * cuts) are therefore named JSON aliases rather than re-declared shapes. That
- * is deliberate on both counts:
- *
- * - **Named**, not one anonymous `unknown`, so a `.d.ts` reader can still see
- *   which field is which and the SDK's surface documents itself.
- * - **Not re-declared**, because a second definition of the document is exactly
- *   the disagreement this contract exists to end — and publishing the studio's
- *   domain types under Apache would be an irrevocable grant of code that was
- *   deliberately placed one tier down.
- *
- * `@nodaro/studio-production` narrows every one of them to its real type and
- * pins the narrowed view against this one at build time, so the two cannot
- * drift apart in silence. A consumer that wants the narrow types depends on
- * that package; a consumer that only reads the wire uses these.
- */
-
-/**
- * How a result is ADDRESSED: its job id when it has one, its url otherwise.
- *
- * Never a position. An index is meaningless the moment another writer inserts
- * a result — and two writers is the normal case here, since an agent and the
- * editor hold the same production open. Uploaded and hand-attached media have
- * no job, which is why the url is the fallback rather than the key.
- */
-export type ResultKey = string
-
-// ── the document's own vocabulary, as JSON ──────────────────────────────────
-// Each alias names the `@nodaro/studio-production` type that defines it.
-
-/** `LookSelectionMap` — cinematic picks by dimension key. */
-export type StudioLookMapJson = Record<string, unknown>
-/** `Cast` — the production's roles, keyed by role slug. */
-export type StudioCastJson = Record<string, unknown>
-/** `CastLookMap` — which view of each actor a scene pins. */
-export type StudioCastLookMapJson = Record<string, unknown>
-/** `ProductionFolder` — a named timeline folder. */
-export type StudioFolderJson = Record<string, unknown>
-/** `StoryboardSettings` — the Storyboard tab's persisted state (`brief` lives here). */
-export type StudioStoryboardJson = Record<string, unknown>
-/** `ProductionMusic` — the rendered soundtrack muxed over the export. */
-export type StudioMusicJson = Record<string, unknown>
-/** `PlanMusic` — the soundtrack PLAN (prompt + pickers), kept beside the track. */
-export type StudioMusicPlanJson = Record<string, unknown>
-/** `ProductionCut` — one exported cut of the film. */
-export type StudioCutJson = Record<string, unknown>
-/** `ScenePlan` — a scene's authored framing / motion / voice, before it renders. */
-export type StudioPlanJson = Record<string, unknown>
-/** `ShotBeat` — one timed motion window inside a scene. */
-export type StudioBeatJson = Record<string, unknown>
-/** `ShotTransition` — how a scene's last frames go out. */
-export type StudioTransitionJson = Record<string, unknown>
-/** `ShotVoice` — the scene's generated voiceover. */
-export type StudioVoiceJson = Record<string, unknown>
-/** `DirectionFields` / `SubjectFields` — platform catalog ids carried on a result. */
-export type StudioIdFieldsJson = Record<string, unknown>
-/** `ConnectedReference` — a bound `@`-entity chip. */
-export type StudioReferenceJson = Record<string, unknown>
-/** `TrashedItem` — one deleted shot, still or clip, restorable by id. */
-export type StudioTrashItemJson = Record<string, unknown>
-
-// ── results ────────────────────────────────────────────────────────────────
-
-/**
- * One generated STILL, with the context that regenerates it.
- *
- * Result histories ACCUMULATE — a generate appends, it never replaces — so a
- * shot's stills are every framing candidate it has ever had, and each one
- * carries what it was made with. That is what makes "go back to the second
- * one" a read rather than a re-run.
- */
-export interface StudioResultView {
-  key: ResultKey
-  url: string
-  jobId?: string
-  name?: string
-  prompt?: string
-  negativePrompt?: string
-  provider?: string
-  referenceImageUrls?: string[]
-  references?: StudioReferenceJson[]
-  aspectRatio?: string
-  resolution?: string
-  /** The look layers this generation was sent with — film, scene, then the shot's own. */
-  filmLook?: StudioLookMapJson
-  sceneLook?: StudioLookMapJson
-  look?: StudioLookMapJson
-  subject?: StudioIdFieldsJson
-}
-
-/**
- * One generated CLIP, with the frames it was animated from.
- *
- * The frames matter more here than they look: selecting a past clip restores
- * the start and end frames THAT clip was made from, which is why they are
- * stored per result rather than read off the shot.
- */
-export interface StudioClipResultView {
-  key: ResultKey
-  url: string
-  jobId?: string
-  name?: string
-  prompt?: string
-  provider?: string
-  negativePrompt?: string
-  duration?: number
-  /** The frames THIS clip was animated from — restored with it, never derived. */
-  startFrameUrl?: string
-  endFrameUrl?: string
-  referenceImageUrls?: string[]
-  references?: StudioReferenceJson[]
-  beats?: StudioBeatJson[]
-  scenePrompt?: string
-  endTransition?: StudioTransitionJson
-  filmLook?: StudioLookMapJson
-  sceneLook?: StudioLookMapJson
-  look?: StudioLookMapJson
-  subject?: StudioIdFieldsJson
-}
-
-/**
- * A framing batch that is STILL RUNNING, with everything needed to land it.
- *
- * A marker rather than a promise: any client — or none — can finish the job,
- * because the context that turns a finished job into a result is written down
- * on the production instead of living in the browser tab that started it.
- */
-export interface PendingStillView {
-  jobId: string
-  batchId?: string
-  provider?: string
-  prompt?: string
-  count?: number
-  startedAt?: string
-}
-
-/** An animate that is still running. The clip mirror of {@link PendingStillView}. */
-export interface PendingClipView {
-  jobId: string
-  provider?: string
-  prompt?: string
-  startedAt?: string
-}
-
-// ── the shot ───────────────────────────────────────────────────────────────
-
-/** A shot's framed STILL: the active frame, and (at `detail: "full"`) its history. */
-export interface StudioStillView {
-  nodeId: string
-  provider: string
-  prompt: string
-  active: ResultKey | null
-  activeUrl: string
-  count: number
-  /** Cinematic direction as PLATFORM catalog ids — never baked hint text. */
-  direction?: StudioIdFieldsJson
-  subject?: StudioIdFieldsJson
-  /** Present only at `detail: "full"` — a list read returns counts, not histories. */
-  results?: StudioResultView[]
-  pending: PendingStillView[]
-}
-
-/** A shot's animated CLIP. Independent of the still: deleting one never touches the other. */
-export interface StudioClipView {
-  nodeId: string
-  provider: string
-  prompt: string
-  duration?: number
-  active: ResultKey | null
-  activeUrl: string
-  count: number
-  direction?: StudioIdFieldsJson
-  /** The voice this clip was revoiced into, when it was. */
-  revoicedVoiceId?: string
-  revoicedVoiceName?: string
-  /** Present only at `detail: "full"`. */
-  results?: StudioClipResultView[]
-  pending: PendingClipView[]
-}
-
-/** One shot, in timeline order. */
-export interface StudioShotView {
-  id: string
-  index: number
-  name?: string
-  folderId?: string
-  still?: StudioStillView
-  clip?: StudioClipView
-  /** Explicit and sticky: selecting a still never moves them. */
-  startFrame?: string
-  endFrame?: string
-  directingReferences?: {
-    images?: string[]
-    videos?: string[]
-    audio?: string[]
-  }
-  plan?: StudioPlanJson
-  scenePrompt?: string
-  beats?: StudioBeatJson[]
-  endTransition?: StudioTransitionJson
-  look?: StudioLookMapJson
-  castLook?: StudioCastLookMapJson
-  voice?: StudioVoiceJson
-}
-
-// ── the production ─────────────────────────────────────────────────────────
-
-/** What is in flight, at a glance — the reason a `get` can reconcile before it reads. */
-export interface StudioPendingView {
-  stills: number
-  clips: number
-  music: boolean
-  draft: { jobId: string; mode: "replace" | "append" } | null
-}
-
-/** The bin: a count always, the items only at `detail: "full"`. */
-export interface StudioTrashView {
-  count: number
-  items?: StudioTrashItemJson[]
-}
-
-/** The read shape of every `/v1/studio/productions` route and every studio MCP tool. */
-export interface StudioProductionView {
-  id: string
-  name: string
-  version: number
-  updatedAt: string
-  thumbnailUrl: string | null
-  shared: boolean
-  archived: boolean
-  film?: StudioLookMapJson
-  cast?: StudioCastJson
-  folders: StudioFolderJson[]
-  storyboard?: StudioStoryboardJson
-  music?: StudioMusicJson
-  musicPlan?: StudioMusicPlanJson
-  cuts: StudioCutJson[]
-  trash: StudioTrashView
-  pending: StudioPendingView
-  /** In timeline order. */
-  shots: StudioShotView[]
-}
-
-/** A dashboard row — what a list returns, with no shot bodies at all. */
-export interface StudioProductionSummary {
-  id: string
-  name: string
-  version: number
-  updatedAt: string
-  thumbnailUrl: string | null
-  shared: boolean
-  archived: boolean
-  shotCount: number
-}
-
-// ── request / response bodies ───────────────────────────────────────────────
-// Phase 0's five routes. The operation, generation and lifecycle bodies land
-// with the routes that take them, so this file never describes a route the
-// platform does not serve.
-
-/** `GET …/skill` — the authoring skill, rendered from the package at request time. */
-export interface StudioSkillResponse {
-  /** SKILL.md — the authoring guide. */
-  skill: string
-  /** references/catalog.md — every picker, model and enum, in full. */
-  catalog: string
-  /** schema.json — the strict JSON Schema a plan is validated against. */
-  schema: Record<string, unknown>
-  /** The operating guide: the tool map, the loops, the rules. */
-  operating: string
-  /** The catalog versions the three were rendered from. */
-  generatedFrom: { prompts: string; shared: string }
-}
-
-/** One thing wrong with a plan, addressed at the field that is wrong. */
-export interface StudioPlanIssue {
-  path: string
-  message: string
-  hint?: string
-}
-
-/** `POST …/validate` — free, persists nothing, and resolves against the caller's library. */
-export interface StudioValidatePlanRequest {
-  plan: Record<string, unknown>
-}
-
-export interface StudioValidatePlanResponse {
-  valid: boolean
-  errors: StudioPlanIssue[]
-  warnings: StudioPlanIssue[]
-  summary?: {
-    name?: string
-    scenes: number
-    shots: number
-    cast: number
-    /** Cast entries that matched a row in the caller's library. */
-    bound: number
-  }
-}
-
-/** `GET …?limit&cursor` — the caller's "Studio" project, archived and hidden filtered. */
-export interface StudioListProductionsResponse {
-  data: StudioProductionSummary[]
-  nextCursor?: string
-}
-
-/** `POST …` — a new production, optionally landed from a plan in the same call. */
-export interface StudioCreateProductionRequest {
-  name?: string
-  plan?: Record<string, unknown>
-}
-
-/** `POST …/:id/import` — add a plan's scenes to a production that already exists. */
-export interface StudioImportPlanRequest {
-  plan: Record<string, unknown>
-  mode?: "append"
-}
-
-/** What an import did, in the words a receipt would use. */
-export interface StudioImportSummary {
-  shotsAdded: number
-  castEnrolled: number
-  /** Cast entries that resolved to a row in the caller's library. */
-  castBound: number
-}
-
-export interface StudioProductionResponse {
-  production: StudioProductionView
-  warnings?: StudioPlanIssue[]
-  summary?: StudioImportSummary
-}
-
-/** How much of a production a read returns. */
-export type StudioProductionDetail = "summary" | "full"