@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/api.ts

@@ -4,21 +4,40 @@
 // back labelled and this chrome can tell its own echo from someone else's write
 // (see state/clientId.ts). Every write also carries `baseRev`, so a lost race
 // is a 409 the author sees rather than a silent clobber.
-import type { Doc3D, ExportFormat, ExportQualityId, RenderStats } from "@dailies-studio/shot/doc";
+import { PROJECT_MEDIA_LIMIT_BYTES } from "@dailies-studio/shot/doc";
+import type { DefClosure, OpenverseSource3D } from "@dailies-studio/shot/doc";
+import type {
+  ComponentDef3D,
+  ComponentUse,
+  Doc3D,
+  ExportFormat,
+  ExportQualityId,
+  LibraryReferenceKind3D,
+  MaterialGraph3D,
+  MediaProbe,
+  RenderStats,
+  ShotAsset,
+  ShotComponentHost,
+  SyncSnapshot,
+} from "@dailies-studio/shot/doc";
 import type { Contract } from "@dailies-studio/contract";
+import type { ComponentSource } from "@dailies-studio/ui";
 import { createAgentClient } from "@dailies-studio/agent-client";
 import type { AgentClient, AgentTransport } from "@dailies-studio/agent-client";
 import { CLIENT_ID, CLIENT_ID_HEADER } from "./state/clientId.js";
