@dailies-studio/shot-editor 0.1.0

package/src/state/agentActions.ts

@@ -0,0 +1,203 @@
+// Async flows for the shot editor's agent drawer. The store holds state; every
+// await lives here — the sibling chromes' posture, over the SHARED
+// @dailies-studio/agent-client core so the four panels cannot interpret the same
+// SSE stream four different ways.
+//
+// ── WHAT THIS LANE DOES THAT THE OTHERS DO NOT NEED TO ──────────────────
+//
+// Nothing, and that is the point of having one document. The canvas chrome's
+// version carries an `openBoard` arm and a "which board am I focused on"
+// branch. A shot chrome has ONE document open, so an apply is either "the open
+// shot" (the SSE bus adopts it, exactly as it adopts another tab's save) or
+// "some other shot" (it landed on disk; the switcher will show it), and there
+// is no third case to get wrong.
+import { AgentApiError, applyAgentEvent, createItemIds } from "@dailies-studio/agent-client";
+import type { AgentEvent, AgentProposalItem, TranscriptSink } from "@dailies-studio/agent-client";
+import { ApiError, agent } from "../api.js";
+import type { ShotEditorStore } from "./store.js";
+import type { ShotEditorState } from "./types.js";
+
+function message(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/** 409 from either error class — the shared client throws AgentApiError, this
+ *  chrome's own request helper throws ApiError, and a stale card must look the
+ *  same whichever leg reported it. */
+function isConflict(e: unknown): boolean {
+  return (e instanceof AgentApiError || e instanceof ApiError) && e.status === 409;
+}
+
+const itemId = createItemIds("sh");
+
+export async function refreshAgentCredentials(store: ShotEditorStore): Promise<void> {
+  try {
+    store.setAgentCredentials(await agent.credentials());
+  } catch (e) {
+    store.setAgentCredentials(null, message(e));
+  }
+}
+
+export async function saveAgentKey(store: ShotEditorStore, key: string): Promise<void> {
+  try {
+    store.setAgentCredentials(await agent.setKey(key));
+  } catch (e) {
+    // Keep the last good credential state; the error rides beside it.
+    store.setAgentCredentials(store.getState().agentCredentials, message(e));
+  }
+}
+
+export async function clearAgentKey(store: ShotEditorStore): Promise<void> {
+  try {
+    store.setAgentCredentials(await agent.clearKey());
+  } catch (e) {
+    store.setAgentCredentials(store.getState().agentCredentials, message(e));
+  }
+}
+
+/**
+ * What "this" means in the shot chrome: which surface is asking, which shot is
+ * open, which scene and frame the author is looking at.
+ *
+ * `surface: "shot"` is load-bearing, not decoration — it is what makes the
+ * server append the shot addendum to the system prompt AND compose the shot
+ * tools for the session. Everything else is clamped to ids and names: the
+ * document itself is never pinned, because the agent pulls it (fresh, and only
+ * when it needs it) through `get_shot_doc`.
+ */
+export function buildShotAgentContext(s: ShotEditorState): unknown {
+  const shot: Record<string, unknown> = {};
+  if (s.name !== null) shot.docName = s.name;
+  if (s.doc !== null) shot.componentName = s.doc.name;
+  // The playhead and the open scene, unconditionally. Every layer in this lane
+  // renders AT a frame, so "which moment am I looking at" is always a real
+  // statement about what the author means by "this".
+  shot.frame = s.frame;
+  if (s.sceneId !== null) shot.sceneId = s.sceneId;
+  const primary = s.selection[0];
+  if (primary !== undefined) shot.selectedLayerId = primary;
+  return { surface: "shot", ...(Object.keys(shot).length > 0 ? { shot } : {}) };
+}
+
+/** Every key `buildShotAgentContext` may put under `context.shot`. The server
+ *  rejects anything else, so this list and the server's are one contract. */
+export const SHOT_CONTEXT_KEYS = ["docName", "componentName", "frame", "sceneId", "selectedLayerId"];
+
+/** The store, seen as the shared reducer's three transcript verbs. */
+function sinkFor(store: ShotEditorStore): TranscriptSink {
+  return {
+    append: (item) => store.appendAgentItem(item),
+    patchProposal: (id, patch) => store.patchAgentProposal(id, patch),
+    setCost: (costUsd) => store.setAgentCost(costUsd),
+  };
+}
+
+/** One turn: create a session, stream it to the end. Resolves when the
+ *  transcript is complete (or the transport failed). */
+export async function askAgent(store: ShotEditorStore, prompt: string): Promise<void> {
+  const s = store.getState();
+  if (s.agentRunning || prompt.trim() === "") return;
+  store.setAgentError(null);
+  store.appendAgentItem({ id: itemId(), kind: "user", text: prompt });
+  store.setAgentRunning(true);
+  try {
+    const { sessionId } = await agent.createSession({
+      prompt,
+      ...(s.agentModel !== null ? { model: s.agentModel } : {}),
+      context: buildShotAgentContext(s),
+    });
+    store.setAgentSession(sessionId);
+    await agent.events(sessionId, (event: AgentEvent) => {
+      applyAgentEvent(sinkFor(store), sessionId, event, itemId);
+    });
+  } catch (e) {
+    store.setAgentError(message(e));
+  } finally {
+    store.setAgentRunning(false);
+  }
+}
+
+export async function cancelAgent(store: ShotEditorStore): Promise<void> {
+  const sessionId = store.getState().agentSessionId;
+  if (sessionId === null || !store.getState().agentRunning) return;
+  try {
+    await agent.cancel(sessionId);
+  } catch (e) {
+    store.setAgentError(message(e));
+  }
+}
+
+function proposalOf(store: ShotEditorStore, id: string): AgentProposalItem | undefined {
+  return store
+    .getState()
+    .agentItems.find((i): i is AgentProposalItem => i.kind === "proposal" && i.id === id);
+}
+
+/**
+ * Apply one proposal.
+ *
+ * The apply POST is the authority — it validates baseRev, writes the doc,
+ * re-runs codegen and audits.
+ *
+ * ── AND THEN NOTHING, DELIBERATELY ─────────────────────────────────────
+ *
+ * There is no re-read here. The server's store emits `doc-changed` on the SSE
+ * bus for EVERY write, so this chrome adopts an agent apply through exactly the
+ * same path it adopts a second tab's save — `adoptExternalChange`, which also
+ * owns the "you have unsaved edits" refusal. A second adoption path here would
+ * be a second answer to "what happens when the document moves underneath me",
+ * and only one of them would have that refusal in it.
+ *
+ * The one thing the bus cannot do is OPEN a document this chrome does not have,
+ * which is what a create needs.
+ */
+export async function applyAgentProposal(store: ShotEditorStore, proposalId: string): Promise<void> {
+  const item = proposalOf(store, proposalId);
+  if (item === undefined || item.status !== "pending") return;
+  store.patchAgentProposal(proposalId, { status: "applying", error: null });
+  // THE AUTHOR'S OWN EDITS GO FIRST. Apply is a button in the same window as
+  // the canvas, so "drag a layer, then click Apply" is an ordinary gesture —
+  // and on loopback the apply round trip beats the autosave debounce. Flushing
+  // first means the author's edit either lands (and this proposal correctly
+  // goes stale, visibly) or fails visibly — never disappears.
+  try {
+    await store.flush();
+  } catch {
+    // flush records its own error; the apply still gets its chance, and a stale
+    // baseRev now shows up as a 409 rather than a silent loss.
+  }
+  try {
+    // Against the MINTING session — later asks created newer sessions.
+    const result = (await agent.apply(item.sessionId, proposalId)) as { warning?: unknown } | null;
+    // "applied with warnings" is a real state: the document was written but
+    // codegen refused (a hand-edited generated file). A green card there is the
+    // one place a half-landed change reads as a landed one.
+    const warning = typeof result?.warning === "string" ? result.warning : null;
+    store.patchAgentProposal(proposalId, { status: "applied", warning });
+  } catch (e) {
+    store.patchAgentProposal(proposalId, {
+      status: isConflict(e) ? "stale" : "failed",
+      error: message(e),
+    });
+    return;
+  }
+
+  if (item.proposalKind !== "shot") return;
+  if (store.getState().name !== item.docName && item.baseRev === null) {
+    // A CREATE names a shot this chrome does not have open — by definition, it
+    // did not exist. Open it: "ask for a video, get an editable one" is the
+    // whole promise of the lane, and leaving the author staring at the previous
+    // document with a green card would be a worse lie than any error.
+    try {
+      await store.openShot(item.docName);
+    } catch (e) {
+      store.patchAgentProposal(proposalId, {
+        status: "applied",
+        warning: `the shot was written, but opening "${item.docName}" failed: ${message(e)}`,
+      });
+    }
+  }
+  // …but an EDIT of some other shot never yanks the author out of the document
+  // they are working in. It landed on disk; the switcher will show it.
+  void store.refreshShots();
+}

package/src/state/clientId.ts

@@ -0,0 +1,25 @@
+// Who this browser surface IS, for the length of one page load.
+//
+// The shot twin of the canvas lane's clientId. It is ATTRIBUTION and never
+// authorization: the server echoes it back on every change event so a surface
+// can recognise its OWN write and skip adopting it. Without that, an autosave
+// round-trips as a "someone else changed this document" push and the chrome
+// fights its own save.
+//
+// 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.
+
+export const CLIENT_ID: string = crypto.randomUUID();
+
+export const CLIENT_ID_HEADER = "x-studio-client-id";
+
+/** The origin label this chrome's own writes carry. */
+export const MY_ORIGIN = "shot-editor";
+
+/** Is this change event our own echo? Client id wins when present; origin is
+ *  the fallback for a server that predates it. */
+export function isOwnEcho(payload: { origin?: string; clientId?: string }): boolean {
+  if (payload.clientId !== undefined) return payload.clientId === CLIENT_ID;
+  return payload.origin === MY_ORIGIN;
+}

package/src/state/context.tsx

@@ -0,0 +1,33 @@
+import { createContext, useContext, useSyncExternalStore } from "react";
+import type { ReactNode } from "react";
+import type { ShotEditorStore } from "./store.js";
+import type { ShotEditorState } from "./types.js";
+
+const StoreContext = createContext<ShotEditorStore | null>(null);
+
+export function StoreProvider(props: { store: ShotEditorStore; children: ReactNode }) {
+  return <StoreContext.Provider value={props.store}>{props.children}</StoreContext.Provider>;
+}
+
+export function useStore(): ShotEditorStore {
+  const store = useContext(StoreContext);
+  if (!store) throw new Error("useStore outside <StoreProvider>");
+  return store;
+}
+
+/**
+ * Subscribe to a slice of shot-editor state.
+ *
+ * The selector result is compared with Object.is per notification, so return
+ * state slices and primitives — never a freshly-built object or array, which
+ * would re-render on every unrelated notification and which
+ * `useSyncExternalStore` would reject outright as an unstable snapshot.
+ */
+export function useShotEditor<T>(selector: (s: ShotEditorState) => T): T {
+  const store = useStore();
+  return useSyncExternalStore(
+    store.subscribe,
+    () => selector(store.getState()),
+    () => selector(store.getState()),
+  );
+}