@hugpy/video-intelligence-ui 0.1.0

package/src/video/sessionForm.ts

@@ -0,0 +1,189 @@
+// SESSION-SCOPED FORM MEMORY — "my inputs are still there when I come back".
+//
+// ── THE BUG THIS FIXES (operator ask 2026-08-06) ────────────────────────────
+// Switching sub-tabs inside the STUDIO tab (Scene / Movie / Clip / Cinema) and
+// switching workbench tabs (Studio ↔ Identities ↔ Frames …) both UNMOUNT the
+// surface you were typing into: WorkbenchStation renders exactly one station
+// body, and GenerateStation swaps the SectionTabs layout for StudioGenerateMode
+// (and StudioGenerateSurface swaps its clip surface for StudioMovieComposer).
+// Plain useState dies with the unmount, so a half-written prompt, a chosen
+// model, a staged reference set — all gone for the price of a glance at another
+// tab.
+//
+// ── WHY A STORE AND NOT KEEP-MOUNTED-BUT-HIDDEN ─────────────────────────────
+// Rendering the inactive sub-tabs behind `hidden` would fix the SUB-tab half and
+// nothing else — a main-tab switch unmounts the whole station regardless, and
+// keeping every station mounted is not on the table. It would also double-mount
+// the pieces that register into the shared sidebar (StudioPlane's
+// registerSettings + its knob PORTAL both land in the ONE settingsHost node) and
+// double the studio clip poll. So state is LIFTED out of the component lifetime
+// instead — which is exactly the idiom this arm already uses for everything else
+// that has to outlive a mount: mediaLibrary.ts and jobTracker.ts are both
+// module-level stores persisted to sessionStorage under the session id.
+//
+// ── SHAPE ───────────────────────────────────────────────────────────────────
+// A per-tab key/value store, session-id-scoped like mediaLibrary (so two tabs
+// keep independent inputs and a new session starts clean), with a useState-shaped
+// hook so a call site converts by swapping one word:
+//
+//     const [prompt, setPrompt] = useState("");
+//     const [prompt, setPrompt] = useSessionState("studio.clip.prompt", "");
+//
+// In-memory is authoritative (synchronous, no JSON round-trip per keystroke);
+// sessionStorage is a debounced mirror so a reload also keeps the inputs. If
+// storage is unavailable (private mode, quota) the memory half still works — the
+// feature degrades to "survives unmounts but not reloads", never to an error.
+//
+// ── WHAT BELONGS HERE, AND WHAT DOES NOT ────────────────────────────────────
+// USER-AUTHORED INPUT only: prompts, knobs, picked models/presets, attached
+// refs, which sub-tab you were on. NOT transient UI (open pickers, previews),
+// NOT in-flight job/upload state, NOT anything unserializable (a Set/Map never
+// survives JSON — leave those on useState). Restoring a stale "uploading…" or a
+// half-open picker would be a worse bug than the one being fixed.
+//
+// Keys are global: two components sharing a key share the VALUE but not the
+// React subscription (each holds its own useState), so only ever use one key per
+// logical field, and never for two surfaces that are mounted at the same time.
+import { useCallback, useRef, useState, type Dispatch, type SetStateAction } from "react";
+import { getSessionId } from "../session";
+import { isCanned } from "../demo/mode";
+
+const KEY_PREFIX = "vi.formMemory.v1";
+const FLUSH_MS = 300;
+
+// Session-scoped key so two tabs (two sessions) keep independent inputs, with the
+// same `:demo`-suffix hermeticism mediaLibrary/jobTracker use so the canned
+// brochure never reads or writes the live session's values.
+function storageKey(): string {
+  const suffix = isCanned() ? ":demo" : "";
+  try {
+    return `${KEY_PREFIX}:${getSessionId()}${suffix}`;
+  } catch {
+    return `${KEY_PREFIX}${suffix}`;
+  }
+}
+
+function hydrate(): Map<string, unknown> {
+  try {
+    const raw = sessionStorage.getItem(storageKey());
+    if (!raw) return new Map();
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return new Map();
+    return new Map(Object.entries(parsed as Record<string, unknown>));
+  } catch {
+    return new Map(); // storage unavailable or corrupt — start empty, quietly
+  }
+}
+
+// Hydrated ONCE at module load: every read after that is a Map lookup, so a
+// keystroke never pays a JSON.parse.
+const memory: Map<string, unknown> = hydrate();
+
+let flushTimer: number | null = null;
+
+function flush(): void {
+  flushTimer = null;
+  try {
+    sessionStorage.setItem(
+      storageKey(),
+      JSON.stringify(Object.fromEntries(memory)),
+    );
+  } catch {
+    /* quota/private mode — the in-memory half still carries this session */
+  }
+}
+
+function scheduleFlush(): void {
+  if (typeof window === "undefined") return;
+  if (flushTimer != null) return;
+  flushTimer = window.setTimeout(flush, FLUSH_MS);
+}
+
+function readValue<T>(key: string, fallback: T): T {
+  return memory.has(key) ? (memory.get(key) as T) : fallback;
+}
+
+function writeValue(key: string, value: unknown): void {
+  memory.set(key, value);
+  scheduleFlush();
+}
+
+/**
+ * useState, but the value outlives the component's mount for the whole browser
+ * session (and a reload). Drop-in: same tuple, same updater-function support.
+ *
+ * `initial` is used only the FIRST time a key is seen this session; afterwards
+ * the stored value wins, which is the entire point (a remount must not re-run
+ * the default over what the operator typed).
+ */
+export function useSessionState<T>(
+  key: string,
+  initial: T | (() => T),
+): [T, Dispatch<SetStateAction<T>>] {
+  const [value, setValue] = useState<T>(() => {
+    if (memory.has(key)) return memory.get(key) as T;
+    const seed = typeof initial === "function" ? (initial as () => T)() : initial;
+    writeValue(key, seed);
+    return seed;
+  });
+
+  const set = useCallback<Dispatch<SetStateAction<T>>>(
+    (action) => {
+      setValue((prev) => {
+        const next =
+          typeof action === "function" ? (action as (p: T) => T)(prev) : action;
+        // Writing from inside the updater keeps the store in step with the
+        // functional-update form (setX(cur => …) is used all over these
+        // surfaces). React may invoke an updater twice under StrictMode; the
+        // write is idempotent for the same `prev`, so that is harmless.
+        writeValue(key, next);
+        return next;
+      });
+    },
+    [key],
+  );
+
+  return [value, set];
+}
+
+/**
+ * The next value of a session-persisted counter — for the module-level `let seq
+ * = 0` row-key generators (`goal_3`, `ref_2`) that back rows now restored from
+ * storage.
+ *
+ * Those counters reset to 0 on a page reload while the ROWS they keyed come back
+ * from sessionStorage, so a freshly minted key could collide with a restored one
+ * (React would then reconcile two different rows as the same element, and in the
+ * movie composer the key doubles as the wire `segment_id`). Persisting the
+ * counter is the smallest fix that keeps the existing key SHAPE intact.
+ */
+export function nextSessionSeq(key: string): number {
+  const next = (readValue<number>(key, 0) ?? 0) + 1;
+  writeValue(key, next);
+  return next;
+}
+
+/**
+ * A ref whose `.current` lives in the same session store — for the flags that
+ * deliberately are NOT state because they must never cause a render (the
+ * "operator has touched this field" marks that gate the studio's geometry/budget
+ * autofill effects).
+ *
+ * These have to persist alongside the values they guard: restore a hand-typed
+ * width but not the "the operator typed it" mark, and the autofill effect fires
+ * on the next mount and clobbers exactly the value we just restored.
+ */
+export function useSessionRef<T>(key: string, initial: T): { current: T } {
+  const holder = useRef<{ current: T } | null>(null);
+  if (holder.current === null) {
+    if (!memory.has(key)) writeValue(key, initial);
+    const obj = {} as { current: T };
+    Object.defineProperty(obj, "current", {
+      get: () => readValue<T>(key, initial),
+      set: (v: T) => writeValue(key, v),
+      enumerable: true,
+    });
+    holder.current = obj;
+  }
+  return holder.current;
+}

