plotlink-ows 1.0.32 → 1.2.94

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

@@ -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.";
+}

package/app/web/lib/upload-retry.ts

@@ -0,0 +1,130 @@
+// Retry/backoff for rate-limited cartoon cut image uploads (#288).
+//
+// The PlotLink upload endpoint rate-limits to 5 uploads/minute. A normal webtoon
+// episode commonly has more than five cuts, so the batch "Upload & Generate" flow
+// would otherwise fail mid-batch on the 6th+ cut with a "Rate limit exceeded"
+// response. These helpers retry a single upload with backoff while it is
+// rate-limited, while leaving genuine (non-rate-limit) failures to fail fast.
+
+// PlotLink allows 5 uploads/minute, so ~12s spacing clears the window for the
+// next cut. Backoff grows from here and is capped so a stuck batch still ends.
+export const RATE_LIMIT_BASE_DELAY_MS = 12_000;
+export const RATE_LIMIT_MAX_RETRIES = 5;
+const MAX_BACKOFF_MS = 60_000;
+
+// PlotLink's documented limit: 5 uploads per rolling 60s window. The proactive
+// throttle below paces the batch to stay under this, so a 7–10 cut episode never
+// blows the budget in a tight loop and then thrashes on reactive backoff (#413).
+export const RATE_LIMIT_WINDOW_MS = 60_000;
+export const RATE_LIMIT_BURST = 5;
+
+/**
+ * A rate-limit response. The OWS route currently forwards PlotLink's rate-limit
+ * as a 500 carrying the upstream message ("Rate limit exceeded. Max 5 uploads
+ * per minute."), so we detect by status 429 OR a rate-limit message — either is
+ * treated as retryable.
+ */
+export function isRateLimitError(status: number, errorMessage?: string | null): boolean {
+  if (status === 429) return true;
+  return !!errorMessage && /rate[\s-]?limit/i.test(errorMessage);
+}
+
+/** Backoff for the Nth retry (0-based): base, 2×base, 4×base, … capped. */
+export function backoffMs(retry: number, baseDelayMs = RATE_LIMIT_BASE_DELAY_MS): number {
+  return Math.min(baseDelayMs * 2 ** retry, MAX_BACKOFF_MS);
+}
+
+export interface AttemptResult {
+  ok: boolean;
+  status: number;
+  errorMessage?: string | null;
+}
+
+export interface RetryDeps {
+  /** Injectable for tests; defaults to a real setTimeout-based sleep. */
+  sleep?: (ms: number) => Promise<void>;
+  maxRetries?: number;
+  baseDelayMs?: number;
+  /** Called once before each backoff wait so the UI can show a waiting state. */
+  onWaiting?: (info: { attempt: number; maxRetries: number; waitMs: number }) => void;
+}
+
+const defaultSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Run `attempt` and, while its result is rate-limited, wait with backoff and
+ * retry up to `maxRetries` times. Returns the first non-rate-limited result, or
+ * the last rate-limited result once retries are exhausted (so the caller still
+ * gets the affected status/message to report). Never retries a non-rate-limit
+ * failure or a success.
+ */
+export async function withRateLimitRetry<T extends AttemptResult>(
+  attempt: () => Promise<T>,
+  deps: RetryDeps = {},
+): Promise<T> {
+  const sleep = deps.sleep ?? defaultSleep;
+  const maxRetries = deps.maxRetries ?? RATE_LIMIT_MAX_RETRIES;
+  const baseDelayMs = deps.baseDelayMs ?? RATE_LIMIT_BASE_DELAY_MS;
+
+  let retries = 0;
+  for (;;) {
+    const result = await attempt();
+    if (result.ok || !isRateLimitError(result.status, result.errorMessage)) return result;
+    if (retries >= maxRetries) return result;
+    const waitMs = backoffMs(retries, baseDelayMs);
+    retries += 1;
+    deps.onWaiting?.({ attempt: retries, maxRetries, waitMs });
+    await sleep(waitMs);
+  }
+}
+
+export interface ThrottleDeps {
+  /** Max uploads allowed per window (default 5 = PlotLink's per-minute limit). */
+  limit?: number;
+  /** Rolling window length in ms (default 60_000). */
+  windowMs?: number;
+  /** Injectable for tests; defaults to a real setTimeout-based sleep. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Injectable clock for tests; defaults to Date.now. */
+  now?: () => number;
+  /** Called once before each proactive wait so the UI can show a waiting state. */
+  onWaiting?: (info: { waitMs: number }) => void;
+}
+
+/**
+ * Build a proactive sliding-window throttle for a batch of uploads (#413).
+ *
+ * Returns an async `throttle()` to call immediately BEFORE each upload. It records
+ * each call's timestamp and, once `limit` uploads have happened inside the last
+ * `windowMs`, sleeps until the oldest of those falls out of the window before
+ * letting the next through — so a 7–10 cut batch paces itself under PlotLink's
+ * 5/min limit instead of firing all uploads at once and then thrashing on reactive
+ * 429 backoff. `withRateLimitRetry` stays as the safety net for any 429 that still
+ * slips through (e.g. budget consumed by another client). Pure aside from the
+ * injected clock/sleep, so it's deterministic in tests.
+ */
+export function createUploadThrottle(deps: ThrottleDeps = {}) {
+  const limit = deps.limit ?? RATE_LIMIT_BURST;
+  const windowMs = deps.windowMs ?? RATE_LIMIT_WINDOW_MS;
+  const sleep = deps.sleep ?? defaultSleep;
+  const now = deps.now ?? (() => Date.now());
+  const stamps: number[] = [];
+
+  const dropExpired = () => {
+    const cutoff = now() - windowMs;
+    while (stamps.length && stamps[0] <= cutoff) stamps.shift();
+  };
+
+  return async function throttle(): Promise<void> {
+    dropExpired();
+    if (stamps.length >= limit) {
+      const waitMs = stamps[0] + windowMs - now();
+      if (waitMs > 0) {
+        deps.onWaiting?.({ waitMs });
+        await sleep(waitMs);
+      }
+      dropExpired();
+    }
+    stamps.push(now());
+  };
+}

