feat(studio): add storyboard manifest contract, parser, and read API (#1528)

First PR in the Studio storyboarding stack. Establishes the parseable
contract the storyboard UI reads from; no UI yet.

- core/storyboard: StoryboardManifest/Frame/Globals types + a lenient
  STORYBOARD.md parser (frontmatter + status/src/duration/transition_in,
  freeform narrative tolerated, never throws, records warnings). Exposed as
  @hyperframes/core/storyboard (browser-safe).
- studio-api: GET /projects/:id/storyboard returns the normalized manifest
  with per-frame srcExists; missing file -> exists:false, not 404.
- fixture: packages/studio/fixtures/storyboard-sample for dogfooding the
  storyboard view in later PRs (built/animated frames + one outline).

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

.gitignore

@@ -142,3 +142,5 @@ docs/superpowers/
 .worktrees
 hyperframes-bench/
 tmp/
+# Studio-generated preview thumbnails
+.thumbnails/

packages/core/package.json

@@ -42,6 +42,10 @@
       "import": "./src/colorLuts.ts",
       "types": "./src/colorLuts.ts"
     },
+    "./storyboard": {
+      "import": "./src/storyboard/index.ts",
+      "types": "./src/storyboard/index.ts"
+    },
     "./runtime": "./dist/hyperframe.runtime.iife.js",
     "./runtime/clipTree": {
       "import": "./src/runtime/clipTree.ts",

packages/core/src/storyboard/index.ts

@@ -0,0 +1,12 @@
+export {
+  STORYBOARD_FILENAME,
+  SCRIPT_FILENAME,
+  FRAME_STATUSES,
+  DEFAULT_FRAME_STATUS,
+  type FrameStatus,
+  type StoryboardGlobals,
+  type StoryboardFrame,
+  type StoryboardWarning,
+  type StoryboardManifest,
+} from "./types.js";
+export { parseStoryboard } from "./parseStoryboard.js";

packages/core/src/storyboard/parseStoryboard.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect } from "vitest";
+import { parseStoryboard } from "./parseStoryboard.js";
+
+const STRUCTURED = `---
+format: 1920x1080
+message: "Ship a launch video in an afternoon"
+arc: Problem → Solution
+audience: indie devs on X
+---
+
+## Frame 1 — Hook
+- duration: 4s
+- transition_in: cut
+- status: built
+- src: compositions/frames/01-hook.html
+
+A bold opening line lands on the beat.
+
+## Frame 2 — The feature in action
+- duration: 6s
+- transition_in: crossfade
+- status: animated
+- src: compositions/frames/02-feature.html
+
+The diff animates line by line as the narration says "...".
+`;
+
+describe("parseStoryboard", () => {
+  it("parses global frontmatter direction", () => {
+    const { globals } = parseStoryboard(STRUCTURED);
+    expect(globals.format).toBe("1920x1080");
+    expect(globals.message).toBe("Ship a launch video in an afternoon");
+    expect(globals.arc).toBe("Problem → Solution");
+    expect(globals.audience).toBe("indie devs on X");
+    expect(globals.extra).toEqual({});
+  });
+
+  it("parses ordered frames with metadata and narrative", () => {
+    const { frames } = parseStoryboard(STRUCTURED);
+    expect(frames).toHaveLength(2);
+
+    const [f1, f2] = frames;
+    expect(f1).toMatchObject({
+      index: 1,
+      number: 1,
+      title: "Hook",
+      status: "built",
+      src: "compositions/frames/01-hook.html",
+      duration: "4s",
+      durationSeconds: 4,
+      transitionIn: "cut",
+    });
+    expect(f1.narrative).toBe("A bold opening line lands on the beat.");
+
+    expect(f2).toMatchObject({
+      index: 2,
+      number: 2,
+      title: "The feature in action",
+      status: "animated",
+      durationSeconds: 6,
+      transitionIn: "crossfade",
+    });
+    expect(f2.narrative).toContain("animates line by line");
+  });
+
+  it("defaults status to outline and reports no warnings for clean input", () => {
+    const { frames, warnings } = parseStoryboard(STRUCTURED);
+    expect(frames.every((f) => f.status !== undefined)).toBe(true);
+    expect(warnings).toEqual([]);
+  });
+
+  it("defaults missing status to outline", () => {
+    const { frames } = parseStoryboard("## Frame 1 — Idea\n\nJust a thought.");
+    expect(frames[0].status).toBe("outline");
+    expect(frames[0].src).toBeUndefined();
+    expect(frames[0].narrative).toBe("Just a thought.");
+  });
+
+  it("warns on unknown status and falls back to outline, preserving the raw value", () => {
+    const { frames, warnings } = parseStoryboard("## Frame 1\n- status: wip\n");
+    expect(frames[0].status).toBe("outline");
+    expect(frames[0].extra.status).toBe("wip");
+    expect(warnings.some((w) => w.frameIndex === 1 && /unknown status/i.test(w.message))).toBe(
+      true,
+    );
+  });
+
+  it("warns on unparseable duration", () => {
+    const { frames, warnings } = parseStoryboard("## Frame 1\n- duration: a while\n");
+    expect(frames[0].duration).toBe("a while");
+    expect(frames[0].durationSeconds).toBeUndefined();
+    expect(warnings.some((w) => /could not parse duration/i.test(w.message))).toBe(true);
+  });
+
+  it("preserves unknown frontmatter and frame metadata keys in extra", () => {
+    const { globals, frames } = parseStoryboard(
+      "---\nmood: playful\n---\n## Frame 1\n- voice: Rachel\n- status: built\n",
+    );
+    expect(globals.extra.mood).toBe("playful");
+    expect(frames[0].extra.voice).toBe("Rachel");
+  });
+
+  it("parses scene, voiceover, and poster fields with aliases", () => {
+    const md = `## Frame 1 — Hook
+- scene: A bold line punches in on the beat
+- vo: "Ship a launch video in an afternoon."
+- poster: 2.5s
+
+Longer narrative here.`;
+    const { frames } = parseStoryboard(md);
+    expect(frames[0].scene).toBe("A bold line punches in on the beat");
+    expect(frames[0].voiceover).toBe("Ship a launch video in an afternoon.");
+    expect(frames[0].poster).toBe(2.5);
+    expect(frames[0].narrative).toBe("Longer narrative here.");
+  });
+
+  it("accepts description/voiceover/narration aliases", () => {
+    const { frames } = parseStoryboard(
+      "## Frame 1\n- description: one liner\n- voiceover: spoken line\n",
+    );
+    expect(frames[0].scene).toBe("one liner");
+    expect(frames[0].voiceover).toBe("spoken line");
+  });
+
+  it("is lenient: accepts Beat/Scene headings at H2 or H3", () => {
+    const md = "## Scene 1 — Open\n\nWide shot.\n\n### Beat 2.1 — Punch\n\nClose up.";
+    const { frames } = parseStoryboard(md);
+    expect(frames).toHaveLength(2);
+    expect(frames[0].title).toBe("Open");
+    expect(frames[1].number).toBe(2);
+  });
+
+  it("keeps deeper sub-headings inside a frame as narrative", () => {
+    const md = `## Frame 1 — Demo
+- duration: 6s
+
+Intro line.
+
+#### Beats
+The diff animates line by line.
+
+## Frame 2 — Close
+
+Ending.`;
+    const { frames } = parseStoryboard(md);
+    expect(frames).toHaveLength(2);
+    expect(frames[0].narrative).toContain("Intro line.");
+    expect(frames[0].narrative).toContain("#### Beats");
+    expect(frames[0].narrative).toContain("The diff animates line by line.");
+    expect(frames[1].title).toBe("Close");
+  });
+
+  it("ignores non-frame headings between frames (e.g. Fonts, Color palette)", () => {
+    const md = `## Frame 1 — Hook
+
+Opening.
+
+## Fonts
+
+| Role | File |
+
+## Frame 2 — Close
+
+Ending.`;
+    const { frames } = parseStoryboard(md);
+    expect(frames.map((f) => f.title)).toEqual(["Hook", "Close"]);
+    expect(frames[0].narrative).toBe("Opening.");
+  });
+
+  it("handles missing/empty input without throwing", () => {
+    expect(parseStoryboard("")).toEqual({ globals: { extra: {} }, frames: [], warnings: [] });
+    const noFrontmatter = parseStoryboard("# Title\n\nNo frames here.");
+    expect(noFrontmatter.frames).toEqual([]);
+  });
+
+  it("warns on unterminated frontmatter and treats whole file as body", () => {
+    const { frames, warnings } = parseStoryboard("---\nmessage: hi\n## Frame 1\n\nBody.");
+    expect(warnings.some((w) => /no closing/i.test(w.message))).toBe(true);
+    expect(frames).toHaveLength(1);
+  });
+});

