@hyperframes/studio 0.6.110 → 0.6.111

package/src/components/storyboard/StoryboardFrameTile.tsx

@@ -0,0 +1,88 @@
+import type { StoryboardFrameView } from "../../hooks/useStoryboard";
+import { FramePoster, posterTime } from "./FramePoster";
+import { FRAME_STATUS_META } from "./frameStatus";
+
+export interface StoryboardFrameTileProps {
+  projectId: string;
+  frame: StoryboardFrameView;
+  /** Open this frame in the full-area focus view. */
+  onOpen: (index: number) => void;
+}
+
+function firstLine(text: string): string {
+  return (
+    text
+      .split("\n")
+      .find((line) => line.trim().length > 0)
+      ?.trim() ?? ""
+  );
+}
+
+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: poster preview + its metadata. Click to focus. */
+// fallow-ignore-next-line complexity
+export function StoryboardFrameTile({ projectId, frame, onOpen }: 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);
+
+  return (
+    <article className="min-w-0">
+      <button
+        type="button"
+        onClick={() => onOpen(frame.index)}
+        className="group relative block aspect-video w-full overflow-hidden rounded-lg border border-neutral-800 bg-neutral-900 text-left transition-colors hover:border-neutral-600"
+      >
+        <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>
+        {renderable && frame.src ? (
+          <FramePoster
+            projectId={projectId}
+            src={frame.src}
+            seconds={posterTime(frame)}
+            title={title}
+          />
+        ) : (
+          <FrameTilePlaceholder frame={frame} />
+        )}
+      </button>
+
+      <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}
+          aria-label={`Status: ${meta.label} — ${meta.tooltip}`}
+          className={`shrink-0 cursor-default rounded px-1.5 py-0.5 text-[10px] font-medium uppercase tracking-wide ${meta.chipClass}`}
+        >
+          {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>
+  );
+}
+
+function FrameTilePlaceholder({ frame }: { frame: StoryboardFrameView }) {
+  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">{placeholderMessage(frame)}</span>
+    </div>
+  );
+}

package/src/components/storyboard/StoryboardGrid.tsx

@@ -0,0 +1,33 @@
+import type { StoryboardFrameView } from "../../hooks/useStoryboard";
+import { StoryboardFrameTile } from "./StoryboardFrameTile";
+
+export interface StoryboardGridProps {
+  projectId: string;
+  frames: StoryboardFrameView[];
+  /** Open a frame in the full-area focus view. */
+  onOpenFrame: (index: number) => void;
+}
+
+/** The contact sheet: ordered frame tiles in a responsive grid. */
+export function StoryboardGrid({ projectId, frames, onOpenFrame }: 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 grid gap-x-6 gap-y-8 [grid-template-columns:repeat(auto-fill,minmax(300px,1fr))]">
+      {frames.map((frame) => (
+        <StoryboardFrameTile
+          key={frame.index}
+          projectId={projectId}
+          frame={frame}
+          onOpen={onOpenFrame}
+        />
+      ))}
+    </div>
+  );
+}

package/src/components/storyboard/StoryboardLoaded.tsx