package/app/web/lib/verify-public-title.ts

@@ -0,0 +1,105 @@
+import { isRawFilenameTitle, isGenericEpisodeTitle } from "./publish-helpers";
+
+/**
+ * End-to-end public-title verification for cartoon publishes (#379).
+ *
+ * Local guards (#347/#358/#365/#368) ensure OWS *sends* a reader-facing title,
+ * but the real pilot (`plotlink.xyz/story/59/1` rendered `genesis` / `plot-01`)
+ * showed we must also prove the PUBLIC, indexed metadata is reader-facing — not
+ * just that local preview computed a good label. After indexing, OWS reads the
+ * indexed storyline detail and verifies the title here. Already-published bad
+ * titles are immutable, so this can only warn + keep the next publish honest.
+ */
+
+/** Subset of PlotLink's `GET /api/storyline/<id>` response we read for #379. */
+export interface PublicStorylineDetail {
+  title?: string;
+  name?: string;
+  // PlotLink may expose per-episode entries (plots/chapters) with their own
+  // title + index; we read whichever is present, matching by plot index.
+  plots?: Array<{ title?: string; name?: string; index?: number; plotIndex?: number }>;
+  chapters?: Array<{ title?: string; name?: string; index?: number; plotIndex?: number }>;
+}
+
+export interface PublicTitleVerdict {
+  /** false → the indexed public title is raw/generic (verification failed). */
+  ok: boolean;
+  /** false → the relevant public title field was absent (read inconclusive). */
+  checked: boolean;
+  /** the public title actually evaluated, when present. */
+  publicTitle?: string;
+  /** human-facing failure reason, when ok === false. */
+  reason?: string;
+}
+
+/** Find the public title for a plot index across whichever list PlotLink returns. */
+function pickPlotTitle(detail: PublicStorylineDetail, plotIndex: number | undefined): string | undefined {
+  const lists = [detail.plots, detail.chapters].filter(Boolean) as NonNullable<PublicStorylineDetail["plots"]>[];
+  for (const list of lists) {
+    const byIndex =
+      plotIndex != null ? list.find((p) => p.plotIndex === plotIndex || p.index === plotIndex) : undefined;
+    let entry = byIndex;
+    if (!entry && list.length === 1) {
+      // Fall back to the lone entry ONLY when it carries no index to match on
+      // (or the caller gave no index) — never when a known index simply differs,
+      // which would verify the wrong episode.
+      const only = list[0];
+      const hasIndex = only.plotIndex != null || only.index != null;
+      if (!hasIndex || plotIndex == null) entry = only;
+    }
+    const t = (entry?.title ?? entry?.name)?.trim();
+    if (t) return t;
+  }
+  return undefined;
+}
+
+/**
+ * Verify the indexed PlotLink title for a cartoon publish is reader-facing.
+ * Genesis (storyline) titles must not be the raw `genesis` fallback; plot titles
+ * must not be `plot-NN` or a generic `Episode NN` placeholder. Returns
+ * `checked: false` when the relevant public title is absent, so the caller never
+ * false-fails an inconclusive read (e.g. a transient indexer response).
+ */
+export function verifyPublicCartoonTitle(opts: {
+  fileName: string;
+  detail: PublicStorylineDetail | null | undefined;
+  plotIndex?: number;
+}): PublicTitleVerdict {
+  const { fileName, detail, plotIndex } = opts;
+  if (!detail) return { ok: true, checked: false };
+
+  if (fileName === "genesis.md") {
+    const publicTitle = (detail.title ?? detail.name)?.trim();
+    if (!publicTitle) return { ok: true, checked: false };
+    if (isRawFilenameTitle(publicTitle, "genesis.md")) {
+      return {
+        ok: false,
+        checked: true,
+        publicTitle,
+        reason: `PlotLink indexed the storyline title as “${publicTitle}”, a raw filename rather than the reader-facing title.`,
+      };
+    }
+    return { ok: true, checked: true, publicTitle };
+  }
+
+  const publicTitle = pickPlotTitle(detail, plotIndex);
+  if (!publicTitle) return { ok: true, checked: false };
+  if (isRawFilenameTitle(publicTitle, fileName) || isGenericEpisodeTitle(publicTitle)) {
+    return {
+      ok: false,
+      checked: true,
+      publicTitle,
+      reason: `PlotLink indexed the episode title as “${publicTitle}”, a generic placeholder rather than a reader-facing episode title.`,
+    };
+  }
+  return { ok: true, checked: true, publicTitle };
+}
+
+/** Durable, writer-facing warning shown when public-title verification fails (#379). */
+export function publicTitleWarning(verdict: PublicTitleVerdict): string {
+  return (
+    `${verdict.reason ?? "PlotLink indexed a raw/generic public title for this publish."} ` +
+    `Published metadata is immutable on-chain and cannot be edited — the next publish must use corrected, reader-facing metadata. ` +
+    `(The webtoon pilot stays blocked until a publish indexes a real public title.)`
+  );
+}

package/app/web/styles.css

@@ -62,6 +62,15 @@ code, pre {
   font-family: "Geist Mono", ui-monospace, monospace;
 }
 
+/* Cartoon awaiting-upload pending panel — calm, info-toned (NOT red). Shown
+   after Generate MD lays down the skeleton but before final images are
+   uploaded. Mirrors the planning-callout treatment so the two pending states
+   feel related rather than alarming. */
+.cartoon-awaiting-upload {
+  border-color: color-mix(in srgb, var(--accent) 30%, transparent);
+  background: color-mix(in srgb, var(--accent) 5%, transparent);
+}
+
 /* Ensure dim/faint terminal text (SGR 2) stays readable on cream bg */
 .xterm .xterm-dim {
   opacity: 1 !important;