plotlink-ows 1.2.94 → 1.2.96

package/app/web/components/LetteringEditor.tsx

@@ -20,8 +20,14 @@ import {
   type OverlayType,
 } from "@app-lib/overlays";
 import { layoutBubbleText } from "@app-lib/bubble-text";
-import { cutLetteringChecklist, cutScriptLines, isExportStale, overlaysSignature, type ScriptLine } from "@app-lib/lettering-status";
-import { textPanelDimensions } from "@app-lib/cuts";
+import {
+  cutLetteringChecklist,
+  cutScriptLines,
+  isExportStale,
+  overlaysSignature,
+  type ScriptLine,
+} from "@app-lib/lettering-status";
+import { textPanelDimensions, type CutAiDraft } from "@app-lib/cuts";
 import { useAuthedAsset } from "./asset-image";
 
 function toPixel(norm: number, size: number): number {
@@ -61,17 +67,29 @@ interface Cut {
   kind?: "image" | "text";
   background?: string;
   aspectRatio?: string;
+  aiDraft?: CutAiDraft | null;
 }
 
 interface LetteringEditorProps {
   storyName: string;
   cut: Cut;
   plotFile: string;
-  onSave: (overlays: Overlay[]) => void | Promise<void>;
+  onSave: (
+    overlays: Overlay[],
+    aiDraft?: CutAiDraft | null,
+  ) => void | Promise<void>;
   onClose: () => void;
   onExported?: () => void;
   language?: string;
   authFetch: (url: string, opts?: RequestInit) => Promise<Response>;
+  /** Focused-editor header label supplied by the review board (#488). */
+  targetLabel?: string;
+  /** When true, the Save button returns to the review board after persisting. */
+  returnOnSave?: boolean;
+  /** Whether the wider app work area / terminal is currently restored. */
+  workspaceVisible?: boolean;
+  /** Toggle the surrounding app work area while staying in the editor. */
+  onToggleWorkspaceVisible?: () => void;
 }
 
 const TYPE_LABEL: Record<OverlayType, string> = {
@@ -90,7 +108,8 @@ const TYPE_BORDER: Record<OverlayType, string> = {
 // a trimmed text snippet, falling back to the type name for empty bubbles.
 function overlapLabel(o: Overlay): string {
   const snippet = (o.speaker || o.text || "").trim().replace(/\s+/g, " ");
-  if (snippet) return `“${snippet.length > 18 ? `${snippet.slice(0, 18)}…` : snippet}”`;
+  if (snippet)
+    return `“${snippet.length > 18 ? `${snippet.slice(0, 18)}…` : snippet}”`;
   return TYPE_LABEL[o.type];
 }
 
@@ -106,7 +125,20 @@ function clamp(v: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, v));
 }
 
-export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onExported, language = "English", authFetch }: LetteringEditorProps) {
+export function LetteringEditor({
+  storyName,
+  cut,
+  plotFile,
+  onSave,
+  onClose,
+  onExported,
+  language = "English",
+  authFetch,
+  targetLabel,
+  returnOnSave = false,
+  workspaceVisible = false,
+  onToggleWorkspaceVisible,
+}: LetteringEditorProps) {
   const bodyFont = getDefaultFont(language);
   const displayFont = getDisplayFont();
   const bodyFontFamily = getFontFamily(bodyFont);
@@ -126,10 +158,14 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
       try {
         const { ensureFontsReady } = await import("./export-cut");
         await ensureFontsReady([bodyFont.family, displayFont.family]);
-      } catch { /* best effort — still render the preview */ }
+      } catch {
+        /* best effort — still render the preview */
+      }
       if (!cancelled) setFontsReady(true);
     })();
-    return () => { cancelled = true; };
+    return () => {
+      cancelled = true;
+    };
   }, [bodyFont.family, displayFont.family]);
 
   // Clean image lives behind requireAuth, so a raw <img src> would 401. Load it
@@ -138,15 +174,22 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
   // Repair agent-authored overlays (e.g. semantic `position` strings with no
   // numeric geometry) on load so the bubbles actually render and export — and
   // surface a note when some could not be auto-placed (#309).
-  const overlayNormalization = useMemo(() => normalizeOverlays(cut.overlays), [cut.overlays]);
+  const overlayNormalization = useMemo(
+    () => normalizeOverlays(cut.overlays),
+    [cut.overlays],
+  );
   const invalidOverlayCount = overlayNormalization.invalid.length;
   // Overlays that could not be placed (no geometry, no recognizable position)
   // are NOT exported. Exporting silently would produce a final missing that
   // bubble/text, so block export until the writer explicitly discards them (#309).
   const [acknowledgedInvalid, setAcknowledgedInvalid] = useState(false);
   const autoPlacedOverlays =
-    invalidOverlayCount === 0 && overlayNormalization.changed && overlayNormalization.overlays.length > 0;
-  const [overlays, setOverlays] = useState<Overlay[]>(() => overlayNormalization.overlays as Overlay[]);
+    invalidOverlayCount === 0 &&
+    overlayNormalization.changed &&
+    overlayNormalization.overlays.length > 0;
+  const [overlays, setOverlays] = useState<Overlay[]>(
+    () => overlayNormalization.overlays as Overlay[],
+  );
   // Signature of the overlays that match the current export/upload (#336, re1).
   // Captured (already normalized like the live `overlays`) when the cut opens so
   // a load-time normalization isn't mistaken for a user edit, and advanced to the
@@ -158,15 +201,19 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
   // Offscreen canvas to measure text exactly like the export canvas, so the
   // preview wraps/sizes bubble text identically to the final image (#310).
   const measureCanvasRef = useRef<HTMLCanvasElement | null>(null);
-  const measureWidth = useCallback((fontFamily: string) => (text: string, fontSize: number, fontWeight: 400 | 700 = 400): number => {
-    if (!measureCanvasRef.current && typeof document !== "undefined") {
-      measureCanvasRef.current = document.createElement("canvas");
-    }
-    const mctx = measureCanvasRef.current?.getContext("2d");
-    if (!mctx) return text.length * fontSize * 0.5; // jsdom fallback
-    mctx.font = `${fontWeight} ${fontSize}px ${fontFamily}`;
-    return mctx.measureText(text).width;
-  }, []);
+  const measureWidth = useCallback(
+    (fontFamily: string) =>
+      (text: string, fontSize: number, fontWeight: 400 | 700 = 400): number => {
+        if (!measureCanvasRef.current && typeof document !== "undefined") {
+          measureCanvasRef.current = document.createElement("canvas");
+        }
+        const mctx = measureCanvasRef.current?.getContext("2d");
+        if (!mctx) return text.length * fontSize * 0.5; // jsdom fallback
+        mctx.font = `${fontWeight} ${fontSize}px ${fontFamily}`;
+        return mctx.measureText(text).width;
+      },
+    [],
+  );
   // Gate the exact (canvas-measured) preview layout on the SAME font-readiness
   // signal export uses (ensureFontsReady), so the preview does not freeze line
   // breaks computed from fallback-font metrics that would diverge from the
@@ -176,10 +223,25 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
   const [confirmDelete, setConfirmDelete] = useState(false);
   const [exporting, setExporting] = useState(false);
   const [exportError, setExportError] = useState<string | null>(null);
-  const [imageBounds, setImageBounds] = useState({ x: 0, y: 0, width: 0, height: 0 });
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const [imageBounds, setImageBounds] = useState({
+    x: 0,
+    y: 0,
+    width: 0,
+    height: 0,
+  });
   const containerRef = useRef<HTMLDivElement>(null);
   const imgRef = useRef<HTMLImageElement>(null);
