@nodaro/shared 2.22.0 → 2.24.0

package/src/studio-production-wire.ts

@@ -0,0 +1,344 @@
+/**
+ * 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"

package/src/types.ts

@@ -214,6 +214,49 @@ export interface ConnectedReference {
    * The single new structured-shape field for external (API/MCP/SDK) parity.
    */
   readonly identityLock?: { enabled: boolean; text?: string }
+  /**
+   * PER-USE identity description for this reference — what the caller wants the
+   * model told about this subject THIS TIME, overriding whatever the entity's
+   * library record says. Wherever a reference's identity description already
+   * renders (the legacy identity bullet's `— <desc>` part, a `{image:N:label}`
+   * directive's descriptor) it WINS over `characterCanonicalDescription` /
+   * `locationCanonicalDescription` / `description`; where the HYBRID format
+   * renders no description at all, it adds one trailing `<binding> — <override>.`
+   * line instead.
+   *
+   * The two formats are deliberately ASYMMETRIC where a reference renders no
+   * directive at all — a plain upload (`manual` / `wired-image`, non-extra) that
+   * is neither `@`-mentioned nor `{image:N}`-covered: the LEGACY format stays
+   * silent, and the override is not surfaced there (a bullet would force a
+   * fidelity verb onto an opaque image); the HYBRID format — the production
+   * default — adds the trailing line above for it.
+   *
+   * DISTINCT from `description`, which stays the reference's own label slot (the
+   * free text an extra-ref row / an upstream node carries) — a caller that edits
+   * the wording for ONE use writes it here, so the label is untouched and
+   * dropping the override falls back to the library wording. Absent →
+   * byte-identical to a caller that never sent it.
+   */
+  readonly descriptionOverride?: string
+}
+
+/**
+ * A reference the caller can NAME and DESCRIBE but has no media for — a cast
+ * role no entity has been bound to yet, an analysis slot, a character the author
+ * has only written down. It carries no `url`, so it attaches no reference image
+ * and claims no `@image_N` seat; it reaches the model purely as prose
+ * (`<Name> — <description>.`), rendered in ONE place per lane by
+ * `@nodaro/prompts`' `renderDescribedReferenceLines`.
+ *
+ * Correlation with the prompt body is BY NAME: the caller leaves the name in the
+ * prose (never an indexed `@slug:N` mention — that grammar is url-gated) and the
+ * described line tells the model who that name is.
+ */
+export interface DescribedReference {
+  /** Display name exactly as it appears in the prompt prose (e.g. "Natalie"). */
+  readonly name: string
+  /** What the model should picture when it reads that name. */
+  readonly description: string
 }
 
 /** Default label per source — used by `@` autocomplete and inventory fallback. */

package/src/video-analysis-pricing.ts