package/src/video/spreadAssist.ts

@@ -0,0 +1,392 @@
+// STUDIO SPREAD — the pure half (STUDIO-SPREAD-SPEC §2).
+//
+// Everything here is a FUNCTION OF ITS INPUTS: wire shapes, request builders,
+// tolerant response readers and the intent→action mapping. No React, no fetch, no
+// component state. The transport lives in usePromptAssist (one in-flight assist,
+// one error model); the composer keeps only its editor state. Splitting it this way
+// keeps StudioMovieComposer from growing a second brain, and makes the two things
+// most likely to be wrong — the wire shape and the intent routing table — readable
+// in one screen.
+//
+// THE ONE RULE THAT SHAPES ALL OF IT (spec §1a/§1d): a classification is a
+// LABEL, never an action, and a spread reply may only touch rows the user
+// SELECTED. Every reader below is written so a malformed/partial/over-eager reply
+// degrades to "change nothing and say so" rather than to "overwrite the movie".
+
+/** How a segment is spliced onto the one before it — mirrors studio_movie_schema. */
+export type SpreadJointMode = "still" | "vace_extend" | "cut";
+
+/**
+ * One typed segment reference (spec §1c). Field names mirror
+ * `studio_movie_schema.StudioMovieGoal` EXACTLY so a row goes over the wire with no
+ * translation layer to get wrong. Every field bar `segment_id` is optional; the
+ * backend validates and renders them into the model preface as plain sentences.
+ */
+export interface SegmentRefWire {
+  segment_id: string;
+  prompt?: string;
+  negative?: string;
+  /** The user's INSTRUCTION for this row, when the router said "direction". */
+  direction?: string;
+  joint_mode?: SpreadJointMode;
+  branch_frame?: number;
+  seed?: number;
+  index?: number;
+}
+
+/** The locked identity block (§1e). `name` is required by the backend validator. */
+export interface IdentityContextWire {
+  identity_id?: string;
+  name: string;
+  reference_asset_ids?: string[];
+  locked_description?: string;
+  do_not_invent?: string[];
+}
+
+/** The typed `context` object shared by detail/generate/negative/spread. */
+export interface AssistContextWire {
+  kind?: "image" | "scene" | "movie";
+  /** FREE-FORM user text only — structured row state rides the typed fields (§1c). */
+  hint?: string;
+  segment?: SegmentRefWire;
+  previous_segment?: SegmentRefWire;
+  next_segment?: SegmentRefWire;
+  identity_profile?: IdentityContextWire;
+}
+
+/** The `mode:"spread"` request body (§1a), minus `model` (the hook adds that). */
+export interface SpreadRequestWire {
+  mode: "spread";
+  movie_query?: string;
+  style_bible?: Record<string, string>;
+  fixed_segments: SegmentRefWire[];
+  target_segments: SegmentRefWire[];
+  global_negative?: string[];
+  steering_seed?: number;
+  context?: AssistContextWire;
+}
+
+/** One replacement row the generator wrote. Only TARGET ids ever appear here. */
+export interface SpreadSegmentResult {
+  segment_id: string;
+  operation: string;
+  prompt: string;
+  negative: string;
+  continuity_note: string;
+  directions_used: unknown[];
+  warnings: string[];
+}
+
+/** The parsed 200 body of a spread call. */
+export interface SpreadResult {
+  segments: SpreadSegmentResult[];
+  missing_segments: string[];
+  warnings: string[];
+  invented_identity_attributes: string[];
+  /** The shared steering set + its seed — echoed so a liked spread can be re-pinned. */
+  steering: Record<string, unknown>;
+  steering_seed: number | null;
+  model: string | null;
+  model_requested: string | null;
+  model_resolved: string | null;
+}
+
+// ── intent routing (§1d) ────────────────────────────────────────────────────
+/** What the 3B router can say. `ambiguous` is also the degraded/failure value. */
+export type IntentName = "empty" | "direction" | "scene_prompt" | "ambiguous";
+
+/** The parsed /video/prompt/intent 200 body. This route ALWAYS returns 200. */
+export interface IntentResult {
+  intent: IntentName;
+  operation: string | null;
+  confidence: number;
+  cached: boolean;
+  degraded: boolean;
+}
+
+/** The per-field tri-state control: Auto · Direction · Scene prompt. */
+export type PromptFieldMode = "auto" | "direction" | "scene_prompt";
+
+/** The resolved action for a prompt field — null means "uncertain, show both". */
+export type PromptOperation = "generate" | "enhance_scene" | "generate_from_direction";
+
+/**
+ * Resolve which action a row's primary button should invoke.
+ *
+ * Routing order is the spec's (§1d), in order: blank field → generate; an EXPLICIT
+ * user mode → obey it (the router is never consulted); else the router's answer;
+ * else — including `ambiguous`, a degraded router, or "not classified yet" — null,
+ * which the UI renders as "Uncertain → choose an action" with BOTH buttons live.
+ */
+export function resolveOperation(
+  mode: PromptFieldMode,
+  intent: IntentResult | null,
+  promptIsBlank: boolean,
+): PromptOperation | null {
+  if (promptIsBlank) return "generate";
+  if (mode === "direction") return "generate_from_direction";
+  if (mode === "scene_prompt") return "enhance_scene";
+  if (!intent) return null;                       // not classified yet — no guess
+  if (intent.intent === "empty") return "generate";
+  if (intent.intent === "direction") return "generate_from_direction";
+  if (intent.intent === "scene_prompt") return "enhance_scene";
+  return null;                                    // ambiguous / degraded
+}
+
+/** Which /video/prompt/assist mode an operation invokes. */
+export function assistModeFor(op: PromptOperation): "detail" | "generate" {
+  return op === "enhance_scene" ? "detail" : "generate";
+}
+
+/** The button label for an operation (the detected verb the spec names). */
+export function operationLabel(op: PromptOperation): string {
+  if (op === "enhance_scene") return "Enhance prompt";
+  if (op === "generate_from_direction") return "Generate from direction";
+  return "Generate prompt";
+}
+
+/**
+ * The honest one-line readout under a field in AUTO mode. Returns "" when there is
+ * nothing to say yet (blank field, or no classification has been asked for).
+ */
+export function detectionText(
+  intent: IntentResult | null,
+  op: PromptOperation | null,
+): string {
+  if (!intent) return "";
+  if (intent.intent === "empty") return "Empty → Generate prompt";
+  if (op == null) {
+    return intent.degraded
+      ? "Router unavailable → choose an action"
+      : "Uncertain → choose an action";
+  }
+  const what = intent.intent === "direction" ? "Direction" : "Scene prompt";
+  return `Detected: ${what} → ${operationLabel(op)}`;
+}
+
+// ── request builders ────────────────────────────────────────────────────────
+/** Drop blank strings / undefined so the wire carries only what the user actually set. */
+function put<T extends object>(obj: T, key: keyof T & string, value: unknown): void {
+  if (value === undefined || value === null) return;
+  if (typeof value === "string" && value.trim() === "") return;
+  (obj as Record<string, unknown>)[key] = typeof value === "string" ? value.trim() : value;
+}
+
+/** A composer goal row, in the shape this module needs (host-agnostic). */
+export interface SpreadGoalInput {
+  /** Stable per-row id — the composer's React key doubles as the segment_id. */
+  key: string;
+  prompt: string;
+  negative: string;
+  seed: string;
+  branchFrame: string;
+  joint: SpreadJointMode;
+  /** Timeline position (0 = the root segment). */
+  index: number;
+  /** Set when the row's resolved operation is "generate from direction". */
+  isDirection?: boolean;
+}
+
+/** Parse a blank-means-unset numeric editor string into an int, or undefined. */
+function intOrUndef(raw: string): number | undefined {
+  const s = raw.trim();
+  if (s === "") return undefined;
+  const n = Number(s);
+  if (!Number.isInteger(n) || n < 0) return undefined;
+  return n;
+}
+
+/**
+ * One goal row → one typed segment reference.
+ *
+ * `branch_frame` is dropped for a `cut` (a cut carries no frame, and the backend
+ * would render a sentence about a frame that does not exist). A row classified as a
+ * DIRECTION sends its text under BOTH `prompt` (what is in the box now) and
+ * `direction` (the instruction to act on) — the preface renders them distinctly.
+ */
+export function segmentRef(goal: SpreadGoalInput): SegmentRefWire {
+  const ref: SegmentRefWire = { segment_id: goal.key };
+  put(ref, "prompt", goal.prompt);
+  put(ref, "negative", goal.negative);
+  if (goal.isDirection) put(ref, "direction", goal.prompt);
+  if (goal.index > 0) {
+    ref.joint_mode = goal.joint;
+    if (goal.joint !== "cut") {
+      const bf = intOrUndef(goal.branchFrame);
+      if (bf !== undefined) ref.branch_frame = bf;
+    }
+  }
+  const seed = intOrUndef(goal.seed);
+  if (seed !== undefined) ref.seed = seed;
+  ref.index = goal.index;
+  return ref;
+}
+
+export interface BuildSpreadOptions {
+  goals: SpreadGoalInput[];
+  /** Row keys the user SELECTED — these and only these may be rewritten. */
+  selectedKeys: ReadonlySet<string>;
+  /** The overall request ("a chase through a night market"). Optional. */
+  movieQuery: string;
+  /** The movie-wide negative, split into exclusion terms. */
+  globalNegative: string;
+  /** Pin a previous spread's world by reusing its steering seed. */
+  steeringSeed?: number | null;
+  context?: AssistContextWire;
+  styleBible?: Record<string, string>;
+}
+
+/**
+ * Build the ONE spread call (§1a): selected rows are `target_segments`, every other
+ * row rides as a LOCKED `fixed_segment` so the generator can see the whole timeline
+ * and write into it coherently. Returns null when nothing is selected — the caller
+ * must not fire a call the backend would 400 for being empty.
+ */
+export function buildSpreadBody(opts: BuildSpreadOptions): SpreadRequestWire | null {
+  const targets = opts.goals.filter((g) => opts.selectedKeys.has(g.key));
+  if (targets.length === 0) return null;
+  const fixed = opts.goals.filter((g) => !opts.selectedKeys.has(g.key));
+  const body: SpreadRequestWire = {
+    mode: "spread",
+    fixed_segments: fixed.map(segmentRef),
+    target_segments: targets.map(segmentRef),
+  };
+  put(body, "movie_query", opts.movieQuery);
+  const negatives = opts.globalNegative
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s !== "");
+  if (negatives.length) body.global_negative = negatives;
+  if (opts.steeringSeed != null && Number.isInteger(opts.steeringSeed)) {
+    body.steering_seed = opts.steeringSeed;
+  }
+  if (opts.styleBible && Object.keys(opts.styleBible).length) {
+    body.style_bible = opts.styleBible;
+  }
+  if (opts.context && Object.keys(opts.context).length) body.context = opts.context;
+  return body;
+}
+
+// ── response readers (tolerant; a bad shape changes NOTHING) ────────────────
+function strArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((x): x is string => typeof x === "string") : [];
+}
+
+function str(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * Read a spread 200 body. Returns null if it is not a spread reply at all (the
+ * caller then reports a malformed response rather than applying anything). Rows
+ * without a usable `segment_id` + `prompt` are DROPPED, never defaulted.
+ */
+export function readSpreadResult(value: unknown): SpreadResult | null {
+  if (value == null || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (!Array.isArray(v.segments)) return null;
+  const segments: SpreadSegmentResult[] = [];
+  for (const raw of v.segments) {
+    if (raw == null || typeof raw !== "object") continue;
+    const r = raw as Record<string, unknown>;
+    const id = str(r.segment_id).trim();
+    const prompt = str(r.prompt).trim();
+    if (!id || !prompt) continue;
+    segments.push({
+      segment_id: id,
+      operation: str(r.operation) || "generate",
+      prompt,
+      negative: str(r.negative).trim(),
+      continuity_note: str(r.continuity_note).trim(),
+      directions_used: Array.isArray(r.directions_used) ? r.directions_used : [],
+      warnings: strArray(r.warnings),
+    });
+  }
+  const seed = v.steering_seed;
+  return {
+    segments,
+    missing_segments: strArray(v.missing_segments),
+    warnings: strArray(v.warnings),
+    invented_identity_attributes: strArray(v.invented_identity_attributes),
+    steering:
+      v.steering != null && typeof v.steering === "object"
+        ? (v.steering as Record<string, unknown>)
+        : {},
+    steering_seed: typeof seed === "number" && Number.isInteger(seed) ? seed : null,
+    model: typeof v.model === "string" ? v.model : null,
+    model_requested: typeof v.model_requested === "string" ? v.model_requested : null,
+    model_resolved: typeof v.model_resolved === "string" ? v.model_resolved : null,
+  };
+}
+
+/**
+ * Read an intent 200 body. Anything unrecognized reads as a DEGRADED `ambiguous`,
+ * which the UI renders as "choose an action" — the same, safe, both-buttons state
+ * a real router outage produces. There is no failure mode here that arms a button.
+ */
+export function readIntentResult(value: unknown): IntentResult {
+  const degraded: IntentResult = {
+    intent: "ambiguous",
+    operation: null,
+    confidence: 0,
+    cached: false,
+    degraded: true,
+  };
+  if (value == null || typeof value !== "object") return degraded;
+  const v = value as Record<string, unknown>;
+  const name = v.intent;
+  if (name !== "empty" && name !== "direction" && name !== "scene_prompt" && name !== "ambiguous") {
+    return degraded;
+  }
+  return {
+    intent: name,
+    operation: typeof v.operation === "string" ? v.operation : null,
+    confidence: typeof v.confidence === "number" ? v.confidence : 0,
+    cached: v.cached === true,
+    degraded: v.degraded === true,
+  };
+}
+
+/**
+ * The non-destructive notice a spread produces: what changed, what did NOT, and
+ * every warning the backend surfaced. Rendered as a dismissible panel — the spec's
+ * "surface warnings/missing/invented non-destructively", i.e. never as an overwrite
+ * and never swallowed.
+ */
+export function spreadNoticeLines(result: SpreadResult, appliedKeys: string[]): string[] {
+  const lines: string[] = [];
+  lines.push(
+    appliedKeys.length === 1
+      ? "1 segment rewritten."
+      : `${appliedKeys.length} segments rewritten.`,
+  );
+  if (result.missing_segments.length) {
+    lines.push(
+      `The generator did not write ${result.missing_segments.length} selected ` +
+        "row(s) — they are unchanged.",
+    );
+  }
+  if (result.invented_identity_attributes.length) {
+    lines.push(
+      "⚠ Invented identity attributes reported: " +
+        result.invented_identity_attributes.join(", ") +
+        " — check these against your identity profile.",
+    );
+  }
+  for (const w of result.warnings) lines.push(w);
+  for (const s of result.segments) {
+    for (const w of s.warnings) lines.push(`${s.segment_id}: ${w}`);
+  }
+  // PROVENANCE (§1f): say plainly when another model answered.
+  if (
+    result.model_requested &&
+    result.model_resolved &&
+    result.model_requested !== result.model_resolved
+  ) {
+    lines.push(
+      `⚠ Answered by ${result.model_resolved}, not the requested ` +
+        `${result.model_requested}.`,
+    );
+  }
+  return lines;
+}

package/src/video/studioBridge.ts

@@ -0,0 +1,82 @@
+// Tiny seam letting the shell-level session-library sidebar STAGE a source clip
+// into the Studio Clips station's generate form while (or before) it is mounted —
+// the B2 movie->studio chain's "Send to Studio". It mirrors composerBridge exactly
+// but for a DIFFERENT station with a DIFFERENT staging contract: the Generate
+// composer takes ordered text/media PARTS (composerBridge), whereas the studio
+// generate form takes ONE prior-tier VIDEO to extend. Keeping them as two small,
+// self-contained seams (each registered by its own station) is cleaner than
+// overloading composerBridge's StageRequest with a studio mode — the handlers,
+// payloads, and mounting stations share nothing.
+//
+// Single-handler by design: exactly one StudioClipsStation is ever mounted (the
+// /studio-clips route). Because "Send to Studio" fires from the shell sidebar on
+// ANY route — before Studio Clips has mounted — a stage request raised while no
+// handler is registered is BUFFERED and drained the instant the station registers
+// (the sidebar navigates to /studio-clips alongside the call). No deps; never
+// touches server media.
+import type { MediaRef } from "./contract";
+import type { StudioItemProvenance } from "./mediaLibrary";
+
+/**
+ * How the studio should consume the staged clip (slice (a) / v2v):
+ *   • "extend"  — i2v: continue the clip FROM ITS LAST FRAME (the original B2 flow).
+ *   • "restyle" — v2v: repaint/transform the WHOLE clip via the VACE control model.
+ * Capability-aware "Send to Studio": the sidebar can pre-pick a mode, and the
+ * Studio Clips station also lets the user toggle it before generating.
+ */
+export type StudioMode = "extend" | "restyle";
+
+/**
+ * A staged studio request: the prior-tier clip (a movie/scene/studio video ref)
+ * to extend or restyle. The station derives the POST body from it — `source_video`
+ * = the ref's abs-path uri (jail-resolved by the route), falling back to
+ * `source_asset_id` = the ref's asset_id (resolved via the media catalog). Every
+ * field optional + additive so the shape can grow without breaking callers.
+ */
+export interface StudioStageRequest {
+  sourceVideo?: MediaRef;
+  /** Preferred consume mode; the station defaults to "extend" when omitted. */
+  mode?: StudioMode;
+  /** Optional provenance forwarded from the source (e.g. the library item behind a
+   *  "Send to Studio" / "Restyle") so the receiving surface can mint a first-class
+   *  StudioItem carrying it. Purely additive — existing callers that omit it are
+   *  unaffected. */
+  provenance?: StudioItemProvenance;
+}
+
+type StudioStageHandler = (req: StudioStageRequest) => void;
+// A STACK of registered handlers (mount-aware). There are now TWO surfaces that can
+// host the studio generate form — the standalone Studio station's Generate tab and
+// the Generate station's "studio" mode — so a single overwriteable slot could let
+// two mounts fight. The stack makes the seam robust: the MOST-RECENTLY registered
+// mount is the active target, and on unmount its handler is removed (restoring the
+// previous one as active) rather than blindly nulling a slot another mount may own.
+// In practice the two surfaces live on different routes and are never mounted at the
+// same time, but this keeps the contract correct regardless of mount order.
+let handlers: StudioStageHandler[] = [];
+let pending: StudioStageRequest[] = [];
+
+/**
+ * A studio surface registers its stager while mounted. On register we drain any
+ * buffered request (raised from the sidebar before any surface mounted). Returns an
+ * unregister that removes THIS handler (not whatever is currently on top).
+ */
+export function registerStudioStager(fn: StudioStageHandler): () => void {
+  handlers.push(fn);
+  if (pending.length > 0) {
+    const queued = pending;
+    pending = [];
+    for (const req of queued) fn(req);
+  }
+  return () => {
+    handlers = handlers.filter((h) => h !== fn);
+  };
+}
+
+/** Ask the active mounted studio surface to apply `req`. Buffered if none is mounted
+ *  yet (drained by the next surface that registers). */
+export function requestStudioStage(req: StudioStageRequest): void {
+  const active = handlers[handlers.length - 1];
+  if (active) active(req);
+  else pending.push(req);
+}