-
-export interface ShotListing {
-  name: string;
-  mtimeMs: number;
-}
+import { dailiesHost } from "./hostApi.js";
+import type { DailiesHost, HostRefusalError } from "./hostApi.js";
 
 export interface LoadedShot {
   name: string;
   doc: Doc3D;
   rev: string;
+  /** What the caller may do with this Project. Absent (an older server)
+   *  means everything; hosted, a Viewer reads `edit: false`. */
+  can?: { edit: boolean; comment: boolean };
+  /** Live collaboration is on for this Project: edits go over the document's
+   *  live session (state/sync.ts), not `saveShot`. */
+  sync?: true;
 }
 
 export interface SaveResult {
@@ -36,6 +55,9 @@ export class ApiError extends Error {
     readonly status: number,
     message: string,
     readonly reason?: string,
+    readonly details?: Readonly<Record<string, unknown>>,
+    /** The body's machine `code`, e.g. "forbidden" for a role refusal. */
+    readonly code?: string,
   ) {
     super(message);
     this.name = "ApiError";
@@ -45,72 +67,268 @@ export class ApiError extends Error {
   }
 }
 
-async function request<T>(path: string, init?: RequestInit): Promise<T> {
-  const res = await fetch(path, {
-    ...init,
-    headers: {
-      ...(init?.body !== undefined ? { "content-type": "application/json" } : {}),
-      [CLIENT_ID_HEADER]: CLIENT_ID,
-      ...init?.headers,
-    },
-  });
-  const text = await res.text();
-  let body: unknown = null;
-  if (text.length > 0) {
-    try {
-      body = JSON.parse(text);
-    } catch {
-      // A non-JSON body from a route that owes JSON is itself the error.
-      throw new ApiError(res.status, text.slice(0, 400));
+/**
+ * How long a request waits out a workspace that is starting, and how often it
+ * asks again: the dashboard's budget (packages/dashboard/src/api.ts). The
+ * hosted Worker answers JSON 503 `{starting: true}` while the workspace's
+ * store resets after a deploy; any other 503 is a real failure.
+ */
+export const STARTING_BUDGET_MS = 20_000;
+export const STARTING_RETRY_MS = 1_500;
+
+/** `baseRevGuarded`: a write the store refuses as stale (409) once a first
+ *  attempt landed, so sending it again after a 503 `{starting: true}` cannot
+ *  do twice what the first did. A read is retried too; nothing else is.
+ *  `onStatus` hears the final answer's status, for a route whose 200 and 201
+ *  mean different things. */
+async function request<T>(
+  path: string,
+  init?: RequestInit,
+  baseRevGuarded = false,
+  onStatus?: (status: number) => void,
+): Promise<T> {
+  const method = (init?.method ?? "GET").toUpperCase();
+  const retries = baseRevGuarded || method === "GET" || method === "HEAD";
+  const deadline = Date.now() + STARTING_BUDGET_MS;
+  let res: Response;
+  let body: unknown;
+  for (;;) {
+    res = await fetch(path, {
+      ...init,
+      headers: {
+        ...(init?.body !== undefined ? { "content-type": "application/json" } : {}),
+        [CLIENT_ID_HEADER]: CLIENT_ID,
+        ...init?.headers,
+      },
+    });
+    const text = await res.text();
+    body = null;
+    if (text.length > 0) {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        // A non-JSON body from a route that owes JSON is itself the error.
+        throw new ApiError(res.status, text.slice(0, 400));
+      }
     }
+    const starting = res.status === 503 && (body as { starting?: unknown } | null)?.starting === true;
+    if (!starting || !retries || Date.now() + STARTING_RETRY_MS > deadline) break;
+    await new Promise((resolve) => setTimeout(resolve, STARTING_RETRY_MS));
   }
   if (!res.ok) {
-    const b = body as { error?: unknown; reason?: unknown } | null;
+    const b = body as { error?: unknown; reason?: unknown; code?: unknown } | null;
+    // The whole body rides along, so a caller can read a refusal's extras
+    // (`userIds` on a 422 mention_no_access, `retry` on a 429).
+    const details = typeof body === "object" && body !== null ? (body as Readonly<Record<string, unknown>>) : undefined;
     throw new ApiError(
       res.status,
-      typeof b?.error === "string" ? b.error : `${init?.method ?? "GET"} ${path} failed (${res.status})`,
+      details !== undefined && b?.code === "project_quota_exceeded"
+        ? quotaMessage(details)
+        : typeof b?.error === "string"
+          ? b.error
+          : `${init?.method ?? "GET"} ${path} failed (${res.status})`,
       typeof b?.reason === "string" ? b.reason : undefined,
+      details,
+      typeof b?.code === "string" ? b.code : undefined,
     );
   }
+  onStatus?.(res.status);
   return body as T;
 }
 
-export function listShots(): Promise<{ shots: ShotListing[] }> {
-  return request("/api/shots");
-}
-
 export function loadShot(name: string): Promise<LoadedShot> {
   return request(`/api/shots/${encodeURIComponent(name)}`);
 }
 
+/** The live document with its place in the session's log: what a snapshot
+ *  too large for the socket points at. */
+export function loadShotSnapshot(name: string): Promise<SyncSnapshot> {
+  return request(`/api/shots/${encodeURIComponent(name)}?sync=1`);
+}
+
 /** `baseRev` is REQUIRED at this seam even though the route allows it to be
  *  absent: an editor that omits it is an editor that can silently overwrite
  *  another surface's work, and `null` already means "I am claiming a create". */
 export function saveShot(name: string, doc: Doc3D, baseRev: string | null): Promise<SaveResult> {
-  return request(`/api/shots/${encodeURIComponent(name)}`, {
-    method: "PUT",
-    body: JSON.stringify({ doc, baseRev }),
+  return request(
+    `/api/shots/${encodeURIComponent(name)}`,
+    { method: "PUT", body: JSON.stringify({ doc, baseRev }) },
+    true,
+  );
+}
+
+/**
+ * Re-emit `src/shots/<Name>.tsx` from the document, discarding hand edits.
+ *
+ * ALWAYS DESTRUCTIVE at this seam, and the caller must confirm before reaching
+ * it. The route's GET is the dry run and its POST without the flag is a
+ * re-emit that still refuses a conflict — but a menu row named "Regenerate" that
+ * reported "still blocked" and did nothing would leave the author exactly where
+ * the emit warning already put them, which is the state this row exists to
+ * leave. `ok: false` with `blocked` is still a 200: the answer arrived.
+ */
+export function regenerateShot(name: string): Promise<{
+  ok: boolean;
+  generated: string | null;
+  blocked?: string;
+  warning?: string;
+}> {
+  return request(`/api/shots/${encodeURIComponent(name)}/regenerate`, {
+    method: "POST",
+    body: JSON.stringify({ discardHandEdits: true }),
   });
 }
 
-export function deleteShot(name: string): Promise<{ deleted: true }> {
-  return request(`/api/shots/${encodeURIComponent(name)}`, { method: "DELETE" });
+// ---- version history (packages/store/src/shotVersions.ts) --------------------
+
+/** The open autosave group: the edits that led to the stored document. */
+export interface ShotVersionHead {
+  /** User ids, first writer first. "local" is the CLI's one user. */
+  authors: string[];
+  /** Epoch ms of the group's first and last save. */
+  from: number;
+  at: number;
 }
 
-export function renameShot(name: string, to: string): Promise<{ renamed: true; generated: string | null }> {
-  return request(`/api/shots/${encodeURIComponent(name)}/rename`, {
-    method: "POST",
-    body: JSON.stringify({ to }),
-  });
+export interface ShotVersion extends ShotVersionHead {
+  id: string;
+  rev: string;
+  /** Present on a named version. */
+  name?: string;
+  /** The row a restore brought back. */
+  restoredFrom?: string;
 }
 
-export function duplicateShot(name: string, to: string): Promise<{ duplicated: true }> {
-  return request(`/api/shots/${encodeURIComponent(name)}/duplicate`, {
-    method: "POST",
-    body: JSON.stringify({ to }),
+export interface ShotVersionList {
+  head: ShotVersionHead | null;
+  /** Newest first. */
+  versions: ShotVersion[];
+  /** User id to display name (hosted). Empty from the CLI. */
+  people: Record<string, string>;
+}
+
+const versionsPath = (name: string, rest = ""): string => `/api/shots/${encodeURIComponent(name)}/versions${rest}`;
+
+// ---- an agent's question to the person (store agentQuestions.ts) ----------
+
+/** What an export question opens the Export dialog with (store
+ *  `AgentQuestionExport`); each absent field is the dialog's own default. */
+export interface AgentQuestionExport {
+  format?: ExportFormat;
+  quality?: ExportQualityId;
+  scene?: string;
+}
+
+/** The saved video an export question's yes made (store
+ *  `AgentQuestionVideo`): in Videos, written by the studio server's render, or
+ *  only downloaded. */
+export type AgentQuestionVideo =
+  | { where: "videos"; id: string; url: string }
+  | { where: "project"; path: string }
+  | { where: "downloads"; filename: string };
+
+/** The question as the route answers it (store `AgentQuestion`, restated:
+ *  the chrome does not depend on the store package). */
+export interface AgentQuestion {
+  id: string;
+  projectId: string;
+  question: string;
+  summary: string;
+  boardRev: string;
+  askedBy: { client: string; member: string | null; sessionId: string };
+  askedAt: number;
+  status: "open" | "answered" | "withdrawn";
+  /** A later question's export: a yes opens the Export dialog with it. */
+  export?: AgentQuestionExport;
+  answer?: {
+    choice: "yes" | "changes";
+    note?: string;
+    by: { id: string; name: string };
+    at: number;
+    boardRev: string | null;
+    video?: AgentQuestionVideo;
+  };
+}
+
+const questionPath = (name: string): string => `/api/shots/${encodeURIComponent(name)}/question`;
+
+/** The Project's open question, else its latest answered one for a day. */
+export async function getAgentQuestion(name: string): Promise<AgentQuestion | null> {
+  return (await request<{ question: AgentQuestion | null }>(questionPath(name))).question;
+}
+
+/** Answer it: "yes" makes the video, "changes" sends the note. */
+export async function answerAgentQuestion(
+  name: string,
+  id: string,
+  body: { choice: "yes" | "changes"; note?: string },
+): Promise<AgentQuestion> {
+  return (
+    await request<{ question: AgentQuestion }>(`${questionPath(name)}/${encodeURIComponent(id)}/answer`, {
+      method: "POST",
+      body: JSON.stringify(body),
+    })
+  ).question;
+}
+
+/** Tell an export question where its saved video is, which wakes the
+ *  agent's waiting get_answer. */
+export async function reportAgentQuestionVideo(name: string, id: string, video: AgentQuestionVideo): Promise<AgentQuestion> {
+  return (
+    await request<{ question: AgentQuestion }>(`${questionPath(name)}/${encodeURIComponent(id)}/video`, {
+      method: "POST",
+      body: JSON.stringify({ video }),
+    })
+  ).question;
+}
+
+export function listVersions(name: string): Promise<ShotVersionList> {
+  return request(versionsPath(name));
+}
+
+/** Close the open group as a version. `rev` refuses (409) when the stored
+ *  document is no longer the one the author saw. */
+export function saveVersion(name: string, body: { name?: string; rev?: string }): Promise<{ version: ShotVersion }> {
+  return request(versionsPath(name), { method: "POST", body: JSON.stringify(body) });
+}
+
+export function readVersion(name: string, id: string): Promise<{ version: ShotVersion; doc: Doc3D }> {
+  return request(versionsPath(name, `/${encodeURIComponent(id)}`));
+}
+
+export function renameVersion(name: string, id: string, label: string): Promise<{ version: ShotVersion }> {
+  return request(versionsPath(name, `/${encodeURIComponent(id)}`), {
+    method: "PATCH",
+    body: JSON.stringify({ name: label }),
   });
 }
 
+/** Write the version's document as a new save. The live session adopts it
+ *  like any other write, so the editor sees a change event. */
+export function restoreVersion(name: string, id: string): Promise<{ version: ShotVersion; rev: string }> {
+  return request(versionsPath(name, `/${encodeURIComponent(id)}/restore`), { method: "POST" });
+}
+
+/** The Trash entries of the document `docId`. A hosted editor may list no
+ *  more than that; the local server lists the whole Trash. `id` is the
+ *  Project's id (hosted, where it is the document's id too); `name` the name
+ *  it had (local). */
+export function listTrash(docId: string): Promise<{ items: { trashId: string; id?: string; name?: string; deletedAt: number }[] }> {
+  return request(`/api/trash?doc=${encodeURIComponent(docId)}`);
+}
+
+/** Bring a Project back from the Trash (R10's "Restore"). `name` is where it
+ *  landed: its old name, or a free one if that was taken meanwhile. */
+export function restoreFromTrash(trashId: string): Promise<{ name: string }> {
+  return request(`/api/trash/${encodeURIComponent(trashId)}/restore`, { method: "POST" });
+}
+
+/** `doc` as a new Project, beside a trashed one whose media it may use (R10's
+ *  "Save as copy"). */
+export function copyFromTrash(trashId: string, doc: Doc3D): Promise<{ name: string; id: string; title: string }> {
+  return request(`/api/trash/${encodeURIComponent(trashId)}/copy`, { method: "POST", body: JSON.stringify({ doc }) });
+}
+
 // ---- the component registry (instance layers) --------------------------------
 
 /**
@@ -122,7 +340,10 @@ export function duplicateShot(name: string, to: string): Promise<{ duplicated: t
  *
  * `host` is the instance gate (only "three" components can be instanced — a
  * "dom" one under the three reconciler is a hard crash, and the SERVER's
- * `classifyHost` is what decided the value). `contractHash` is the drift
+ * `classifyHost` is what decided the value). Its union is `ShotComponentHost`,
+ * imported rather than restated: the row is the wire shape of a value the
+ * schema already owns, and a chrome-local copy would keep typechecking after a
+ * host classification was added. `contractHash` is the drift
  * baseline recorded on the layer. `contractAvailability` is the server's own
  * verdict on whether generated code can STATICALLY IMPORT the contract or
  * whether the document must carry a snapshot — consumed verbatim, never
@@ -137,7 +358,14 @@ export interface ComponentRow {
   contractHash: string;
   contractSource: "declared" | "inferred";
   contractAvailability?: "sibling" | "colocated" | "inferred";
-  host: "dom" | "three" | "dom-embedded-gl";
+  host: ShotComponentHost;
+  /**
+   * The SERVER's verdict on where the component came from: the user's own code
+   * or something the studio shipped. `builtin` is the older flag and both are
+   * on the wire, so read them through `componentSourceOf` from
+   * `@dailies-studio/ui` rather than testing either one directly.
+   */
+  source?: ComponentSource;
   builtin?: boolean;
   /**
    * Present only on catalog EFFECTS, which is what makes it the filter for the
@@ -155,10 +383,241 @@ export interface ComponentRow {
     thumb?: string;
     softwareRaster?: "unfinished";
   };
+  /**
+   * Where the SERVER says this component came from: the user's own code, a
+   * shipped built-in, or a library item this Project vendored under
+   * `src/shared/`. Derived from the install lockfile at read time, which is
+   * why the document never stores it: a field would go stale on uninstall.
+   */
+  library?: LibraryDescriptor;
+}
+
+// ---- the shipped library -----------------------------------------------------
+//
+// Chrome-local copies of the CLI's `libraryCatalog.ts` shapes, for the same
+// reason `ComponentRow` is declared above rather than imported: only these
+// fields are load-bearing here, and the shot chrome depends on no other package
+// for a wire shape. Every field the server ADDS later keeps this typechecking.
+
+export type LibraryScope = "builtin" | "shared" | "project";
+
+export interface LibraryDescriptor {
+  scope: LibraryScope;
+  removable: boolean;
+  publisher?: string;
+  libraryId?: string;
+  libraryVersion?: number;
+  /** The installed files no longer match what was installed. */
+  modified?: boolean;
+}
+
+/** `component`, the four kinds a `library` reference may name, and `sounds`,
+ *  which is none of them: a pack is imported and its files become sound
+ *  cards, so a `library` card of kind "sounds" is a type error here. */
+export type LibraryItemKind = "component" | LibraryReferenceKind3D | "sounds";
+
+/**
+ * One row of `GET /api/library/catalog`: a built-in, an installed shared
+ * component, or a SHIPPED item. `action` is the server's verdict on what a
+ * drop does: `install` vendors a component first, `add` places one already in
+ * the registry (`installedAs` names it), `claim` copies a shot into a new
+ * Project, `import` lands a material, an image pack or a sound pack in this
+ * one, and `read` is a blueprint, which is copied by hand through its ops.
+ */
+export interface LibraryItem {
+  id: string;
+  name: string;
+  /** The manifest's human name; print it through `libraryDisplayName`. */
+  displayName?: string;
+  source: "builtin" | "shared" | "shipped";
+  group: string;
+  kind?: LibraryItemKind;
+  category?: string;
+  tags: string[];
+  vibe?: string[];
+  useFor?: string;
+  avoidFor?: string;
+  lengthFrames?: number;
+  deps?: string[];
+  /** The `/api/library/items/<id>` URL. */
+  docs?: string;
+  /** The `/api/library/items/<id>/thumb` URL, only when the item has one. */
+  thumb?: string;
+  host: ShotComponentHost;
+  action: "add" | "install" | "claim" | "import" | "read";
+  installedAs?: string;
+  description?: string;
+  publisher?: string;
+  version?: number;
+  updateAvailable?: boolean;
+}
+
+export interface LibraryCatalog {
+  items: LibraryItem[];
+  /** Items the registry refused to read. Named so the rail can say WHICH. */
+  problems: Array<{ id: string; error: string }>;
+}
+
+/** `GET /api/library/items/<id>`: the row, its `library.json`, its README and
+ *  the kind-specific extra. */
+export interface LibraryItemDetail {
+  item: LibraryItem;
+  manifest: Readonly<Record<string, unknown>>;
+  docs: string;
+  component?: {
+    files: Array<{ path: string; bytes: number; hash: string }>;
+    peerDeps: string[];
+    entry: string;
+    exportName: string;
+    host: ShotComponentHost;
+    contractHash: string;
+    installedAs?: string;
+    contract?: Contract;
+  };
+  shot?: { summary: { durationFrames: number; sceneCount: number; layerCount: number; outline: string[] } };
+  material?: { material: MaterialGraph3D };
+  blueprint?: { ops: unknown; expects: Array<{ layer: string; kind: string }> };
+  images?: { files: Array<{ path: string; kind: string; bytes: number }> };
+  /** A sound pack's files, each measured off its WAV: its length and where
+   *  it lands (`hitMs`, from its `library.json`). */
+  sounds?: {
+    files: Array<{
+      path: string;
+      kind: "audio";
+      bytes: number;
+      durationMs: number;
+      hitMs: number;
+      /** The author's name for the file (`library.json`); print it through
+       *  `libraryFileLabel`, which falls back to the stem. */
+      label?: string;
+    }>;
+  };
+}
+
+/** One sound a pack import registered: the Project asset id `add_audio` and a
+ *  sound card name, the pack's file name, and the two numbers it is placed by. */
+export interface LibraryAddedSound {
+  id: string;
+  file: string;
+  hitMs: number;
+  durationMs: number;
+}
+
+/** `POST /api/library/add-sounds`: the whole pack, content-addressed, so a
+ *  second import of the same pack uploads nothing and answers the same ids. */
+export interface LibraryAddSoundsResult {
+  assets: LibraryAddedSound[];
+  rev: string;
+  usedBytes: number;
+  remainingBytes: number;
+}
+
+/** `POST /api/library/install`: the CLI's `InstallResult`, plus the component
+ *  detail the route fetched AFTER awaiting its own registry rescan, so the
+ *  caller can place the component without a second round trip. */
+export interface LibraryInstallResult {
+  componentId: string;
+  dir: string;
+  written: string[];
+  removed: string[];
+  alreadyInstalled: boolean;
+  replaces: { version: number; contentHash: string } | null;
+  files: Array<{ path: string }>;
+  conflicts: string[];
+  componentDetail: ComponentDetail | null;
+}
+
+export function libraryCatalog(): Promise<LibraryCatalog> {
+  return request("/api/library/catalog");
+}
+
+export function libraryItem(id: string): Promise<LibraryItemDetail> {
+  return request(`/api/library/items/${encodeURIComponent(id)}`);
+}
+
+/** Vendor a shipped component into this Project. A 409 is a user file in the
+ *  way, refused before any byte lands. */
+export function libraryInstall(libraryId: string): Promise<LibraryInstallResult> {
+  return request("/api/library/install", {
+    method: "POST",
+    body: JSON.stringify({ libraryId }),
+  });
+}
+
+/** Copy a shipped shot into a NEW Project. 409 when `name` is taken. */
+export function libraryClaim(
+  libraryId: string,
+  name?: string,
+): Promise<{ name: string; title: string; projectId: string; href: string }> {
+  return request("/api/library/claim", {
+    method: "POST",
+    body: JSON.stringify(name === undefined ? { libraryId } : { libraryId, name }),
+  });
+}
+
+/** `baseRev` is the rev from the last read, so a stale write is a 409 the
+ *  author sees rather than a silent clobber: the same discipline as `saveShot`. */
+export function libraryImportMaterial(input: {
+  libraryId: string;
+  name: string;
+  baseRev: string;
+}): Promise<{ materialId: string; rev: string }> {
+  return request("/api/library/import-material", {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+export function libraryAddImages(input: {
+  libraryId: string;
+  name: string;
+  baseRev: string;
+}): Promise<{
+  assets: Array<{ id: string; path: string; hash: string; kind: string; size: number }>;
+  rev: string;
+  usedBytes: number;
+  remainingBytes: number;
+}> {
+  return request("/api/library/add-images", {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+/** Import a sound pack into a Project against a saved rev: the one sound
+ *  `file` names (a bare file name), or every file of it when it names none. */
+export function libraryAddSounds(input: {
+  libraryId: string;
+  name: string;
+  baseRev: string;
+  file?: string;
+}): Promise<LibraryAddSoundsResult> {
+  return request("/api/library/add-sounds", {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+/**
+ * Where a default edit would LAND and which keys can take one — the defaults
+ * rail renders read-only rows from this instead of learning editability from a
+ * refused write. Computed by the server against the current source bytes on
+ * every detail GET, never cached beside the contract (the answer can change
+ * without the contractHash moving). Absent on builtins.
+ */
+export interface ComponentDefaultsMeta {
+  /** Project-relative posix path the persist write targets: the sibling
+   *  `.controls.ts`, the component file (colocated / inferred). */
+  file: string;
+  /** False when the target sits in a generated lane — the whole rail is
+   *  read-only then, with the shot named as the owner. */
+  writable: boolean;
+  keys: Readonly<Record<string, { editable: true } | { editable: false; reason: string }>>;
 }
 
 export interface ComponentDetail extends ComponentRow {
   contract: Contract;
+  defaults?: ComponentDefaultsMeta;
 }
 
 /** A bare ARRAY, not an envelope — the shape that route has always answered. */
@@ -170,37 +629,382 @@ export function componentDetail(id: string): Promise<ComponentDetail> {
   return request(`/api/components/${encodeURIComponent(id)}`);
 }
 
+/** What persisting a default answers. */
+export interface ComponentDefaultResult {
+  file: string;
+  wrote: boolean;
+  hash?: string;
+  results: Readonly<Record<string, { status: "written" } | { status: "refused"; reason: string }>>;
+  contractHash: string;
+  editableKeys: ComponentDefaultsMeta["keys"];
+}
+
+/**
+ * Persist ONE contract default into the component's source — the defaults
+ * rail's commit. The server locates the exact span (the `default:` inside
+ * `defineControls`, or the destructured render-fn default) and splices the
+ * printed literal; everything else in the file survives byte-for-byte.
+ *
+ * `contractHash` is the drift baseline: a 409 means the contract moved since
+ * the panel loaded, and the caller refetches the detail rather than writing
+ * blind. The per-key verdict comes back in `results` on a 200 — a refused key
+ * is an answer, not an error.
+ *
+ * Hosted, the code host computes the edit (`__dailiesHost.applyDefaults`,
+ * the same decisions over the files it compiled), this module writes it
+ * through the file API with its baseHash, and the host re-extracts to answer
+ * the contract after it: the dev server's route, split at the write.
+ */
+export function setComponentDefault(
+  id: string,
+  contractHash: string,
+  key: string,
+  value: unknown,
+): Promise<ComponentDefaultResult> {
+  const host = dailiesHost();
+  if (host !== undefined) return hostedDefault(host, id, { contractHash, values: { [key]: value } });
+  return request(`/api/components/${encodeURIComponent(id)}/defaults`, {
+    method: "POST",
+    body: JSON.stringify({ contractHash, values: { [key]: value } }),
+  });
+}
+
+/** A host refusal as the error the dev server's route gives this module:
+ *  its status and message, and its `reason` when it carries one. Any other
+ *  failure passes through. */
+function hostError(error: unknown): unknown {
+  const status = (error as HostRefusalError | null)?.status;
+  if (!(error instanceof Error) || typeof status !== "number") return error;
+  const reason = (error as HostRefusalError).body?.["reason"];
+  return new ApiError(status, error.message, typeof reason === "string" ? reason : undefined);
+}
+
+async function viaHost<T>(call: () => Promise<T>): Promise<T> {
+  try {
+    return await call();
+  } catch (e) {
+    throw hostError(e);
+  }
+}
+
+/** The dev server's defaults route, hosted: edit, write with the edit's
+ *  baseHash, and on a 409 (the file moved under the edit) edit again and
+ *  write ONCE more, so a second collision is the author's to see, as there. */
+async function hostedDefault(
+  host: DailiesHost,
+  id: string,
+  body: { contractHash: string; values: Record<string, unknown> },
+): Promise<ComponentDefaultResult> {
+  let edit = await viaHost(() => host.applyDefaults(id, body));
+  let written: SourceFileSaved | null = null;
+  if (edit.edits > 0) {
+    try {
+      written = await writeFile(edit.file, edit.content, edit.baseHash);
+    } catch (e) {
+      if (!(e instanceof ApiError) || e.status !== 409) throw e;
+      edit = await viaHost(() => host.applyDefaults(id, body));
+      if (edit.edits > 0) written = await writeFile(edit.file, edit.content, edit.baseHash);
+    }
+  }
+  // The contract the host serves now, the write extracted.
+  const after = await viaHost(() => host.componentDefaults(id));
+  return {
+    file: edit.file,
+    wrote: written !== null,
+    ...(written !== null ? { hash: written.hash } : {}),
+    results: edit.results,
+    contractHash: after?.contractHash ?? edit.contractHash,
+    editableKeys: after?.editableKeys ?? {},
+  };
+}
+
+// ---- code component source ---------------------------------------------------
+//
+// `/api/files` is the studio's ONE write path into user code, and it is the
+// same route the motion chrome's code drawer has always used. Nothing new is
+// added server-side for the code studio: the containment guard, the generated
+// guard, the sha256 conflict check and the atomic write are all already there,
+// and reaching them through anything but this route would be a second set of
+// rules over the same files.
+
+/** Mirror of the server's FileDiagnostic. Positions are 0-based offsets into
+ *  the text that was checked, which is the buffer when one was sent. */
+export interface CodeDiagnostic {
+  category: "error" | "warning" | "suggestion" | "message";
+  code: number;
+  message: string;
+  start: number;
+  length: number;
+  line: number;
+  character: number;
+  endLine: number;
+  endCharacter: number;
+}
+
+export interface SourceFile {
+  path: string;
+  content: string;
+  /** sha256 of the bytes on disk. Sent back as `baseHash` to make a write
+   *  conflict-checked, which is how a save can refuse rather than clobber. */
+  hash: string;
+  mtimeMs: number;
+  size: number;
+  /** What the file uses on disk, so a save can put it back. */
+  lineEnding: "lf" | "crlf";
+  /** Set when the file is a build product the studio itself emits. */
+  generated?: { lane: string; by: string; id: string; docName?: string };
+}
+
+export interface SourceFileSaved {
+  saved: true;
+  hash: string;
+}
+
+/** One editable file in the project, as the listing reports it. FLAT — the
+ *  server walks the tree and answers posix paths, and the shape of the tree is
+ *  the chrome's problem, which is right: nesting is a way of DRAWING this list,
+ *  not a fact about the project. */
+export interface ProjectFile {
+  path: string;
+  size: number;
+  /** Set when the file is a build product the studio itself emits. The listing
+   *  decides this by directory alone, so a marker-only generated file reads as
+   *  ordinary here and refuses on the way in — which is why the buffer trusts
+   *  `SourceFile.generated` and not this. */
+  generated?: { lane: string; by: string; id: string; docName?: string };
+}
+
+/** `truncated` means the walk hit the server's cap and stopped. Said out loud
+ *  in the tree rather than swallowed: a file tree that silently omits files is
+ *  worse than no file tree. */
+export interface ProjectFiles {
+  files: ProjectFile[];
+  truncated?: boolean;
+}
+
+/** Every editable file in the project. The route has always existed — the
+ *  motion chrome's drawer used it — and this is the shot chrome finally asking.
+ *  Editable extensions only, no dotfiles, no `node_modules`, no `.studio`. */
+export function listFiles(): Promise<ProjectFiles> {
+  return request("/api/files");
+}
+
+export function readFile(rel: string): Promise<SourceFile> {
+  return request(`/api/files/${encodeURIComponent(rel)}`);
+}
+
+/** `baseHash` makes the write conflict-checked: a 409 lands in `ApiError.status`
+ *  rather than overwriting whatever arrived under the buffer. */
+export function writeFile(
+  rel: string,
+  content: string,
+  baseHash?: string,
+): Promise<SourceFileSaved> {
+  return request(`/api/files/${encodeURIComponent(rel)}`, {
+    method: "PUT",
+    body: JSON.stringify(baseHash !== undefined ? { content, baseHash } : { content }),
+  });
+}
+
+/** Create a new file. A path that exists answers 409 rather than overwriting. */
+export function createFile(rel: string, content: string): Promise<SourceFileSaved> {
+  return request(`/api/files/${encodeURIComponent(rel)}`, { method: "POST", body: JSON.stringify({ content }) });
+}
+
+/** Typecheck a file. `content` checks an UNSAVED buffer instead of disk, which
+ *  is what puts a red gutter under code the author has not committed yet.
+ *  Hosted, the code host's extractor answers it, in the same shape. */
+export function fileDiagnostics(
+  rel: string,
+  content?: string,
+): Promise<{ diagnostics: CodeDiagnostic[] }> {
+  const host = dailiesHost();
+  if (host !== undefined) return viaHost(() => host.diagnostics(rel, content));
+  return request("/api/diagnostics", {
+    method: "POST",
+    body: JSON.stringify(content !== undefined ? { path: rel, content } : { path: rel }),
+  });
+}
+
 // ---- the asset store ---------------------------------------------------------
 
-/** What `POST /api/assets` answers with. `path` is the BARE content-addressed
- *  filename; identical bytes always land on it, so a re-import is idempotent. */
+/** What the Project-scoped asset POST answers with. `path` is the BARE
+ * content-addressed filename; identical bytes always land on it, so a
+ * re-import is idempotent. */
 export interface UploadedAsset {
   path: string;
   hash: string;
   /** Absent for an extension the store does not recognise. */
   kind?: string;
+  /** Canonical bytes after server-side conversion (not the upload's size). */
+  size?: number;
+  usedBytes?: number;
+  remainingBytes?: number;
+  /** A video's measurement, which the chrome writes onto the asset row
+   *  (`mergeAssetMedia`) as `dailies media import` does, so one upload
+   *  registers the same row on either host. Locally the route's own answer
+   *  (its probe of the staged bytes, on a re-upload too); hosted, the
+   *  browser's probe (`uploadAsset` below), since the Worker measures
+   *  nothing. */
+  media?: MediaProbe;
+}
+
+export interface ProjectAssetUsage {
+  limitBytes: number;
+  usedBytes: number;
+  reservedBytes: number;
+  remainingBytes: number;
+  assets: ReadonlyArray<{
+    path: string;
+    hash: string;
+    kind?: string;
+    size: number;
+  }>;
+  /** Registry rows whose file is gone from local storage (the local server's
+   *  `ProjectAssetQuota`). Absent hosted, where stored media cannot go missing. */
+  missing?: ReadonlyArray<{ id: string; path: string }>;
 }
 
 /**
- * Upload one file into the shared asset store (the F2-C route every chrome
- * uses; the shot lane is served by the same server, so it is the same route).
+ * Upload one file into the open Project's quota-accounted asset store.
  *
- * The filename rides a URI-ENCODED header because HTTP headers are latin-1 and
- * user filenames are not, and the BODY is the raw bytes — this is the one write
- * in this module that is not JSON, so it overrides `request`'s content-type
- * rather than letting it claim the bytes are JSON.
+ * HOSTED, the page does the local route's media work around the POST (browser
+ * host media/host.ts): audio is canonicalised first (the Worker stores bytes
+ * as they arrive and refuses any other audio), and after it a video is
+ * measured and every upload's sidecars are derived. Locally the route does
+ * all of that itself.
+ *
+ * `remainingBytes` is the meter's number (`assetUsage`), when the caller has
+ * one. Hosted, a file over it is refused before any byte is sent, as the
+ * Worker reserves the bytes before it dedupes; the server's check still
+ * stands behind this one.
+ */
+export async function uploadAsset(project: string, file: File, remainingBytes?: number): Promise<UploadedAsset> {
+  const host = dailiesHost();
+  if (host === undefined) {
+    // Locally only the whole allowance: the route answers bytes the Project
+    // already holds before it checks the space left, and audio is judged as
+    // the WAV only the route makes.
+    if (!file.type.startsWith("audio/")) await refuseOverSpace(project, file, undefined);
+    return postAsset(project, file);
+  }
+  const media = host.media;
+  const prepared = await media.prepareUpload(file);
+  // Hosted, the browser made the WAV, so audio is judged as it will be stored.
+  await refuseOverSpace(project, prepared, remainingBytes, prepared === file ? undefined : "wav");
+  const uploaded = await postAsset(project, prepared, await sha256Hex(prepared));
+  const probe = await media.uploaded(uploaded.path, prepared);
+  return probe === null ? uploaded : { ...uploaded, media: probe };
+}
+
+/**
+ * The POST itself. The filename rides a URI-ENCODED header because HTTP
+ * headers are latin-1 and user filenames are not, and the BODY is the raw
+ * bytes — this is the one write in this module that is not JSON, so it
+ * overrides `request`'s content-type rather than letting it claim the bytes
+ * are JSON.
  */
-export function uploadAsset(file: File): Promise<UploadedAsset> {
-  return request("/api/assets", {
+function postAsset(project: string, file: File, sha256?: string): Promise<UploadedAsset> {
+  return request(`/api/shots/${encodeURIComponent(project)}/assets`, {
     method: "POST",
     body: file,
     headers: {
       "content-type": "application/octet-stream",
       "x-studio-filename": encodeURIComponent(file.name),
+      ...(sha256 === undefined ? {} : { [CONTENT_SHA256_HEADER]: sha256 }),
     },
   });
 }
 
+/**
+ * Refuse a file the Project cannot hold before streaming a doomed body, in the
+ * server's own words (`quotaMessage`). Over the whole allowance needs no
+ * number from anyone. Over `hint` asks the server first: the meter can be
+ * stale (a save may have freed space since), and a refusal is only as good as
+ * the number it quotes. If that read fails, the server judges the upload.
+ */
+async function refuseOverSpace(
+  project: string,
+  file: File,
+  hint: number | undefined,
+  storedAs?: "wav",
+): Promise<void> {
+  const wav = storedAs === undefined ? {} : { storedAs };
+  if (file.size > PROJECT_MEDIA_LIMIT_BYTES) {
+    const whole = `This file is ${formatBytes(file.size)}, over the ${formatBytes(PROJECT_MEDIA_LIMIT_BYTES)} media allowance of a whole Project.`;
+    throw new ApiError(
+      413,
+      storedAs === undefined ? whole : `Audio is stored uncompressed (48 kHz WAV). ${whole}`,
+      undefined,
+      { code: "project_quota_exceeded", limitBytes: PROJECT_MEDIA_LIMIT_BYTES, requestedBytes: file.size, ...wav },
+    );
+  }
+  if (hint === undefined || file.size <= hint) return;
+  let usage: ProjectAssetUsage;
+  try {
+    usage = await projectAssetUsage(project);
+  } catch {
+    return;
+  }
+  if (typeof usage.remainingBytes !== "number" || file.size <= usage.remainingBytes) return;
+  const details = {
+    code: "project_quota_exceeded",
+    limitBytes: usage.limitBytes,
+    usedBytes: usage.usedBytes,
+    requestedBytes: file.size,
+    remainingBytes: usage.remainingBytes,
+    ...wav,
+  };
+  throw new ApiError(413, quotaMessage(details), undefined, details);
+}
+
+/**
+ * What a hosted upload says its bytes hash to (the Worker's
+ * `WORKER_HEADERS.contentSha256`): the Worker hashes the body anyway and
+ * refuses a mismatch, and skips storing bytes the workspace already holds
+ * (a re-upload, the same file in another Project). Hosted only; the local
+ * route stores every upload.
+ */
+export const CONTENT_SHA256_HEADER = "x-studio-content-sha256";
+
+async function sha256Hex(file: Blob): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", await file.arrayBuffer()));
+  return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** Server-authoritative Project usage, including bytes reserved by concurrent
+ * uploads. Kept beside upload because both are one quota surface. */
+export function projectAssetUsage(project: string): Promise<ProjectAssetUsage> {
+  return request(`/api/shots/${encodeURIComponent(project)}/assets`);
+}
+
+/** The server sends the ceiling it enforced. Say THAT number back, rather than
+ * a literal that can drift away from the rule the refusal came from. */
+function quotaMessage(details: Readonly<Record<string, unknown>>): string {
+  const remaining = typeof details["remainingBytes"] === "number" ? details["remainingBytes"] : 0;
+  const requested = typeof details["requestedBytes"] === "number" ? details["requestedBytes"] : null;
+  const limit = formatBytes(
+    typeof details["limitBytes"] === "number" ? details["limitBytes"] : PROJECT_MEDIA_LIMIT_BYTES,
+  );
+  const left = formatBytes(remaining);
+  const message =
+    requested === null
+      ? `This Project has ${left} of its ${limit} media allowance left.`
+      : `This file needs ${formatBytes(requested)}, but this Project has ${left} of its ${limit} media allowance left.`;
+  // The server judged the stored WAV, not the file the user picked, so say why
+  // the number is bigger than their MP3.
+  return details["storedAs"] === "wav" ? `Audio is stored uncompressed (48 kHz WAV). ${message}` : message;
+}
+
+/** A byte count as an author reads it. The one copy: the quota refusal, the
+ *  usage meter and every file row say the same number the same way. */
+export function formatBytes(bytes: number): string {
+  const safe = Math.max(0, bytes);
+  if (safe >= 1_000_000) return `${(safe / 1_000_000).toFixed(safe >= 10_000_000 ? 0 : 1)} MB`;
+  if (safe >= 1_000) return `${Math.round(safe / 1_000)} KB`;
+  return `${safe} B`;
+}
+
 /**
  * The stored bytes of an asset.
  *
@@ -210,6 +1014,293 @@ export function uploadAsset(file: File): Promise<UploadedAsset> {
  * and the stored one's can differ by a partial frame, and the clip has to be
  * timed against what will actually be mixed.
  */
+/** One workspace font (store `WorkspaceFont`): uploaded once to the
+ *  workspace, offered in every Project's font list. Its id is the stored path
+ *  a Project copy of the same bytes gets, so a copy is found by
+ *  `asset.path === id`. The optional keys are what the file's name table
+ *  says, and are absent when it could not be read (a file uploaded before
+ *  migration 0033 keeps its file-name family and nothing else). */
+export interface WorkspaceFont {
+  id: string;
+  /** The name table's family (name ID 16, then 1), else the file stem. */
+  family: string;
+  filename: string;
+  format: string;
+  size: number;
+  /** OS/2 usWeightClass, 1 to 1000. */
+  weight?: number;
+  italic?: boolean;
+  /** A variable font's `wght` axis: [min, default, max]. */
+  wghtAxis?: [number, number, number];
+}
+
+/** `GET /api/fonts` on both hosts. `canManage` is whether this person may
+ *  upload and remove (`fonts.manage`; always locally). */
+export interface WorkspaceFontList {
+  fonts: WorkspaceFont[];
+  canManage: boolean;
+  maxFonts: number;
+  limitBytes: number;
+}
+
+export function listWorkspaceFonts(): Promise<WorkspaceFontList> {
+  return request("/api/fonts");
+}
+
+export const workspaceFontUrl = (id: string): string => `/studio/fonts/${encodeURIComponent(id)}`;
+
+/**
+ * Add a font file to the workspace's fonts (`POST /studio/fonts`, the font
+ * picker's upload, on both hosts). `created` is false when the workspace
+ * already held these bytes (a 200 answering that row). A refusal is an
+ * `ApiError` carrying the server's message and `code` as they came
+ * (`font_too_large`, `fonts_full`, `forbidden`, `rate_limited`...), with the
+ * whole body in `details` (`limitBytes`, `maxFonts`, `retryAfter`).
+ */
+export async function uploadWorkspaceFont(file: File): Promise<{ font: WorkspaceFont; created: boolean }> {
+  let status = 0;
+  const body = await request<{ font: WorkspaceFont | null }>(
+    "/studio/fonts",
+    {
+      method: "POST",
+      body: file,
+      headers: { "content-type": "application/octet-stream", "x-studio-filename": encodeURIComponent(file.name) },
+    },
+    false,
+    (s) => {
+      status = s;
+    },
+  );
+  if (body.font === null) throw new ApiError(status, `${file.name} was stored, but the workspace could not read it back.`);
+  return { font: body.font, created: status === 201 };
+}
+
+/** How a font download reports: bytes read so far, and the whole size when
+ *  the response says it (`Content-Length` on an unencoded body), else null. */
+export interface FontDownloadOptions {
+  signal?: AbortSignal;
+  onProgress?: (loaded: number, total: number | null) => void;
+}
+
+/** A response body read whole, reporting as it streams. */
+async function readFontBody(res: Response, opts: FontDownloadOptions): Promise<Blob> {
+  const reader = opts.onProgress === undefined ? undefined : res.body?.getReader();
+  if (reader === undefined) return res.blob();
+  const length = Number(res.headers.get("content-length"));
+  const total = res.headers.has("content-encoding") || !(length > 0) ? null : length;
+  const chunks: Uint8Array[] = [];
+  let loaded = 0;
+  opts.onProgress?.(0, total);
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    loaded += value.byteLength;
+    opts.onProgress?.(loaded, total);
+  }
+  return new Blob(chunks);
+}
+
+/** Who a saved video's page opens for (worker videos.ts). */
+export type VideoVisibility = "private" | "workspace" | "link";
+
+export interface SaveVideoMeta {
+  /** The Project's name (the store's `name`), whose export this is. */
+  project: string;
+  title: string;
+  filename: string;
+  visibility: VideoVisibility;
+  /** The "Sound credits" block the export owes (v49), shown on its page. */
+  credits?: string;
+  durationMs: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Save an export to the workspace's Videos, hosted only, and answer its id
+ * and page. In parts, at the size the server names: a video can be larger
+ * than one request may carry.
+ */
+export async function saveVideo(blob: Blob, meta: SaveVideoMeta): Promise<{ id: string; url: string }> {
+  const started = await request<{ id: string; partBytes: number; parts: number }>("/studio/videos", {
+    method: "POST",
+    body: JSON.stringify({ ...meta, size: blob.size }),
+  });
+  const base = `/studio/videos/${encodeURIComponent(started.id)}`;
+  const parts: Array<{ partNumber: number; etag: string }> = [];
+  for (let n = 1; n <= started.parts; n++) {
+    parts.push(
+      await request(`${base}/parts/${n}`, {
+        method: "PUT",
+        body: blob.slice((n - 1) * started.partBytes, n * started.partBytes),
+        headers: { "content-type": "application/octet-stream" },
+      }),
+    );
+  }
+  const done = await request<{ url: string }>(`${base}/complete`, { method: "POST", body: JSON.stringify({ parts }) });
+  return { id: started.id, url: done.url };
+}
+
+/** The font's bytes as a File named like the upload, ready for `uploadAsset`. */
+export async function fetchWorkspaceFont(font: WorkspaceFont, opts: FontDownloadOptions = {}): Promise<File> {
+  const url = workspaceFontUrl(font.id);
+  const res = await fetch(url, opts.signal === undefined ? undefined : { signal: opts.signal });
+  if (!res.ok) throw new ApiError(res.status, `${font.family} is no longer in this workspace's fonts.`);
+  return new File([await readFontBody(res, opts)], font.filename, { type: res.headers.get("content-type") ?? "" });
+}
+
+/** A font file from a url (a Google font on jsDelivr, the chrome's bundled
+ *  Inter) as a File named `name`, ready for `uploadAsset`. */
+export async function fetchFontFile(url: string, name: string, opts: FontDownloadOptions = {}): Promise<File> {
+  const res = await fetch(url, opts.signal === undefined ? undefined : { signal: opts.signal });
+  if (!res.ok) throw new ApiError(res.status, `${name} could not be fetched (${res.status}).`);
+  return new File([await readFontBody(res, opts)], name, { type: "font/woff2" });
+}
+
+// ---- the generate drawer (Sound mode) ----------------------------------------
+//
+// The wire of `/studio/audio/generate`, on both hosts. The shapes are
+// `GenerationStatus` and `GenerationTake` in `@dailies-studio/store`
+// (audioGeneration.ts), restated because the chrome does not depend on the
+// store package.
+
+export type GenerationKind = "sfx" | "music" | "voice";
+
+export interface GenerationTake {
+  id: string;
+  kind: GenerationKind;
+  prompt: string;
+  seconds: number | null;
+  voice: string | null;
+  provider: string;
+  model: string;
+  createdAt: number;
+  name: string;
+  /** Where the bytes are served, same-origin. */
+  url: string;
+  /** Set when the take is already a stored asset (local). */
+  path?: string;
+  hash?: string;
+  /** In the sound history past its waiting day. */
+  kept?: boolean;
+  /** Music composed to a Project's sections: it lines up only from frame 0. */
+  scored?: boolean;
+}
+
+/** One page of the sound history, newest first (store `GenerationHistory`).
+ *  A page can be short, even empty, and still have a `next`. */
+export interface GenerationHistory {
+  takes: GenerationTake[];
+  next: string | null;
+}
+
+export interface GenerationStatus {
+  host: "local" | "hosted";
+  kinds: Record<GenerationKind, { ok: boolean; reason?: string }>;
+  voices: ReadonlyArray<{ id: string; name: string; description: string }>;
+  caps: {
+    promptMaxChars: number;
+    sfx: { minSeconds: number; maxSeconds: number; defaultSeconds: number };
+    music: { minSeconds: number; maxSeconds: number; defaultSeconds: number };
+    voice: { maxChars: number };
+  };
+  /** Hosted, with no ElevenLabs key the workspace can use: "add" when this
+   *  member may add one (Settings, AI keys), "ask" when an Owner or Admin must. */
+  needsKey?: "add" | "ask";
+  recent: GenerationTake[];
+}
+
+export interface GenerationBody {
+  project: string;
+  kind: GenerationKind;
+  prompt: string;
+  seconds?: number;
+  voice?: string;
+  instrumental?: boolean;
+  loop?: boolean;
+  /** Music scored to the Project: its sections, in order (`scoreSectionsOf`). */
+  sections?: Array<{ name: string; durationMs: number }>;
+}
+
+export const AUDIO_GENERATE_ROUTE = "/studio/audio/generate";
+
+export function generationStatus(project: string): Promise<GenerationStatus> {
+  return request(`${AUDIO_GENERATE_ROUTE}?project=${encodeURIComponent(project)}`);
+}
+
+export function generateAudioTake(body: GenerationBody): Promise<{ take: GenerationTake }> {
+  return request(AUDIO_GENERATE_ROUTE, { method: "POST", body: JSON.stringify(body) });
+}
+
+/** The sound history: every take this member may see that is kept or still
+ *  in its day, newest first; `before` asks for the page after a `next`. */
+export function generationHistory(before?: string): Promise<GenerationHistory> {
+  return request(`${AUDIO_GENERATE_ROUTE}/history${before === undefined ? "" : `?before=${encodeURIComponent(before)}`}`);
+}
+
+/** Keep a take in the history past its day: it went into `project` (by its
+ *  storage name), which lets a member keep another's take they added. */
+export function keepGeneration(id: string, project?: string): Promise<{ kept: boolean }> {
+  return request(`${AUDIO_GENERATE_ROUTE}/${encodeURIComponent(id)}/keep`, {
+    method: "POST",
+    body: JSON.stringify(project === undefined ? {} : { project }),
+  });
+}
+
+/** Delete a take from the history. Locally its file stays, for any Project
+ *  that uses it; hosted, its waiting-room bytes go. */
+export function deleteGeneration(id: string): Promise<{ deleted: boolean }> {
+  return request(`${AUDIO_GENERATE_ROUTE}/${encodeURIComponent(id)}`, { method: "DELETE" });
+}
+
+/** A hosted take's bytes as a File, ready for `importAudio`. */
+export async function fetchGenerationFile(take: GenerationTake): Promise<File> {
+  const res = await fetch(take.url);
+  if (!res.ok) throw new ApiError(res.status, "That take has expired. Generate it again.");
+  return new File([await res.blob()], `${take.name}.mp3`, { type: res.headers.get("content-type") ?? "audio/mpeg" });
+}
+
+// ---- stock sounds (the Library's Stock sounds) -------------------------------
+//
+// The wire of `/api/openverse`, on both hosts. `OpenverseTake` is the store's
+// (openverse.ts), restated because the chrome does not depend on the store
+// package. The search itself never comes here: the Library searches Openverse
+// from this browser (`panels/library/stockSearch.ts`).
+
+export const OPENVERSE_ROUTE = "/api/openverse";
+
+export interface OpenverseTake {
+  /** The provenance to record: the host's own read of the row. */
+  source: OpenverseSource3D;
+  /** Same-origin: where the file is read. */
+  file: string;
+  filename: string;
+  durationMs: number;
+}
+
+/** Whether this host can add a stock sound: locally always, hosted once the
+ *  deployment has a registered Openverse app. */
+export function openverseStatus(): Promise<{ imports: boolean }> {
+  return request(OPENVERSE_ROUTE);
+}
+
+/** The host reads the row itself and answers the provenance to record and
+ *  where to read the file. */
+export function openverseTake(input: { id: string; project: string }): Promise<OpenverseTake> {
+  return request(`${OPENVERSE_ROUTE}/take`, { method: "POST", body: JSON.stringify(input) });
+}
+
+/** A take's bytes as a File, ready for the audio upload lane. */
+export async function fetchOpenverseFile(take: OpenverseTake): Promise<File> {
+  const res = await fetch(take.file);
+  if (!res.ok) {
+    const body = (await res.json().catch(() => null)) as { error?: unknown } | null;
+    throw new ApiError(res.status, typeof body?.error === "string" ? body.error : `The sound could not be fetched (${res.status}).`);
+  }
+  return new File([await res.blob()], take.filename, { type: "audio/mpeg" });
+}
+
 export async function fetchAssetBytes(path: string): Promise<ArrayBuffer> {
   const url = `/studio/assets/${encodeURIComponent(path)}`;
   const res = await fetch(url);
@@ -227,6 +1318,16 @@ export interface RenderJob {
   total: number;
   out?: string;
   error?: string;
+  /** Every `warning:` line the render emitted. Optional on the wire: a server
+   *  older than this field simply omits it, and the dialog renders nothing. */
+  warnings?: string[];
+  /** A failed render's last output lines, `[page]` errors included. */
+  log?: string[];
+  /** A failed render's forensics folder, when one was written. */
+  diagnostics?: string;
+  /** What the render is doing before its first frame, such as downloading
+   *  the browser renderer. Cleared once frames start. */
+  note?: string;
   elapsedMs: number;
 }
 
@@ -235,6 +1336,9 @@ export interface RenderRequest {
   quality: ExportQualityId;
   /** Absent = the whole timeline. */
   sceneId?: string;
+  /** Master frames [start, end) of the whole timeline, for the work area.
+   *  Never sent with `sceneId`. */
+  frameRange?: { start: number; end: number };
   /** `false` renders a SILENT file even though the document has clips. Absent
    *  = the server's default, which is to mux whatever `doc.audio` carries. */
   audio?: boolean;
@@ -270,6 +1374,414 @@ export function cancelRender(name: string): Promise<{ cancelled: boolean }> {
   return request(`/api/shots/${encodeURIComponent(name)}/render`, { method: "DELETE" });
 }
 
+// ---- comments (packages/store/src/commentRoutes.ts) ------------------------
+
+/** A pin on a storyboard Frame (a still). */
+export interface CommentFrameAnchor {
+  kind: "frame";
+  /** The Shot the Frame sat in when the thread was made. */
+  sceneId: string;
+  stillId: string;
+  /** 0..1 across the picture, left to right. */
+  u: number;
+  /** 0..1 down the picture, top to bottom. */
+  v: number;
+  layerId: string | null;
+  frame: number;
+  frameLabel: string | null;
+}
+
+/** A thread on a board card (migration 0029): a planned shot (`partId`) or
+ *  a reference (`referenceId`), exactly one of the two. `sceneId` is the Shot
+ *  the card pointed at when written, or null. `stillId` is never set: it is
+ *  here so "does this thread sit on still X" reads on any anchor. */
+export interface CommentCardAnchor {
+  kind: "card";
+  partId: string | null;
+  referenceId: string | null;
+  sceneId: string | null;
+  stillId?: never;
+}
+
+/** A thread on a spot in the Studio (migration 0029): a Shot at a Shot-local
+ *  `frame`, the layer under the click (or none), the point as 0..1 of the
+ *  camera frame. `stillId` as on a card. */
+export interface CommentStudioAnchor {
+  kind: "studio";
+  sceneId: string;
+  frame: number;
+  layerId: string | null;
+  u: number;
+  v: number;
+  stillId?: never;
+}
+
+/** Where a thread is pinned, always read back with its `kind`. */
+export type CommentAnchor = CommentFrameAnchor | CommentCardAnchor | CommentStudioAnchor;
+export type CommentAnchorKind = CommentAnchor["kind"];
+
+/** One thread linked to another (0029): a board thread and a Studio thread,
+ *  seen from either side. `kind` is the other thread's anchor kind. */
+export interface CommentLink {
+  threadId: string;
+  kind: CommentAnchorKind;
+}
+
+export interface CommentPerson {
+  id: string;
+  login: string;
+  displayName: string | null;
+  avatarKey: string | null;
+}
+
+export interface CommentMessage {
+  id: string;
+  threadId: string;
+  authorId: string;
+  authorLabel: string;
+  authorAvatarKey: string | null;
+  /** Mentions are inline `<@usr-...>` tokens. Empty when deleted. */
+  body: string;
+  viaAgent: boolean;
+  createdAt: number;
+  editedAt: number | null;
+  deleted: boolean;
+  can: { edit: boolean; delete: boolean };
+}
+
+export interface CommentThread {
+  id: string;
+  projectId: string;
+  anchor: CommentAnchor;
+  /** The threads linked to this one, in the other place. */
+  links: CommentLink[];
+  status: "open" | "resolved";
+  createdBy: string;
+  assignee: CommentPerson | null;
+  resolvedBy: string | null;
+  resolvedAt: number | null;
+  messageCount: number;
+  snapshotKey: string | null;
+  createdAt: number;
+  updatedAt: number;
+  lastMessageAt: number;
+  head: CommentMessage | null;
+  viewer: { lastReadAt: number | null; following: boolean; unread: boolean };
+  /** Whether the anchor is there, judged against the SAVED document. */
+  orphan: CommentOrphan;
+  can: { reply: boolean; resolve: boolean; assign: boolean; delete: boolean; snapshot: boolean };
+  /** Oldest first; only on a single-thread read. */
+  messages?: CommentMessage[];
+}
+
+/** Null while the anchor is there: a Frame pin's Frame, a card's part or
+ *  reference, a Studio thread's Shot and layer. */
+export type CommentOrphan = "frame-removed" | "card-removed" | "layer-removed" | "shot-removed" | null;
+
+export interface MentionablePerson extends CommentPerson {
+  guest: boolean;
+}
+
+export interface Mentionable {
+  /** People who can open the Project, with their role on it. */
+  people: (MentionablePerson & { role: string })[];
+  /** Members who cannot open it yet: only for a caller who may share it. */
+  others: MentionablePerson[];
+  canShare: boolean;
+}
+
+export interface InboxItem {
+  id: number;
+  kind: "mention" | "reply" | "assigned" | "resolved" | "reopened";
+  projectId: string;
+  /** The Project's store name, the editor's `?shot=`; null when unknown. */
+  projectName: string | null;
+  projectTitle: string | null;
+  threadId: string;
+  /** '' for a card written on no Shot. */
+  sceneId: string;
+  /** '' for a card or Studio thread. */
+  stillId: string;
+  frameLabel: string | null;
+  /** Where the thread sits, so an item opens the right place. */
+  anchorKind: CommentAnchorKind;
+  messageId: string | null;
+  excerpt: string;
+  actorId: string;
+  actorLabel: string;
+  viaAgent: boolean;
+  createdAt: number;
+  readAt: number | null;
+}
+
+export type ThreadFilter = {
+  status?: "open" | "resolved";
+  filter?: "mine" | "mentions";
+  cursor?: string;
+  kind?: CommentAnchorKind;
+  partId?: string;
+  referenceId?: string;
+  sceneId?: string;
+};
+
+const query = (params: Record<string, string | number | undefined>): string =>
+  new URLSearchParams(
+    Object.entries(params).flatMap(([key, value]) => (value === undefined ? [] : [[key, String(value)]])),
+  ).toString();
+
+const threadPath = (id: string): string => `/api/comments/${encodeURIComponent(id)}`;
+
+export function listThreads(
+  projectId: string,
+  filter: ThreadFilter = {},
+): Promise<{ threads: CommentThread[]; nextCursor?: string }> {
+  return request(`/api/comments?${query({ project: projectId, limit: 50, ...filter })}`);
+}
+
+export async function getThread(id: string): Promise<CommentThread> {
+  return (await request<{ thread: CommentThread }>(threadPath(id))).thread;
+}
+
+export async function createThread(projectId: string, anchor: CommentAnchor, body: string): Promise<CommentThread> {
+  const res = await request<{ thread: CommentThread }>("/api/comments", {
+    method: "POST",
+    body: JSON.stringify({ projectId, anchor, body }),
+  });
+  return res.thread;
+}
+
+export function replyThread(id: string, body: string): Promise<{ message: CommentMessage; thread: CommentThread }> {
+  return request(`${threadPath(id)}/messages`, { method: "POST", body: JSON.stringify({ body }) });
+}
+
+export async function patchThread(
+  id: string,
+  patch: { status?: "open" | "resolved"; assigneeId?: string | null },
+): Promise<CommentThread> {
+  return (await request<{ thread: CommentThread }>(threadPath(id), { method: "PATCH", body: JSON.stringify(patch) })).thread;
+}
+
+/** Link a board thread and a Studio thread of one Project. Idempotent.
+ *  Answers this thread with its links. */
+export async function linkThread(id: string, otherId: string): Promise<CommentThread> {
+  const res = await request<{ thread: CommentThread }>(`${threadPath(id)}/links`, {
+    method: "POST",
+    body: JSON.stringify({ threadId: otherId }),
+  });
+  return res.thread;
+}
+
+/** Undo `linkThread`. Idempotent. Answers this thread with its links. */
+export async function unlinkThread(id: string, otherId: string): Promise<CommentThread> {
+  const res = await request<{ thread: CommentThread }>(`${threadPath(id)}/links/${encodeURIComponent(otherId)}`, {
+    method: "DELETE",
+  });
+  return res.thread;
+}
+
+export async function deleteThread(id: string): Promise<void> {
+  await request(threadPath(id), { method: "DELETE" });
+}
+
+export async function editMessage(threadId: string, messageId: string, body: string): Promise<CommentMessage | null> {
+  const res = await request<{ message: CommentMessage | null }>(
+    `${threadPath(threadId)}/messages/${encodeURIComponent(messageId)}`,
+    { method: "PATCH", body: JSON.stringify({ body }) },
+  );
+  return res.message;
+}
+
+export async function deleteMessage(threadId: string, messageId: string): Promise<void> {
+  await request(`${threadPath(threadId)}/messages/${encodeURIComponent(messageId)}`, { method: "DELETE" });
+}
+
+export async function markThreadRead(id: string): Promise<void> {
+  await request(`${threadPath(id)}/read`, { method: "POST" });
+}
+
+export function mentionable(projectId: string, q: string): Promise<Mentionable> {
+  return request(`/api/comments/mentionable?${query({ project: projectId, q: q === "" ? undefined : q, limit: 8 })}`);
+}
+
+/** One person who can open a Project (the workspace's people route). */
+export interface ProjectPerson {
+  userId: string;
+  login: string;
+  name: string;
+  avatarUrl: string | null;
+  isYou: boolean;
+  projectRole: string;
+  guest: boolean;
+}
+
+/** Who can open a Project: names and avatars for the presence faces. Hosted
+ *  only. */
+export function projectPeople(name: string): Promise<{ people: ProjectPerson[] }> {
+  return request(`/api/projects/shot/${encodeURIComponent(name)}/people`);
+}
+
+export function inbox(unreadOnly: boolean): Promise<{ items: InboxItem[]; nextCursor?: string; unread: number }> {
+  return request(`/api/inbox?${query({ unread: unreadOnly ? 1 : undefined, limit: 30 })}`);
+}
+
+export async function markInboxRead(ids?: readonly number[]): Promise<void> {
+  await request("/api/inbox/read", { method: "POST", body: JSON.stringify(ids === undefined ? {} : { ids }) });
+}
+
+/** Keep the picture the author commented on (webp, png or jpeg, at most
+ *  256 KB): its author, once. A removed Frame's thread shows it. */
+export async function putSnapshot(id: string, picture: Blob): Promise<void> {
+  await request(`${threadPath(id)}/snapshot`, {
+    method: "PUT",
+    body: picture,
+    headers: { "content-type": picture.type },
+  });
+}
+
+/** The picture a thread keeps, for an `<img src>`. */
+export const snapshotUrl = (id: string): string => `${threadPath(id)}/snapshot`;
+
+/** Ask the Project's admins for Editor. Always 202, so nothing leaks about
+ *  whether a request was filed (packages/worker/src/requests.ts). */
+export async function requestEditAccess(projectId: string): Promise<void> {
+  await request("/api/workspace/requests", { method: "POST", body: JSON.stringify({ projectId, role: "editor" }) });
+}
+
+// ---- the workspace component store (packages/store/src/workspaceComponents.ts) --
+//
+// Restated here, as the comment shapes above are: the chrome cannot import the
+// store package. Keep these in step with that file.
+
+/** Where a component lives: a definition in a Project, or a code module. */
+export type WorkspaceComponentHome = { projectId: string; def: string } | { component: string };
+
+export interface WorkspaceComponent {
+  id: string;
+  kind: "studio" | "code";
+  home: WorkspaceComponentHome;
+  name: string;
+  slug: string;
+  /** The latest version's number and contentHash. */
+  version: number;
+  contentHash: string;
+  createdAt: number;
+  updatedAt: number;
+  createdBy: string;
+  /** A Studio-made component's home Project name, as the list answers it. */
+  homeName?: string | null;
+  /** In the workspace's library (`setWorkspaceComponentLibrary`): every
+   *  Project lists it under Your library. */
+  library?: true;
+}
+
+/** A code file a live Project lists as made for it or uses, by module path
+ *  (`src/Gem.tsx`). `projectId` is null for a Project the caller may not
+ *  view: the file still belongs to some Project, just not one it may name. */
+export interface ComponentFileHome {
+  path: string;
+  projectId: string | null;
+}
+
+/** One version as the History list shows it. */
+export interface WorkspaceComponentVersionInfo {
+  version: number;
+  contentHash: string;
+  name: string;
+  /** The exposed prop keys (studio) or the contract keys (code), in order. */
+  propKeys: string[];
+  mediaHashes: string[];
+  createdAt: number;
+  createdBy: string;
+}
+
+export interface StudioComponentPayload {
+  kind: "studio";
+  def: ComponentDef3D;
+  nested: Record<string, ComponentDef3D>;
+  assets: Record<string, ShotAsset>;
+  materials: Record<string, MaterialGraph3D>;
+}
+
+export interface CodeComponentPayload {
+  kind: "code";
+  files: { path: string; content: string }[];
+  contract: unknown;
+}
+
+/** A version with its payload: the view and restore read. */
+export interface WorkspaceComponentVersion extends WorkspaceComponentVersionInfo {
+  payload: StudioComponentPayload | CodeComponentPayload;
+}
+
+/** One row of the usage index. */
+export type IndexedComponentUse = ComponentUse & { projectId: string; projectName: string };
+
+export interface RecordedComponentVersion {
+  component: WorkspaceComponent;
+  version: WorkspaceComponentVersionInfo;
+  created: boolean;
+}
+
+const WORKSPACE_COMPONENTS = "/api/workspace-components";
+const workspaceComponentPath = (id: string): string => `${WORKSPACE_COMPONENTS}/${encodeURIComponent(id)}`;
+
+/** Every workspace component the caller may see, and which Project each code
+ *  file belongs to (`homes`), the index Your library reads. */
+export function listWorkspaceComponents(): Promise<{ components: WorkspaceComponent[]; homes: ComponentFileHome[] }> {
+  return request(WORKSPACE_COMPONENTS);
+}
+
+/** Add a recorded component to the workspace's library, or take it out.
+ *  Answers the row as it now stands. */
+export async function setWorkspaceComponentLibrary(id: string, library: boolean): Promise<WorkspaceComponent> {
+  return (
+    await request<{ component: WorkspaceComponent }>(`${workspaceComponentPath(id)}/library`, {
+      method: "PUT",
+      body: JSON.stringify({ library }),
+    })
+  ).component;
+}
+
+/** Record a version from the saved document (studio) or the registry (code).
+ *  The same content twice writes nothing (`created: false`). */
+export function recordWorkspaceComponent(
+  body: { kind: "studio"; projectId: string; def: string } | { kind: "code"; component: string },
+): Promise<RecordedComponentVersion> {
+  return request(WORKSPACE_COMPONENTS, { method: "POST", body: JSON.stringify(body) });
+}
+
+/** Newest first. */
+export async function workspaceComponentVersions(id: string): Promise<WorkspaceComponentVersionInfo[]> {
+  return (await request<{ versions: WorkspaceComponentVersionInfo[] }>(`${workspaceComponentPath(id)}/versions`)).versions;
+}
+
+export async function workspaceComponentVersion(id: string, version: number): Promise<WorkspaceComponentVersion> {
+  return (await request<{ version: WorkspaceComponentVersion }>(`${workspaceComponentPath(id)}/versions/${version}`)).version;
+}
+
+export async function workspaceComponentUses(id: string): Promise<IndexedComponentUse[]> {
+  return (await request<{ uses: IndexedComponentUse[] }>(`${workspaceComponentPath(id)}/uses`)).uses;
+}
+
+let buildProbe = 0;
+
+/**
+ * Why a code component's module does not build now, or null when it does.
+ * Hosted, the code host's compile answers (after a sync). Locally, the dev
+ * server's transform: asking for the module is what compiles it, and a module
+ * that fails answers non-2xx with no usable body (Vite's middleware mode hands
+ * the error on without one), hence the plain sentence.
+ */
+export async function componentBuildError(rel: string): Promise<string | null> {
+  const host = dailiesHost();
+  if (host !== undefined) {
+    if (host.buildErrors === undefined) return null;
+    return (await host.buildErrors())[rel] ?? null;
+  }
+  const res = await fetch(`/${rel.split("/").map(encodeURIComponent).join("/")}?dailies-build=${++buildProbe}`);
+  return res.ok ? null : `${rel} does not build.`;
+}
+
 // ---- the agent lane ----------------------------------------------------------
 
 /**
@@ -287,3 +1799,67 @@ const agentTransport: AgentTransport = {
 };
 
 export const agent: AgentClient = createAgentClient(agentTransport);
+
+// ---- Community component listings (worker componentListings.ts) ----------
+// The three Studio-side calls on this host. Listing a component, its link and
+// its preview are written on the main host (`/c/share`), not here.
+
+const COMPONENT_LISTINGS = "/studio/component-listings";
+
+/** The owner side: this workspace's listing of a component, if any, with how
+ *  many people added each version. */
+export interface OwnedComponentListing {
+  id: string;
+  status: "draft" | "unlisted" | "published";
+  version: number | null;
+  name: string;
+  people: { version: number; people: number }[];
+}
+
+export async function ownedComponentListing(componentId: string): Promise<OwnedComponentListing | null> {
+  return (
+    await request<{ listing: OwnedComponentListing | null }>(
+      `${COMPONENT_LISTINGS}/owned?component=${encodeURIComponent(componentId)}`,
+    )
+  ).listing;
+}
+
+/** The copy side: the latest version of each listing these copies came from
+ *  (`origin.source`). A copy whose `origin.version` is lower has an update. */
+export interface ComponentListingUpdate {
+  source: string;
+  version: number;
+  contentHash: string;
+  name: string;
+}
+
+export async function componentListingUpdates(sources: readonly string[]): Promise<ComponentListingUpdate[]> {
+  const ids = [...new Set(sources)].filter((s) => s.startsWith("cml-")).slice(0, 50);
+  if (ids.length === 0) return [];
+  return (
+    await request<{ updates: ComponentListingUpdate[] }>(`${COMPONENT_LISTINGS}/updates?source=${ids.join(",")}`)
+  ).updates;
+}
+
+/** The latest version of a listing this workspace may see, as its frozen
+ *  closure, so an update can name what it keeps aside before the yes. */
+export function componentListingDefinition(
+  listingId: string,
+): Promise<{ version: number; contentHash: string; closure: DefClosure }> {
+  return request(`${COMPONENT_LISTINGS}/${encodeURIComponent(listingId)}/definition`);
+}
+
+/** Replace the copy `def` in `project` with the listing's latest version.
+ *  Overrides move by key (`carryOverrides`); `quarantined` counts the ones
+ *  kept under their old names. The store writes the document, so the open
+ *  editor receives it as a remote change. */
+export function applyComponentListingUpdate(
+  listingId: string,
+  project: string,
+  def: string,
+): Promise<{ defId: string; changed: boolean; quarantined: number; rev: string; version: number }> {
+  return request(`${COMPONENT_LISTINGS}/${encodeURIComponent(listingId)}/update`, {
+    method: "POST",
+    body: JSON.stringify({ project, def, clientId: CLIENT_ID }),
+  });
+}