-  const dragRef = useRef<{ id: string; mode: "move" | "resize"; startX: number; startY: number; origX: number; origY: number; origW: number; origH: number } | null>(null);
+  const dragRef = useRef<{
+    id: string;
+    mode: "move" | "resize";
+    startX: number;
+    startY: number;
+    origX: number;
+    origY: number;
+    origW: number;
+    origH: number;
+  } | null>(null);
 
   const updateImageBounds = useCallback(() => {
     const container = containerRef.current;
@@ -191,7 +253,10 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
     if (cut.kind === "text") {
       // A text panel has no image — size the editor canvas from the SAME aspect
       // ratio the export uses, so lettering and the exported final agree (#351).
-      const dims = textPanelDimensions(cut.aspectRatio) ?? { width: 800, height: 600 };
+      const dims = textPanelDimensions(cut.aspectRatio) ?? {
+        width: 800,
+        height: 600,
+      };
       iw = dims.width;
       ih = dims.height;
     } else {
@@ -204,7 +269,12 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
     const scale = Math.min(cw / iw, ch / ih);
     const rw = iw * scale;
     const rh = ih * scale;
-    setImageBounds({ x: (cw - rw) / 2, y: (ch - rh) / 2, width: rw, height: rh });
+    setImageBounds({
+      x: (cw - rw) / 2,
+      y: (ch - rh) / 2,
+      width: rw,
+      height: rh,
+    });
   }, [cut.kind, cut.aspectRatio]);
 
   useEffect(() => {
@@ -221,76 +291,130 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
   // default font; without measurement it falls back to a generous default that
   // fits ordinary lines, instead of the tiny create-default. The writer can still
   // resize freely afterward, and the overflow warning stays useful if they shrink it.
-  const fittedSize = useCallback((o: Overlay): { width: number; height: number } => {
-    const comfortable = comfortableOverlaySize(o.type, o.x, o.y);
-    const width = comfortable.width;
-    const maxH = Math.max(0.08, 1 - o.y);
-    if (!o.text || !fontsReady || imageBounds.width <= 0) {
-      return comfortable;
-    }
-    const fontFamily = o.type === "sfx" ? displayFontFamily : bodyFontFamily;
-    const wPx = toPixel(width, imageBounds.width);
-    let height = o.type === "sfx" ? 0.08 : 0.12;
-    for (let i = 0; i < 24; i++) {
-      const h = Math.min(height, maxH);
-      const hPx = toPixel(h, imageBounds.height);
-      const layout = layoutBubbleText(
-        measureWidth(fontFamily), o.text, wPx, hPx,
-        bubbleLayoutOptionsForOverlay({ ...o, width, height: h }, imageBounds.height || 300, wPx, hPx),
-      );
-      if (!layout.overflow || h >= maxH) return { width, height: h };
-      height += 0.03;
-    }
-    return { width, height: Math.min(height, maxH) };
-  }, [fontsReady, imageBounds, measureWidth, bodyFontFamily, displayFontFamily]);
+  const fittedSize = useCallback(
+    (o: Overlay): { width: number; height: number } => {
+      const comfortable = comfortableOverlaySize(o.type, o.x, o.y);
+      const width = comfortable.width;
+      const maxH = Math.max(0.08, 1 - o.y);
+      if (!o.text || !fontsReady || imageBounds.width <= 0) {
+        return comfortable;
+      }
+      const fontFamily = o.type === "sfx" ? displayFontFamily : bodyFontFamily;
+      const wPx = toPixel(width, imageBounds.width);
+      let height = o.type === "sfx" ? 0.08 : 0.12;
+      for (let i = 0; i < 24; i++) {
+        const h = Math.min(height, maxH);
+        const hPx = toPixel(h, imageBounds.height);
+        const layout = layoutBubbleText(
+          measureWidth(fontFamily),
+          o.text,
+          wPx,
+          hPx,
+          bubbleLayoutOptionsForOverlay(
+            { ...o, width, height: h },
+            imageBounds.height || 300,
+            wPx,
+            hPx,
+          ),
+        );
+        if (!layout.overflow || h >= maxH) return { width, height: h };
+        height += 0.03;
+      }
+      return { width, height: Math.min(height, maxH) };
+    },
+    [fontsReady, imageBounds, measureWidth, bodyFontFamily, displayFontFamily],
+  );
 
-  const addOverlay = useCallback((type: OverlayType) => {
-    const o = createOverlay(type, 0.1 + Math.random() * 0.3, 0.1 + Math.random() * 0.3);
-    const sized: Overlay = { ...o, ...fittedSize(o) };
-    setOverlays((prev) => [...prev, sized]);
-    setSelectedId(sized.id);
-  }, [fittedSize]);
+  const addOverlay = useCallback(
+    (type: OverlayType) => {
+      const o = createOverlay(
+        type,
+        0.1 + Math.random() * 0.3,
+        0.1 + Math.random() * 0.3,
+      );
+      const sized: Overlay = { ...o, ...fittedSize(o) };
+      setOverlays((prev) => [...prev, sized]);
+      setSelectedId(sized.id);
+    },
+    [fittedSize],
+  );
 
   // Insert a line from the cut's cuts.json script (#336) as a prefilled overlay,
   // so the writer never has to hand-copy dialogue/narration/SFX out of the JSON.
-  const addScriptLine = useCallback((line: ScriptLine) => {
-    const o = createOverlay(line.type, 0.1 + Math.random() * 0.3, 0.1 + Math.random() * 0.3);
-    const filled: Overlay = {
-      ...o,
-      text: line.text,
-      ...(line.type === "speech" && line.speaker ? { speaker: line.speaker } : {}),
-    };
-    const sized: Overlay = { ...filled, ...fittedSize(filled) };
-    setOverlays((prev) => [...prev, sized]);
-    setSelectedId(sized.id);
-  }, [fittedSize]);
+  const addScriptLine = useCallback(
+    (line: ScriptLine) => {
+      const o = createOverlay(
+        line.type,
+        0.1 + Math.random() * 0.3,
+        0.1 + Math.random() * 0.3,
+      );
+      const filled: Overlay = {
+        ...o,
+        text: line.text,
+        ...(line.type === "speech" && line.speaker
+          ? { speaker: line.speaker }
+          : {}),
+      };
+      const sized: Overlay = { ...filled, ...fittedSize(filled) };
+      setOverlays((prev) => [...prev, sized]);
+      setSelectedId(sized.id);
+    },
+    [fittedSize],
+  );
 
   const updateOverlay = useCallback((id: string, changes: Partial<Overlay>) => {
-    setOverlays((prev) => prev.map((o) => o.id === id ? { ...o, ...changes } : o));
+    setOverlays((prev) =>
+      prev.map((o) => (o.id === id ? { ...o, ...changes } : o)),
+    );
   }, []);
 
-  const enableManualTypography = useCallback((overlay: Overlay) => {
-    const renderHeight = imageBounds.height || 300;
-    const width = imageBounds.width > 0 ? toPixel(overlay.width, imageBounds.width) : 200;
-    const height = imageBounds.height > 0 ? toPixel(overlay.height, imageBounds.height) : 100;
-    const fontFamily = overlay.type === "sfx" ? displayFontFamily : bodyFontFamily;
-    const autoLayout = layoutBubbleText(
-      measureWidth(fontFamily),
-      overlay.text,
-      width,
-      height,
-      bubbleLayoutOptionsForOverlay({ ...overlay, textStyle: undefined }, renderHeight, width, height),
-    );
-    updateOverlay(overlay.id, {
+  const enableManualTypography = useCallback(
+    (overlay: Overlay) => {
+      const renderHeight = imageBounds.height || 300;
+      const width =
+        imageBounds.width > 0 ? toPixel(overlay.width, imageBounds.width) : 200;
+      const height =
+        imageBounds.height > 0
+          ? toPixel(overlay.height, imageBounds.height)
+          : 100;
+      const fontFamily =
+        overlay.type === "sfx" ? displayFontFamily : bodyFontFamily;
+      const autoLayout = layoutBubbleText(
+        measureWidth(fontFamily),
+        overlay.text,
+        width,
+        height,
+        bubbleLayoutOptionsForOverlay(
+          { ...overlay, textStyle: undefined },
+          renderHeight,
+          width,
+          height,
+        ),
+      );
+      updateOverlay(overlay.id, {
         textStyle: {
           mode: "manual",
           fontScale: autoLayout.fontSize / Math.max(1, renderHeight),
           fontWeight: overlay.textStyle?.fontWeight ?? 400,
-          lineHeightFactor: autoLayout.fontSize > 0 ? autoLayout.lineHeight / autoLayout.fontSize : 1.2,
-          speakerScale: autoLayout.fontSize > 0 && autoLayout.speakerFontSize > 0 ? autoLayout.speakerFontSize / autoLayout.fontSize : 0.8,
+          lineHeightFactor:
+            autoLayout.fontSize > 0
+              ? autoLayout.lineHeight / autoLayout.fontSize
+              : 1.2,
+          speakerScale:
+            autoLayout.fontSize > 0 && autoLayout.speakerFontSize > 0
+              ? autoLayout.speakerFontSize / autoLayout.fontSize
+              : 0.8,
         },
-    });
-  }, [imageBounds, displayFontFamily, bodyFontFamily, measureWidth, updateOverlay]);
+      });
+    },
+    [
+      imageBounds,
+      displayFontFamily,
+      bodyFontFamily,
+      measureWidth,
+      updateOverlay,
+    ],
+  );
 
   const deleteOverlay = useCallback((id: string) => {
     setOverlays((prev) => prev.filter((o) => o.id !== id));
@@ -309,23 +433,26 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
     setConfirmDelete(false);
   }, []);
 
-  const handleMouseDown = useCallback((e: React.MouseEvent, id: string, mode: "move" | "resize") => {
-    e.stopPropagation();
-    e.preventDefault();
-    const overlay = overlays.find((o) => o.id === id);
-    if (!overlay) return;
-    setSelectedId(id);
-    dragRef.current = {
-      id,
-      mode,
-      startX: e.clientX,
-      startY: e.clientY,
-      origX: overlay.x,
-      origY: overlay.y,
-      origW: overlay.width,
-      origH: overlay.height,
-    };
-  }, [overlays]);
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent, id: string, mode: "move" | "resize") => {
+      e.stopPropagation();
+      e.preventDefault();
+      const overlay = overlays.find((o) => o.id === id);
+      if (!overlay) return;
+      setSelectedId(id);
+      dragRef.current = {
+        id,
+        mode,
+        startX: e.clientX,
+        startY: e.clientY,
+        origX: overlay.x,
+        origY: overlay.y,
+        origW: overlay.width,
+        origH: overlay.height,
+      };
+    },
+    [overlays],
+  );
 
   useEffect(() => {
     const onMouseMove = (e: MouseEvent) => {
@@ -345,7 +472,9 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
       }
     };
 
-    const onMouseUp = () => { dragRef.current = null; };
+    const onMouseUp = () => {
+      dragRef.current = null;
+    };
 
     window.addEventListener("mousemove", onMouseMove);
     window.addEventListener("mouseup", onMouseUp);
@@ -355,9 +484,27 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
     };
   }, [imageBounds, updateOverlay]);
 
