@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/agentActivity.ts

@@ -0,0 +1,198 @@
+// WHAT AN MCP AGENT IS DOING, for the "agent working" indicator.
+//
+// A store of its own, like presence: it never enters undo, the save or the
+// document. It is fed by the feed's `agent-activity` signals (renderEvents.ts),
+// which both servers send around every MCP tool call (store mcpActivity.ts).
+//
+// ── WORKING BETWEEN CALLS ───────────────────────────────────────────────────
+//
+// An agent thinks between calls, so an agent whose last call ended is still
+// "working" for `AGENT_GRACE_MS`. A signal is never replayed, so a missed
+// `end` cannot leave a face up for good: a call in flight expires after
+// `AGENT_CALL_MAX_MS`. Wall time is fine here: this is editor chrome, never
+// the stage.
+import { findLayer } from "@dailies-studio/shot/doc";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+
+/** The `agent-activity` payload (store docEvents.ts `AgentActivityPayload`),
+ *  restated: the chrome does not depend on the store package. */
+export interface AgentActivityPayload {
+  v: 1;
+  sessionId: string;
+  client?: string;
+  phase: "start" | "end";
+  tool: string;
+  step: string;
+  project?: string;
+  layers?: string[];
+  file?: string;
+  component?: string;
+  props?: Record<string, unknown>;
+  frame?: number;
+  ok?: boolean;
+}
+
+/** A frame's data as an `AgentActivityPayload`, or null for anything else. */
+export function parseAgentActivity(data: string): AgentActivityPayload | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  if (raw === null || typeof raw !== "object") return null;
+  const o = raw as Record<string, unknown>;
+  if (o["v"] !== 1 || typeof o["sessionId"] !== "string" || typeof o["tool"] !== "string" || typeof o["step"] !== "string") return null;
+  if (o["phase"] !== "start" && o["phase"] !== "end") return null;
+  const text = (k: string): string | undefined => (typeof o[k] === "string" ? (o[k] as string) : undefined);
+  const out: AgentActivityPayload = { v: 1, sessionId: o["sessionId"], phase: o["phase"], tool: o["tool"], step: o["step"] };
+  for (const k of ["client", "project", "file", "component"] as const) {
+    const v = text(k);
+    if (v !== undefined) out[k] = v;
+  }
+  if (Array.isArray(o["layers"])) out.layers = o["layers"].filter((x): x is string => typeof x === "string");
+  if (o["props"] !== null && typeof o["props"] === "object" && !Array.isArray(o["props"])) out.props = o["props"] as Record<string, unknown>;
+  if (typeof o["frame"] === "number" && Number.isFinite(o["frame"])) out.frame = o["frame"];
+  if (typeof o["ok"] === "boolean") out.ok = o["ok"];
+  return out;
+}
+
+/** An agent stays "working" this long after its last call ended. */
+export const AGENT_GRACE_MS = 20_000;
+/** A call with no `end` is dropped after this long. */
+export const AGENT_CALL_MAX_MS = 120_000;
+
+/** One agent, by MCP session: what it is doing now and what it last touched. */
+export interface AgentWork {
+  sessionId: string;
+  /** Its client's name ("Claude"), else "Agent". */
+  name: string;
+  step: string;
+  tool: string;
+  /** A call is in flight. */
+  busy: boolean;
+  project: string | null;
+  layers: readonly string[];
+  file: string | null;
+  component: string | null;
+  /** The source file and component it last wrote, kept while it works: it
+   *  compiles and previews between writes, and is still the file's writer. */
+  wroteFile: string | null;
+  wroteComponent: string | null;
+  /** The last component preview it asked for, until another replaces it. */
+  preview: { component: string; props: Record<string, unknown>; frame: number } | null;
+  /** When it was last heard from (`Date.now()`). */
+  at: number;
+}
+
+export interface AgentActivityState {
+  /** In arrival order. */
+  agents: readonly AgentWork[];
+}
+
+export interface AgentActivityStore {
+  getState(): AgentActivityState;
+  subscribe(listener: () => void): () => void;
+  receive(event: AgentActivityPayload): void;
+}
+
+const EMPTY: AgentActivityState = { agents: [] };
+
+/** Is `work` still working at `now`. */
+export function isWorking(work: AgentWork, now: number): boolean {
+  return now - work.at < (work.busy ? AGENT_CALL_MAX_MS : AGENT_GRACE_MS);
+}
+
+/** Fold one signal into the agents. Pure, for the tests and the store. */
+export function foldActivity(agents: readonly AgentWork[], event: AgentActivityPayload, now: number): AgentWork[] {
+  const seen = agents.find((a) => a.sessionId === event.sessionId);
+  const preview =
+    event.tool === "preview_component" && event.component !== undefined
+      ? { component: event.component, props: event.props ?? {}, frame: event.frame ?? 0 }
+      : (seen?.preview ?? null);
+  const writes = event.tool === "write_source_file" || event.tool === "edit_component_source";
+  const next: AgentWork = {
+    sessionId: event.sessionId,
+    name: event.client ?? seen?.name ?? "Agent",
+    step: event.step,
+    tool: event.tool,
+    busy: event.phase === "start",
+    // A read of the guide names no Project: keep the one it was working in.
+    project: event.project ?? seen?.project ?? null,
+    layers: event.layers ?? (event.phase === "end" ? (seen?.layers ?? []) : []),
+    file: event.file ?? (event.phase === "end" ? (seen?.file ?? null) : null),
+    component: event.component ?? (event.phase === "end" ? (seen?.component ?? null) : null),
+    wroteFile: writes && event.file !== undefined ? event.file : (seen?.wroteFile ?? null),
+    wroteComponent: writes && event.component !== undefined ? event.component : (seen?.wroteComponent ?? null),
+    preview,
+    at: now,
+  };
+  return seen === undefined ? [...agents, next] : agents.map((a) => (a === seen ? next : a));
+}
+
+export function createAgentActivityStore(clock: () => number = () => Date.now()): AgentActivityStore {
+  let state = EMPTY;
+  const listeners = new Set<() => void>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const emit = (): void => {
+    for (const l of listeners) l();
+  };
+  /** Drop the agents that stopped working, and wake for the next one. */
+  const sweep = (): void => {
+    timer = null;
+    const now = clock();
+    const kept = state.agents.filter((a) => isWorking(a, now));
+    if (kept.length !== state.agents.length) {
+      state = { agents: kept };
+      emit();
+    }
+    if (kept.length === 0) return;
+    const due = Math.min(...kept.map((a) => a.at + (a.busy ? AGENT_CALL_MAX_MS : AGENT_GRACE_MS) - now));
+    timer = setTimeout(sweep, Math.max(250, due));
+  };
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    receive(event) {
+      state = { agents: foldActivity(state.agents, event, clock()) };
+      emit();
+      if (timer !== null) clearTimeout(timer);
+      sweep();
+    },
+  };
+}
+
+/** The agents working in Project `name`, newest last. */
+export function agentsIn(state: AgentActivityState, name: string | null): AgentWork[] {
+  return name === null ? [] : state.agents.filter((a) => a.project === name);
+}
+
+/** The agent writing `file` (project-relative) or component `id`, if any. */
+export function agentWriting(state: AgentActivityState, file: string | null, componentId: string | null): AgentWork | null {
+  return (
+    state.agents.find(
+      (a) => (file !== null && a.wroteFile === file) || (componentId !== null && a.wroteComponent === componentId),
+    ) ?? null
+  );
+}
+
+/**
+ * The planned shots an MCP agent is building now, in `boardBuilding`'s shape:
+ * each part whose Shot holds a layer an agent working in this Project named.
+ * A card reads Building for these as it does for this tab's own agent.
+ */
+export function agentBuildingParts(doc: Doc3D | null, state: AgentActivityState, name: string | null): { part: string }[] {
+  if (doc === null) return [];
+  const scenes = new Set<string>();
+  for (const agent of agentsIn(state, name)) {
+    for (const ref of agent.layers) {
+      const found = findLayer(doc, ref);
+      if (found !== null) scenes.add(found.sceneId);
+    }
+  }
+  if (scenes.size === 0) return [];
+  return (doc.storyboard?.parts ?? []).filter((p) => p.scene !== undefined && scenes.has(p.scene)).map((p) => ({ part: p.id }));
+}

