@hyperframes/studio 0.7.57 → 0.7.59

package/src/components/nle/zLaneGesture.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it, vi } from "vitest";
+import { runLaneZGesture, runZLaneGesture } from "./zLaneGesture";
+
+const durable = { durable: true, allMatched: true, changed: true };
+
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  let reject!: (e: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+describe("runZLaneGesture", () => {
+  it("runs the mirror after a durable z commit and resolves its result", async () => {
+    const order: string[] = [];
+    const result = await runZLaneGesture({
+      commitZ: async () => {
+        order.push("z");
+        return durable;
+      },
+      mirror: async () => {
+        order.push("mirror");
+        return true;
+      },
+    });
+    expect(result).toBe(true);
+    expect(order).toEqual(["z", "mirror"]);
+  });
+
+  it("skips the mirror when the z commit reports unmatched targets", async () => {
+    const mirror = vi.fn(async () => true);
+    const result = await runZLaneGesture({
+      commitZ: async () => ({ durable: false, allMatched: false, changed: true }),
+      mirror,
+    });
+    expect(result).toBe(false);
+    expect(mirror).not.toHaveBeenCalled();
+  });
+
+  it("still mirrors on a void resolution (empty-entries commit path)", async () => {
+    const mirror = vi.fn(async () => true);
+    await runZLaneGesture({ commitZ: async () => undefined, mirror });
+    expect(mirror).toHaveBeenCalledTimes(1);
+  });
+
+  it("serializes gestures: B's z phase waits for A's mirror phase", async () => {
+    const order: string[] = [];
+    const aMirrorGate = deferred<void>();
+
+    const a = runZLaneGesture({
+      commitZ: async () => {
+        order.push("A:z");
+        return durable;
+      },
+      mirror: async () => {
+        await aMirrorGate.promise;
+        order.push("A:mirror");
+        return true;
+      },
+    });
+    const b = runZLaneGesture({
+      commitZ: async () => {
+        order.push("B:z");
+        return durable;
+      },
+      mirror: async () => {
+        order.push("B:mirror");
+        return true;
+      },
+    });
+
+    // Give B every chance to start early — it must not.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(order).toEqual(["A:z"]);
+
+    aMirrorGate.resolve();
+    await Promise.all([a, b]);
+    expect(order).toEqual(["A:z", "A:mirror", "B:z", "B:mirror"]);
+  });
+
+  it("holds a lane→z gesture until an overlapping z→lane gesture fully settles", async () => {
+    const order: string[] = [];
+    const mirrorGate = deferred<void>();
+    const zFirst = runZLaneGesture({
+      commitZ: async () => {
+        order.push("z-first:z");
+        return durable;
+      },
+      mirror: async () => {
+        order.push("z-first:lane-start");
+        await mirrorGate.promise;
+        order.push("z-first:lane-end");
+        return true;
+      },
+    });
+    const laneFirst = runLaneZGesture({
+      commitLane: async () => {
+        order.push("lane-first:lane");
+        return true;
+      },
+      commitZ: async () => {
+        order.push("lane-first:z");
+      },
+    });
+
+    await Promise.resolve();
+    expect(order).toEqual(["z-first:z", "z-first:lane-start"]);
+    mirrorGate.resolve();
+    await Promise.all([zFirst, laneFirst]);
+    expect(order).toEqual([
+      "z-first:z",
+      "z-first:lane-start",
+      "z-first:lane-end",
+      "lane-first:lane",
+      "lane-first:z",
+    ]);
+  });
+
+  it("holds a z→lane gesture until an overlapping lane→z gesture fully settles", async () => {
+    const order: string[] = [];
+    const zGate = deferred<void>();
+    const laneFirst = runLaneZGesture({
+      commitLane: async () => {
+        order.push("lane-first:lane");
+        return true;
+      },
+      commitZ: async () => {
+        order.push("lane-first:z-start");
+        await zGate.promise;
+        order.push("lane-first:z-end");
+      },
+    });
+    const zFirst = runZLaneGesture({
+      commitZ: async () => {
+        order.push("z-first:z");
+        return durable;
+      },
+      mirror: async () => {
+        order.push("z-first:lane");
+        return true;
+      },
+    });
+
+    await Promise.resolve();
+    expect(order).toEqual(["lane-first:lane", "lane-first:z-start"]);
+    zGate.resolve();
+    await Promise.all([laneFirst, zFirst]);
+    expect(order).toEqual([
+      "lane-first:lane",
+      "lane-first:z-start",
+      "lane-first:z-end",
+      "z-first:z",
+      "z-first:lane",
+    ]);
+  });
+
+  it("a failed gesture rejects its caller but never wedges the queue", async () => {
+    const boom = new Error("z failed");
+    const failed = runZLaneGesture({
+      commitZ: async () => {
+        throw boom;
+      },
+      mirror: async () => true,
+    });
+    await expect(failed).rejects.toBe(boom);
+
+    const next = await runZLaneGesture({
+      commitZ: async () => durable,
+      mirror: async () => true,
+    });
+    expect(next).toBe(true);
+  });
+});

package/src/components/nle/zLaneGesture.ts

@@ -0,0 +1,77 @@
+import type { DomEditPatchBatchesResult } from "../../hooks/domEditCommitTypes";
+
+/**
+ * Run one COMPLETE z→lane gesture — the z-index persist followed by its
+ * timeline lane mirror — as a single serialized transaction.
+ *
+ * Why a queue: the two phases persist through DIFFERENT pipelines (the z patch
+ * rides the DOM-edit save queue, the lane move rides the timeline/SDK move
+ * path). Each gesture orders its own phases by awaiting the z persist, but
+ * without cross-gesture serialization a second rapid gesture can land between
+ * the first gesture's phases and the interleaved file writes can clobber each
+ * other. Canvas z→lane and timeline lane→z gestures both chain through this
+ * single module-level tail, so gesture B cannot start until gesture A settled.
+ *
+ * Why the durability gate: a resolved z commit is not necessarily durable —
+ * when the server cannot match a patch target, commitDomEditPatchBatches
+ * resolves with `durable: false` (after scheduling a reload to
+ * reconverge). Mirroring a lane move onto a z state that disk never held
+ * would desync track order from what actually paints, so the mirror phase is
+ * skipped and the gesture resolves `false`.
+ *
+ * Failures never wedge the queue: a rejected gesture propagates to ITS caller
+ * while the tail continues for the next gesture.
+ */
+let gestureTail: Promise<void> | null = null;
+
+/** The single ordering owner for every gesture that crosses z/lane persistence. */
+export function serializeZLaneGesture<Result>(run: () => Promise<Result>): Promise<Result> {
+  const previous = gestureTail;
+  // Preserve synchronous optimistic updates for the first gesture. A queued
+  // gesture starts only after the preceding gesture fully settled.
+  let gesture: Promise<Result>;
+  if (previous) {
+    gesture = previous.then(run, run);
+  } else {
+    try {
+      gesture = Promise.resolve(run());
+    } catch (error) {
+      gesture = Promise.reject(error);
+    }
+  }
+  const tail = gesture.then(
+    () => undefined,
+    () => undefined,
+  );
+  gestureTail = tail;
+  void tail.then(() => {
+    if (gestureTail === tail) gestureTail = null;
+  });
+  return gesture;
+}
+
+export function runZLaneGesture(input: {
+  /** Phase 1: persist the z patch (handleDomZIndexReorderCommit). */
+  commitZ: () => Promise<DomEditPatchBatchesResult | undefined | void>;
+  /** Phase 2: mirror into a timeline lane move; only runs on a durable phase 1. */
+  mirror: () => Promise<boolean>;
+}): Promise<boolean> {
+  const run = async (): Promise<boolean> => {
+    const result = await input.commitZ();
+    if (result && !result.durable) return false;
+    return input.mirror();
+  };
+  return serializeZLaneGesture(run);
+}
+
+/** Run one lane→z gesture under the same owner as canvas z→lane gestures. */
+export function runLaneZGesture(input: {
+  commitLane: () => Promise<boolean>;
+  commitZ: () => Promise<void>;
+}): Promise<boolean> {
+  return serializeZLaneGesture(async () => {
+    if (!(await input.commitLane())) return false;
+    await input.commitZ();
+    return true;
+  });
+}

package/src/components/panels/VariablesPanel.tsx

@@ -6,6 +6,7 @@ import type {
   VariableValidationIssue,
 } from "@hyperframes/sdk";
 import type { EditHistoryKind } from "../../utils/editHistory";
+import type { PublishSdkSession } from "../../utils/sdkCutover";
 import { useStudioPlaybackContext, useStudioShellContext } from "../../contexts/StudioContext";
 import { useDomEditContext } from "../../contexts/DomEditContext";
 import { useFileManagerContext } from "../../contexts/FileManagerContext";
@@ -32,6 +33,7 @@ function shellSingleQuote(value: string): string {
 
 interface VariablesPanelProps {
   sdkSession: Composition | null;
+  publishSdkSession: PublishSdkSession;
   reloadPreview: () => void;
   domEditSaveTimestampRef: MutableRefObject<number>;
   recordEdit: (entry: {
@@ -247,6 +249,7 @@ const EMPTY_STATE = (
 // fallow-ignore-next-line complexity
 export const VariablesPanel = memo(function VariablesPanel({
   sdkSession,
+  publishSdkSession,
   reloadPreview,
   domEditSaveTimestampRef,
   recordEdit,
@@ -285,6 +288,7 @@ export const VariablesPanel = memo(function VariablesPanel({
     recordEdit,
     reloadPreview,
     domEditSaveTimestampRef,
+    publishSdkSession,
   });
 
   const declarations = useMemo(

package/src/components/sidebar/CompositionsTab.test.ts

@@ -1,5 +1,9 @@
-import { describe, expect, it } from "vitest";
-import { resolveCompositionPreviewScale, resolveThumbnailSeekTime } from "./CompositionsTab";
+import { describe, expect, it, vi } from "vitest";
+import {
+  resolveCompositionPreviewScale,
+  resolveThumbnailSeekTime,
+  syncIframePlayback,
+} from "./CompositionsTab";
 
 describe("resolveCompositionPreviewScale", () => {
   it("scales a 16:9 stage to fit the composition card", () => {
@@ -50,3 +54,25 @@ describe("resolveThumbnailSeekTime", () => {
     expect(resolveThumbnailSeekTime(Number.NaN)).toBe(3);
   });
 });
+
+describe("syncIframePlayback", () => {
+  it("mutes a composition-card preview before playing it", () => {
+    const calls: string[] = [];
+    const postMessage = vi.fn(() => calls.push("mute"));
+    const player = {
+      play: vi.fn(() => calls.push("play")),
+    };
+    const iframe = {
+      contentWindow: { __player: player, postMessage },
+      getRootNode: () => ({}),
+    } as unknown as HTMLIFrameElement;
+
+    expect(syncIframePlayback(iframe, true)).toBe(true);
+    expect(postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ action: "set-muted", muted: true }),
+      "*",
+    );
+    expect(calls).toEqual(["mute", "play"]);
+    expect(player.play).toHaveBeenCalledOnce();
+  });
+});

package/src/components/sidebar/CompositionsTab.tsx

@@ -1,4 +1,5 @@
 import { memo, useCallback, useEffect, useRef, useState } from "react";
+import { setPreviewMediaMuted } from "../../player/lib/timelineIframeHelpers";
 
 interface CompositionsTabProps {
   projectId: string;
@@ -87,12 +88,13 @@ function resolveIframeDuration(iframe: HTMLIFrameElement | null): number | null
   }
 }
 
-function syncIframePlayback(iframe: HTMLIFrameElement | null, shouldPlay: boolean): boolean {
+export function syncIframePlayback(iframe: HTMLIFrameElement | null, shouldPlay: boolean): boolean {
   try {
     const player = (iframe?.contentWindow as PreviewWindow | null)?.__player;
     if (!player) return false;
 
     if (shouldPlay) {
+      setPreviewMediaMuted(iframe, true);
       player.play?.();
       return true;
     }

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 }) {