-  const handleSave = useCallback(() => {
-    onSave(overlays);
-  }, [overlays, onSave]);
+  const handleSave = useCallback(async () => {
+    setSaveError(null);
+    try {
+      const currentSig = overlaysSignature(overlays);
+      const nextAiDraft =
+        cut.aiDraft?.status === "generated" &&
+        currentSig !== (cut.aiDraft.baseSig ?? "")
+          ? {
+              ...cut.aiDraft,
+              status: "edited" as const,
+              updatedAt: new Date().toISOString(),
+            }
+          : (cut.aiDraft ?? undefined);
+      await onSave(overlays, nextAiDraft ?? null);
+      if (returnOnSave) onClose();
+    } catch (err) {
+      setSaveError(
+        err instanceof Error ? err.message : "Failed to save overlays",
+      );
+    }
+  }, [overlays, onSave, onClose, returnOnSave, cut.aiDraft]);
 
   const handleExport = useCallback(async () => {
     // Block export when the cut plan contained overlays that could not be placed
@@ -379,10 +526,15 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
       const { exportCut, ensureFontsReady } = await import("./export-cut");
 
       const usesSfx = overlays.some((o) => o.type === "sfx");
-      const fontsToCheck = [bodyFont.family, ...(usesSfx ? [displayFont.family] : [])];
+      const fontsToCheck = [
+        bodyFont.family,
+        ...(usesSfx ? [displayFont.family] : []),
+      ];
       const { ready, missing } = await ensureFontsReady(fontsToCheck);
       if (!ready) {
-        setExportError(`Fonts not loaded: ${missing.join(", ")}. Check your connection and retry.`);
+        setExportError(
+          `Fonts not loaded: ${missing.join(", ")}. Check your connection and retry.`,
+        );
         setExporting(false);
         return;
       }
@@ -407,7 +559,9 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
         { narration: cut.narration, dialogue: cut.dialogue },
         // Text panels have no clean image — render the final on a styled
         // background canvas sized by the panel's aspect ratio (#351).
-        cut.kind === "text" ? { background: cut.background, aspectRatio: cut.aspectRatio } : undefined,
+        cut.kind === "text"
+          ? { background: cut.background, aspectRatio: cut.aspectRatio }
+          : undefined,
       );
 
       const fd = new FormData();
@@ -432,7 +586,22 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
     } finally {
       setExporting(false);
     }
-  }, [cut, cleanAsset, overlays, storyName, plotFile, bodyFont, displayFont, bodyFontFamily, displayFontFamily, authFetch, onSave, onExported, invalidOverlayCount, acknowledgedInvalid]);
+  }, [
+    cut,
+    cleanAsset,
+    overlays,
+    storyName,
+    plotFile,
+    bodyFont,
+    displayFont,
+    bodyFontFamily,
+    displayFontFamily,
+    authFetch,
+    onSave,
+    onExported,
+    invalidOverlayCount,
+    acknowledgedInvalid,
+  ]);
 
   const selectedOverlay = overlays.find((o) => o.id === selectedId);
 
@@ -440,7 +609,10 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
   // the writer gets a readability warning before export/publish (#318). Computed
   // from the live overlay positions, so it clears as soon as bubbles are moved
   // apart. Non-blocking: overlap can be intentional, so it never blocks export.
-  const overlapPairs = useMemo(() => detectOverlappingOverlays(overlays), [overlays]);
+  const overlapPairs = useMemo(
+    () => detectOverlappingOverlays(overlays),
+    [overlays],
+  );
 
   // Re-baseline when a different cut opens without a remount (rare — the parent
   // normally unmounts the editor between cuts).
@@ -448,7 +620,9 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
   useEffect(() => {
     if (baselineCutIdRef.current !== cut.id) {
       baselineCutIdRef.current = cut.id;
-      setExportBaselineSig(overlaysSignature(overlayNormalization.overlays as Overlay[]));
+      setExportBaselineSig(
+        overlaysSignature(overlayNormalization.overlays as Overlay[]),
+      );
     }
   }, [cut.id, overlayNormalization.overlays]);
 
@@ -482,7 +656,8 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
       const outOfBounds = isOverlayOutOfBounds(o);
       let overflow = false;
       if (fontsReady && imageBounds.width > 0 && o.text) {
-        const fontFamily = o.type === "sfx" ? displayFontFamily : bodyFontFamily;
+        const fontFamily =
+          o.type === "sfx" ? displayFontFamily : bodyFontFamily;
         const w = toPixel(o.width, imageBounds.width);
         const h = toPixel(o.height, imageBounds.height);
         const layout = layoutBubbleText(
@@ -497,7 +672,14 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
       if (outOfBounds || overflow) out[o.id] = { outOfBounds, overflow };
     }
     return out;
-  }, [overlays, fontsReady, imageBounds, measureWidth, bodyFontFamily, displayFontFamily]);
+  }, [
+    overlays,
+    fontsReady,
+    imageBounds,
+    measureWidth,
+    bodyFontFamily,
+    displayFontFamily,
+  ]);
   const warningCount = Object.keys(overlayWarnings).length;
 
   const isTextPanel = cut.kind === "text";
@@ -506,7 +688,13 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
   // A text/interstitial panel (#351) is editable on a styled background canvas
   // even when empty, so it skips the "no clean image" guard that applies to a
   // would-be image cut with nothing placed yet.
