[#232] Show actionable errors for invalid cartoon cuts.json

app/routes/stories.test.ts

@@ -231,6 +231,41 @@ describe("POST /upload-clean/:cutId route", () => {
     expect(res.status).toBe(404);
   });
 
+  it("GET cuts returns 404 when cuts file is missing", async () => {
+    const storyDir = path.join(tmpDir, "no-cuts-story");
+    fs.mkdirSync(storyDir, { recursive: true });
+
+    const res = await app.request("/api/stories/no-cuts-story/cuts/plot-01");
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(body.error).toContain("not found");
+  });
+
+  it("GET cuts returns 400 with validation error for invalid schema", async () => {
+    const storyDir = path.join(tmpDir, "bad-cuts-story");
+    fs.mkdirSync(storyDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(storyDir, "plot-01.cuts.json"),
+      JSON.stringify({ version: 1, plotFile: "plot-01", cuts: [{ id: "c01", shot: "wide" }] }),
+    );
+
+    const res = await app.request("/api/stories/bad-cuts-story/cuts/plot-01");
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("invalid");
+  });
+
+  it("GET cuts returns 400 for malformed JSON", async () => {
+    const storyDir = path.join(tmpDir, "malformed-cuts-story");
+    fs.mkdirSync(storyDir, { recursive: true });
+    fs.writeFileSync(path.join(storyDir, "plot-01.cuts.json"), "{ not valid json");
+
+    const res = await app.request("/api/stories/malformed-cuts-story/cuts/plot-01");
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("invalid JSON");
+  });
+
   it("detects Korean language from structure.md title without .story.json language", async () => {
     const storyDir = path.join(tmpDir, "korean-story");
     fs.mkdirSync(storyDir, { recursive: true });

app/web/components/CartoonPreview.tsx

@@ -49,7 +49,7 @@
   }
 
   return (
     <img
       src={src}
       alt={alt}
       onError={() => setError(true)}
@@ -200,8 +200,12 @@
 
   if (error) {
     return (
-      <div className="h-full flex flex-col items-center justify-center gap-2 px-4">
-        <p className="text-sm text-error">{error}</p>
+      <div className="h-full flex flex-col items-center justify-center gap-2 px-4 text-center" data-testid="cuts-error">
+        <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 max-w-sm">
+          {plotFile}.cuts.json must follow the OWS v1 schema. Ask Claude to regenerate it using the v1 cuts schema shown in the cartoon writing instructions.
+        </p>
         <button onClick={loadCuts} className="text-xs text-accent hover:text-accent-dim">
           Retry
         </button>

app/web/components/CutListPanel.test.tsx

@@ -276,4 +276,36 @@ describe("CutListPanel", () => {
       expect(screen.getByText("Retry")).toBeInTheDocument();
     });
   });
+
+  it("shows actionable v1 schema guidance for invalid cuts (wrong schema)", async () => {
+    const authFetch = mockAuthFetch({ ok: false, status: 400, data: { error: "plot-01.cuts.json is invalid: Cut 0 has invalid shotType" } });
+    render(<CutListPanel storyName="story" fileName="plot-01.md" authFetch={authFetch} />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("cuts-error")).toBeInTheDocument();
+      expect(screen.getByText("Invalid cuts file")).toBeInTheDocument();
+      expect(screen.getByText(/invalid shotType/)).toBeInTheDocument();
+      expect(screen.getByText(/OWS v1 schema/)).toBeInTheDocument();
+    });
+  });
+
+  it("shows actionable error for invalid JSON", async () => {
+    const authFetch = mockAuthFetch({ ok: false, status: 400, data: { error: "plot-01.cuts.json contains invalid JSON" } });
+    render(<CutListPanel storyName="story" fileName="plot-01.md" authFetch={authFetch} />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/contains invalid JSON/)).toBeInTheDocument();
+      expect(screen.getByText(/OWS v1 schema/)).toBeInTheDocument();
+    });
+  });
+
+  it("missing cuts file (404) shows No cuts, not an error", async () => {
+    const authFetch = mockAuthFetch({ ok: false, status: 404, data: { error: "Cuts file not found" } });
+    render(<CutListPanel storyName="story" fileName="plot-01.md" authFetch={authFetch} />);
+
+    await waitFor(() => {
+      expect(screen.getByText("No cuts yet")).toBeInTheDocument();
+    });
+    expect(screen.queryByTestId("cuts-error")).not.toBeInTheDocument();
+  });
 });

app/web/components/CutListPanel.tsx

@@ -159,7 +159,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"
@@ -267,8 +267,12 @@
 
   if (error) {
     return (
-      <div className="p-4 space-y-2">
-        <p className="text-sm text-error">{error}</p>
+      <div className="p-4 space-y-2" data-testid="cuts-error">
+        <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.
+        </p>
         <button onClick={loadCuts} className="text-xs text-accent hover:text-accent-dim">Retry</button>
       </div>
     );

app/web/components/preview-routing.test.tsx

@@ -53,16 +53,29 @@ describe("CartoonPreview", () => {
     });
   });
 
-  it("shows error state on fetch failure", async () => {
-    const authFetch = mockAuthFetch({ ok: false, status: 400, data: { error: "Invalid JSON" } });
+  it("shows actionable v1 schema error for invalid cuts", async () => {
+    const authFetch = mockAuthFetch({ ok: false, status: 400, data: { error: "plot-01.cuts.json is invalid: Cut 0 missing numeric id" } });
     render(<CartoonPreview storyName="test-story" fileName="plot-01.md" authFetch={authFetch} />);
 
     await waitFor(() => {
-      expect(screen.getByText("Invalid JSON")).toBeInTheDocument();
+      expect(screen.getByTestId("cuts-error")).toBeInTheDocument();
+      expect(screen.getByText("Invalid cuts file")).toBeInTheDocument();
+      expect(screen.getByText(/missing numeric id/)).toBeInTheDocument();
+      expect(screen.getByText(/OWS v1 schema/)).toBeInTheDocument();
       expect(screen.getByText("Retry")).toBeInTheDocument();
     });
   });
 
+  it("missing cuts (404) shows No cuts, not an error", async () => {
+    const authFetch = mockAuthFetch({ ok: false, status: 404, data: { error: "Cuts file not found" } });
+    render(<CartoonPreview storyName="test-story" fileName="plot-01.md" authFetch={authFetch} />);
+
+    await waitFor(() => {
+      expect(screen.getByText("No cuts yet")).toBeInTheDocument();
+    });
+    expect(screen.queryByTestId("cuts-error")).not.toBeInTheDocument();
+  });
+
   it("renders cut with final image", async () => {
     const cutsData = {
       version: 1,