package/src/state/agentQuestion.ts

@@ -0,0 +1,239 @@
+// THE AGENT'S QUESTION to the person, for the open Project (store
+// agentQuestions.ts; plans/AGENT-QUESTION-DIALOG-PLAN.md): "The storyboard
+// is ready. Make the video?", asked in the editor by an MCP agent between
+// planning and making.
+//
+// A store of its own, like the comments': never undo, never the save. It reads
+// `GET /api/shots/:name/question` when a Project opens and again on each
+// `agent-question` signal, so a tab opened after the ask still shows it. An
+// open question opens the dialog, whatever workspace is on screen; Escape or
+// "Open storyboard" closes it unanswered, and the status chip opens it again.
+// The dialog shows a question only over its own Project (`projectId`), so a
+// slow or failed read never puts one Project's question over another.
+//
+// An EXPORT QUESTION ("The video is built. Export it?") carries the Export
+// dialog's choices. Its yes keeps them here as `exportAsk` until the export
+// is saved: the Export dialog opens with them, and whatever it saves (to
+// Videos, through the studio server's render, or only to the downloads) is
+// reported back to the question, which wakes the agent's get_answer. Each
+// read keeps it too while the yes has no video, so a reload, another tab or
+// another editor can still export it.
+import * as api from "../api.js";
+import type { AgentQuestion, AgentQuestionExport, AgentQuestionVideo } from "../api.js";
+
+/** An export the person said yes to, until its video is reported. */
+export interface AgentExportAsk {
+  /** The Project's id: only its own Export dialog takes the ask. */
+  projectId: string;
+  questionId: string;
+  export: AgentQuestionExport;
+  /** The studio server's render started for it, reported once it is done. */
+  serverJob?: string;
+}
+
+export interface AgentQuestionState {
+  /** The Project store name the question was read for. */
+  project: string | null;
+  question: AgentQuestion | null;
+  /** The dialog is on screen. */
+  open: boolean;
+  /** An answer is on its way. */
+  sending: boolean;
+  /** Why the last answer was refused, in the server's words. */
+  error: string | null;
+  /** An export question's yes, until its video is reported: this tab's, or
+   *  one a read found. */
+  exportAsk: AgentExportAsk | null;
+}
+
+export interface AgentQuestionStore {
+  getState(): AgentQuestionState;
+  subscribe(listener: () => void): () => void;
+  /** Read the Project's question (on open, and on each signal for it). */
+  load(project: string | null): Promise<void>;
+  /** Show or hide the dialog. Hiding never answers. */
+  show(): void;
+  hide(): void;
+  /** Answer the question on screen, posted to the Project's name now. */
+  answer(project: string, choice: "yes" | "changes", note?: string): Promise<boolean>;
+  /** The studio server's render started for the export ask, or null when
+   *  that render ended without a file (the next export reports instead). */
+  exportOnServer(jobId: string | null): void;
+  /** Report the saved video to `ask`'s question, posted to the Project's
+   *  name now. The ask is spent at once, and kept again (without its server
+   *  render) when the report is refused. Throws the server's refusal. */
+  reportVideo(ask: AgentExportAsk, project: string, video: AgentQuestionVideo): Promise<void>;
+}
+
+const EMPTY: AgentQuestionState = { project: null, question: null, open: false, sending: false, error: null, exportAsk: null };
+
+const isOpen = (q: AgentQuestion | null): q is AgentQuestion => q !== null && q.status === "open";
+
+export function createAgentQuestionStore(): AgentQuestionStore {
+  let state = EMPTY;
+  const listeners = new Set<() => void>();
+  /** The questions the person closed unanswered: a re-read never re-opens
+   *  them. Any other open question opens, a Project reopened later included. */
+  const dismissed = new Set<string>();
+  let generation = 0;
+  /** The answer in flight: only the latest one clears `sending`. */
+  let answering = 0;
+  /** The Project name that answer was posted to, and a re-read of it skipped
+   *  meanwhile, read again once it settles. */
+  let sendingFor: string | null = null;
+  let missed = false;
+  const set = (patch: Partial<AgentQuestionState>): void => {
+    state = { ...state, ...patch };
+    for (const l of listeners) l();
+  };
+  /** A refused answer on screen: the question closed before it landed. It
+   *  stays, saying why, until the person closes it. */
+  const refusalShown = (): boolean => state.open && state.error !== null && state.question !== null && !isOpen(state.question);
+  /** The export ask a read question makes: a yes to an export whose video
+   *  nobody reported, whichever tab or editor said it, so the next export in
+   *  this tab reports it (after a reload too). The ask held for it is kept,
+   *  with its server render. Anything else holds none. */
+  const askOf = (question: AgentQuestion | null): AgentExportAsk | null => {
+    if (question?.export === undefined || question.status !== "answered" || question.answer?.choice !== "yes" || question.answer.video !== undefined) {
+      return null;
+    }
+    if (state.exportAsk?.questionId === question.id) return state.exportAsk;
+    return { projectId: question.projectId, questionId: question.id, export: question.export };
+  };
+  const store: AgentQuestionStore = {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async load(project) {
+      const gen = ++generation;
+      if (project === null) {
+        answering++;
+        sendingFor = null;
+        set({ ...EMPTY });
+        return;
+      }
+      let question: AgentQuestion | null;
+      try {
+        question = await api.getAgentQuestion(project);
+      } catch {
+        // A server without the route, or one mid-restart: the next signal or
+        // Project open asks again.
+        return;
+      }
+      if (gen !== generation) return;
+      // An answer in flight settles the question itself (taken, or refused
+      // with why): a signal racing it must not close the dialog first. It is
+      // read again once the answer lands, so a newer ask still opens.
+      if (sendingFor === project) {
+        missed = true;
+        return;
+      }
+      const wanted = isOpen(question) && !dismissed.has(question.id);
+      const exportAsk = askOf(question);
+      if (refusalShown() && !wanted) {
+        set({ project, exportAsk, ...(question !== null && question.id === state.question?.id ? { question } : {}) });
+        return;
+      }
+      set({
+        project,
+        question,
+        exportAsk,
+        // An open question the person has not closed opens the dialog; a
+        // closed one closes it.
+        open: wanted,
+        error: question !== null && question.id === state.question?.id ? state.error : null,
+      });
+    },
+    show() {
+      if (state.question === null) return;
+      dismissed.delete(state.question.id);
+      set({ open: true });
+    },
+    hide() {
+      const refused = refusalShown();
+      if (state.question !== null) dismissed.add(state.question.id);
+      set({ open: false, error: null });
+      // A refusal kept the screen while signals came in: read what is open now
+      // (a newer ask opens).
+      if (refused && state.project !== null) void store.load(state.project);
+    },
+    async answer(project, choice, note) {
+      const { question } = state;
+      if (!isOpen(question) || state.sending) return false;
+      const mine = ++answering;
+      sendingFor = project;
+      missed = false;
+      set({ sending: true, error: null });
+      // The store may hold another question by the time the answer comes
+      // back: then the result is that one's business, and touches nothing.
+      const current = (): boolean => mine === answering && state.question?.id === question.id;
+      const done = (patch: Partial<AgentQuestionState>): void => {
+        if (mine !== answering) return;
+        sendingFor = null;
+        set({ sending: false, ...(current() ? patch : {}) });
+        if (missed) {
+          missed = false;
+          void store.load(project);
+        }
+      };
+      try {
+        const answered = await api.answerAgentQuestion(project, question.id, note === undefined ? { choice } : { choice, note });
+        done({
+          question: answered,
+          open: false,
+          // An export's yes: the Export dialog opens with its choices, and
+          // reports what it saves.
+          ...(choice === "yes" && answered.export !== undefined
+            ? { exportAsk: { projectId: answered.projectId, questionId: answered.id, export: answered.export } }
+            : {}),
+        });
+        return true;
+      } catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        if (!(e instanceof api.ApiError && e.code === "question_closed")) {
+          // Not taken, or not known: show why, even to one who closed the
+          // dialog while it was sending, and let a re-read say what the
+          // question is now (one recorded after all closes the dialog).
+          if (current()) dismissed.delete(question.id);
+          const reread = current();
+          done({ open: true, error });
+          if (reread) void store.load(project);
+          return false;
+        }
+        // Closed meanwhile: answered in another tab, withdrawn, or replaced.
+        // Kept on screen with who answered, never as sent. The route shows no
+        // withdrawn question, so one it does not show reads as withdrawn here.
+        let now: AgentQuestion | null = null;
+        try {
+          now = await api.getAgentQuestion(project);
+        } catch {
+          // Unknown: withdrawn is the safe reading, it claims no answer.
+        }
+        done({ open: true, error, question: now !== null && now.id === question.id ? now : { ...question, status: "withdrawn" } });
+        return false;
+      }
+    },
+    exportOnServer(jobId) {
+      const ask = state.exportAsk;
+      if (ask === null) return;
+      const { serverJob: _was, ...rest } = ask;
+      set({ exportAsk: jobId === null ? rest : { ...rest, serverJob: jobId } });
+    },
+    async reportVideo(ask, project, video) {
+      if (state.exportAsk === ask) set({ exportAsk: null });
+      try {
+        await api.reportAgentQuestionVideo(project, ask.questionId, video);
+      } catch (e) {
+        // Kept for the next export, unless another ask came meanwhile or the
+        // Project closed. Without its server render: that one was told once,
+        // and a report that failed is never posted again on its own.
+        const { serverJob: _told, ...kept } = ask;
+        if (state.exportAsk === null && state.project !== null) set({ exportAsk: kept });
+        throw e;
+      }
+    },
+  };
+  return store;
+}

