npm - plotlink-ows - Versions diffs - 1.0.33 → 1.2.95 - Mend

plotlink-ows 1.0.33 → 1.2.95

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (152) hide show

package/README.md +4 -0
package/app/lib/active-wallet.ts +260 -0
package/app/lib/agent-command.ts +85 -0
package/app/lib/agent-readiness.ts +133 -0
package/app/lib/apply-schema.ts +55 -0
package/app/lib/bubble-text.ts +160 -0
package/app/lib/cartoon-coach.ts +198 -0
package/app/lib/cartoon-markdown.ts +83 -0
package/app/lib/cartoon-prompt.ts +122 -0
package/app/lib/cartoon-readiness.ts +813 -0
package/app/lib/clean-image-sync.ts +245 -0
package/app/lib/codex-images.ts +152 -0
package/app/lib/cut-asset-diagnostics.ts +120 -0
package/app/lib/cuts.ts +302 -0
package/app/lib/fonts.ts +109 -0
package/app/lib/generate-claude-md.ts +8 -1
package/app/lib/generate-story-instructions.ts +731 -0
package/app/lib/image-asset-validate.ts +123 -0
package/app/lib/lettering-status.ts +133 -0
package/app/lib/overlays.ts +637 -0
package/app/lib/paths.ts +10 -0
package/app/lib/public-title.ts +65 -0
package/app/lib/publish.ts +16 -2
package/app/lib/story-progress.ts +242 -0
package/app/lib/terminal-protocol.ts +16 -0
package/app/lib/terminal-redact.ts +50 -0
package/app/prisma/schema.sql +25 -0
package/app/routes/agent.ts +42 -0
package/app/routes/codex-images.ts +67 -0
package/app/routes/dashboard.ts +6 -4
package/app/routes/publish.ts +259 -45
package/app/routes/settings.ts +92 -37
package/app/routes/stories.ts +961 -5
package/app/routes/terminal.ts +383 -31
package/app/routes/wallet.ts +58 -30
package/app/server.ts +47 -12
package/app/vite.config.ts +6 -0
package/app/web/components/CartoonNextAction.tsx +145 -0
package/app/web/components/CartoonPreview.tsx +267 -0
package/app/web/components/CartoonPublishPage.tsx +407 -0
package/app/web/components/CartoonPublishPreview.tsx +121 -0
package/app/web/components/CartoonStepGuide.tsx +90 -0
package/app/web/components/CartoonWorkflowNav.tsx +68 -0
package/app/web/components/CodexImportPicker.tsx +230 -0
package/app/web/components/CutListPanel.tsx +1337 -0
package/app/web/components/Dashboard.tsx +15 -6
package/app/web/components/EpisodesPage.tsx +80 -0
package/app/web/components/FinishEpisodePanel.tsx +151 -0
package/app/web/components/Layout.tsx +7 -4
package/app/web/components/LetteringEditor.tsx +1182 -0
package/app/web/components/PreviewPanel.tsx +952 -78
package/app/web/components/Settings.tsx +63 -0
package/app/web/components/StoriesPage.tsx +745 -33
package/app/web/components/StoryBrowser.tsx +22 -14
package/app/web/components/StoryInfoPage.tsx +266 -0
package/app/web/components/StoryProgressPanel.tsx +446 -0
package/app/web/components/TerminalPanel.tsx +233 -11
package/app/web/components/WalletCard.tsx +110 -8
package/app/web/components/WorkflowCoach.tsx +156 -0
package/app/web/components/asset-image.tsx +114 -0
package/app/web/components/asset-test-utils.ts +44 -0
package/app/web/components/export-cut.ts +320 -0
package/app/web/dist/assets/export-cut-che5mMWc.js +1 -0
package/app/web/dist/assets/index-CcfChGEK.css +32 -0
package/app/web/dist/assets/index-Dc2TQ3Ij.js +143 -0
package/app/web/dist/index.html +2 -2
package/app/web/lib/cartoon-publish-summary.ts +43 -0
package/app/web/lib/codex-import.ts +94 -0
package/app/web/lib/image-compress.ts +53 -0
package/app/web/lib/import-image.ts +58 -0
package/app/web/lib/publish-helpers.ts +385 -0
package/app/web/lib/upload-retry.ts +130 -0
package/app/web/lib/verify-public-title.ts +105 -0
package/app/web/styles.css +9 -0
package/bin/plotlink-ows.js +53 -16
package/bin/startup-plan.cjs +58 -0
package/lib/genres.ts +92 -0
package/package.json +60 -20
package/scripts/gen-schema-sql.mjs +49 -0
package/scripts/package-hygiene.mjs +116 -0
package/scripts/preflight.mjs +173 -0
package/scripts/start-smoke.mjs +128 -0
package/app/node_modules/.prisma/local-client/client.d.ts +0 -1
package/app/node_modules/.prisma/local-client/client.js +0 -5
package/app/node_modules/.prisma/local-client/default.d.ts +0 -1
package/app/node_modules/.prisma/local-client/default.js +0 -5
package/app/node_modules/.prisma/local-client/edge.d.ts +0 -1
package/app/node_modules/.prisma/local-client/edge.js +0 -184
package/app/node_modules/.prisma/local-client/index-browser.js +0 -173
package/app/node_modules/.prisma/local-client/index.d.ts +0 -3304
package/app/node_modules/.prisma/local-client/index.js +0 -207
package/app/node_modules/.prisma/local-client/libquery_engine-darwin-arm64.dylib.node +0 -0
package/app/node_modules/.prisma/local-client/package.json +0 -183
package/app/node_modules/.prisma/local-client/query_engine_bg.js +0 -2
package/app/node_modules/.prisma/local-client/query_engine_bg.wasm +0 -0
package/app/node_modules/.prisma/local-client/runtime/edge-esm.js +0 -35
package/app/node_modules/.prisma/local-client/runtime/edge.js +0 -35
package/app/node_modules/.prisma/local-client/runtime/index-browser.d.ts +0 -370
package/app/node_modules/.prisma/local-client/runtime/index-browser.js +0 -17
package/app/node_modules/.prisma/local-client/runtime/library.d.ts +0 -3982
package/app/node_modules/.prisma/local-client/runtime/library.js +0 -147
package/app/node_modules/.prisma/local-client/runtime/react-native.js +0 -84
package/app/node_modules/.prisma/local-client/runtime/wasm-compiler-edge.js +0 -85
package/app/node_modules/.prisma/local-client/runtime/wasm-engine-edge.js +0 -38
package/app/node_modules/.prisma/local-client/schema.prisma +0 -21
package/app/node_modules/.prisma/local-client/wasm-edge-light-loader.mjs +0 -5
package/app/node_modules/.prisma/local-client/wasm-worker-loader.mjs +0 -5
package/app/node_modules/.prisma/local-client/wasm.d.ts +0 -1
package/app/node_modules/.prisma/local-client/wasm.js +0 -191
package/app/web/dist/assets/index-B-2Ft7Yv.css +0 -32
package/app/web/dist/assets/index-DxATSk7X.js +0 -134
package/packages/cli/node_modules/commander/LICENSE +0 -22
package/packages/cli/node_modules/commander/Readme.md +0 -1149
package/packages/cli/node_modules/commander/esm.mjs +0 -16
package/packages/cli/node_modules/commander/index.js +0 -24
package/packages/cli/node_modules/commander/lib/argument.js +0 -149
package/packages/cli/node_modules/commander/lib/command.js +0 -2662
package/packages/cli/node_modules/commander/lib/error.js +0 -39
package/packages/cli/node_modules/commander/lib/help.js +0 -709
package/packages/cli/node_modules/commander/lib/option.js +0 -367
package/packages/cli/node_modules/commander/lib/suggestSimilar.js +0 -101
package/packages/cli/node_modules/commander/package-support.json +0 -16
package/packages/cli/node_modules/commander/package.json +0 -82
package/packages/cli/node_modules/commander/typings/esm.d.mts +0 -3
package/packages/cli/node_modules/commander/typings/index.d.ts +0 -1045
package/packages/cli/node_modules/resolve-from/index.d.ts +0 -31
package/packages/cli/node_modules/resolve-from/index.js +0 -47
package/packages/cli/node_modules/resolve-from/license +0 -9
package/packages/cli/node_modules/resolve-from/package.json +0 -36
package/packages/cli/node_modules/resolve-from/readme.md +0 -72
package/packages/cli/node_modules/tsup/LICENSE +0 -21
package/packages/cli/node_modules/tsup/README.md +0 -75
package/packages/cli/node_modules/tsup/assets/cjs_shims.js +0 -13
package/packages/cli/node_modules/tsup/assets/esm_shims.js +0 -9
package/packages/cli/node_modules/tsup/assets/package.json +0 -3
package/packages/cli/node_modules/tsup/dist/chunk-DI5BO6XE.js +0 -153
package/packages/cli/node_modules/tsup/dist/chunk-JZ25TPTY.js +0 -42
package/packages/cli/node_modules/tsup/dist/chunk-PEEXUWMS.js +0 -6
package/packages/cli/node_modules/tsup/dist/chunk-TWFEYLU4.js +0 -352
package/packages/cli/node_modules/tsup/dist/chunk-VGC3FXLU.js +0 -203
package/packages/cli/node_modules/tsup/dist/cli-default.js +0 -12
package/packages/cli/node_modules/tsup/dist/cli-main.js +0 -8
package/packages/cli/node_modules/tsup/dist/cli-node.js +0 -14
package/packages/cli/node_modules/tsup/dist/index.d.ts +0 -511
package/packages/cli/node_modules/tsup/dist/index.js +0 -1711
package/packages/cli/node_modules/tsup/dist/rollup.js +0 -6949
package/packages/cli/node_modules/tsup/package.json +0 -99
package/packages/cli/node_modules/tsup/schema.json +0 -362
package/public/screenshot-1.png +0 -0
package/public/screenshot-2.png +0 -0
package/public/screenshot-3.png +0 -0
package/scripts/e2e-verify.ts +0 -1100

