@hyperframes/studio 0.8.49 → 0.8.51

package/src/components/storyboard/frameComments.test.ts

@@ -1,95 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { buildCommentsFile, draftEntries, parseCommentsFile, passForFrames } from "./frameComments";
-
-const frames = [
-  { index: 1, status: "built" as const, src: "compositions/frames/01-hook.html", title: "Hook" },
-  {
-    index: 2,
-    status: "built" as const,
-    src: "compositions/frames/02-thesis.html",
-    title: "Thesis",
-  },
-  { index: 3, status: "built" as const, src: "compositions/frames/03-proof.html", title: "Proof" },
-];
-
-describe("passForFrames", () => {
-  it("maps the furthest status to the review pass", () => {
-    expect(passForFrames([{ status: "outline" }, { status: "outline" }])).toBe("storyboard");
-    expect(passForFrames([{ status: "outline" }, { status: "built" }])).toBe("sketch");
-    expect(passForFrames([{ status: "built" }, { status: "animated" }])).toBe("final");
-  });
-});
-
-describe("draftEntries", () => {
-  it("keeps only non-empty drafts, in board order, with src/title echoed", () => {
-    const entries = draftEntries(frames, { 3: "swap the chart", 1: "  ", 2: "tighter kerning" });
-    expect(entries).toEqual([
-      { frame: 2, src: frames[1]?.src, title: "Thesis", text: "tighter kerning" },
-      { frame: 3, src: frames[2]?.src, title: "Proof", text: "swap the chart" },
-    ]);
-  });
-});
-
-describe("parseCommentsFile", () => {
-  it("reads a well-formed file", () => {
-    const parsed = parseCommentsFile(
-      JSON.stringify({
-        version: 1,
-        pass: "sketch",
-        submitted_at: "2026-07-10T00:00:00Z",
-        comments: [{ frame: 2, text: "hi" }],
-      }),
-    );
-    expect(parsed?.pass).toBe("sketch");
-    expect(parsed?.comments).toEqual([{ frame: 2, src: undefined, title: undefined, text: "hi" }]);
-  });
-
-  it("treats empty or malformed input as no file", () => {
-    expect(parseCommentsFile("")).toBeNull();
-    expect(parseCommentsFile("not json")).toBeNull();
-    expect(parseCommentsFile(JSON.stringify({ comments: "nope" }))).toBeNull();
-  });
-
-  it("drops malformed entries but keeps the valid ones", () => {
-    const parsed = parseCommentsFile(
-      JSON.stringify({ comments: [{ frame: 1, text: "ok" }, { frame: "x" }, null] }),
-    );
-    expect(parsed?.comments).toEqual([{ frame: 1, src: undefined, title: undefined, text: "ok" }]);
-  });
-});
-
-describe("buildCommentsFile", () => {
-  it("merges an unconsumed previous batch: new frames win, others stay", () => {
-    const previous = parseCommentsFile(
-      JSON.stringify({
-        version: 1,
-        pass: "sketch",
-        submitted_at: "2026-07-10T00:00:00Z",
-        comments: [
-          { frame: 1, text: "old note on hook" },
-          { frame: 3, text: "old note on proof" },
-        ],
-      }),
-    );
-    const file = buildCommentsFile(
-      frames,
-      { 3: "new note on proof" },
-      previous,
-      "2026-07-10T01:00:00Z",
-    );
-    expect(file.pass).toBe("sketch");
-    expect(file.submitted_at).toBe("2026-07-10T01:00:00Z");
-    expect(file.comments.map((c) => [c.frame, c.text])).toEqual([
-      [1, "old note on hook"],
-      [3, "new note on proof"],
-    ]);
-  });
-
-  it("writes a fresh batch when no previous file exists", () => {
-    const file = buildCommentsFile(frames, { 2: "tighter" }, null, "2026-07-10T01:00:00Z");
-    expect(file.version).toBe(1);
-    expect(file.comments).toEqual([
-      { frame: 2, src: frames[1]?.src, title: "Thesis", text: "tighter" },
-    ]);
-  });
-});

package/src/components/storyboard/frameComments.ts

