[#204] Build SVG/HTML lettering editor foundation

app/lib/cuts.ts

@@ -1,5 +1,6 @@
 import fs from "fs";
 import path from "path";
+import type { Overlay } from "./overlays";
 
 export const SHOT_TYPES = ["wide", "medium", "close-up", "extreme-close-up"] as const;
 export type ShotType = (typeof SHOT_TYPES)[number];
@@ -22,6 +23,7 @@
   exportedAt: string | null;
   uploadedCid: string | null;
   uploadedUrl: string | null;
+  overlays: Overlay[];
 }
 
 export interface CutsFile {
@@ -30,7 +32,7 @@
   cuts: Cut[];
 }
 
 export function createDefaultCut(id: number, _plotFile: string): Cut {
   return {
     id,
     shotType: "medium",
@@ -44,6 +46,7 @@
     exportedAt: null,
     uploadedCid: null,
     uploadedUrl: null,
+    overlays: [],
   };
 }
 
@@ -151,6 +154,9 @@
         return { valid: false, error: `Cut ${i} ${field} must be a string or null` };
       }
     }
+    if (cut.overlays !== undefined && !Array.isArray(cut.overlays)) {
+      return { valid: false, error: `Cut ${i} overlays must be an array` };
+    }
   }
 
   return { valid: true };

app/lib/overlays.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { toPixel, toNorm, createOverlay } from "./overlays";
+
+describe("toPixel", () => {
+  it("converts 0.5 to half of container", () => {
+    expect(toPixel(0.5, 800)).toBe(400);
+  });
+
+  it("converts 0 to 0", () => {
+    expect(toPixel(0, 600)).toBe(0);
+  });
+
+  it("converts 1 to full container", () => {
+    expect(toPixel(1, 600)).toBe(600);
+  });
+
+  it("handles fractional values", () => {
+    expect(toPixel(0.25, 1000)).toBe(250);
+  });
+});
+
+describe("toNorm", () => {
+  it("converts half to 0.5", () => {
+    expect(toNorm(400, 800)).toBe(0.5);
+  });
+
+  it("converts 0 to 0", () => {
+    expect(toNorm(0, 800)).toBe(0);
+  });
+
+  it("returns 0 for zero container size", () => {
+    expect(toNorm(100, 0)).toBe(0);
+  });
+});
+
+describe("createOverlay", () => {
+  it("creates speech overlay with defaults", () => {
+    const o = createOverlay("speech", 0.2, 0.3);
+    expect(o.type).toBe("speech");
+    expect(o.x).toBe(0.2);
+    expect(o.y).toBe(0.3);
+    expect(o.width).toBe(0.25);
+    expect(o.height).toBe(0.12);
+    expect(o.text).toBe("");
+    expect(o.speaker).toBe("");
+    expect(o.id).toMatch(/^overlay-/);
+  });
+
+  it("creates sfx overlay with smaller dimensions", () => {
+    const o = createOverlay("sfx");
+    expect(o.type).toBe("sfx");
+    expect(o.width).toBe(0.15);
+    expect(o.height).toBe(0.08);
+    expect(o.speaker).toBeUndefined();
+  });
+
+  it("creates narration overlay without speaker", () => {
+    const o = createOverlay("narration");
+    expect(o.type).toBe("narration");
+    expect(o.speaker).toBeUndefined();
+  });
+
+  it("generates unique IDs", () => {
+    const a = createOverlay("speech");
+    const b = createOverlay("speech");
+    expect(a.id).not.toBe(b.id);
+  });
+});

app/lib/overlays.ts