-  if (!isTextPanel && isNarrationCut && overlays.length === 0 && !cut.narration && !cut.dialogue?.length) {
+  if (
+    !isTextPanel &&
+    isNarrationCut &&
+    overlays.length === 0 &&
+    !cut.narration &&
+    !cut.dialogue?.length
+  ) {
     return (
       <div className="h-full flex items-center justify-center text-sm text-muted">
         No clean image — upload one first, or add overlays for a narration cut.
@@ -515,48 +703,138 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
   }
 
   return (
-    <div className="h-full flex flex-col">
+    <div
+      className="h-full flex flex-col"
+      data-testid="focused-lettering-editor"
+    >
       {/* Toolbar */}
-      <div className="px-3 py-1.5 border-b border-border flex items-center justify-between">
-        <div className="flex items-center gap-2">
-          <span className="text-xs font-mono text-muted">Cut #{cut.id}</span>
-          <span className="text-[10px] text-muted" data-testid="overlay-count">{overlays.length} overlays</span>
-          <div className="flex items-center gap-1 ml-2">
-            <button onClick={() => addOverlay("speech")} className="px-2 py-0.5 text-[10px] border border-border rounded hover:border-accent hover:bg-accent/5" data-testid="add-speech">Speech</button>
-            <button onClick={() => addOverlay("narration")} className="px-2 py-0.5 text-[10px] border border-border rounded hover:border-accent hover:bg-accent/5" data-testid="add-narration">Narration</button>
-            <button onClick={() => addOverlay("sfx")} className="px-2 py-0.5 text-[10px] border border-border rounded hover:border-accent hover:bg-accent/5" data-testid="add-sfx">SFX</button>
+      <div className="px-4 py-3 border-b border-border bg-surface/40 flex items-center justify-between gap-3">
+        <div className="min-w-0">
+          <div className="flex items-center gap-2">
+            <span className="text-[10px] font-bold uppercase tracking-[0.16em] text-accent">
+              Focused lettering editor
+            </span>
+            <span className="text-xs font-mono text-muted">
+              {targetLabel ?? `Cut #${cut.id}`}
+            </span>
           </div>
+          <p className="mt-0.5 text-[11px] text-muted">
+            Place bubbles, captions, SFX, or between-scene card text, then save
+            back to the full cut review.
+          </p>
+          <span className="text-[10px] text-muted" data-testid="overlay-count">
+            {overlays.length} overlays
+          </span>
         </div>
-        <div className="flex items-center gap-2">
-          {exportError && <span className="text-[10px] text-error">{exportError}</span>}
-          <button onClick={handleExport} disabled={exporting} className="px-3 py-1 text-xs border border-accent text-accent rounded hover:bg-accent/5 disabled:opacity-50" data-testid="export-btn">
+        <div className="flex items-center gap-2 flex-wrap justify-end">
+          <button
+            onClick={onClose}
+            className="px-3 py-1 text-xs border border-border rounded text-muted hover:text-foreground"
+            data-testid="return-to-cut-review-btn"
+          >
+            Back to cut review
+          </button>
+          {onToggleWorkspaceVisible && (
+            <button
+              onClick={onToggleWorkspaceVisible}
+              className="px-3 py-1 text-xs border border-border rounded text-muted hover:border-accent hover:text-accent"
+              data-testid="toggle-work-area-btn"
+            >
+              {workspaceVisible ? "Hide work area" : "Show work area"}
+            </button>
+          )}
+          <div className="flex items-center gap-1 ml-2">
+            <button
+              onClick={() => addOverlay("speech")}
+              className="px-2 py-0.5 text-[10px] border border-border rounded hover:border-accent hover:bg-accent/5"
+              data-testid="add-speech"
+            >
+              Speech
+            </button>
+            <button
+              onClick={() => addOverlay("narration")}
+              className="px-2 py-0.5 text-[10px] border border-border rounded hover:border-accent hover:bg-accent/5"
+              data-testid="add-narration"
+            >
+              Narration
+            </button>
+            <button
+              onClick={() => addOverlay("sfx")}
+              className="px-2 py-0.5 text-[10px] border border-border rounded hover:border-accent hover:bg-accent/5"
+              data-testid="add-sfx"
+            >
+              SFX
+            </button>
+          </div>
+          {exportError && (
+            <span className="text-[10px] text-error">{exportError}</span>
+          )}
+          {saveError && (
+            <span className="text-[10px] text-error">{saveError}</span>
+          )}
+          <button
+            onClick={handleExport}
+            disabled={exporting}
+            className="px-3 py-1 text-xs border border-accent text-accent rounded hover:bg-accent/5 disabled:opacity-50"
+            data-testid="export-btn"
+          >
             {exporting ? "Exporting..." : "Export"}
           </button>
-          <button onClick={handleSave} className="px-3 py-1 text-xs bg-accent text-white rounded hover:bg-accent-dim">Save</button>
-          <button onClick={onClose} className="px-3 py-1 text-xs text-muted hover:text-foreground border border-border rounded">Close</button>
+          <button
+            onClick={() => {
+              void handleSave();
+            }}
+            className="px-3 py-1 text-xs bg-accent text-white rounded hover:bg-accent-dim"
+            data-testid="save-lettering-btn"
+          >
+            Save
+          </button>
+          <button
+            onClick={onClose}
+            className="px-3 py-1 text-xs text-muted hover:text-foreground border border-border rounded"
+            data-testid="cancel-lettering-btn"
+          >
+            Cancel
+          </button>
         </div>
       </div>
 
       {invalidOverlayCount > 0 && !acknowledgedInvalid ? (
-        <div className="px-3 py-1 border-b border-border bg-error/10 text-[10px] text-error flex items-center gap-2 flex-wrap" data-testid="overlay-repair-note">
+        <div
+          className="px-3 py-1 border-b border-border bg-error/10 text-[10px] text-error flex items-center gap-2 flex-wrap"
+          data-testid="overlay-repair-note"
+        >
           <span>
-            {invalidOverlayCount} overlay{invalidOverlayCount === 1 ? "" : "s"} from the cut plan {invalidOverlayCount === 1 ? "has" : "have"} no usable position and cannot be exported. Re-place {invalidOverlayCount === 1 ? "it" : "them"}, or
+            {invalidOverlayCount} overlay{invalidOverlayCount === 1 ? "" : "s"}{" "}
+            from the cut plan {invalidOverlayCount === 1 ? "has" : "have"} no
+            usable position and cannot be exported. Re-place{" "}
+            {invalidOverlayCount === 1 ? "it" : "them"}, or
           </span>
           <button
             onClick={() => setAcknowledgedInvalid(true)}
             data-testid="discard-invalid-overlays"
             className="px-1.5 py-0.5 border border-error/40 rounded hover:bg-error/10"
           >
-            discard {invalidOverlayCount} unplaceable overlay{invalidOverlayCount === 1 ? "" : "s"}
+            discard {invalidOverlayCount} unplaceable overlay
+            {invalidOverlayCount === 1 ? "" : "s"}
           </button>
         </div>
       ) : invalidOverlayCount > 0 ? (
-        <div className="px-3 py-1 border-b border-border bg-amber-500/10 text-[10px] text-amber-700" data-testid="overlay-repair-note">
-          Discarded {invalidOverlayCount} unplaceable overlay{invalidOverlayCount === 1 ? "" : "s"} — the export will not include {invalidOverlayCount === 1 ? "it" : "them"}.
+        <div
+          className="px-3 py-1 border-b border-border bg-amber-500/10 text-[10px] text-amber-700"
+          data-testid="overlay-repair-note"
+        >
+          Discarded {invalidOverlayCount} unplaceable overlay
+          {invalidOverlayCount === 1 ? "" : "s"} — the export will not include{" "}
+          {invalidOverlayCount === 1 ? "it" : "them"}.
         </div>
       ) : autoPlacedOverlays ? (
-        <div className="px-3 py-1 border-b border-border bg-amber-500/10 text-[10px] text-amber-700" data-testid="overlay-repair-note">
-          Auto-placed overlays from the cut plan — review their positions before exporting.
+        <div
+          className="px-3 py-1 border-b border-border bg-amber-500/10 text-[10px] text-amber-700"
+          data-testid="overlay-repair-note"
+        >
+          Auto-placed overlays from the cut plan — review their positions before
+          exporting.
         </div>
       ) : null}
 
@@ -565,9 +843,14 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
           className="px-3 py-1 border-b border-border bg-amber-500/10 text-[10px] text-amber-700"
           data-testid="overlay-overlap-warning"
         >
-          Cut #{cut.id}: {overlapPairs.length} bubble {overlapPairs.length === 1 ? "pair overlaps" : "pairs overlap"} and may be hard to read —{" "}
+          Cut #{cut.id}: {overlapPairs.length} bubble{" "}
+          {overlapPairs.length === 1 ? "pair overlaps" : "pairs overlap"} and
+          may be hard to read —{" "}
           {overlapPairs
-            .map((p) => `#${p.indexA + 1} ${overlapLabel(overlays[p.indexA])} ↔ #${p.indexB + 1} ${overlapLabel(overlays[p.indexB])}`)
+            .map(
+              (p) =>
+                `#${p.indexA + 1} ${overlapLabel(overlays[p.indexA])} ↔ #${p.indexB + 1} ${overlapLabel(overlays[p.indexB])}`,
+            )
             .join("; ")}
           . Move them apart, or export as-is if the overlap is intended.
         </div>
@@ -579,13 +862,19 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
         className="px-3 py-1 border-b border-border flex items-center gap-3 flex-wrap text-[10px] text-muted"
         data-testid="lettering-checklist"
       >
-        {([
-          ["clean-image", "Clean image", checklist.hasCleanImage],
-          ["script-text", "Script text", checklist.hasScriptText],
-          ["bubbles", `Bubbles placed${checklist.bubblesPlaced ? ` (${checklist.bubblesPlaced})` : ""}`, checklist.bubblesPlaced > 0],
-          ["exported", "Final exported", checklist.exported],
-          ["uploaded", "Uploaded", checklist.uploaded],
-        ] as [string, string, boolean][]).map(([key, label, done]) => (
+        {(
+          [
+            ["clean-image", "Clean image", checklist.hasCleanImage],
+            ["script-text", "Script text", checklist.hasScriptText],
+            [
+              "bubbles",
+              `Bubbles placed${checklist.bubblesPlaced ? ` (${checklist.bubblesPlaced})` : ""}`,
+              checklist.bubblesPlaced > 0,
+            ],
+            ["exported", "Final exported", checklist.exported],
+            ["uploaded", "Uploaded", checklist.uploaded],
+          ] as [string, string, boolean][]
+        ).map(([key, label, done]) => (
           <span
             key={key}
             data-testid={`lettering-check-${key}`}
@@ -606,7 +895,8 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
           className="px-3 py-1 border-b border-border bg-amber-500/10 text-[10px] text-amber-700"
           data-testid="lettering-stale-export-warning"
         >
-          Bubbles changed since the last export — re-export this cut and upload the new final image before publishing.
+          Bubbles changed since the last export — re-export this cut and upload
+          the new final image before publishing.
         </div>
       )}
 
@@ -617,11 +907,15 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
           className="px-3 py-1 border-b border-border bg-amber-500/10 text-[10px] text-amber-700"
           data-testid="lettering-export-warning"
         >
-          {warningCount} bubble{warningCount === 1 ? "" : "s"} may not export cleanly:{" "}
+          {warningCount} bubble{warningCount === 1 ? "" : "s"} may not export
+          cleanly:{" "}
           {Object.entries(overlayWarnings)
             .map(([id, w]) => {
               const idx = overlays.findIndex((o) => o.id === id);
-              const problems = [w.outOfBounds ? "outside image" : null, w.overflow ? "text overflow" : null]
+              const problems = [
+                w.outOfBounds ? "outside image" : null,
+                w.overflow ? "text overflow" : null,
+              ]
                 .filter(Boolean)
                 .join(", ");
               return `#${idx + 1} ${overlapLabel(overlays[idx])} (${problems})`;
@@ -635,16 +929,22 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
       <div className="flex-1 min-h-0 flex">
         <div
           ref={containerRef}
-          className="flex-1 min-w-0 relative overflow-hidden"
+          className="flex-1 min-w-0 relative overflow-hidden bg-[#f8f5ef]"
           onClick={handleBackgroundClick}
           data-testid="editor-surface"
         >
           {cut.cleanImagePath && cleanAsset.error ? (
-            <div className="w-full h-full flex items-center justify-center text-muted text-xs" data-testid="clean-image-error">
+            <div
+              className="w-full h-full flex items-center justify-center text-muted text-xs"
+              data-testid="clean-image-error"
+            >
               Clean image not available
             </div>
           ) : cut.cleanImagePath && !cleanAsset.url ? (
-            <div className="w-full h-full flex items-center justify-center text-muted text-xs" data-testid="clean-image-loading">
+            <div
+              className="w-full h-full flex items-center justify-center text-muted text-xs"
+              data-testid="clean-image-loading"
+            >
               Loading clean image…
             </div>
           ) : cut.cleanImagePath ? (
@@ -681,7 +981,12 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
                 if (el && imageBounds.width === 0) {
                   const rect = el.getBoundingClientRect();
                   if (rect.width > 0) {
-                    setImageBounds({ x: 0, y: 0, width: rect.width, height: rect.height });
+                    setImageBounds({
+                      x: 0,
+                      y: 0,
+                      width: rect.width,
+                      height: rect.height,
+                    });
                   }
                 }
               }}
@@ -698,15 +1003,22 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
               Tailless speech (no tailAnchor, or a tip inside the bubble) traces
               a plain rounded rectangle. Tail-anchor edits update the path live. */}
           {imageBounds.width > 0 && (
-            <svg className="absolute inset-0 w-full h-full pointer-events-none" data-testid="balloon-layer">
+            <svg
+              className="absolute inset-0 w-full h-full pointer-events-none"
+              data-testid="balloon-layer"
+            >
               {overlays.map((overlay) => {
                 if (overlay.type !== "speech") return null;
-                const ox = imageBounds.x + toPixel(overlay.x, imageBounds.width);
-                const oy = imageBounds.y + toPixel(overlay.y, imageBounds.height);
+                const ox =
+                  imageBounds.x + toPixel(overlay.x, imageBounds.width);
+                const oy =
+                  imageBounds.y + toPixel(overlay.y, imageBounds.height);
                 const ow = toPixel(overlay.width, imageBounds.width);
                 const oh = toPixel(overlay.height, imageBounds.height);
                 const radius = balloonRadiusForOverlay(overlay, ow, oh);
-                const tail = overlay.tailAnchor ? speechTailPoints(ox, oy, ow, oh, overlay.tailAnchor, radius) : null;
+                const tail = overlay.tailAnchor
+                  ? speechTailPoints(ox, oy, ow, oh, overlay.tailAnchor, radius)
+                  : null;
                 // Strong, clean near-black outline scaled to the preview size so
                 // the bubble reads as a webtoon balloon (matching the export's
                 // proportional stroke), not a faint UI box (#363).
@@ -726,116 +1038,164 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
             </svg>
           )}
 
-          {imageBounds.width > 0 && overlays.map((overlay) => {
-            const left = imageBounds.x + toPixel(overlay.x, imageBounds.width);
-            const top = imageBounds.y + toPixel(overlay.y, imageBounds.height);
-            const width = toPixel(overlay.width, imageBounds.width);
-            const height = toPixel(overlay.height, imageBounds.height);
-            const isSelected = overlay.id === selectedId;
-            // Speech bubbles draw no body border here — the integrated balloon
-            // <path> in the layer below is their outline, so a box border would
-            // re-introduce the body/tail seam (#327). Their selection cue is the
-            // path's accent stroke (plus the resize handle). Narration/SFX keep
-            // their bordered box + selection ring as before.
-            const isSpeech = overlay.type === "speech";
-            // Narration reads as an intentional parchment caption card (rounded,
-            // filled), mirroring the export, instead of an empty bordered box (#363).
-            const isNarration = overlay.type === "narration";
-            const warned = !!overlayWarnings[overlay.id];
-
-            return (
-              <div
-                key={overlay.id}
-                data-testid={`overlay-${overlay.id}`}
-                data-warning={warned ? "true" : "false"}
-                onClick={(e) => handleOverlayClick(e, overlay.id)}
-                onMouseDown={(e) => handleMouseDown(e, overlay.id, "move")}
-                className={`absolute rounded cursor-move select-none ${
-                  isSpeech ? "" : `border-2 ${TYPE_BORDER[overlay.type]}`
-                } ${isNarration ? "bg-[#f4efe6]/85 rounded-md" : ""} ${
-                  isSelected && !isSpeech ? "ring-2 ring-accent" : ""
-                } ${warned ? "ring-2 ring-amber-500" : ""}`}
-                style={{ left, top, width, height }}
-              >
-                {(() => {
-                  const fontFamily = overlay.type === "sfx" ? displayFontFamily : bodyFontFamily;
-                  if (!overlay.text) {
-                    return (
-                      <span className="text-[9px] px-1 text-muted truncate block pointer-events-none" style={{ fontFamily }}>
-                        {TYPE_LABEL[overlay.type]}
-                      </span>
+          {imageBounds.width > 0 &&
+            overlays.map((overlay) => {
+              const left =
+                imageBounds.x + toPixel(overlay.x, imageBounds.width);
+              const top =
+                imageBounds.y + toPixel(overlay.y, imageBounds.height);
+              const width = toPixel(overlay.width, imageBounds.width);
+              const height = toPixel(overlay.height, imageBounds.height);
+              const isSelected = overlay.id === selectedId;
+              // Speech bubbles draw no body border here — the integrated balloon
+              // <path> in the layer below is their outline, so a box border would
+              // re-introduce the body/tail seam (#327). Their selection cue is the
+              // path's accent stroke (plus the resize handle). Narration/SFX keep
+              // their bordered box + selection ring as before.
+              const isSpeech = overlay.type === "speech";
+              // Narration reads as an intentional parchment caption card (rounded,
+              // filled), mirroring the export, instead of an empty bordered box (#363).
+              const isNarration = overlay.type === "narration";
+              const warned = !!overlayWarnings[overlay.id];
+
+              return (
+                <div
+                  key={overlay.id}
+                  data-testid={`overlay-${overlay.id}`}
+                  data-warning={warned ? "true" : "false"}
+                  onClick={(e) => handleOverlayClick(e, overlay.id)}
+                  onMouseDown={(e) => handleMouseDown(e, overlay.id, "move")}
+                  className={`absolute rounded cursor-move select-none ${
+                    isSpeech ? "" : `border-2 ${TYPE_BORDER[overlay.type]}`
+                  } ${isNarration ? "bg-[#f4efe6]/85 rounded-md" : ""} ${
+                    isSelected && !isSpeech ? "ring-2 ring-accent" : ""
+                  } ${warned ? "ring-2 ring-amber-500" : ""}`}
+                  style={{ left, top, width, height }}
+                >
+                  {(() => {
+                    const fontFamily =
+                      overlay.type === "sfx"
+                        ? displayFontFamily
+                        : bodyFontFamily;
+                    if (!overlay.text) {
+                      return (
+                        <span
+                          className="text-[9px] px-1 text-muted truncate block pointer-events-none"
+                          style={{ fontFamily }}
+                        >
+                          {TYPE_LABEL[overlay.type]}
+                        </span>
+                      );
+                    }
+                    const hasSpeaker =
+                      overlay.type !== "sfx" && !!overlay.speaker;
+                    if (!fontsReady) {
+                      // Until the web font's metrics are available, don't freeze
+                      // canvas-measured line breaks from fallback metrics (they
+                      // would diverge from export). Show a CSS-wrapped transient;
+                      // the exact layout computes once fonts are ready (#310, re1).
+                      return (
+                        <div
+                          className="absolute inset-0 flex items-center justify-center px-1 overflow-hidden pointer-events-none text-center break-words"
+                          style={{
+                            fontFamily,
+                            fontSize: Math.max(9, Math.min(height * 0.05, 16)),
+                            fontWeight: overlay.textStyle?.fontWeight ?? 400,
+                          }}
+                          data-testid={`overlay-text-${overlay.id}`}
+                          data-fonts-ready="false"
+                        >
+                          {hasSpeaker
+                            ? `${overlay.speaker}: ${overlay.text}`
+                            : overlay.text}
+                        </div>
+                      );
+                    }
+                    const layout = layoutBubbleText(
+                      measureWidth(fontFamily),
+                      overlay.text,
+                      width,
+                      height,
+                      bubbleLayoutOptionsForOverlay(
+                        overlay,
+                        imageBounds.height,
+                        width,
+                        height,
+                      ),
                     );
-                  }
-                  const hasSpeaker = overlay.type !== "sfx" && !!overlay.speaker;
-                  if (!fontsReady) {
-                    // Until the web font's metrics are available, don't freeze
-                    // canvas-measured line breaks from fallback metrics (they
-                    // would diverge from export). Show a CSS-wrapped transient;
-                    // the exact layout computes once fonts are ready (#310, re1).
                     return (
                       <div
-                        className="absolute inset-0 flex items-center justify-center px-1 overflow-hidden pointer-events-none text-center break-words"
-                        style={{
-                          fontFamily,
-                          fontSize: Math.max(9, Math.min(height * 0.05, 16)),
-                          fontWeight: overlay.textStyle?.fontWeight ?? 400,
-                        }}
+                        className="absolute inset-0 flex flex-col items-center justify-center px-1 overflow-hidden pointer-events-none text-center"
+                        style={{ fontFamily }}
                         data-testid={`overlay-text-${overlay.id}`}
-                        data-fonts-ready="false"
+                        data-fonts-ready="true"
                       >
-                        {hasSpeaker ? `${overlay.speaker}: ${overlay.text}` : overlay.text}
+                        {hasSpeaker && (
+                          <span
+                            className="font-bold text-[#3a3a3a] block"
+                            style={{
+                              fontSize: layout.speakerFontSize,
+                              lineHeight: 1.2,
+                            }}
+                          >
+                            {overlay.speaker}
+                          </span>
+                        )}
+                        <span
+                          className="text-[#1a1a1a]"
+                          style={{
+                            fontSize: layout.fontSize,
+                            lineHeight: `${layout.lineHeight}px`,
+                            fontWeight: overlay.textStyle?.fontWeight ?? 400,
+                          }}
+                        >
+                          {layout.lines.map((line, i) => (
+                            <span key={i} className="block">
+                              {line}
+                            </span>
+                          ))}
+                        </span>
                       </div>
                     );
-                  }
-                  const layout = layoutBubbleText(
-                    measureWidth(fontFamily),
-                    overlay.text,
-                    width,
-                    height,
-                    bubbleLayoutOptionsForOverlay(overlay, imageBounds.height, width, height),
-                  );
-                  return (
+                  })()}
+                  {isSelected && (
                     <div
-                      className="absolute inset-0 flex flex-col items-center justify-center px-1 overflow-hidden pointer-events-none text-center"
-                      style={{ fontFamily }}
-                      data-testid={`overlay-text-${overlay.id}`}
-                      data-fonts-ready="true"
-                    >
-                      {hasSpeaker && (
-                        <span className="font-bold text-[#3a3a3a] block" style={{ fontSize: layout.speakerFontSize, lineHeight: 1.2 }}>
-                          {overlay.speaker}
-                        </span>
-                      )}
-                      <span
-                        className="text-[#1a1a1a]"
-                        style={{ fontSize: layout.fontSize, lineHeight: `${layout.lineHeight}px`, fontWeight: overlay.textStyle?.fontWeight ?? 400 }}
-                      >
-                        {layout.lines.map((line, i) => (
-                          <span key={i} className="block">{line}</span>
-                        ))}
-                      </span>
-                    </div>
-                  );
-                })()}
-                {isSelected && (
-                  <div
-                    onMouseDown={(e) => { e.stopPropagation(); handleMouseDown(e, overlay.id, "resize"); }}
-                    className="absolute bottom-0 right-0 w-2 h-2 bg-accent cursor-se-resize"
-                    data-testid={`resize-${overlay.id}`}
-                  />
-                )}
-              </div>
-            );
-          })}
+                      onMouseDown={(e) => {
+                        e.stopPropagation();
+                        handleMouseDown(e, overlay.id, "resize");
+                      }}
+                      className="absolute bottom-0 right-0 w-2 h-2 bg-accent cursor-se-resize"
+                      data-testid={`resize-${overlay.id}`}
+                    />
+                  )}
+                </div>
+              );
+            })}
         </div>
 
         {/* Inspector panel */}
-        <div className="w-52 border-l border-border p-3 overflow-y-auto flex-shrink-0">
+        <div className="w-64 border-l border-border p-3 overflow-y-auto flex-shrink-0">
+          {cut.aiDraft?.status === "generated" && (
+            <div
+              className="mb-3 rounded border border-accent/30 bg-accent/5 p-2 space-y-1"
+              data-testid="ai-draft-current-target"
+            >
+              <p className="text-[10px] font-bold uppercase tracking-[0.14em] text-accent">
+                AI draft ready
+              </p>
+              <p className="text-[11px] text-muted">
+                These first-pass overlays came from the cut script. Review and
+                tune them here before exporting the final panel.
+              </p>
+            </div>
+          )}
           {/* Insert-from-script (#336): drop the cut's planned dialogue/narration/
               SFX straight into a prefilled overlay — no copy/paste out of JSON. */}
           {scriptLines.length > 0 && (
             <div className="mb-3 space-y-1.5" data-testid="script-insert-panel">
-              <span className="text-[10px] font-medium text-muted">From script</span>
+              <span className="text-[10px] font-medium text-muted">
+                From script
+              </span>
               <div className="flex flex-col gap-1">
                 {scriptLines.map((line) => (
                   <button
@@ -845,10 +1205,14 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
                     title={`Add ${line.type} overlay with this text`}
                     className="text-left px-2 py-1 text-[10px] border border-border rounded hover:border-accent hover:bg-accent/5"
                   >
-                    <span className="font-medium text-accent">+ {TYPE_LABEL[line.type]}</span>{" "}
+                    <span className="font-medium text-accent">
+                      + {TYPE_LABEL[line.type]}
+                    </span>{" "}
                     <span className="text-muted">
                       {line.speaker ? `${line.speaker}: ` : ""}
-                      {line.text.length > 32 ? `${line.text.slice(0, 32)}…` : line.text}
+                      {line.text.length > 32
+                        ? `${line.text.slice(0, 32)}…`
+                        : line.text}
                     </span>
                   </button>
                 ))}
@@ -857,14 +1221,22 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
           )}
           {selectedOverlay ? (
             <div className="space-y-3">
-              <p className="text-xs font-medium text-foreground">{TYPE_LABEL[selectedOverlay.type]}</p>
+              <p className="text-xs font-medium text-foreground">
+                {TYPE_LABEL[selectedOverlay.type]}
+              </p>
 
               {selectedOverlay.speaker !== undefined && (
                 <label className="block space-y-1">
-                  <span className="text-[10px] font-medium text-muted">Speaker</span>
+                  <span className="text-[10px] font-medium text-muted">
+                    Speaker
+                  </span>
                   <input
                     value={selectedOverlay.speaker || ""}
-                    onChange={(e) => updateOverlay(selectedOverlay.id, { speaker: e.target.value })}
+                    onChange={(e) =>
+                      updateOverlay(selectedOverlay.id, {
+                        speaker: e.target.value,
+                      })
+                    }
                     className="w-full px-2 py-1 text-xs border border-border rounded bg-transparent focus:border-accent focus:outline-none"
                     placeholder="Character name"
                     data-testid="inspector-speaker"
@@ -876,7 +1248,9 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
                 <span className="text-[10px] font-medium text-muted">Text</span>
                 <textarea
                   value={selectedOverlay.text}
-                  onChange={(e) => updateOverlay(selectedOverlay.id, { text: e.target.value })}
+                  onChange={(e) =>
+                    updateOverlay(selectedOverlay.id, { text: e.target.value })
+                  }
                   rows={3}
                   className="w-full px-2 py-1 text-xs border border-border rounded bg-transparent resize-none focus:border-accent focus:outline-none"
                   placeholder="Overlay text"
@@ -887,7 +1261,9 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
               {/* One-click resize so a long line that overflows can be fitted
                   without hand-dragging the box (#452). */}
               <button
-                onClick={() => updateOverlay(selectedOverlay.id, fittedSize(selectedOverlay))}
+                onClick={() =>
+                  updateOverlay(selectedOverlay.id, fittedSize(selectedOverlay))
+                }
                 data-testid="inspector-fit-text"
                 className="w-full px-2 py-1 text-[11px] border border-border rounded hover:border-accent hover:text-accent"
                 title="Resize this overlay so its text fits without overflowing"
@@ -895,13 +1271,22 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
                 Fit box to text
               </button>
 
-              <div className="space-y-1.5 rounded border border-border/70 p-2" data-testid="inspector-typography">
+              <div
+                className="space-y-1.5 rounded border border-border/70 p-2"
+                data-testid="inspector-typography"
+              >
                 <div className="flex items-center justify-between gap-2">
-                  <span className="text-[10px] font-medium text-muted">Typography</span>
+                  <span className="text-[10px] font-medium text-muted">
+                    Typography
+                  </span>
                   {selectedOverlay.textStyle?.mode === "manual" ? (
                     <button
                       type="button"
-                      onClick={() => updateOverlay(selectedOverlay.id, { textStyle: undefined })}
+                      onClick={() =>
+                        updateOverlay(selectedOverlay.id, {
+                          textStyle: undefined,
+                        })
+                      }
                       className="px-1.5 py-0.5 text-[10px] border border-border rounded hover:border-accent hover:bg-accent/5"
                       data-testid="inspector-text-auto"
                     >
@@ -921,20 +1306,32 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
                 {selectedOverlay.textStyle?.mode === "manual" ? (
                   <div className="space-y-1.5">
                     <label className="block space-y-1">
-                      <span className="text-[10px] text-muted">Font size (% panel height)</span>
+                      <span className="text-[10px] text-muted">
+                        Font size (% panel height)
+                      </span>
                       <input
                         type="number"
                         step="0.1"
                         min="1.5"
                         max="12"
-                        value={(((selectedOverlay.textStyle.fontScale ?? 0.032) * 100)).toFixed(1)}
-                        onChange={(e) => updateOverlay(selectedOverlay.id, {
-                          textStyle: {
-                            ...selectedOverlay.textStyle,
-                            mode: "manual",
-                            fontScale: Math.max(0.015, Math.min(0.12, (parseFloat(e.target.value) || 3.2) / 100)),
-                          },
-                        })}
+                        value={(
+                          (selectedOverlay.textStyle.fontScale ?? 0.032) * 100
+                        ).toFixed(1)}
+                        onChange={(e) =>
+                          updateOverlay(selectedOverlay.id, {
+                            textStyle: {
+                              ...selectedOverlay.textStyle,
+                              mode: "manual",
+                              fontScale: Math.max(
+                                0.015,
+                                Math.min(
+                                  0.12,
+                                  (parseFloat(e.target.value) || 3.2) / 100,
+                                ),
+                              ),
+                            },
+                          })
+                        }
                         className="w-full px-2 py-1 text-xs border border-border rounded bg-transparent focus:border-accent focus:outline-none"
                         data-testid="inspector-font-scale"
                       />
@@ -942,14 +1339,18 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
                     <label className="block space-y-1">
                       <span className="text-[10px] text-muted">Weight</span>
                       <select
-                        value={String(selectedOverlay.textStyle.fontWeight ?? 400)}
-                        onChange={(e) => updateOverlay(selectedOverlay.id, {
-                          textStyle: {
-                            ...selectedOverlay.textStyle,
-                            mode: "manual",
-                            fontWeight: e.target.value === "700" ? 700 : 400,
-                          },
-                        })}
+                        value={String(
+                          selectedOverlay.textStyle.fontWeight ?? 400,
+                        )}
+                        onChange={(e) =>
+                          updateOverlay(selectedOverlay.id, {
+                            textStyle: {
+                              ...selectedOverlay.textStyle,
+                              mode: "manual",
+                              fontWeight: e.target.value === "700" ? 700 : 400,
+                            },
+                          })
+                        }
                         className="w-full px-2 py-1 text-xs border border-border rounded bg-transparent focus:border-accent focus:outline-none"
                         data-testid="inspector-font-weight"
                       >
@@ -958,40 +1359,61 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
                       </select>
                     </label>
                     <label className="block space-y-1">
-                      <span className="text-[10px] text-muted">Line height</span>
+                      <span className="text-[10px] text-muted">
+                        Line height
+                      </span>
                       <input
                         type="number"
                         step="0.05"
                         min="0.9"
                         max="2"
-                        value={(selectedOverlay.textStyle.lineHeightFactor ?? 1.2).toFixed(2)}
-                        onChange={(e) => updateOverlay(selectedOverlay.id, {
-                          textStyle: {
-                            ...selectedOverlay.textStyle,
-                            mode: "manual",
-                            lineHeightFactor: Math.max(0.9, Math.min(2, parseFloat(e.target.value) || 1.2)),
-                          },
-                        })}
+                        value={(
+                          selectedOverlay.textStyle.lineHeightFactor ?? 1.2
+                        ).toFixed(2)}
+                        onChange={(e) =>
+                          updateOverlay(selectedOverlay.id, {
+                            textStyle: {
+                              ...selectedOverlay.textStyle,
+                              mode: "manual",
+                              lineHeightFactor: Math.max(
+                                0.9,
+                                Math.min(2, parseFloat(e.target.value) || 1.2),
+                              ),
+                            },
+                          })
+                        }
                         className="w-full px-2 py-1 text-xs border border-border rounded bg-transparent focus:border-accent focus:outline-none"
                         data-testid="inspector-line-height"
                       />
                     </label>
                     {selectedOverlay.type !== "sfx" && (
                       <label className="block space-y-1">
-                        <span className="text-[10px] text-muted">Speaker scale</span>
+                        <span className="text-[10px] text-muted">
+                          Speaker scale
+                        </span>
                         <input
                           type="number"
                           step="0.05"
                           min="0.5"
                           max="1.5"
-                          value={(selectedOverlay.textStyle.speakerScale ?? 0.8).toFixed(2)}
-                          onChange={(e) => updateOverlay(selectedOverlay.id, {
-                            textStyle: {
-                              ...selectedOverlay.textStyle,
-                              mode: "manual",
-                              speakerScale: Math.max(0.5, Math.min(1.5, parseFloat(e.target.value) || 0.8)),
-                            },
-                          })}
+                          value={(
+                            selectedOverlay.textStyle.speakerScale ?? 0.8
+                          ).toFixed(2)}
+                          onChange={(e) =>
+                            updateOverlay(selectedOverlay.id, {
+                              textStyle: {
+                                ...selectedOverlay.textStyle,
+                                mode: "manual",
+                                speakerScale: Math.max(
+                                  0.5,
+                                  Math.min(
+                                    1.5,
+                                    parseFloat(e.target.value) || 0.8,
+                                  ),
+                                ),
+                              },
+                            })
+                          }
                           className="w-full px-2 py-1 text-xs border border-border rounded bg-transparent focus:border-accent focus:outline-none"
                           data-testid="inspector-speaker-scale"
                         />
@@ -999,109 +1421,176 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
                     )}
                   </div>
                 ) : (
-                  <p className="text-[10px] text-muted">Auto-fit stays on by default and resizes text to the box.</p>
+                  <p className="text-[10px] text-muted">
+                    Auto-fit stays on by default and resizes text to the box.
+                  </p>
                 )}
               </div>
 
-              {selectedOverlay.type === "speech" && (() => {
-                const tail = selectedOverlay.tailAnchor || { x: 0.5, y: 1.2 };
-                return (
-                  <div className="space-y-1">
-                    <span className="text-[10px] font-medium text-muted">Tail anchor</span>
-                    <div className="flex flex-wrap gap-1" data-testid="inspector-tail-presets">
-                      {TAIL_PRESETS.map((preset) => (
-                        <button
-                          key={preset.key}
-                          type="button"
-                          onClick={() => updateOverlay(selectedOverlay.id, { tailAnchor: preset.anchor })}
-                          className="px-1.5 py-0.5 text-[10px] border border-border rounded hover:border-accent hover:bg-accent/5"
-                          data-testid={`inspector-tail-${preset.key}`}
-                        >
-                          {preset.label}
-                        </button>
-                      ))}
-                    </div>
-                    <div className="flex gap-2">
-                      <label className="flex items-center gap-1 text-[10px] font-mono text-muted">
-                        x
-                        <input
-                          type="number"
-                          step="0.1"
-                          value={tail.x}
-                          onChange={(e) => updateOverlay(selectedOverlay.id, { tailAnchor: { ...tail, x: parseFloat(e.target.value) || 0 } })}
-                          className="w-14 px-1 py-0.5 text-[10px] border border-border rounded bg-transparent focus:border-accent focus:outline-none"
-                          data-testid="inspector-tail-x"
-                        />
-                      </label>
-                      <label className="flex items-center gap-1 text-[10px] font-mono text-muted">
-                        y
-                        <input
-                          type="number"
-                          step="0.1"
-                          value={tail.y}
-                          onChange={(e) => updateOverlay(selectedOverlay.id, { tailAnchor: { ...tail, y: parseFloat(e.target.value) || 0 } })}
-                          className="w-14 px-1 py-0.5 text-[10px] border border-border rounded bg-transparent focus:border-accent focus:outline-none"
-                          data-testid="inspector-tail-y"
-                        />
-                      </label>
+              {selectedOverlay.type === "speech" &&
+                (() => {
+                  const tail = selectedOverlay.tailAnchor || { x: 0.5, y: 1.2 };
+                  return (
+                    <div className="space-y-1">
+                      <span className="text-[10px] font-medium text-muted">
+                        Tail anchor
+                      </span>
+                      <div
+                        className="flex flex-wrap gap-1"
+                        data-testid="inspector-tail-presets"
+                      >
+                        {TAIL_PRESETS.map((preset) => (
+                          <button
+                            key={preset.key}
+                            type="button"
+                            onClick={() =>
+                              updateOverlay(selectedOverlay.id, {
+                                tailAnchor: preset.anchor,
+                              })
+                            }
+                            className="px-1.5 py-0.5 text-[10px] border border-border rounded hover:border-accent hover:bg-accent/5"
+                            data-testid={`inspector-tail-${preset.key}`}
+                          >
+                            {preset.label}
+                          </button>
+                        ))}
+                      </div>
+                      <div className="flex gap-2">
+                        <label className="flex items-center gap-1 text-[10px] font-mono text-muted">
+                          x
+                          <input
+                            type="number"
+                            step="0.1"
+                            value={tail.x}
+                            onChange={(e) =>
+                              updateOverlay(selectedOverlay.id, {
+                                tailAnchor: {
+                                  ...tail,
+                                  x: parseFloat(e.target.value) || 0,
+                                },
+                              })
+                            }
+                            className="w-14 px-1 py-0.5 text-[10px] border border-border rounded bg-transparent focus:border-accent focus:outline-none"
+                            data-testid="inspector-tail-x"
+                          />
+                        </label>
+                        <label className="flex items-center gap-1 text-[10px] font-mono text-muted">
+                          y
+                          <input
+                            type="number"
+                            step="0.1"
+                            value={tail.y}
+                            onChange={(e) =>
+                              updateOverlay(selectedOverlay.id, {
+                                tailAnchor: {
+                                  ...tail,
+                                  y: parseFloat(e.target.value) || 0,
+                                },
+                              })
+                            }
+                            className="w-14 px-1 py-0.5 text-[10px] border border-border rounded bg-transparent focus:border-accent focus:outline-none"
+                            data-testid="inspector-tail-y"
+                          />
+                        </label>
+                      </div>
                     </div>
-                  </div>
-                );
-              })()}
+                  );
+                })()}
 
               {selectedOverlay.type !== "sfx" && (
-                <div className="space-y-1.5 rounded border border-border/70 p-2" data-testid="inspector-bubble-style">
-                  <span className="text-[10px] font-medium text-muted">Bubble controls</span>
+                <div
+                  className="space-y-1.5 rounded border border-border/70 p-2"
+                  data-testid="inspector-bubble-style"
+                >
+                  <span className="text-[10px] font-medium text-muted">
+                    Bubble controls
+                  </span>
                   <label className="block space-y-1">
-                    <span className="text-[10px] text-muted">Padding X (% width)</span>
+                    <span className="text-[10px] text-muted">
+                      Padding X (% width)
+                    </span>
                     <input
                       type="number"
                       step="1"
                       min="0"
                       max="25"
-                      value={(((selectedOverlay.bubbleStyle?.paddingX ?? 0.06) * 100)).toFixed(0)}
-                      onChange={(e) => updateOverlay(selectedOverlay.id, {
-                        bubbleStyle: {
-                          ...selectedOverlay.bubbleStyle,
-                          paddingX: Math.max(0, Math.min(0.25, (parseFloat(e.target.value) || 6) / 100)),
-                        },
-                      })}
+                      value={(
+                        (selectedOverlay.bubbleStyle?.paddingX ?? 0.06) * 100
+                      ).toFixed(0)}
+                      onChange={(e) =>
+                        updateOverlay(selectedOverlay.id, {
+                          bubbleStyle: {
+                            ...selectedOverlay.bubbleStyle,
+                            paddingX: Math.max(
+                              0,
+                              Math.min(
+                                0.25,
+                                (parseFloat(e.target.value) || 6) / 100,
+                              ),
+                            ),
+                          },
+                        })
+                      }
                       className="w-full px-2 py-1 text-xs border border-border rounded bg-transparent focus:border-accent focus:outline-none"
                       data-testid="inspector-padding-x"
                     />
                   </label>
                   <label className="block space-y-1">
-                    <span className="text-[10px] text-muted">Padding Y (% height)</span>
+                    <span className="text-[10px] text-muted">
+                      Padding Y (% height)
+                    </span>
                     <input
                       type="number"
                       step="1"
                       min="0"
                       max="25"
-                      value={(((selectedOverlay.bubbleStyle?.paddingY ?? 0.08) * 100)).toFixed(0)}
-                      onChange={(e) => updateOverlay(selectedOverlay.id, {
-                        bubbleStyle: {
-                          ...selectedOverlay.bubbleStyle,
-                          paddingY: Math.max(0, Math.min(0.25, (parseFloat(e.target.value) || 8) / 100)),
-                        },
-                      })}
+                      value={(
+                        (selectedOverlay.bubbleStyle?.paddingY ?? 0.08) * 100
+                      ).toFixed(0)}
+                      onChange={(e) =>
+                        updateOverlay(selectedOverlay.id, {
+                          bubbleStyle: {
+                            ...selectedOverlay.bubbleStyle,
+                            paddingY: Math.max(
+                              0,
+                              Math.min(
+                                0.25,
+                                (parseFloat(e.target.value) || 8) / 100,
+                              ),
+                            ),
+                          },
+                        })
+                      }
                       className="w-full px-2 py-1 text-xs border border-border rounded bg-transparent focus:border-accent focus:outline-none"
                       data-testid="inspector-padding-y"
                     />
                   </label>
                   <label className="block space-y-1">
-                    <span className="text-[10px] text-muted">Corner roundness (% short side)</span>
+                    <span className="text-[10px] text-muted">
+                      Corner roundness (% short side)
+                    </span>
                     <input
                       type="number"
                       step="1"
                       min="0"
                       max="49"
-                      value={(((selectedOverlay.bubbleStyle?.cornerRadius ?? 0.4) * 100)).toFixed(0)}
-                      onChange={(e) => updateOverlay(selectedOverlay.id, {
-                        bubbleStyle: {
-                          ...selectedOverlay.bubbleStyle,
-                          cornerRadius: Math.max(0, Math.min(0.49, (parseFloat(e.target.value) || 40) / 100)),
-                        },
-                      })}
+                      value={(
+                        (selectedOverlay.bubbleStyle?.cornerRadius ?? 0.4) * 100
+                      ).toFixed(0)}
+                      onChange={(e) =>
+                        updateOverlay(selectedOverlay.id, {
+                          bubbleStyle: {
+                            ...selectedOverlay.bubbleStyle,
+                            cornerRadius: Math.max(
+                              0,
+                              Math.min(
+                                0.49,
+                                (parseFloat(e.target.value) || 40) / 100,
+                              ),
+                            ),
+                          },
+                        })
+                      }
                       className="w-full px-2 py-1 text-xs border border-border rounded bg-transparent focus:border-accent focus:outline-none"
                       data-testid="inspector-corner-radius"
                     />
@@ -1109,13 +1598,25 @@ export function LetteringEditor({ storyName, cut, plotFile, onSave, onClose, onE
                 </div>
               )}
 
-              <div className="text-[10px] text-muted" data-testid="inspector-font">
-                Font: {selectedOverlay.type === "sfx" ? displayFont.family : bodyFont.family}
+              <div
+                className="text-[10px] text-muted"
+                data-testid="inspector-font"
+              >
+                Font:{" "}
+                {selectedOverlay.type === "sfx"
+                  ? displayFont.family
+                  : bodyFont.family}
               </div>
 
               <div className="text-[10px] font-mono text-muted space-y-0.5">
-                <p>x: {selectedOverlay.x.toFixed(3)}, y: {selectedOverlay.y.toFixed(3)}</p>
-                <p>w: {selectedOverlay.width.toFixed(3)}, h: {selectedOverlay.height.toFixed(3)}</p>
+                <p>
+                  x: {selectedOverlay.x.toFixed(3)}, y:{" "}
+                  {selectedOverlay.y.toFixed(3)}
+                </p>
+                <p>
+                  w: {selectedOverlay.width.toFixed(3)}, h:{" "}
+                  {selectedOverlay.height.toFixed(3)}
+                </p>
               </div>
 
               <button