@@ -1,115 +0,0 @@
-import type { FrameStatus } from "@hyperframes/core/storyboard";
-
-/**
- * Frame comments — the storyboard review's structured feedback channel.
- *
- * The board's per-frame comment boxes write one batch file on submit; the
- * consuming agent revises exactly the frames named, deletes the file, and
- * re-presents. The file shape is a cross-repo contract — keep it in sync with
- * skills/hyperframes/references/storyboard-format.md § Frame comments.
- */
-export const FRAME_COMMENTS_PATH = ".hyperframes/frame-comments.json";
-
-export type FrameCommentsPass = "storyboard" | "sketch" | "final";
-
-export interface FrameCommentEntry {
-  /** The frame's 1-based `index` in the manifest — the key. */
-  frame: number;
-  /** Copied from the frame at submit time so a post-submit reorder is detectable. */
-  src?: string;
-  title?: string;
-  text: string;
-}
-
-export interface FrameCommentsFile {
-  version: 1;
-  pass: FrameCommentsPass;
-  submitted_at: string;
-  comments: FrameCommentEntry[];
-}
-
-interface CommentableFrame {
-  index: number;
-  status: FrameStatus;
-  src?: string;
-  title?: string;
-}
-
-/** Which review the batch belongs to — the furthest status present on the board. */
-export function passForFrames(frames: ReadonlyArray<{ status: FrameStatus }>): FrameCommentsPass {
-  if (frames.some((f) => f.status === "animated")) return "final";
-  if (frames.some((f) => f.status === "built")) return "sketch";
-  return "storyboard";
-}
-
-/** The non-empty drafts as file entries, in board order. */
-export function draftEntries(
-  frames: readonly CommentableFrame[],
-  drafts: Readonly<Record<number, string>>,
-): FrameCommentEntry[] {
-  const entries: FrameCommentEntry[] = [];
-  for (const frame of frames) {
-    const text = drafts[frame.index]?.trim();
-    if (!text) continue;
-    entries.push({ frame: frame.index, src: frame.src, title: frame.title, text });
-  }
-  return entries;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function parseCommentEntry(item: unknown): FrameCommentEntry | null {
-  if (!isRecord(item)) return null;
-  if (typeof item.frame !== "number" || typeof item.text !== "string") return null;
-  return {
-    frame: item.frame,
-    src: typeof item.src === "string" ? item.src : undefined,
-    title: typeof item.title === "string" ? item.title : undefined,
-    text: item.text,
-  };
-}
-
-function parsePass(value: unknown): FrameCommentsPass {
-  return value === "sketch" || value === "final" ? value : "storyboard";
-}
-
-/** Tolerant read of an existing comments file — anything malformed counts as "no file". */
-export function parseCommentsFile(raw: string): FrameCommentsFile | null {
-  if (!raw.trim()) return null;
-  let data: unknown;
-  try {
-    data = JSON.parse(raw);
-  } catch {
-    return null;
-  }
-  if (!isRecord(data) || !Array.isArray(data.comments)) return null;
-  const comments = data.comments
-    .map(parseCommentEntry)
-    .filter((entry): entry is FrameCommentEntry => entry !== null);
-  return {
-    version: 1,
-    pass: parsePass(data.pass),
-    submitted_at: typeof data.submitted_at === "string" ? data.submitted_at : "",
-    comments,
-  };
-}
-
-/**
- * One file = the currently pending feedback. A resubmit before the agent
- * consumed the previous batch keeps the pending entries for frames the new
- * batch doesn't mention and overwrites the ones it does.
- */
-export function buildCommentsFile(
-  frames: readonly CommentableFrame[],
-  drafts: Readonly<Record<number, string>>,
-  previous: FrameCommentsFile | null,
-  submittedAt: string,
-): FrameCommentsFile {
-  const fresh = draftEntries(frames, drafts);
-  const freshIndexes = new Set(fresh.map((entry) => entry.frame));
-  const kept = previous?.comments.filter((entry) => !freshIndexes.has(entry.frame)) ?? [];
-  const comments = [...kept, ...fresh].sort((a, b) => a.frame - b.frame);
-  return { version: 1, pass: passForFrames(frames), submitted_at: submittedAt, comments };
-}

package/src/components/storyboard/frameStatus.ts

@@ -1,36 +0,0 @@
-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"];

package/src/components/storyboard/storyboardReviewStage.test.ts

@@ -1,40 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { deriveStoryboardHandoffStep, deriveStoryboardReviewStage } from "./storyboardReviewStage";
-
-describe("deriveStoryboardReviewStage", () => {
-  it.each([
-    [[], "empty"],
-    [["outline", "outline"], "plan-review"],
-    [["outline", "built"], "sketch-in-progress"],
-    [["outline", "animated"], "sketch-in-progress"],
-    [["built", "built"], "sketch-review"],
-    [["built", "animated"], "animation-in-progress"],
-    [["animated", "animated"], "final-review"],
-  ] as const)("maps %j to %s", (statuses, expected) => {
-    expect(deriveStoryboardReviewStage(statuses.map((status) => ({ status }))).stage).toBe(
-      expected,
-    );
-  });
-
-  it("returns counts for the visible progress summary", () => {
-    expect(
-      deriveStoryboardReviewStage([
-        { status: "outline" },
-        { status: "built" },
-        { status: "animated" },
-        { status: "animated" },
-      ]).counts,
-    ).toEqual({ outline: 1, built: 1, animated: 2 });
-  });
-});
-
-describe("storyboard review handoff", () => {
-  it.each([
-    [0, 0, 1],
-    [2, 0, 2],
-    [0, 3, 3],
-    [1, 3, 2],
-  ] as const)("maps %i drafts and %i pending comments to step %i", (drafts, pending, step) => {
-    expect(deriveStoryboardHandoffStep(drafts, pending)).toBe(step);
-  });
-});

package/src/components/storyboard/storyboardReviewStage.ts

@@ -1,45 +0,0 @@
-import type { FrameStatus } from "@hyperframes/core/storyboard";
-
-export type StoryboardReviewStage =
-  | "empty"
-  | "plan-review"
-  | "sketch-in-progress"
-  | "sketch-review"
-  | "animation-in-progress"
-  | "final-review";
-
-export interface StoryboardReviewSummary {
-  stage: StoryboardReviewStage;
-  counts: Record<FrameStatus, number>;
-  frameCount: number;
-}
-
-export type StoryboardHandoffStep = 1 | 2 | 3;
-
-/** Current user action in the Studio → agent feedback handoff. */
-export function deriveStoryboardHandoffStep(
-  draftCount: number,
-  pendingCount: number,
-): StoryboardHandoffStep {
-  if (draftCount > 0) return 2;
-  if (pendingCount > 0) return 3;
-  return 1;
-}
-
-/** Derive the board-level review moment from agent-owned frame statuses. */
-export function deriveStoryboardReviewStage(
-  frames: ReadonlyArray<{ status: FrameStatus }>,
-): StoryboardReviewSummary {
-  const counts: Record<FrameStatus, number> = { outline: 0, built: 0, animated: 0 };
-  for (const frame of frames) counts[frame.status] += 1;
-
-  let stage: StoryboardReviewStage;
-  if (frames.length === 0) stage = "empty";
-  else if (counts.outline === frames.length) stage = "plan-review";
-  else if (counts.outline > 0) stage = "sketch-in-progress";
-  else if (counts.built === frames.length) stage = "sketch-review";
-  else if (counts.built > 0) stage = "animation-in-progress";
-  else stage = "final-review";
-
-  return { stage, counts, frameCount: frames.length };
-}

package/src/components/storyboard/useFrameComments.ts

@@ -1,98 +0,0 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
-import { useFileManagerContext } from "../../contexts/FileManagerContext";
-import type { StoryboardFrameView } from "../../hooks/useStoryboard";
-import {
-  FRAME_COMMENTS_PATH,
-  buildCommentsFile,
-  parseCommentsFile,
-  type FrameCommentEntry,
-} from "./frameComments";
-
-export type CommentsSubmitState = "idle" | "saving";
-
-export interface FrameCommentsValue {
-  /** Draft text per frame index — "" / absent means no comment. */
-  drafts: Record<number, string>;
-  setDraft: (index: number, text: string) => void;
-  /** How many frames currently carry a non-empty draft. */
-  draftCount: number;
-  submitState: CommentsSubmitState;
-  /** Most recent submit failure, shown next to the submit action. */
-  submitError: string | null;
-  /** Write the batch to `.hyperframes/frame-comments.json` and clear the drafts. */
-  submit: () => Promise<boolean>;
-  /**
-   * Comments already submitted but not yet consumed by the agent (the file
-   * still exists on disk). Refreshed on mount, after submit, and on window
-   * focus — the agent deletes the file once it has applied the feedback.
-   */
-  pending: FrameCommentEntry[] | null;
-  /** Re-read the comments file — callers hook this to board data refreshes. */
-  refreshPending: () => Promise<void>;
-}
-
-/** Per-frame comment drafts + the batch submit that writes the comments file. */
-export function useFrameComments(frames: StoryboardFrameView[]): FrameCommentsValue {
-  const { writeProjectFile, readOptionalProjectFile } = useFileManagerContext();
-  const [drafts, setDrafts] = useState<Record<number, string>>({});
-  const [submitState, setSubmitState] = useState<CommentsSubmitState>("idle");
-  const [submitError, setSubmitError] = useState<string | null>(null);
-  const [pending, setPending] = useState<FrameCommentEntry[] | null>(null);
-
-  const refreshPending = useCallback(async () => {
-    try {
-      const parsed = parseCommentsFile(await readOptionalProjectFile(FRAME_COMMENTS_PATH));
-      setPending(parsed && parsed.comments.length > 0 ? parsed.comments : null);
-    } catch {
-      // Transient read failure — keep whatever is currently shown.
-    }
-  }, [readOptionalProjectFile]);
-
-  useEffect(() => {
-    void refreshPending();
-    const onFocus = () => void refreshPending();
-    window.addEventListener("focus", onFocus);
-    return () => window.removeEventListener("focus", onFocus);
-  }, [refreshPending]);
-
-  const setDraft = useCallback((index: number, text: string) => {
-    setDrafts((prev) => ({ ...prev, [index]: text }));
-  }, []);
-
-  const draftCount = useMemo(
-    () => Object.values(drafts).filter((text) => text.trim().length > 0).length,
-    [drafts],
-  );
-
-  // One guarded async transaction owns loading, success, failure, and cleanup state.
-  // fallow-ignore-next-line complexity
-  const submit = useCallback(async () => {
-    if (draftCount === 0 || submitState === "saving") return false;
-    setSubmitState("saving");
-    setSubmitError(null);
-    try {
-      const previous = parseCommentsFile(await readOptionalProjectFile(FRAME_COMMENTS_PATH));
-      const file = buildCommentsFile(frames, drafts, previous, new Date().toISOString());
-      await writeProjectFile(FRAME_COMMENTS_PATH, `${JSON.stringify(file, null, 2)}\n`);
-      setDrafts({});
-      setPending(file.comments);
-      return true;
-    } catch (err: unknown) {
-      setSubmitError(err instanceof Error ? err.message : "Failed to submit comments");
-      return false;
-    } finally {
-      setSubmitState("idle");
-    }
-  }, [draftCount, submitState, frames, drafts, readOptionalProjectFile, writeProjectFile]);
-
-  return {
-    drafts,
-    setDraft,
-    draftCount,
-    submitState,
-    submitError,
-    submit,
-    pending,
-    refreshPending,
-  };
-}

package/src/contexts/ViewModeContext.tsx

@@ -1,142 +0,0 @@
-import {
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  type ReactNode,
-} from "react";
-import { createStableContext } from "../utils/hmrStableContext";
-
-/**
- * Top-level Studio view mode.
- *
- * `timeline` is the existing NLE/preview stage. `storyboard` replaces that stage
- * with the storyboard contact sheet. The mode is mirrored to the `?view=` query
- * param so it survives reloads and — importantly — so an agent can deep-link the
- * user straight into the storyboard by navigating the tab to `?view=storyboard`.
- */
-export type StudioViewMode = "timeline" | "storyboard";
-export type ViewModeGuard = (nextMode: StudioViewMode) => boolean;
-
-const VIEW_QUERY_PARAM = "view";
-
-function readViewModeFromUrl(): StudioViewMode {
-  if (typeof window === "undefined") return "timeline";
-  return new URLSearchParams(window.location.search).get(VIEW_QUERY_PARAM) === "storyboard"
-    ? "storyboard"
-    : "timeline";
-}
-
-function writeViewModeToUrl(mode: StudioViewMode): void {
-  if (typeof window === "undefined") return;
-  const url = new URL(window.location.href);
-  if (mode === "storyboard") {
-    url.searchParams.set(VIEW_QUERY_PARAM, "storyboard");
-  } else {
-    url.searchParams.delete(VIEW_QUERY_PARAM);
-  }
-  window.history.replaceState(window.history.state, "", url);
-}
-
-interface HistoryLocation {
-  href: string;
-  state: unknown;
-}
-
-function readHistoryLocation(): HistoryLocation | null {
-  if (typeof window === "undefined") return null;
-  return {
-    href: window.location.href,
-    state: window.history.state,
-  };
-}
-
-export interface ViewModeValue {
-  viewMode: StudioViewMode;
-  /** Returns false when an active editor vetoes the transition. */
-  setViewMode: (mode: StudioViewMode) => boolean;
-  registerViewModeGuard: (guard: ViewModeGuard) => () => void;
-}
-
-/**
- * Owns the view-mode state — initial read from `?view=`, toggling, popstate sync.
- * Storyboard mode is always available; no flag gating.
- */
-export function useViewModeState(): ViewModeValue {
-  const [viewMode, setMode] = useState<StudioViewMode>(() => readViewModeFromUrl());
-  const guardsRef = useRef(new Set<ViewModeGuard>());
-  const acceptedLocationRef = useRef<HistoryLocation | null>(readHistoryLocation());
-
-  const canSetViewMode = useCallback((mode: StudioViewMode) => {
-    for (const guard of guardsRef.current) {
-      if (!guard(mode)) return false;
-    }
-    return true;
-  }, []);
-
-  // Reflect genuine browser back/forward between history entries with a different
-  // `?view=`. Note: our own writes use `replaceState` (below), which does NOT fire
-  // `popstate`, so this listener never sees them — `setViewMode` updates state directly.
-  // An agent deep-links by doing a full navigation to `?view=storyboard` (picked up by
-  // the mount-time read); a scripted `pushState`/`replaceState` to `?view=` would not be
-  // reflected here, by design.
-  useEffect(() => {
-    const onPopState = () => {
-      const mode = readViewModeFromUrl();
-      if (mode !== viewMode && !canSetViewMode(mode)) {
-        const acceptedLocation = acceptedLocationRef.current;
-        if (acceptedLocation) {
-          window.history.pushState(acceptedLocation.state, "", acceptedLocation.href);
-        }
-        return;
-      }
-      setMode(mode);
-      acceptedLocationRef.current = readHistoryLocation();
-    };
-    window.addEventListener("popstate", onPopState);
-    return () => window.removeEventListener("popstate", onPopState);
-  }, [canSetViewMode, viewMode]);
-
-  const setViewMode = useCallback(
-    (mode: StudioViewMode) => {
-      if (!canSetViewMode(mode)) return false;
-      setMode(mode);
-      writeViewModeToUrl(mode);
-      acceptedLocationRef.current = readHistoryLocation();
-      return true;
-    },
-    [canSetViewMode],
-  );
-
-  const registerViewModeGuard = useCallback((guard: ViewModeGuard) => {
-    guardsRef.current.add(guard);
-    return () => {
-      guardsRef.current.delete(guard);
-    };
-  }, []);
-
-  return useMemo(
-    () => ({ viewMode, setViewMode, registerViewModeGuard }),
-    [viewMode, setViewMode, registerViewModeGuard],
-  );
-}
-
-const ViewModeContext = createStableContext<ViewModeValue | null>("ViewModeContext", null);
-
-export function useViewMode(): ViewModeValue {
-  const ctx = useContext(ViewModeContext);
-  if (!ctx) throw new Error("useViewMode must be used within ViewModeProvider");
-  return ctx;
-}
-
-export function ViewModeProvider({
-  value,
-  children,
-}: {
-  value: ViewModeValue;
-  children: ReactNode;
-}) {
-  return <ViewModeContext value={value}>{children}</ViewModeContext>;
-}