Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

13.1 KB
Raw Blame
/**
 * Comic-specific check helpers (#2842 split of checkInfra.js): lettering density
 * / balloon load accounting (#1313) and the comic↔prose synchronization pairing
 * (#1589).
 */

import { parseComicScript } from './externals.js';

// ---------------------------------------------------------------------------
// Comic lettering density / balloon load (#1313) — deterministic over each
// issue's parsed comic script. The pure word/balloon accounting + threshold
// evaluation lives in ./letteringDensity.js (shared with the client comic-script
// stage's inline warnings); the helpers below turn its violations into
// manuscriptReview findings and pre-flight whether any issue even has a script
// (the check's gate). Scope is 'issue' — findings carry the issue number so the
// editor groups them per issue / per page.
// ---------------------------------------------------------------------------

// The AUTHORITATIVE comic pages for an issue (parser-shaped `[{ panels: [...] }]`).
// A POPULATED per-page split (`stages.comicPages.pages[]`) WINS over the generated
// markdown (`stages.comicScript.output`): once a script is split into pages, edits
// in the Comic tab persist to `comicPages.pages[].rawText/panels` and never flow
// back to `comicScript.output`, so reading the raw script would analyze stale text
// (flag balloons the user already cut, miss ones they added). The client
// comic-script stage reads the same `comicPages.pages[].panels`, so both surfaces
// judge the same edited content.
//
// We key on `pages.length`, not `Array.isArray(pages)`, on purpose: the issue
// sanitizer (`sanitizeVisualStage`) ALWAYS materializes `comicPages.pages` as `[]`,
// so an EMPTY array can't distinguish "never split" from "split then all pages
// deleted" — they are byte-identical on disk. Falling back to the still-present
// generated script when the split is empty means an UNSPLIT or IMPORTED script
// (the common pre-render case, where lettering feedback matters most) is still
// checked; the script remains the issue's authored comic text even if a prior
// split was emptied.
export function comicIssuePages(issue) {
  const pages = issue?.stages?.comicPages?.pages;
  if (Array.isArray(pages) && pages.length) {
    return pages.filter((p) => p && typeof p === 'object');
  }
  const output = typeof issue?.stages?.comicScript?.output === 'string' ? issue.stages.comicScript.output : '';
  return output.trim() ? parseComicScript(output).pages : [];
}

// Issues with analyzable comic content, as { number, pages }, sorted by issue
// number for a stable scan order. Shared by the lettering check's `run` AND the
// staleness runner's fingerprint (which projects the lettering-relevant fields off
// this), so the fingerprinted content is exactly what the check analyzes.
export function comicLetteringIssues(issues) {
  return (Array.isArray(issues) ? issues : [])
    .map((i) => ({
      number: Number.isInteger(i?.number) ? i.number : null,
      pages: comicIssuePages(i),
    }))
    .filter((i) => i.pages.length)
    .sort((a, b) => (a.number ?? 0) - (b.number ?? 0));
}

// Cheap presence test for the check's gate — true when any issue has an edited
// comic-pages split OR a non-empty generated script — without paying the parse
// that `comicLetteringIssues` does.
export function hasComicContent(issues) {
  return (Array.isArray(issues) ? issues : []).some((i) => {
    const pages = i?.stages?.comicPages?.pages;
    if (Array.isArray(pages) && pages.length) return true;
    return (typeof i?.stages?.comicScript?.output === 'string' ? i.stages.comicScript.output : '').trim();
  });
}

// One human-readable { problem, suggestion } per violation kind. Kept here (not
// in the pure helper) because the wording is PortOS-facing copy, while the helper
// stays a reusable counting primitive.
function comicLetteringText(v) {
  const who = v.speaker ? ` (${v.speaker})` : '';
  switch (v.kind) {
    case 'balloon-words':
      return {
        problem: `A balloon${who} runs ${v.count} words — over the ~${v.threshold}-word balloon limit. A wall of text crammed into one balloon is the #1 reader gripe in comics.`,
        suggestion: 'Split the balloon in two, move some of it to a caption, or trim the line.',
      };
    case 'caption-words':
      return {
        problem: `A caption box runs ${v.count} words — over the ~${v.threshold}-word limit. A dense narration box buries the art the same way an over-stuffed balloon does.`,
        suggestion: 'Tighten the caption, split it across panels, or cut it down.',
      };
    case 'panel-words':
      return {
        problem: `This panel carries ${v.count} words of lettering — over the ~${v.threshold}-word panel limit, crowding the art.`,
        suggestion: 'Spread the lettering across more panels, or cut copy so the art can breathe.',
      };
    case 'panel-balloons':
      return {
        problem: `This panel has ${v.count} balloons — more than the ~${v.threshold} a single panel reads cleanly with.`,
        suggestion: 'Break the exchange across more panels, or merge balloons from the same speaker.',
      };
    case 'page-words':
    default:
      return {
        problem: `This page carries ${v.count} words of lettering — over the ~${v.threshold}-word page ceiling; the text load would overwhelm the art.`,
        suggestion: 'Move some beats to adjacent pages, or trim copy so the page is not text-heavy.',
      };
  }
}

