@hyperframes/studio 0.7.60 → 0.7.61

package/src/components/storyboard/StoryboardReviewGuide.tsx

@@ -0,0 +1,300 @@
+import type { StoryboardFrameView } from "../../hooks/useStoryboard";
+import {
+  AgentChatMessageButton,
+  APPLY_STORYBOARD_FEEDBACK_MESSAGE,
+} from "./AgentChatMessageButton";
+import { FRAME_STATUS_META, FRAME_STATUS_ORDER } from "./frameStatus";
+import {
+  deriveStoryboardHandoffStep,
+  deriveStoryboardReviewStage,
+  type StoryboardHandoffStep,
+  type StoryboardReviewStage,
+} from "./storyboardReviewStage";
+
+const GUIDE_COPY: Record<StoryboardReviewStage, { eyebrow: string; title: string; body: string }> =
+  {
+    empty: {
+      eyebrow: "Waiting for a plan",
+      title: "The storyboard has no frames yet",
+      body: "Ask your agent to draft the story plan. Frames will appear here automatically.",
+    },
+    "plan-review": {
+      eyebrow: "Ready for review",
+      title: "Review the story plan",
+      body: "Check the sequence, scene direction, and voiceover before visual work begins. Leave frame comments, save them, then reply in your terminal or IDE agent chat.",
+    },
+    "sketch-in-progress": {
+      eyebrow: "Build in progress",
+      title: "Visual sketches are in progress",
+      body: "New posters appear automatically as your agent builds them. You can comment now; wait until no frames remain in Outline before approving the layouts.",
+    },
+    "sketch-review": {
+      eyebrow: "Ready for review",
+      title: "Review the visual direction",
+      body: "Check composition, hierarchy, and copy. Save frame comments, then reply in your terminal or IDE agent chat.",
+    },
+    "animation-in-progress": {
+      eyebrow: "Build in progress",
+      title: "Animation is in progress",
+      body: "The board refreshes as frames advance. Review completed frames now; the final review is ready when every frame is Animated.",
+    },
+    "final-review": {
+      eyebrow: "Ready for review",
+      title: "Review motion and timing",
+      body: "Every frame is animated. Open a frame in Preview to review it in the timeline, or leave frame comments for another revision.",
+    },
+  };
+
+const REVIEW_ACTION_COPY: Record<
+  StoryboardReviewStage,
+  { body: string; approvalMessage?: string }
+> = {
+  empty: { body: "Add comments as previews arrive." },
+  "plan-review": {
+    body: "Add comments where you want changes. If everything looks right, approve this pass in agent chat.",
+    approvalMessage: "Approve this storyboard plan and continue to visual sketches.",
+  },
+  "sketch-in-progress": {
+    body: "Add comments as previews arrive. You’ll be prompted to approve when this pass is ready.",
+  },
+  "sketch-review": {
+    body: "Add comments where you want changes. If everything looks right, approve this pass in agent chat.",
+    approvalMessage: "Approve these storyboard sketches and continue to animation.",
+  },
+  "animation-in-progress": {
+    body: "Add comments as previews arrive. You’ll be prompted to approve when this pass is ready.",
+  },
+  "final-review": {
+    body: "Add comments where you want changes. If everything looks right, approve this pass in agent chat.",
+    approvalMessage: "Approve this final storyboard review and continue to rendering.",
+  },
+};
+
+type ReviewStepOffset = -1 | 0 | 1;
+const REVIEW_STEP_STATES: Record<
+  ReviewStepOffset,
+  {
+    textClass: string;
+    numberClass: string;
+    ariaCurrent: "step" | undefined;
+    marker: (number: StoryboardHandoffStep) => StoryboardHandoffStep | string;
+  }
+> = {
+  [-1]: {
+    textClass: "text-emerald-400",
+    numberClass: "border-emerald-700 bg-emerald-500/10",
+    ariaCurrent: undefined,
+    marker: () => "✓",
+  },
+  [0]: {
+    textClass: "text-sky-300",
+    numberClass: "border-sky-500 bg-sky-500/15",
+    ariaCurrent: "step",
+    marker: (number) => number,
+  },
+  [1]: {
+    textClass: "text-neutral-600",
+    numberClass: "border-neutral-700",
+    ariaCurrent: undefined,
+    marker: (number) => number,
+  },
+};
+
+const REVIEW_STEP_SEPARATOR_CLASS: Record<StoryboardHandoffStep, string> = {
+  1: "invisible",
+  2: "",
+  3: "",
+};
+
+export interface StoryboardReviewGuideProps {
+  frames: StoryboardFrameView[];
+  draftCount: number;
+  pendingCount: number;
+  onFeedbackMessageCopied: () => void;
+}
+
+/** Stage-aware instructions plus the explicit Studio → agent handoff. */
+export function StoryboardReviewGuide({
+  frames,
+  draftCount,
+  pendingCount,
+  onFeedbackMessageCopied,
+}: StoryboardReviewGuideProps) {
+  const summary = deriveStoryboardReviewStage(frames);
+  const copy = GUIDE_COPY[summary.stage];
+  const handoffStep = deriveStoryboardHandoffStep(draftCount, pendingCount);
+  const progress = progressLabel(summary);
+
+  return (
+    <section className="mt-5 rounded-lg border border-neutral-800 bg-neutral-900/60 px-4 py-3">
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+        <div className="max-w-3xl">
+          <div className="text-[10px] font-semibold uppercase tracking-wider text-sky-400">
+            {copy.eyebrow}
+          </div>
+          <h2 className="mt-0.5 text-sm font-semibold text-neutral-100">{copy.title}</h2>
+          <p className="mt-1 text-xs leading-relaxed text-neutral-400">{copy.body}</p>
+        </div>
+        {summary.frameCount > 0 && (
+          <div className="shrink-0">
+            <div className="mb-1.5 text-right text-[11px] font-medium text-neutral-300">
+              {progress}
+            </div>
+            <div className="flex flex-wrap justify-end gap-1.5" aria-label="Frame status summary">
+              {FRAME_STATUS_ORDER.map((status) => (
+                <span
+                  key={status}
+                  className={`rounded px-2 py-1 text-[10px] font-medium ${FRAME_STATUS_META[status].chipClass}`}
+                >
+                  {summary.counts[status]} {FRAME_STATUS_META[status].label}
+                </span>
+              ))}
+            </div>
+          </div>
+        )}
+      </div>
+
+      {summary.frameCount > 0 && (
+        <div className="mt-3 border-t border-neutral-800 pt-3">
+          <ReviewSteps current={handoffStep} />
+          <NextAction
+            stage={summary.stage}
+            step={handoffStep}
+            draftCount={draftCount}
+            onFeedbackMessageCopied={onFeedbackMessageCopied}
+          />
+        </div>
+      )}
+    </section>
+  );
+}
+
+function ReviewSteps({ current }: { current: StoryboardHandoffStep }) {
+  const steps = ["Review frames", "Save feedback", "Reply in agent chat"];
+  return (
+    <ol className="hidden items-center gap-2 sm:flex" aria-label="Storyboard review workflow">
+      {steps.map((label, index) => (
+        <ReviewStep
+          key={label}
+          label={label}
+          number={(index + 1) as StoryboardHandoffStep}
+          current={current}
+        />
+      ))}
+    </ol>
+  );
+}
+
+function ReviewStep({
+  label,
+  number,
+  current,
+}: {
+  label: string;
+  number: StoryboardHandoffStep;
+  current: StoryboardHandoffStep;
+}) {
+  const offset = Math.sign(number - current) as ReviewStepOffset;
+  const state = REVIEW_STEP_STATES[offset];
+
+  return (
+    <li className="flex items-center gap-2">
+      <span
+        className={`text-neutral-700 ${REVIEW_STEP_SEPARATOR_CLASS[number]}`}
+        aria-hidden="true"
+      >
+        →
+      </span>
+      <span
+        aria-current={state.ariaCurrent}
+        className={`flex items-center gap-1.5 text-[11px] font-medium ${state.textClass}`}
+      >
+        <span
+          className={`flex h-5 w-5 items-center justify-center rounded-full border text-[10px] ${state.numberClass}`}
+        >
+          {state.marker(number)}
+        </span>
+        {label}
+      </span>
+    </li>
+  );
+}
+
+function NextAction({
+  stage,
+  step,
+  draftCount,
+  onFeedbackMessageCopied,
+}: {
+  stage: StoryboardReviewStage;
+  step: StoryboardHandoffStep;
+  draftCount: number;
+  onFeedbackMessageCopied: () => void;
+}) {
+  if (step === 3) {
+    return <AgentHandoffAction onFeedbackMessageCopied={onFeedbackMessageCopied} />;
+  }
+  if (step === 2) return <SaveFeedbackAction draftCount={draftCount} />;
+  return <ReviewFramesAction stage={stage} />;
+}
+
+function AgentHandoffAction({ onFeedbackMessageCopied }: { onFeedbackMessageCopied: () => void }) {
+  return (
+    <div className="mt-3 flex flex-col gap-3 rounded-md border border-sky-900/70 bg-sky-950/20 px-3 py-2.5 sm:flex-row sm:items-center sm:justify-between">
+      <div className="max-w-3xl">
+        <div className="text-xs font-semibold text-sky-200">Next: return to your agent chat</div>
+        <p className="mt-0.5 text-[11px] text-neutral-400">
+          Feedback is saved, but the agent has not been notified. Paste this prompt in your terminal
+          or IDE agent chat.
+        </p>
+      </div>
+      <AgentChatMessageButton
+        message={APPLY_STORYBOARD_FEEDBACK_MESSAGE}
+        onCopied={onFeedbackMessageCopied}
+      />
+    </div>
+  );
+}
+
+function SaveFeedbackAction({ draftCount }: { draftCount: number }) {
+  return (
+    <div className="mt-3 rounded-md border border-neutral-800 bg-neutral-950/40 px-3 py-2.5">
+      <div>
+        <div className="text-xs font-semibold text-neutral-200">Next: save your feedback</div>
+        <p className="mt-0.5 text-[11px] text-neutral-500">
+          {draftCount} frame{draftCount === 1 ? " has" : "s have"} feedback ready. Use Save &amp;
+          copy message above to prepare this batch for your agent.
+        </p>
+      </div>
+    </div>
+  );
+}
+
+function ReviewFramesAction({ stage }: { stage: StoryboardReviewStage }) {
+  const copy = REVIEW_ACTION_COPY[stage];
+
+  return (
+    <div className="mt-3 flex flex-col gap-3 rounded-md border border-neutral-800 bg-neutral-950/40 px-3 py-2.5 sm:flex-row sm:items-center sm:justify-between">
+      <div>
+        <div className="text-xs font-semibold text-neutral-200">Next: review the frames</div>
+        <p className="mt-0.5 text-[11px] text-neutral-500">{copy.body}</p>
+      </div>
+      {copy.approvalMessage && (
+        <AgentChatMessageButton message={copy.approvalMessage} label="Copy approval message" />
+      )}
+    </div>
+  );
+}
+
+// The label intentionally folds six workflow states into three user-facing progress formats.
+// fallow-ignore-next-line complexity
+function progressLabel(summary: ReturnType<typeof deriveStoryboardReviewStage>): string {
+  if (summary.stage === "sketch-in-progress" || summary.stage === "sketch-review") {
+    const ready = summary.frameCount - summary.counts.outline;
+    return `${ready} of ${summary.frameCount} visual sketches ready`;
+  }
+  if (summary.stage === "animation-in-progress" || summary.stage === "final-review") {
+    return `${summary.counts.animated} of ${summary.frameCount} animations ready`;
+  }
+  return `${summary.frameCount} plan frame${summary.frameCount === 1 ? "" : "s"} ready`;
+}

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

@@ -0,0 +1,170 @@
+// @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();
+
+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={1}
+          onBack={vi.fn()}
+          onNavigate={vi.fn()}
+          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();
+});
+
+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());
+  });
+});

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

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

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

@@ -17,8 +17,10 @@ export interface FrameCommentsValue {
   /** 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<void>;
+  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
@@ -34,6 +36,7 @@ export function useFrameComments(frames: StoryboardFrameView[]): FrameCommentsVa
   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 () => {
@@ -61,22 +64,35 @@ export function useFrameComments(frames: StoryboardFrameView[]): FrameCommentsVa
     [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;
+    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);
-    } catch {
-      // writeProjectFile surfaces save failures through the studio save banner;
-      // just re-arm the button so the user can retry.
+      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, submit, pending, refreshPending };
+  return {
+    drafts,
+    setDraft,
+    draftCount,
+    submitState,
+    submitError,
+    submit,
+    pending,
+    refreshPending,
+  };
 }