plotlink-ows 1.0.33 → 1.2.94

package/app/lib/cuts.ts

@@ -0,0 +1,302 @@
+import fs from "fs";
+import path from "path";
+import { hasVisibleSpeechTail, CARTOON_BUBBLE_RENDERER_VERSION, type Overlay } from "./overlays";
+
+export const SHOT_TYPES = ["wide", "medium", "close-up", "extreme-close-up"] as const;
+export type ShotType = (typeof SHOT_TYPES)[number];
+
+export interface CutDialogue {
+  speaker: string;
+  text: string;
+}
+
+/**
+ * Panel kind (#350). An "image" cut is the normal art panel (needs a clean
+ * image → lettering → export → upload). A "text" panel is a text/interstitial
+ * card (no clean image; text on a styled background, still exported + uploaded
+ * as a final image for MVP). The field is OPTIONAL and backward-compatible:
+ * a missing `kind` means "image".
+ */
+export type CutKind = "image" | "text";
+
+export interface Cut {
+  id: number;
+  shotType: ShotType;
+  description: string;
+  characters: string[];
+  dialogue: CutDialogue[];
+  narration: string;
+  sfx: string;
+  cleanImagePath: string | null;
+  finalImagePath: string | null;
+  exportedAt: string | null;
+  uploadedCid: string | null;
+  uploadedUrl: string | null;
+  overlays: Overlay[];
+  /**
+   * Bubble-renderer revision the final image was exported with (#381). Absent on
+   * cuts exported before versioning (treated as stale for tailed bubbles). Stamped
+   * by the export-final endpoint with CARTOON_BUBBLE_RENDERER_VERSION.
+   */
+  finalRendererVersion?: number;
+  /** Panel kind (#350). Absent ⇒ "image" (backward-compatible). */
+  kind?: CutKind;
+  /** Text-panel background color (CSS color), e.g. "#101820". Optional (#350). */
+  background?: string;
+  /** Text-panel aspect ratio hint, e.g. "4:5". Optional (#350). */
+  aspectRatio?: string;
+}
+
+/** Whether a cut is a text/interstitial panel (#350); missing kind ⇒ image. */
+export function isTextPanel(cut: Pick<Cut, "kind">): boolean {
+  return cut.kind === "text";
+}
+
+/** Stable key for a cut's single next production step (#371). */
+export type CutActionKey = "add-art" | "letter" | "review";
+
+/**
+ * The one next production action for a single cut (#371), used to deep-link from
+ * the Preview / Cut Inspector straight into that cut's editing step instead of
+ * making the writer hunt for it in the Edit tab. Mirrors the per-cut status the
+ * Edit tab shows (no clean art → letter → final ready) but in creator-facing
+ * language, and reports whether the lettering editor can open directly for it.
+ *
+ * - "add-art": an image cut with no clean image yet → the writer adds/imports the
+ *   clean art first, so the CTA focuses the cut's row (there is nothing to letter
+ *   yet, so the editor does not open).
+ * - "letter": a clean image cut, or a text/interstitial panel, that still needs
+ *   overlays or a final export → open the lettering editor directly.
+ * - "review": a final image already exists → open the editor to review/redo it.
+ */
+export interface CutNextAction {
+  key: CutActionKey;
+  /** Creator-facing CTA label — no markdown/schema jargon (#371). */
+  label: string;
+  /** Whether the lettering editor can be opened directly for this cut. */
+  opensEditor: boolean;
+}
+
+export function cutNextAction(
+  cut: Pick<Cut, "cleanImagePath" | "finalImagePath" | "exportedAt" | "kind">,
+): CutNextAction {
+  const hasFinal = !!cut.finalImagePath || !!cut.exportedAt;
+  if (hasFinal) {
+    return { key: "review", label: "Review final panel", opensEditor: true };
+  }
+  // A clean image or a text/interstitial panel is ready to letter; a text panel
+  // letters on its background and needs no clean image (#350).
+  if (cut.cleanImagePath || isTextPanel(cut)) {
+    return { key: "letter", label: "Letter this cut", opensEditor: true };
+  }
+  return { key: "add-art", label: "Add clean art for this cut", opensEditor: false };
+}
+
+/**
+ * Whether a cut's exported final image is STALE for #381: it has a final image
+ * AND renders at least one visible speech-bubble tail AND was exported by an
+ * older bubble renderer (its `finalRendererVersion` is absent — pre-versioning —
+ * or below `currentVersion`). Such an image may show the old separate-tail seam
+ * and must be re-exported before publish. Tailless cuts are never stale (the
+ * seam fixes only affect tailed bubbles), so existing exports aren't churned.
+ */
+export function isStaleTailedExport(
+  cut: Pick<Cut, "finalImagePath" | "finalRendererVersion" | "overlays">,
+  currentVersion: number = CARTOON_BUBBLE_RENDERER_VERSION,
+): boolean {
+  if (!cut.finalImagePath) return false;
+  const tailed = (cut.overlays ?? []).some(hasVisibleSpeechTail);
+  if (!tailed) return false;
+  return (cut.finalRendererVersion ?? 0) < currentVersion;
+}
+
+/** Ids of cuts whose final image is a stale tailed export (#381), in order. */
+export function staleTailedCutIds(
+  cutsFile: Pick<CutsFile, "cuts">,
+  currentVersion: number = CARTOON_BUBBLE_RENDERER_VERSION,
+): number[] {
+  return cutsFile.cuts.filter((c) => isStaleTailedExport(c, currentVersion)).map((c) => c.id);
+}
+
+/** Base canvas width for a text panel sized from its aspect ratio (#351). */
+export const TEXT_PANEL_BASE_WIDTH = 800;
+
+/**
+ * Canvas dimensions for a text panel from an "W:H" aspect ratio (#351) — shared
+ * by the lettering editor (so its surface matches) and the export, so a text
+ * panel letters and exports at the SAME shape. Returns null for a missing or
+ * malformed ratio; callers fall back to 800×600.
+ */
+export function textPanelDimensions(aspectRatio: string | undefined): { width: number; height: number } | null {
+  if (!aspectRatio) return null;
+  const m = aspectRatio.match(/^\s*(\d+(?:\.\d+)?)\s*:\s*(\d+(?:\.\d+)?)\s*$/);
+  if (!m) return null;
+  const w = parseFloat(m[1]);
+  const h = parseFloat(m[2]);
+  if (!(w > 0) || !(h > 0)) return null;
+  return { width: TEXT_PANEL_BASE_WIDTH, height: Math.round((TEXT_PANEL_BASE_WIDTH * h) / w) };
+}
+
+export interface CutsFile {
+  version: 1;
+  plotFile: string;
+  /**
+   * Optional human-readable episode title (#347). When present it becomes the
+   * published chapter title for a cartoon episode whose plot-NN.md has no H1
+   * (cartoon publish markdown is image-only by design), so the episode never
+   * publishes as the raw "plot-NN" filename. Absent in v1 cut plans — callers
+   * fall back to a friendly "Episode NN".
+   */
+  title?: string;
+  cuts: Cut[];
+}
+
+export function createDefaultCut(id: number, _plotFile: string): Cut {
+  return {
+    id,
+    shotType: "medium",
+    description: "",
+    characters: [],
+    dialogue: [],
+    narration: "",
+    sfx: "",
+    cleanImagePath: null,
+    finalImagePath: null,
+    exportedAt: null,
+    uploadedCid: null,
+    uploadedUrl: null,
+    overlays: [],
+  };
+}
+
+export function createCutsFile(plotFile: string, cutCount = 1): CutsFile {
+  const cuts = Array.from({ length: cutCount }, (_, i) => createDefaultCut(i + 1, plotFile));
+  return { version: 1, plotFile, cuts };
+}
+
+function cutsFilePath(storyDir: string, plotFile: string): string {
+  return path.join(storyDir, `${plotFile}.cuts.json`);
+}
+
+export function readCutsFile(storyDir: string, plotFile: string): CutsFile | null {
+  const filePath = cutsFilePath(storyDir, plotFile);
+  if (!fs.existsSync(filePath)) return null;
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch (err) {
+    throw new Error(`Cannot read ${plotFile}.cuts.json: ${(err as Error).message}`);
+  }
+
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    throw new Error(`${plotFile}.cuts.json contains invalid JSON`);
+  }
+
+  const validation = validateCutsFile(data);
+  if (!validation.valid) {
+    throw new Error(`${plotFile}.cuts.json is invalid: ${validation.error}`);
+  }
+
+  return data as CutsFile;
+}
+
+export function writeCutsFile(storyDir: string, plotFile: string, cutsFile: CutsFile): void {
+  const filePath = cutsFilePath(storyDir, plotFile);
+  fs.writeFileSync(filePath, JSON.stringify(cutsFile, null, 2) + "\n");
+}
+
+export function validateCutsFile(data: unknown): { valid: boolean; error?: string } {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return { valid: false, error: "Must be a JSON object" };
+  }
+
+  const obj = data as Record<string, unknown>;
+
+  if (obj.version !== 1) {
+    return { valid: false, error: "Unsupported version (expected 1)" };
+  }
+
+  if (typeof obj.plotFile !== "string" || !obj.plotFile) {
+    return { valid: false, error: "Missing or invalid plotFile" };
+  }
+
+  if (!Array.isArray(obj.cuts)) {
+    return { valid: false, error: "cuts must be an array" };
+  }
+
+  // Optional episode title (#347) — string when present.
+  if (obj.title !== undefined && typeof obj.title !== "string") {
+    return { valid: false, error: "title must be a string" };
+  }
+
+  const validShots = new Set<string>(SHOT_TYPES);
+
+  for (let i = 0; i < obj.cuts.length; i++) {
+    const cut = obj.cuts[i] as Record<string, unknown>;
+    if (typeof cut !== "object" || cut === null) {
+      return { valid: false, error: `Cut ${i} is not an object` };
+    }
+    if (typeof cut.id !== "number") {
+      return { valid: false, error: `Cut ${i} missing numeric id` };
+    }
+    if (typeof cut.shotType !== "string" || !validShots.has(cut.shotType)) {
+      return { valid: false, error: `Cut ${i} has invalid shotType` };
+    }
+    if (typeof cut.description !== "string") {
+      return { valid: false, error: `Cut ${i} missing description` };
+    }
+    if (!Array.isArray(cut.characters)) {
+      return { valid: false, error: `Cut ${i} characters must be an array` };
+    }
+    for (let j = 0; j < (cut.characters as unknown[]).length; j++) {
+      if (typeof (cut.characters as unknown[])[j] !== "string") {
+        return { valid: false, error: `Cut ${i} characters[${j}] must be a string` };
+      }
+    }
+    if (!Array.isArray(cut.dialogue)) {
+      return { valid: false, error: `Cut ${i} dialogue must be an array` };
+    }
+    for (let j = 0; j < (cut.dialogue as unknown[]).length; j++) {
+      const d = (cut.dialogue as Record<string, unknown>[])[j];
+      if (typeof d !== "object" || d === null || typeof d.speaker !== "string" || typeof d.text !== "string") {
+        return { valid: false, error: `Cut ${i} dialogue[${j}] must have speaker and text strings` };
+      }
+    }
+    if (typeof cut.narration !== "string") {
+      return { valid: false, error: `Cut ${i} missing narration` };
+    }
+    if (typeof cut.sfx !== "string") {
+      return { valid: false, error: `Cut ${i} missing sfx` };
+    }
+    const nullableStrings = ["cleanImagePath", "finalImagePath", "exportedAt", "uploadedCid", "uploadedUrl"] as const;
+    for (const field of nullableStrings) {
+      if (cut[field] !== null && typeof cut[field] !== "string") {
+        return { valid: false, error: `Cut ${i} ${field} must be a string or null` };
+      }
+    }
+    if (cut.overlays !== undefined && !Array.isArray(cut.overlays)) {
+      return { valid: false, error: `Cut ${i} overlays must be an array` };
+    }
+    // Text-panel fields (#350) — all optional and backward-compatible.
+    if (cut.kind !== undefined && cut.kind !== "image" && cut.kind !== "text") {
+      return { valid: false, error: `Cut ${i} kind must be "image" or "text"` };
+    }
+    if (cut.background !== undefined && typeof cut.background !== "string") {
+      return { valid: false, error: `Cut ${i} background must be a string` };
+    }
+    if (cut.aspectRatio !== undefined && typeof cut.aspectRatio !== "string") {
+      return { valid: false, error: `Cut ${i} aspectRatio must be a string` };
+    }
+    // Bubble-renderer version stamp (#381) — optional, backward-compatible
+    // (absent ⇒ pre-versioning final image).
+    if (cut.finalRendererVersion !== undefined && typeof cut.finalRendererVersion !== "number") {
+      return { valid: false, error: `Cut ${i} finalRendererVersion must be a number` };
+    }
+  }
+
+  return { valid: true };
+}

