@hyperframes/studio 0.7.58 → 0.7.59

package/src/components/storyboard/FramePoster.tsx

@@ -10,6 +10,13 @@ export interface FramePosterProps {
   title: string;
   /** `cover` fills+crops (contact-sheet tile); `contain` letterboxes (focus hero). */
   fit?: "cover" | "contain";
+  /**
+   * Project content signature to key the poster URL on. The thumbnail route
+   * regenerates when the frame's source changes, but the browser only refetches
+   * when the URL does — so bake the signature in to pick up fresh posters after
+   * a background board refresh.
+   */
+  posterVersion?: string;
 }
 
 /**
@@ -18,11 +25,19 @@ export interface FramePosterProps {
  * no postMessage seek, and no client-side fps assumption. Shared by the
  * contact-sheet tile and the frame-focus view.
  */
-export function FramePoster({ projectId, src, seconds, title, fit = "cover" }: FramePosterProps) {
+export function FramePoster({
+  projectId,
+  src,
+  seconds,
+  title,
+  fit = "cover",
+  posterVersion,
+}: FramePosterProps) {
   const [failed, setFailed] = useState(false);
   // The <img> is reused (no key) when a tile/hero swaps to a different frame, so a
-  // prior load error would stick. Reset when the poster target changes.
-  useEffect(() => setFailed(false), [src, seconds]);
+  // prior load error would stick. Reset when the poster target changes — including
+  // a new posterVersion, so a frame that failed mid-write retries once it settles.
+  useEffect(() => setFailed(false), [src, seconds, posterVersion]);
   if (failed) {
     return (
       <div className="flex h-full w-full items-center justify-center text-[11px] text-neutral-600">
@@ -30,12 +45,17 @@ export function FramePoster({ projectId, src, seconds, title, fit = "cover" }: F
       </div>
     );
   }
-  const url = buildCompositionThumbnailUrl({
+  let url = buildCompositionThumbnailUrl({
     previewUrl: `/api/projects/${projectId}/preview/comp/${src}`,
     seekTime: seconds,
     duration: 0,
     origin: window.location.origin,
   });
+  if (posterVersion) {
+    const withVersion = new URL(url, window.location.origin);
+    withVersion.searchParams.set("sig", posterVersion);
+    url = withVersion.toString();
+  }
   return (
     <img
       src={url}

package/src/components/storyboard/StoryboardFrameFocus.tsx

@@ -19,6 +19,8 @@ export interface StoryboardFrameFocusProps {
   onSaved: () => void;
   /** Select a composition in the timeline (sets active comp + editing file + sidebar highlight). */
   onSelectComposition: (path: string) => void;
+  /** Project signature the board was loaded with (busts the poster cache). */
+  posterVersion?: string;
 }
 
 /**
@@ -39,6 +41,7 @@ export function StoryboardFrameFocus({
   onNavigate,
   onSaved,
   onSelectComposition,
+  posterVersion,
 }: StoryboardFrameFocusProps) {
   const { readProjectFile, writeProjectFile } = useFileManagerContext();
   const { setViewMode } = useViewMode();
@@ -151,6 +154,7 @@ export function StoryboardFrameFocus({
                 seconds={posterTime(frame)}
                 title={title}
                 fit="contain"
+                posterVersion={posterVersion}
               />
             ) : (
               <div className="flex h-full w-full items-center justify-center text-sm text-neutral-600">

package/src/components/storyboard/StoryboardFrameTile.tsx

@@ -7,6 +7,13 @@ export interface StoryboardFrameTileProps {
   frame: StoryboardFrameView;
   /** Open this frame in the full-area focus view. */
   onOpen: (index: number) => void;
+  /** This frame's pending comment draft ("" when none). */
+  commentDraft: string;
+  onCommentDraftChange: (index: number, text: string) => void;
+  /** A submitted comment the agent has not consumed yet (null when none). */
+  pendingComment: string | null;
+  /** Project signature the board was loaded with (busts the poster cache). */
+  posterVersion?: string;
 }
 
 function firstLine(text: string): string {
@@ -26,7 +33,15 @@ function placeholderMessage(frame: StoryboardFrameView): string {
 
 /** A single contact-sheet tile: poster preview + its metadata. Click to focus. */
 // fallow-ignore-next-line complexity
-export function StoryboardFrameTile({ projectId, frame, onOpen }: StoryboardFrameTileProps) {
+export function StoryboardFrameTile({
+  projectId,
+  frame,
+  onOpen,
+  commentDraft,
+  onCommentDraftChange,
+  pendingComment,
+  posterVersion,
+}: StoryboardFrameTileProps) {
   const meta = FRAME_STATUS_META[frame.status];
   const renderable = frame.srcExists && frame.status !== "outline";
   const title = frame.title ?? `Frame ${frame.index}`;
@@ -48,6 +63,7 @@ export function StoryboardFrameTile({ projectId, frame, onOpen }: StoryboardFram
             src={frame.src}
             seconds={posterTime(frame)}
             title={title}
+            posterVersion={posterVersion}
           />
         ) : (
           <FrameTilePlaceholder frame={frame} />
@@ -74,6 +90,19 @@ export function StoryboardFrameTile({ projectId, frame, onOpen }: StoryboardFram
         {frame.duration && <span>{frame.duration}</span>}
         {frame.transitionIn && <span>↘ {frame.transitionIn}</span>}
       </div>
+      <textarea
+        value={commentDraft}
+        onChange={(e) => onCommentDraftChange(frame.index, e.target.value)}
+        rows={2}
+        placeholder="Comment on this frame…"
+        aria-label={`Comment on ${title}`}
+        className="mt-2 w-full resize-none rounded-md border border-neutral-800 bg-neutral-900/60 px-2 py-1.5 text-xs text-neutral-200 placeholder:text-neutral-600 focus:border-sky-700 focus:outline-none"
+      />
+      {pendingComment && (
+        <p className="mt-1 text-[11px] text-sky-400/90">
+          <span className="font-medium">Pending:</span> “{pendingComment}”
+        </p>
+      )}
     </article>
   );
 }

package/src/components/storyboard/StoryboardGrid.tsx

@@ -1,4 +1,5 @@
 import type { StoryboardFrameView } from "../../hooks/useStoryboard";
+import type { FrameCommentEntry } from "./frameComments";
 import { StoryboardFrameTile } from "./StoryboardFrameTile";
 
 export interface StoryboardGridProps {
@@ -6,10 +7,25 @@ export interface StoryboardGridProps {
   frames: StoryboardFrameView[];
   /** Open a frame in the full-area focus view. */
   onOpenFrame: (index: number) => void;
+  /** Per-frame comment drafts, keyed by frame index. */
+  commentDrafts: Record<number, string>;
+  onCommentDraftChange: (index: number, text: string) => void;
+  /** Submitted comments the agent has not consumed yet. */
+  pendingComments: FrameCommentEntry[] | null;
+  /** Project signature the board was loaded with (busts poster caches). */
+  posterVersion?: string;
 }
 
 /** The contact sheet: ordered frame tiles in a responsive grid. */
-export function StoryboardGrid({ projectId, frames, onOpenFrame }: StoryboardGridProps) {
+export function StoryboardGrid({
+  projectId,
+  frames,
+  onOpenFrame,
+  commentDrafts,
+  onCommentDraftChange,
+  pendingComments,
+  posterVersion,
+}: StoryboardGridProps) {
   if (frames.length === 0) {
     return (
       <div className="mt-8 rounded-lg border border-dashed border-neutral-800 px-6 py-12 text-center text-sm text-neutral-500">
@@ -26,6 +42,12 @@ export function StoryboardGrid({ projectId, frames, onOpenFrame }: StoryboardGri
           projectId={projectId}
           frame={frame}
           onOpen={onOpenFrame}
+          commentDraft={commentDrafts[frame.index] ?? ""}
+          onCommentDraftChange={onCommentDraftChange}
+          pendingComment={
+            pendingComments?.find((entry) => entry.frame === frame.index)?.text ?? null
+          }
+          posterVersion={posterVersion}
         />
       ))}
     </div>

package/src/components/storyboard/StoryboardLoaded.tsx

@@ -1,11 +1,13 @@
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import type { StoryboardResponse } from "../../hooks/useStoryboard";
+import { Button } from "../ui/Button";
 import { StoryboardDirection } from "./StoryboardDirection";
 import { StoryboardGrid } from "./StoryboardGrid";
 import { StoryboardStatusLegend } from "./StoryboardStatusLegend";
 import { StoryboardScriptPanel } from "./StoryboardScriptPanel";
 import { StoryboardSourceEditor, type SourceFile } from "./StoryboardSourceEditor";
 import { StoryboardFrameFocus } from "./StoryboardFrameFocus";
+import { useFrameComments, type CommentsSubmitState } from "./useFrameComments";
 
 type SubView = "board" | "source";
 
@@ -33,6 +35,14 @@ export function StoryboardLoaded({
   const [subView, setSubView] = useState<SubView>("board");
   const [sourceDirty, setSourceDirty] = useState(false);
   const [focusedIndex, setFocusedIndex] = useState<number | null>(null);
+  const comments = useFrameComments(data.frames);
+  // When the board refreshes off a project change (agent revised frames), the
+  // agent has likely consumed the comments file too — re-check so the pending
+  // banner clears the moment revisions land, not on the next window focus.
+  const { refreshPending } = comments;
+  useEffect(() => {
+    void refreshPending();
+  }, [data.signature, refreshPending]);
   const sourceFiles = useMemo<SourceFile[]>(() => {
     const files: SourceFile[] = [{ path: data.path, label: data.path }];
     if (data.script?.exists) files.push({ path: data.script.path, label: data.script.path });
@@ -72,14 +82,23 @@ export function StoryboardLoaded({
         }
         onSaved={reload}
         onSelectComposition={onSelectComposition}
+        posterVersion={data.signature}
       />
     );
   }
 
   return (
     <div className="flex flex-1 min-h-0 flex-col bg-neutral-950 text-neutral-200">
-      <div className="flex items-center border-b border-neutral-800 px-4 py-2">
+      <div className="flex items-center gap-3 border-b border-neutral-800 px-4 py-2">
         <SubViewToggle value={subView} onChange={changeSubView} />
+        {subView === "board" && (
+          <CommentsSubmitBar
+            draftCount={comments.draftCount}
+            pendingCount={comments.pending?.length ?? 0}
+            submitState={comments.submitState}
+            onSubmit={() => void comments.submit()}
+          />
+        )}
       </div>
       {subView === "board" ? (
         <div className="flex-1 min-h-0 overflow-auto">
@@ -92,6 +111,10 @@ export function StoryboardLoaded({
               projectId={projectId}
               frames={data.frames}
               onOpenFrame={setFocusedIndex}
+              commentDrafts={comments.drafts}
+              onCommentDraftChange={comments.setDraft}
+              pendingComments={comments.pending}
+              posterVersion={data.signature}
             />
             {data.script && <StoryboardScriptPanel script={data.script} />}
           </div>
@@ -107,6 +130,39 @@ export function StoryboardLoaded({
   );
 }
 
+/** Batch-submit the per-frame comment drafts to `.hyperframes/frame-comments.json`. */
+function CommentsSubmitBar({
+  draftCount,
+  pendingCount,
+  submitState,
+  onSubmit,
+}: {
+  draftCount: number;
+  pendingCount: number;
+  submitState: CommentsSubmitState;
+  onSubmit: () => void;
+}) {
+  return (
+    <div className="ml-auto flex items-center gap-3">
+      {pendingCount > 0 && (
+        <span className="text-xs text-sky-300">
+          {pendingCount} comment{pendingCount > 1 ? "s" : ""} pending — reply anything in your agent
+          chat and it will apply them.
+        </span>
+      )}
+      <Button
+        variant="primary"
+        size="sm"
+        loading={submitState === "saving"}
+        disabled={draftCount === 0 || submitState === "saving"}
+        onClick={onSubmit}
+      >
+        {draftCount > 0 ? `Submit comments (${draftCount})` : "Submit comments"}
+      </Button>
+    </div>
+  );
+}
+
 const SUB_VIEWS: Array<{ value: SubView; label: string }> = [
   { value: "board", label: "Board" },
   { value: "source", label: "Source" },

package/src/components/storyboard/StoryboardView.tsx

@@ -1,6 +1,7 @@
 import { useState, type ReactNode } from "react";
 import { Copy, Check } from "@phosphor-icons/react";
 import { useStoryboard } from "../../hooks/useStoryboard";
+import { useProjectSignaturePoll } from "../../hooks/useProjectSignaturePoll";
 import { copyTextToClipboard } from "../../utils/clipboard";
 import { Button } from "../ui/Button";
 import { StoryboardLoaded } from "./StoryboardLoaded";
@@ -19,6 +20,10 @@ export interface StoryboardViewProps {
 // fallow-ignore-next-line complexity
 export function StoryboardView({ projectId, onSelectComposition }: StoryboardViewProps) {
   const { data, loading, error, reload } = useStoryboard(projectId);
+  // Keep the board current while an agent writes to the project: when the
+  // project signature moves past the one `data` was loaded with, refetch. Also
+  // upgrades the empty state the moment STORYBOARD.md lands on disk.
+  useProjectSignaturePoll(projectId, data?.signature, reload);
 
   if (loading) return <StoryboardFrame>{<Message>Loading storyboard…</Message>}</StoryboardFrame>;
   if (error) {
@@ -87,12 +92,14 @@ audience: <who it's for>
 ## Frame 1 — <title>
 - duration: 5s
 - transition_in: crossfade
-- status: planned
+- status: outline
 - src: compositions/frames/01-<slug>.html
 
 <A sentence or two: what's on screen and what the narration says.>
 
-Add one \`## Frame N\` section per beat. Keep the arc tight.`;
+Add one \`## Frame N\` section per beat. Keep the arc tight.
+
+Then run the review loop from the hyperframes-core skill (references/review-loop.md): present the plan as a proposal, offer wireframe sketches on this board, and build on the confirmed layouts.`;
 }
 
 function EmptyState({ path }: { path: string }) {

package/src/components/storyboard/frameComments.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import { buildCommentsFile, draftEntries, parseCommentsFile, passForFrames } from "./frameComments";
+
+const frames = [
+  { index: 1, status: "built" as const, src: "compositions/frames/01-hook.html", title: "Hook" },
+  {
+    index: 2,
+    status: "built" as const,
+    src: "compositions/frames/02-thesis.html",
+    title: "Thesis",
+  },
+  { index: 3, status: "built" as const, src: "compositions/frames/03-proof.html", title: "Proof" },
+];
+
+describe("passForFrames", () => {
+  it("maps the furthest status to the review pass", () => {
+    expect(passForFrames([{ status: "outline" }, { status: "outline" }])).toBe("storyboard");
+    expect(passForFrames([{ status: "outline" }, { status: "built" }])).toBe("sketch");
+    expect(passForFrames([{ status: "built" }, { status: "animated" }])).toBe("final");
+  });
+});
+
+describe("draftEntries", () => {
+  it("keeps only non-empty drafts, in board order, with src/title echoed", () => {
+    const entries = draftEntries(frames, { 3: "swap the chart", 1: "  ", 2: "tighter kerning" });
+    expect(entries).toEqual([
+      { frame: 2, src: frames[1]?.src, title: "Thesis", text: "tighter kerning" },
+      { frame: 3, src: frames[2]?.src, title: "Proof", text: "swap the chart" },
+    ]);
+  });
+});
+
+describe("parseCommentsFile", () => {
+  it("reads a well-formed file", () => {
+    const parsed = parseCommentsFile(
+      JSON.stringify({
+        version: 1,
+        pass: "sketch",
+        submitted_at: "2026-07-10T00:00:00Z",
+        comments: [{ frame: 2, text: "hi" }],
+      }),
+    );
+    expect(parsed?.pass).toBe("sketch");
+    expect(parsed?.comments).toEqual([{ frame: 2, src: undefined, title: undefined, text: "hi" }]);
+  });
+
+  it("treats empty or malformed input as no file", () => {
+    expect(parseCommentsFile("")).toBeNull();
+    expect(parseCommentsFile("not json")).toBeNull();
+    expect(parseCommentsFile(JSON.stringify({ comments: "nope" }))).toBeNull();
+  });
+
+  it("drops malformed entries but keeps the valid ones", () => {
+    const parsed = parseCommentsFile(
+      JSON.stringify({ comments: [{ frame: 1, text: "ok" }, { frame: "x" }, null] }),
+    );
+    expect(parsed?.comments).toEqual([{ frame: 1, src: undefined, title: undefined, text: "ok" }]);
+  });
+});
+
+describe("buildCommentsFile", () => {
+  it("merges an unconsumed previous batch: new frames win, others stay", () => {
+    const previous = parseCommentsFile(
+      JSON.stringify({
+        version: 1,
+        pass: "sketch",
+        submitted_at: "2026-07-10T00:00:00Z",
+        comments: [
+          { frame: 1, text: "old note on hook" },
+          { frame: 3, text: "old note on proof" },
+        ],
+      }),
+    );
+    const file = buildCommentsFile(
+      frames,
+      { 3: "new note on proof" },
+      previous,
+      "2026-07-10T01:00:00Z",
+    );
+    expect(file.pass).toBe("sketch");
+    expect(file.submitted_at).toBe("2026-07-10T01:00:00Z");
+    expect(file.comments.map((c) => [c.frame, c.text])).toEqual([
+      [1, "old note on hook"],
+      [3, "new note on proof"],
+    ]);
+  });
+
+  it("writes a fresh batch when no previous file exists", () => {
+    const file = buildCommentsFile(frames, { 2: "tighter" }, null, "2026-07-10T01:00:00Z");
+    expect(file.version).toBe(1);
+    expect(file.comments).toEqual([
+      { frame: 2, src: frames[1]?.src, title: "Thesis", text: "tighter" },
+    ]);
+  });
+});

package/src/components/storyboard/frameComments.ts

@@ -0,0 +1,115 @@
+import type { FrameStatus } from "@hyperframes/core/storyboard";
+
+/**
+ * Frame comments — the storyboard review's structured feedback channel.
+ *
+ * The board's per-frame comment boxes write one batch file on submit; the
+ * consuming agent revises exactly the frames named, deletes the file, and
+ * re-presents. The file shape is a cross-repo contract — keep it in sync with
+ * skills/hyperframes-core/references/storyboard-format.md § Frame comments.
+ */
+export const FRAME_COMMENTS_PATH = ".hyperframes/frame-comments.json";
+
+export type FrameCommentsPass = "storyboard" | "sketch" | "final";
+
+export interface FrameCommentEntry {
+  /** The frame's 1-based `index` in the manifest — the key. */
+  frame: number;
+  /** Copied from the frame at submit time so a post-submit reorder is detectable. */
+  src?: string;
+  title?: string;
+  text: string;
+}
+
+export interface FrameCommentsFile {
+  version: 1;
+  pass: FrameCommentsPass;
+  submitted_at: string;
+  comments: FrameCommentEntry[];
+}
+
+interface CommentableFrame {
+  index: number;
+  status: FrameStatus;
+  src?: string;
+  title?: string;
+}
+
+/** Which review the batch belongs to — the furthest status present on the board. */
+export function passForFrames(frames: ReadonlyArray<{ status: FrameStatus }>): FrameCommentsPass {
+  if (frames.some((f) => f.status === "animated")) return "final";
+  if (frames.some((f) => f.status === "built")) return "sketch";
+  return "storyboard";
+}
+
+/** The non-empty drafts as file entries, in board order. */
+export function draftEntries(
+  frames: readonly CommentableFrame[],
+  drafts: Readonly<Record<number, string>>,
+): FrameCommentEntry[] {
+  const entries: FrameCommentEntry[] = [];
+  for (const frame of frames) {
+    const text = drafts[frame.index]?.trim();
+    if (!text) continue;
+    entries.push({ frame: frame.index, src: frame.src, title: frame.title, text });
+  }
+  return entries;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function parseCommentEntry(item: unknown): FrameCommentEntry | null {
+  if (!isRecord(item)) return null;
+  if (typeof item.frame !== "number" || typeof item.text !== "string") return null;
+  return {
+    frame: item.frame,
+    src: typeof item.src === "string" ? item.src : undefined,
+    title: typeof item.title === "string" ? item.title : undefined,
+    text: item.text,
+  };
+}
+
+function parsePass(value: unknown): FrameCommentsPass {
+  return value === "sketch" || value === "final" ? value : "storyboard";
+}
+
+/** Tolerant read of an existing comments file — anything malformed counts as "no file". */
+export function parseCommentsFile(raw: string): FrameCommentsFile | null {
+  if (!raw.trim()) return null;
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(data) || !Array.isArray(data.comments)) return null;
+  const comments = data.comments
+    .map(parseCommentEntry)
+    .filter((entry): entry is FrameCommentEntry => entry !== null);
+  return {
+    version: 1,
+    pass: parsePass(data.pass),
+    submitted_at: typeof data.submitted_at === "string" ? data.submitted_at : "",
+    comments,
+  };
+}
+
+/**
+ * One file = the currently pending feedback. A resubmit before the agent
+ * consumed the previous batch keeps the pending entries for frames the new
+ * batch doesn't mention and overwrites the ones it does.
+ */
+export function buildCommentsFile(
+  frames: readonly CommentableFrame[],
+  drafts: Readonly<Record<number, string>>,
+  previous: FrameCommentsFile | null,
+  submittedAt: string,
+): FrameCommentsFile {
+  const fresh = draftEntries(frames, drafts);
+  const freshIndexes = new Set(fresh.map((entry) => entry.frame));
+  const kept = previous?.comments.filter((entry) => !freshIndexes.has(entry.frame)) ?? [];
+  const comments = [...kept, ...fresh].sort((a, b) => a.frame - b.frame);
+  return { version: 1, pass: passForFrames(frames), submitted_at: submittedAt, comments };
+}

package/src/components/storyboard/useFrameComments.ts

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useFileManagerContext } from "../../contexts/FileManagerContext";
+import type { StoryboardFrameView } from "../../hooks/useStoryboard";
+import {
+  FRAME_COMMENTS_PATH,
+  buildCommentsFile,
+  parseCommentsFile,
+  type FrameCommentEntry,
+} from "./frameComments";
+
+export type CommentsSubmitState = "idle" | "saving";
+
+export interface FrameCommentsValue {
+  /** Draft text per frame index — "" / absent means no comment. */
+  drafts: Record<number, string>;
+  setDraft: (index: number, text: string) => void;
+  /** How many frames currently carry a non-empty draft. */
+  draftCount: number;
+  submitState: CommentsSubmitState;
+  /** Write the batch to `.hyperframes/frame-comments.json` and clear the drafts. */
+  submit: () => Promise<void>;
+  /**
+   * Comments already submitted but not yet consumed by the agent (the file
+   * still exists on disk). Refreshed on mount, after submit, and on window
+   * focus — the agent deletes the file once it has applied the feedback.
+   */
+  pending: FrameCommentEntry[] | null;
+  /** Re-read the comments file — callers hook this to board data refreshes. */
+  refreshPending: () => Promise<void>;
+}
+
+/** Per-frame comment drafts + the batch submit that writes the comments file. */
+export function useFrameComments(frames: StoryboardFrameView[]): FrameCommentsValue {
+  const { writeProjectFile, readOptionalProjectFile } = useFileManagerContext();
+  const [drafts, setDrafts] = useState<Record<number, string>>({});
+  const [submitState, setSubmitState] = useState<CommentsSubmitState>("idle");
+  const [pending, setPending] = useState<FrameCommentEntry[] | null>(null);
+
+  const refreshPending = useCallback(async () => {
+    try {
+      const parsed = parseCommentsFile(await readOptionalProjectFile(FRAME_COMMENTS_PATH));
+      setPending(parsed && parsed.comments.length > 0 ? parsed.comments : null);
+    } catch {
+      // Transient read failure — keep whatever is currently shown.
+    }
+  }, [readOptionalProjectFile]);
+
+  useEffect(() => {
+    void refreshPending();
+    const onFocus = () => void refreshPending();
+    window.addEventListener("focus", onFocus);
+    return () => window.removeEventListener("focus", onFocus);
+  }, [refreshPending]);
+
+  const setDraft = useCallback((index: number, text: string) => {
+    setDrafts((prev) => ({ ...prev, [index]: text }));
+  }, []);
+
+  const draftCount = useMemo(
+    () => Object.values(drafts).filter((text) => text.trim().length > 0).length,
+    [drafts],
+  );
+
+  const submit = useCallback(async () => {
+    if (draftCount === 0 || submitState === "saving") return;
+    setSubmitState("saving");
+    try {
+      const previous = parseCommentsFile(await readOptionalProjectFile(FRAME_COMMENTS_PATH));
+      const file = buildCommentsFile(frames, drafts, previous, new Date().toISOString());
+      await writeProjectFile(FRAME_COMMENTS_PATH, `${JSON.stringify(file, null, 2)}\n`);
+      setDrafts({});
+      setPending(file.comments);
+    } catch {
+      // writeProjectFile surfaces save failures through the studio save banner;
+      // just re-arm the button so the user can retry.
+    } finally {
+      setSubmitState("idle");
+    }
+  }, [draftCount, submitState, frames, drafts, readOptionalProjectFile, writeProjectFile]);
+
+  return { drafts, setDraft, draftCount, submitState, submit, pending, refreshPending };
+}