package/app/web/dist/index.html CHANGED Viewed

@@ -7,8 +7,8 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Lora:wght@400;600;700&family=Geist+Mono:wght@400;500&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-DxATSk7X.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-B-2Ft7Yv.css">
+    <script type="module" crossorigin src="/assets/index-Dc2TQ3Ij.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CcfChGEK.css">
   </head>
   <body>
     <div id="root"></div>

package/app/web/lib/cartoon-publish-summary.ts ADDED Viewed

@@ -0,0 +1,43 @@
+// Pre-publish summary of cartoon publish markdown (#289).
+//
+// The OWS publish preview must show exactly what PlotLink will render — image
+// blocks plus ANY non-image prose actually present in the markdown — separate
+// from the cuts.json planning inspector. This helper derives a compact summary
+// (image count, char count, and the non-image prose that would be published) so
+// the operator can see at a glance whether planning/placeholder text leaked into
+// the immutable markdown (the failure mode behind #286).
+export interface CartoonMarkdownSummary {
+  imageCount: number;
+  charCount: number;
+  /** Visible non-image, non-marker text that would be published as prose. */
+  nonImageProse: string;
+  /** First 200 chars of nonImageProse, for a compact pre-publish summary. */
+  nonImageProsePreview: string;
+}
+const IMAGE_RE = /!\[[^\]]*\]\([^)]*\)/g;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+/** Length of the non-image prose excerpt surfaced in the pre-publish summary. */
+export const PROSE_PREVIEW_LIMIT = 200;
+export function summarizeCartoonMarkdown(markdown: string): CartoonMarkdownSummary {
+  const imageCount = (markdown.match(IMAGE_RE) || []).length;
+  const charCount = markdown.length;
+  // Strip ows:cartoon-cut markers (HTML comments) and image references; whatever
+  // remains is text that PlotLink would publish verbatim around the images.
+  const nonImageProse = markdown
+    .replace(HTML_COMMENT_RE, " ")
+    .replace(IMAGE_RE, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return {
+    imageCount,
+    charCount,
+    nonImageProse,
+    nonImageProsePreview: nonImageProse.slice(0, PROSE_PREVIEW_LIMIT),
+  };
+}

package/app/web/lib/codex-import.ts ADDED Viewed

@@ -0,0 +1,94 @@
+// Codex generated-image cache handoff (#403) — client side.
+//
+// Built-in image generation drops finished cartoon art into a hidden cache
+// (`~/.codex/generated_images/.../ig_<hash>.png`) as a PNG, usually > 1MB. OWS
+// only records WebP/JPEG <= 1MB clean assets, and the agent terminal is forbidden
+// from converting the file itself (#297). Rather than make the writer hunt through
+// that hidden folder in an OS file dialog, the OWS app lists the cache (read-only,
+// authenticated) and lets the writer import one generated image straight into a
+// cut — the browser converts the PNG exactly like the existing manual upload
+// (importImageToCompliantBlob), so the upload route and its validation are
+// unchanged.
+//
+// This module owns the two read-only calls to the `/api/codex` routes: list the
+// cache, and fetch one cache image's raw bytes as a File ready for the existing
+// import/upload pipeline. Kept thin and free of React so the fetch→File wiring is
+// unit-testable.
+/** One entry in the Codex generated-image cache, as returned by GET /api/codex/images. */
+export interface CodexCacheImage {
+  /** Opaque, path-safe token addressing this cache file (relative to the root). */
+  token: string;
+  /** Base file name, e.g. `ig_0f26….png`, for display. */
+  name: string;
+  /** Raw file size in bytes (pre-conversion). */
+  size: number;
+  /** Last-modified time (ms since epoch); the server lists newest first. */
+  mtimeMs: number;
+}
+type AuthFetch = (url: string, opts?: RequestInit) => Promise<Response>;
+/** Narrow an unknown listing entry to a well-formed CodexCacheImage. */
+function isCacheImage(v: unknown): v is CodexCacheImage {
+  if (!v || typeof v !== "object") return false;
+  const o = v as Record<string, unknown>;
+  return (
+    typeof o.token === "string" &&
+    o.token.length > 0 &&
+    typeof o.name === "string" &&
+    typeof o.size === "number" &&
+    typeof o.mtimeMs === "number"
+  );
+}
+/**
+ * List recent Codex-generated cache images, newest first. Best-effort: a non-OK
+ * response or a malformed body yields `[]` (the cache is optional infrastructure —
+ * a writer without Codex installed simply sees no import option), and only
+ * well-formed entries are kept.
+ */
+export async function listCodexCacheImages(authFetch: AuthFetch): Promise<CodexCacheImage[]> {
+  let res: Response;
+  try {
+    res = await authFetch("/api/codex/images");
+  } catch {
+    return [];
+  }
+  if (!res.ok) return [];
+  let data: unknown;
+  try {
+    data = await res.json();
+  } catch {
+    return [];
+  }
+  const images = (data as { images?: unknown })?.images;
+  if (!Array.isArray(images)) return [];
+  return images.filter(isCacheImage);
+}
+/**
+ * Fetch one cache image's raw bytes and wrap them in a File ready for the existing
+ * per-cut import pipeline (importImageToCompliantBlob → upload-clean). The File
+ * keeps the cache entry's name and the response's real content type, so a large
+ * PNG flows through the same in-browser conversion a manually-picked PNG does.
+ * Throws a clear, user-facing error when the image can't be fetched, so callers
+ * surface the gap instead of importing nothing silently.
+ */
+export async function fetchCodexCacheFile(
+  authFetch: AuthFetch,
+  image: CodexCacheImage,
+): Promise<File> {
+  let res: Response;
+  try {
+    res = await authFetch(`/api/codex/images/${encodeURIComponent(image.token)}`);
+  } catch {
+    throw new Error("Could not read the generated image from the Codex cache");
+  }
+  if (!res.ok) {
+    throw new Error("Could not read the generated image from the Codex cache");
+  }
+  const blob = await res.blob();
+  const type = blob.type || res.headers.get("Content-Type") || "image/png";
+  return new File([blob], image.name || "codex-image.png", { type });
+}

package/app/web/lib/image-compress.ts ADDED Viewed

@@ -0,0 +1,53 @@
+// Shared client-side image compression policy. A single source of truth for the
+// "fit a canvas into a PlotLink-compliant (WebP/JPEG, <=1MB) image" routine so
+// the lettering export (export-cut.ts) and the Codex-image import path
+// (import-image.ts, #301) compress identically — both produce assets the
+// upload/import endpoints accept without any agent-side shell image tools.
+/** PlotLink hard limit for cover / clean / final cartoon assets. */
+export const MAX_IMAGE_BYTES = 1024 * 1024;
+function canvasToBlob(
+  canvas: HTMLCanvasElement,
+  format: string,
+  quality: number,
+): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => (blob ? resolve(blob) : reject(new Error(`Failed to export as ${format}`))),
+      format,
+      quality,
+    );
+  });
+}
+/**
+ * Compress a canvas to a WebP (preferred) or JPEG Blob no larger than
+ * MAX_IMAGE_BYTES. Tries descending WebP qualities first; if the browser cannot
+ * encode WebP (toBlob silently falls back to PNG) it drops to JPEG. Throws a
+ * clear, user-facing error when even the lowest-quality JPEG exceeds the limit,
+ * so callers can surface "could not compress under 1MB" rather than silently
+ * uploading an oversize asset.
+ */
+export async function compressCanvasToBlob(canvas: HTMLCanvasElement): Promise<Blob> {
+  const webpQualities = [0.9, 0.8, 0.7, 0.6];
+  for (const q of webpQualities) {
+    try {
+      const blob = await canvasToBlob(canvas, "image/webp", q);
+      // A browser without WebP encoding returns image/png here — stop trying
+      // WebP and fall through to the JPEG ladder rather than emit a PNG.
+      if (blob.type !== "image/webp") break;
+      if (blob.size <= MAX_IMAGE_BYTES) return blob;
+    } catch {
+      break;
+    }
+  }
+  const jpegQualities = [0.85, 0.7, 0.5];
+  for (const q of jpegQualities) {
+    const blob = await canvasToBlob(canvas, "image/jpeg", q);
+    if (blob.size <= MAX_IMAGE_BYTES) return blob;
+  }
+  throw new Error("Cannot compress image under 1MB — reduce overlay count or image size");
+}