package/app/lib/fonts.ts

@@ -0,0 +1,109 @@
+export interface FontEntry {
+  family: string;
+  googleFontsId: string;
+  license: string;
+  licenseUrl: string;
+  category: "body" | "display";
+  weights: number[];
+  languages: string[];
+}
+
+export const FONT_REGISTRY: FontEntry[] = [
+  {
+    family: "Noto Sans",
+    googleFontsId: "Noto+Sans",
+    license: "OFL-1.1",
+    licenseUrl: "https://fonts.google.com/noto/specimen/Noto+Sans/about",
+    category: "body",
+    weights: [400, 500, 700],
+    languages: ["English", "Spanish", "French", "Portuguese", "Russian", "Others"],
+  },
+  {
+    family: "Noto Sans KR",
+    googleFontsId: "Noto+Sans+KR",
+    license: "OFL-1.1",
+    licenseUrl: "https://fonts.google.com/noto/specimen/Noto+Sans+KR/about",
+    category: "body",
+    weights: [400, 500, 700],
+    languages: ["Korean"],
+  },
+  {
+    family: "Noto Sans JP",
+    googleFontsId: "Noto+Sans+JP",
+    license: "OFL-1.1",
+    licenseUrl: "https://fonts.google.com/noto/specimen/Noto+Sans+JP/about",
+    category: "body",
+    weights: [400, 500, 700],
+    languages: ["Japanese"],
+  },
+  {
+    family: "Noto Sans SC",
+    googleFontsId: "Noto+Sans+SC",
+    license: "OFL-1.1",
+    licenseUrl: "https://fonts.google.com/noto/specimen/Noto+Sans+SC/about",
+    category: "body",
+    weights: [400, 500, 700],
+    languages: ["Chinese"],
+  },
+  {
+    family: "Noto Sans Devanagari",
+    googleFontsId: "Noto+Sans+Devanagari",
+    license: "OFL-1.1",
+    licenseUrl: "https://fonts.google.com/noto/specimen/Noto+Sans+Devanagari/about",
+    category: "body",
+    weights: [400, 500, 700],
+    languages: ["Hindi"],
+  },
+  {
+    family: "Noto Naskh Arabic",
+    googleFontsId: "Noto+Naskh+Arabic",
+    license: "OFL-1.1",
+    licenseUrl: "https://fonts.google.com/noto/specimen/Noto+Naskh+Arabic/about",
+    category: "body",
+    weights: [400, 500, 700],
+    languages: ["Arabic"],
+  },
+  {
+    family: "Bangers",
+    googleFontsId: "Bangers",
+    license: "OFL-1.1",
+    licenseUrl: "https://fonts.google.com/specimen/Bangers/about",
+    category: "display",
+    weights: [400],
+    languages: [],
+  },
+];
+
+export const FONT_FALLBACK_STACK = "system-ui, sans-serif";
+
+const defaultFont = FONT_REGISTRY.find((f) => f.family === "Noto Sans")!;
+const displayFont = FONT_REGISTRY.find((f) => f.category === "display")!;
+
+export function getDefaultFont(language: string): FontEntry {
+  const match = FONT_REGISTRY.find(
+    (f) => f.category === "body" && f.languages.includes(language),
+  );
+  return match || defaultFont;
+}
+
+export function getDisplayFont(): FontEntry {
+  return displayFont;
+}
+
+export function getFontCdnUrl(font: FontEntry): string {
+  const weights = font.weights.join(";");
+  return `https://fonts.googleapis.com/css2?family=${font.googleFontsId}:wght@${weights}&display=swap`;
+}
+
+export function getFontFamily(font: FontEntry): string {
+  return `"${font.family}", ${FONT_FALLBACK_STACK}`;
+}
+
+export const LANGUAGE_FONT_SAMPLES: Record<string, { text: string; font: string }> = {
+  English: { text: "The quick brown fox jumps", font: "Noto Sans" },
+  Korean: { text: "한국어 샘플 텍스트", font: "Noto Sans KR" },
+  Japanese: { text: "日本語のサンプル", font: "Noto Sans JP" },
+  Chinese: { text: "中文示例文本", font: "Noto Sans SC" },
+  Hindi: { text: "हिंदी नमूना पाठ", font: "Noto Sans Devanagari" },
+  Arabic: { text: "نص عربي نموذجي", font: "Noto Naskh Arabic" },
+};