// Map a lettering violation to a manuscriptReview finding for issue `number`.
// `panelNumber` is absent for page-level findings, so the location degrades to
// "Issue N · Page P" cleanly. Severity rides the violation's overflow-scaled
// value (#1313).
export function comicLetteringFinding(v, number) {
  const { problem, suggestion } = comicLetteringText(v);
  const where = v.panelNumber != null
    ? `Page ${v.pageNumber} · Panel ${v.panelNumber}`
    : `Page ${v.pageNumber}`;
  return {
    severity: v.severity,
    category: 'lettering',
    location: number != null ? `Issue ${number} · ${where}` : where,
    problem,
    suggestion,
    anchorQuote: typeof v.anchorQuote === 'string' ? v.anchorQuote : '',
    issueNumber: number,
  };
}

// Map a balloon-attribution violation to a manuscriptReview finding for issue
// `number`. The wording is PortOS-facing copy (kept here, not in the pure
// helper). Severity rides the violation's risk-scaled value.
export function balloonAttributionFinding(v, number) {
  const where = `Page ${v.pageNumber} · Panel ${v.panelNumber}`;
  const more = v.panelCount > 1 ? ` (and ${v.panelCount - 1} more panel${v.panelCount - 1 === 1 ? '' : 's'} on this page)` : '';
  const target = Array.isArray(v.visibleOthers) && v.visibleOthers.length
    ? ` Another character (${v.visibleOthers.slice(0, 3).join(', ')}) IS shown on the page, so the balloon will likely be tailed to the wrong character.`
    : ' No one is clearly shown speaking it, so the balloon reads as orphaned.';
  return {
    severity: v.severity,
    category: 'continuity',
    location: number != null ? `Issue ${number} · ${where}` : where,
    problem: `${v.speaker} speaks here${more} but is not shown anywhere on the page and the line carries no off-panel/broadcast cue.${target}`,
    suggestion: `Either show ${v.speaker} in a panel on this page, or mark the line as spoken from elsewhere — e.g. ${v.speaker} (OFF-PANEL), (V.O.), (RADIO), or (SPEAKERS)/(PA) for a broadcast — so it renders as a disembodied balloon instead of being attributed to a visible character.`,
    anchorQuote: typeof v.anchorQuote === 'string' ? v.anchorQuote : '',
    issueNumber: number,
  };
}

// ---------------------------------------------------------------------------
// Comic ↔ prose synchronization helpers (#1589). The cross-media check pairs each
// hybrid issue's PROSE (a manuscript section) with its authoritative COMIC content
// and feeds the pair to the model. Pure + deterministic so they're unit-testable
// in isolation (the LLM caller is injected via ctx.callStagedLLM).
// ---------------------------------------------------------------------------

// Per-issue prose ceiling fed to the comic↔prose check (#1589) — so a long
// chapter can't blow a small/local provider's window. Unlike the manuscript-
// corpus checks (which chunk the whole series), this check makes ONE call per
// hybrid issue with that issue's prose + comic, so the bound is per-issue. The
// comic content is the smaller, authoritative anchor; the prose is sliced to this
// ceiling and the prompt warns the model the prose may be truncated. ~24k chars
// ≈ 6k tokens, which fits alongside the comic block on every supported provider.
export const PROSE_SYNC_PROSE_CHAR_CAP = 24_000;

// Extract an issue's PROSE-stage text. Inlines arcPlanner's `stageTextOf` (output
// then input) to keep the registry import-pure (no service import). Reads the
// `prose` stage SPECIFICALLY — NOT the default manuscript precedence (comicScript ▸
// teleplay ▸ prose), which for a hybrid comic+prose issue would return the comic
// script, not the prose (the bug this check exists to avoid). Returns '' when the
// issue has no prose-stage text.
function proseStageText(issue) {
  const stage = issue?.stages?.prose;
  const output = typeof stage?.output === 'string' ? stage.output.trim() : '';
  if (output) return output;
  return typeof stage?.input === 'string' ? stage.input.trim() : '';
}