package/app/web/lib/import-image.ts ADDED Viewed

@@ -0,0 +1,58 @@
+import { compressCanvasToBlob, MAX_IMAGE_BYTES } from "./image-compress";
+// OWS-owned import path for Codex-generated cartoon images (#301).
+//
+// Codex image generation often lands a large PNG in its local cache. OWS only
+// accepts WebP/JPEG <=1MB for cover (assets/cover.webp) and clean
+// (assets/plot-NN/cut-XX-clean.webp) assets, and #297 correctly forbids the
+// agent from shelling out to ImageMagick/sharp/Playwright to convert it. This
+// converts a selected local image entirely in the browser (canvas), so a PNG
+// becomes a compliant asset with no agent-side image tooling.
+/** Image MIME types the import/upload endpoints accept as-is. */
+const COMPLIANT_TYPES = ["image/webp", "image/jpeg"];
+/** True when a file already satisfies the PlotLink asset constraints. */
+export function isCompliantImage(file: { type: string; size: number }): boolean {
+  return COMPLIANT_TYPES.includes(file.type) && file.size <= MAX_IMAGE_BYTES;
+}
+async function decodeToCanvas(file: File): Promise<HTMLCanvasElement> {
+  if (typeof createImageBitmap !== "function") {
+    throw new Error("This browser cannot decode the image for import");
+  }
+  let bitmap: ImageBitmap;
+  try {
+    bitmap = await createImageBitmap(file);
+  } catch {
+    throw new Error("Could not read the selected image — pick a PNG, WebP, or JPEG file");
+  }
+  try {
+    const canvas = document.createElement("canvas");
+    canvas.width = bitmap.width;
+    canvas.height = bitmap.height;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) throw new Error("Could not process the image for import");
+    ctx.drawImage(bitmap, 0, 0);
+    return canvas;
+  } finally {
+    // Release decoded pixels promptly; large PNGs are the common input here.
+    bitmap.close?.();
+  }
+}
+/**
+ * Convert a locally-selected image (PNG, WebP, JPEG, …) into a PlotLink-compliant
+ * WebP/JPEG Blob <=1MB. Already-compliant files are returned untouched (no
+ * re-encode, preserving quality and the existing manual upload behavior).
+ * Throws a clear, user-facing error when the source cannot be decoded or cannot
+ * be compressed under 1MB, so callers surface the gap instead of saving an
+ * invalid asset.
+ */
+export async function importImageToCompliantBlob(file: File): Promise<Blob> {
+  if (isCompliantImage(file)) return file;
+  const canvas = await decodeToCanvas(file);
+  return compressCanvasToBlob(canvas);
+}
+export { MAX_IMAGE_BYTES };