package/src/state/bootOpen.ts

@@ -0,0 +1,42 @@
+// The document fetch, started at MODULE EVALUATION instead of after the first
+// commit.
+//
+// `useOpenFromUrl` used to initiate the open inside a post-mount useEffect, so
+// the HTTP GET waterfalled behind module evaluation, createRoot and the first
+// commit — the exact span the `open→frame` markPerf measures. The store exists
+// at module scope in main.tsx, so nothing forces the wait: main.tsx calls
+// `startBootOpen` right after creating the store, and the effect ADOPTS the
+// in-flight promise for its `?def=` / `?shot=` / `?material=` continuations
+// instead of initiating a second fetch.
+//
+// The adoption is guarded on the STORE IDENTITY and the document name, because
+// tests (and any future second mount) create their own stores: a promise
+// started against one store must never satisfy another's open. A miss simply
+// falls back to initiating, which is the old behavior exactly.
+import type { ShotEditorStore } from "./store.js";
+
+let started: { store: ShotEditorStore; wanted: string; promise: Promise<void> } | null = null;
+
+/** The `?scene=` / `?shot=` precedence rule, in one place: `scene=` names the
+ *  document and wins; `shot=` is the ORIGINAL spelling of the document name
+ *  and is read as one only when `scene=` is absent. Non-empty, because
+ *  `?scene=` alone is a URL a truncating share sheet produces. */
+export function wantedDocOf(params: URLSearchParams): string | null {
+  const wanted = params.get("scene") ?? params.get("shot");
+  return wanted !== null && wanted.length > 0 ? wanted : null;
+}
+
+/** Kick the open for the URL's document, if it names one. Called from main.tsx
+ *  at module scope — before createRoot, so the round trip overlaps the mount.
+ *  `openShot` handles its own errors (they land in state.error). */
+export function startBootOpen(store: ShotEditorStore): void {
+  const wanted = wantedDocOf(new URLSearchParams(window.location.search));
+  if (wanted === null) return;
+  started = { store, wanted, promise: store.openShot(wanted) };
+}
+
+/** The in-flight boot open for exactly this store and document, or null. */
+export function bootOpenFor(store: ShotEditorStore, wanted: string): Promise<void> | null {
+  if (started === null || started.store !== store || started.wanted !== wanted) return null;
+  return started.promise;
+}

