@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/comments.ts

@@ -0,0 +1,1099 @@
+// COMMENTS (plan C5, Paper page 20; S5): threads pinned to a storyboard
+// Frame, a board card or a spot in the Studio, their messages, the links
+// between a board thread and a Studio thread, the draft, the panel's filter,
+// and the inbox.
+//
+// TWO PLACES, ONE LIST EACH (S5). The board talks about the plan: Frame pins
+// and card threads. The Studio talks about the picture at a moment: Studio
+// threads. The panel never mixes the two (`boardThreads`, `studioThreads`).
+//
+// A SMALL STORE OF ITS OWN, beside the editor's. Comments are not document
+// edits: they never enter undo, never save with the Project, and change under
+// the author's feet (another reviewer, an agent). So they live here, created
+// by and hung on the editor store as `store.comments`. The editor store reads
+// them for the board frame's pins and wakes on every change of this one.
+//
+// THE SERVER IS THE TRUTH. Every write goes to `/api/comments` and the answer
+// replaces the local row. The `comments-changed` and `inbox-changed` events
+// (renderEvents.ts) are signals with no payload worth trusting, so they refetch.
+//
+// WHERE A THREAD IS NOW is read against the LIVE document (`orphanOf`), not the
+// saved one the server judged: an undo that brings a Frame back brings its pin
+// back on the same frame, before the save lands.
+import { visibleStills } from "@dailies-studio/shot/doc";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import * as api from "../api.js";
+import type {
+  CommentAnchor,
+  CommentCardAnchor,
+  CommentFrameAnchor,
+  CommentOrphan,
+  CommentStudioAnchor,
+  CommentThread,
+  InboxItem,
+  Mentionable,
+} from "../api.js";
+import type { ShotStudioPin } from "../bridgeTypes.js";
+import { boardShots, shotNameOf, shotNumberOf, stillNameOf } from "./storyboardModel.js";
+
+export type CommentsFilter = "open" | "resolved" | "mine" | "mentions";
+
+/** The most characters one message may hold (packages/db COMMENT_BODY_MAX). */
+export const COMMENT_BODY_MAX = 4000;
+
+/** The composer key of the draft pin, beside the thread ids. */
+export const NEW_THREAD = "new";
+
+/** The largest picture a thread keeps (packages/store COMMENT_SNAPSHOT_MAX). */
+const COMMENT_SNAPSHOT_MAX = 256 * 1024;
+
+export interface CommentsState {
+  /** The Project the threads belong to; null before a load. */
+  projectId: string | null;
+  /** Every thread of the Project, open and resolved, newest activity first. */
+  threads: readonly CommentThread[];
+  loaded: boolean;
+  /** The last failed read, shown in the panel. */
+  error: string | null;
+  filter: CommentsFilter;
+  /** The ids the server's Mine or Mentions filter answered; null until it has. */
+  matched: readonly string[] | null;
+  /** The thread open in the popover. */
+  openId: string | null;
+  /** The open thread with its messages, once read. */
+  detail: CommentThread | null;
+  /** The thread being written, before its first post: a Frame pin, a card
+   *  or a Studio spot. */
+  draft: { anchor: CommentAnchor } | null;
+  /** What the composer holds, per thread id and `NEW_THREAD`. */
+  texts: Readonly<Record<string, string>>;
+  /** Names for mention chips and the assignee menu, by user id. */
+  names: Readonly<Record<string, string>>;
+  inbox: { items: readonly InboxItem[]; unread: number; loaded: boolean };
+}
+
+/** The API calls this store makes: the real module, or a test's double. */
+export type CommentsApi = Pick<
+  typeof api,
+  | "listThreads"
+  | "getThread"
+  | "createThread"
+  | "replyThread"
+  | "patchThread"
+  | "deleteThread"
+  | "editMessage"
+  | "deleteMessage"
+  | "markThreadRead"
+  | "mentionable"
+  | "inbox"
+  | "markInboxRead"
+  | "putSnapshot"
+  | "linkThread"
+  | "unlinkThread"
+>;
+
+export interface CommentsStore {
+  getState(): CommentsState;
+  subscribe(listener: () => void): () => void;
+  /** Read the Project's threads (and the people to mention). Again for the
+   *  same Project, it refreshes. */
+  load(projectId: string): Promise<void>;
+  /** Forget the Project: another one is opening. */
+  reset(): void;
+  /** Re-read the threads, the open thread and the filter's matches. */
+  refresh(): Promise<void>;
+  setFilter(filter: CommentsFilter): Promise<void>;
+  open(threadId: string): Promise<void>;
+  close(): void;
+  startDraft(anchor: CommentAnchor): void;
+  cancelDraft(): void;
+  setText(key: string, text: string): void;
+  /** Post the composer's text for `key` (a thread id, or `NEW_THREAD` for the
+   *  draft pin). Answers the refusal to show, or null once it landed. A new
+   *  thread then keeps `picture()`, the Frame as the author saw it, best
+   *  effort: a removed Frame's thread shows it. */
+  post(key: string, body: string, picture?: () => Promise<Blob | null>): Promise<string | null>;
+  setStatus(threadId: string, status: "open" | "resolved"): Promise<string | null>;
+  assign(threadId: string, userId: string | null): Promise<string | null>;
+  remove(threadId: string): Promise<string | null>;
+  /** Link a board thread and a Studio thread ("Link to Studio", "Link to
+   *  board"), or undo it. Both rows learn the link. The refusal, or null. */
+  link(threadId: string, otherId: string): Promise<string | null>;
+  unlink(threadId: string, otherId: string): Promise<string | null>;
+  editMessage(threadId: string, messageId: string, body: string): Promise<string | null>;
+  deleteMessage(threadId: string, messageId: string): Promise<string | null>;
+  /** The people a mention may name, for the menu. */
+  mentionable(q: string): Promise<Mentionable>;
+  loadInbox(): Promise<void>;
+  markInboxRead(ids?: readonly number[]): Promise<void>;
+  /** A `comments-changed` event: refetch when it is about this Project. */
+  changed(event: { projectId?: unknown }): void;
+}
+
+const EMPTY: CommentsState = {
+  projectId: null,
+  threads: [],
+  loaded: false,
+  error: null,
+  filter: "open",
+  matched: null,
+  openId: null,
+  detail: null,
+  draft: null,
+  texts: {},
+  names: {},
+  inbox: { items: [], unread: 0, loaded: false },
+};
+
+/** The most pages one load reads. */
+// ponytail: 10 pages of 50 threads. A Project past 500 threads pages the
+// panel instead (`nextCursor` is there for it).
+const MAX_PAGES = 10;
+
+const messageOf = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+/** A list with `thread` in place of the row of the same id, or added first. */
+export function upsertThread(threads: readonly CommentThread[], thread: CommentThread): CommentThread[] {
+  const { messages: _messages, ...row } = thread;
+  const at = threads.findIndex((t) => t.id === thread.id);
+  return at < 0 ? [row, ...threads] : threads.map((t, i) => (i === at ? row : t));
+}
+
+/** The names a list of threads teaches: authors, assignees. */
+function namesFrom(threads: readonly CommentThread[]): Record<string, string> {
+  const names: Record<string, string> = {};
+  for (const t of threads) {
+    if (t.head !== null) names[t.head.authorId] = t.head.authorLabel;
+    if (t.assignee !== null) names[t.assignee.id] = personLabel(t.assignee);
+    for (const m of t.messages ?? []) names[m.authorId] = m.authorLabel;
+  }
+  return names;
+}
+
+export function createCommentsStore(deps: { api?: CommentsApi } = {}): CommentsStore {
+  const http: CommentsApi = deps.api ?? api;
+  let state: CommentsState = EMPTY;
+  const listeners = new Set<() => void>();
+  /** Bumped by `reset`, so an answer for the last Project lands nowhere. */
+  let generation = 0;
+
+  function set(patch: Partial<CommentsState>): void {
+    state = { ...state, ...patch };
+    for (const listener of listeners) listener();
+  }
+
+  const learn = (threads: readonly CommentThread[]) => ({ names: { ...state.names, ...namesFrom(threads) } });
+
+  async function readAll(projectId: string): Promise<CommentThread[]> {
+    const all: CommentThread[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const res = await http.listThreads(projectId, cursor === undefined ? {} : { cursor });
+      all.push(...res.threads);
+      cursor = res.nextCursor;
+      if (cursor === undefined) break;
+    }
+    return all;
+  }
+
+  async function readMatched(projectId: string, filter: CommentsFilter): Promise<readonly string[] | null> {
+    if (filter !== "mine" && filter !== "mentions") return null;
+    const res = await http.listThreads(projectId, { filter });
+    return res.threads.map((t) => t.id);
+  }
+
+  /** Runs a write, folding its thread into the list. The refusal's message,
+   *  or null. */
+  async function write(run: () => Promise<CommentThread | null>): Promise<string | null> {
+    const gen = generation;
+    try {
+      const thread = await run();
+      if (gen !== generation || thread === null) return null;
+      set({
+        threads: upsertThread(state.threads, thread),
+        ...(state.openId === thread.id
+          ? { detail: thread.messages === undefined ? { ...thread, messages: state.detail?.messages ?? [] } : thread }
+          : {}),
+        ...learn([thread]),
+      });
+      return null;
+    } catch (e) {
+      return messageOf(e);
+    }
+  }
+
+  /** Upload a new thread's picture. Silent: the thread stands without it. */
+  async function keepPicture(threadId: string, picture: () => Promise<Blob | null>): Promise<void> {
+    try {
+      const blob = await picture();
+      if (blob !== null && blob.size > 0 && blob.size <= COMMENT_SNAPSHOT_MAX) await http.putSnapshot(threadId, blob);
+    } catch {
+      // A thread without its picture shows the live Frame, or a ground.
+    }
+  }
+
+  /** A link or unlink: the server answers `threadId`'s row, and the other
+   *  row takes the same link from here, so neither waits for a refetch. */
+  async function relink(threadId: string, otherId: string, on: boolean): Promise<string | null> {
+    const said = await write(() => (on ? http.linkThread(threadId, otherId) : http.unlinkThread(threadId, otherId)));
+    if (said !== null) return said;
+    const self = state.threads.find((t) => t.id === threadId);
+    const other = state.threads.find((t) => t.id === otherId);
+    if (self === undefined || other === undefined) return null;
+    const links = other.links.filter((l) => l.threadId !== threadId);
+    const next = { ...other, links: on ? [...links, { threadId, kind: self.anchor.kind }] : links };
+    set({
+      threads: upsertThread(state.threads, next),
+      ...(state.detail?.id === otherId ? { detail: { ...state.detail, links: next.links } } : {}),
+    });
+    return null;
+  }
+
+  const store: CommentsStore = {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    async load(projectId) {
+      if (state.projectId !== projectId) {
+        generation++;
+        set({ ...EMPTY, projectId, inbox: state.inbox });
+      }
+      const gen = generation;
+      try {
+        const [threads, people] = await Promise.all([
+          readAll(projectId),
+          http.mentionable(projectId, "").catch(() => null),
+        ]);
+        if (gen !== generation) return;
+        const names: Record<string, string> = { ...state.names, ...namesFrom(threads) };
+        for (const p of [...(people?.people ?? []), ...(people?.others ?? [])]) names[p.id] = personLabel(p);
+        set({ threads, loaded: true, error: null, names });
+      } catch (e) {
+        if (gen === generation) set({ loaded: true, error: messageOf(e) });
+      }
+    },
+
+    reset() {
+      generation++;
+      set({ ...EMPTY, inbox: state.inbox });
+    },
+
+    async refresh() {
+      const { projectId, openId, filter } = state;
+      if (projectId === null) return;
+      const gen = generation;
+      try {
+        const [threads, matched, detail] = await Promise.all([
+          readAll(projectId),
+          readMatched(projectId, filter),
+          openId === null ? null : http.getThread(openId).catch(() => null),
+        ]);
+        if (gen !== generation) return;
+        set({
+          threads,
+          matched,
+          error: null,
+          loaded: true,
+          // A thread deleted elsewhere closes here.
+          ...(openId !== null && state.openId === openId
+            ? detail === null
+              ? { openId: null, detail: null }
+              : { detail }
+            : {}),
+          ...learn(detail === null ? threads : [...threads, detail]),
+        });
+      } catch (e) {
+        if (gen === generation) set({ error: messageOf(e) });
+      }
+    },
+
+    async setFilter(filter) {
+      set({ filter, matched: null });
+      const { projectId } = state;
+      if (projectId === null) return;
+      const gen = generation;
+      try {
+        const matched = await readMatched(projectId, filter);
+        if (gen === generation && state.filter === filter) set({ matched });
+      } catch (e) {
+        if (gen === generation) set({ error: messageOf(e) });
+      }
+    },
+
+    async open(threadId) {
+      const known = state.threads.find((t) => t.id === threadId) ?? null;
+      set({ openId: threadId, draft: null, detail: known });
+      const gen = generation;
+      try {
+        const thread = await http.getThread(threadId);
+        if (gen !== generation || state.openId !== threadId) return;
+        const read = { ...thread, viewer: { ...thread.viewer, unread: false } };
+        set({ detail: read, threads: upsertThread(state.threads, read), ...learn([thread]) });
+        if (thread.viewer.unread) await http.markThreadRead(threadId).catch(() => undefined);
+      } catch (e) {
+        if (gen === generation && state.openId === threadId) set({ openId: null, detail: null, error: messageOf(e) });
+      }
+    },
+
+    close() {
+      if (state.openId !== null) set({ openId: null, detail: null });
+    },
+
+    startDraft(anchor) {
+      set({ draft: { anchor }, openId: null, detail: null });
+    },
+
+    cancelDraft() {
+      if (state.draft === null) return;
+      const { [NEW_THREAD]: _gone, ...texts } = state.texts;
+      set({ draft: null, texts });
+    },
+
+    setText(key, text) {
+      set({ texts: { ...state.texts, [key]: text } });
+    },
+
+    async post(key, body, picture) {
+      const { projectId, draft } = state;
+      const text = body.trim();
+      if (text === "") return "Write something first.";
+      if (text.length > COMMENT_BODY_MAX) return `A comment holds at most ${COMMENT_BODY_MAX} characters.`;
+      const gen = generation;
+      try {
+        if (key === NEW_THREAD) {
+          if (projectId === null || draft === null) return "Pick a spot on the Frame first.";
+          const thread = await http.createThread(projectId, draft.anchor, text);
+          if (gen !== generation) return null;
+          const { [NEW_THREAD]: _gone, ...texts } = state.texts;
+          set({
+            threads: upsertThread(state.threads, thread),
+            draft: null,
+            texts,
+            openId: thread.id,
+            detail: { ...thread, messages: thread.head === null ? [] : [thread.head] },
+            ...learn([thread]),
+          });
+          if (picture !== undefined && thread.can.snapshot) void keepPicture(thread.id, picture);
+          return null;
+        }
+        const res = await http.replyThread(key, text);
+        if (gen !== generation) return null;
+        const { [key]: _gone, ...texts } = state.texts;
+        const detail =
+          state.openId === key
+            ? { ...res.thread, messages: [...(state.detail?.messages ?? []), res.message] }
+            : state.detail;
+        set({ threads: upsertThread(state.threads, res.thread), detail, texts, ...learn([res.thread]) });
+        return null;
+      } catch (e) {
+        return messageOf(e);
+      }
+    },
+
+    setStatus: (threadId, status) => write(() => http.patchThread(threadId, { status })),
+    assign: (threadId, userId) => write(() => http.patchThread(threadId, { assigneeId: userId })),
+
+    async remove(threadId) {
+      try {
+        await http.deleteThread(threadId);
+        set({
+          threads: state.threads.filter((t) => t.id !== threadId),
+          ...(state.openId === threadId ? { openId: null, detail: null } : {}),
+        });
+        return null;
+      } catch (e) {
+        return messageOf(e);
+      }
+    },
+
+    link: (threadId, otherId) => relink(threadId, otherId, true),
+    unlink: (threadId, otherId) => relink(threadId, otherId, false),
+
+    async editMessage(threadId, messageId, body) {
+      const text = body.trim();
+      if (text === "") return "Write something first.";
+      try {
+        const message = await http.editMessage(threadId, messageId, text);
+        const detail = state.detail;
+        if (message !== null && detail?.id === threadId) {
+          set({ detail: { ...detail, messages: (detail.messages ?? []).map((m) => (m.id === messageId ? message : m)) } });
+        }
+        return null;
+      } catch (e) {
+        return messageOf(e);
+      }
+    },
+
+    async deleteMessage(threadId, messageId) {
+      try {
+        await http.deleteMessage(threadId, messageId);
+        const detail = state.detail;
+        if (detail?.id === threadId) {
+          set({ detail: { ...detail, messages: (detail.messages ?? []).filter((m) => m.id !== messageId) } });
+        }
+        void store.refresh();
+        return null;
+      } catch (e) {
+        return messageOf(e);
+      }
+    },
+
+    async mentionable(q) {
+      const { projectId } = state;
+      if (projectId === null) return { people: [], others: [], canShare: false };
+      const res = await http.mentionable(projectId, q);
+      const names: Record<string, string> = {};
+      for (const p of [...res.people, ...res.others]) names[p.id] = personLabel(p);
+      set({ names: { ...state.names, ...names } });
+      return res;
+    },
+
+    async loadInbox() {
+      try {
+        const res = await http.inbox(false);
+        set({ inbox: { items: res.items, unread: res.unread, loaded: true } });
+      } catch {
+        // The badge keeps what it had: an inbox that cannot be read (an older
+        // server, signed out) is no error the author can act on.
+        if (!state.inbox.loaded) set({ inbox: { ...state.inbox, loaded: true } });
+      }
+    },
+
+    async markInboxRead(ids) {
+      const now = Date.now();
+      let read = 0;
+      const items = state.inbox.items.map((item) => {
+        if (item.readAt !== null || (ids !== undefined && !ids.includes(item.id))) return item;
+        read++;
+        return { ...item, readAt: now };
+      });
+      const unread = ids === undefined ? 0 : Math.max(0, state.inbox.unread - read);
+      set({ inbox: { ...state.inbox, items, unread } });
+      await http.markInboxRead(ids).catch(() => undefined);
+      void store.loadInbox();
+    },
+
+    changed(event) {
+      if (state.projectId !== null && event.projectId === state.projectId) void store.refresh();
+    },
+  };
+  return store;
+}
+
+// ── pure reads ────────────────────────────────────────────────────────────
+
+/** A person's name as the comments show it. */
+export function personLabel(p: { displayName: string | null; login: string }): string {
+  return p.displayName?.trim() || p.login;
+}
+
+/** The person palette (page 20): each person keeps one colour everywhere. */
+const PERSON_COLORS = ["#0099FF", "#8A6CFF", "#2EC4B6", "#C46CFF", "#5B8CFF"] as const;
+
+/** A person's colour, stable for their id. */
+export function personColor(userId: string): string {
+  let hash = 0;
+  for (let i = 0; i < userId.length; i++) hash = (hash * 31 + userId.charCodeAt(i)) | 0;
+  return PERSON_COLORS[Math.abs(hash) % PERSON_COLORS.length]!;
+}
+
+/** A thread on a storyboard Frame. */
+export type FrameThread = CommentThread & { anchor: CommentFrameAnchor };
+/** A thread on a board card. */
+export type CardThread = CommentThread & { anchor: CommentCardAnchor };
+/** A thread on a spot in the Studio. */
+export type StudioThread = CommentThread & { anchor: CommentStudioAnchor };
+
+export const isFrameThread = (t: CommentThread): t is FrameThread => t.anchor.kind === "frame";
+export const isCardThread = (t: CommentThread): t is CardThread => t.anchor.kind === "card";
+export const isStudioThread = (t: CommentThread): t is StudioThread => t.anchor.kind === "studio";
+
+/** The board's own threads (S5): Frame pins and card threads. */
+export const boardThreads = (threads: readonly CommentThread[]): CommentThread[] =>
+  threads.filter((t) => t.anchor.kind !== "studio");
+/** The Studio's own threads (S5). */
+export const studioThreads = (threads: readonly CommentThread[]): StudioThread[] => threads.filter(isStudioThread);
+
+/** Which place a thread belongs to: the board or the Studio. */
+export const placeOfKind = (kind: CommentAnchor["kind"]): "board" | "studio" => (kind === "studio" ? "studio" : "board");
+
+/** A board card, by the ids a card thread names. */
+export interface CardRef {
+  type: "shot" | "reference";
+  id: string;
+  label: string;
+  /** The Shot the card points at now: a planned shot's `scene`, a reference's
+   *  part's `scene`. Null when there is none. */
+  sceneId: string | null;
+}
+
+/** The card a card thread sits on, in the live document, or null when it is
+ *  gone. */
+export function cardOf(doc: Doc3D, target: { partId: string | null; referenceId: string | null }): CardRef | null {
+  const parts = doc.storyboard?.parts ?? [];
+  if (target.partId !== null) {
+    const part = parts.find((p) => p.id === target.partId);
+    return part === undefined
+      ? null
+      : { type: "shot", id: part.id, label: part.label.trim() || "Untitled shot", sceneId: part.scene ?? null };
+  }
+  const ref = doc.resources?.references?.find((r) => r.id === target.referenceId);
+  if (ref === undefined) return null;
+  const part = ref.part === undefined ? undefined : parts.find((p) => p.id === ref.part);
+  return { type: "reference", id: ref.id, label: ref.label.trim() || "Card", sceneId: part?.scene ?? null };
+}
+
+/**
+ * Whether a thread's anchor is there in the live document. Null when it is.
+ * - A Frame pin: "frame-removed" when its Shot is there but not the Frame,
+ *   "shot-removed" when the Shot is gone too. Still ids are document-global,
+ *   so a Frame moved to another Shot keeps its threads.
+ * - A card thread: "card-removed" once its part or reference is gone.
+ * - A Studio thread: "shot-removed" without its Shot, "layer-removed" without
+ *   its layer.
+ * The server's `orphanState` (packages/store/src/commentOrphans.ts), which
+ * this package cannot import.
+ */
+export function orphanOf(doc: Doc3D, anchor: CommentAnchor): CommentOrphan {
+  const shotThere = (id: string): boolean => doc.scenesById[id] !== undefined && doc.scenes.includes(id);
+  if (anchor.kind === "card") return cardOf(doc, anchor) === null ? "card-removed" : null;
+  if (anchor.kind === "studio") {
+    if (!shotThere(anchor.sceneId)) return "shot-removed";
+    if (anchor.layerId === null) return null;
+    return doc.scenesById[anchor.sceneId]!.layersById[anchor.layerId] === undefined ? "layer-removed" : null;
+  }
+  return homeOf(doc, anchor.stillId) !== null ? null : shotThere(anchor.sceneId) ? "frame-removed" : "shot-removed";
+}
+
+/** The Shot that holds still `stillId` now, or null. */
+export function homeOf(doc: Doc3D, stillId: string): string | null {
+  for (const id of doc.scenes) {
+    if (doc.scenesById[id]?.stills?.some((still) => still.id === stillId) === true) return id;
+  }
+  return null;
+}
+
+const isOpen = (t: CommentThread): boolean => t.status === "open";
+
+/** Where a pin sits, in words: its Shot, its Frame ("Frame 3 of 5" and the
+ *  Frame's own name) and the layer under it. A removed Frame keeps the label
+ *  it was pinned with. */
+export interface ThreadPlace {
+  shotNumber: string | null;
+  shotName: string;
+  frameLabel: string;
+  /** "Frame 3 of 5", or null for a removed Frame. */
+  ordinal: string | null;
+  layer: string | null;
+}
+
+export function placeOf(doc: Doc3D, anchor: CommentFrameAnchor): ThreadPlace {
+  const home = homeOf(doc, anchor.stillId);
+  const sceneId = home ?? anchor.sceneId;
+  const scene = doc.scenesById[sceneId];
+  const stills = home === null || scene === undefined ? [] : visibleStills(scene);
+  const at = stills.findIndex((s) => s.id === anchor.stillId);
+  const layer = anchor.layerId === null ? undefined : scene?.layersById[anchor.layerId];
+  return {
+    shotNumber: home === null ? null : shotNumberOf(doc, home),
+    shotName: scene === undefined ? "Removed Shot" : shotNameOf(doc, sceneId),
+    frameLabel: at < 0 ? (anchor.frameLabel ?? "Frame") : stillNameOf(stills, stills[at]!.frame),
+    ordinal: at < 0 ? null : `Frame ${at + 1} of ${stills.length}`,
+    layer: layer === undefined ? null : layer.label.trim() || null,
+  };
+}
+
+/** A Studio thread's moment as S5 writes it: "00:01.10", minutes, seconds
+ *  and the frame inside that second, from a Shot-local frame. */
+export function studioTime(frame: number, fps: { num: number; den: number }): string {
+  const perSecond = Math.max(1, Math.round(fps.num / fps.den));
+  const seconds = Math.floor(frame / perSecond);
+  const two = (n: number): string => String(n).padStart(2, "0");
+  return `${two(Math.floor(seconds / 60))}:${two(seconds % 60)}.${two(frame - seconds * perSecond)}`;
+}
+
+/** What a thread's head says about where it sits (S5): "Frame 3 of 5 · on
+ *  Logo", "On card · 02 Cards gather", or the Studio's "00:01.10" and
+ *  "Layer · Card back". A gone anchor says so. */
+export interface ThreadWhere {
+  /** The Studio moment, drawn as a timecode; null off the Studio. */
+  time: string | null;
+  text: string;
+}
+
+export function threadWhere(doc: Doc3D, anchor: CommentAnchor): ThreadWhere {
+  const orphan = orphanOf(doc, anchor);
+  if (anchor.kind === "card") {
+    const card = cardOf(doc, anchor);
+    if (card === null) return { time: null, text: "Card removed" };
+    const number = card.type === "shot" && card.sceneId !== null ? shotNumberOf(doc, card.sceneId) : null;
+    return { time: null, text: `On card · ${number === null ? "" : `${number} `}${card.label}` };
+  }
+  if (anchor.kind === "studio") {
+    const time = studioTime(anchor.frame, doc.fps);
+    if (orphan === "shot-removed") return { time, text: "Shot removed" };
+    const layer = anchor.layerId === null ? undefined : doc.scenesById[anchor.sceneId]?.layersById[anchor.layerId];
+    if (orphan === "layer-removed") return { time, text: "Layer removed" };
+    return { time, text: layer === undefined ? shotNameOf(doc, anchor.sceneId) : `Layer · ${layer.label.trim() || "Layer"}` };
+  }
+  const place = placeOf(doc, anchor);
+  const where = orphan === null ? (place.ordinal ?? place.frameLabel) : orphan === "frame-removed" ? "Frame removed" : "Shot removed";
+  return { time: null, text: `${where}${place.layer === null ? "" : ` · on ${place.layer}`}` };
+}
+
+/**
+ * Every Studio pin (bridge v45): the open Studio threads, and the open one
+ * even once resolved, each numbered in its Shot by frame then age, the
+ * number the panel's rows show too. The stage draws a pin only while stopped
+ * on its Shot and frame, so these go once, not per frame. A thread whose
+ * Shot or layer is gone draws none.
+ */
+export function studioPinsFor(doc: Doc3D, threads: readonly CommentThread[], openId: string | null): ShotStudioPin[] {
+  const shown = threads
+    .filter(isStudioThread)
+    .filter((t) => (isOpen(t) || t.id === openId) && orphanOf(doc, t.anchor) === null);
+  const numbers = studioNumbers(shown);
+  return shown.map((t) => {
+    const author = t.head?.authorLabel ?? "Someone";
+    const excerpt = plainText(t.head?.body ?? "", {}).slice(0, 80);
+    return {
+      threadId: t.id,
+      anchor: { ...t.anchor },
+      initials: String(numbers.get(t.id) ?? ""),
+      color: personColor(t.createdBy),
+      active: t.id === openId,
+      label: `Comment by ${author}${excerpt === "" ? "" : `: ${excerpt}`}`,
+    };
+  });
+}
+
+/** Studio threads numbered 1, 2, 3 per Shot, by frame then age. */
+export function studioNumbers(threads: readonly StudioThread[]): Map<string, number> {
+  const out = new Map<string, number>();
+  const sorted = [...threads].sort((a, b) => a.anchor.frame - b.anchor.frame || a.createdAt - b.createdAt);
+  const next = new Map<string, number>();
+  for (const t of sorted) {
+    const n = (next.get(t.anchor.sceneId) ?? 0) + 1;
+    next.set(t.anchor.sceneId, n);
+    out.set(t.id, n);
+  }
+  return out;
+}
+
+/** The open threads a board card counts (S5: "1 board · 1 Studio"). */
+export interface CardCommentCount {
+  /** Open threads on the card itself. */
+  board: number;
+  /** Open Studio threads about it: on its planned shot's Shot, and any Studio
+   *  thread linked to one of its board threads. */
+  studio: number;
+}
+
+/**
+ * The counts on a card (S5 note 3: "each shot card shows how many Studio notes
+ * are open, so the plan view never hides work"). A planned shot counts the
+ * open Studio threads on its Shot; a reference has no Shot of its own, so it
+ * counts only the Studio threads linked to its threads. Each thread once.
+ */
+export function cardCommentCounts(
+  doc: Doc3D,
+  threads: readonly CommentThread[],
+  target: { partId: string } | { referenceId: string },
+): CardCommentCount {
+  const card = "partId" in target ? { partId: target.partId, referenceId: null } : { partId: null, referenceId: target.referenceId };
+  return {
+    board: cardThreadsOf(threads, card).filter(isOpen).length,
+    studio: studioNotesFor(doc, threads, card).length,
+  };
+}
+
+/** The threads on one card. */
+function cardThreadsOf(
+  threads: readonly CommentThread[],
+  card: { partId: string | null; referenceId: string | null },
+): CardThread[] {
+  return threads
+    .filter(isCardThread)
+    .filter((t) => (card.partId !== null ? t.anchor.partId === card.partId : t.anchor.referenceId === card.referenceId));
+}
+
+/** The open Studio threads about a card, by frame: on its planned shot's
+ *  Shot, and linked to one of its threads. The board's Studio-note strips
+ *  and the card's "Studio" count. */
+export function studioNotesFor(
+  doc: Doc3D,
+  threads: readonly CommentThread[],
+  card: { partId: string | null; referenceId: string | null },
+): StudioThread[] {
+  const linked = new Set(
+    cardThreadsOf(threads, card).flatMap((t) => t.links.filter((l) => l.kind === "studio").map((l) => l.threadId)),
+  );
+  const sceneId = card.partId === null ? null : (cardOf(doc, { partId: card.partId, referenceId: null })?.sceneId ?? null);
+  return threads
+    .filter(isStudioThread)
+    .filter((t) => isOpen(t) && (linked.has(t.id) || (sceneId !== null && t.anchor.sceneId === sceneId)))
+    .sort((a, b) => a.anchor.frame - b.anchor.frame || a.createdAt - b.createdAt);
+}
+
+/**
+ * The other place's threads one thread shows as notes (S5's strip): every
+ * thread linked to it, and on a card, the open Studio threads about the card
+ * too. Each once, linked ones first.
+ */
+export function notesAbout(doc: Doc3D, threads: readonly CommentThread[], thread: CommentThread): CommentThread[] {
+  const byId = new Map(threads.map((t) => [t.id, t]));
+  const out = new Map<string, CommentThread>();
+  for (const link of thread.links) {
+    const other = byId.get(link.threadId);
+    if (other !== undefined) out.set(other.id, other);
+  }
+  if (isCardThread(thread)) for (const t of studioNotesFor(doc, threads, thread.anchor)) out.set(t.id, t);
+  return [...out.values()];
+}
+
+/** "1 board · 1 Studio", the parts with a count, or "" with none. */
+export function cardCountWords(count: CardCommentCount): string {
+  return [count.board > 0 ? `${count.board} board` : "", count.studio > 0 ? `${count.studio} Studio` : ""]
+    .filter((part) => part !== "")
+    .join(" · ");
+}
+
+export interface CommentCount {
+  open: number;
+  /** Open threads with something the viewer has not read. */
+  unread: number;
+}
+
+/** Open threads per still id: the strip's Frame badges and the scrubber's
+ *  dots. */
+export function countsByStill(threads: readonly CommentThread[]): Map<string, CommentCount> {
+  const counts = new Map<string, CommentCount>();
+  for (const t of threads) {
+    if (!isOpen(t) || !isFrameThread(t)) continue;
+    const c = counts.get(t.anchor.stillId) ?? { open: 0, unread: 0 };
+    counts.set(t.anchor.stillId, { open: c.open + 1, unread: c.unread + (t.viewer.unread ? 1 : 0) });
+  }
+  return counts;
+}
+
+/** Open Frame threads per Shot, orphans included (page 20: "The Shot title
+ *  counts every open thread, even on removed Frames"), by the Shot that holds
+ *  the Frame now, else the one it was pinned in. */
+export function countsByShot(doc: Doc3D, threads: readonly CommentThread[]): Map<string, CommentCount> {
+  const counts = new Map<string, CommentCount>();
+  for (const t of threads) {
+    if (!isOpen(t) || !isFrameThread(t)) continue;
+    const id = homeOf(doc, t.anchor.stillId) ?? t.anchor.sceneId;
+    const c = counts.get(id) ?? { open: 0, unread: 0 };
+    counts.set(id, { open: c.open + 1, unread: c.unread + (t.viewer.unread ? 1 : 0) });
+  }
+  return counts;
+}
+
+/** The threads a filter shows. Open also keeps nothing resolved; the panel
+ *  adds "Resolved today" under it. */
+export function filterThreads(
+  threads: readonly CommentThread[],
+  filter: CommentsFilter,
+  matched: readonly string[] | null,
+): CommentThread[] {
+  if (filter === "open") return threads.filter(isOpen);
+  if (filter === "resolved") return threads.filter((t) => !isOpen(t));
+  const ids = new Set(matched ?? []);
+  return threads.filter((t) => ids.has(t.id));
+}
+
+/** Resolved threads whose resolve happened since local midnight of `now`. */
+export function resolvedToday(threads: readonly CommentThread[], now: number): CommentThread[] {
+  const midnight = new Date(now);
+  midnight.setHours(0, 0, 0, 0);
+  return threads.filter((t) => !isOpen(t) && (t.resolvedAt ?? 0) >= midnight.getTime());
+}
+
+/** One Frame's rows in the panel. */
+export interface FrameGroup {
+  stillId: string;
+  /** Shot-local frame. */
+  frame: number;
+  label: string;
+  orphan: CommentOrphan;
+  threads: CommentThread[];
+}
+
+/** One Shot's block in the panel. */
+export interface ShotGroup {
+  sceneId: string;
+  /** "02", or null for a Shot that is gone. */
+  number: string | null;
+  name: string;
+  open: number;
+  frames: FrameGroup[];
+}
+
+/**
+ * The board list's Frame threads: by Shot in playing order, then by Frame in
+ * frame order, newest thread first inside one Frame. A removed Frame sorts
+ * after its Shot's live ones; a removed Shot's threads come last, by the name
+ * it had. Card and Studio threads are left out (`groupCardThreads`,
+ * `groupStudioThreads`).
+ */
+export function groupThreads(doc: Doc3D, threads: readonly CommentThread[]): ShotGroup[] {
+  const shots = boardShots(doc);
+  const order = new Map(shots.map((s, i) => [s.sceneId, i]));
+  const groups = new Map<string, ShotGroup>();
+  for (const t of threads.filter(isFrameThread)) {
+    const home = homeOf(doc, t.anchor.stillId);
+    const sceneId = home ?? t.anchor.sceneId;
+    const orphan = home !== null ? null : orphanOf(doc, t.anchor);
+    const groupKey = orphan === "shot-removed" ? `gone:${sceneId}` : sceneId;
+    let group = groups.get(groupKey);
+    if (group === undefined) {
+      group = {
+        sceneId,
+        number: orphan === "shot-removed" ? null : shotNumberOf(doc, sceneId),
+        name: orphan === "shot-removed" ? "Removed Shot" : shotNameOf(doc, sceneId),
+        open: 0,
+        frames: [],
+      };
+      groups.set(groupKey, group);
+    }
+    if (isOpen(t)) group.open++;
+    let frame = group.frames.find((f) => f.stillId === t.anchor.stillId);
+    if (frame === undefined) {
+      const stills = home === null ? [] : (shots.find((s) => s.sceneId === home)?.stills ?? []);
+      const still = stills.find((s) => s.id === t.anchor.stillId);
+      frame = {
+        stillId: t.anchor.stillId,
+        frame: still?.frame ?? t.anchor.frame,
+        label: still === undefined ? (t.anchor.frameLabel ?? "Frame") : stillNameOf(stills, still.frame),
+        orphan,
+        threads: [],
+      };
+      group.frames.push(frame);
+    }
+    frame.threads.push(t);
+  }
+  const rank = (g: ShotGroup): number => (g.number === null ? Infinity : (order.get(g.sceneId) ?? Infinity));
+  const out = [...groups.values()].sort((a, b) => rank(a) - rank(b));
+  for (const g of out) {
+    g.frames.sort((a, b) => Number(a.orphan !== null) - Number(b.orphan !== null) || a.frame - b.frame);
+    for (const f of g.frames) f.threads.sort((a, b) => b.lastMessageAt - a.lastMessageAt);
+  }
+  return out;
+}
+
+/** One card's rows in the board list. */
+export interface CardGroup {
+  /** The part or reference id. */
+  id: string;
+  /** The card, as `cardCommentCounts` takes it. */
+  target: { partId: string } | { referenceId: string };
+  /** "02 Cards gather", or what a removed card was. */
+  label: string;
+  orphan: CommentOrphan;
+  open: number;
+  threads: CommentThread[];
+}
+
+/**
+ * The board list's card threads, one group per card: planned shots in plan
+ * order, then references in board order, then removed cards. Newest activity
+ * first inside a card.
+ */
+export function groupCardThreads(doc: Doc3D, threads: readonly CommentThread[]): CardGroup[] {
+  const order = new Map<string, number>();
+  (doc.storyboard?.parts ?? []).forEach((p, i) => order.set(p.id, i));
+  (doc.resources?.references ?? []).forEach((r, i) => order.set(r.id, 1e6 + i));
+  const groups = new Map<string, CardGroup>();
+  for (const t of threads.filter(isCardThread)) {
+    const id = t.anchor.partId ?? t.anchor.referenceId ?? "";
+    let group = groups.get(id);
+    if (group === undefined) {
+      const where = threadWhere(doc, t.anchor);
+      group = {
+        id,
+        target: t.anchor.partId !== null ? { partId: t.anchor.partId } : { referenceId: id },
+        label: where.text.replace(/^On card · /, ""),
+        orphan: orphanOf(doc, t.anchor),
+        open: 0,
+        threads: [],
+      };
+      groups.set(id, group);
+    }
+    if (isOpen(t)) group.open++;
+    group.threads.push(t);
+  }
+  const rank = (g: CardGroup): number => order.get(g.id) ?? Infinity;
+  const out = [...groups.values()].sort((a, b) => rank(a) - rank(b));
+  for (const g of out) g.threads.sort((a, b) => b.lastMessageAt - a.lastMessageAt);
+  return out;
+}
+
+/** One Shot's Studio rows. */
+export interface StudioGroup {
+  sceneId: string;
+  /** "02", or null for a Shot that is gone. */
+  number: string | null;
+  name: string;
+  open: number;
+  /** By frame, then oldest first: the order the pins number in. */
+  threads: StudioThread[];
+}
+
+/** The Studio list: its threads by Shot in playing order, a removed Shot's
+ *  last. */
+export function groupStudioThreads(doc: Doc3D, threads: readonly CommentThread[]): StudioGroup[] {
+  const order = new Map(doc.scenes.map((id, i) => [id, i]));
+  const groups = new Map<string, StudioGroup>();
+  for (const t of threads.filter(isStudioThread)) {
+    const sceneId = t.anchor.sceneId;
+    let group = groups.get(sceneId);
+    if (group === undefined) {
+      const gone = orphanOf(doc, t.anchor) === "shot-removed";
+      group = {
+        sceneId,
+        number: gone ? null : shotNumberOf(doc, sceneId),
+        name: gone ? "Removed Shot" : shotNameOf(doc, sceneId),
+        open: 0,
+        threads: [],
+      };
+      groups.set(sceneId, group);
+    }
+    if (isOpen(t)) group.open++;
+    group.threads.push(t);
+  }
+  const rank = (g: StudioGroup): number => (g.number === null ? Infinity : (order.get(g.sceneId) ?? Infinity));
+  const out = [...groups.values()].sort((a, b) => rank(a) - rank(b));
+  for (const g of out) g.threads.sort((a, b) => a.anchor.frame - b.anchor.frame || a.createdAt - b.createdAt);
+  return out;
+}
+
+/**
+ * The open thread N (dir 1) or Shift+N (dir -1) goes to from `fromId`, in the
+ * board list's order: the cards' threads (planned shots in plan order, then
+ * the other cards, oldest first on each), then any older Frame threads (Shot,
+ * Frame, oldest first). A removed card or Frame is skipped. Wraps at either
+ * end; undefined with none.
+ */
+export function nextOpenThread(
+  doc: Doc3D,
+  threads: readonly CommentThread[],
+  fromId: string | null,
+  dir: 1 | -1,
+): CommentThread | undefined {
+  const open = threads.filter(isOpen);
+  const cards = groupCardThreads(doc, open)
+    .filter((g) => g.orphan === null)
+    .flatMap((g) => [...g.threads].sort((a, b) => a.createdAt - b.createdAt));
+  const place = new Map<string, number>();
+  boardShots(doc).forEach((shot, s) => {
+    for (const still of shot.stills) if (still.id !== null) place.set(still.id, s * 1e7 + still.frame);
+  });
+  const frames = open
+    .filter(isFrameThread)
+    .filter((t) => place.has(t.anchor.stillId))
+    .sort((a, b) => place.get(a.anchor.stillId)! - place.get(b.anchor.stillId)! || a.createdAt - b.createdAt);
+  const ring = [...cards, ...frames];
+  if (ring.length === 0) return undefined;
+  const at = fromId === null ? -1 : ring.findIndex((t) => t.id === fromId);
+  if (at < 0) return dir === 1 ? ring[0] : ring[ring.length - 1];
+  return ring[(at + dir + ring.length) % ring.length];
+}
+
+/**
+ * "ASK AGENT TO FIX" (plan C5): fix what open comment threads ask for, by
+ * their ids, through the comment tools (packages/store/src/mcpCommentTools.ts).
+ * Prefilled, never sent, like `movePrompt`. Each thread says where it sits, by
+ * kind; the agent reads the words with `get_comment`, so a body is never
+ * pasted into the prompt.
+ */
+export function commentPrompt(doc: Doc3D, threads: readonly Pick<CommentThread, "id" | "anchor">[]): string {
+  const shot = (sceneId: string): string =>
+    doc.scenesById[sceneId] === undefined ? "a removed Shot" : `Shot "${shotNameOf(doc, sceneId)}"`;
+  const where = (t: (typeof threads)[number]): string => {
+    const a = t.anchor;
+    if (a.kind === "card") {
+      const card = cardOf(doc, a);
+      return `${t.id} (on the board, ${card === null ? "a removed card" : `card "${card.label}"`})`;
+    }
+    if (a.kind === "studio") return `${t.id} (in the Studio, ${shot(a.sceneId)} at ${studioTime(a.frame, doc.fps)})`;
+    return `${t.id} (${a.frameLabel ?? "a Frame"} in ${shot(a.sceneId)})`;
+  };
+  const lines = [
+    threads.length === 1
+      ? "Fix what this comment thread asks for:"
+      : `Fix what these ${threads.length} open comment threads ask for:`,
+    ...threads.map((t) => `- ${where(t)}`),
+    "",
+    "For each thread:",
+    "1. Read it with get_comment: the messages, where it sits, the layer and the snapshot of what the reviewer saw.",
+    "2. Make the change in one shot_batch.",
+    "3. Reply with reply_comment, saying in one or two sentences what you changed.",
+    "4. Resolve it with resolve_comment. Leave it open and say why in the reply when it needs the author to decide.",
+  ];
+  return lines.join("\n");
+}
+
+// ── mentions ──────────────────────────────────────────────────────────────
+
+/** A mention as stored: `<@usr-...>`, as in packages/db comments.ts. */
+const MENTION_RE = /<@(usr-[A-Za-z0-9-]{1,64})>/g;
+
+export type BodySegment = { kind: "text"; text: string } | { kind: "mention"; userId: string; label: string };
+
+/** A stored body as text and mention chips. */
+export function bodySegments(body: string, names: Readonly<Record<string, string>>): BodySegment[] {
+  const out: BodySegment[] = [];
+  let last = 0;
+  for (const match of body.matchAll(MENTION_RE)) {
+    if (match.index > last) out.push({ kind: "text", text: body.slice(last, match.index) });
+    const userId = match[1]!;
+    out.push({ kind: "mention", userId, label: names[userId] ?? "someone" });
+    last = match.index + match[0].length;
+  }
+  if (last < body.length) out.push({ kind: "text", text: body.slice(last) });
+  return out;
+}
+
+/** A stored body as one line of plain text, mentions as `@Name`. */
+export function plainText(body: string, names: Readonly<Record<string, string>>): string {
+  return bodySegments(body, names)
+    .map((s) => (s.kind === "text" ? s.text : `@${s.label}`))
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** The `@word` being typed just before `caret`, or null. An `@` counts at
+ *  the start or after whitespace, so an email address opens no menu. */
+export function mentionQuery(text: string, caret: number): { start: number; query: string } | null {
+  const match = /(^|\s)@([^\s@]{0,40})$/.exec(text.slice(0, caret));
+  return match === null ? null : { start: caret - match[2]!.length - 1, query: match[2]! };
+}
+
+/** `text` with the `@query` at `start..caret` replaced by `@Label `. */
+export function insertMention(
+  text: string,
+  start: number,
+  caret: number,
+  label: string,
+): { text: string; caret: number } {
+  const chip = `@${label} `;
+  return { text: text.slice(0, start) + chip + text.slice(caret), caret: start + chip.length };
+}
+
+/**
+ * The composer's text as a stored body: each `@Label` of a person picked from
+ * the menu becomes their `<@id>` token. Longest labels first, so "@Ann Lee"
+ * is not eaten by a picked "@Ann".
+ */
+export function encodeMentions(text: string, picked: readonly { id: string; label: string }[]): string {
+  let out = text;
+  for (const p of [...picked].sort((a, b) => b.label.length - a.label.length)) {
+    out = out.split(`@${p.label}`).join(`<@${p.id}>`);
+  }
+  return out;
+}