package/app/web/lib/publish-helpers.ts ADDED Viewed

@@ -0,0 +1,385 @@
+/** Cover image constraints enforced by the plotlink backend. */
+export const COVER_MAX_BYTES = 1024 * 1024;
+export const COVER_ALLOWED_TYPES = ["image/webp", "image/jpeg"] as const;
+/**
+ * Writer-facing cover requirements, surfaced in the cartoon cover step (#337):
+ * the enforced format/size plus the recommended portrait shape and a reminder to
+ * use clean cover art (AI-generated lettering often renders as unreadable text).
+ */
+export const COVER_GUIDANCE =
+  "Cover: WebP or JPEG, max 1MB, 600×900 portrait recommended. Use clean cover art — avoid unreadable AI text or broken lettering.";
+export type CoverReadinessState = "none" | "selected" | "invalid" | "attached";
+export interface CoverReadiness {
+  state: CoverReadinessState;
+  /** Short writer-facing status line. */
+  label: string;
+  /** Visual tone hint for the badge. */
+  tone: "muted" | "accent" | "error" | "success";
+}
+/**
+ * Resolve the cartoon cover readiness shown next to publish (#337) so a writer
+ * always sees whether a cover is missing, queued, invalid, or attached before
+ * the story goes out. Precedence: an already-attached storyline cover wins;
+ * then an invalid selection (so the error is never hidden by a stale pick);
+ * then a valid local cover queued for upload; otherwise none yet.
+ */
+export function cartoonCoverReadiness(input: {
+  /** A valid local cover file is queued (will upload at publish). */
+  hasSelectedCover: boolean;
+  /** The latest selection/detection was rejected (wrong type / too large). */
+  invalid: boolean;
+  /** A cover is already attached on the published storyline. */
+  attached: boolean;
+}): CoverReadiness {
+  if (input.attached) {
+    return { state: "attached", label: "Cover attached to your story.", tone: "success" };
+  }
+  if (input.invalid) {
+    return { state: "invalid", label: "Cover file can't be used — must be WebP or JPEG, max 1MB.", tone: "error" };
+  }
+  if (input.hasSelectedCover) {
+    return { state: "selected", label: "Cover selected — it will be uploaded when you publish.", tone: "accent" };
+  }
+  return { state: "none", label: "No cover yet — add one before publishing (recommended).", tone: "muted" };
+}
+/**
+ * Validate a chosen story cover against the constraints the plotlink backend
+ * enforces (WebP/JPEG, ≤1MB) so the writer gets immediate feedback at selection
+ * rather than a late error at save. Pure — takes only size/type — and shared by
+ * fiction and cartoon (the cover route is content-type agnostic). The 600x900
+ * portrait guidance is a recommendation and is not enforced here. Returns a
+ * user-facing error string, or null when the file is acceptable.
+ */
+export function validateCoverImage(file: { size: number; type: string }): string | null {
+  if (file.size > COVER_MAX_BYTES) return "Image exceeds 1MB limit";
+  if (!(COVER_ALLOWED_TYPES as readonly string[]).includes(file.type)) {
+    return "Only WebP and JPEG images are accepted";
+  }
+  return null;
+}
+type AuthFetch = (url: string, opts?: RequestInit) => Promise<Response>;
+/**
+ * Attach a pre-publish cover to a freshly-created storyline. The on-chain
+ * `createStoryline` flow can't carry a cover CID, so after a genesis publishes
+ * we upload the selected cover (byte-validated server-side, #281) and set it via
+ * the existing `update-storyline` endpoint — the same two-step the published
+ * Edit Story panel uses. Best-effort: a failed upload OR a failed
+ * update-storyline returns null, so the storyline still stands and the writer
+ * can set a cover later via Edit Story. Returns the cover CID only when the
+ * cover was actually attached (both steps succeeded), else null.
+ */
+export async function attachCoverToStoryline(
+  authFetch: AuthFetch,
+  storylineId: number,
+  coverFile: File,
+): Promise<string | null> {
+  const fd = new FormData();
+  fd.append("file", coverFile);
+  const upRes = await authFetch("/api/publish/upload-cover", { method: "POST", body: fd });
+  if (!upRes.ok) return null;
+  const { cid } = (await upRes.json()) as { cid?: string };
+  if (!cid) return null;
+  const updRes = await authFetch("/api/publish/update-storyline", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ storylineId, coverCid: cid }),
+  });
+  // The cover is only attached if update-storyline also succeeds; a non-ok
+  // response means the cover was uploaded but never set on the storyline.
+  if (!updRes.ok) return null;
+  return cid;
+}
+/** The first markdown H1 (`# Title`) in `content`, trimmed; null when none. */
+export function extractH1Title(content: string): string | null {
+  const m = content.match(/^#\s+(.+)$/m);
+  const t = m ? m[1].trim() : "";
+  return t ? t : null;
+}
+/**
+ * Prettify a story folder slug into a human title:
+ * "swipe-right-refund-later" → "Swipe Right Refund Later". Used only as the
+ * last-resort genesis title so a storyline never publishes as the bare
+ * "genesis" filename.
+ */
+export function prettifyStorySlug(slug: string): string {
+  return slug
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .split(" ")
+    .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(" ");
+}
+/**
+ * Whether a resolved publish title is still a raw internal filename label
+ * ("genesis"/"Genesis" for genesis.md, "plot-NN" for a plot) rather than a
+ * reader-facing title (#358). The publish panel blocks on this so a cartoon
+ * story can't ship raw labels (which are immutable once on-chain). Compared
+ * case-insensitively and trimmed.
+ */
+export function isRawFilenameTitle(title: string, fileName: string): boolean {
+  const t = (title ?? "").trim().toLowerCase();
+  if (!t) return true;
+  if (fileName === "genesis.md") return t === "genesis";
+  const m = fileName.match(/^(plot-\d+)\.md$/);
+  if (m) return t === m[1].toLowerCase() || /^plot-\d+$/.test(t);
+  return false;
+}
+/**
+ * Friendly episode title from a plot filename (#347): "plot-01.md" → "Episode
+ * 01" (numbering preserved, padded to ≥2 digits). Returns null for a non-plot
+ * filename. Used as the last-resort cartoon episode title so an episode never
+ * publishes as the raw "plot-NN" filename.
+ */
+export function episodeTitleFromPlotFile(fileName: string): string | null {
+  const m = fileName.match(/^plot-(\d+)\.md$/);
+  if (!m) return null;
+  const n = m[1];
+  return `Episode ${n.length < 2 ? n.padStart(2, "0") : n}`;
+}
+/**
+ * Whether a cartoon episode title is just a GENERIC number label rather than a
+ * reader-facing title (#368): "Episode 01", "Episode 1", "Ep. 01", "Chapter 01",
+ * "Plot 01", "plot-01", or a bare number. These pass #365's "has a title" check
+ * (they're a real H1 / cut-plan title) but are still placeholders that don't meet
+ * webtoon metadata quality, so they must not publish.
+ *
+ * A title that pairs a number with actual title text — "Episode 01 — The Couple
+ * Coupon" — is NOT generic (the regex anchors `$` right after the number, so any
+ * trailing title text fails the match). Compared trimmed / case-insensitive.
+ */
+export function isGenericEpisodeTitle(title: string): boolean {
+  const t = (title ?? "").trim();
+  if (!t) return true;
+  // A generic label word (episode/ep/chapter/ch/part/pt/plot) + a number, with
+  // nothing meaningful after the number.
+  if (/^(?:episode|ep|chapter|ch|part|pt|plot)\.?\s*[-–—:#]?\s*\d+$/i.test(t)) return true;
+  // A bare number ("01", "1"), or a raw filename-style "plot-01"/"plot_1".
+  if (/^\d+$/.test(t)) return true;
+  if (/^plot[-_\s]?\d+$/i.test(t)) return true;
+  return false;
+}
+/**
+ * Whether a cartoon plot has an EXPLICIT reader-facing episode title (#365,
+ * tightened by #368): a real `# Title` H1 in the plot markdown, or a non-empty
+ * cut-plan title — that is NOT a generic "Episode NN"/"Chapter NN"/"plot-NN"
+ * placeholder.
+ *
+ * #347/#358 stopped raw `plot-NN` titles from publishing by falling back to a
+ * friendly "Episode NN"; #365 made that fallback diagnostic-only. #368 closes the
+ * remaining gap: a real H1 or cut-plan title that is itself only a generic number
+ * label still doesn't satisfy publish-quality webtoon metadata, so it is rejected
+ * here too. Independent of the #358 raw-filename block, which is kept.
+ *
+ * The check must mirror `derivePublishTitle`'s SOURCE PRECEDENCE so the gate
+ * judges exactly what will publish: for a plot, the H1 wins when present, so a
+ * generic H1 blocks even if the cut-plan title is real (otherwise we'd pass on
+ * the cut title but publish the generic H1). Only when there is no H1 does the
+ * cut-plan title decide.
+ */
+export function hasExplicitEpisodeTitle(opts: { fileContent: string; episodeTitle?: string | null }): boolean {
+  const h1 = extractH1Title(opts.fileContent);
+  if (h1) return !isGenericEpisodeTitle(h1);
+  const cut = opts.episodeTitle?.trim() || null;
+  return !!cut && !isGenericEpisodeTitle(cut);
+}
+/**
+ * Resolve the title used when publishing a story file to PlotLink (#331, #347).
+ *
+ * The storyline title is set once, at genesis publish, and is immutable
+ * on-chain — so a headingless `genesis.md` must NOT fall back to the bare
+ * "genesis" filename. For `genesis.md` the title resolves:
+ *   1. an explicit `# Title` H1 inside genesis.md, then
+ *   2. the `# Title` H1 from the story's structure.md, then
+ *   3. a prettified story folder slug — never raw "genesis".
+ *
+ * For a plot file:
+ *   1. an explicit `# Title` H1 in plot-NN.md, then
+ *   2. for CARTOON content (its publish markdown is image-only by design, so it
+ *      usually has no H1): the cut plan's episode title, else a friendly
+ *      "Episode NN" — NEVER the raw "plot-NN" filename (#347).
+ *   3. for fiction: the prior H1-or-filename behavior, unchanged.
+ *
+ * A plot's title does not change the storyline title on-chain (createStoryline
+ * set it; chainPlot uses this for the chapter). Result is capped at 60 chars.
+ */
+export function derivePublishTitle(opts: {
+  fileName: string;
+  fileContent: string;
+  storySlug: string;
+  structureContent?: string | null;
+  contentType?: string;
+  /** Episode title from plot-NN.cuts.json, if any (cartoon). */
+  episodeTitle?: string | null;
+}): string {
+  const { fileName, fileContent, storySlug, structureContent, contentType, episodeTitle } = opts;
+  const ownH1 = extractH1Title(fileContent);
+  if (fileName === "genesis.md") {
+    const structureH1 = structureContent ? extractH1Title(structureContent) : null;
+    return (ownH1 ?? structureH1 ?? prettifyStorySlug(storySlug)).slice(0, 60);
+  }
+  // Plot file.
+  if (ownH1) return ownH1.slice(0, 60);
+  if (contentType === "cartoon") {
+    const fromCuts = episodeTitle?.trim();
+    const friendly = episodeTitleFromPlotFile(fileName);
+    return ((fromCuts || friendly) ?? fileName.replace(/\.md$/, "")).slice(0, 60);
+  }
+  return fileName.replace(/\.md$/, "").slice(0, 60);
+}
+/** Minimal publish-status record shape needed to reason about plot duplicates. */
+export interface PlotPublishRecord {
+  status?: "published" | "published-not-indexed" | "pending" | "draft";
+  storylineId?: number;
+  plotIndex?: number;
+  txHash?: string;
+}
+/**
+ * Whether a plot file already has a successful on-chain `chainPlot` recorded
+ * (#332). A minted chapter records its txHash + storyline + plotIndex; editing
+ * the file later resets `status` to "pending" but KEEPS those fields, so the
+ * presence of a txHash and a real plotIndex (>0) is the reliable signal that a
+ * chapter for this file already exists on PlotLink — republishing would mint a
+ * permanent duplicate chapter.
+ */
+export function hasPriorOnChainPlot(record: PlotPublishRecord | null | undefined): boolean {
+  return !!record?.txHash && record?.plotIndex != null && record.plotIndex > 0;
+}
+/**
+ * Whether a fresh `chainPlot` mint for this plot file must be BLOCKED to avoid a
+ * duplicate chapter (#332). Blocks whenever the file already has an on-chain
+ * chapter, EXCEPT the `published-not-indexed` state: there the on-chain tx
+ * exists but indexing failed, so the recovery flow (Retry Index, or an
+ * explicitly-confirmed Retry Publish in the UI) is intentional and handled
+ * separately. A first-time publish (no prior txHash) is never blocked, so
+ * existing fiction/cartoon first-publish behavior is unchanged.
+ */
+export function shouldBlockDuplicatePlotPublish(record: PlotPublishRecord | null | undefined): boolean {
+  return hasPriorOnChainPlot(record) && record?.status !== "published-not-indexed";
+}
+export function getContentTypeForPublish(
+  storyContentTypes: Record<string, string>,
+  storyName: string,
+  storylineId: number | undefined,
+): string | undefined {
+  if (storyContentTypes[storyName] === "cartoon" && !storylineId) {
+    return "cartoon";
+  }
+  return undefined;
+}
+/**
+ * Resolve the effective content type for the currently-selected story, falling
+ * back to the pending `_new_*` draft map before persistence.
+ *
+ * A freshly-created cartoon draft has no `.story.json` yet, so it is absent from
+ * the persisted `storyContentTypes` state; its type lives only in the in-memory
+ * pending map (`contentTypeMap`) until the rename/persist completes. Preview and
+ * terminal-launch gating must both see "cartoon" immediately — otherwise a new
+ * cartoon draft's terminal could launch before Codex readiness gating applies.
+ *
+ * Order: persisted state → pending draft map → "fiction" default. Returns
+ * undefined only when no story is selected.
+ */
+/**
+ * Pure predicate: does a story need the explicit legacy-cartoon provider repair?
+ *
+ * True ONLY when ALL of:
+ *  - the resolved content type is "cartoon", AND
+ *  - no provider is recorded on the story (legacy `.story.json` with no
+ *    `agentProvider`; absent ⇒ would default to Claude at launch), AND
+ *  - it is a real, persisted story (NOT a `_new_*` draft — new drafts already
+ *    force codex at creation, #254).
+ *
+ * Fiction, a cartoon that already has a provider, or a `_new_*` draft ⇒ false.
+ * This is read-only detection: it never writes or migrates anything.
+ */
+export function needsLegacyProviderRepair(
+  contentType: "fiction" | "cartoon" | undefined,
+  agentProvider: "claude" | "codex" | undefined,
+  storyName: string | null,
+): boolean {
+  if (contentType !== "cartoon") return false;
+  if (agentProvider) return false;
+  if (!storyName || storyName.startsWith("_new_")) return false;
+  return true;
+}
+export function resolveSelectedContentType(
+  selectedStory: string | null,
+  storyContentTypes: Record<string, "fiction" | "cartoon">,
+  pendingContentTypes: Map<string, "fiction" | "cartoon">,
+): "fiction" | "cartoon" | undefined {
+  if (!selectedStory) return undefined;
+  return (
+    storyContentTypes[selectedStory] ||
+    pendingContentTypes.get(selectedStory) ||
+    "fiction"
+  );
+}
+/** Shape of the `/api/publish/preflight` response we consume in the UI (#375). */
+export interface PublishPreflight {
+  ready?: boolean;
+  error?: string | null;
+  ethBalance?: string;
+  requiredBalance?: string;
+  creationFee?: string;
+  hasEnoughEth?: boolean;
+  address?: string;
+}
+/** Format a wei amount (decimal string) as ETH with 6 dp; null if unparseable. */
+function weiToEth(wei: string | undefined): string | null {
+  if (!wei) return null;
+  const n = Number(wei);
+  if (!Number.isFinite(n)) return null;
+  return (n / 1e18).toFixed(6);
+}
+/**
+ * Whether a publish preflight result must block opening the publish stream (#375).
+ * A wallet that cannot cover at least the creation fee — or any other not-ready
+ * preflight state — should stop the publish action before `/api/publish/file`
+ * rather than proceed into "Broadcasting…" and silently fail.
+ */
+export function isPreflightBlocked(pre: PublishPreflight | null | undefined): boolean {
+  return !!pre && pre.ready === false;
+}
+/**
+ * Build a durable, writer-facing block message for a not-ready publish preflight
+ * (#375). Prefers an explicit insufficient-balance message with the exact
+ * required vs. current ETH; otherwise surfaces preflight's own error.
+ */
+export function formatPreflightBlock(pre: PublishPreflight): string {
+  const need = weiToEth(pre.requiredBalance) ?? weiToEth(pre.creationFee);
+  const have = weiToEth(pre.ethBalance);
+  if (pre.hasEnoughEth === false && need && have) {
+    return (
+      `Insufficient ETH: need at least ${need} ETH to publish; current balance is ${have} ETH.` +
+      (pre.address ? ` Top up the OWS wallet (${pre.address}) and try again.` : " Top up the OWS wallet and try again.")
+    );
+  }
+  return pre.error || "Publish preflight failed — the OWS wallet isn't ready to publish.";
+}