plotlink-ows 1.0.32 → 1.2.94

package/app/routes/stories.ts

@@ -2,6 +2,15 @@ import { Hono } from "hono";
 import fs from "fs";
 import path from "path";
 import { STORIES_DIR } from "../lib/paths";
+import { writeStoryInstructions } from "../lib/generate-story-instructions";
+import { readCutsFile, writeCutsFile, validateCutsFile } from "../lib/cuts";
+import { buildStoryProgress } from "../lib/story-progress";
+import { deriveCartoonCoach } from "../lib/cartoon-coach";
+import { diagnoseCutAssets, summarizeAssetDiagnostics } from "../lib/cut-asset-diagnostics";
+import { CARTOON_BUBBLE_RENDERER_VERSION } from "../lib/overlays";
+import { mergeCartoonMarkdown } from "../lib/cartoon-markdown";
+import { syncCleanImages, cleanImageCandidates, sniffImageType, cleanImageBytesMatchMime, findStaleAssetPaths, clearStaleAssetPaths, type SniffedType } from "../lib/clean-image-sync";
+import { imageAssetIssue, isValidImageAsset, pngAssetExists, CLEAN_IMAGE_VALID_EXT } from "../lib/image-asset-validate";
 
 const stories = new Hono();
 
@@ -34,6 +43,18 @@ interface StoryInfo {
   hasGenesis: boolean;
   plotCount: number;
   publishedCount: number;
+  contentType: "fiction" | "cartoon";
+  // Publish metadata from .story.json, surfaced so the publish controls seed
+  // from the real story values (#424). Absent ⇒ could not be determined (no
+  // .story.json value, no structure.md hint, no script detection), so the client
+  // shows an explicit "Needs metadata" state instead of a misleading default
+  // (English/Romance). `genre` is the raw stored label; the client canonicalizes.
+  language?: string;
+  genre?: string;
+  isNsfw?: boolean;
+  // Optional. Absent ⇒ no provider recorded (legacy story ⇒ defaults to Claude
+  // at launch). Surfaced read-only so the client can offer a scoped repair.
+  agentProvider?: AgentProvider;
 }
 
 function readPublishStatus(storyDir: string): Record<string, FileStatus> {
@@ -51,8 +72,73 @@ function writePublishStatus(storyDir: string, status: Record<string, FileStatus>
   fs.writeFileSync(statusFile, JSON.stringify(status, null, 2) + "\n");
 }
 
+export type AgentProvider = "claude" | "codex";
+
+interface StoryMeta {
+  contentType: "fiction" | "cartoon";
+  // Publish metadata authored in .story.json. Surfaced so the publish controls
+  // initialize from the story's real values instead of falling back to the
+  // first-in-list defaults (Romance / English) — see #424.
+  title?: string;
+  description?: string;
+  language?: string;
+  genre?: string;
+  isNsfw?: boolean;
+  agentMode?: "normal" | "bypass";
+  // Optional. Absent ⇒ Claude (no migration). "claude" | "codex".
+  agentProvider?: AgentProvider;
+}
+
+function readStoryMeta(storyDir: string): StoryMeta {
+  const metaFile = path.join(storyDir, ".story.json");
+  try {
+    if (fs.existsSync(metaFile)) {
+      const raw = JSON.parse(fs.readFileSync(metaFile, "utf-8"));
+      if (raw.contentType === "fiction" || raw.contentType === "cartoon") {
+        // Accept both camelCase `isNsfw` and snake_case `is_nsfw` on read; we
+        // always persist canonical `isNsfw` (see writeStoryMeta).
+        const isNsfw = typeof raw.isNsfw === "boolean" ? raw.isNsfw
+          : typeof raw.is_nsfw === "boolean" ? raw.is_nsfw
+          : undefined;
+        return {
+          contentType: raw.contentType,
+          ...(typeof raw.title === "string" ? { title: raw.title } : {}),
+          ...(typeof raw.description === "string" ? { description: raw.description } : {}),
+          ...(typeof raw.language === "string" ? { language: raw.language } : {}),
+          ...(typeof raw.genre === "string" ? { genre: raw.genre } : {}),
+          ...(isNsfw !== undefined ? { isNsfw } : {}),
+          ...(raw.agentMode === "bypass" || raw.agentMode === "normal" ? { agentMode: raw.agentMode } : {}),
+          ...(raw.agentProvider === "claude" || raw.agentProvider === "codex" ? { agentProvider: raw.agentProvider } : {}),
+        };
+      }
+    }
+  } catch { /* ignore */ }
+  return { contentType: "fiction" };
+}
+
+function writeStoryMeta(storyDir: string, meta: StoryMeta) {
+  const metaFile = path.join(storyDir, ".story.json");
+  fs.writeFileSync(metaFile, JSON.stringify(meta, null, 2) + "\n");
+}
+
+function parseLanguageMetadata(content: string): string | null {
+  const match = content.match(/^(?:\*\*)?Language(?:\*\*)?:\s*(?:\*\*)?([^*\n]+)/im);
+  if (match) return match[1].trim();
+  return null;
+}
+
+function detectLanguageFromScript(text: string): string | null {
+  if (/[가-힯]/.test(text)) return "Korean";
+  if (/[぀-ゟ゠-ヿ]/.test(text)) return "Japanese";
+  if (/[一-鿿]/.test(text)) return "Chinese";
+  if (/[ऀ-ॿ]/.test(text)) return "Hindi";
+  if (/[؀-ۿ]/.test(text)) return "Arabic";
+  return null;
+}
+
 function scanStory(storyDir: string, name: string): StoryInfo {
   const publishStatus = readPublishStatus(storyDir);
+  const storyMeta = readStoryMeta(storyDir);
   const entries = fs.readdirSync(storyDir).filter((f) => f.endsWith(".md"));
 
   const files: FileStatus[] = entries.map((file) => {
@@ -68,14 +154,15 @@ function scanStory(storyDir: string, name: string): StoryInfo {
   const plotCount = entries.filter((f) => f.match(/^plot-\d+\.md$/)).length;
   const publishedCount = files.filter((f) => f.status === "published" || f.status === "published-not-indexed").length;
 
-  // Extract title from structure.md or genesis.md
+  // Extract title and language hints from structure.md or genesis.md
   let title: string | null = null;
+  let structContent: string | null = null;
   try {
     const structPath = path.join(storyDir, "structure.md");
     const genesisPath = path.join(storyDir, "genesis.md");
     if (fs.existsSync(structPath)) {
-      const content = fs.readFileSync(structPath, "utf-8");
-      const match = content.match(/^#\s+(.+)$/m);
+      structContent = fs.readFileSync(structPath, "utf-8");
+      const match = structContent.match(/^#\s+(.+)$/m);
       if (match) title = match[1];
     } else if (fs.existsSync(genesisPath)) {
       const content = fs.readFileSync(genesisPath, "utf-8");
@@ -84,7 +171,40 @@ function scanStory(storyDir: string, name: string): StoryInfo {
     }
   } catch { /* best effort */ }
 
-  return { name, title, files, hasStructure, hasGenesis, plotCount, publishedCount };
+  // Resolve language best-effort from explicit metadata → structure.md hint →
+  // script detection. Do NOT blind-default to English (#424): when nothing
+  // determines it, leave it undefined so the client shows "Needs metadata"
+  // rather than silently publishing the wrong language.
+  let language: string | undefined = storyMeta.language;
+  if (!language) {
+    const fromMetadata = structContent ? parseLanguageMetadata(structContent) : null;
+    const fromScript = title ? detectLanguageFromScript(title) : null;
+    language = fromMetadata ?? fromScript ?? undefined;
+  }
+
+  return {
+    name,
+    // Prefer the explicit .story.json title when present (#424); fall back to
+    // the H1 parsed from structure.md / genesis.md.
+    title: storyMeta.title ?? title,
+    files,
+    hasStructure,
+    hasGenesis,
+    plotCount,
+    publishedCount,
+    contentType: storyMeta.contentType,
+    // Surfaced from .story.json/detection so the publish controls seed real
+    // values (#424); omitted when undetermined so the client shows "Needs
+    // metadata" instead of a misleading English default.
+    ...(language ? { language } : {}),
+    ...(storyMeta.genre ? { genre: storyMeta.genre } : {}),
+    ...(typeof storyMeta.description === "string" ? { description: storyMeta.description } : {}),
+    ...(storyMeta.isNsfw !== undefined ? { isNsfw: storyMeta.isNsfw } : {}),
+    // Read-only passthrough. Absent when the story has no provider recorded
+    // (legacy), so a legacy cartoon shows no provider and the client can offer
+    // the explicit repair affordance. Never written/migrated here.
+    ...(storyMeta.agentProvider ? { agentProvider: storyMeta.agentProvider } : {}),
+  };
 }
 
 /** GET /api/stories — list all stories */
@@ -177,6 +297,842 @@ stories.get("/:name", (c) => {
   return c.json({ ...info, files: filesWithContent });
 });
 
+/** POST /api/stories/:name/metadata — write/update .story.json */
+stories.post("/:name/metadata", async (c) => {
+  const name = safeName(c.req.param("name"));
+  if (!name) return c.json({ error: "Invalid story name" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  const body = await c.req.json<{ contentType?: string; language?: string; agentMode?: string; agentProvider?: string }>();
+  if (body.contentType !== "fiction" && body.contentType !== "cartoon") {
+    return c.json({ error: "contentType must be 'fiction' or 'cartoon'" }, 400);
+  }
+
+  const existing = readStoryMeta(storyDir);
+  const meta: StoryMeta = {
+    ...existing,
+    contentType: body.contentType,
+    ...(typeof body.language === "string" ? { language: body.language } : {}),
+    ...(body.agentMode === "bypass" || body.agentMode === "normal" ? { agentMode: body.agentMode } : {}),
+    ...(body.agentProvider === "claude" || body.agentProvider === "codex" ? { agentProvider: body.agentProvider } : {}),
+  };
+  writeStoryMeta(storyDir, meta);
+  // Provider-aware so a legacy-cartoon repair (agentProvider → codex) rewrites
+  // CLAUDE.md with the Codex file-creation contract; absent ⇒ Claude/manual.
+  writeStoryInstructions(storyDir, meta.contentType, meta.agentProvider);
+
+  return c.json({ ok: true });
+});
+
+/**
+ * POST /api/stories/:name/publish-metadata — persist publish controls back to
+ * .story.json (#424).
+ *
+ * Lets a writer's genre/language/is-NSFW selections in the publish panel stick
+ * across refresh, keeping the controls in sync with story metadata. Unlike the
+ * /metadata route this does NOT change contentType or rewrite CLAUDE.md — it
+ * only updates publish fields, so fiction/agent behavior is untouched. Each
+ * field is optional; omitted fields are left as-is (so a single control edit
+ * never clobbers the others).
+ */
+stories.post("/:name/publish-metadata", async (c) => {
+  const name = safeName(c.req.param("name"));
+  if (!name) return c.json({ error: "Invalid story name" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  const body = await c.req.json<{ title?: string; description?: string; language?: string; genre?: string; isNsfw?: boolean }>();
+
+  const existing = readStoryMeta(storyDir);
+  const meta: StoryMeta = {
+    ...existing,
+    ...(typeof body.title === "string" ? { title: body.title } : {}),
+    ...(typeof body.description === "string" ? { description: body.description } : {}),
+    ...(typeof body.language === "string" ? { language: body.language } : {}),
+    ...(typeof body.genre === "string" ? { genre: body.genre } : {}),
+    ...(typeof body.isNsfw === "boolean" ? { isNsfw: body.isNsfw } : {}),
+  };
+  writeStoryMeta(storyDir, meta);
+
+  return c.json({ ok: true });
+});
+
+/** Derive a filesystem-safe slug from a title (#423). Non-Latin titles (e.g.
+ * Korean) reduce to empty → fall back to "story"; the real title is kept in
+ * .story.json and is what the UI displays. */
+function slugifyTitle(title: string): string {
+  const base = title.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+  return base || "story";
+}
+
+/**
+ * POST /api/stories/create — guided New Story setup (#423).
+ *
+ * Creates the story folder + .story.json + CLAUDE.md from the user's chosen
+ * title/metadata UP FRONT, so a normal user no longer has to prompt the agent to
+ * rename an "Untitled" project. The (possibly non-Latin) title is stored in
+ * .story.json and shown in the UI; the folder slug is an ASCII fallback. Cartoon
+ * always uses Codex (the clean-image step needs image generation).
+ */
+stories.post("/create", async (c) => {
+  const body = await c.req.json<{ title?: string; description?: string; language?: string; genre?: string; contentType?: string; agentMode?: string; agentProvider?: string }>();
+  const title = (body.title ?? "").trim();
+  if (!title) return c.json({ error: "Title is required" }, 400);
+
+  const contentType = body.contentType === "cartoon" ? "cartoon" : "fiction";
+  const agentProvider: AgentProvider = contentType === "cartoon" ? "codex" : (body.agentProvider === "codex" ? "codex" : "claude");
+  const agentMode = body.agentMode === "bypass" ? "bypass" : "normal";
+
+  if (!fs.existsSync(STORIES_DIR)) fs.mkdirSync(STORIES_DIR, { recursive: true });
+  const base = slugifyTitle(title);
+  let slug = base;
+  for (let i = 2; fs.existsSync(path.join(STORIES_DIR, slug)); i++) slug = `${base}-${i}`;
+  const storyDir = path.join(STORIES_DIR, slug);
+  fs.mkdirSync(storyDir, { recursive: true });
+
+  const meta: StoryMeta = {
+    contentType,
+    title,
+    ...(typeof body.description === "string" && body.description.trim() ? { description: body.description.trim() } : {}),
+    ...(typeof body.language === "string" && body.language ? { language: body.language } : {}),
+    ...(typeof body.genre === "string" && body.genre ? { genre: body.genre } : {}),
+    agentMode,
+    agentProvider,
+  };
+  writeStoryMeta(storyDir, meta);
+  writeStoryInstructions(storyDir, contentType, agentProvider);
+
+  return c.json({ name: slug, title, contentType });
+});
+
+/** GET /api/stories/:name/cuts/:plotFile — read cuts.json for a plot */
+stories.get("/:name/cuts/:plotFile", (c) => {
+  const name = safeName(c.req.param("name"));
+  const plotFile = safeName(c.req.param("plotFile"));
+  if (!name || !plotFile) return c.json({ error: "Invalid path" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  try {
+    const cutsFile = readCutsFile(storyDir, plotFile);
+    if (!cutsFile) return c.json({ error: "Cuts file not found" }, 404);
+    return c.json(cutsFile);
+  } catch (err) {
+    return c.json({ error: (err as Error).message }, 400);
+  }
+});
+
+/** PUT /api/stories/:name/cuts/:plotFile — update cuts.json */
+stories.put("/:name/cuts/:plotFile", async (c) => {
+  const name = safeName(c.req.param("name"));
+  const plotFile = safeName(c.req.param("plotFile"));
+  if (!name || !plotFile) return c.json({ error: "Invalid path" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  const body = await c.req.json();
+  const validation = validateCutsFile(body);
+  if (!validation.valid) {
+    return c.json({ error: validation.error }, 400);
+  }
+
+  writeCutsFile(storyDir, plotFile, body);
+  return c.json({ ok: true });
+});
+
+/** POST /api/stories/:name/cuts/:plotFile/upload-clean/:cutId — upload clean image for a cut */
+stories.post("/:name/cuts/:plotFile/upload-clean/:cutId", async (c) => {
+  const name = safeName(c.req.param("name"));
+  const plotFile = safeName(c.req.param("plotFile"));
+  const cutIdStr = c.req.param("cutId");
+  if (!name || !plotFile || !cutIdStr) return c.json({ error: "Invalid path" }, 400);
+
+  const cutId = parseInt(cutIdStr, 10);
+  if (isNaN(cutId) || cutId < 1) return c.json({ error: "Invalid cut ID" }, 400);
+
+  const storyDir = path.join(STORIES_DIR, name);
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  const cutsFile = readCutsFile(storyDir, plotFile);
+  if (!cutsFile) return c.json({ error: "Cuts file not found" }, 404);
+
+  const cut = cutsFile.cuts.find((c) => c.id === cutId);
+  if (!cut) return c.json({ error: `Cut ${cutId} not found` }, 404);
+
+  let formData: FormData;
+  try {
+    formData = await c.req.formData();
+  } catch {
+    return c.json({ error: "No file provided" }, 400);
+  }
+  const file = formData.get("file") as File | Blob | null;
+  if (!file || (typeof file === "string")) {
+    return c.json({ error: "No file provided" }, 400);
+  }
+
+  if (file.size > 1024 * 1024) {
+    return c.json({ error: "File must be under 1MB" }, 400);
+  }
+
+  const mime = file.type;
+  if (mime !== "image/webp" && mime !== "image/jpeg") {
+    return c.json({ error: "Only WebP and JPEG images are supported" }, 400);
+  }
+
+  // Validate by actual file bytes, not just the (spoofable) MIME label, so a
+  // renamed text/PNG file claiming image/webp cannot be recorded as a clean
+  // image. Mirrors the magic-byte check used by sync-clean-images (#256/#266).
+  const buffer = Buffer.from(await file.arrayBuffer());
+  if (!cleanImageBytesMatchMime(buffer, mime)) {
+    return c.json(
+      { error: "File content is not a valid WebP/JPEG image (bytes do not match the image type)" },
+      400,
+    );
+  }
+
+  const ext = mime === "image/webp" ? "webp" : "jpg";
+  const padded = String(cutId).padStart(2, "0");
+  const assetDir = path.join(storyDir, "assets", plotFile);
+  fs.mkdirSync(assetDir, { recursive: true });
+
+  const fileName = `cut-${padded}-clean.${ext}`;
+  const filePath = path.join(assetDir, fileName);
+  fs.writeFileSync(filePath, buffer);
+
+  const cleanImagePath = `assets/${plotFile}/cut-${padded}-clean.${ext}`;
+  cut.cleanImagePath = cleanImagePath;
+  writeCutsFile(storyDir, plotFile, cutsFile);
+
+  return c.json({ ok: true, cleanImagePath });
+});
+
+function saveExportedCut(
+  storyDir: string,
+  plotFile: string,
+  cutId: number,
+  buffer: Buffer,
+  mime: string,
+): { finalImagePath: string } {
+  const ext = mime === "image/webp" ? "webp" : "jpg";
+  const padded = String(cutId).padStart(2, "0");
+  const assetDir = path.join(storyDir, "assets", plotFile);
+  fs.mkdirSync(assetDir, { recursive: true });
+
+  const fileName = `cut-${padded}-final.${ext}`;
+  fs.writeFileSync(path.join(assetDir, fileName), buffer);
+
+  const finalImagePath = `assets/${plotFile}/cut-${padded}-final.${ext}`;
+
+  const cutsFile = readCutsFile(storyDir, plotFile)!;
+  const cut = cutsFile.cuts.find((c) => c.id === cutId)!;
+  cut.finalImagePath = finalImagePath;
+  cut.exportedAt = new Date().toISOString();
+  // Stamp the bubble-renderer revision so a later renderer upgrade can flag this
+  // final image as stale (needing re-export) before publish (#381).
+  cut.finalRendererVersion = CARTOON_BUBBLE_RENDERER_VERSION;
+  // A NEW final image invalidates any prior upload (#381): the old PlotLink asset
+  // is the previous render (e.g. the stale separated-tail one). Clear the upload
+  // record so the cut becomes upload-eligible again — otherwise the bulk upload
+  // skips it (it filters out cuts that already have an uploadedCid) and the old
+  // image would keep publishing even after re-export.
+  cut.uploadedCid = null;
+  cut.uploadedUrl = null;
+  writeCutsFile(storyDir, plotFile, cutsFile);
+
+  return { finalImagePath };
+}
+
+/** POST /api/stories/:name/cuts/:plotFile/export-final/:cutId — save exported final image */
+stories.post("/:name/cuts/:plotFile/export-final/:cutId", async (c) => {
+  const name = safeName(c.req.param("name"));
+  const plotFile = safeName(c.req.param("plotFile"));
+  const cutIdStr = c.req.param("cutId");
+  if (!name || !plotFile || !cutIdStr) return c.json({ error: "Invalid path" }, 400);
+
+  const cutId = parseInt(cutIdStr, 10);
+  if (isNaN(cutId) || cutId < 1) return c.json({ error: "Invalid cut ID" }, 400);
+
+  const storyDir = path.join(STORIES_DIR, name);
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  const cutsFile = readCutsFile(storyDir, plotFile);
+  if (!cutsFile) return c.json({ error: "Cuts file not found" }, 404);
+
+  const cut = cutsFile.cuts.find((ct) => ct.id === cutId);
+  if (!cut) return c.json({ error: `Cut ${cutId} not found` }, 404);
+
+  let formData: FormData;
+  try {
+    formData = await c.req.formData();
+  } catch {
+    return c.json({ error: "No file provided" }, 400);
+  }
+  const file = formData.get("file") as File | Blob | null;
+  if (!file || (typeof file === "string")) {
+    return c.json({ error: "No file provided" }, 400);
+  }
+
+  if (file.size > 1024 * 1024) {
+    return c.json({ error: "File must be under 1MB" }, 400);
+  }
+
+  const mime = file.type;
+  if (mime !== "image/webp" && mime !== "image/jpeg") {
+    return c.json({ error: "Only WebP and JPEG images are supported" }, 400);
+  }
+
+  const buffer = Buffer.from(await file.arrayBuffer());
+  const result = saveExportedCut(storyDir, plotFile, cutId, buffer, mime);
+
+  return c.json({ ok: true, finalImagePath: result.finalImagePath });
+});
+
+/** POST /api/stories/:name/cuts/:plotFile/set-uploaded/:cutId — record upload CID/URL for a cut */
+stories.post("/:name/cuts/:plotFile/set-uploaded/:cutId", async (c) => {
+  const name = safeName(c.req.param("name"));
+  const plotFile = safeName(c.req.param("plotFile"));
+  const cutIdStr = c.req.param("cutId");
+  if (!name || !plotFile || !cutIdStr) return c.json({ error: "Invalid path" }, 400);
+
+  const cutId = parseInt(cutIdStr, 10);
+  if (isNaN(cutId) || cutId < 1) return c.json({ error: "Invalid cut ID" }, 400);
+
+  const storyDir = path.join(STORIES_DIR, name);
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  const cutsFile = readCutsFile(storyDir, plotFile);
+  if (!cutsFile) return c.json({ error: "Cuts file not found" }, 404);
+
+  const cut = cutsFile.cuts.find((ct) => ct.id === cutId);
+  if (!cut) return c.json({ error: `Cut ${cutId} not found` }, 404);
+
+  const body = await c.req.json<{ cid: string; url: string }>();
+  if (!body.cid || !body.url) return c.json({ error: "cid and url required" }, 400);
+
+  cut.uploadedCid = body.cid;
+  cut.uploadedUrl = body.url;
+  writeCutsFile(storyDir, plotFile, cutsFile);
+
+  return c.json({ ok: true });
+});
+
+/** POST /api/stories/:name/cuts/:plotFile/generate-markdown — generate/update plot markdown from cuts */
+stories.post("/:name/cuts/:plotFile/generate-markdown", async (c) => {
+  const name = safeName(c.req.param("name"));
+  const plotFile = safeName(c.req.param("plotFile"));
+  if (!name || !plotFile) return c.json({ error: "Invalid path" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  const cutsFile = readCutsFile(storyDir, plotFile);
+  if (!cutsFile) return c.json({ error: "Cuts file not found" }, 404);
+
+  const mdFile = path.join(storyDir, `${plotFile}.md`);
+  const existingMd = fs.existsSync(mdFile) ? fs.readFileSync(mdFile, "utf-8") : "";
+
+  const { markdown, warnings } = mergeCartoonMarkdown(existingMd, cutsFile.cuts);
+  fs.writeFileSync(mdFile, markdown, "utf-8");
+
+  return c.json({ ok: true, warnings });
+});
+
+/**
+ * POST /api/stories/:name/cuts/:plotFile/sync-clean-images — detect clean image
+ * files that exist on disk and record their path on the matching cut. Only
+ * records a path when a real, valid file exists (size ≤ 1MB, allowed extension);
+ * invalid/oversized files are reported as `rejected` and never recorded.
+ */
+stories.post("/:name/cuts/:plotFile/sync-clean-images", (c) => {
+  const name = safeName(c.req.param("name"));
+  const plotFile = safeName(c.req.param("plotFile"));
+  if (!name || !plotFile) return c.json({ error: "Invalid path" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  let cutsFile;
+  try {
+    cutsFile = readCutsFile(storyDir, plotFile);
+  } catch (err) {
+    return c.json({ error: (err as Error).message }, 400);
+  }
+  if (!cutsFile) return c.json({ error: "Cuts file not found" }, 404);
+
+  const rejectedMap = new Map<string, { cutId: number; reason: string }>();
+
+  // Validate a candidate relative path against the real filesystem (shared
+  // validator). Returns true ONLY when the file exists and is a valid WebP/JPEG
+  // ≤ 1MB. A present-but-invalid file (wrong extension, oversized, content
+  // mismatch) is recorded in `rejected` (deduped by path) so the writer learns
+  // why it was not recorded; a merely-absent file is silently "not found".
+  const fileExists = (relPath: string): boolean => {
+    const issue = imageAssetIssue(storyDir, relPath);
+    if (issue === null) return true;
+    if (issue === "missing") return false; // absent / non-file → not a rejection
+    const cutMatch = relPath.match(/cut-(\d+)-clean\./);
+    const cutId = cutMatch ? parseInt(cutMatch[1], 10) : 0;
+    rejectedMap.set(relPath, { cutId, reason: issue });
+    return false;
+  };
+
+  // Touch every canonical candidate so oversized/invalid files surface as
+  // rejections even when a valid one is also present for the same cut.
+  for (const cut of cutsFile.cuts) {
+    for (const rel of cleanImageCandidates(plotFile, cut.id)) {
+      fileExists(rel);
+    }
+  }
+
+  // Surface any on-disk clean image with a disallowed extension (e.g. .txt) so
+  // the writer learns why it was not recorded — these never become candidates.
+  const assetDir = path.join(storyDir, "assets", plotFile);
+  if (fs.existsSync(assetDir)) {
+    const knownCutIds = new Set(cutsFile.cuts.map((cut) => cut.id));
+    for (const entry of fs.readdirSync(assetDir)) {
+      const m = entry.match(/^cut-(\d+)-clean\.([A-Za-z0-9]+)$/);
+      if (!m) continue;
+      const ext = m[2].toLowerCase();
+      const cutId = parseInt(m[1], 10);
+      if (!knownCutIds.has(cutId)) continue;
+      const rel = `assets/${plotFile}/${entry}`;
+      if (!CLEAN_IMAGE_VALID_EXT.has(ext) && !rejectedMap.has(rel)) {
+        rejectedMap.set(rel, { cutId, reason: `Unsupported extension .${ext}` });
+      }
+    }
+  }
+
+  const result = syncCleanImages(cutsFile.cuts, plotFile, fileExists);
+  const rejected = Array.from(rejectedMap.values());
+  if (result.changed) {
+    writeCutsFile(storyDir, plotFile, { ...cutsFile, cuts: result.cuts });
+  }
+
+  return c.json({ ok: true, changed: result.changed, synced: result.synced, cleared: result.cleared, rejected });
+});
+
+/**
+ * GET /api/stories/:name/cuts/:plotFile/detect-clean-images — dry-run detection.
+ * Reports the cut ids that have a valid local clean image on disk (exists, ≤ 1MB,
+ * magic-byte-valid, extension matches content) AND whose cut currently has
+ * `cleanImagePath === null`. This mirrors the sync route's validation but NEVER
+ * writes cuts.json — it is read-only so the client can show a per-cut affordance.
+ */
+stories.get("/:name/cuts/:plotFile/detect-clean-images", (c) => {
+  const name = safeName(c.req.param("name"));
+  const plotFile = safeName(c.req.param("plotFile"));
+  if (!name || !plotFile) return c.json({ error: "Invalid path" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  let cutsFile;
+  try {
+    cutsFile = readCutsFile(storyDir, plotFile);
+  } catch (err) {
+    return c.json({ error: (err as Error).message }, 400);
+  }
+  if (!cutsFile) return c.json({ error: "Cuts file not found" }, 404);
+
+  // Read-only validation via the shared validator (exists + allowed extension +
+  // ≤ 1MB + magic-byte content match). Never records rejections or mutates cuts.
+  const detected: number[] = [];
+  for (const cut of cutsFile.cuts) {
+    if (cut.cleanImagePath !== null) continue;
+    const hasValid = cleanImageCandidates(plotFile, cut.id).some((rel) =>
+      isValidImageAsset(storyDir, rel),
+    );
+    if (hasValid) detected.push(cut.id);
+  }
+
+  // Also report recorded clean/final paths that no longer point to a valid local
+  // image (#302) so the client can show a precise per-cut error and offer the
+  // repair action instead of silently treating the cut as image-ready. Skip
+  // already-uploaded cuts: their content is on IPFS, so a missing LOCAL file is
+  // not a defect to surface.
+  const stale = findStaleAssetPaths(cutsFile.cuts, (rel) => isValidImageAsset(storyDir, rel)).filter(
+    (issue) => {
+      const cut = cutsFile!.cuts.find((ct) => ct.id === issue.cutId);
+      return !cut?.uploadedUrl;
+    },
+  );
+
+  return c.json({ detected, stale });
+});
+
+/**
+ * GET /api/stories/:name/cuts/:plotFile/asset-diagnostics — read-only per-cut
+ * asset state rescan (#427).
+ *
+ * Classifies each cut's REAL asset state against the local story folder —
+ * planned / missing / clean-ready / final-ready / uploaded — with a precise
+ * per-cut reason when a recorded path doesn't resolve (so "files exist but
+ * aren't displayed" or "a typoed path" become a clear diagnostic instead of a
+ * generic publish warning). Works for genesis.cuts.json and plot-NN.cuts.json
+ * equally. Never mutates, uploads, or publishes anything.
+ */
+stories.get("/:name/cuts/:plotFile/asset-diagnostics", (c) => {
+  const name = safeName(c.req.param("name"));
+  const plotFile = safeName(c.req.param("plotFile"));
+  if (!name || !plotFile) return c.json({ error: "Invalid path" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  let cutsFile;
+  try {
+    cutsFile = readCutsFile(storyDir, plotFile);
+  } catch (err) {
+    return c.json({ error: (err as Error).message }, 400);
+  }
+  if (!cutsFile) return c.json({ error: "Cuts file not found" }, 404);
+
+  // Resolve a convertible PNG clean image for a cut (#441): the recorded clean
+  // path when it's a real PNG, else an unrecorded `cut-NN-clean.png` on disk.
+  const pngClean = (cut: { id: number; cleanImagePath: string | null }): string | null => {
+    if (cut.cleanImagePath && /\.png$/i.test(cut.cleanImagePath) && pngAssetExists(storyDir, cut.cleanImagePath)) {
+      return cut.cleanImagePath;
+    }
+    const candidate = `assets/${plotFile}/cut-${String(cut.id).padStart(2, "0")}-clean.png`;
+    return pngAssetExists(storyDir, candidate) ? candidate : null;
+  };
+
+  const diagnostics = diagnoseCutAssets(cutsFile.cuts, (rel) => imageAssetIssue(storyDir, rel), pngClean);
+  const summary = summarizeAssetDiagnostics(diagnostics);
+  return c.json({ diagnostics, summary });
+});
+
+/**
+ * POST /api/stories/:name/cuts/:plotFile/repair-asset-paths — clear stale
+ * recorded asset paths (#302). Any cleanImagePath/finalImagePath that no longer
+ * points to a valid local image is reset to null; valid paths and already-
+ * uploaded cuts (uploadedCid/uploadedUrl) are preserved. This is the real repair
+ * behind the per-cut "Clear stale path" action and, unlike sync-clean-images,
+ * also repairs a stale finalImagePath.
+ */
+stories.post("/:name/cuts/:plotFile/repair-asset-paths", (c) => {
+  const name = safeName(c.req.param("name"));
+  const plotFile = safeName(c.req.param("plotFile"));
+  if (!name || !plotFile) return c.json({ error: "Invalid path" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  let cutsFile;
+  try {
+    cutsFile = readCutsFile(storyDir, plotFile);
+  } catch (err) {
+    return c.json({ error: (err as Error).message }, 400);
+  }
+  if (!cutsFile) return c.json({ error: "Cuts file not found" }, 404);
+
+  const result = clearStaleAssetPaths(cutsFile.cuts, (rel) => isValidImageAsset(storyDir, rel));
+  if (result.changed) {
+    writeCutsFile(storyDir, plotFile, { ...cutsFile, cuts: result.cuts });
+  }
+
+  return c.json({ ok: true, changed: result.changed, cleared: result.cleared });
+});
+
+
+const COVER_MAX_BYTES = 1024 * 1024;
+// Candidate agent-created cover files, in preference order (#296). The agent
+// writes a single cover under assets/; we never guess plot/cut images here.
+const COVER_CANDIDATES = [
+  { rel: "assets/cover.webp", type: "image/webp", sniff: "webp" as const },
+  { rel: "assets/cover.jpg", type: "image/jpeg", sniff: "jpeg" as const },
+  { rel: "assets/cover.jpeg", type: "image/jpeg", sniff: "jpeg" as const },
+];
+
+/**
+ * GET /api/stories/:name/cover-asset — detect an agent-created cover image so the
+ * genesis pre-publish UI can offer it as the default cover without a manual file
+ * pick (#296). Returns the FIRST candidate that exists, with a byte-validated
+ * `valid` flag (so an oversize or spoofed cover is surfaced as a warning and not
+ * offered/uploaded). `{ found: false }` when no candidate exists.
+ */
+stories.get("/:name/cover-asset", (c) => {
+  const name = safeName(c.req.param("name"));
+  if (!name) return c.json({ error: "Invalid story name" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+
+  for (const cand of COVER_CANDIDATES) {
+    const full = path.join(storyDir, cand.rel);
+    if (!fs.existsSync(full) || !fs.statSync(full).isFile()) continue;
+
+    const size = fs.statSync(full).size;
+    let sniffed: SniffedType = "unknown";
+    try {
+      const fd = fs.openSync(full, "r");
+      try {
+        const head = Buffer.alloc(16);
+        const read = fs.readSync(fd, head, 0, 16, 0);
+        sniffed = sniffImageType(head.subarray(0, read));
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch { /* treat as unreadable → invalid below */ }
+
+    if (size > COVER_MAX_BYTES) {
+      return c.json({ found: true, valid: false, path: cand.rel, type: cand.type, size, error: `${cand.rel} is ${(size / 1024).toFixed(0)}KB, exceeds the 1MB cover limit` });
+    }
+    if (sniffed !== cand.sniff) {
+      return c.json({ found: true, valid: false, path: cand.rel, type: cand.type, size, error: `${cand.rel} is not a valid ${cand.sniff.toUpperCase()} image (file contents do not match)` });
+    }
+    return c.json({ found: true, valid: true, path: cand.rel, type: cand.type, size });
+  }
+
+  return c.json({ found: false });
+});
+
+/** Cover state for the story progress overview (#418): present / invalid / missing. */
+function detectCoverState(storyDir: string): "missing" | "present" | "invalid" {
+  for (const cand of COVER_CANDIDATES) {
+    const full = path.join(storyDir, cand.rel);
+    if (!fs.existsSync(full) || !fs.statSync(full).isFile()) continue;
+    const size = fs.statSync(full).size;
+    if (size > COVER_MAX_BYTES) return "invalid";
+    let sniffed: SniffedType = "unknown";
+    try {
+      const fd = fs.openSync(full, "r");
+      try {
+        const head = Buffer.alloc(16);
+        const read = fs.readSync(fd, head, 0, 16, 0);
+        sniffed = sniffImageType(head.subarray(0, read));
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch { return "invalid"; }
+    return sniffed === cand.sniff ? "present" : "invalid";
+  }
+  return "missing";
+}
+
+/**
+ * GET /api/stories/:name/progress — story-level production progress map (#418).
+ *
+ * Aggregates the story's metadata, setup, cover, and per-episode state into one
+ * workflow overview so a writer sees what's done and what's next without reading
+ * file names or terminal output. Cartoon episodes reuse the same readiness
+ * classifier as the per-file publish UI (so a placeholder plot reads as
+ * "placeholder", never publish-ready); fiction gets a simpler written/published
+ * view. Pure aggregation — no wallet/publish side effects.
+ */
+stories.get("/:name/progress", (c) => {
+  const name = safeName(c.req.param("name"));
+  if (!name) return c.json({ error: "Invalid story name" }, 400);
+  const storyDir = path.join(STORIES_DIR, name);
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  const info = scanStory(storyDir, name);
+  const statusByFile = new Map(info.files.map((f) => [f.file, f.status]));
+
+  // Episodes in reader order: Genesis (Episode 1) first, then plot-NN.
+  const episodeFiles = [
+    ...(info.hasGenesis ? ["genesis.md"] : []),
+    ...info.files
+      .map((f) => f.file)
+      .filter((f) => /^plot-\d+\.md$/.test(f))
+      .sort((a, b) => parseInt(a.match(/\d+/)![0], 10) - parseInt(b.match(/\d+/)![0], 10)),
+  ];
+
+  const episodes = episodeFiles.map((file) => {
+    const plotFile = file.replace(/\.md$/, "");
+    let markdown = "";
+    try { markdown = fs.readFileSync(path.join(storyDir, file), "utf-8"); } catch { /* missing */ }
+    let cuts = null;
+    let title: string | null = null;
+    try {
+      const cutsFile = readCutsFile(storyDir, plotFile);
+      if (cutsFile) { cuts = cutsFile.cuts; title = typeof cutsFile.title === "string" ? cutsFile.title : null; }
+    } catch { /* invalid cuts ⇒ treat as none */ }
+    return { file, status: statusByFile.get(file) ?? ("pending" as const), markdown, cuts, title };
+  });
+
+  const progress = buildStoryProgress({
+    name,
+    contentType: info.contentType,
+    title: info.title,
+    language: info.language ?? null,
+    genre: info.genre ?? null,
+    isNsfw: info.isNsfw ?? null,
+    hasStructure: info.hasStructure,
+    hasGenesis: info.hasGenesis,
+    cover: detectCoverState(storyDir),
+    episodes,
+  });
+
+  // Persistent workflow coach (#429): one next action for the current state.
+  // `?focus=<file>` makes it speak about the file the writer is viewing (so a
+  // future-episode placeholder reads as "plan this first"); without it the coach
+  // tracks the story's active episode. We also scan each cartoon episode for
+  // clean images that are on disk but not yet recorded in cuts.json, so the
+  // clean-image stage can offer "Refresh assets" instead of "Generate" (#427).
+  let coach = null;
+  if (info.contentType === "cartoon") {
+    const focusFile = c.req.query("focus") || null;
+    const undetectedCleanByFile: Record<string, number> = {};
+    for (const ep of episodes) {
+      if (!ep.cuts) continue;
+      let undetected = 0;
+      for (const cut of ep.cuts) {
+        if (cut.cleanImagePath !== null) continue;
+        const plotFile = ep.file.replace(/\.md$/, "");
+        if (cleanImageCandidates(plotFile, cut.id).some((rel) => isValidImageAsset(storyDir, rel))) undetected++;
+      }
+      if (undetected > 0) undetectedCleanByFile[ep.file] = undetected;
+    }
+    coach = deriveCartoonCoach(progress, { focusFile, undetectedCleanByFile });
+  }
+
+  return c.json({ ...progress, coach });
+});
+
+/**
+ * POST /api/stories/:name/import-cover — save a browser-converted cover image as
+ * the deterministic local asset `assets/cover.webp` (or `.jpg`) so a
+ * Codex-generated image can become a compliant cover without agent-side shell
+ * image tools (#301). The browser canvas path (import-image.ts) does the
+ * PNG→WebP conversion and size compression; this route only validates and
+ * persists. Mirrors the upload-clean byte/size checks: WebP/JPEG only, <=1MB,
+ * magic-byte validated so a renamed/oversize file cannot land as a cover.
+ *
+ * To keep #296 auto-detection unambiguous (it returns the FIRST existing
+ * candidate in webp>jpg>jpeg order), any sibling cover.* files are removed so
+ * exactly one cover asset remains after a successful import.
+ */
+stories.post("/:name/import-cover", async (c) => {
+  const name = safeName(c.req.param("name"));
+  if (!name) return c.json({ error: "Invalid story name" }, 400);
+
+  const storyDir = path.join(STORIES_DIR, name);
+  if (!fs.existsSync(storyDir) || !fs.statSync(storyDir).isDirectory()) {
+    return c.json({ error: "Story not found" }, 404);
+  }
+
+  let formData: FormData;
+  try {
+    formData = await c.req.formData();
+  } catch {
+    return c.json({ error: "No file provided" }, 400);
+  }
+  const file = formData.get("file") as File | Blob | null;
+  if (!file || typeof file === "string") {
+    return c.json({ error: "No file provided" }, 400);
+  }
+
+  if (file.size > 1024 * 1024) {
+    return c.json({ error: "File must be under 1MB" }, 400);
+  }
+
+  const mime = file.type;
+  if (mime !== "image/webp" && mime !== "image/jpeg") {
+    return c.json({ error: "Only WebP and JPEG images are supported" }, 400);
+  }
+
+  // Validate by actual bytes, not the spoofable MIME label, so an unconverted
+  // PNG (or renamed text file) cannot be persisted as a cover. Mirrors
+  // upload-clean (#266).
+  const buffer = Buffer.from(await file.arrayBuffer());
+  if (!cleanImageBytesMatchMime(buffer, mime)) {
+    return c.json(
+      { error: "File content is not a valid WebP/JPEG image (bytes do not match the image type)" },
+      400,
+    );
+  }
+
+  const assetDir = path.join(storyDir, "assets");
+  fs.mkdirSync(assetDir, { recursive: true });
+
+  // Remove any existing cover.* so detection resolves to exactly this import.
+  for (const cand of COVER_CANDIDATES) {
+    const full = path.join(storyDir, cand.rel);
+    if (fs.existsSync(full)) fs.rmSync(full, { force: true });
+  }
+
+  const ext = mime === "image/webp" ? "webp" : "jpg";
+  const coverPath = `assets/cover.${ext}`;
+  fs.writeFileSync(path.join(storyDir, coverPath), buffer);
+
+  return c.json({ ok: true, path: coverPath, type: mime, size: buffer.length });
+});
+
+/** GET /api/stories/:name/asset/:assetPath — serve story asset file (supports nested paths) */
+// NOTE: uses a regex splat param (`{.+}`) rather than a bare `*` wildcard.
+// Hono v4 does not populate `c.req.param("*")` for a mixed named/wildcard route
+// like `/:name/asset/*`, so the handler always saw an empty assetPath and
+// returned 400 — which surfaced as "Image not available" in the UI once the
+// clean-image loaders actually started sending the auth header (#278). The
+// regex param captures the remaining path, including slashes, and is readable
+// back by name.
+stories.get("/:name/asset/:assetPath{.+}", (c) => {
+  const name = safeName(c.req.param("name"));
+  if (!name) return c.json({ error: "Invalid story name" }, 400);
+
+  const assetPath = c.req.param("assetPath");
+  if (!assetPath) return c.json({ error: "Invalid asset path" }, 400);
+
+  if (assetPath.includes("..") || assetPath.startsWith("/")) {
+    return c.json({ error: "Invalid asset path" }, 400);
+  }
+
+  const fullPath = path.join(STORIES_DIR, name, "assets", assetPath);
+  const resolved = path.resolve(fullPath);
+  const assetsRoot = path.resolve(path.join(STORIES_DIR, name, "assets"));
+  if (!resolved.startsWith(assetsRoot + path.sep) && resolved !== assetsRoot) {
+    return c.json({ error: "Invalid asset path" }, 400);
+  }
+
+  if (!fs.existsSync(resolved)) {
+    return c.json({ error: "Asset not found" }, 404);
+  }
+
+  const ext = path.extname(resolved).toLowerCase();
+  const mimeTypes: Record<string, string> = {
+    ".webp": "image/webp",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+  };
+  const ct = mimeTypes[ext] || "application/octet-stream";
+
+  const data = fs.readFileSync(resolved);
+  return new Response(data, {
+    headers: { "Content-Type": ct, "Cache-Control": "no-cache" },
+  });
+});
+
 /** GET /api/stories/:name/:file — single file content */
 stories.get("/:name/:file", (c) => {
   const name = safeName(c.req.param("name"));
@@ -290,4 +1246,4 @@ stories.post("/:name/:file/mark-not-indexed", async (c) => {
   return c.json({ ok: true });
 });
 
-export { stories as storiesRoutes, readPublishStatus, STORIES_DIR };
+export { stories as storiesRoutes, readPublishStatus, readStoryMeta, writeStoryMeta, saveExportedCut, STORIES_DIR };