feat(studio): storyboard frame contact-sheet grid

Third PR in the Studio storyboarding stack. Renders the frames as a live
contact sheet inside the storyboard view.

- StoryboardGrid: ordered, responsive grid of frame tiles.
- StoryboardFrameTile: number badge, scaled non-interactive live preview
  iframe (via /api/projects/:id/preview/comp/<src>), title, duration,
  transition, and a status chip (outline / built / animated).
- Frames that are outline-only or whose src is missing render an explicit
  placeholder instead of an iframe.
- StoryboardView swaps its placeholder for the real grid.

With PR1-PR3 the storyboard view is end-to-end viewable against the
storyboard-sample fixture for UI/UX feedback.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jrusso1020

packages/studio/src/components/storyboard/StoryboardDirection.tsx

@@ -13,6 +13,7 @@ export function StoryboardDirection({ globals, frameCount }: StoryboardDirection
   const meta = [
     { label: "Arc", value: globals.arc },
     { label: "Audience", value: globals.audience },
+    { label: "Voice", value: globals.extra.voice },
     { label: "Format", value: globals.format },
     { label: "Frames", value: String(frameCount) },
   ].filter((item): item is { label: string; value: string } => Boolean(item.value));

packages/studio/src/components/storyboard/StoryboardFrameTile.tsx

@@ -0,0 +1,166 @@
+import { useEffect, useRef } from "react";
+import type { FrameStatus } from "@hyperframes/core/storyboard";
+import type { StoryboardFrameView } from "../../hooks/useStoryboard";
+import { FRAME_STATUS_META } from "./frameStatus";
+
+export interface StoryboardFrameTileProps {
+  projectId: string;
+  frame: StoryboardFrameView;
+}
+
+// Frames author at 1920×1080; tiles render a scaled, non-interactive preview.
+const TILE_WIDTH = 360;
+const FRAME_WIDTH = 1920;
+const FRAME_HEIGHT = 1080;
+const SCALE = TILE_WIDTH / FRAME_WIDTH;
+// Compositions are seek-driven at the canonical 30fps; tiles seek by frame index.
+const PREVIEW_FPS = 30;
+
+const STATUS_CHIP: Record<FrameStatus, string> = {
+  outline: "bg-neutral-800 text-neutral-300",
+  built: "bg-sky-500/20 text-sky-300",
+  animated: "bg-emerald-500/20 text-emerald-300",
+};
+
+/** Time (seconds) to show a tile at — past the intro so the key moment is visible. */
+function posterTime(frame: StoryboardFrameView): number {
+  if (frame.poster != null) return frame.poster;
+  if (frame.durationSeconds != null) return frame.durationSeconds * 0.66;
+  return 1.5;
+}
+
+function firstLine(text: string): string {
+  return (
+    text
+      .split("\n")
+      .find((line) => line.trim().length > 0)
+      ?.trim() ?? ""
+  );
+}
+
+/** True for the runtime's `{ source: "hf-preview", type: "ready" }` announcement. */
+function isReadyMessage(data: unknown): boolean {
+  const msg = data as { source?: string; type?: string } | null;
+  return msg !== null && msg.source === "hf-preview" && msg.type === "ready";
+}
+
+function placeholderMessage(frame: StoryboardFrameView): string {
+  if (frame.status === "outline") return "Not built yet";
+  if (frame.src && !frame.srcExists) return "Frame file not found";
+  return "No preview";
+}
+
+/** A single contact-sheet tile: live frame preview + its metadata. */
+// fallow-ignore-next-line complexity
+export function StoryboardFrameTile({ projectId, frame }: StoryboardFrameTileProps) {
+  const meta = FRAME_STATUS_META[frame.status];
+  const renderable = frame.srcExists && frame.status !== "outline";
+  const title = frame.title ?? `Frame ${frame.index}`;
+  const sceneLine = frame.scene ?? firstLine(frame.narrative);
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  useTilePosterSeek(iframeRef, renderable, posterTime(frame));
+
+  return (
+    <article className="w-[360px]">
+      <div className="relative overflow-hidden rounded-lg border border-neutral-800 bg-neutral-900">
+        <div className="absolute left-2 top-2 z-10 flex h-6 min-w-6 items-center justify-center rounded-full bg-black/70 px-1.5 text-xs font-semibold text-neutral-100">
+          {frame.number ?? frame.index}
+        </div>
+        <div
+          style={{ width: TILE_WIDTH, height: TILE_WIDTH * (FRAME_HEIGHT / FRAME_WIDTH) }}
+          className="relative"
+        >
+          {renderable && frame.src ? (
+            <iframe
+              ref={iframeRef}
+              title={title}
+              src={`/api/projects/${projectId}/preview/comp/${frame.src}`}
+              width={FRAME_WIDTH}
+              height={FRAME_HEIGHT}
+              tabIndex={-1}
+              style={{
+                border: 0,
+                transformOrigin: "top left",
+                transform: `scale(${SCALE})`,
+                pointerEvents: "none",
+              }}
+            />
+          ) : (
+            <FrameTilePlaceholder frame={frame} />
+          )}
+        </div>
+      </div>
+
+      <div className="mt-2 flex items-start justify-between gap-2">
+        <h3 className="truncate text-sm font-medium text-neutral-200">{title}</h3>
+        <span
+          title={meta.tooltip}
+          className={`shrink-0 cursor-default rounded px-1.5 py-0.5 text-[10px] font-medium uppercase tracking-wide ${STATUS_CHIP[frame.status]}`}
+        >
+          {meta.label}
+        </span>
+      </div>
+      {sceneLine && <p className="mt-0.5 line-clamp-2 text-xs text-neutral-400">{sceneLine}</p>}
+      {frame.voiceover && (
+        <p className="mt-1 line-clamp-2 text-xs italic text-neutral-500">
+          <span aria-hidden="true">🎙 </span>“{frame.voiceover}”
+        </p>
+      )}
+      <div className="mt-1 flex gap-3 text-[11px] text-neutral-600">
+        {frame.duration && <span>{frame.duration}</span>}
+        {frame.transitionIn && <span>↘ {frame.transitionIn}</span>}
+      </div>
+    </article>
+  );
+}
+
+/**
+ * Seek the tile's preview iframe to its poster time once the runtime is ready,
+ * so frames whose content animates in from t=0 aren't shown blank. The runtime
+ * announces readiness via a `hf-preview` `ready` message; we reply with a seek
+ * control command (and also retry on load as a race-safe fallback).
+ */
+function useTilePosterSeek(
+  iframeRef: React.RefObject<HTMLIFrameElement | null>,
+  renderable: boolean,
+  seconds: number,
+): void {
+  useEffect(() => {
+    if (!renderable) return;
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+    const targetFrame = Math.max(0, Math.round(seconds * PREVIEW_FPS));
+    const sendSeek = () => {
+      iframe.contentWindow?.postMessage(
+        {
+          source: "hf-parent",
+          type: "control",
+          action: "seek",
+          frame: targetFrame,
+          seekMode: "commit",
+        },
+        "*",
+      );
+    };
+    const onMessage = (event: MessageEvent) => {
+      if (event.source === iframe.contentWindow && isReadyMessage(event.data)) sendSeek();
+    };
+    const onLoad = () => window.setTimeout(sendSeek, 150);
+    window.addEventListener("message", onMessage);
+    iframe.addEventListener("load", onLoad);
+    return () => {
+      window.removeEventListener("message", onMessage);
+      iframe.removeEventListener("load", onLoad);
+    };
+  }, [iframeRef, renderable, seconds]);
+}
+
+function FrameTilePlaceholder({ frame }: { frame: StoryboardFrameView }) {
+  const message = placeholderMessage(frame);
+  return (
+    <div className="flex h-full w-full flex-col items-center justify-center gap-1 border border-dashed border-neutral-700 bg-neutral-950 text-center">
+      <span className="text-xs font-medium text-neutral-400">{frame.title ?? "Outline"}</span>
+      <span className="text-[11px] text-neutral-600">{message}</span>
+    </div>
+  );
+}

packages/studio/src/components/storyboard/StoryboardGrid.tsx

@@ -0,0 +1,26 @@
+import type { StoryboardFrameView } from "../../hooks/useStoryboard";
+import { StoryboardFrameTile } from "./StoryboardFrameTile";
+
+export interface StoryboardGridProps {
+  projectId: string;
+  frames: StoryboardFrameView[];
+}
+
+/** The contact sheet: ordered frame tiles in a responsive grid. */
+export function StoryboardGrid({ projectId, frames }: 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">
+        This storyboard has no frames yet.
+      </div>
+    );
+  }
+
+  return (
+    <div className="mt-8 flex flex-wrap gap-x-6 gap-y-8">
+      {frames.map((frame) => (
+        <StoryboardFrameTile key={frame.index} projectId={projectId} frame={frame} />
+      ))}
+    </div>
+  );
+}