// Per-issue PROSE-stage content, as `{ number, prose }`, sorted by issue number.
// The single source of truth for "the prose half" of the comic↔prose-sync check —
// read by BOTH the check's `run` AND the runner's `prose` staleness resolver
// (mirrors `comicLetteringIssues` for the comic half), so the fingerprinted text is
// exactly what the check compares. Only issues with prose-stage text contribute.
export function proseStageIssues(issues) {
  return (Array.isArray(issues) ? issues : [])
    .map((i) => ({ number: Number.isInteger(i?.number) ? i.number : null, prose: proseStageText(i) }))
    .filter((i) => i.prose)
    .sort((a, b) => (a.number ?? 0) - (b.number ?? 0));
}

// Render an issue's parsed comic pages into a compact, model-readable block —
// page/panel headers plus each panel's visual DESCRIPTION (what the panel SHOWS),
// DIALOGUE (`speaker: line`), CAPTION, and SFX — so the model can compare what the
// comic shows and says against the prose. Mirrors the field set in
// `projectComicPacingContent` (the `comicScript.pacing` source this check
// fingerprints), so the rendered content matches what staleness tracks. Returns ''
// when no panel carries any content.
export function renderComicForProseSync(pages) {
  const lines = [];
  (Array.isArray(pages) ? pages : []).forEach((p, pageIdx) => {
    const panels = Array.isArray(p?.panels) ? p.panels : [];
    panels.forEach((panel, panelIdx) => {
      const block = [];
      const desc = typeof panel?.description === 'string' ? panel.description.trim() : '';
      if (desc) block.push(`  Shows: ${desc}`);
      for (const d of (Array.isArray(panel?.dialogue) ? panel.dialogue : [])) {
        // The comic-script parser keys the speaker as `character` ({ character, line }),
        // the same field balloonAttribution/letteringDensity read — NOT `speaker`.
        // Tolerate a `speaker` alias for robustness, but `character` is the real shape.
        const rawSpeaker = typeof d?.character === 'string' ? d.character : (typeof d?.speaker === 'string' ? d.speaker : '');
        const speaker = rawSpeaker.trim();
        const line = typeof d?.line === 'string' ? d.line.trim() : '';
        if (line) block.push(`  ${speaker ? `${speaker}: ` : ''}${line}`);
      }
      const caption = typeof panel?.caption === 'string' ? panel.caption.trim() : '';
      if (caption) block.push(`  Caption: ${caption}`);
      const sfx = typeof panel?.sfx === 'string' ? panel.sfx.trim() : '';
      if (sfx) block.push(`  SFX: ${sfx}`);
      // Skip an entirely empty panel — no content to cross-check against prose.
      if (block.length) {
        lines.push(`Page ${pageIdx + 1} · Panel ${panelIdx + 1}`, ...block);
      }
    });
  });
  return lines.join('\n');
}

// The issues that have BOTH drafted PROSE-stage text AND comic content — the
// comparable set for the comic↔prose sync check. Returns `[{ number, prose, comic }]`
// sorted by issue number (`comicLetteringIssues` already sorts), prose sliced to
// PROSE_SYNC_PROSE_CHAR_CAP. An issue with comic but no prose (or prose but no
// comic) has nothing to cross-check and is skipped. Pure: reads ctx.issues only —
// both halves come off the already-loaded issue records (the prose STAGE, not the
// comicScript-precedence manuscript section).
export function proseSyncPairs(ctx) {
  const proseByIssue = new Map();
  for (const { number, prose } of proseStageIssues(ctx?.issues)) {
    if (Number.isInteger(number)) proseByIssue.set(number, prose);
  }
  const pairs = [];
  for (const { number, pages } of comicLetteringIssues(ctx?.issues)) {
    if (!Number.isInteger(number)) continue;
    const prose = proseByIssue.get(number);
    if (!prose) continue;
    const comic = renderComicForProseSync(pages);
    if (!comic.trim()) continue;
    pairs.push({ number, prose: prose.slice(0, PROSE_SYNC_PROSE_CHAR_CAP), comic });
  }
  return pairs;
}