@@ -105,39 +105,46 @@ export const VIDEO_ANALYSIS_WINDOW = { LEN: WINDOW_LEN, STRIDE: WINDOW_STRIDE, O
 // analysis rows and 6 of 8 audit rows tick up by 1–5 credits (~0.1–0.6%); unlike
 // the 8_482 → 8_706 round, the legacy `gemini-3-flash` family moves too.
 // Output of the plugin's `scripts/gen-va-buckets.mjs`, pasted verbatim.
+//
+// REGENERATED 2026-09-06 — the zoom-through doctrine round (cloud-plugins
+// 0.221.0 → 0.221.7): the analyser's system prompt grew across the day's
+// releases, moving the plugin's system-prompt token pin 9_082 → 9_434. 17 of
+// 20 analysis rows and 6 of 8 audit rows tick up by 1–5 credits (~0.1–0.5%);
+// the legacy `gemini-3-flash` family moves too.
+// Output of the plugin's `scripts/gen-va-buckets.mjs`, pasted verbatim.
 export const VIDEO_ANALYSIS_BUCKET_CREDITS: Record<string, number> = {
   // Legacy fast-tier model (pre-2026-07) — kept for stored raw-id configs.
   "video-analysis:gemini-3-flash:60s": 181,
-  "video-analysis:gemini-3-flash:180s": 185,
-  "video-analysis:gemini-3-flash:360s": 515,
-  "video-analysis:gemini-3-flash:600s": 848,
+  "video-analysis:gemini-3-flash:180s": 186,
+  "video-analysis:gemini-3-flash:360s": 516,
+  "video-analysis:gemini-3-flash:600s": 849,
   // Current fast tier — regenerated from the private formula for its backing
   // model; higher than the legacy fast schedule but still ≤ pro per bucket.
-  "video-analysis:gemini-3.6-flash:60s": 204,
+  "video-analysis:gemini-3.6-flash:60s": 205,
   "video-analysis:gemini-3.6-flash:180s": 219,
-  "video-analysis:gemini-3.6-flash:360s": 602,
-  "video-analysis:gemini-3.6-flash:600s": 992,
-  "video-analysis:gemini-3.1-pro:60s": 216,
-  "video-analysis:gemini-3.1-pro:180s": 232,
-  "video-analysis:gemini-3.1-pro:360s": 640,
-  "video-analysis:gemini-3.1-pro:600s": 1056,
+  "video-analysis:gemini-3.6-flash:360s": 603,
+  "video-analysis:gemini-3.6-flash:600s": 995,
+  "video-analysis:gemini-3.1-pro:60s": 217,
+  "video-analysis:gemini-3.1-pro:180s": 233,
+  "video-analysis:gemini-3.1-pro:360s": 642,
+  "video-analysis:gemini-3.1-pro:600s": 1059,
   // Mixed tiers (`mixed` + `mixed-fast`) share ONE credit family — they are
   // variants of the same engine plan (plan internals live in the private
   // analysis plugin). Admin-tunable via model_pricing like every other row.
   "video-analysis:mixed:60s": 270,
-  "video-analysis:mixed:180s": 291,
-  "video-analysis:mixed:360s": 729,
-  "video-analysis:mixed:600s": 1177,
+  "video-analysis:mixed:180s": 292,
+  "video-analysis:mixed:360s": 731,
+  "video-analysis:mixed:600s": 1181,
   // SMART — the accuracy tier, and since the 2026-08-03 re-plan a multi-roll
   // plan like the others, always refined (`selectionMode` does not apply
   // here — smart always refines; it never offers a cheaper "choose" path).
   // Priced above the economy tiers because it genuinely costs more to run;
   // the only tier whose accuracy is validated against a hand-counted edit
   // list, re-validated at the current plan before this schedule shipped.
-  "video-analysis:smart:60s": 413,
-  "video-analysis:smart:180s": 503,
-  "video-analysis:smart:360s": 1267,
-  "video-analysis:smart:600s": 2076,
+  "video-analysis:smart:60s": 414,
+  "video-analysis:smart:180s": 504,
+  "video-analysis:smart:360s": 1270,
+  "video-analysis:smart:600s": 2081,
 }
 
 /**
@@ -208,13 +215,13 @@ export function videoAnalysisNumWindows(bucketSec: number): number {
  */
 export const VIDEO_AUDIT_BUCKET_CREDITS: Record<string, number> = {
   "video-audit:60s": 215,
-  "video-audit:180s": 290,
-  "video-audit:360s": 663,
-  "video-audit:600s": 1073,
+  "video-audit:180s": 291,
+  "video-audit:360s": 664,
+  "video-audit:600s": 1075,
   "video-audit:auto:60s": 396,
-  "video-audit:auto:180s": 475,
-  "video-audit:auto:360s": 1178,
-  "video-audit:auto:600s": 1921,
+  "video-audit:auto:180s": 477,
+  "video-audit:auto:360s": 1180,
+  "video-audit:auto:600s": 1924,
 }
 
 /**