packages/studio/src/components/storyboard/StoryboardScriptPanel.tsx

@@ -0,0 +1,26 @@
+import type { StoryboardScript } from "../../hooks/useStoryboard";
+
+export interface StoryboardScriptPanelProps {
+  script: StoryboardScript;
+}
+
+/**
+ * Collapsible view of the companion narration script (SCRIPT.md). The mature
+ * pipeline keeps the full voiceover script — voice settings, per-line delivery
+ * and timing — in this file; here it's surfaced read-only alongside the frames.
+ * (Per-frame VO iteration will live in the frame focus view.)
+ */
+export function StoryboardScriptPanel({ script }: StoryboardScriptPanelProps) {
+  if (!script.exists) return null;
+  return (
+    <details className="mt-10 rounded-lg border border-neutral-800 bg-neutral-900/50">
+      <summary className="cursor-pointer select-none px-4 py-3 text-sm font-medium text-neutral-300">
+        Narration script
+        <span className="ml-2 font-normal text-neutral-500">{script.path}</span>
+      </summary>
+      <pre className="max-h-[420px] overflow-auto whitespace-pre-wrap border-t border-neutral-800 px-4 py-3 text-xs leading-relaxed text-neutral-400">
+        {script.content}
+      </pre>
+    </details>
+  );
+}