@@ -0,0 +1,136 @@
+import { useMemo, useState } from "react";
+import type { StoryboardResponse } from "../../hooks/useStoryboard";
+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";
+
+type SubView = "board" | "source";
+
+export interface StoryboardLoadedProps {
+  projectId: string;
+  data: StoryboardResponse;
+  /** Re-fetch the manifest after a source edit is saved. */
+  reload: () => void;
+  /** Select a composition in the timeline (used by "Open in Preview"). */
+  onSelectComposition: (path: string) => void;
+}
+
+function clampIndex(index: number, count: number): number {
+  return Math.max(1, Math.min(count, index));
+}
+
+/** A storyboard that exists on disk: Board (contact sheet) ↔ Source ↔ frame focus. */
+// fallow-ignore-next-line complexity
+export function StoryboardLoaded({
+  projectId,
+  data,
+  reload,
+  onSelectComposition,
+}: StoryboardLoadedProps) {
+  const [subView, setSubView] = useState<SubView>("board");
+  const [sourceDirty, setSourceDirty] = useState(false);
+  const [focusedIndex, setFocusedIndex] = useState<number | null>(null);
+  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 });
+    return files;
+    // Depend on the stable fields, not the `data.script` object — every reload()
+    // produces a fresh object and would needlessly re-create this array.
+  }, [data.path, data.script?.path, data.script?.exists]);
+
+  // Leaving the source editor drops its in-memory buffer; confirm when it's dirty.
+  // fallow-ignore-next-line complexity
+  const changeSubView = (next: SubView) => {
+    if (next === subView) return;
+    if (
+      subView === "source" &&
+      sourceDirty &&
+      !window.confirm("Discard unsaved markdown changes?")
+    ) {
+      return;
+    }
+    setSubView(next);
+  };
+
+  const focusedFrame =
+    focusedIndex != null ? (data.frames.find((f) => f.index === focusedIndex) ?? null) : null;
+
+  if (focusedFrame) {
+    return (
+      <StoryboardFrameFocus
+        key={focusedFrame.index}
+        projectId={projectId}
+        storyboardPath={data.path}
+        frame={focusedFrame}
+        frameCount={data.frames.length}
+        onBack={() => setFocusedIndex(null)}
+        onNavigate={(delta) =>
+          setFocusedIndex(clampIndex(focusedFrame.index + delta, data.frames.length))
+        }
+        onSaved={reload}
+        onSelectComposition={onSelectComposition}
+      />
+    );
+  }
+
+  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">
+        <SubViewToggle value={subView} onChange={changeSubView} />
+      </div>
+      {subView === "board" ? (
+        <div className="flex-1 min-h-0 overflow-auto">
+          <div className="mx-auto max-w-[1400px] px-8 py-8">
+            <StoryboardDirection globals={data.globals} frameCount={data.frames.length} />
+            <div className="mt-5">
+              <StoryboardStatusLegend />
+            </div>
+            <StoryboardGrid
+              projectId={projectId}
+              frames={data.frames}
+              onOpenFrame={setFocusedIndex}
+            />
+            {data.script && <StoryboardScriptPanel script={data.script} />}
+          </div>
+        </div>
+      ) : (
+        <StoryboardSourceEditor
+          files={sourceFiles}
+          onSaved={reload}
+          onDirtyChange={setSourceDirty}
+        />
+      )}
+    </div>
+  );
+}
+
+const SUB_VIEWS: Array<{ value: SubView; label: string }> = [
+  { value: "board", label: "Board" },
+  { value: "source", label: "Source" },
+];
+
+function SubViewToggle({ value, onChange }: { value: SubView; onChange: (next: SubView) => void }) {
+  return (
+    <div className="flex items-center gap-0.5 rounded-md bg-neutral-900 p-0.5" role="tablist">
+      {SUB_VIEWS.map((option) => (
+        <button
+          key={option.value}
+          type="button"
+          role="tab"
+          aria-selected={value === option.value}
+          onClick={() => onChange(option.value)}
+          className={`rounded px-3 py-1 text-xs font-medium transition-colors ${
+            value === option.value
+              ? "bg-neutral-700 text-neutral-100"
+              : "text-neutral-400 hover:text-neutral-200"
+          }`}
+        >
+          {option.label}
+        </button>
+      ))}
+    </div>
+  );
+}

package/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>
+  );
+}

package/src/components/storyboard/StoryboardSourceEditor.tsx