@@ -0,0 +1,38 @@
+export const OVERLAY_TYPES = ["speech", "narration", "sfx"] as const;
+export type OverlayType = (typeof OVERLAY_TYPES)[number];
+
+export interface Overlay {
+  id: string;
+  type: OverlayType;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  text: string;
+  speaker?: string;
+}
+
+export function toPixel(norm: number, containerSize: number): number {
+  return norm * containerSize;
+}
+
+export function toNorm(pixel: number, containerSize: number): number {
+  if (containerSize === 0) return 0;
+  return pixel / containerSize;
+}
+
+let counter = 0;
+
+export function createOverlay(type: OverlayType, x = 0.1, y = 0.1): Overlay {
+  counter++;
+  return {
+    id: `overlay-${Date.now()}-${counter}`,
+    type,
+    x,
+    y,
+    width: type === "sfx" ? 0.15 : 0.25,
+    height: type === "sfx" ? 0.08 : 0.12,
+    text: "",
+    ...(type === "speech" ? { speaker: "" } : {}),
+  };
+}

app/web/components/CutListPanel.tsx

@@ -1,4 +1,16 @@
 import { useState, useEffect, useCallback, useRef } from "react";
+import { LetteringEditor } from "./LetteringEditor";
+
+interface Overlay {
+  id: string;
+  type: "speech" | "narration" | "sfx";
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  text: string;
+  speaker?: string;
+}
 
 interface CutDialogue {
   speaker: string;
@@ -18,6 +30,7 @@
   exportedAt: string | null;
   uploadedCid: string | null;
   uploadedUrl: string | null;
+  overlays: Overlay[];
 }
 
 interface CutsFile {
@@ -75,6 +88,7 @@
   onToggle,
   authFetch,
   onUpdated,
+  onOpenEditor,
 }: {
   cut: Cut;
   storyName: string;
@@ -83,6 +97,7 @@
   onToggle: () => void;
   authFetch: (url: string, opts?: RequestInit) => Promise<Response>;
   onUpdated: () => void;
+  onOpenEditor: () => void;
 }) {
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [uploading, setUploading] = useState(false);
@@ -143,7 +158,7 @@
           {/* Clean image preview */}
           {cut.cleanImagePath && (
             <div className="mt-2">
               <img
                 src={assetUrl(storyName, cut.cleanImagePath)}
                 alt={`Cut ${cut.id} clean`}
                 className="w-full max-h-48 object-contain rounded border border-border bg-white"
@@ -177,6 +192,16 @@
             )}
           </div>
 
+          {/* Open editor button */}
+          {cut.cleanImagePath && (
+            <button
+              onClick={onOpenEditor}
+              className="px-3 py-1.5 text-xs border border-accent/30 text-accent rounded hover:bg-accent/5"
+            >
+              Open editor
+            </button>
+          )}
+
           {/* Cut metadata */}
           {cut.characters.length > 0 && (
             <p className="text-xs text-muted">Characters: {cut.characters.join(", ")}</p>
@@ -202,6 +227,7 @@
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [expandedCut, setExpandedCut] = useState<number | null>(null);
+  const [editingCutId, setEditingCutId] = useState<number | null>(null);
 
   const plotFile = fileName.replace(/\.md$/, "");
 
@@ -252,6 +278,28 @@
     );
   }
 
+  const editingCut = editingCutId !== null ? cutsFile.cuts.find((c) => c.id === editingCutId) : null;
+
+  if (editingCut) {
+    return (
+      <LetteringEditor
+        storyName={storyName}
+        cut={editingCut}
+        onSave={async (overlays: Overlay[]) => {
+          const updated = { ...cutsFile, cuts: cutsFile.cuts.map((c) => c.id === editingCutId ? { ...c, overlays } : c) };
+          await authFetch(`/api/stories/${storyName}/cuts/${plotFile}`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(updated),
+          });
+          setEditingCutId(null);
+          loadCuts();
+        }}
+        onClose={() => setEditingCutId(null)}
+      />
+    );
+  }
+
   const stats = cutsFile.cuts.reduce(
     (acc, cut) => {
       const s = getCutStatus(cut);
@@ -284,6 +332,7 @@
             onToggle={() => setExpandedCut(expandedCut === cut.id ? null : cut.id)}
             authFetch={authFetch}
             onUpdated={loadCuts}
+            onOpenEditor={() => setEditingCutId(cut.id)}
           />
         ))}
       </div>