packages/studio/src/components/storyboard/StoryboardStatusLegend.tsx

@@ -0,0 +1,27 @@
+import { FRAME_STATUS_META, FRAME_STATUS_ORDER } from "./frameStatus";
+
+const DOT: Record<string, string> = {
+  outline: "bg-neutral-500",
+  built: "bg-sky-400",
+  animated: "bg-emerald-400",
+};
+
+/**
+ * Explains the frame lifecycle: a frame advances outline → built → animated.
+ * Mirrors the status chips on each tile.
+ */
+export function StoryboardStatusLegend() {
+  return (
+    <div className="flex flex-wrap items-center gap-x-5 gap-y-1.5 text-[11px] text-neutral-500">
+      <span className="uppercase tracking-wider text-neutral-600">Status</span>
+      {FRAME_STATUS_ORDER.map((status, i) => (
+        <span key={status} className="flex items-center gap-1.5">
+          {i > 0 && <span className="text-neutral-700">→</span>}
+          <span className={`h-2 w-2 rounded-full ${DOT[status]}`} />
+          <span className="font-medium text-neutral-300">{FRAME_STATUS_META[status].label}</span>
+          <span className="text-neutral-500">— {FRAME_STATUS_META[status].description}</span>
+        </span>
+      ))}
+    </div>
+  );
+}

packages/studio/src/components/storyboard/StoryboardView.tsx

@@ -1,15 +1,18 @@
 import type { ReactNode } from "react";
 import { useStoryboard } from "../../hooks/useStoryboard";
 import { StoryboardDirection } from "./StoryboardDirection";
+import { StoryboardGrid } from "./StoryboardGrid";
+import { StoryboardStatusLegend } from "./StoryboardStatusLegend";
+import { StoryboardScriptPanel } from "./StoryboardScriptPanel";
 
 export interface StoryboardViewProps {
   projectId: string;
 }
 
 /**
  * Top-level storyboard stage. Replaces the timeline/preview when the view mode
- * is `storyboard`. PR2 lands the shell (global direction + states); the frame
- * contact-sheet grid arrives in PR3.
+ * is `storyboard`: renders the global direction plus the frame contact sheet,
+ * with loading / error / empty states.
  */
 // fallow-ignore-next-line complexity
 export function StoryboardView({ projectId }: StoryboardViewProps) {
@@ -35,11 +38,11 @@ export function StoryboardView({ projectId }: StoryboardViewProps) {
   return (
     <StoryboardFrame>
       <StoryboardDirection globals={data.globals} frameCount={data.frames.length} />
-      {/* PR3: frame contact-sheet grid renders here. */}
-      <div className="mt-8 rounded-lg border border-dashed border-neutral-800 px-6 py-12 text-center text-sm text-neutral-500">
-        {data.frames.length} frame{data.frames.length === 1 ? "" : "s"} parsed — the contact sheet
-        renders here next.
+      <div className="mt-5">
+        <StoryboardStatusLegend />
       </div>
+      <StoryboardGrid projectId={projectId} frames={data.frames} />
+      {data.script && <StoryboardScriptPanel script={data.script} />}
     </StoryboardFrame>
   );
 }

packages/studio/src/components/storyboard/frameStatus.ts

@@ -0,0 +1,26 @@
+import type { FrameStatus } from "@hyperframes/core/storyboard";
+
+/** Display metadata for each frame lifecycle status, shared by tiles and the legend. */
+export const FRAME_STATUS_META: Record<
+  FrameStatus,
+  { label: string; tooltip: string; description: string }
+> = {
+  outline: {
+    label: "Outline",
+    tooltip: "Planned in text — no HTML frame built yet.",
+    description: "Planned in text. Story and intent exist; the visual isn’t built.",
+  },
+  built: {
+    label: "Built",
+    tooltip: "Static HTML frame built — not animated yet.",
+    description: "The HTML frame exists as a static key moment. Look is locked; motion isn’t.",
+  },
+  animated: {
+    label: "Animated",
+    tooltip: "Keyframed and animated — plays in the final cut.",
+    description: "Keyframed into motion. This is the file stitched into the final video.",
+  },
+};
+
+/** The lifecycle order an agent advances each frame through. */
+export const FRAME_STATUS_ORDER: FrameStatus[] = ["outline", "built", "animated"];

packages/studio/src/hooks/useStoryboard.ts

@@ -11,13 +11,21 @@ export interface StoryboardFrameView extends StoryboardFrame {
   srcExists: boolean;
 }
 
+/** The companion narration script (SCRIPT.md), when present alongside the storyboard. */
+export interface StoryboardScript {
+  exists: boolean;
+  path: string;
+  content: string;
+}
+
 /** Shape of `GET /api/projects/:id/storyboard`. */
 export interface StoryboardResponse {
   exists: boolean;
   path: string;
   globals: StoryboardGlobals;
   frames: StoryboardFrameView[];
   warnings: StoryboardWarning[];
+  script?: StoryboardScript;
 }
 
 export interface UseStoryboardResult {