plotlink-ows 1.0.32 → 1.2.94

package/app/lib/image-asset-validate.ts

@@ -0,0 +1,123 @@
+import fs from "fs";
+import path from "path";
+import { sniffImageType, type SniffedType } from "./clean-image-sync";
+
+// Shared filesystem validation for cartoon clean/final image assets. A single
+// source of truth for "is this recorded/candidate relative path a real, valid
+// WebP/JPEG file" — used by the sync/detect endpoints and by the stale-path
+// detection that gates publish readiness (#302).
+
+export const CLEAN_IMAGE_MAX_BYTES = 1024 * 1024;
+export const CLEAN_IMAGE_VALID_EXT = new Set(["webp", "jpg", "jpeg"]);
+
+/** Map an allowed file extension to the image type its content must match. */
+export const CLEAN_IMAGE_EXT_TO_TYPE: Record<string, Exclude<SniffedType, "unknown">> = {
+  webp: "webp",
+  jpg: "jpeg",
+  jpeg: "jpeg",
+};
+
+/**
+ * Validate a relative asset path against the real filesystem. Returns `null`
+ * when the file exists and is a valid WebP/JPEG (regular file, allowed
+ * extension, <=1MB, magic-byte content matches the extension); otherwise a short
+ * reason string. Filesystem read only — never mutates anything.
+ *
+ * `"missing"` covers a non-existent path, a non-regular file, an unreadable
+ * file, or a path that escapes the story's `assets/` tree; the other reasons
+ * describe a present-but-invalid asset.
+ */
+export function imageAssetIssue(storyDir: string, relPath: string): string | null {
+  // Recorded cut asset paths come from cuts.json and must be a canonical
+  // RELATIVE path inside the story's assets/ tree. Reject non-canonical forms
+  // before any filesystem read so a recorded path cannot be trusted as a local
+  // asset on a technicality:
+  //  - absolute paths (even ones that point inside assets/);
+  //  - any `..` path segment (even when it resolves back inside assets/, e.g.
+  //    "assets/plot-01/../evil.webp" → "assets/evil.webp").
+  // Then a resolved-boundary check rejects anything that still escapes assets/.
+  if (path.isAbsolute(relPath)) return "missing";
+  if (relPath.split(/[/\\]/).includes("..")) return "missing";
+
+  const assetsRoot = path.resolve(storyDir, "assets");
+  const abs = path.resolve(storyDir, relPath);
+  if (abs !== assetsRoot && !abs.startsWith(assetsRoot + path.sep)) return "missing";
+
+  if (!fs.existsSync(abs)) return "missing";
+
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(abs);
+  } catch {
+    return "missing";
+  }
+  if (!stat.isFile()) return "missing";
+
+  const ext = path.extname(relPath).slice(1).toLowerCase();
+  if (!CLEAN_IMAGE_VALID_EXT.has(ext)) return `Unsupported extension .${ext}`;
+  if (stat.size > CLEAN_IMAGE_MAX_BYTES) return "File must be under 1MB";
+
+  // Sniff the real content so a text file (or a renamed/mismatched image) named
+  // `.webp`/`.jpg` cannot pass on extension alone.
+  let sniffed: SniffedType;
+  try {
+    const fd = fs.openSync(abs, "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 "missing";
+  }
+
+  if (sniffed === "unknown") return "not a valid image (content does not match WebP/JPEG/PNG)";
+  if (sniffed !== CLEAN_IMAGE_EXT_TO_TYPE[ext]) return `content does not match .${ext} extension`;
+  return null;
+}
+
+/** True when a relative asset path is a real, valid WebP/JPEG file on disk. */
+export function isValidImageAsset(storyDir: string, relPath: string): boolean {
+  return imageAssetIssue(storyDir, relPath) === null;
+}
+
+/**
+ * True when a relative asset path points to a real PNG image on disk (#441).
+ * PNG is NOT a publishable clean format — but it is a normal intermediate that
+ * the writer converts to WebP/JPEG, so detection treats it as a conversion step
+ * rather than a hard "unsupported extension" error. Same traversal guards as
+ * `imageAssetIssue`; deliberately does NOT gate on the 1MB size limit (the
+ * browser conversion compresses, so an oversize PNG is still convertible).
+ */
+export function pngAssetExists(storyDir: string, relPath: string): boolean {
+  if (path.isAbsolute(relPath)) return false;
+  if (relPath.split(/[/\\]/).includes("..")) return false;
+
+  const assetsRoot = path.resolve(storyDir, "assets");
+  const abs = path.resolve(storyDir, relPath);
+  if (abs !== assetsRoot && !abs.startsWith(assetsRoot + path.sep)) return false;
+
+  if (!fs.existsSync(abs)) return false;
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(abs);
+  } catch {
+    return false;
+  }
+  if (!stat.isFile()) return false;
+
+  try {
+    const fd = fs.openSync(abs, "r");
+    try {
+      const head = Buffer.alloc(16);
+      const read = fs.readSync(fd, head, 0, 16, 0);
+      return sniffImageType(head.subarray(0, read)) === "png";
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return false;
+  }
+}

package/app/lib/lettering-status.ts