@@ -0,0 +1,231 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { marked } from "marked";
+import DOMPurify from "dompurify";
+import { SourceEditor } from "../editor/SourceEditor";
+import { useFileManagerContext } from "../../contexts/FileManagerContext";
+
+export interface SourceFile {
+  path: string;
+  label: string;
+}
+
+export interface StoryboardSourceEditorProps {
+  files: SourceFile[];
+  /** Called after a successful save so the Board can re-parse the updated file. */
+  onSaved: () => void;
+  /** Surfaces unsaved-edit state so the parent can guard the Board↔Source toggle. */
+  onDirtyChange?: (dirty: boolean) => void;
+}
+
+const DISCARD_PROMPT = "Discard unsaved markdown changes?";
+
+interface EditableFile {
+  content: string;
+  setContent: (next: string) => void;
+  dirty: boolean;
+  loading: boolean;
+  saving: boolean;
+  error: string | null;
+  save: () => void;
+}
+
+/** Load a project file's raw text and track edits + save state via the shared file manager. */
+function useEditableFile(path: string, onSaved: () => void): EditableFile {
+  const { readProjectFile, writeProjectFile } = useFileManagerContext();
+  const [content, setContent] = useState("");
+  const [saved, setSaved] = useState("");
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!path) return;
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    readProjectFile(path)
+      .then((text) => {
+        if (cancelled) return;
+        setContent(text);
+        setSaved(text);
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) setError(err instanceof Error ? err.message : "failed to load file");
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [path, readProjectFile]);
+
+  const save = useCallback(() => {
+    if (saving) return; // coalesce a fast double Cmd+S into one PUT
+    setSaving(true);
+    setError(null);
+    writeProjectFile(path, content)
+      .then(() => {
+        setSaved(content);
+        onSaved();
+      })
+      .catch((err: unknown) => setError(err instanceof Error ? err.message : "failed to save"))
+      .finally(() => setSaving(false));
+  }, [writeProjectFile, path, content, onSaved, saving]);
+
+  return { content, setContent, dirty: content !== saved, loading, saving, error, save };
+}
+
+/** Preview links open in a new tab with the `window.opener` back-channel severed. */
+function hardenLinks(node: Element): void {
+  if (node.tagName === "A" && node.hasAttribute("href")) {
+    node.setAttribute("target", "_blank");
+    node.setAttribute("rel", "noopener noreferrer");
+  }
+}
+
+/** Render markdown to sanitized HTML, debounced so we don't re-parse on every keystroke. */
+function useMarkdownPreview(source: string): string {
+  const [debounced, setDebounced] = useState(source);
+  const primed = useRef(false);
+  useEffect(() => {
+    // Paint the first non-empty content immediately (no 200ms blank window after a file
+    // loads), exactly once, then debounce all subsequent keystrokes.
+    if (!primed.current && source !== "") {
+      primed.current = true;
+      setDebounced(source);
+      return;
+    }
+    const id = window.setTimeout(() => setDebounced(source), 200);
+    return () => window.clearTimeout(id);
+  }, [source]);
+  return useMemo(() => {
+    // `{ async: false }` pins the synchronous string return (no Promise union to narrow).
+    const html = marked.parse(debounced, { async: false });
+    // Scope the link-hardening hook to this call; `finally` guarantees removal even if
+    // `sanitize` throws, so the hook can never leak into other DOMPurify consumers.
+    DOMPurify.addHook("afterSanitizeAttributes", hardenLinks);
+    try {
+      return DOMPurify.sanitize(html);
+    } finally {
+      DOMPurify.removeHook("afterSanitizeAttributes");
+    }
+  }, [debounced]);
+}
+
+function isSaveShortcut(event: React.KeyboardEvent): boolean {
+  return (event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "s";
+}
+
+// Minimal prose styling for the rendered preview (Tailwind doesn't style raw HTML).
+const PREVIEW_PROSE =
+  "text-sm leading-relaxed text-neutral-300 " +
+  "[&_h1]:mb-2 [&_h1]:mt-5 [&_h1]:text-xl [&_h1]:font-semibold [&_h1]:text-neutral-100 " +
+  "[&_h2]:mb-1.5 [&_h2]:mt-5 [&_h2]:text-base [&_h2]:font-semibold [&_h2]:text-neutral-100 " +
+  "[&_h3]:mt-4 [&_h3]:font-semibold [&_h3]:text-neutral-200 " +
+  "[&_p]:my-2 [&_ul]:my-2 [&_ul]:list-disc [&_ul]:pl-5 [&_ol]:my-2 [&_ol]:list-decimal [&_ol]:pl-5 " +
+  "[&_code]:rounded [&_code]:bg-neutral-800 [&_code]:px-1 [&_code]:text-[0.85em] [&_code]:text-neutral-200 " +
+  "[&_pre]:my-3 [&_pre]:overflow-auto [&_pre]:rounded [&_pre]:bg-neutral-900 [&_pre]:p-3 " +
+  "[&_pre_code]:bg-transparent [&_pre_code]:p-0 " +
+  "[&_hr]:my-4 [&_hr]:border-neutral-800 [&_a]:text-sky-400 [&_strong]:text-neutral-100 " +
+  "[&_img]:my-2 [&_img]:max-w-full [&_img]:h-auto [&_img]:rounded " +
+  "[&_table]:my-3 [&_th]:border [&_th]:border-neutral-800 [&_th]:px-2 [&_th]:py-1 " +
+  "[&_td]:border [&_td]:border-neutral-800 [&_td]:px-2 [&_td]:py-1";
+
+/**
+ * Raw markdown editor + live preview for the storyboard's canonical files
+ * (STORYBOARD.md / SCRIPT.md). Markdown stays the source of truth: saving writes
+ * the file and re-parses the Board. Deliberately raw (not WYSIWYG) so the
+ * structured frame fields can't be mangled; the preview is sanitized before render.
+ */
+// fallow-ignore-next-line complexity
+export function StoryboardSourceEditor({
+  files,
+  onSaved,
+  onDirtyChange,
+}: StoryboardSourceEditorProps) {
+  const [selected, setSelected] = useState(files[0]?.path ?? "");
+  // Reconcile against the current file list so a removed/renamed file can't strand the tab.
+  const activePath = files.some((f) => f.path === selected) ? selected : (files[0]?.path ?? "");
+  const file = useEditableFile(activePath, onSaved);
+  const previewHtml = useMarkdownPreview(file.content);
+
+  // Surface dirty state to the parent (guards the Board↔Source toggle) and warn
+  // on browser-level navigation while there are unsaved edits.
+  useEffect(() => onDirtyChange?.(file.dirty), [onDirtyChange, file.dirty]);
+  useEffect(() => {
+    if (!file.dirty) return;
+    const onBeforeUnload = (event: BeforeUnloadEvent) => {
+      event.preventDefault();
+      event.returnValue = "";
+    };
+    window.addEventListener("beforeunload", onBeforeUnload);
+    return () => window.removeEventListener("beforeunload", onBeforeUnload);
+  }, [file.dirty]);
+
+  // Switching files discards the in-memory buffer; confirm when there are unsaved edits.
+  const selectFile = (path: string) => {
+    if (path === activePath) return;
+    if (file.dirty && !window.confirm(DISCARD_PROMPT)) return;
+    setSelected(path);
+  };
+
+  return (
+    <div
+      className="flex flex-1 min-h-0 flex-col"
+      onKeyDown={(e) => {
+        if (!isSaveShortcut(e)) return;
+        e.preventDefault();
+        if (file.dirty && !file.saving) file.save();
+      }}
+    >
+      <div className="flex items-center gap-1 border-b border-neutral-800 px-4 py-2">
+        {files.map((f) => (
+          <button
+            key={f.path}
+            type="button"
+            onClick={() => selectFile(f.path)}
+            className={`rounded px-2.5 py-1 text-xs font-medium transition-colors ${
+              activePath === f.path
+                ? "bg-neutral-800 text-neutral-100"
+                : "text-neutral-400 hover:text-neutral-200"
+            }`}
+          >
+            {f.label}
+          </button>
+        ))}
+        <div className="ml-auto flex items-center gap-3">
+          {file.error && <span className="text-xs text-red-400">{file.error}</span>}
+          <span className="text-xs text-neutral-500">
+            {file.saving ? "Saving…" : file.dirty ? "Unsaved changes" : "Saved"}
+          </span>
+          <button
+            type="button"
+            onClick={file.save}
+            disabled={!file.dirty || file.saving}
+            className="rounded bg-emerald-600 px-3 py-1 text-xs font-medium text-white disabled:opacity-40"
+          >
+            Save
+          </button>
+        </div>
+      </div>
+      <div className="flex flex-1 min-h-0">
+        <div className="w-1/2 min-w-0 border-r border-neutral-800">
+          {file.loading ? (
+            <div className="p-4 text-sm text-neutral-500">Loading {activePath}…</div>
+          ) : (
+            <SourceEditor
+              content={file.content}
+              language="markdown"
+              filePath={activePath}
+              onChange={file.setContent}
+            />
+          )}
+        </div>
+        <div className="w-1/2 min-w-0 overflow-auto bg-neutral-950 px-6 py-4">
+          <div className={PREVIEW_PROSE} dangerouslySetInnerHTML={{ __html: previewHtml }} />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/storyboard/StoryboardStatusLegend.tsx

@@ -0,0 +1,21 @@
+import { FRAME_STATUS_META, FRAME_STATUS_ORDER } from "./frameStatus";
+
+/**
+ * Explains the frame lifecycle: a frame advances outline → built → animated.
+ * Mirrors the status chips on each tile (shares FRAME_STATUS_META).
+ */
+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 ${FRAME_STATUS_META[status].dotClass}`} />
+          <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>
+  );
+}

package/src/components/storyboard/StoryboardView.tsx

@@ -0,0 +1,78 @@
+import type { ReactNode } from "react";
+import { useStoryboard } from "../../hooks/useStoryboard";
+import { StoryboardLoaded } from "./StoryboardLoaded";
+
+export interface StoryboardViewProps {
+  projectId: string;
+  /** Select a composition in the timeline (used by the frame focus "Open in Preview"). */
+  onSelectComposition: (path: string) => void;
+}
+
+/**
+ * Top-level storyboard stage. Replaces the timeline/preview when the view mode
+ * is `storyboard`. Handles the load states here; once a storyboard exists,
+ * {@link StoryboardLoaded} owns the Board ↔ Source experience.
+ */
+// fallow-ignore-next-line complexity
+export function StoryboardView({ projectId, onSelectComposition }: StoryboardViewProps) {
+  const { data, loading, error, reload } = useStoryboard(projectId);
+
+  if (loading) return <StoryboardFrame>{<Message>Loading storyboard…</Message>}</StoryboardFrame>;
+  if (error) {
+    return (
+      <StoryboardFrame>
+        <Message tone="error">Couldn’t load the storyboard: {error}</Message>
+      </StoryboardFrame>
+    );
+  }
+  if (!data) return <StoryboardFrame>{null}</StoryboardFrame>;
+  if (!data.exists) {
+    return (
+      <StoryboardFrame>
+        <EmptyState path={data.path} />
+      </StoryboardFrame>
+    );
+  }
+
+  return (
+    <StoryboardLoaded
+      projectId={projectId}
+      data={data}
+      reload={reload}
+      onSelectComposition={onSelectComposition}
+    />
+  );
+}
+
+function StoryboardFrame({ children }: { children: ReactNode }) {
+  return (
+    <div className="flex-1 min-h-0 overflow-auto bg-neutral-950 text-neutral-200">
+      <div className="mx-auto max-w-[1400px] px-8 py-8">{children}</div>
+    </div>
+  );
+}
+
+function Message({ children, tone = "muted" }: { children: ReactNode; tone?: "muted" | "error" }) {
+  return (
+    <div
+      className={`px-6 py-12 text-center text-sm ${
+        tone === "error" ? "text-red-400" : "text-neutral-500"
+      }`}
+    >
+      {children}
+    </div>
+  );
+}
+
+function EmptyState({ path }: { path: string }) {
+  return (
+    <div className="rounded-lg border border-dashed border-neutral-800 px-6 py-16 text-center">
+      <h2 className="text-base font-semibold text-neutral-300">No storyboard yet</h2>
+      <p className="mx-auto mt-2 max-w-md text-sm text-neutral-500">
+        Add a <code className="rounded bg-neutral-900 px-1 py-0.5 text-neutral-400">{path}</code> at
+        the project root to plan this video frame by frame. Your agent can create and iterate on it
+        for you.
+      </p>
+    </div>
+  );
+}

package/src/components/storyboard/frameStatus.ts

@@ -0,0 +1,36 @@
+import type { FrameStatus } from "@hyperframes/core/storyboard";
+
+/**
+ * Single source of truth for how each frame lifecycle status is presented —
+ * label, tooltip, description, and the chip/dot color classes — so the tile
+ * chip and the legend dot can't drift apart.
+ */
+export const FRAME_STATUS_META: Record<
+  FrameStatus,
+  { label: string; tooltip: string; description: string; chipClass: string; dotClass: 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.",
+    chipClass: "bg-neutral-800 text-neutral-300",
+    dotClass: "bg-neutral-500",
+  },
+  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.",
+    chipClass: "bg-sky-500/20 text-sky-300",
+    dotClass: "bg-sky-400",
+  },
+  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.",
+    chipClass: "bg-emerald-500/20 text-emerald-300",
+    dotClass: "bg-emerald-400",
+  },
+};
+
+/** The lifecycle order an agent advances each frame through. */
+export const FRAME_STATUS_ORDER: FrameStatus[] = ["outline", "built", "animated"];