packages/core/src/storyboard/parseStoryboard.ts

@@ -0,0 +1,351 @@
+import {
+  DEFAULT_FRAME_STATUS,
+  FRAME_STATUSES,
+  type FrameStatus,
+  type StoryboardFrame,
+  type StoryboardGlobals,
+  type StoryboardManifest,
+  type StoryboardWarning,
+} from "./types.js";
+
+/**
+ * Lenient parser for `STORYBOARD.md`.
+ *
+ * The canonical (structured) format is:
+ *
+ * ```markdown
+ * ---
+ * format: 1920x1080
+ * message: "Ship a launch video in an afternoon"
+ * arc: Problem → Solution
+ * audience: indie devs on X
+ * ---
+ *
+ * ## Frame 3 — The feature in action
+ * - duration: 6s
+ * - transition_in: crossfade
+ * - status: animated
+ * - src: compositions/frames/03-feature.html
+ *
+ * The diff animates line by line as the narration says "...".
+ * ```
+ *
+ * The parser is deliberately tolerant: it never throws, it accepts freeform
+ * narrative, it recognizes `Frame` / `Beat` / `Scene` section headings at H2 or
+ * H3, and it records anything surprising as a {@link StoryboardWarning} rather
+ * than failing. Unknown frontmatter / metadata keys are preserved in `extra`.
+ */
+export function parseStoryboard(source: string): StoryboardManifest {
+  const warnings: StoryboardWarning[] = [];
+  const { globals, bodyStartLine, body } = parseFrontmatter(source, warnings);
+  const frames = parseFrames(body, bodyStartLine, warnings);
+  return { globals, frames, warnings };
+}
+
+// Headings that begin a frame section: `## Frame N`, `### Beat 1.1`, `## Scene 2`.
+// Detection-only (ends at the keyword) — the title is sliced off in code. A single
+// `[ \t]+` before the required keyword stays linear; avoids the polynomial backtracking
+// a trailing `[\s…]*(.*)$` would add on tab-heavy input (CodeQL js/polynomial-redos).
+const FRAME_HEADING_RE = /^(#{2,3})[ \t]+(?:frame|beat|scene)\b/i;
+/** Leading separators between the frame keyword and its title text. */
+const FRAME_TITLE_SEP_RE = /^[\s.:—-]+/;
+/** Any markdown heading; captures the `#` run so section depth can be compared. */
+const HEADING_LEVEL_RE = /^(#{1,6})\s+/;
+/** A metadata list item: `- key: value` or `* key: value`. */
+const META_RE = /^\s*[-*]\s+([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/;
+/** Leading integer of a frame label, e.g. `3` in `3 — Title` or `1` in `1.1`. */
+const LEADING_INT_RE = /^(\d+)/;
+/** First numeric token in a duration string, e.g. `6` in `6s`, `6.5` in `6.5 sec`. */
+const DURATION_NUM_RE = /(\d+(?:\.\d+)?)/;
+/** Metadata keys that all map to the transition-in field. */
+const TRANSITION_KEYS = new Set(["transition_in", "transitionin", "transition"]);
+/** Metadata keys that all map to the one-line scene description. */
+const SCENE_KEYS = new Set(["scene", "description", "summary", "caption"]);
+/** Metadata keys that all map to the voiceover/narration line. */
+const VOICEOVER_KEYS = new Set(["voiceover", "vo", "voice_over", "narration"]);
+
+interface FrontmatterResult {
+  globals: StoryboardGlobals;
+  /** 1-based line number where the body (post-frontmatter) begins. */
+  bodyStartLine: number;
+  body: string;
+}
+
+function emptyGlobals(): StoryboardGlobals {
+  return { extra: {} };
+}
+
+function isFrameStatus(value: string): value is FrameStatus {
+  return (FRAME_STATUSES as readonly string[]).includes(value);
+}
+
+// ── Frontmatter ───────────────────────────────────────────────────────────────
+
+/** Locate the `---`-delimited frontmatter block, or null when there is none. */
+function findFrontmatterRange(
+  lines: string[],
+  warnings: StoryboardWarning[],
+): { start: number; end: number } | null {
+  let start = 0;
+  while (start < lines.length && (lines[start] ?? "").trim() === "") start++;
+  if ((lines[start] ?? "").trim() !== "---") return null;
+
+  for (let i = start + 1; i < lines.length; i++) {
+    if ((lines[i] ?? "").trim() === "---") return { start, end: i };
+  }
+  warnings.push({
+    message: "Frontmatter opening '---' has no closing '---'; treating whole file as body.",
+    line: start + 1,
+  });
+  return null;
+}
+
+function parseFrontmatterEntries(
+  lines: string[],
+  start: number,
+  end: number,
+  warnings: StoryboardWarning[],
+): StoryboardGlobals {
+  const globals = emptyGlobals();
+  for (let i = start + 1; i < end; i++) {
+    const raw = lines[i] ?? "";
+    if (raw.trim() === "") continue;
+    const colon = raw.indexOf(":");
+    if (colon === -1) {
+      warnings.push({
+        message: `Ignored non key:value frontmatter line: "${raw.trim()}"`,
+        line: i + 1,
+      });
+      continue;
+    }
+    const key = raw.slice(0, colon).trim().toLowerCase();
+    assignGlobal(globals, key, stripQuotes(raw.slice(colon + 1).trim()));
+  }
+  return globals;
+}
+
+function parseFrontmatter(source: string, warnings: StoryboardWarning[]): FrontmatterResult {
+  const lines = source.split(/\r?\n/);
+  const range = findFrontmatterRange(lines, warnings);
+  if (!range) return { globals: emptyGlobals(), bodyStartLine: 1, body: source };
+
+  const globals = parseFrontmatterEntries(lines, range.start, range.end, warnings);
+  const body = lines.slice(range.end + 1).join("\n");
+  return { globals, bodyStartLine: range.end + 2, body };
+}
+
+function assignGlobal(globals: StoryboardGlobals, key: string, value: string): void {
+  switch (key) {
+    case "format":
+      globals.format = value;
+      break;
+    case "message":
+      globals.message = value;
+      break;
+    case "arc":
+      globals.arc = value;
+      break;
+    case "audience":
+      globals.audience = value;
+      break;
+    default:
+      globals.extra[key] = value;
+  }
+}
+
+// ── Frames ────────────────────────────────────────────────────────────────────
+
+interface FrameSection {
+  headingText: string;
+  headingLine: number;
+  /** Heading depth (number of leading `#`) that opened this frame section. */
+  level: number;
+  lines: string[];
+}
+
+/** Open a new frame section if `line` is a frame heading, else null. */
+function openFrameSection(line: string, headingLine: number): FrameSection | null {
+  const match = FRAME_HEADING_RE.exec(line);
+  if (!match) return null;
+  const headingText = line.slice(match[0].length).replace(FRAME_TITLE_SEP_RE, "").trim();
+  return { headingText, headingLine, level: (match[1] ?? "##").length, lines: [] };
+}
+
+/**
+ * Whether `line` ends the current frame: a non-frame heading at the same or
+ * shallower depth (e.g. a sibling `## Fonts`). Deeper sub-headings (e.g.
+ * `#### Beats`) stay part of the frame's narrative.
+ */
+function endsFrameSection(line: string, current: FrameSection | null): boolean {
+  if (!current) return false;
+  const heading = HEADING_LEVEL_RE.exec(line);
+  return heading !== null && (heading[1] ?? "").length <= current.level;
+}
+
+function parseFrames(
+  body: string,
+  bodyStartLine: number,
+  warnings: StoryboardWarning[],
+): StoryboardFrame[] {
+  const lines = body.split(/\r?\n/);
+  const sections: FrameSection[] = [];
+  let current: FrameSection | null = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const opened = openFrameSection(line, bodyStartLine + i);
+    if (opened) {
+      sections.push(opened);
+      current = opened;
+    } else if (endsFrameSection(line, current)) {
+      current = null;
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+
+  return sections.map((section, idx) => buildFrame(section, idx + 1, warnings));
+}
+
+function buildFrame(
+  section: FrameSection,
+  index: number,
+  warnings: StoryboardWarning[],
+): StoryboardFrame {
+  const frame: StoryboardFrame = { index, status: DEFAULT_FRAME_STATUS, narrative: "", extra: {} };
+
+  const { number, title } = parseHeading(section.headingText);
+  if (number !== undefined) frame.number = number;
+  if (title) frame.title = title;
+
+  const narrativeLines: string[] = [];
+  for (const line of section.lines) {
+    const meta = META_RE.exec(line);
+    if (meta) {
+      applyMeta(
+        frame,
+        (meta[1] ?? "").toLowerCase(),
+        (meta[2] ?? "").trim(),
+        section.headingLine,
+        warnings,
+      );
+    } else {
+      narrativeLines.push(line);
+    }
+  }
+  frame.narrative = narrativeLines.join("\n").trim();
+  return frame;
+}
+
+function parseHeading(text: string): { number?: number; title?: string } {
+  if (!text) return {};
+  const intMatch = LEADING_INT_RE.exec(text);
+  if (!intMatch) return { title: text };
+
+  const number = Number.parseInt(intMatch[1] ?? "", 10);
+  const rest = text
+    .slice((intMatch[0] ?? "").length)
+    .replace(/^[\s.:—-]+/, "")
+    .trim();
+  return { number, title: rest || undefined };
+}
+
+/** Setter for a recognized metadata key. Extra trailing args are ignored by simple setters. */
+type MetaSetter = (
+  frame: StoryboardFrame,
+  value: string,
+  headingLine: number,
+  warnings: StoryboardWarning[],
+) => void;
+
+/** Map of metadata key (and aliases) → setter. Keeps {@link applyMeta} a flat dispatch. */
+const META_SETTERS = new Map<string, MetaSetter>([
+  ["duration", applyDuration],
+  ["status", applyStatus],
+  ["poster", applyPoster],
+  [
+    "src",
+    (frame, value) => {
+      frame.src = value;
+    },
+  ],
+  ...keyedSetters(TRANSITION_KEYS, (frame, value) => {
+    frame.transitionIn = value;
+  }),
+  ...keyedSetters(SCENE_KEYS, (frame, value) => {
+    frame.scene = value;
+  }),
+  ...keyedSetters(VOICEOVER_KEYS, (frame, value) => {
+    frame.voiceover = stripQuotes(value);
+  }),
+]);
+
+function keyedSetters(keys: Set<string>, setter: MetaSetter): Array<[string, MetaSetter]> {
+  return [...keys].map((key) => [key, setter]);
+}
+
+function applyMeta(
+  frame: StoryboardFrame,
+  key: string,
+  value: string,
+  headingLine: number,
+  warnings: StoryboardWarning[],
+): void {
+  const setter = META_SETTERS.get(key);
+  if (setter) setter(frame, value, headingLine, warnings);
+  else frame.extra[key] = value;
+}
+
+function applyPoster(frame: StoryboardFrame, value: string): void {
+  const num = DURATION_NUM_RE.exec(value);
+  if (num) frame.poster = Number.parseFloat(num[1] ?? "");
+}
+
+function applyDuration(
+  frame: StoryboardFrame,
+  value: string,
+  headingLine: number,
+  warnings: StoryboardWarning[],
+): void {
+  frame.duration = value;
+  const num = DURATION_NUM_RE.exec(value);
+  if (num) {
+    frame.durationSeconds = Number.parseFloat(num[1] ?? "");
+    return;
+  }
+  warnings.push({
+    message: `Frame ${frame.index}: could not parse duration "${value}".`,
+    line: headingLine,
+    frameIndex: frame.index,
+  });
+}
+
+function applyStatus(
+  frame: StoryboardFrame,
+  value: string,
+  headingLine: number,
+  warnings: StoryboardWarning[],
+): void {
+  const normalized = value.toLowerCase();
+  if (isFrameStatus(normalized)) {
+    frame.status = normalized;
+    return;
+  }
+  frame.extra.status = value;
+  warnings.push({
+    message: `Frame ${frame.index}: unknown status "${value}"; defaulting to "${DEFAULT_FRAME_STATUS}".`,
+    line: headingLine,
+    frameIndex: frame.index,
+  });
+}
+
+function stripQuotes(value: string): string {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}

packages/core/src/storyboard/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Storyboard data model.
+ *
+ * A storyboard is the plan for a video before any animation work happens: an
+ * ordered set of frames (key moments) plus their narrative/script. It is
+ * authored as a single canonical markdown file (`STORYBOARD.md`) and parsed
+ * into this normalized shape for the Studio's storyboard view and for agents.
+ *
+ * See PRD: "Storyboarding in HyperFrames". The markdown stays canonical; this
+ * is the derived structure the parser produces.
+ */
+
+/** Canonical filename for the storyboard manifest at a project root. */
+export const STORYBOARD_FILENAME = "STORYBOARD.md";
+
+/**
+ * Canonical filename for the companion narration script. Holds the full
+ * voiceover script (voice settings, per-line delivery + timing). Optional —
+ * frames can also carry an inline `voiceover` line in {@link STORYBOARD_FILENAME}.
+ */
+export const SCRIPT_FILENAME = "SCRIPT.md";
+
+/**
+ * Lifecycle of a single frame. The agent advances each frame
+ * `outline → built → animated`; the Studio renders progress from this.
+ */
+export type FrameStatus = "outline" | "built" | "animated";
+
+/** The set of recognized {@link FrameStatus} values. */
+export const FRAME_STATUSES: readonly FrameStatus[] = ["outline", "built", "animated"];
+
+/** Default status when a frame omits one (it is still just an outline). */
+export const DEFAULT_FRAME_STATUS: FrameStatus = "outline";
+
+/** Global direction for the whole video, parsed from the frontmatter. */
+export interface StoryboardGlobals {
+  /** Canvas format as authored, e.g. `"1920x1080"`. */
+  format?: string;
+  /** One-line message / thesis of the video. */
+  message?: string;
+  /** Narrative arc, e.g. `"Problem → Solution"`. */
+  arc?: string;
+  /** Target audience, e.g. `"indie devs on X"`. */
+  audience?: string;
+  /** Any frontmatter keys outside the known set, preserved verbatim. */
+  extra: Record<string, string>;
+}
+
+/** A single frame: one key moment in the video. */
+export interface StoryboardFrame {
+  /** 1-based order within the storyboard, assigned by document order. */
+  index: number;
+  /** Frame number as authored (the `N` in `Frame N`), when present. */
+  number?: number;
+  /** Frame title (the text after the number), when present. */
+  title?: string;
+  /** Lifecycle status; defaults to {@link DEFAULT_FRAME_STATUS}. */
+  status: FrameStatus;
+  /** Project-relative path to the frame's HTML sub-composition, when linked. */
+  src?: string;
+  /** Duration in seconds, parsed from e.g. `"6s"`. Undefined when unparseable. */
+  durationSeconds?: number;
+  /** Raw duration string as authored, e.g. `"6s"`. */
+  duration?: string;
+  /** Transition into this frame, e.g. `"crossfade"`. */
+  transitionIn?: string;
+  /** One-line description of the key moment (the contact-sheet caption). */
+  scene?: string;
+  /** Voiceover / narration line spoken over this frame. */
+  voiceover?: string;
+  /**
+   * Representative time (seconds) to show this frame at in the contact sheet —
+   * a "poster" frame past the intro animation. Falls back to a heuristic.
+   */
+  poster?: number;
+  /** Narrative / script markdown for this frame (everything below the metadata). */
+  narrative: string;
+  /** Metadata keys outside the known set, preserved verbatim. */
+  extra: Record<string, string>;
+}
+
+/** A non-fatal issue encountered while parsing. The parser never throws. */
+export interface StoryboardWarning {
+  message: string;
+  /** 1-based source line number, when known. */
+  line?: number;
+  /** 1-based frame index the warning relates to, when applicable. */
+  frameIndex?: number;
+}
+
+/** Fully parsed storyboard manifest. */
+export interface StoryboardManifest {
+  globals: StoryboardGlobals;
+  frames: StoryboardFrame[];
+  /** Non-fatal parse issues (unknown status, unparseable duration, etc.). */
+  warnings: StoryboardWarning[];
+}

packages/core/src/studio-api/createStudioApi.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import type { StudioApiAdapter } from "./types.js";
 import { registerProjectRoutes } from "./routes/projects.js";
+import { registerStoryboardRoutes } from "./routes/storyboard.js";
 import { registerFileRoutes } from "./routes/files.js";
 import { registerPreviewRoutes } from "./routes/preview.js";
 import { registerLintRoutes } from "./routes/lint.js";
@@ -20,6 +21,7 @@ export function createStudioApi(adapter: StudioApiAdapter): Hono {
   const api = new Hono();
 
   registerProjectRoutes(api, adapter);
+  registerStoryboardRoutes(api, adapter);
   registerFileRoutes(api, adapter);
   registerPreviewRoutes(api, adapter);
   registerLintRoutes(api, adapter);

packages/core/src/studio-api/routes/storyboard.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { Hono } from "hono";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { registerStoryboardRoutes } from "./storyboard.js";
+import type { StudioApiAdapter } from "../types.js";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function makeProject(): string {
+  const dir = mkdtempSync(join(tmpdir(), "storyboard-route-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function makeApp(projectDir: string): Hono {
+  const adapter = {
+    resolveProject: (id: string) => (id === "p" ? { id: "p", dir: projectDir } : null),
+  } as unknown as StudioApiAdapter;
+  const app = new Hono();
+  registerStoryboardRoutes(app, adapter);
+  return app;
+}
+
+/** Request the storyboard for project "p" and return status + parsed JSON body. */
+async function getStoryboard(projectDir: string) {
+  const res = await makeApp(projectDir).request("/projects/p/storyboard");
+  return { status: res.status, body: await res.json() };
+}
+
+describe("GET /projects/:id/storyboard", () => {
+  it("returns exists:false with empty frames when STORYBOARD.md is absent", async () => {
+    const { status, body } = await getStoryboard(makeProject());
+    expect(status).toBe(200);
+    expect(body.exists).toBe(false);
+    expect(body.frames).toEqual([]);
+  });
+
+  it("404s for an unknown project", async () => {
+    const res = await makeApp(makeProject()).request("/projects/nope/storyboard");
+    expect(res.status).toBe(404);
+  });
+
+  it("parses the manifest and resolves frame src existence on disk", async () => {
+    const dir = makeProject();
+    mkdirSync(join(dir, "compositions", "frames"), { recursive: true });
+    writeFileSync(join(dir, "compositions", "frames", "01-hook.html"), "<div></div>");
+    writeFileSync(
+      join(dir, "STORYBOARD.md"),
+      `---
+message: Hello world
+---
+
+## Frame 1 — Hook
+- status: built
+- src: compositions/frames/01-hook.html
+
+Opening line.
+
+## Frame 2 — Missing
+- status: outline
+- src: compositions/frames/02-missing.html
+
+Not built yet.
+`,
+    );
+
+    const { status, body } = await getStoryboard(dir);
+    expect(status).toBe(200);
+    expect(body.exists).toBe(true);
+    expect(body.globals.message).toBe("Hello world");
+    expect(body.frames).toHaveLength(2);
+    expect(body.frames[0]).toMatchObject({ title: "Hook", status: "built", srcExists: true });
+    expect(body.frames[1]).toMatchObject({ title: "Missing", status: "outline", srcExists: false });
+  });
+
+  it("surfaces the companion SCRIPT.md when present", async () => {
+    const dir = makeProject();
+    writeFileSync(join(dir, "STORYBOARD.md"), "## Frame 1\n\nHi.\n");
+    writeFileSync(join(dir, "SCRIPT.md"), "# Script\n\nLine 1.\n");
+    const { body } = await getStoryboard(dir);
+    expect(body.script).toMatchObject({ exists: true, path: "SCRIPT.md" });
+    expect(body.script.content).toContain("Line 1.");
+  });
+
+  it("reports script.exists=false when there is no SCRIPT.md", async () => {
+    const dir = makeProject();
+    writeFileSync(join(dir, "STORYBOARD.md"), "## Frame 1\n\nHi.\n");
+    const { body } = await getStoryboard(dir);
+    expect(body.script.exists).toBe(false);
+  });
+
+  it("does not resolve src paths that escape the project", async () => {
+    const dir = makeProject();
+    writeFileSync(
+      join(dir, "STORYBOARD.md"),
+      "## Frame 1\n- src: ../../etc/passwd\n\nEscape attempt.\n",
+    );
+    const { body } = await getStoryboard(dir);
+    expect(body.frames[0].srcExists).toBe(false);
+  });
+});

packages/core/src/studio-api/routes/storyboard.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { Hono } from "hono";
+import type { StudioApiAdapter } from "../types.js";
+import { resolveWithinProject } from "../helpers/safePath.js";
+import {
+  parseStoryboard,
+  SCRIPT_FILENAME,
+  STORYBOARD_FILENAME,
+  type StoryboardFrame,
+} from "../../storyboard/index.js";
+
+/** A frame enriched with disk-resolution info the Studio needs to render tiles. */
+interface ResolvedStoryboardFrame extends StoryboardFrame {
+  /** Whether `src` resolves to an existing file inside the project. */
+  srcExists: boolean;
+}
+
+function resolveFrames(projectDir: string, frames: StoryboardFrame[]): ResolvedStoryboardFrame[] {
+  return frames.map((frame) => {
+    let srcExists = false;
+    if (frame.src) {
+      const abs = resolveWithinProject(projectDir, frame.src);
+      srcExists = abs ? existsSync(abs) : false;
+    }
+    return { ...frame, srcExists };
+  });
+}
+
+/** Read the companion SCRIPT.md narration doc if it exists alongside the storyboard. */
+function readScript(projectDir: string): { exists: boolean; path: string; content: string } {
+  const abs = resolveWithinProject(projectDir, SCRIPT_FILENAME);
+  if (abs && existsSync(abs)) {
+    try {
+      return { exists: true, path: SCRIPT_FILENAME, content: readFileSync(abs, "utf-8") };
+    } catch {
+      /* fall through to absent */
+    }
+  }
+  return { exists: false, path: SCRIPT_FILENAME, content: "" };
+}
+
+export function registerStoryboardRoutes(api: Hono, adapter: StudioApiAdapter): void {
+  // Parsed storyboard manifest for a project. Markdown (STORYBOARD.md) stays
+  // canonical on disk; this returns the derived, normalized structure. When the
+  // file is absent we return `exists: false` with empty frames rather than 404,
+  // so the Studio can render an opt-in empty state.
+  api.get("/projects/:id/storyboard", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+
+    const abs = resolveWithinProject(project.dir, STORYBOARD_FILENAME);
+    if (!abs || !existsSync(abs)) {
+      return c.json({
+        exists: false,
+        path: STORYBOARD_FILENAME,
+        globals: { extra: {} },
+        frames: [],
+        warnings: [],
+        script: readScript(project.dir),
+      });
+    }
+
+    let source: string;
+    try {
+      source = readFileSync(abs, "utf-8");
+    } catch {
+      return c.json({ error: "failed to read storyboard" }, 500);
+    }
+
+    const manifest = parseStoryboard(source);
+    return c.json({
+      exists: true,
+      path: STORYBOARD_FILENAME,
+      globals: manifest.globals,
+      frames: resolveFrames(project.dir, manifest.frames),
+      warnings: manifest.warnings,
+      script: readScript(project.dir),
+    });
+  });
+}

packages/studio/fixtures/storyboard-sample/README.md

@@ -0,0 +1,26 @@
+# storyboard-sample (Studio fixture)
+
+A small, self-contained project for dogfooding the Studio **Storyboard** view.
+Not a registry catalog item — it lives here purely as test content for the
+storyboard UI/UX work.
+
+It exercises the storyboard contract end to end:
+
+- `STORYBOARD.md` — structured manifest (frontmatter + 5 frames) in the canonical
+  format the parser reads.
+- `compositions/frames/0{1..4}-*.html` — live HTML frame sub-compositions
+  (`built` / `animated` statuses) the contact-sheet tiles render.
+- Frame 5 (`05-cta.html`) is intentionally **absent** and `status: outline`, so
+  the grid has an outline placeholder to render.
+
+Preview the storyboard view (flag-gated):
+
+```bash
+VITE_STUDIO_ENABLE_STORYBOARD=1 npx hyperframes preview packages/studio/fixtures/storyboard-sample
+```
+
+Inspect just the parsed manifest the Studio consumes:
+
+```bash
+curl localhost:<port>/api/projects/<id>/storyboard | jq
+```

packages/studio/fixtures/storyboard-sample/SCRIPT.md

@@ -0,0 +1,52 @@
+# SCRIPT — storyboard-sample
+
+**Voice:** Rachel (ElevenLabs)
+**Voice settings:** stability 0.35 · similarity 0.75 · style 0.20
+**Voice direction:** Confident, warm, a little playful. Sounds like a person, never a reader.
+
+---
+
+## Line 1 — Hook (Frame 1)
+
+**Time:** 0.0 – 3.0s
+**Delivery:** Land the promise on the beat. Slight smile.
+
+```
+Ship a launch video in an afternoon.
+```
+
+## Line 2 — The problem (Frame 2)
+
+**Time:** 3.0 – 7.0s
+**Delivery:** Wry, a touch tired — the old grind.
+
+```
+The old way? Prompt, wait twenty minutes, get something that misses.
+```
+
+## Line 3 — The feature (Frame 3)
+
+**Time:** 7.0 – 12.0s
+**Delivery:** Lift into confidence on "then it animates."
+
+```
+You lock the story first — then it animates.
+```
+
+## Line 4 — Proof (Frame 4)
+
+**Time:** 12.0 – 16.0s
+**Delivery:** Punchy, two clean beats.
+
+```
+Fewer re-renders. More finished videos.
+```
+
+## Line 5 — CTA (Frame 5)
+
+**Time:** 16.0 – 19.0s
+**Delivery:** Calm, inviting. Let the command land.
+
+```
+Try it: npx hyperframes.
+```

packages/studio/fixtures/storyboard-sample/STORYBOARD.md

@@ -0,0 +1,71 @@
+---
+format: 1920x1080
+message: "Ship a launch video in an afternoon"
+arc: Hook → Problem → Solution → Proof → CTA
+audience: indie devs on X
+voice: Rachel — 5 lines from SCRIPT.md
+---
+
+## Frame 1 — Hook
+
+- scene: Big type punches in on the beat
+- duration: 3s
+- poster: 2s
+- transition_in: cut
+- status: animated
+- voiceover: "Ship a launch video in an afternoon."
+- src: compositions/frames/01-hook.html
+
+Open cold on the promise. Big type punches in on the beat: "Ship a launch
+video in an afternoon." This is the thesis — everything after pays it off.
+
+## Frame 2 — The problem
+
+- scene: A 20-minute timer spins on a stack of rejected takes
+- duration: 4s
+- poster: 2.6s
+- transition_in: crossfade
+- status: animated
+- voiceover: "The old way? Prompt, wait twenty minutes, get something that misses."
+- src: compositions/frames/02-problem.html
+
+The old way: prompt, wait twenty minutes, get something that misses. A timer
+spins while a stack of rejected takes piles up. Establish the pain we remove.
+
+## Frame 3 — The feature in action
+
+- scene: Frames line up as a contact sheet
+- duration: 5s
+- poster: 3.3s
+- transition_in: crossfade
+- status: built
+- voiceover: "You lock the story first — then it animates."
+- src: compositions/frames/03-feature.html
+
+Cut to the storyboard view itself. Frames line up as a contact sheet and the
+narration says "...you lock the story first, then it animates." Show, don't tell.
+
+## Frame 4 — Proof
+
+- scene: A stat counts up to the payoff number
+- duration: 4s
+- poster: 2.6s
+- transition_in: wipe
+- status: built
+- voiceover: "Fewer re-renders. More finished videos."
+- src: compositions/frames/04-proof.html
+
+A real metric lands: fewer re-renders per finished video. Number counts up
+while a caption credits the storyboard-first flow.
+
+## Frame 5 — Call to action
+
+- scene: End card with the wordmark and a one-line CTA
+- duration: 3s
+- transition_in: crossfade
+- status: outline
+- voiceover: "Try it: npx hyperframes."
+- src: compositions/frames/05-cta.html
+
+End card, still an outline. "Try it: npx hyperframes" with the wordmark. Not
+built yet — this frame should render as an outline placeholder in the grid.

packages/studio/fixtures/storyboard-sample/compositions/frames/01-hook.html

@@ -0,0 +1,50 @@
+<template id="frame-01-hook-template">
+  <div data-composition-id="frame-01-hook" data-width="1920" data-height="1080" data-duration="3">
+    <div class="canvas">
+      <h1 class="headline">Ship a launch video<br /><em>in an afternoon</em></h1>
+    </div>
+
+    <style>
+      [data-composition-id="frame-01-hook"] .canvas {
+        width: 1920px;
+        height: 1080px;
+        background: radial-gradient(circle at 50% 40%, #1b1140 0%, #07060f 70%);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-family: "Inter", system-ui, sans-serif;
+        overflow: hidden;
+      }
+      [data-composition-id="frame-01-hook"] .headline {
+        color: #fff;
+        font-size: 120px;
+        font-weight: 800;
+        line-height: 1.05;
+        letter-spacing: -0.03em;
+        text-align: center;
+        opacity: 0;
+      }
+      [data-composition-id="frame-01-hook"] .headline em {
+        color: #8b7bff;
+        font-style: normal;
+      }
+    </style>
+
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script>
+      (function () {
+        const tl = gsap.timeline({ paused: true });
+        const h = '[data-composition-id="frame-01-hook"] .headline';
+        tl.fromTo(
+          h,
+          { opacity: 0, scale: 0.86 },
+          { opacity: 1, scale: 1, duration: 0.6, ease: "back.out(1.4)" },
+          0.1,
+        );
+        tl.to(h, { scale: 1.04, duration: 2, ease: "none" }, 0.7);
+        window.__timelines = window.__timelines || {};
+        window.__timelines["frame-01-hook"] = tl;
+      })();
+    </script>
+  </div>
+</template>

packages/studio/fixtures/storyboard-sample/compositions/frames/02-problem.html

@@ -0,0 +1,62 @@
+<template id="frame-02-problem-template">
+  <div
+    data-composition-id="frame-02-problem"
+    data-width="1920"
+    data-height="1080"
+    data-duration="4"
+  >
+    <div class="canvas">
+      <div class="spinner"></div>
+      <div class="timer">20:00</div>
+      <div class="label">prompt · wait · miss · repeat</div>
+    </div>
+
+    <style>
+      [data-composition-id="frame-02-problem"] .canvas {
+        width: 1920px;
+        height: 1080px;
+        background: #0c0a14;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        gap: 40px;
+        font-family: "Inter", system-ui, sans-serif;
+        overflow: hidden;
+      }
+      [data-composition-id="frame-02-problem"] .spinner {
+        width: 180px;
+        height: 180px;
+        border-radius: 50%;
+        border: 14px solid #2a2342;
+        border-top-color: #8b7bff;
+      }
+      [data-composition-id="frame-02-problem"] .timer {
+        color: #fff;
+        font-size: 96px;
+        font-weight: 700;
+        font-variant-numeric: tabular-nums;
+        letter-spacing: 0.02em;
+      }
+      [data-composition-id="frame-02-problem"] .label {
+        color: #6f6790;
+        font-size: 34px;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        opacity: 0;
+      }
+    </style>
+
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script>
+      (function () {
+        const id = '[data-composition-id="frame-02-problem"]';
+        const tl = gsap.timeline({ paused: true });
+        tl.to(id + " .spinner", { rotation: 720, duration: 4, ease: "none" }, 0);
+        tl.to(id + " .label", { opacity: 1, duration: 0.5, ease: "power2.out" }, 0.8);
+        window.__timelines = window.__timelines || {};
+        window.__timelines["frame-02-problem"] = tl;
+      })();
+    </script>
+  </div>
+</template>

packages/studio/fixtures/storyboard-sample/compositions/frames/03-feature.html

@@ -0,0 +1,84 @@
+<template id="frame-03-feature-template">
+  <div
+    data-composition-id="frame-03-feature"
+    data-width="1920"
+    data-height="1080"
+    data-duration="5"
+  >
+    <div class="canvas">
+      <div class="sheet">
+        <div class="tile t1"></div>
+        <div class="tile t2"></div>
+        <div class="tile t3"></div>
+        <div class="tile t4"></div>
+      </div>
+      <div class="cap">Lock the story first. Then it animates.</div>
+    </div>
+
+    <style>
+      [data-composition-id="frame-03-feature"] .canvas {
+        width: 1920px;
+        height: 1080px;
+        background: #f5f3ec;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        gap: 56px;
+        font-family: "Inter", system-ui, sans-serif;
+        overflow: hidden;
+      }
+      [data-composition-id="frame-03-feature"] .sheet {
+        display: grid;
+        grid-template-columns: repeat(2, 360px);
+        grid-auto-rows: 202px;
+        gap: 28px;
+      }
+      [data-composition-id="frame-03-feature"] .tile {
+        border-radius: 18px;
+        opacity: 0;
+      }
+      [data-composition-id="frame-03-feature"] .t1 {
+        background: #8b7bff;
+      }
+      [data-composition-id="frame-03-feature"] .t2 {
+        background: #ff7262;
+      }
+      [data-composition-id="frame-03-feature"] .t3 {
+        background: #1abcfe;
+      }
+      [data-composition-id="frame-03-feature"] .t4 {
+        background: #0acf83;
+      }
+      [data-composition-id="frame-03-feature"] .cap {
+        color: #1a1726;
+        font-size: 44px;
+        font-weight: 600;
+        letter-spacing: -0.01em;
+        opacity: 0;
+      }
+    </style>
+
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script>
+      (function () {
+        const id = '[data-composition-id="frame-03-feature"]';
+        const tl = gsap.timeline({ paused: true });
+        tl.to(
+          id + " .tile",
+          { opacity: 1, y: 0, duration: 0.5, stagger: 0.18, ease: "back.out(1.3)" },
+          0.2,
+        );
+        tl.fromTo(
+          id + " .tile",
+          { y: 30 },
+          { y: 0, duration: 0.5, stagger: 0.18, ease: "back.out(1.3)" },
+          0.2,
+        );
+        tl.to(id + " .cap", { opacity: 1, duration: 0.6, ease: "power2.out" }, 1.4);
+        window.__timelines = window.__timelines || {};
+        window.__timelines["frame-03-feature"] = tl;
+      })();
+    </script>
+  </div>
+</template>

packages/studio/fixtures/storyboard-sample/compositions/frames/04-proof.html

@@ -0,0 +1,68 @@
+<template id="frame-04-proof-template">
+  <div data-composition-id="frame-04-proof" data-width="1920" data-height="1080" data-duration="4">
+    <div class="canvas">
+      <div class="stat"><span class="num">0</span><span class="unit">%</span></div>
+      <div class="cap">fewer re-renders per finished video</div>
+    </div>
+
+    <style>
+      [data-composition-id="frame-04-proof"] .canvas {
+        width: 1920px;
+        height: 1080px;
+        background: linear-gradient(160deg, #07060f 0%, #161033 100%);
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        gap: 24px;
+        font-family: "Inter", system-ui, sans-serif;
+        overflow: hidden;
+      }
+      [data-composition-id="frame-04-proof"] .stat {
+        display: flex;
+        align-items: baseline;
+        color: #8b7bff;
+        font-weight: 800;
+        letter-spacing: -0.04em;
+      }
+      [data-composition-id="frame-04-proof"] .num {
+        font-size: 320px;
+        font-variant-numeric: tabular-nums;
+      }
+      [data-composition-id="frame-04-proof"] .unit {
+        font-size: 160px;
+      }
+      [data-composition-id="frame-04-proof"] .cap {
+        color: #cfc9ec;
+        font-size: 44px;
+        font-weight: 500;
+        opacity: 0;
+      }
+    </style>
+
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script>
+      (function () {
+        const id = '[data-composition-id="frame-04-proof"]';
+        const numEl = document.querySelector(id + " .num");
+        const tl = gsap.timeline({ paused: true });
+        const counter = { v: 0 };
+        tl.to(
+          counter,
+          {
+            v: 41,
+            duration: 1.6,
+            ease: "power2.out",
+            onUpdate() {
+              if (numEl) numEl.textContent = String(Math.round(counter.v));
+            },
+          },
+          0.3,
+        );
+        tl.to(id + " .cap", { opacity: 1, duration: 0.6, ease: "power2.out" }, 1.4);
+        window.__timelines = window.__timelines || {};
+        window.__timelines["frame-04-proof"] = tl;
+      })();
+    </script>
+  </div>
+</template>

packages/studio/fixtures/storyboard-sample/index.html

@@ -0,0 +1,81 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Storyboard Demo</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: #07060f;
+      }
+      .scene {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-duration="16"
+      data-width="1920"
+      data-height="1080"
+    >
+      <div
+        id="frame-1"
+        class="scene"
+        data-composition-id="frame-01-hook"
+        data-composition-src="compositions/frames/01-hook.html"
+        data-start="0"
+        data-duration="3"
+        data-track-index="1"
+      ></div>
+      <div
+        id="frame-2"
+        class="scene"
+        data-composition-id="frame-02-problem"
+        data-composition-src="compositions/frames/02-problem.html"
+        data-start="3"
+        data-duration="4"
+        data-track-index="1"
+      ></div>
+      <div
+        id="frame-3"
+        class="scene"
+        data-composition-id="frame-03-feature"
+        data-composition-src="compositions/frames/03-feature.html"
+        data-start="7"
+        data-duration="5"
+        data-track-index="1"
+      ></div>
+      <div
+        id="frame-4"
+        class="scene"
+        data-composition-id="frame-04-proof"
+        data-composition-src="compositions/frames/04-proof.html"
+        data-start="12"
+        data-duration="4"
+        data-track-index="1"
+      ></div>
+    </div>
+
+    <script>
+      window.__timelines = window.__timelines || {};
+      window.__timelines["main"] = gsap.timeline({ paused: true });
+    </script>
+  </body>
+</html>