@@ -0,0 +1,133 @@
+// Per-cut lettering status + "insert from script" helpers for the cartoon
+// lettering editor guidance (#336). Pure and UI-agnostic so they can be unit
+// tested and shared between the editor checklist and the insert-from-script
+// panel. None of this changes the export model or publish readiness rules.
+
+import type { Overlay } from "./overlays";
+
+/** The cut fields the lettering guidance reads (a structural subset of Cut). */
+export interface LetteringCut {
+  cleanImagePath?: string | null;
+  finalImagePath?: string | null;
+  exportedAt?: string | null;
+  uploadedUrl?: string | null;
+  uploadedCid?: string | null;
+  narration?: string;
+  sfx?: string;
+  dialogue?: { speaker: string; text: string }[];
+  overlays?: Overlay[];
+}
+
+export interface LetteringChecklist {
+  /** A clean (text-free) image has been recorded for the cut. */
+  hasCleanImage: boolean;
+  /** The cut plan carries script text (dialogue, narration, or SFX) to letter. */
+  hasScriptText: boolean;
+  /** How many overlays (bubbles/captions/SFX) have been placed. */
+  bubblesPlaced: number;
+  /** A final lettered image has been exported. */
+  exported: boolean;
+  /** An uploaded URL/CID is recorded for the cut. */
+  uploaded: boolean;
+}
+
+/**
+ * Summarize a single cut's lettering progress for the editor's status strip
+ * (#336): clean image present → script text available → bubbles placed →
+ * exported → uploaded. Read-only; derived straight from the cut record.
+ *
+ * `opts.staleExport` (#336, re1): when the writer has edited the overlays since
+ * the recorded export, the existing final image / uploaded URL no longer match
+ * what's on screen, so export & upload are reported as NOT done — the writer
+ * must re-export before those steps count again.
+ */
+export function cutLetteringChecklist(
+  cut: LetteringCut,
+  opts: { staleExport?: boolean } = {},
+): LetteringChecklist {
+  const exported = !opts.staleExport && (!!cut.finalImagePath || !!cut.exportedAt);
+  const uploaded = !opts.staleExport && (!!cut.uploadedUrl || !!cut.uploadedCid);
+  return {
+    hasCleanImage: !!cut.cleanImagePath,
+    hasScriptText:
+      (cut.dialogue?.length ?? 0) > 0 || !!cut.narration?.trim() || !!cut.sfx?.trim(),
+    bubblesPlaced: cut.overlays?.length ?? 0,
+    exported,
+    uploaded,
+  };
+}
+
+/**
+ * Stable signature of an overlay set for change detection (#336). Captures only
+ * the fields that affect the rendered/exported image (type, geometry, text,
+ * speaker, tail), so reordering of unrelated metadata doesn't matter and any
+ * real edit changes the signature.
+ */
+export function overlaysSignature(overlays: Overlay[] | undefined): string {
+  return JSON.stringify(
+    (overlays ?? []).map((o) => [
+      o.type,
+      o.x,
+      o.y,
+      o.width,
+      o.height,
+      o.text,
+      o.speaker ?? "",
+      o.tailAnchor ?? null,
+      o.textStyle ?? null,
+      o.bubbleStyle ?? null,
+    ]),
+  );
+}
+
+/**
+ * Whether a cut's recorded export/upload is stale because the overlays were
+ * edited since (#336, re1). Only meaningful once the cut has actually been
+ * exported or uploaded; compares the current overlays against the baseline that
+ * was on screen when the editor opened (already normalized the same way), so a
+ * load-time normalization is not mistaken for a user edit.
+ */
+export function isExportStale(opts: {
+  exported: boolean;
+  uploaded: boolean;
+  /** Signature of the overlays that match the recorded export (see overlaysSignature). */
+  baselineSig: string;
+  current: Overlay[] | undefined;
+}): boolean {
+  if (!opts.exported && !opts.uploaded) return false;
+  return opts.baselineSig !== overlaysSignature(opts.current);
+}
+
+export type ScriptLineType = "speech" | "narration" | "sfx";
+
+/** A piece of the cut's script the writer can drop straight into an overlay. */
+export interface ScriptLine {
+  type: ScriptLineType;
+  /** Speaker for a dialogue line; undefined for narration/SFX. */
+  speaker?: string;
+  text: string;
+  /** Stable key for list rendering / dedupe (type + index within its kind). */
+  key: string;
+}
+
+/**
+ * Flatten a cut's `cuts.json` script (dialogue lines, narration, SFX) into the
+ * ordered list the editor offers as one-click "insert into a bubble" actions
+ * (#336) — so a writer never has to hand-copy text out of the JSON. Empty
+ * pieces are skipped.
+ */
+export function cutScriptLines(cut: LetteringCut): ScriptLine[] {
+  const lines: ScriptLine[] = [];
+  (cut.dialogue ?? []).forEach((d, i) => {
+    if (d?.text?.trim()) {
+      lines.push({ type: "speech", speaker: d.speaker, text: d.text.trim(), key: `speech-${i}` });
+    }
+  });
+  if (cut.narration?.trim()) {
+    lines.push({ type: "narration", text: cut.narration.trim(), key: "narration" });
+  }
+  if (cut.sfx?.trim()) {
+    lines.push({ type: "sfx", text: cut.sfx.trim(), key: "sfx" });
+  }
+  return lines;
+}