@hyperframes/studio 0.6.109 → 0.6.111

package/src/components/storyboard/StoryboardFrameFocus.tsx

@@ -0,0 +1,262 @@
+import { useCallback, useEffect, useState } from "react";
+import { setFrameStatus, setFrameVoiceover, type FrameStatus } from "@hyperframes/core/storyboard";
+import type { StoryboardFrameView } from "../../hooks/useStoryboard";
+import { useFileManagerContext } from "../../contexts/FileManagerContext";
+import { useViewMode } from "../../contexts/ViewModeContext";
+import { FramePoster, posterTime } from "./FramePoster";
+import { FRAME_STATUS_META, FRAME_STATUS_ORDER } from "./frameStatus";
+
+export interface StoryboardFrameFocusProps {
+  projectId: string;
+  /** Path to STORYBOARD.md (edits are written here). */
+  storyboardPath: string;
+  frame: StoryboardFrameView;
+  frameCount: number;
+  onBack: () => void;
+  onNavigate: (delta: number) => void;
+  /** Re-parse the manifest after an edit is saved. */
+  onSaved: () => void;
+  /** Select a composition in the timeline (sets active comp + editing file + sidebar highlight). */
+  onSelectComposition: (path: string) => void;
+}
+
+/**
+ * Full-area focus on a single frame: large poster, editable voiceover guide,
+ * status advancement, full narrative, and a jump into the live preview. Edits
+ * are written back to STORYBOARD.md in place (markdown stays canonical).
+ *
+ * Mounted with a `key` per frame, so `draft` initializes from the frame and a
+ * save-triggered reload never clobbers in-progress typing.
+ */
+// fallow-ignore-next-line complexity
+export function StoryboardFrameFocus({
+  projectId,
+  storyboardPath,
+  frame,
+  frameCount,
+  onBack,
+  onNavigate,
+  onSaved,
+  onSelectComposition,
+}: StoryboardFrameFocusProps) {
+  const { readProjectFile, writeProjectFile } = useFileManagerContext();
+  const { setViewMode } = useViewMode();
+  const [draft, setDraft] = useState(frame.voiceover ?? "");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const applyEdit = useCallback(
+    async (edit: (source: string) => string) => {
+      if (busy) return; // one read-modify-write at a time; avoids a lost update
+      setBusy(true);
+      setError(null);
+      try {
+        const source = await readProjectFile(storyboardPath);
+        await writeProjectFile(storyboardPath, edit(source));
+        onSaved();
+      } catch (err: unknown) {
+        setError(err instanceof Error ? err.message : "failed to save");
+      } finally {
+        setBusy(false);
+      }
+    },
+    [readProjectFile, writeProjectFile, storyboardPath, onSaved, busy],
+  );
+
+  const title = frame.title ?? `Frame ${frame.index}`;
+  const dirty = draft !== (frame.voiceover ?? "");
+  const canOpenPreview = frame.srcExists && Boolean(frame.src);
+
+  // Leaving the frame drops the in-memory voiceover draft; confirm when it's dirty.
+  const confirmLeave = () => !dirty || window.confirm("Discard unsaved voiceover changes?");
+  const handleBack = () => {
+    if (confirmLeave()) onBack();
+  };
+  const handleNavigate = (delta: number) => {
+    if (confirmLeave()) onNavigate(delta);
+  };
+
+  // ←/→ navigate frames, Esc returns to the Board — but never while typing in a field.
+  useEffect(() => {
+    // fallow-ignore-next-line complexity
+    const onKey = (e: KeyboardEvent) => {
+      const el = document.activeElement;
+      if (el instanceof HTMLTextAreaElement || el instanceof HTMLInputElement) return;
+      if (e.key === "Escape") handleBack();
+      else if (e.key === "ArrowLeft" && frame.index > 1) handleNavigate(-1);
+      else if (e.key === "ArrowRight" && frame.index < frameCount) handleNavigate(1);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  });
+
+  const openInPreview = () => {
+    if (frame.src) onSelectComposition(frame.src);
+    setViewMode("timeline");
+  };
+
+  return (
+    <div className="flex flex-1 min-h-0 flex-col bg-neutral-950 text-neutral-200">
+      <div className="flex items-center gap-3 border-b border-neutral-800 px-4 py-2">
+        <button
+          type="button"
+          onClick={handleBack}
+          className="rounded px-2 py-1 text-xs font-medium text-neutral-300 hover:bg-neutral-800"
+        >
+          ← Board
+        </button>
+        <span className="text-sm font-medium text-neutral-200">
+          Frame {frame.number ?? frame.index} — {title}
+        </span>
+        <div className="ml-auto flex items-center gap-1">
+          <NavButton
+            label="‹ Prev"
+            disabled={frame.index <= 1}
+            onClick={() => handleNavigate(-1)}
+          />
+          <NavButton
+            label="Next ›"
+            disabled={frame.index >= frameCount}
+            onClick={() => handleNavigate(1)}
+          />
+        </div>
+      </div>
+
+      <div className="flex flex-1 min-h-0">
+        <div className="flex w-3/5 min-w-0 items-center justify-center bg-neutral-900/40 p-8">
+          <div className="aspect-video w-full max-w-[900px] overflow-hidden rounded-lg border border-neutral-800 bg-neutral-900">
+            {canOpenPreview && frame.src ? (
+              <FramePoster
+                projectId={projectId}
+                src={frame.src}
+                seconds={posterTime(frame)}
+                title={title}
+                fit="contain"
+              />
+            ) : (
+              <div className="flex h-full w-full items-center justify-center text-sm text-neutral-600">
+                {frame.status === "outline" ? "Not built yet" : "No preview"}
+              </div>
+            )}
+          </div>
+        </div>
+
+        <div className="w-2/5 min-w-0 space-y-6 overflow-auto border-l border-neutral-800 px-6 py-5">
+          <StatusRow
+            status={frame.status}
+            busy={busy}
+            onSet={(s) => applyEdit((src) => setFrameStatus(src, frame.index, s))}
+          />
+
+          <div className="flex flex-wrap gap-x-6 gap-y-1 text-[11px] text-neutral-500">
+            {frame.duration && <span>Duration {frame.duration}</span>}
+            {frame.transitionIn && <span>Transition {frame.transitionIn}</span>}
+          </div>
+
+          <section>
+            <div className="mb-1 flex items-center justify-between">
+              <h3 className="text-xs font-semibold uppercase tracking-wider text-neutral-400">
+                🎙 Voiceover <span className="font-normal normal-case text-neutral-600">guide</span>
+              </h3>
+              <button
+                type="button"
+                onClick={() => applyEdit((src) => setFrameVoiceover(src, frame.index, draft))}
+                disabled={!dirty || busy}
+                className="rounded bg-emerald-600 px-2.5 py-1 text-xs font-medium text-white disabled:opacity-40"
+              >
+                Save
+              </button>
+            </div>
+            <textarea
+              value={draft}
+              onChange={(e) => setDraft(e.target.value)}
+              rows={3}
+              placeholder="What the narrator says over this frame…"
+              className="w-full resize-y rounded border border-neutral-800 bg-neutral-900 p-2 text-sm text-neutral-200 outline-none focus:border-neutral-600"
+            />
+            <p className="mt-1 text-[11px] text-neutral-600">
+              A draft guide. SCRIPT.md locks the final narration that drives TTS.
+            </p>
+            {error && <p className="mt-1 text-[11px] text-red-400">{error}</p>}
+          </section>
+
+          {frame.narrative && (
+            <section>
+              <h3 className="mb-1 text-xs font-semibold uppercase tracking-wider text-neutral-400">
+                Narrative
+              </h3>
+              <p className="whitespace-pre-wrap text-sm text-neutral-300">{frame.narrative}</p>
+            </section>
+          )}
+
+          <button
+            type="button"
+            onClick={openInPreview}
+            disabled={!canOpenPreview}
+            className="rounded border border-neutral-700 px-3 py-1.5 text-xs font-medium text-neutral-200 hover:bg-neutral-800 disabled:opacity-40"
+          >
+            Open in Preview →
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function NavButton({
+  label,
+  disabled,
+  onClick,
+}: {
+  label: string;
+  disabled: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      className="rounded px-2 py-1 text-xs font-medium text-neutral-300 hover:bg-neutral-800 disabled:opacity-30"
+    >
+      {label}
+    </button>
+  );
+}
+
+function StatusRow({
+  status,
+  busy,
+  onSet,
+}: {
+  status: FrameStatus;
+  busy: boolean;
+  onSet: (next: FrameStatus) => void;
+}) {
+  return (
+    <div className="flex items-center gap-2">
+      <span className="text-xs font-semibold uppercase tracking-wider text-neutral-500">
+        Status
+      </span>
+      <div className="flex items-center gap-0.5 rounded-md bg-neutral-900 p-0.5">
+        {FRAME_STATUS_ORDER.map((option) => (
+          <button
+            key={option}
+            type="button"
+            disabled={busy}
+            aria-pressed={status === option}
+            title={FRAME_STATUS_META[option].tooltip}
+            onClick={() => onSet(option)}
+            className={`rounded px-2.5 py-1 text-xs font-medium transition-colors disabled:opacity-50 ${
+              status === option
+                ? "bg-neutral-700 text-neutral-100"
+                : "text-neutral-400 hover:text-neutral-200"
+            }`}
+          >
+            {FRAME_STATUS_META[option].label}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}

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