package/src/state/cameraVerbs.ts

@@ -0,0 +1,139 @@
+// THE CAMERA VERBS: every word the chrome uses for moving the shot camera,
+// and the sentence that explains each, in one table.
+//
+// ── WHY THIS FILE EXISTS ────────────────────────────────────────────────
+//
+// The same verb was spelled four ways: "Align camera" on the bar, "Point the
+// shot camera where this view is looking" in its tooltip, "Point the camera at
+// this view" in the View menu and "Point the camera at the working view" in
+// the manual. Follow had four spellings of its own. An author meeting the
+// third spelling had no way to know it was the first verb again, and the
+// founder's verdict on the result was "I don't know what these options are".
+//
+// So the rows live here once, the way `layouts.ts` holds the layout rows: one
+// literal, `as const satisfies Record<...>`, and the bar, the View menu, the
+// shortcut manual and the in-pane badge all DERIVE from it. A verb cannot be
+// renamed on one surface and not another, because no surface owns a word.
+//
+// ── TWO CAMERAS, SAID ONCE ──────────────────────────────────────────────
+//
+// The 3D view is the author's own eye: editor state, never exported. The shot
+// camera is the picture. Every verb in this table moves the SHOT camera, and
+// the caption says so above them, because nothing on screen ever named the
+// pair before and every confusion about these verbs came from that.
+
+import type { CameraGate } from "@dailies-studio/shot/doc";
+
+export type CameraVerb = "pilot" | "toView" | "frameSelection" | "addMove";
+
+export interface CameraVerbSpec {
+  /** The bar's row, the menu row and the manual's name. Short, a verb phrase. */
+  label: string;
+  /** What it does, in one sentence: the tooltip, the manual's line, the docs. */
+  sentence: string;
+  /** The App menu row's id, which is also how `shortcuts.ts` points a row at a
+   *  menu entry and how the menu asks for its accelerator. */
+  menuId: string;
+}
+
+export const CAMERA_VERBS = {
+  pilot: {
+    label: "Pilot camera",
+    sentence:
+      "Steer the shot camera from the Camera pane: middle-drag orbits, shift-drag pans, " +
+      "wheel zooms, R rolls. Esc stops.",
+    menuId: "view.camera.pilot",
+  },
+  toView: {
+    label: "Move camera to view",
+    sentence: "Put the shot camera where the 3D view is looking.",
+    menuId: "view.camera.align",
+  },
+  frameSelection: {
+    label: "Frame selection with camera",
+    sentence: "Move the shot camera so the selected layers fill the frame.",
+    menuId: "view.camera.fitSelection",
+  },
+  addMove: {
+    label: "Add camera move",
+    sentence: "Start a camera move that ends at the playhead.",
+    menuId: "view.camera.addMove",
+  },
+} as const satisfies Record<CameraVerb, CameraVerbSpec>;
+
+/** Every verb, in the order the bar and the menu list them. */
+export const CAMERA_VERB_KEYS = Object.keys(CAMERA_VERBS) as readonly CameraVerb[];
+
+/** One row, seen as a `CameraVerbSpec` rather than as its own literal type —
+ *  the same widening `layoutSpec` makes, in one place. */
+export function cameraVerb(key: CameraVerb): CameraVerbSpec {
+  return CAMERA_VERBS[key];
+}
+
+/** The caption above the verbs: the one sentence that teaches the model. */
+export const TWO_CAMERAS =
+  "Two cameras: the 3D view is yours and is never exported. The shot camera is the " +
+  "picture. Everything below moves the shot camera.";
+
+/** The in-pane badge while piloting, when nothing holds the camera. */
+export const PILOT_BADGE = "PILOTING CAMERA · ESC TO EJECT";
+
+/**
+ * What hovering the camera gizmo says about the drag it offers, or null when a
+ * drag simply moves the scene's own camera.
+ *
+ * The gate's own answer in the drag pill's voice: short, upper case, and said
+ * BEFORE the press. The full sentence with the two ways out stays the error
+ * strip's and the inspector's.
+ */
+export function gateBadge(gate: CameraGate | null): string | null {
+  if (gate === null) return null;
+  const label = gate.shot === undefined ? "" : ` "${gate.shot.label.toUpperCase()}"`;
+  switch (gate.kind) {
+    case "free":
+      if (gate.writes === "editsMove") return `DRAG EDITS THE MOVE${label}`;
+      if (gate.writes === "newMove") return "DRAG ADDS A CAMERA MOVE ENDING HERE";
+      return null;
+    case "held":
+      return `HELD BY THE MOVE${label} · ⇧A TO ANIMATE`;
+    case "derived":
+      return `${label.trim()} FOLLOWS ITS LAYERS · NOTHING TO DRAG`;
+    case "shaped":
+      return `${label.trim()} IS A PATH · EDIT ITS POSES IN THE INSPECTOR`;
+    case "tooEarly":
+      return "MOVE THE PLAYHEAD LATER TO ANIMATE";
+  }
+}
+
+/** The pilot badge's text for a gate (and a driver), composed by the chrome. */
+export function pilotText(gate: CameraGate | null, driver: string | null): string {
+  if (driver !== null) return pilotHoldBadge("driven", driver);
+  if (gate === null || gate.kind === "free") return PILOT_BADGE;
+  return pilotHoldBadge(gate.kind, gate.shot?.label ?? null);
+}
+
+/**
+ * The badge while piloting a camera that a gesture cannot write.
+ *
+ * SHORT, and in the badge's own voice: the gate's full sentence (with the two
+ * ways out) is the inspector's and the error strip's. `label` is the move's
+ * name, or the component's when a component drives the camera.
+ */
+export function pilotHoldBadge(
+  hold: "held" | "derived" | "shaped" | "tooEarly" | "driven",
+  label: string | null,
+): string {
+  const name = label === null ? "" : ` "${label.toUpperCase()}"`;
+  switch (hold) {
+    case "held":
+      return `PILOTING CAMERA · HELD BY${name} · ⇧A TO ANIMATE · ESC TO EJECT`;
+    case "derived":
+      return `PILOTING CAMERA ·${name} FOLLOWS ITS LAYERS · LOOK ONLY · ESC TO EJECT`;
+    case "shaped":
+      return `PILOTING CAMERA ·${name} IS A PATH · EDIT ITS POSES IN THE INSPECTOR · ESC TO EJECT`;
+    case "tooEarly":
+      return "PILOTING CAMERA · MOVE THE PLAYHEAD LATER TO ANIMATE · ESC TO EJECT";
+    case "driven":
+      return `PILOTING CAMERA · DRIVEN BY${name === "" ? " A COMPONENT" : name} · LOOK ONLY · ESC TO EJECT`;
+  }
+}

package/src/state/clientId.ts

@@ -9,8 +9,13 @@
 // In memory rather than sessionStorage on purpose: two tabs of the same
 // document must be two clients, and sessionStorage is per-tab but survives a
 // reload — which would make a reloaded tab claim the pre-reload tab's writes.
+//
+// Hosted, it is the code host's (hostApi.ts `clientId`): the tab's one id, so
+// an agent session asked from this chrome relays its browser tools to this
+// tab's code host and no other.
+import { dailiesHost } from "../hostApi.js";
 
-export const CLIENT_ID: string = crypto.randomUUID();
+export const CLIENT_ID: string = dailiesHost()?.clientId ?? crypto.randomUUID();
 
 export const CLIENT_ID_HEADER = "x-studio-client-id";