@hyperframes/studio 0.7.59 → 0.7.61

package/src/components/storyboard/StoryboardLoaded.tsx

@@ -3,10 +3,14 @@ import type { StoryboardResponse } from "../../hooks/useStoryboard";
 import { Button } from "../ui/Button";
 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";
+import { StoryboardReviewGuide } from "./StoryboardReviewGuide";
+import {
+  AgentChatMessageButton,
+  APPLY_STORYBOARD_FEEDBACK_MESSAGE,
+} from "./AgentChatMessageButton";
 import { useFrameComments, type CommentsSubmitState } from "./useFrameComments";
 
 type SubView = "board" | "source";
@@ -35,6 +39,7 @@ export function StoryboardLoaded({
   const [subView, setSubView] = useState<SubView>("board");
   const [sourceDirty, setSourceDirty] = useState(false);
   const [focusedIndex, setFocusedIndex] = useState<number | null>(null);
+  const [feedbackMessageCopied, setFeedbackMessageCopied] = useState(false);
   const comments = useFrameComments(data.frames);
   // When the board refreshes off a project change (agent revised frames), the
   // agent has likely consumed the comments file too — re-check so the pending
@@ -43,6 +48,20 @@ export function StoryboardLoaded({
   useEffect(() => {
     void refreshPending();
   }, [data.signature, refreshPending]);
+  useEffect(() => {
+    if (comments.draftCount > 0) setFeedbackMessageCopied(false);
+  }, [comments.draftCount]);
+
+  const saveFeedbackAndCopyMessage = async () => {
+    const saved = await comments.submit();
+    if (!saved) return;
+    try {
+      await navigator.clipboard.writeText(APPLY_STORYBOARD_FEEDBACK_MESSAGE);
+      setFeedbackMessageCopied(true);
+    } catch {
+      setFeedbackMessageCopied(false);
+    }
+  };
   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 });
@@ -82,31 +101,54 @@ export function StoryboardLoaded({
         }
         onSaved={reload}
         onSelectComposition={onSelectComposition}
+        scriptExists={Boolean(data.script?.exists)}
+        commentDraft={comments.drafts[focusedFrame.index] ?? ""}
+        onCommentDraftChange={(text) => comments.setDraft(focusedFrame.index, text)}
+        pendingComment={
+          comments.pending?.find((entry) => entry.frame === focusedFrame.index)?.text ?? null
+        }
+        pendingCommentCount={comments.pending?.length ?? 0}
+        commentDraftCount={comments.draftCount}
+        commentsSubmitState={comments.submitState}
+        commentsSubmitError={comments.submitError}
+        feedbackMessageCopied={feedbackMessageCopied}
+        onFeedbackMessageCopied={() => setFeedbackMessageCopied(true)}
+        onSaveFeedback={() => void saveFeedbackAndCopyMessage()}
         posterVersion={data.signature}
       />
     );
   }
 
   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">
+    <div className="flex w-full max-w-[100vw] flex-1 min-h-0 min-w-0 flex-col overflow-hidden bg-neutral-950 text-neutral-200">
+      <div className="flex flex-wrap items-center gap-3 border-b border-neutral-800 px-4 py-2">
         <SubViewToggle value={subView} onChange={changeSubView} />
         {subView === "board" && (
           <CommentsSubmitBar
             draftCount={comments.draftCount}
             pendingCount={comments.pending?.length ?? 0}
             submitState={comments.submitState}
-            onSubmit={() => void comments.submit()}
+            submitError={comments.submitError}
+            messageCopied={feedbackMessageCopied}
+            onSave={() => void saveFeedbackAndCopyMessage()}
+            onMessageCopied={() => setFeedbackMessageCopied(true)}
           />
         )}
       </div>
       {subView === "board" ? (
         <div className="flex-1 min-h-0 overflow-auto">
-          <div className="mx-auto max-w-[1400px] px-8 py-8">
+          <div className="mx-auto max-w-[1400px] px-4 py-5 sm:px-8 sm:py-8">
             <StoryboardDirection globals={data.globals} frameCount={data.frames.length} />
-            <div className="mt-5">
-              <StoryboardStatusLegend />
-            </div>
+            <StoryboardReviewGuide
+              frames={data.frames}
+              draftCount={comments.draftCount}
+              pendingCount={comments.pending?.length ?? 0}
+              onFeedbackMessageCopied={() => setFeedbackMessageCopied(true)}
+            />
+            <StoryboardWarnings
+              warnings={data.warnings}
+              onOpenSource={() => changeSubView("source")}
+            />
             <StoryboardGrid
               projectId={projectId}
               frames={data.frames}
@@ -135,34 +177,90 @@ function CommentsSubmitBar({
   draftCount,
   pendingCount,
   submitState,
-  onSubmit,
+  submitError,
+  messageCopied,
+  onSave,
+  onMessageCopied,
 }: {
   draftCount: number;
   pendingCount: number;
   submitState: CommentsSubmitState;
-  onSubmit: () => void;
+  submitError: string | null;
+  messageCopied: boolean;
+  onSave: () => void;
+  onMessageCopied: () => void;
 }) {
   return (
-    <div className="ml-auto flex items-center gap-3">
+    <div className="ml-auto flex min-w-0 flex-1 flex-wrap items-center justify-end gap-2 sm:flex-none">
       {pendingCount > 0 && (
-        <span className="text-xs text-sky-300">
-          {pendingCount} comment{pendingCount > 1 ? "s" : ""} pending — reply anything in your agent
-          chat and it will apply them.
+        <>
+          <span className="text-xs text-sky-300">
+            {messageCopied
+              ? "Feedback saved · Message copied — paste it in your terminal or IDE agent chat."
+              : "Feedback saved · Agent not notified."}
+          </span>
+          <AgentChatMessageButton
+            message={APPLY_STORYBOARD_FEEDBACK_MESSAGE}
+            label={messageCopied ? "Copy again" : "Copy prompt for agent"}
+            onCopied={onMessageCopied}
+          />
+        </>
+      )}
+      {pendingCount === 0 && draftCount === 0 && (
+        <span className="text-xs text-neutral-500">Add frame comments to request changes.</span>
+      )}
+      {submitError && (
+        <span className="max-w-64 truncate text-xs text-red-400" title={submitError}>
+          Couldn’t submit: {submitError}
         </span>
       )}
-      <Button
-        variant="primary"
-        size="sm"
-        loading={submitState === "saving"}
-        disabled={draftCount === 0 || submitState === "saving"}
-        onClick={onSubmit}
-      >
-        {draftCount > 0 ? `Submit comments (${draftCount})` : "Submit comments"}
-      </Button>
+      {draftCount > 0 && (
+        <Button
+          variant="primary"
+          size="sm"
+          loading={submitState === "saving"}
+          disabled={submitState === "saving"}
+          onClick={onSave}
+        >
+          Save &amp; copy message ({draftCount})
+        </Button>
+      )}
     </div>
   );
 }
 
+function StoryboardWarnings({
+  warnings,
+  onOpenSource,
+}: {
+  warnings: StoryboardResponse["warnings"];
+  onOpenSource: () => void;
+}) {
+  if (warnings.length === 0) return null;
+  return (
+    <details className="mt-3 rounded-lg border border-amber-900/60 bg-amber-950/20 px-4 py-2 text-xs text-amber-200">
+      <summary className="cursor-pointer font-medium">
+        {warnings.length} storyboard warning{warnings.length === 1 ? "" : "s"}
+      </summary>
+      <ul className="mt-2 space-y-1 text-amber-200/80">
+        {warnings.map((warning, index) => (
+          <li key={`${warning.line ?? "unknown"}-${index}`}>
+            {warning.line ? `Line ${warning.line}: ` : ""}
+            {warning.message}
+          </li>
+        ))}
+      </ul>
+      <button
+        type="button"
+        onClick={onOpenSource}
+        className="mt-2 rounded text-amber-100 underline underline-offset-2 hover:text-white"
+      >
+        Open source to fix
+      </button>
+    </details>
+  );
+}
+
 const SUB_VIEWS: Array<{ value: SubView; label: string }> = [
   { value: "board", label: "Board" },
   { value: "source", label: "Source" },

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