package/app/lib/generate-claude-md.ts

@@ -27,6 +27,11 @@ All endpoints except auth use \`Authorization: Bearer {token}\` headers.
 The OWS passphrase is stored in \`~/.plotlink-ows/.env\` as \`OWS_PASSPHRASE\`.
 For login, the passphrase is hashed with HMAC-SHA256 and compared against the stored hash.
 
+**Never print secrets into the terminal.** Do not \`echo\`, \`cat\`, or log the
+\`OWS_PASSPHRASE\`, the session token, or any \`Authorization: Bearer\` header / login
+command that contains the passphrase. The app authenticates for you — you never
+need to read or print these.
+
 | Endpoint | Method | Auth | Purpose |
 |----------|--------|------|---------|
 | \`/api/auth/status\` | GET | No | Check if passphrase is configured |
@@ -39,7 +44,7 @@ For login, the passphrase is hashed with HMAC-SHA256 and compared against the st
 
 | Endpoint | Method | Purpose |
 |----------|--------|---------|
-| \`/api/publish/preflight\` | GET | Check wallet balance, Filebase config |
+| \`/api/publish/preflight\` | GET | Check wallet balance vs. creation fee (uploads go through the PlotLink API) |
 | \`/api/publish/file\` | POST | Publish story on-chain (SSE stream of progress events) |
 | \`/api/publish/retry-index\` | POST | Retry indexing for a published file |
 | \`/api/publish/upload-cover\` | POST | Upload cover image — FormData \`file\` field, **WebP or JPEG only**, max 1MB → returns \`{ cid }\` |
@@ -77,6 +82,7 @@ Both upload-cover and update-storyline sign messages with the OWS wallet.
 | \`/api/stories/:name/:file\` | GET | Single file content and publish status |
 | \`/api/stories/:name/:file\` | PUT | Update file content \`{ content }\` |
 | \`/api/stories/:name/:file/publish-status\` | POST | Record publish result (txHash, storylineId, etc.) |
+| \`/api/stories/:name/metadata\` | POST | Write story metadata \`{ contentType }\` |
 | \`/api/stories/:name/:file/mark-not-indexed\` | POST | Mark file as not indexed \`{ indexError? }\` |
 
 ## Terminal
@@ -110,6 +116,7 @@ Stories live in \`~/.plotlink-ows/stories/{story-name}/\`:
 
 \`\`\`
 stories/{story-name}/
+  .story.json     # Content type metadata (fiction | cartoon)
   structure.md    # Outline, characters, arc
   genesis.md      # Synopsis hook (~1000 chars)
   plot-01.md      # Chapter 1 (max 10K chars)