plotlink-ows 1.2.94 → 1.2.96

package/app/web/components/CutListPanel.tsx

@@ -1,15 +1,34 @@
-import { useState, useEffect, useCallback, useRef } from "react";
+import { Fragment, useState, useEffect, useCallback, useRef } from "react";
 import { LetteringEditor } from "./LetteringEditor";
 import { AssetImage, assetUrl } from "./asset-image";
-import { buildCodexTaskPrompt, buildLetteringPrompt } from "@app-lib/cartoon-prompt";
+import { buildCodexTaskPrompt } from "@app-lib/cartoon-prompt";
 import type { Cut as LibCut } from "@app-lib/cuts";
 import { isTextPanel, isStaleTailedExport } from "@app-lib/cuts";
-import { withRateLimitRetry, createUploadThrottle, type RetryDeps } from "../lib/upload-retry";
-import { importImageToCompliantBlob, isCompliantImage } from "../lib/import-image";
+import {
+  withRateLimitRetry,
+  createUploadThrottle,
+  type RetryDeps,
+} from "../lib/upload-retry";
+import {
+  importImageToCompliantBlob,
+  isCompliantImage,
+} from "../lib/import-image";
 import { CodexImportPicker } from "./CodexImportPicker";
 import { FinishEpisodePanel } from "./FinishEpisodePanel";
