@hyperframes/studio 0.8.49 → 0.8.51

package/src/components/storyboard/StoryboardSourceEditor.tsx

@@ -1,231 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,169 +0,0 @@
-import { useState, type ReactNode } from "react";
-import { Copy, Check } from "@phosphor-icons/react";
-import { useStoryboard } from "../../hooks/useStoryboard";
-import { useProjectSignaturePoll } from "../../hooks/useProjectSignaturePoll";
-import { copyTextToClipboard } from "../../utils/clipboard";
-import { Button } from "../ui/Button";
-import { StoryboardLoaded } from "./StoryboardLoaded";
-
-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);
-  // Keep the board current while an agent writes to the project: when the
-  // project signature moves past the one `data` was loaded with, refetch. Also
-  // upgrades the empty state the moment STORYBOARD.md lands on disk.
-  useProjectSignaturePoll(projectId, data?.signature, reload);
-
-  if (loading) return <StoryboardFrame>{<Message>Loading storyboard…</Message>}</StoryboardFrame>;
-  if (error) {
-    return (
-      <StoryboardFrame>
-        <Message tone="error">Couldn’t load the storyboard: {error}</Message>
-        <div className="flex justify-center">
-          <Button size="sm" variant="secondary" onClick={reload}>
-            Retry
-          </Button>
-        </div>
-      </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 handoffPrompt(path: string): string {
-  return `Create a \`${path}\` at the project root to plan this video frame by frame.
-
-Use this format:
-
----
-format: 1920x1080
-message: <the one-line takeaway of the video>
-arc: <the narrative shape, e.g. Problem → Solution>
-audience: <who it's for>
----
-
-## Frame 1 — <title>
-- duration: 5s
-- transition_in: crossfade
-- status: outline
-- src: compositions/frames/01-<slug>.html
-
-<A sentence or two: what's on screen and what the narration says.>
-
-Add one \`## Frame N\` section per beat. Keep the arc tight.
-
-Then run the review loop from the hyperframes skill (references/review-loop.md): present the plan as a proposal, offer wireframe sketches on this board, and build on the confirmed layouts.`;
-}
-
-function EmptyState({ path }: { path: string }) {
-  const [copied, setCopied] = useState(false);
-  const prompt = handoffPrompt(path);
-
-  const onCopy = async () => {
-    if (await copyTextToClipboard(prompt)) {
-      setCopied(true);
-      window.setTimeout(() => setCopied(false), 2000);
-    }
-  };
-
-  return (
-    <div>
-      <div className="rounded-lg border border-dashed border-neutral-800 px-6 py-10 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. Hand this prompt to your coding
-          agent to scaffold it.
-        </p>
-
-        <div className="mx-auto mt-6 max-w-2xl overflow-hidden rounded-lg border border-neutral-800 bg-neutral-900 text-left">
-          <div className="flex items-center justify-between border-b border-neutral-800 px-3 py-2">
-            <span className="font-mono text-xs text-neutral-500">Prompt for your agent</span>
-            <Button
-              size="sm"
-              variant="secondary"
-              onClick={onCopy}
-              icon={copied ? <Check size={14} /> : <Copy size={14} />}
-            >
-              {copied ? "Copied" : "Copy prompt"}
-            </Button>
-          </div>
-          <pre className="max-h-64 overflow-auto px-4 py-3 font-mono text-xs leading-relaxed text-neutral-400 whitespace-pre-wrap">
-            {prompt}
-          </pre>
-        </div>
-      </div>
-
-      <SkeletonPreview />
-    </div>
-  );
-}
-
-/** Faded placeholder of a filled board so landing here isn't a dead end —
- *  it previews the contact-sheet layout {@link StoryboardGrid} renders. */
-function SkeletonPreview() {
-  return (
-    <div aria-hidden="true" className="mt-10 select-none opacity-40">
-      <div className="mb-4 text-center text-xs uppercase tracking-wide text-neutral-600">
-        Preview
-      </div>
-      <div className="grid gap-x-6 gap-y-8 [grid-template-columns:repeat(auto-fill,minmax(300px,1fr))]">
-        {[0, 1, 2].map((i) => (
-          <div key={i} className="rounded-lg border border-neutral-800 bg-neutral-900/40 p-3">
-            <div className="aspect-video w-full rounded bg-neutral-800/60" />
-            <div className="mt-3 h-3 w-2/3 rounded bg-neutral-800/60" />
-            <div className="mt-2 h-2.5 w-full rounded bg-neutral-800/40" />
-            <div className="mt-1.5 h-2.5 w-4/5 rounded bg-neutral-800/40" />
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-}

package/src/components/storyboard/StoryboardViewModeGuard.test.tsx

@@ -1,187 +0,0 @@
-// @vitest-environment happy-dom
-
-import React, { act } from "react";
-import { createRoot, type Root } from "react-dom/client";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { ViewModeProvider, useViewModeState } from "../../contexts/ViewModeContext";
-import { ViewModeToggle } from "../StudioHeader";
-import { StoryboardFrameFocus } from "./StoryboardFrameFocus";
-
-(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
-
-vi.mock("../../contexts/FileManagerContext", () => ({
-  useFileManagerContext: () => ({
-    readProjectFile: vi.fn(),
-    writeProjectFile: vi.fn(),
-  }),
-}));
-
-vi.mock("../../utils/studioTelemetry", () => ({
-  trackStudioEvent: vi.fn(),
-}));
-
-vi.mock("./FramePoster", () => ({
-  FramePoster: () => <div>poster</div>,
-  posterTime: () => 0,
-}));
-
-const onSelectComposition = vi.fn();
-const onNavigate = vi.fn();
-
-function TestApp() {
-  const viewMode = useViewModeState();
-  return (
-    <ViewModeProvider value={viewMode}>
-      <span data-view-mode={viewMode.viewMode}>{viewMode.viewMode}</span>
-      <ViewModeToggle />
-      {viewMode.viewMode === "storyboard" && (
-        <StoryboardFrameFocus
-          projectId="project"
-          storyboardPath="STORYBOARD.md"
-          frame={{
-            index: 1,
-            number: 1,
-            title: "Opening",
-            status: "built",
-            src: "frames/01-opening.html",
-            srcExists: true,
-            voiceover: "Original voiceover",
-            narrative: "",
-            extra: {},
-          }}
-          frameCount={2}
-          onBack={vi.fn()}
-          onNavigate={onNavigate}
-          onSaved={vi.fn()}
-          onSelectComposition={onSelectComposition}
-          scriptExists={false}
-          commentDraft=""
-          onCommentDraftChange={vi.fn()}
-          pendingComment={null}
-          pendingCommentCount={0}
-          commentDraftCount={0}
-          commentsSubmitState="idle"
-          commentsSubmitError={null}
-          feedbackMessageCopied={false}
-          onFeedbackMessageCopied={vi.fn()}
-          onSaveFeedback={vi.fn()}
-        />
-      )}
-    </ViewModeProvider>
-  );
-}
-
-function renderApp(): { host: HTMLDivElement; root: Root } {
-  const host = document.createElement("div");
-  document.body.append(host);
-  const root = createRoot(host);
-  act(() => root.render(<TestApp />));
-  return { host, root };
-}
-
-function makeVoiceoverDirty(host: HTMLElement): void {
-  const textarea = host.querySelector<HTMLTextAreaElement>(
-    'textarea[placeholder^="What the narrator says"]',
-  );
-  if (!textarea) throw new Error("voiceover textarea not rendered");
-  const valueSetter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")?.set;
-  act(() => {
-    valueSetter?.call(textarea, "Changed voiceover");
-    textarea.dispatchEvent(new Event("input", { bubbles: true }));
-  });
-}
-
-function clickButton(host: HTMLElement, label: string): void {
-  const button = [...host.querySelectorAll("button")].find(
-    (candidate) => candidate.textContent?.trim() === label,
-  );
-  if (!button) throw new Error(`button not found: ${label}`);
-  act(() => button.dispatchEvent(new MouseEvent("click", { bubbles: true })));
-}
-
-async function goBack(): Promise<void> {
-  await act(async () => {
-    window.history.back();
-    await new Promise((resolve) => setTimeout(resolve, 0));
-  });
-}
-
-beforeEach(() => {
-  window.history.replaceState({ entry: "timeline" }, "", "/");
-  window.history.pushState({ entry: "storyboard" }, "", "/?view=storyboard");
-  onSelectComposition.mockReset();
-  onNavigate.mockReset();
-});
-
-afterEach(() => {
-  document.body.innerHTML = "";
-  vi.restoreAllMocks();
-});
-
-describe("dirty storyboard voiceover view-mode guard", () => {
-  it("guards the header Preview transition on decline and allows it on accept", () => {
-    const confirm = vi.spyOn(window, "confirm").mockReturnValue(false);
-    const { host, root } = renderApp();
-    makeVoiceoverDirty(host);
-
-    clickButton(host, "Preview");
-    expect(host.querySelector("[data-view-mode]")?.textContent).toBe("storyboard");
-    expect(confirm).toHaveBeenCalledWith("Discard unsaved voiceover changes?");
-
-    confirm.mockReturnValue(true);
-    clickButton(host, "Preview");
-    expect(host.querySelector("[data-view-mode]")?.textContent).toBe("timeline");
-    expect(onSelectComposition).not.toHaveBeenCalled();
-    act(() => root.unmount());
-  });
-
-  it("guards Open in Preview on decline and selects the frame only after accept", () => {
-    const confirm = vi.spyOn(window, "confirm").mockReturnValue(false);
-    const { host, root } = renderApp();
-    makeVoiceoverDirty(host);
-
-    clickButton(host, "Open in Preview →");
-    expect(host.querySelector("[data-view-mode]")?.textContent).toBe("storyboard");
-    expect(onSelectComposition).not.toHaveBeenCalled();
-
-    confirm.mockReturnValue(true);
-    clickButton(host, "Open in Preview →");
-    expect(host.querySelector("[data-view-mode]")?.textContent).toBe("timeline");
-    expect(onSelectComposition).toHaveBeenCalledWith("frames/01-opening.html");
-    act(() => root.unmount());
-  });
-
-  it("guards browser history transitions on decline and allows them on accept", async () => {
-    const confirm = vi.spyOn(window, "confirm").mockReturnValue(false);
-    const { host, root } = renderApp();
-    makeVoiceoverDirty(host);
-
-    await goBack();
-    expect(host.querySelector("[data-view-mode]")?.textContent).toBe("storyboard");
-    expect(window.location.search).toBe("?view=storyboard");
-    expect(window.history.state).toEqual({ entry: "storyboard" });
-    expect(confirm).toHaveBeenCalledWith("Discard unsaved voiceover changes?");
-
-    confirm.mockReturnValue(true);
-    await goBack();
-    expect(host.querySelector("[data-view-mode]")?.textContent).toBe("timeline");
-    expect(window.location.search).toBe("");
-    expect(window.history.state).toEqual({ entry: "timeline" });
-    act(() => root.unmount());
-  });
-});
-
-describe("storyboard frame keyboard navigation", () => {
-  it("leaves arrow keys with contenteditable text", () => {
-    const { host, root } = renderApp();
-    const editor = document.createElement("div");
-    editor.contentEditable = "true";
-    host.append(editor);
-    editor.focus();
-
-    act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight" })));
-
-    expect(onNavigate).not.toHaveBeenCalled();
-    act(() => root.unmount());
-  });
-});