-import { cartoonChecklist, checkMarkdownReadiness } from "@app-lib/cartoon-readiness";
-import { summarizeAssetDiagnostics, type CutAssetDiagnostic } from "@app-lib/cut-asset-diagnostics";
+import {
+  cartoonChecklist,
+  checkMarkdownReadiness,
+} from "@app-lib/cartoon-readiness";
+import {
+  summarizeAssetDiagnostics,
+  type CutAssetDiagnostic,
+} from "@app-lib/cut-asset-diagnostics";
+import {
+  buildDraftOverlays,
+  overlaysSignature,
+  cutScriptLines,
+} from "@app-lib/lettering-status";
+import type { CutAiDraft } from "@app-lib/cuts";
 
 interface Overlay {
   id: string;
@@ -54,6 +73,7 @@ interface Cut {
   uploadedUrl: string | null;
   overlays: Overlay[];
   kind?: "image" | "text";
+  aiDraft?: CutAiDraft | null;
   background?: string;
   aspectRatio?: string;
   finalRendererVersion?: number;
@@ -83,10 +103,32 @@ interface CutListPanelProps {
   // is called once applied so the parent can clear the request.
   focusRequest?: { cutId: number; openEditor: boolean; seq: number } | null;
   onFocusHandled?: () => void;
+  /** Enter/leave the wider app's focused lettering mode (#493). */
+  onFocusedLetteringModeChange?: (active: boolean) => void;
+  /** Whether the surrounding work area is currently restored while editing. */
+  workspaceVisible?: boolean;
+  /** Restore/fold the wider app work area while staying in the editor. */
+  onWorkspaceVisibleChange?: (visible: boolean) => void;
 }
 
 type CutStatus = "missing" | "clean" | "lettered" | "uploaded" | "text";
 
+function canDraftLettering(cut: Cut): boolean {
+  return (
+    (!!cut.cleanImagePath || isTextPanel(cut)) && cutScriptLines(cut).length > 0
+  );
+}
+
+function buildAiDraftState(overlays: Overlay[]): CutAiDraft {
+  const now = new Date().toISOString();
+  return {
+    status: "generated",
+    baseSig: overlaysSignature(overlays),
+    generatedAt: now,
+    updatedAt: now,
+  };
+}
+
 function getCutStatus(cut: Cut): CutStatus {
   if (cut.uploadedCid) return "uploaded";
   if (cut.finalImagePath || cut.exportedAt) return "lettered";
@@ -101,14 +143,31 @@ function getCutStatus(cut: Cut): CutStatus {
 // per cut + the single primary human action, instead of internal field names.
 type BoardTone = "muted" | "amber" | "green" | "accent";
 const BOARD_TONE_TEXT: Record<BoardTone, string> = {
-  muted: "text-muted", amber: "text-amber-700", green: "text-green-700", accent: "text-accent",
+  muted: "text-muted",
+  amber: "text-amber-700",
+  green: "text-green-700",
+  accent: "text-accent",
 };
 const BOARD_TONE_DOT: Record<BoardTone, string> = {
-  muted: "bg-muted/40", amber: "bg-amber-500", green: "bg-green-600", accent: "bg-accent",
+  muted: "bg-muted/40",
+  amber: "bg-amber-500",
+  green: "bg-green-600",
+  accent: "bg-accent",
 };
 
-type BoardStatusKey = "uploaded" | "exported" | "convert" | "text" | "review" | "letter" | "needs-image";
-interface BoardStatus { key: BoardStatusKey; label: string; tone: BoardTone }
+type BoardStatusKey =
+  | "uploaded"
+  | "exported"
+  | "convert"
+  | "text"
+  | "review"
+  | "letter"
+  | "needs-image";
+interface BoardStatus {
+  key: BoardStatusKey;
+  label: string;
+  tone: BoardTone;
+}
 
 /**
  * Map a cut's real state to one creator-facing board status (#440). `.png` clean
@@ -117,11 +176,17 @@ interface BoardStatus { key: BoardStatusKey; label: string; tone: BoardTone }
  * Details. Precedence follows the pipeline: uploaded → exported → convert →
  * letter/review → needs image.
  */
-function boardStatus(cut: Cut, needsConversion: boolean, hasStale: boolean): BoardStatus {
+function boardStatus(
+  cut: Cut,
+  needsConversion: boolean,
+  hasStale: boolean,
+): BoardStatus {
   // Uploaded content lives on IPFS, so a missing LOCAL file is not a defect.
-  if (cut.uploadedCid || cut.uploadedUrl) return { key: "uploaded", label: "Uploaded", tone: "green" };
+  if (cut.uploadedCid || cut.uploadedUrl)
+    return { key: "uploaded", label: "Uploaded", tone: "green" };
   // PNG clean art is an actionable conversion step (#441).
-  if (needsConversion) return { key: "convert", label: "Needs conversion", tone: "amber" };
+  if (needsConversion)
+    return { key: "convert", label: "Needs conversion", tone: "amber" };
   // A recorded asset path that's broken on disk (#302) must NOT read as a
   // finished "Exported"/clean cut (#440 RE1): a recorded final needs
   // re-review/re-export; otherwise the clean art is gone → needs image. The
@@ -131,8 +196,10 @@ function boardStatus(cut: Cut, needsConversion: boolean, hasStale: boolean): Boa
       ? { key: "review", label: "Needs review", tone: "amber" }
       : { key: "needs-image", label: "Needs image", tone: "muted" };
   }
-  if (cut.finalImagePath) return { key: "exported", label: "Exported", tone: "green" };
-  if (isTextPanel(cut)) return { key: "text", label: "Ready for captions", tone: "accent" };
+  if (cut.finalImagePath)
+    return { key: "exported", label: "Exported", tone: "green" };
+  if (isTextPanel(cut))
+    return { key: "text", label: "Ready for captions", tone: "accent" };
   if (cut.cleanImagePath) {
     return (cut.overlays?.length ?? 0) > 0
       ? { key: "review", label: "Needs review", tone: "amber" }
@@ -141,6 +208,59 @@ function boardStatus(cut: Cut, needsConversion: boolean, hasStale: boolean): Boa
   return { key: "needs-image", label: "Needs image", tone: "muted" };
 }
 
+function letteringReviewState(cut: Cut): {
+  label: string;
+  detail: string;
+  tone: BoardTone;
+} {
+  if (cut.uploadedCid || cut.uploadedUrl) {
+    return { label: "Complete", detail: "Final image uploaded", tone: "green" };
+  }
+  if (cut.finalImagePath || cut.exportedAt) {
+    return { label: "Exported", detail: "Ready to upload", tone: "green" };
+  }
+  if ((cut.overlays?.length ?? 0) > 0) {
+    if (cut.aiDraft?.status === "generated") {
+      return {
+        label: "Draft ready",
+        detail: `${cut.overlays.length} AI-drafted overlay${cut.overlays.length === 1 ? "" : "s"} ready to review`,
+        tone: "amber",
+      };
+    }
+    return {
+      label: "User-edited",
+      detail: `${cut.overlays.length} overlay${cut.overlays.length === 1 ? "" : "s"} adjusted and ready to review`,
+      tone: "amber",
+    };
+  }
+  if (canDraftLettering(cut)) {
+    return {
+      label: "No draft",
+      detail: "Draft with AI or place bubbles manually",
+      tone: "muted",
+    };
+  }
+  if (isTextPanel(cut)) {
+    return {
+      label: "Between-scene card",
+      detail: "Open to add narration or title text",
+      tone: "accent",
+    };
+  }
+  if (cut.cleanImagePath) {
+    return {
+      label: "Unlettered",
+      detail: "Clean art ready for bubble placement",
+      tone: "muted",
+    };
+  }
+  return {
+    label: "Needs artwork",
+    detail: "Add or sync clean art first",
+    tone: "muted",
+  };
+}
+
 function CutRow({
   cut,
   storyName,
@@ -153,6 +273,8 @@ function CutRow({
   detectedLocalClean,
   onSyncClean,
   syncing,
+  onAiDraft,
+  aiDrafting,
   staleMessages,
   onRepairStale,
   repairing,
@@ -172,6 +294,8 @@ function CutRow({
   detectedLocalClean: boolean;
   onSyncClean: () => void;
   syncing: boolean;
+  onAiDraft: () => void;
+  aiDrafting: boolean;
   staleMessages: string[];
   onRepairStale: () => void;
   repairing: boolean;
@@ -190,10 +314,6 @@ function CutRow({
   // generated PNG into this cut without hunting through a hidden folder.
   const [showCodexPicker, setShowCodexPicker] = useState(false);
   const [convertingThis, setConvertingThis] = useState(false);
-  // Lettering is a first-class step (#442): an intentional Manual vs AI-draft
-  // choice per cut, surfaced on the card (not hidden under Edit).
-  const [letteringMode, setLetteringMode] = useState<"manual" | "ai">("manual");
-  const [letteringCopied, setLetteringCopied] = useState(false);
   const status = getCutStatus(cut);
   // A recorded cleanImagePath/finalImagePath whose file is missing/invalid (#302):
   // surface it precisely rather than letting the field-based status claim the cut
@@ -213,46 +333,54 @@ function CutRow({
 
   // Returns true on a successful upload so callers (e.g. the Codex import picker)
   // can close themselves only when the clean image was actually recorded.
-  const handleUpload = useCallback(async (file: File): Promise<boolean> => {
-    setUploading(true);
-    setUploadError(null);
-    try {
-      // Accept Codex-generated images (e.g. large PNG) by converting/compressing
-      // them to a compliant WebP/JPEG <=1MB in the browser first (#301). An
-      // already-compliant WebP/JPEG is passed through untouched, so the manual
-      // upload behavior is unchanged. A source that cannot be decoded or
-      // compressed under 1MB surfaces a clear error instead of saving anything.
-      let upload: Blob = file;
-      if (!isCompliantImage(file)) {
-        try {
-          upload = await importImageToCompliantBlob(file);
-        } catch (err) {
-          setUploadError(err instanceof Error ? err.message : "Could not import image");
-          return false;
+  const handleUpload = useCallback(
+    async (file: File): Promise<boolean> => {
+      setUploading(true);
+      setUploadError(null);
+      try {
+        // Accept Codex-generated images (e.g. large PNG) by converting/compressing
+        // them to a compliant WebP/JPEG <=1MB in the browser first (#301). An
+        // already-compliant WebP/JPEG is passed through untouched, so the manual
+        // upload behavior is unchanged. A source that cannot be decoded or
+        // compressed under 1MB surfaces a clear error instead of saving anything.
+        let upload: Blob = file;
+        if (!isCompliantImage(file)) {
+          try {
+            upload = await importImageToCompliantBlob(file);
+          } catch (err) {
+            setUploadError(
+              err instanceof Error ? err.message : "Could not import image",
+            );
+            return false;
+          }
         }
-      }
 
-      const ext = upload.type === "image/jpeg" ? "jpg" : "webp";
-      const formData = new FormData();
-      formData.append("file", new File([upload], `clean.${ext}`, { type: upload.type }));
-      const res = await authFetch(
-        `/api/stories/${storyName}/cuts/${plotFile}/upload-clean/${cut.id}`,
-        { method: "POST", body: formData },
-      );
-      if (!res.ok) {
-        const data = await res.json();
-        setUploadError(data.error || "Upload failed");
+        const ext = upload.type === "image/jpeg" ? "jpg" : "webp";
+        const formData = new FormData();
+        formData.append(
+          "file",
+          new File([upload], `clean.${ext}`, { type: upload.type }),
+        );
+        const res = await authFetch(
+          `/api/stories/${storyName}/cuts/${plotFile}/upload-clean/${cut.id}`,
+          { method: "POST", body: formData },
+        );
+        if (!res.ok) {
+          const data = await res.json();
+          setUploadError(data.error || "Upload failed");
+          return false;
+        }
+        onUpdated();
+        return true;
+      } catch {
+        setUploadError("Upload failed");
         return false;
+      } finally {
+        setUploading(false);
       }
-      onUpdated();
-      return true;
-    } catch {
-      setUploadError("Upload failed");
-      return false;
-    } finally {
-      setUploading(false);
-    }
-  }, [authFetch, storyName, plotFile, cut.id, onUpdated]);
+    },
+    [authFetch, storyName, plotFile, cut.id, onUpdated],
+  );
 
   // Creator-facing board status + the single primary action for this cut (#440).
   const board = boardStatus(cut, needsConversion, hasStale);
@@ -264,21 +392,50 @@ function CutRow({
   // first-class Manual/AI-draft lettering choice instead of a single button.
   const bubblesPlaced = cut.overlays?.length ?? 0;
   const atLetteringStage =
-    !isTextPanel(cut) && !!cut.cleanImagePath && !cut.finalImagePath &&
-    !cut.uploadedCid && !cut.uploadedUrl && !hasStale && !needsConversion;
-
-  const copyLetteringPrompt = useCallback(() => {
-    navigator.clipboard?.writeText(buildLetteringPrompt(cut as unknown as LibCut, plotFile));
-    setLetteringCopied(true);
-    setTimeout(() => setLetteringCopied(false), 2000);
-  }, [cut, plotFile]);
+    !isTextPanel(cut) &&
+    !!cut.cleanImagePath &&
+    !cut.finalImagePath &&
+    !cut.uploadedCid &&
+    !cut.uploadedUrl &&
+    !hasStale &&
+    !needsConversion;
+  const canAiDraft =
+    !hasStale &&
+    !needsConversion &&
+    !cut.finalImagePath &&
+    !cut.uploadedCid &&
+    !cut.uploadedUrl &&
+    canDraftLettering(cut);
+  const aiDraftLabel =
+    (cut.overlays?.length ?? 0) > 0 ? "Re-draft with AI" : "AI draft lettering";
 
   const primary: { label: string; onClick: () => void; testid: string } | null =
-    board.key === "convert" ? { label: convertingThis ? "Converting…" : "Convert image", onClick: handleConvertThis, testid: `card-convert-${cut.id}` }
-    : board.key === "review" ? { label: "Review cut", onClick: onOpenEditor, testid: `card-review-${cut.id}` }
-    : board.key === "text" ? { label: "Add captions", onClick: onOpenEditor, testid: `card-letter-${cut.id}` }
-    : board.key === "needs-image" ? { label: "Add artwork", onClick: onToggle, testid: `card-addart-${cut.id}` }
-    : null; // exported / uploaded — the next action is the episode-level upload/publish
+    board.key === "convert"
+      ? {
+          label: convertingThis ? "Converting…" : "Convert image",
+          onClick: handleConvertThis,
+          testid: `card-convert-${cut.id}`,
+        }
+      : board.key === "review"
+        ? {
+            label: "Review cut",
+            onClick: onOpenEditor,
+            testid: `card-review-${cut.id}`,
+          }
+        : board.key === "text"
+          ? {
+              label: "Add captions",
+              onClick: onOpenEditor,
+              testid: `card-letter-${cut.id}`,
+            }
+          : board.key === "needs-image"
+            ? {
+                label: "Add artwork",
+                onClick: onToggle,
+                testid: `card-addart-${cut.id}`,
+              }
+            : null; // exported / uploaded — the next action is the episode-level upload/publish
+  const reviewState = letteringReviewState(cut);
 
   return (
     <div
@@ -290,10 +447,19 @@ function CutRow({
           action, plus an "Open details" toggle for the technical controls (#440). */}
       <div className="px-3 py-2 space-y-2" data-testid={`cut-card-${cut.id}`}>
         <div className="flex items-center gap-2 text-sm">
-          <span className={`w-2 h-2 rounded-full flex-shrink-0 ${BOARD_TONE_DOT[board.tone]}`} />
-          <span className="font-medium text-xs text-foreground">Cut {String(cut.id).padStart(2, "0")}</span>
-          <span className="font-mono text-[10px] text-muted">· {cut.shotType}</span>
-          <span className={`ml-auto text-[10px] font-medium flex-shrink-0 ${BOARD_TONE_TEXT[board.tone]}`} data-testid={`cut-card-status-${cut.id}`}>
+          <span
+            className={`w-2 h-2 rounded-full flex-shrink-0 ${BOARD_TONE_DOT[board.tone]}`}
+          />
+          <span className="font-medium text-xs text-foreground">
+            Cut {String(cut.id).padStart(2, "0")}
+          </span>
+          <span className="font-mono text-[10px] text-muted">
+            · {cut.shotType}
+          </span>
+          <span
+            className={`ml-auto text-[10px] font-medium flex-shrink-0 ${BOARD_TONE_TEXT[board.tone]}`}
+            data-testid={`cut-card-status-${cut.id}`}
+          >
             {board.label}
           </span>
         </div>
@@ -303,13 +469,25 @@ function CutRow({
             assetPath={thumbPath}
             authFetch={authFetch}
             alt={`Cut ${cut.id} artwork`}
-            className="w-full max-h-44 object-contain rounded border border-border bg-white"
+            className="w-full max-h-[32rem] object-contain rounded border border-border bg-white"
           />
         ) : (
-          <div className="w-full h-20 rounded border border-dashed border-border bg-surface/40 flex items-center justify-center text-[10px] text-muted" data-testid={`cut-card-noart-${cut.id}`}>
-            {isTextPanel(cut) ? "Text panel — no artwork needed" : "No artwork yet"}
+          <div
+            className="w-full min-h-28 rounded border border-dashed border-border bg-surface/40 flex items-center justify-center text-[10px] text-muted"
+            data-testid={`cut-card-noart-${cut.id}`}
+          >
+            {isTextPanel(cut)
+              ? "Text panel — no artwork needed"
+              : "No artwork yet"}
           </div>
         )}
+        <div
+          className={`rounded border border-border/70 bg-surface/50 px-2 py-1.5 text-[11px] ${BOARD_TONE_TEXT[reviewState.tone]}`}
+          data-testid={`lettering-review-state-${cut.id}`}
+        >
+          <span className="font-semibold">{reviewState.label}</span>
+          <span className="text-muted"> · {reviewState.detail}</span>
+        </div>
         <button
           onClick={onToggle}
           data-testid={`cut-desc-${cut.id}`}
@@ -317,61 +495,49 @@ function CutRow({
         >
           {cut.description || "No description"}
         </button>
-        {/* Lettering is a first-class, visible step (#442): an intentional
-            Manual vs AI-draft choice on the card, then the matching CTA. */}
-        {atLetteringStage && (
-          <div className="space-y-1" data-testid={`lettering-${cut.id}`}>
-            <div className="text-[10px] font-medium text-muted uppercase tracking-wider">Lettering</div>
-            <label className="flex items-center gap-1.5 text-[11px] text-foreground">
-              <input
-                type="radio" name={`lettering-mode-${cut.id}`} checked={letteringMode === "manual"}
-                onChange={() => setLetteringMode("manual")} data-testid={`lettering-mode-manual-${cut.id}`}
-              />
-              Manual — I place bubbles myself
-            </label>
-            <label className="flex items-center gap-1.5 text-[11px] text-foreground">
-              <input
-                type="radio" name={`lettering-mode-${cut.id}`} checked={letteringMode === "ai"}
-                onChange={() => setLetteringMode("ai")} data-testid={`lettering-mode-ai-${cut.id}`}
-              />
-              AI draft — ask the agent to place initial bubbles
-            </label>
-            {letteringMode === "ai" && (
-              <p className="text-[10px] text-muted">
-                Paste it to your agent, then review the draft bubbles here and export the final cut.
-              </p>
-            )}
-          </div>
-        )}
         <div className="flex items-center gap-2 flex-wrap">
           {atLetteringStage ? (
-            letteringMode === "manual" ? (
+            <>
               <button
                 onClick={onOpenEditor}
                 data-testid={`add-bubbles-${cut.id}`}
                 className="px-2.5 py-1 text-[11px] font-medium rounded bg-accent text-white hover:bg-accent-dim"
               >
-                {bubblesPlaced > 0 ? "Review lettering" : "Add speech bubbles"}
+                {bubblesPlaced > 0 ? "Review lettering" : "Open focused editor"}
               </button>
-            ) : (
-              <button
-                onClick={copyLetteringPrompt}
-                data-testid={`copy-lettering-${cut.id}`}
-                className="px-2.5 py-1 text-[11px] font-medium rounded border border-accent/40 text-accent hover:bg-accent/5"
-              >
-                {letteringCopied ? "Copied!" : "Copy AI lettering prompt"}
-              </button>
-            )
+              {canAiDraft && (
+                <button
+                  onClick={onAiDraft}
+                  disabled={aiDrafting}
+                  data-testid={`ai-draft-${cut.id}`}
+                  className="px-2.5 py-1 text-[11px] rounded border border-accent/40 text-accent hover:bg-accent/5 disabled:opacity-50"
+                >
+                  {aiDrafting ? "Drafting…" : aiDraftLabel}
+                </button>
+              )}
+            </>
           ) : primary ? (
             <button
               onClick={primary.onClick}
-              disabled={board.key === "convert" && (convertingThis || converting)}
+              disabled={
+                board.key === "convert" && (convertingThis || converting)
+              }
               data-testid={primary.testid}
               className="px-2.5 py-1 text-[11px] font-medium rounded bg-accent text-white hover:bg-accent-dim disabled:opacity-50"
             >
               {primary.label}
             </button>
           ) : null}
+          {!atLetteringStage && !primary && canAiDraft && (
+            <button
+              onClick={onAiDraft}
+              disabled={aiDrafting}
+              data-testid={`ai-draft-${cut.id}`}
+              className="px-2.5 py-1 text-[11px] rounded border border-accent/40 text-accent hover:bg-accent/5 disabled:opacity-50"
+            >
+              {aiDrafting ? "Drafting…" : aiDraftLabel}
+            </button>
+          )}
           <button
             onClick={onToggle}
             data-testid={`cut-details-${cut.id}`}
@@ -393,9 +559,13 @@ function CutRow({
               draft art). The raw unsupported-extension reason stays hidden in the
               Convert artwork banner's technical details. */}
           {needsConversion && (
-            <div className="mt-2 rounded border border-amber-500/40 bg-amber-500/10 p-2 space-y-1" data-testid={`needs-conversion-${cut.id}`}>
+            <div
+              className="mt-2 rounded border border-amber-500/40 bg-amber-500/10 p-2 space-y-1"
+              data-testid={`needs-conversion-${cut.id}`}
+            >
               <p className="text-[11px] text-amber-800">
-                This cut’s artwork is a PNG. Convert it to WebP so it can be lettered and published.
+                This cut’s artwork is a PNG. Convert it to WebP so it can be
+                lettered and published.
               </p>
               <button
                 onClick={handleConvertThis}
@@ -408,9 +578,14 @@ function CutRow({
             </div>
           )}
           {hasStale && !needsConversion && (
-            <div className="mt-2 rounded border border-error/40 bg-error/5 p-2 space-y-1" data-testid={`stale-asset-${cut.id}`}>
+            <div
+              className="mt-2 rounded border border-error/40 bg-error/5 p-2 space-y-1"
+              data-testid={`stale-asset-${cut.id}`}
+            >
               {staleMessages.map((m, i) => (
-                <p key={i} className="text-[11px] text-error">{m}</p>
+                <p key={i} className="text-[11px] text-error">
+                  {m}
+                </p>
               ))}
               <button
                 onClick={onRepairStale}
@@ -430,111 +605,137 @@ function CutRow({
               Text/interstitial panels need no clean image (#351), so this whole
               generation/upload handoff is image-cut only. */}
           {!isTextPanel(cut) && (
-          <div className="mt-2 space-y-2">
-            <button
-              onClick={() => {
-                navigator.clipboard.writeText(buildCodexTaskPrompt(cut as unknown as LibCut, plotFile));
-                setCopied(true);
-                setTimeout(() => setCopied(false), 2000);
-              }}
-              data-testid={`copy-prompt-${cut.id}`}
-              className="px-3 py-1.5 text-xs border border-border rounded hover:border-accent hover:bg-accent/5"
-            >
-              {copied ? "Copied!" : "Copy Codex task"}
-            </button>
-
-            <input
-              ref={fileInputRef}
-              type="file"
-              accept="image/webp,image/jpeg,image/png"
-              className="hidden"
-              onChange={(e) => {
-                const file = e.target.files?.[0];
-                if (file) handleUpload(file);
-                e.target.value = "";
-              }}
-            />
-            <div className="flex items-center gap-2 flex-wrap">
+            <div className="mt-2 space-y-2">
               <button
-                onClick={() => fileInputRef.current?.click()}
-                disabled={uploading}
-                className="px-3 py-1.5 text-xs border border-border rounded hover:border-accent hover:bg-accent/5 disabled:opacity-50"
-              >
-                {uploading ? "Uploading..." : cut.cleanImagePath ? "Replace clean image" : "Upload clean image"}
-              </button>
-              {/* #403: import a Codex-generated PNG straight from its cache, so a
-                  writer never has to hunt through ~/.codex/generated_images in an
-                  OS file dialog. Same in-browser PNG→WebP conversion + upload. */}
-              <button
-                onClick={() => setShowCodexPicker((v) => !v)}
-                disabled={uploading}
-                data-testid={`import-codex-${cut.id}`}
-                className="px-3 py-1.5 text-xs border border-border rounded hover:border-accent hover:bg-accent/5 disabled:opacity-50"
+                onClick={() => {
+                  navigator.clipboard.writeText(
+                    buildCodexTaskPrompt(cut as unknown as LibCut, plotFile),
+                  );
+                  setCopied(true);
+                  setTimeout(() => setCopied(false), 2000);
+                }}
+                data-testid={`copy-prompt-${cut.id}`}
+                className="px-3 py-1.5 text-xs border border-border rounded hover:border-accent hover:bg-accent/5"
               >
-                {showCodexPicker ? "Hide Codex images" : "Import from Codex"}
+                {copied ? "Copied!" : "Copy Codex task"}
               </button>
-            </div>
-            {showCodexPicker && (
-              <CodexImportPicker
-                authFetch={authFetch}
-                cutId={cut.id}
-                onImport={async (file) => {
-                  const ok = await handleUpload(file);
-                  if (ok) setShowCodexPicker(false);
+
+              <input
+                ref={fileInputRef}
+                type="file"
+                accept="image/webp,image/jpeg,image/png"
+                className="hidden"
+                onChange={(e) => {
+                  const file = e.target.files?.[0];
+                  if (file) handleUpload(file);
+                  e.target.value = "";
                 }}
-                onClose={() => setShowCodexPicker(false)}
               />
-            )}
-            {!cut.cleanImagePath && (
-              <p className="text-xs text-muted" data-testid={`clean-image-handoff-${cut.id}`}>
-                Generate this cut in Codex, then import the cached PNG with &ldquo;Import from Codex&rdquo; — or
-                upload an image manually. Letter it next.
-              </p>
-            )}
-            {status === "missing" && (
-              <div
-                className="rounded border border-border bg-surface/60 p-2 space-y-1"
-                data-testid={`ask-codex-${cut.id}`}
-              >
-                <p className="text-[11px] font-medium text-foreground">Generate this cut in Codex</p>
-                <p className="text-[10px] text-muted">
-                  Copy the task below and paste it into Codex. Codex usually saves a PNG to its
-                  image cache — bring it into this cut with &ldquo;Import from Codex&rdquo; above (the PNG
-                  becomes a WebP automatically). If Codex instead writes a WebP/JPEG at{" "}
-                  <span className="font-mono">assets/{plotFile}/cut-{String(cut.id).padStart(2, "0")}-clean.webp</span>,
-                  it&rsquo;s picked up by &ldquo;Sync clean images&rdquo;.
-                </p>
+              <div className="flex items-center gap-2 flex-wrap">
                 <button
-                  onClick={() => {
-                    navigator.clipboard.writeText(buildCodexTaskPrompt(cut as unknown as LibCut, plotFile));
-                    setAskCopied(true);
-                    setTimeout(() => setAskCopied(false), 2000);
-                  }}
-                  data-testid={`ask-codex-copy-${cut.id}`}
-                  className="px-2 py-1 text-[11px] border border-border rounded hover:border-accent hover:bg-accent/5"
+                  onClick={() => fileInputRef.current?.click()}
+                  disabled={uploading}
+                  className="px-3 py-1.5 text-xs border border-border rounded hover:border-accent hover:bg-accent/5 disabled:opacity-50"
+                >
+                  {uploading
+                    ? "Uploading..."
+                    : cut.cleanImagePath
+                      ? "Replace clean image"
+                      : "Upload clean image"}
+                </button>
+                {/* #403: import a Codex-generated PNG straight from its cache, so a
+                  writer never has to hunt through ~/.codex/generated_images in an
+                  OS file dialog. Same in-browser PNG→WebP conversion + upload. */}
+                <button
+                  onClick={() => setShowCodexPicker((v) => !v)}
+                  disabled={uploading}
+                  data-testid={`import-codex-${cut.id}`}
+                  className="px-3 py-1.5 text-xs border border-border rounded hover:border-accent hover:bg-accent/5 disabled:opacity-50"
                 >
-                  {askCopied ? "Copied!" : "Copy Codex task"}
+                  {showCodexPicker ? "Hide Codex images" : "Import from Codex"}
                 </button>
               </div>
-            )}
-            {status === "missing" && detectedLocalClean && (
-              <button
-                onClick={onSyncClean}
-                disabled={syncing}
-                data-testid={`found-local-clean-${cut.id}`}
-                className="px-3 py-1.5 text-xs border border-green-700/40 text-green-700 rounded hover:bg-green-700/5 disabled:opacity-50"
-              >
-                {syncing ? "Syncing..." : "Found local clean image — sync to cut plan"}
-              </button>
-            )}
-            {uploadError && (
-              <p className="text-xs text-error mt-1">{uploadError}</p>
-            )}
-          </div>
+              {showCodexPicker && (
+                <CodexImportPicker
+                  authFetch={authFetch}
+                  cutId={cut.id}
+                  onImport={async (file) => {
+                    const ok = await handleUpload(file);
+                    if (ok) setShowCodexPicker(false);
+                  }}
+                  onClose={() => setShowCodexPicker(false)}
+                />
+              )}
+              {!cut.cleanImagePath && (
+                <p
+                  className="text-xs text-muted"
+                  data-testid={`clean-image-handoff-${cut.id}`}
+                >
+                  Generate this cut in Codex, then import the cached PNG with
+                  &ldquo;Import from Codex&rdquo; — or upload an image manually.
+                  Letter it next.
+                </p>
+              )}
+              {status === "missing" && (
+                <div
+                  className="rounded border border-border bg-surface/60 p-2 space-y-1"
+                  data-testid={`ask-codex-${cut.id}`}
+                >
+                  <p className="text-[11px] font-medium text-foreground">
+                    Generate this cut in Codex
+                  </p>
+                  <p className="text-[10px] text-muted">
+                    Copy the task below and paste it into Codex. Codex usually
+                    saves a PNG to its image cache — bring it into this cut with
+                    &ldquo;Import from Codex&rdquo; above (the PNG becomes a
+                    WebP automatically). If Codex instead writes a WebP/JPEG at{" "}
+                    <span className="font-mono">
+                      assets/{plotFile}/cut-{String(cut.id).padStart(2, "0")}
+                      -clean.webp
+                    </span>
+                    , it&rsquo;s picked up by &ldquo;Sync clean images&rdquo;.
+                  </p>
+                  <button
+                    onClick={() => {
+                      navigator.clipboard.writeText(
+                        buildCodexTaskPrompt(
+                          cut as unknown as LibCut,
+                          plotFile,
+                        ),
+                      );
+                      setAskCopied(true);
+                      setTimeout(() => setAskCopied(false), 2000);
+                    }}
+                    data-testid={`ask-codex-copy-${cut.id}`}
+                    className="px-2 py-1 text-[11px] border border-border rounded hover:border-accent hover:bg-accent/5"
+                  >
+                    {askCopied ? "Copied!" : "Copy Codex task"}
+                  </button>
+                </div>
+              )}
+              {status === "missing" && detectedLocalClean && (
+                <button
+                  onClick={onSyncClean}
+                  disabled={syncing}
+                  data-testid={`found-local-clean-${cut.id}`}
+                  className="px-3 py-1.5 text-xs border border-green-700/40 text-green-700 rounded hover:bg-green-700/5 disabled:opacity-50"
+                >
+                  {syncing
+                    ? "Syncing..."
+                    : "Found local clean image — sync to cut plan"}
+                </button>
+              )}
+              {uploadError && (
+                <p className="text-xs text-error mt-1">{uploadError}</p>
+              )}
+            </div>
           )}
 
           {/* Open editor — image cuts, narration cuts, and text panels (#351) */}
-          {(cut.cleanImagePath || cut.narration || cut.dialogue.length > 0 || isTextPanel(cut)) && (
+          {(cut.cleanImagePath ||
+            cut.narration ||
+            cut.dialogue.length > 0 ||
+            isTextPanel(cut)) && (
             <button
               onClick={onOpenEditor}
               data-testid={`open-editor-${cut.id}`}
@@ -546,12 +747,16 @@ function CutRow({
 
           {/* Cut metadata */}
           {cut.characters.length > 0 && (
-            <p className="text-xs text-muted">Characters: {cut.characters.join(", ")}</p>
+            <p className="text-xs text-muted">
+              Characters: {cut.characters.join(", ")}
+            </p>
           )}
           {cut.dialogue.length > 0 && (
             <div className="text-xs text-muted">
               {cut.dialogue.map((d, i) => (
-                <p key={i}><span className="font-medium">{d.speaker}:</span> {d.text}</p>
+                <p key={i}>
+                  <span className="font-medium">{d.speaker}:</span> {d.text}
+                </p>
               ))}
             </div>
           )}
@@ -564,7 +769,19 @@ function CutRow({
   );
 }
 
-export function CutListPanel({ storyName, fileName, authFetch, language, uploadRetry, onCutsChanged, focusRequest, onFocusHandled }: CutListPanelProps) {
+export function CutListPanel({
+  storyName,
+  fileName,
+  authFetch,
+  language,
+  uploadRetry,
+  onCutsChanged,
+  focusRequest,
+  onFocusHandled,
+  onFocusedLetteringModeChange,
+  workspaceVisible = false,
+  onWorkspaceVisibleChange,
+}: CutListPanelProps) {
   const [cutsFile, setCutsFile] = useState<CutsFile | null>(null);
   // Latest onCutsChanged in a ref so loadCuts can notify the parent without
   // taking the callback as a dependency (which would churn loadCuts/effects).
@@ -583,7 +800,10 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
   // Episode publish markdown + on-chain state, for the guided Finish panel (#414):
   // distinguishes uploaded-but-not-prepared from a prepared/ready-to-publish or
   // already-published episode (which cuts.json alone cannot tell apart).
-  const [episodeState, setEpisodeState] = useState<{ markdownReady: boolean; published: boolean }>({
+  const [episodeState, setEpisodeState] = useState<{
+    markdownReady: boolean;
+    published: boolean;
+  }>({
     markdownReady: false,
     published: false,
   });
@@ -592,9 +812,13 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
   const [converting, setConverting] = useState(false);
   const [convertResult, setConvertResult] = useState<string | null>(null);
   const [syncResult, setSyncResult] = useState<string | null>(null);
+  const [aiDraftingCutId, setAiDraftingCutId] = useState<number | null>(null);
+  const [aiDraftingAll, setAiDraftingAll] = useState(false);
   const [detected, setDetected] = useState<Set<number>>(new Set());
   // cutId → precise stale-path messages (#302), from detect-clean-images.
-  const [staleByCut, setStaleByCut] = useState<Map<number, string[]>>(new Map());
+  const [staleByCut, setStaleByCut] = useState<Map<number, string[]>>(
+    new Map(),
+  );
   // True only after /detect-clean-images has SUCCESSFULLY verified the recorded
   // paths against disk (#311). Gates the "clean-assets-ready" banner so it never
   // claims completion from unverified cut-plan fields while detection is pending
@@ -602,11 +826,15 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
   const [detectConfirmed, setDetectConfirmed] = useState(false);
   // Read-only per-cut asset diagnostics validated against disk (#427): the real
   // state (planned/missing/clean-ready/final-ready/uploaded) + precise issues.
-  const [assetDiagnostics, setAssetDiagnostics] = useState<CutAssetDiagnostic[] | null>(null);
+  const [assetDiagnostics, setAssetDiagnostics] = useState<
+    CutAssetDiagnostic[] | null
+  >(null);
   const [rescanning, setRescanning] = useState(false);
   // #371: cut whose row should be scrolled into view after a Preview→Edit deep
   // link. Applied once its row has rendered (see the scroll effect below).
-  const [scrollTargetCutId, setScrollTargetCutId] = useState<number | null>(null);
+  const [scrollTargetCutId, setScrollTargetCutId] = useState<number | null>(
+    null,
+  );
   // Live DOM refs for cut rows, keyed by cut id, used to scroll a focused cut
   // into view. A ref map avoids re-rendering on registration.
   const rowRefs = useRef<Map<number, HTMLDivElement>>(new Map());
@@ -632,6 +860,11 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
     onFocusHandledRef.current?.();
   }, [focusRequest]);
 
+  useEffect(() => {
+    onFocusedLetteringModeChange?.(editingCutId !== null);
+    return () => onFocusedLetteringModeChange?.(false);
+  }, [editingCutId, onFocusedLetteringModeChange]);
+
   // Scroll a deep-linked, expanded cut into view once its row is on screen. Runs
   // when the target is set and again after the cut plan loads (rows mount). Best
   // effort: `scrollIntoView` is a no-op/undefined under jsdom.
@@ -663,13 +896,19 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
       // distinctly, not just upload progress (#414). Best-effort — a missing file
       // or error simply leaves those steps as not-yet-prepared.
       try {
-        const fileRes = await authFetch(`/api/stories/${storyName}/${fileName}`);
+        const fileRes = await authFetch(
+          `/api/stories/${storyName}/${fileName}`,
+        );
         if (fileRes.ok) {
           const fd = await fileRes.json();
-          const content: string = typeof fd?.content === "string" ? fd.content : "";
+          const content: string =
+            typeof fd?.content === "string" ? fd.content : "";
           const cuts = Array.isArray(parsed?.cuts) ? parsed.cuts : [];
-          const markdownReady = content.length > 0 && checkMarkdownReadiness(content, cuts).ready;
-          const published = fd?.status === "published" || fd?.status === "published-not-indexed";
+          const markdownReady =
+            content.length > 0 && checkMarkdownReadiness(content, cuts).ready;
+          const published =
+            fd?.status === "published" ||
+            fd?.status === "published-not-indexed";
           setEpisodeState({ markdownReady, published });
         } else {
           setEpisodeState({ markdownReady: false, published: false });
@@ -687,6 +926,22 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
     }
   }, [authFetch, storyName, plotFile, fileName]);
 
+  const saveCutsFile = useCallback(
+    async (updated: CutsFile): Promise<boolean> => {
+      const res = await authFetch(
+        `/api/stories/${storyName}/cuts/${plotFile}`,
+        {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(updated),
+        },
+      );
+      if (!res.ok) return false;
+      return true;
+    },
+    [authFetch, storyName, plotFile],
+  );
+
   // Server-confirmed detection of local clean files for cuts whose cleanImagePath
   // is still null. Best-effort: failures leave the detected set unchanged.
   const loadDetect = useCallback(async () => {
@@ -694,15 +949,20 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
     // unverified — don't let the done banner claim completion (#311).
     setDetectConfirmed(false);
     try {
-      const res = await authFetch(`/api/stories/${storyName}/cuts/${plotFile}/detect-clean-images`);
+      const res = await authFetch(
+        `/api/stories/${storyName}/cuts/${plotFile}/detect-clean-images`,
+      );
       if (!res.ok) return;
       const data = await res.json();
-      setDetected(new Set<number>(Array.isArray(data.detected) ? data.detected : []));
+      setDetected(
+        new Set<number>(Array.isArray(data.detected) ? data.detected : []),
+      );
       const staleMap = new Map<number, string[]>();
       const staleList: unknown = data.stale;
       if (Array.isArray(staleList)) {
         for (const s of staleList) {
-          if (typeof s?.cutId !== "number" || typeof s?.message !== "string") continue;
+          if (typeof s?.cutId !== "number" || typeof s?.message !== "string")
+            continue;
           const arr = staleMap.get(s.cutId) ?? [];
           arr.push(s.message);
           staleMap.set(s.cutId, arr);
@@ -722,11 +982,17 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
   const loadDiagnostics = useCallback(async () => {
     setAssetDiagnostics(null);
     try {
-      const res = await authFetch(`/api/stories/${storyName}/cuts/${plotFile}/asset-diagnostics`);
+      const res = await authFetch(
+        `/api/stories/${storyName}/cuts/${plotFile}/asset-diagnostics`,
+      );
       if (!res.ok) return; // stays cleared
       const data = await res.json();
-      setAssetDiagnostics(Array.isArray(data.diagnostics) ? data.diagnostics : null);
-    } catch { /* stays cleared — diagnostics are optional */ }
+      setAssetDiagnostics(
+        Array.isArray(data.diagnostics) ? data.diagnostics : null,
+      );
+    } catch {
+      /* stays cleared — diagnostics are optional */
+    }
   }, [authFetch, storyName, plotFile]);
 
   // "Refresh assets / Check generated images" (#427): a read-only rescan that
@@ -742,26 +1008,125 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
     }
   }, [loadCuts, loadDetect, loadDiagnostics]);
 
+  const draftCutWithAi = useCallback(
+    async (cutId: number, opts: { openEditor?: boolean } = {}) => {
+      if (!cutsFile) return false;
+      const cut = cutsFile.cuts.find((c) => c.id === cutId);
+      if (!cut || !canDraftLettering(cut)) return false;
+      if ((cut.overlays?.length ?? 0) > 0) {
+        const ok = window.confirm(
+          "This cut already has overlays. Re-drafting with AI will replace the current draft overlays for this cut. Continue?",
+        );
+        if (!ok) return false;
+      }
+      const overlays = buildDraftOverlays(cut);
+      if (overlays.length === 0) {
+        setSyncResult(`Cut ${cut.id}: no script lines available to draft.`);
+        return false;
+      }
+      setAiDraftingCutId(cutId);
+      setSyncResult(null);
+      try {
+        const updated: CutsFile = {
+          ...cutsFile,
+          cuts: cutsFile.cuts.map((c) =>
+            c.id === cutId
+              ? { ...c, overlays, aiDraft: buildAiDraftState(overlays) }
+              : c,
+          ),
+        };
+        const ok = await saveCutsFile(updated);
+        if (!ok) {
+          setSyncResult(`Cut ${cut.id}: AI draft failed`);
+          return false;
+        }
+        setSyncResult(`Cut ${cut.id}: AI draft ready`);
+        await loadCuts();
+        if (opts.openEditor) setEditingCutId(cutId);
+        return true;
+      } finally {
+        setAiDraftingCutId(null);
+      }
+    },
+    [cutsFile, saveCutsFile, loadCuts],
+  );
+
+  const draftAllUnletteredCuts = useCallback(async () => {
+    if (!cutsFile) return;
+    const eligible = cutsFile.cuts.filter(
+      (cut) =>
+        canDraftLettering(cut) &&
+        (cut.overlays?.length ?? 0) === 0 &&
+        !cut.finalImagePath &&
+        !cut.uploadedCid &&
+        !cut.uploadedUrl,
+    );
+    if (eligible.length === 0) {
+      setSyncResult("No unlettered cuts need an AI draft");
+      return;
+    }
+    setAiDraftingAll(true);
+    setSyncResult(null);
+    try {
+      const updated: CutsFile = {
+        ...cutsFile,
+        cuts: cutsFile.cuts.map((cut) => {
+          if (!eligible.some((e) => e.id === cut.id)) return cut;
+          const overlays = buildDraftOverlays(cut);
+          return overlays.length > 0
+            ? { ...cut, overlays, aiDraft: buildAiDraftState(overlays) }
+            : cut;
+        }),
+      };
+      const ok = await saveCutsFile(updated);
+      if (!ok) {
+        setSyncResult("AI draft failed");
+        return;
+      }
+      setSyncResult(
+        `AI draft ready for ${eligible.length} cut${eligible.length === 1 ? "" : "s"}`,
+      );
+      await loadCuts();
+    } finally {
+      setAiDraftingAll(false);
+    }
+  }, [cutsFile, saveCutsFile, loadCuts]);
+
   const syncCleanImages = useCallback(async () => {
     setSyncing(true);
     setSyncResult(null);
     setGenWarnings([]);
     try {
-      const res = await authFetch(`/api/stories/${storyName}/cuts/${plotFile}/sync-clean-images`, { method: "POST" });
+      const res = await authFetch(
+        `/api/stories/${storyName}/cuts/${plotFile}/sync-clean-images`,
+        { method: "POST" },
+      );
       const data = await res.json().catch(() => ({}));
       if (!res.ok) {
         setSyncResult(data.error || "Sync failed");
       } else {
         const syncedCount = Array.isArray(data.synced) ? data.synced.length : 0;
-        const clearedCount = Array.isArray(data.cleared) ? data.cleared.length : 0;
+        const clearedCount = Array.isArray(data.cleared)
+          ? data.cleared.length
+          : 0;
         const rejected = Array.isArray(data.rejected) ? data.rejected : [];
         if (rejected.length > 0) {
-          setGenWarnings(rejected.map((r: { cutId: number; reason: string }) => `Cut ${r.cutId}: ${r.reason}`));
+          setGenWarnings(
+            rejected.map(
+              (r: { cutId: number; reason: string }) =>
+                `Cut ${r.cutId}: ${r.reason}`,
+            ),
+          );
         }
         const parts: string[] = [];
         if (syncedCount > 0) parts.push(`Synced ${syncedCount}`);
-        if (clearedCount > 0) parts.push(`Cleared ${clearedCount} stale path${clearedCount === 1 ? "" : "s"}`);
-        setSyncResult(parts.length > 0 ? parts.join(", ") : "No new clean images");
+        if (clearedCount > 0)
+          parts.push(
+            `Cleared ${clearedCount} stale path${clearedCount === 1 ? "" : "s"}`,
+          );
+        setSyncResult(
+          parts.length > 0 ? parts.join(", ") : "No new clean images",
+        );
         await loadCuts();
         await loadDetect();
         await loadDiagnostics();
@@ -777,42 +1142,57 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
   // upload), and persist via the existing upload-clean route, which records the
   // new cleanImagePath. Returns true on success. Publish stays strict — the route
   // only accepts WebP/JPEG ≤1MB, so conversion is the safe bridge from a draft PNG.
-  const convertCut = useCallback(async (cutId: number, pngPath: string): Promise<boolean> => {
-    try {
-      const res = await authFetch(assetUrl(storyName, pngPath));
-      if (!res.ok) return false;
-      const blob = await res.blob();
-      const compliant = await importImageToCompliantBlob(new File([blob], "clean.png", { type: blob.type || "image/png" }));
-      const ext = compliant.type === "image/jpeg" ? "jpg" : "webp";
-      const formData = new FormData();
-      formData.append("file", new File([compliant], `clean.${ext}`, { type: compliant.type }));
-      const up = await authFetch(`/api/stories/${storyName}/cuts/${plotFile}/upload-clean/${cutId}`, { method: "POST", body: formData });
-      return up.ok;
-    } catch {
-      return false;
-    }
-  }, [authFetch, storyName, plotFile]);
+  const convertCut = useCallback(
+    async (cutId: number, pngPath: string): Promise<boolean> => {
+      try {
+        const res = await authFetch(assetUrl(storyName, pngPath));
+        if (!res.ok) return false;
+        const blob = await res.blob();
+        const compliant = await importImageToCompliantBlob(
+          new File([blob], "clean.png", { type: blob.type || "image/png" }),
+        );
+        const ext = compliant.type === "image/jpeg" ? "jpg" : "webp";
+        const formData = new FormData();
+        formData.append(
+          "file",
+          new File([compliant], `clean.${ext}`, { type: compliant.type }),
+        );
+        const up = await authFetch(
+          `/api/stories/${storyName}/cuts/${plotFile}/upload-clean/${cutId}`,
+          { method: "POST", body: formData },
+        );
+        return up.ok;
+      } catch {
+        return false;
+      }
+    },
+    [authFetch, storyName, plotFile],
+  );
 
   // "Convert all artwork" (#441): batch-convert every cut flagged needs-conversion.
-  const convertAll = useCallback(async (jobs: { cutId: number; pngPath: string }[]) => {
-    setConverting(true);
-    setConvertResult(null);
-    let done = 0;
-    const failed: number[] = [];
-    for (const job of jobs) {
-      // Sequential on purpose: avoid hammering browser canvas conversion + the
-      // upload-clean write all at once for a 10-cut episode.
-      const ok = await convertCut(job.cutId, job.pngPath);
-      if (ok) done++; else failed.push(job.cutId);
-    }
-    await refreshAssets();
-    setConverting(false);
-    setConvertResult(
-      failed.length === 0
-        ? `Converted ${done} image${done === 1 ? "" : "s"} to WebP`
-        : `Converted ${done}; ${failed.length} failed (Cut ${failed.join(", ")}) — try Convert image on each`,
-    );
-  }, [convertCut, refreshAssets]);
+  const convertAll = useCallback(
+    async (jobs: { cutId: number; pngPath: string }[]) => {
+      setConverting(true);
+      setConvertResult(null);
+      let done = 0;
+      const failed: number[] = [];
+      for (const job of jobs) {
+        // Sequential on purpose: avoid hammering browser canvas conversion + the
+        // upload-clean write all at once for a 10-cut episode.
+        const ok = await convertCut(job.cutId, job.pngPath);
+        if (ok) done++;
+        else failed.push(job.cutId);
+      }
+      await refreshAssets();
+      setConverting(false);
+      setConvertResult(
+        failed.length === 0
+          ? `Converted ${done} image${done === 1 ? "" : "s"} to WebP`
+          : `Converted ${done}; ${failed.length} failed (Cut ${failed.join(", ")}) — try Convert image on each`,
+      );
+    },
+    [convertCut, refreshAssets],
+  );
 
   // Guided "Finish episode" orchestration (#414): upload every exported final
   // image (paced under the rate limit, #413/#288), then prepare the publish
@@ -824,7 +1204,9 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
     setUploading(true);
     setUploadProgress("");
     setGenWarnings([]);
-    const toUpload = cutsFile.cuts.filter((ct) => ct.finalImagePath && !ct.uploadedCid);
+    const toUpload = cutsFile.cuts.filter(
+      (ct) => ct.finalImagePath && !ct.uploadedCid,
+    );
     const errors: string[] = [];
     // Proactively pace uploads under PlotLink's 5/min limit so a 7–10 cut episode
     // completes without manual waiting, instead of firing all at once and thrashing
@@ -839,14 +1221,27 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
     });
     for (let i = 0; i < toUpload.length; i++) {
       const ct = toUpload[i];
-      setUploadProgress(`Uploading cut ${ct.id} (${i + 1}/${toUpload.length})...`);
+      setUploadProgress(
+        `Uploading cut ${ct.id} (${i + 1}/${toUpload.length})...`,
+      );
       try {
-        const assetRel = ct.finalImagePath!.startsWith("assets/") ? ct.finalImagePath!.slice(7) : ct.finalImagePath!;
-        const imgRes = await authFetch(`/api/stories/${storyName}/asset/${assetRel}`);
-        if (!imgRes.ok) { errors.push(`Cut ${ct.id}: failed to fetch asset`); continue; }
+        const assetRel = ct.finalImagePath!.startsWith("assets/")
+          ? ct.finalImagePath!.slice(7)
+          : ct.finalImagePath!;
+        const imgRes = await authFetch(
+          `/api/stories/${storyName}/asset/${assetRel}`,
+        );
+        if (!imgRes.ok) {
+          errors.push(`Cut ${ct.id}: failed to fetch asset`);
+          continue;
+        }
         const blob = await imgRes.blob();
         const fd = new FormData();
-        fd.append("file", blob, `cut-${ct.id}.${blob.type === "image/webp" ? "webp" : "jpg"}`);
+        fd.append(
+          "file",
+          blob,
+          `cut-${ct.id}.${blob.type === "image/webp" ? "webp" : "jpg"}`,
+        );
         // Proactively wait if we've already used the 5/min budget (#413), then retry
         // with backoff while the PlotLink endpoint rate-limits us anyway (5
         // uploads/min), instead of failing the whole batch (#288). Already-uploaded
@@ -855,13 +1250,20 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
         await throttle();
         const upload = await withRateLimitRetry(
           async () => {
-            const res = await authFetch("/api/publish/upload-plot-image", { method: "POST", body: fd });
+            const res = await authFetch("/api/publish/upload-plot-image", {
+              method: "POST",
+              body: fd,
+            });
             if (res.ok) {
               const { cid, url } = await res.json();
               return { ok: true as const, status: res.status, cid, url };
             }
             const e = await res.json().catch(() => ({}));
-            return { ok: false as const, status: res.status, errorMessage: (e as { error?: string }).error };
+            return {
+              ok: false as const,
+              status: res.status,
+              errorMessage: (e as { error?: string }).error,
+            };
           },
           {
             ...uploadRetry,
@@ -871,16 +1273,28 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
               ),
           },
         );
-        if (!upload.ok) { errors.push(`Cut ${ct.id}: upload failed — ${upload.errorMessage || "unknown"}`); continue; }
+        if (!upload.ok) {
+          errors.push(
+            `Cut ${ct.id}: upload failed — ${upload.errorMessage || "unknown"}`,
+          );
+          continue;
+        }
         const { cid, url } = upload;
-        const setRes = await authFetch(`/api/stories/${storyName}/cuts/${plotFile}/set-uploaded/${ct.id}`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ cid, url }),
-        });
-        if (!setRes.ok) { errors.push(`Cut ${ct.id}: failed to record upload`); }
+        const setRes = await authFetch(
+          `/api/stories/${storyName}/cuts/${plotFile}/set-uploaded/${ct.id}`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ cid, url }),
+          },
+        );
+        if (!setRes.ok) {
+          errors.push(`Cut ${ct.id}: failed to record upload`);
+        }
       } catch (err) {
-        errors.push(`Cut ${ct.id}: ${err instanceof Error ? err.message : "failed"}`);
+        errors.push(
+          `Cut ${ct.id}: ${err instanceof Error ? err.message : "failed"}`,
+        );
       }
     }
     if (errors.length > 0) {
@@ -891,7 +1305,10 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
       return;
     }
     setUploadProgress("Preparing episode for publishing…");
-    const mdRes = await authFetch(`/api/stories/${storyName}/cuts/${plotFile}/generate-markdown`, { method: "POST" });
+    const mdRes = await authFetch(
+      `/api/stories/${storyName}/cuts/${plotFile}/generate-markdown`,
+      { method: "POST" },
+    );
     if (mdRes.ok) {
       const data = await mdRes.json();
       if (data.warnings?.length > 0) setGenWarnings(data.warnings);
@@ -908,13 +1325,22 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
     setRepairing(true);
     setSyncResult(null);
     try {
-      const res = await authFetch(`/api/stories/${storyName}/cuts/${plotFile}/repair-asset-paths`, { method: "POST" });
+      const res = await authFetch(
+        `/api/stories/${storyName}/cuts/${plotFile}/repair-asset-paths`,
+        { method: "POST" },
+      );
       const data = await res.json().catch(() => ({}));
       if (!res.ok) {
         setSyncResult(data.error || "Repair failed");
       } else {
-        const clearedCount = Array.isArray(data.cleared) ? data.cleared.length : 0;
-        setSyncResult(clearedCount > 0 ? `Cleared ${clearedCount} stale path${clearedCount === 1 ? "" : "s"}` : "No stale paths to clear");
+        const clearedCount = Array.isArray(data.cleared)
+          ? data.cleared.length
+          : 0;
+        setSyncResult(
+          clearedCount > 0
+            ? `Cleared ${clearedCount} stale path${clearedCount === 1 ? "" : "s"}`
+            : "No stale paths to clear",
+        );
         await loadCuts();
         await loadDetect();
       }
@@ -924,39 +1350,67 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
     setRepairing(false);
   }, [authFetch, storyName, plotFile, loadCuts, loadDetect]);
 
-  // Append a text/interstitial panel to the cut plan (#352) — a one-click way to
-  // add a narration/title card between image cuts without hand-editing cuts.json.
+  // Insert a text/interstitial panel to the cut plan (#352/#488) — a one-click way
+  // to add a narration/title card between image cuts without hand-editing cuts.json.
   const [addingPanel, setAddingPanel] = useState(false);
-  const addTextPanel = useCallback(async () => {
-    if (!cutsFile) return;
-    setAddingPanel(true);
-    try {
-      const nextId = cutsFile.cuts.reduce((m, c) => Math.max(m, c.id), 0) + 1;
-      const panel = {
-        id: nextId, shotType: "wide", description: "Text panel", characters: [],
-        dialogue: [], narration: "", sfx: "",
-        cleanImagePath: null, finalImagePath: null, exportedAt: null,
-        uploadedCid: null, uploadedUrl: null, overlays: [],
-        kind: "text" as const, background: "#101820", aspectRatio: "4:5",
-      };
-      const updated = { ...cutsFile, cuts: [...cutsFile.cuts, panel] };
-      const res = await authFetch(`/api/stories/${storyName}/cuts/${plotFile}`, {
-        method: "PUT",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(updated),
-      });
-      if (res.ok) {
-        setExpandedCut(nextId);
-        await loadCuts();
-      } else {
-        const data = await res.json().catch(() => ({}));
-        setSyncResult(data.error || "Could not add text panel");
+  const addTextPanelAt = useCallback(
+    async (insertIndex: number, openEditor = true) => {
+      if (!cutsFile) return;
+      setAddingPanel(true);
+      try {
+        const nextId = cutsFile.cuts.reduce((m, c) => Math.max(m, c.id), 0) + 1;
+        const panel = {
+          id: nextId,
+          shotType: "wide",
+          description: "Text panel",
+          characters: [],
+          dialogue: [],
+          narration: "",
+          sfx: "",
+          cleanImagePath: null,
+          finalImagePath: null,
+          exportedAt: null,
+          uploadedCid: null,
+          uploadedUrl: null,
+          overlays: [],
+          kind: "text" as const,
+          background: "#101820",
+          aspectRatio: "4:5",
+        };
+        const nextCuts = [...cutsFile.cuts];
+        nextCuts.splice(
+          Math.max(0, Math.min(insertIndex, nextCuts.length)),
+          0,
+          panel,
+        );
+        const updated = { ...cutsFile, cuts: nextCuts };
+        const res = await authFetch(
+          `/api/stories/${storyName}/cuts/${plotFile}`,
+          {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(updated),
+          },
+        );
+        if (res.ok) {
+          if (openEditor) setEditingCutId(nextId);
+          else setExpandedCut(nextId);
+          await loadCuts();
+        } else {
+          const data = await res.json().catch(() => ({}));
+          setSyncResult(data.error || "Could not add text panel");
+        }
+      } catch {
+        setSyncResult("Could not add text panel");
       }
-    } catch {
-      setSyncResult("Could not add text panel");
-    }
-    setAddingPanel(false);
-  }, [cutsFile, authFetch, storyName, plotFile, loadCuts]);
+      setAddingPanel(false);
+    },
+    [cutsFile, authFetch, storyName, plotFile, loadCuts],
+  );
+  const addTextPanel = useCallback(
+    () => addTextPanelAt(cutsFile?.cuts.length ?? 0, true),
+    [addTextPanelAt, cutsFile],
+  );
 
   useEffect(() => {
     loadCuts();
@@ -974,9 +1428,16 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
         <p className="text-sm text-error font-medium">Invalid cuts file</p>
         <p className="text-xs text-error">{error}</p>
         <p className="text-xs text-muted">
-          {plotFile}.cuts.json must follow the OWS v1 schema. Ask Claude to regenerate it using the v1 cuts schema from the cartoon writing instructions.
+          {plotFile}.cuts.json must follow the OWS v1 schema. Ask Claude to
+          regenerate it using the v1 cuts schema from the cartoon writing
+          instructions.
         </p>
-        <button onClick={loadCuts} className="text-xs text-accent hover:text-accent-dim">Retry</button>
+        <button
+          onClick={loadCuts}
+          className="text-xs text-accent hover:text-accent-dim"
+        >
+          Retry
+        </button>
       </div>
     );
   }
@@ -985,12 +1446,17 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
     return (
       <div className="p-4 text-center space-y-1">
         <p className="text-sm text-muted">No cuts yet</p>
-        <p className="text-xs text-muted">Ask Claude to create a cut plan for this episode.</p>
+        <p className="text-xs text-muted">
+          Ask Claude to create a cut plan for this episode.
+        </p>
       </div>
     );
   }
 
-  const editingCut = editingCutId !== null ? cutsFile.cuts.find((c) => c.id === editingCutId) : null;
+  const editingCut =
+    editingCutId !== null
+      ? cutsFile.cuts.find((c) => c.id === editingCutId)
+      : null;
 
   if (editingCut) {
     return (
@@ -1000,20 +1466,37 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
         plotFile={plotFile}
         language={language}
         authFetch={authFetch}
-        onSave={async (overlays: Overlay[]) => {
-          const updated = { ...cutsFile, cuts: cutsFile.cuts.map((c) => c.id === editingCutId ? { ...c, overlays } : c) };
-          const res = await authFetch(`/api/stories/${storyName}/cuts/${plotFile}`, {
-            method: "PUT",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(updated),
-          });
-          if (!res.ok) {
-            const data = await res.json().catch(() => ({}));
-            throw new Error(data.error || "Failed to save overlays");
+        targetLabel={
+          isTextPanel(editingCut)
+            ? `Between-scene card ${editingCut.id}`
+            : `Cut ${String(editingCut.id).padStart(2, "0")}`
+        }
+        returnOnSave
+        workspaceVisible={workspaceVisible}
+        onToggleWorkspaceVisible={
+          onWorkspaceVisibleChange
+            ? () => onWorkspaceVisibleChange(!workspaceVisible)
+            : undefined
+        }
+        onSave={async (overlays: Overlay[], aiDraft?: CutAiDraft | null) => {
+          const updated = {
+            ...cutsFile,
+            cuts: cutsFile.cuts.map((c) =>
+              c.id === editingCutId
+                ? { ...c, overlays, aiDraft: aiDraft ?? c.aiDraft ?? null }
+                : c,
+            ),
+          };
+          const ok = await saveCutsFile(updated);
+          if (!ok) {
+            throw new Error("Failed to save overlays");
           }
         }}
         onExported={() => loadCuts()}
-        onClose={() => { setEditingCutId(null); loadCuts(); }}
+        onClose={() => {
+          setEditingCutId(null);
+          loadCuts();
+        }}
       />
     );
   }
@@ -1024,21 +1507,30 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
       acc[s]++;
       return acc;
     },
-    { missing: 0, clean: 0, lettered: 0, uploaded: 0, text: 0 } as Record<CutStatus, number>,
+    { missing: 0, clean: 0, lettered: 0, uploaded: 0, text: 0 } as Record<
+      CutStatus,
+      number
+    >,
   );
   // Text/interstitial panels need no clean image (#351), so the clean-assets
   // banner/claims reason about IMAGE cuts only — never the total cut count.
   const imageCutCount = cutsFile.cuts.filter((c) => !isTextPanel(c)).length;
   // #381: final images lettered by an older bubble renderer (separate-tail seam)
   // must be re-exported before publish. Only tailed speech bubbles are affected.
-  const staleTailIds = cutsFile.cuts.filter((c) => isStaleTailedExport(c)).map((c) => c.id);
+  const staleTailIds = cutsFile.cuts
+    .filter((c) => isStaleTailedExport(c))
+    .map((c) => c.id);
 
   // Guided "Finish episode" state (#414). The checklist's publish step reflects the
   // real on-chain status; markdownReady distinguishes uploaded-but-not-prepared from
   // a prepared/ready-to-publish episode. canFinish = something the Finish action can
   // still do: a final to upload, or uploads done but the sequence not yet prepared.
-  const finishChecklist = cartoonChecklist({ cuts: cutsFile.cuts, published: episodeState.published });
-  const uploadStepDone = finishChecklist.steps.find((s) => s.key === "upload")?.status === "done";
+  const finishChecklist = cartoonChecklist({
+    cuts: cutsFile.cuts,
+    published: episodeState.published,
+  });
+  const uploadStepDone =
+    finishChecklist.steps.find((s) => s.key === "upload")?.status === "done";
   const canFinish =
     cutsFile.cuts.some((ct) => ct.finalImagePath && !ct.uploadedCid) ||
     (uploadStepDone && !episodeState.markdownReady);
@@ -1048,7 +1540,9 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
   const conversionJobs = (assetDiagnostics ?? [])
     .filter((d) => d.state === "needs-conversion" && d.convertiblePng)
     .map((d) => ({ cutId: d.cutId, pngPath: d.convertiblePng as string }));
-  const conversionByCut = new Map(conversionJobs.map((j) => [j.cutId, j.pngPath]));
+  const conversionByCut = new Map(
+    conversionJobs.map((j) => [j.cutId, j.pngPath]),
+  );
   const conversionIssues = (assetDiagnostics ?? [])
     .filter((d) => d.state === "needs-conversion" && d.issue)
     .map((d) => d.issue as string);
@@ -1057,119 +1551,211 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
   // milestones, not internal fields: artwork found (any clean image incl. a draft
   // PNG), converted (publishable WebP/JPEG), lettered (bubbles placed/exported),
   // uploaded. PNG-only cuts read as "artwork found" but not yet "converted".
-  const episodeLabel = fileName === "genesis.md"
-    ? "Genesis / Episode 1"
-    : `Episode ${parseInt(plotFile.match(/\d+/)?.[0] ?? "0", 10) + 1}`;
-  const episodeTitle = typeof (cutsFile as { title?: unknown }).title === "string" ? (cutsFile as { title?: string }).title : null;
+  const episodeLabel =
+    fileName === "genesis.md"
+      ? "Genesis / Episode 1"
+      : `Episode ${parseInt(plotFile.match(/\d+/)?.[0] ?? "0", 10) + 1}`;
+  const episodeTitle =
+    typeof (cutsFile as { title?: unknown }).title === "string"
+      ? (cutsFile as { title?: string }).title
+      : null;
   const imageCuts = cutsFile.cuts.filter((c) => !isTextPanel(c));
   const boardSummary = {
     cuts: cutsFile.cuts.length,
-    artwork: imageCuts.filter((c) => c.cleanImagePath || conversionByCut.has(c.id)).length,
-    converted: imageCuts.filter((c) => c.cleanImagePath && /\.(webp|jpe?g)$/i.test(c.cleanImagePath)).length,
-    lettered: cutsFile.cuts.filter((c) => (c.overlays?.length ?? 0) > 0 || !!c.finalImagePath).length,
-    uploaded: cutsFile.cuts.filter((c) => c.uploadedCid || c.uploadedUrl).length,
+    artwork: imageCuts.filter(
+      (c) => c.cleanImagePath || conversionByCut.has(c.id),
+    ).length,
+    converted: imageCuts.filter(
+      (c) => c.cleanImagePath && /\.(webp|jpe?g)$/i.test(c.cleanImagePath),
+    ).length,
+    lettered: cutsFile.cuts.filter(
+      (c) => (c.overlays?.length ?? 0) > 0 || !!c.finalImagePath,
+    ).length,
+    uploaded: cutsFile.cuts.filter((c) => c.uploadedCid || c.uploadedUrl)
+      .length,
   };
+  const aiDraftEligibleCount = cutsFile.cuts.filter(
+    (cut) =>
+      canDraftLettering(cut) &&
+      (cut.overlays?.length ?? 0) === 0 &&
+      !cut.finalImagePath &&
+      !cut.uploadedCid &&
+      !cut.uploadedUrl,
+  ).length;
 
   return (
-    <div className="h-full min-h-[22rem] flex flex-col overflow-hidden" data-testid="cut-list-panel">
+    <div
+      className="h-full min-h-[22rem] flex flex-col overflow-hidden"
+      data-testid="cut-list-panel"
+    >
       {/* Episode header + creator-facing progress summary (#440). */}
-      <div className="px-3 py-2 border-b border-border flex-shrink-0" data-testid="cut-board-header">
-        <div className="flex items-center gap-2 text-xs">
-          <span className="font-serif text-foreground truncate">{episodeLabel}</span>
-          {episodeTitle && <span className="text-muted truncate">· {episodeTitle}</span>}
-        </div>
-        <div className="mt-0.5 text-[10px] text-muted" data-testid="cut-board-summary">
-          {boardSummary.cuts} cuts · {boardSummary.artwork} artwork found · {boardSummary.converted} converted · {boardSummary.lettered} lettered · {boardSummary.uploaded} uploaded
+      <div
+        className="px-3 py-2 border-b border-border flex-shrink-0"
+        data-testid="cut-board-header"
+      >
+        <div className="flex items-start gap-3 justify-between">
+          <div className="min-w-0">
+            <div className="flex items-center gap-2 text-xs">
+              <span className="font-serif text-foreground truncate">
+                {episodeLabel}
+              </span>
+              {episodeTitle && (
+                <span className="text-muted truncate">· {episodeTitle}</span>
+              )}
+            </div>
+            <div
+              className="mt-0.5 text-[10px] text-muted"
+              data-testid="cut-board-summary"
+            >
+              {boardSummary.cuts} cuts · {boardSummary.artwork} artwork found ·{" "}
+              {boardSummary.converted} converted · {boardSummary.lettered}{" "}
+              lettered · {boardSummary.uploaded} uploaded
+            </div>
+          </div>
+          {aiDraftEligibleCount > 0 && (
+            <button
+              onClick={draftAllUnletteredCuts}
+              disabled={aiDraftingAll}
+              data-testid="ai-draft-all-btn"
+              className="px-2.5 py-1 text-[11px] rounded border border-accent/40 text-accent hover:bg-accent/5 disabled:opacity-50"
+            >
+              {aiDraftingAll
+                ? "Drafting…"
+                : `AI draft all unlettered (${aiDraftEligibleCount})`}
+            </button>
+          )}
         </div>
       </div>
       {/* Lower-level / manual controls, collapsed by default so the board stays
           focused on per-cut actions (#440). The guided Finish flow + per-cut
           primary actions are the main path; these stay for power users. */}
-      <details className="border-b border-border flex-shrink-0" data-testid="cut-advanced">
-      <summary className="px-3 py-1.5 text-[10px] text-muted cursor-pointer hover:text-foreground">Technical details</summary>
-      <div className="px-3 py-2 flex flex-wrap items-center gap-2 text-[10px]">
-        <span className="font-mono text-muted">{cutsFile.cuts.length} cuts</span>
-        {stats.missing > 0 && <span className="text-muted">{stats.missing} missing</span>}
-        {stats.clean > 0 && <span className="text-green-700">{stats.clean} clean</span>}
-        {stats.lettered > 0 && <span className="text-amber-700">{stats.lettered} lettered</span>}
-        {stats.uploaded > 0 && <span className="text-green-700">{stats.uploaded} uploaded</span>}
-        {stats.text > 0 && <span className="text-accent">{stats.text} text {stats.text === 1 ? "panel" : "panels"}</span>}
-        <button
-          onClick={async () => {
-            setGenerating(true);
-            setGenWarnings([]);
-            try {
-              const res = await authFetch(`/api/stories/${storyName}/cuts/${plotFile}/generate-markdown`, { method: "POST" });
-              if (res.ok) {
-                const data = await res.json();
-                setGenWarnings(data.warnings || []);
+      <details
+        className="border-b border-border flex-shrink-0"
+        data-testid="cut-advanced"
+      >
+        <summary className="px-3 py-1.5 text-[10px] text-muted cursor-pointer hover:text-foreground">
+          Technical details
+        </summary>
+        <div className="px-3 py-2 flex flex-wrap items-center gap-2 text-[10px]">
+          <span className="font-mono text-muted">
+            {cutsFile.cuts.length} cuts
+          </span>
+          {stats.missing > 0 && (
+            <span className="text-muted">{stats.missing} missing</span>
+          )}
+          {stats.clean > 0 && (
+            <span className="text-green-700">{stats.clean} clean</span>
+          )}
+          {stats.lettered > 0 && (
+            <span className="text-amber-700">{stats.lettered} lettered</span>
+          )}
+          {stats.uploaded > 0 && (
+            <span className="text-green-700">{stats.uploaded} uploaded</span>
+          )}
+          {stats.text > 0 && (
+            <span className="text-accent">
+              {stats.text} text {stats.text === 1 ? "panel" : "panels"}
+            </span>
+          )}
+          <button
+            onClick={async () => {
+              setGenerating(true);
+              setGenWarnings([]);
+              try {
+                const res = await authFetch(
+                  `/api/stories/${storyName}/cuts/${plotFile}/generate-markdown`,
+                  { method: "POST" },
+                );
+                if (res.ok) {
+                  const data = await res.json();
+                  setGenWarnings(data.warnings || []);
+                }
+              } catch {
+                /* ignore */
               }
-            } catch { /* ignore */ }
-            setGenerating(false);
-          }}
-          disabled={generating}
-          className="ml-auto px-2 py-0.5 border border-accent/30 text-accent rounded hover:bg-accent/5 disabled:opacity-50"
-          data-testid="generate-markdown-btn"
-          title="Build the publish-ready episode from the uploaded cut images"
-        >
-          {generating ? "Preparing…" : "Prepare episode for publish"}
-        </button>
-        <button
-          onClick={addTextPanel}
-          disabled={addingPanel}
-          className="px-2 py-0.5 border border-accent/30 text-accent rounded hover:bg-accent/5 disabled:opacity-50"
-          data-testid="add-text-panel-btn"
-          title="Insert a narration/title card between art panels — a solid card exported as a final image panel, no drawing needed"
-        >
-          {addingPanel ? "Adding…" : "Add narration/text panel"}
-        </button>
-        <button
-          onClick={refreshAssets}
-          disabled={rescanning}
-          className="px-2 py-0.5 border border-border text-muted rounded hover:border-accent hover:text-accent disabled:opacity-50"
-          data-testid="refresh-assets-btn"
-          title="Re-check the story folder for agent-generated images and report each cut's asset state — read only, nothing is uploaded or published"
-        >
-          {rescanning ? "Checking…" : "Refresh assets"}
-        </button>
-        <button
-          onClick={syncCleanImages}
-          disabled={syncing}
-          className="px-2 py-0.5 border border-accent/30 text-accent rounded hover:bg-accent/5 disabled:opacity-50"
-          data-testid="sync-clean-btn"
-        >
-          {syncing ? "Syncing..." : "Sync clean images"}
-        </button>
-        <button
-          onClick={finishEpisode}
-          disabled={uploading || !cutsFile?.cuts.some((ct) => ct.finalImagePath && !ct.uploadedCid)}
-          className="px-2 py-0.5 border border-accent/30 text-accent rounded hover:bg-accent/5 disabled:opacity-50"
-          data-testid="upload-generate-btn"
-          title="Upload each cut's final lettered image, then prepare the episode for publishing"
-        >
-          {uploadProgress || "Upload & Prepare for Publish"}
-        </button>
-      </div>
+              setGenerating(false);
+            }}
+            disabled={generating}
+            className="ml-auto px-2 py-0.5 border border-accent/30 text-accent rounded hover:bg-accent/5 disabled:opacity-50"
+            data-testid="generate-markdown-btn"
+            title="Build the publish-ready episode from the uploaded cut images"
+          >
+            {generating ? "Preparing…" : "Prepare episode for publish"}
+          </button>
+          <button
+            onClick={addTextPanel}
+            disabled={addingPanel}
+            className="px-2 py-0.5 border border-accent/30 text-accent rounded hover:bg-accent/5 disabled:opacity-50"
+            data-testid="add-text-panel-btn"
+            title="Insert a narration/title card between art panels — a solid card exported as a final image panel, no drawing needed"
+          >
+            {addingPanel ? "Adding…" : "Add narration/text panel"}
+          </button>
+          <button
+            onClick={refreshAssets}
+            disabled={rescanning}
+            className="px-2 py-0.5 border border-border text-muted rounded hover:border-accent hover:text-accent disabled:opacity-50"
+            data-testid="refresh-assets-btn"
+            title="Re-check the story folder for agent-generated images and report each cut's asset state — read only, nothing is uploaded or published"
+          >
+            {rescanning ? "Checking…" : "Refresh assets"}
+          </button>
+          <button
+            onClick={syncCleanImages}
+            disabled={syncing}
+            className="px-2 py-0.5 border border-accent/30 text-accent rounded hover:bg-accent/5 disabled:opacity-50"
+            data-testid="sync-clean-btn"
+          >
+            {syncing ? "Syncing..." : "Sync clean images"}
+          </button>
+          <button
+            onClick={finishEpisode}
+            disabled={
+              uploading ||
+              !cutsFile?.cuts.some((ct) => ct.finalImagePath && !ct.uploadedCid)
+            }
+            className="px-2 py-0.5 border border-accent/30 text-accent rounded hover:bg-accent/5 disabled:opacity-50"
+            data-testid="upload-generate-btn"
+            title="Upload each cut's final lettered image, then prepare the episode for publishing"
+          >
+            {uploadProgress || "Upload & Prepare for Publish"}
+          </button>
+        </div>
       </details>
       {/* Plain-language workflow + text-panel explainer (#360) so a non-technical
           writer understands the order of operations and what a text panel is. */}
-      <div
-        className="px-3 py-2 border-b border-border bg-surface/40 flex-shrink-0"
+      <details
+        className="px-3 py-1.5 border-b border-border bg-surface/40 flex-shrink-0"
         data-testid="cartoon-workflow-help"
       >
-        <div className="flex flex-wrap items-center gap-1.5 text-[10px] text-muted">
-          <span className="rounded-full border border-border bg-background px-2 py-0.5 text-foreground">1. Letter</span>
-          <span aria-hidden>→</span>
-          <span className="rounded-full border border-border bg-background px-2 py-0.5 text-foreground">2. Export</span>
-          <span aria-hidden>→</span>
-          <span className="rounded-full border border-border bg-background px-2 py-0.5 text-foreground">3. Upload</span>
-          <span aria-hidden>→</span>
-          <span className="rounded-full border border-border bg-background px-2 py-0.5 text-foreground">4. Prepare episode for publish</span>
-        </div>
-        <div className="mt-1 text-[10px] text-muted">
-          Use <span className="text-accent">Add narration/text panel</span> for a narration or title card. It becomes a solid card exported as a final image.
+        <summary className="cursor-pointer select-none text-[10px] text-muted hover:text-foreground">
+          Cut workflow help
+        </summary>
+        <div className="mt-1.5">
+          <div className="flex flex-wrap items-center gap-1.5 text-[10px] text-muted">
+            <span className="rounded-full border border-border bg-background px-2 py-0.5 text-foreground">
+              1. Letter
+            </span>
+            <span aria-hidden>→</span>
+            <span className="rounded-full border border-border bg-background px-2 py-0.5 text-foreground">
+              2. Export
+            </span>
+            <span aria-hidden>→</span>
+            <span className="rounded-full border border-border bg-background px-2 py-0.5 text-foreground">
+              3. Upload
+            </span>
+            <span aria-hidden>→</span>
+            <span className="rounded-full border border-border bg-background px-2 py-0.5 text-foreground">
+              4. Prepare episode for publish
+            </span>
+          </div>
+          <div className="mt-1 text-[10px] text-muted">
+            Use <span className="text-accent">Add narration/text panel</span>{" "}
+            for a narration or title card. It becomes a solid card exported as a
+            final image.
+          </div>
         </div>
-      </div>
+      </details>
       {/* Stale bubble-renderer warning (#381): a final image lettered before the
           current seamless-tail renderer may show the old separate-tail seam.
           Mark those cuts so the writer re-exports (open lettering → Export) and
@@ -1179,23 +1765,38 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
           className="px-3 py-1.5 border-b border-amber-500/40 bg-amber-500/10 text-[10px] text-amber-700 flex-shrink-0"
           data-testid="stale-bubble-export-warning"
         >
-          {staleTailIds.length === 1 ? "Cut" : "Cuts"} {staleTailIds.join(", ")} {staleTailIds.length === 1 ? "was" : "were"} lettered with an older speech-bubble style whose tail can show a visible seam. Re-export {staleTailIds.length === 1 ? "it" : "them"} (open lettering → Export) and re-upload before publishing so the bubble tails are seamless.
+          {staleTailIds.length === 1 ? "Cut" : "Cuts"} {staleTailIds.join(", ")}{" "}
+          {staleTailIds.length === 1 ? "was" : "were"} lettered with an older
+          speech-bubble style whose tail can show a visible seam. Re-export{" "}
+          {staleTailIds.length === 1 ? "it" : "them"} (open lettering → Export)
+          and re-upload before publishing so the bubble tails are seamless.
         </div>
       )}
       {/* Clean-asset generation done-state (#311): when every cut has a present,
           valid clean image, surface a clear "done" signal so the operator knows
           Codex generation is complete even if the terminal session is still
           connected — no more guessing whether it is still Working. */}
-      {detectConfirmed && imageCutCount > 0 && stats.missing === 0 && staleByCut.size === 0 && (
-        <div className="px-3 py-1 border-b border-border bg-green-600/10 text-[10px] text-green-700 flex items-center gap-1 flex-shrink-0" data-testid="clean-assets-ready">
-          <span aria-hidden>✓</span>
-          <span>
-            All {imageCutCount} clean image{imageCutCount === 1 ? "" : "s"} present — clean-asset generation is complete. Ready for lettering in OWS.
-          </span>
-        </div>
-      )}
+      {detectConfirmed &&
+        imageCutCount > 0 &&
+        stats.missing === 0 &&
+        staleByCut.size === 0 && (
+          <div
+            className="px-3 py-1 border-b border-border bg-green-600/10 text-[10px] text-green-700 flex items-center gap-1 flex-shrink-0"
+            data-testid="clean-assets-ready"
+          >
+            <span aria-hidden>✓</span>
+            <span>
+              All {imageCutCount} clean image{imageCutCount === 1 ? "" : "s"}{" "}
+              present — clean-asset generation is complete. Ready for lettering
+              in OWS.
+            </span>
+          </div>
+        )}
       {syncResult && (
-        <div className="px-3 py-1 border-b border-border text-[10px] text-muted flex-shrink-0" data-testid="sync-result">
+        <div
+          className="px-3 py-1 border-b border-border text-[10px] text-muted flex-shrink-0"
+          data-testid="sync-result"
+        >
           {syncResult}
         </div>
       )}
@@ -1204,10 +1805,17 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
           than red "Unsupported extension" errors. The raw reasons stay available
           under a collapsed "Technical details" disclosure. */}
       {conversionJobs.length > 0 && (
-        <div className="px-3 py-2 border-b border-amber-500/40 bg-amber-500/10 text-[11px] flex-shrink-0" data-testid="convert-artwork">
+        <div
+          className="px-3 py-2 border-b border-amber-500/40 bg-amber-500/10 text-[11px] flex-shrink-0"
+          data-testid="convert-artwork"
+        >
           <div className="flex items-center gap-2 flex-wrap">
-            <span className="font-medium text-amber-700" data-testid="convert-artwork-count">
-              {conversionJobs.length} PNG image{conversionJobs.length === 1 ? "" : "s"} found
+            <span
+              className="font-medium text-amber-700"
+              data-testid="convert-artwork-count"
+            >
+              {conversionJobs.length} PNG image
+              {conversionJobs.length === 1 ? "" : "s"} found
             </span>
             <button
               onClick={() => convertAll(conversionJobs)}
@@ -1219,14 +1827,26 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
             </button>
           </div>
           <p className="mt-1 text-[10px] text-muted">
-            PNG artwork is fine while drafting. Convert it before lettering/export so PlotLink can publish it safely.
+            PNG artwork is fine while drafting. Convert it before
+            lettering/export so PlotLink can publish it safely.
           </p>
-          {convertResult && <p className="mt-1 text-[10px] text-muted" data-testid="convert-result">{convertResult}</p>}
+          {convertResult && (
+            <p
+              className="mt-1 text-[10px] text-muted"
+              data-testid="convert-result"
+            >
+              {convertResult}
+            </p>
+          )}
           {conversionIssues.length > 0 && (
             <details className="mt-1" data-testid="convert-technical-details">
-              <summary className="text-[10px] text-muted cursor-pointer">Technical details</summary>
+              <summary className="text-[10px] text-muted cursor-pointer">
+                Technical details
+              </summary>
               <ul className="mt-1 ml-3 list-disc text-[10px] text-muted">
-                {conversionIssues.map((m, i) => <li key={i}>{m}</li>)}
+                {conversionIssues.map((m, i) => (
+                  <li key={i}>{m}</li>
+                ))}
               </ul>
             </details>
           )}
@@ -1236,22 +1856,37 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
           state tally + a precise per-cut reason when a recorded path is broken,
           so "files exist but aren't shown" / a typoed path is a clear diagnostic
           rather than a generic publish warning. */}
-      {assetDiagnostics && assetDiagnostics.length > 0 && (() => {
-        const s = summarizeAssetDiagnostics(assetDiagnostics);
-        const missing = assetDiagnostics.filter((d) => d.state === "missing");
-        return (
-          <div className="px-3 py-1.5 border-b border-border bg-surface/40 text-[10px] flex-shrink-0" data-testid="asset-diagnostics">
-            <span className="text-muted" data-testid="asset-diag-summary">
-              Assets: {s.uploaded} uploaded · {s.finalReady} final · {s.cleanReady} clean · {s.planned} planned{s.needsConversion > 0 ? ` · ${s.needsConversion} needs conversion` : ""}{s.missing > 0 ? ` · ${s.missing} missing` : ""}
-            </span>
-            {missing.length > 0 && (
-              <ul className="mt-1 ml-3 list-disc text-error" data-testid="asset-diag-issues">
-                {missing.map((d) => <li key={d.cutId}>{d.issue}</li>)}
-              </ul>
-            )}
-          </div>
-        );
-      })()}
+      {assetDiagnostics &&
+        assetDiagnostics.length > 0 &&
+        (() => {
+          const s = summarizeAssetDiagnostics(assetDiagnostics);
+          const missing = assetDiagnostics.filter((d) => d.state === "missing");
+          return (
+            <div
+              className="px-3 py-1.5 border-b border-border bg-surface/40 text-[10px] flex-shrink-0"
+              data-testid="asset-diagnostics"
+            >
+              <span className="text-muted" data-testid="asset-diag-summary">
+                Assets: {s.uploaded} uploaded · {s.finalReady} final ·{" "}
+                {s.cleanReady} clean · {s.planned} planned
+                {s.needsConversion > 0
+                  ? ` · ${s.needsConversion} needs conversion`
+                  : ""}
+                {s.missing > 0 ? ` · ${s.missing} missing` : ""}
+              </span>
+              {missing.length > 0 && (
+                <ul
+                  className="mt-1 ml-3 list-disc text-error"
+                  data-testid="asset-diag-issues"
+                >
+                  {missing.map((d) => (
+                    <li key={d.cutId}>{d.issue}</li>
+                  ))}
+                </ul>
+              )}
+            </div>
+          );
+        })()}
       {/* Guided Finish-episode flow (#414): writer-language step status, one primary
           "Finish episode" action that uploads finals then prepares the publish
           markdown in order, and any blockers grouped by the step that fixes them —
@@ -1268,32 +1903,107 @@ export function CutListPanel({ storyName, fileName, authFetch, language, uploadR
         published={episodeState.published}
       />
 
-      {/* Cut list */}
-      <div className="flex-1 min-h-56 overflow-y-auto p-3 space-y-2" data-testid="cut-list-scroll">
-        {cutsFile.cuts.map((cut) => (
-          <CutRow
-            key={cut.id}
-            cut={cut}
-            storyName={storyName}
-            plotFile={plotFile}
-            expanded={expandedCut === cut.id}
-            onToggle={() => setExpandedCut(expandedCut === cut.id ? null : cut.id)}
-            authFetch={authFetch}
-            onUpdated={() => { loadCuts(); loadDetect(); loadDiagnostics(); }}
-            onOpenEditor={() => setEditingCutId(cut.id)}
-            detectedLocalClean={detected.has(cut.id)}
-            onSyncClean={syncCleanImages}
-            syncing={syncing}
-            staleMessages={staleByCut.get(cut.id) ?? []}
-            onRepairStale={repairStalePaths}
-            repairing={repairing}
-            conversionPng={conversionByCut.get(cut.id) ?? null}
-            onConvert={convertCut}
-            converting={converting}
-            rowRef={(el) => { if (el) rowRefs.current.set(cut.id, el); else rowRefs.current.delete(cut.id); }}
-          />
+      {/* Full cut review (#488): all clean cuts are shown vertically first, with
+          explicit between-scene slots for narration/title cards. */}
+      <div
+        className="flex-1 min-h-56 overflow-y-auto p-3 space-y-3"
+        data-testid="lettering-review-board"
+      >
+        {cutsFile.cuts.map((cut, index) => (
+          <Fragment key={cut.id}>
+            <BetweenSceneSlot
+              index={index}
+              beforeLabel={
+                index === 0
+                  ? "Episode opening"
+                  : `After cut ${cutsFile.cuts[index - 1]?.id}`
+              }
+              afterLabel={`Before cut ${cut.id}`}
+              disabled={addingPanel}
+              onAdd={() => addTextPanelAt(index)}
+            />
+            <CutRow
+              cut={cut}
+              storyName={storyName}
+              plotFile={plotFile}
+              expanded={expandedCut === cut.id}
+              onToggle={() =>
+                setExpandedCut(expandedCut === cut.id ? null : cut.id)
+              }
+              authFetch={authFetch}
+              onUpdated={() => {
+                loadCuts();
+                loadDetect();
+                loadDiagnostics();
+              }}
+              onOpenEditor={() => setEditingCutId(cut.id)}
+              detectedLocalClean={detected.has(cut.id)}
+              onSyncClean={syncCleanImages}
+              syncing={syncing}
+              onAiDraft={() => {
+                void draftCutWithAi(cut.id, { openEditor: true });
+              }}
+              aiDrafting={aiDraftingCutId === cut.id}
+              staleMessages={staleByCut.get(cut.id) ?? []}
+              onRepairStale={repairStalePaths}
+              repairing={repairing}
+              conversionPng={conversionByCut.get(cut.id) ?? null}
+              onConvert={convertCut}
+              converting={converting}
+              rowRef={(el) => {
+                if (el) rowRefs.current.set(cut.id, el);
+                else rowRefs.current.delete(cut.id);
+              }}
+            />
+          </Fragment>
         ))}
+        <BetweenSceneSlot
+          index={cutsFile.cuts.length}
+          beforeLabel={`After cut ${cutsFile.cuts[cutsFile.cuts.length - 1]?.id}`}
+          afterLabel="Episode ending"
+          disabled={addingPanel}
+          onAdd={() => addTextPanelAt(cutsFile.cuts.length)}
+        />
       </div>
     </div>
   );
 }
+
+function BetweenSceneSlot({
+  index,
+  beforeLabel,
+  afterLabel,
+  disabled,
+  onAdd,
+}: {
+  index: number;
+  beforeLabel: string;
+  afterLabel: string;
+  disabled: boolean;
+  onAdd: () => void;
+}) {
+  return (
+    <div
+      className="rounded border border-dashed border-border bg-surface/35 px-3 py-2 text-[11px] text-muted flex items-center gap-3"
+      data-testid={`between-scene-slot-${index}`}
+    >
+      <span className="min-w-0 flex-1">
+        <span className="font-medium text-foreground">
+          Between-scene lettering
+        </span>
+        <span className="block truncate">
+          {beforeLabel} · {afterLabel}
+        </span>
+      </span>
+      <button
+        type="button"
+        onClick={onAdd}
+        disabled={disabled}
+        className="flex-shrink-0 rounded border border-accent/40 px-2.5 py-1 text-[11px] font-medium text-accent hover:bg-accent/5 disabled:opacity-50"
+        data-testid={`add-between-scene-${index}`}
+      >
+        Add card
+      </button>
+    </div>
+  );
+}