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

9.5 KB
Raw Blame
/**
 * Comic lettering density / balloon load (#1313) — pure word/balloon accounting
 * over the parsed comic-script pages the `comicScriptParser` emits.
 *
 * The #1 reader gripe in comics is a wall of text crammed into one panel: an
 * over-stuffed balloon, too many balloons fighting for room, or a page whose
 * total lettering load overwhelms the art. `comicScriptParser.js` already parses
 * per-panel dialogue / caption / SFX but never counts words — this module does
 * the counting and flags overflows against industry rules-of-thumb (all
 * configurable): ~25 words per balloon, ~50 words per panel, ~3 balloons per
 * panel, and a per-page lettering ceiling.
 *
 * PURE + side-effect-free so it is unit-testable and so the SAME helper backs
 * both the server-side editorial check (`comic.lettering-density` in
 * checkRegistry.js) and the client comic-script stage inline warnings
 * (`client/src/lib/letteringDensity.js` re-exports this module, so the browser
 * bundle runs this code rather than a copy).
 *
 * A "balloon" is a discrete lettering element the reader's eye lands on: each
 * dialogue entry is one balloon, and each caption box is one (captions repeat —
 * the parser folds `Caption` / `Caption 2` into one newline-joined string, so
 * each non-empty line counts as a box). SFX is lettering and counts toward the
 * panel/page WORD load, but it is rendered as a sound effect rather than a
 * balloon, so it does NOT count toward the balloon tally.
 */

import { countWords } from '../textUtils.js';

// Industry rules-of-thumb (all overridable via the check's config). A balloon
// much over ~20–25 words reads as a wall of text; a panel over ~45–50 words
// crowds the art; more than ~3 balloons in a panel is hard to follow; and a
// page much past ~150 words of lettering starts to bury the illustration.
export const DEFAULT_LETTERING_THRESHOLDS = Object.freeze({
  maxWordsPerBalloon: 25,
  maxWordsPerPanel: 50,
  maxBalloonsPerPanel: 3,
  maxWordsPerPage: 150,
});

// The severity ranks an overflow can scale to (high → low), most-severe first.
// Local copy so this stays self-contained and the client re-export needs nothing
// from checkRegistry.
const LETTERING_SEVERITIES = ['high', 'medium', 'low'];

// Severity scaled by how far over the threshold a count runs (#1313 "severity
// scaled by overflow"): ≥2× the limit is `high`, ≥1.4× is `medium`, otherwise a
// mild overflow is `low`. Pure so it's unit-testable. A count at/under the
// threshold returns `low` but callers only invoke it for genuine overflows.
export function overflowSeverity(count, threshold) {
  if (!(threshold > 0)) return 'medium';
  const ratio = count / threshold;
  if (ratio >= 2) return 'high';
  if (ratio >= 1.4) return 'medium';
  return 'low';
}

// Merge a (possibly hand-edited / partial) config object over the defaults,
// guarding each field's type so a bad value can't crash the scan. A
// non-positive threshold disables that rule (treated as Infinity).
export function sanitizeLetteringThresholds(config) {
  const c = config && typeof config === 'object' ? config : {};
  const pick = (key) => {
    const v = c[key];
    if (typeof v === 'number' && Number.isFinite(v) && v > 0) return v;
    return DEFAULT_LETTERING_THRESHOLDS[key];
  };
  return {
    maxWordsPerBalloon: pick('maxWordsPerBalloon'),
    maxWordsPerPanel: pick('maxWordsPerPanel'),
    maxBalloonsPerPanel: pick('maxBalloonsPerPanel'),
    maxWordsPerPage: pick('maxWordsPerPage'),
  };
}

// Per-panel lettering metrics from a parsed panel
// (`{ description, caption, dialogue: [{ character, line }], sfx }`). Pure.
//
//   - `balloons`     — one entry per dialogue balloon: { speaker, words, line }.
//   - `captionBoxes` — one entry per non-empty caption line: { words, text }.
//   - `balloonCount` — dialogue balloons + caption boxes (the reader-facing tally).
//   - `totalWords`   — dialogue + caption + SFX words (the full lettering load).
export function panelLetteringMetrics(panel) {
  const dialogue = Array.isArray(panel?.dialogue) ? panel.dialogue : [];
  const balloons = dialogue.map((d) => {
    const line = typeof d?.line === 'string' ? d.line : '';
    return {
      speaker: typeof d?.character === 'string' ? d.character.trim() : '',
      words: countWords(line),
      line,
    };
  });
  const caption = typeof panel?.caption === 'string' ? panel.caption : '';
  const captionBoxes = caption
    .split('\n')
    .map((l) => l.trim())
    .filter(Boolean)
    .map((text) => ({ words: countWords(text), text }));
  const sfx = typeof panel?.sfx === 'string' ? panel.sfx : '';
  const dialogueWords = balloons.reduce((sum, b) => sum + b.words, 0);
  const captionWords = captionBoxes.reduce((sum, b) => sum + b.words, 0);
  const sfxWords = countWords(sfx);
  return {
    balloons,
    captionBoxes,
    balloonCount: balloons.length + captionBoxes.length,
    dialogueWords,
    captionWords,
    sfxWords,
    totalWords: dialogueWords + captionWords + sfxWords,
  };
}

// First real lettering text in a panel, for anchoring a panel/page-level finding
// to something the editor can actually locate in the script (prefer a dialogue
// line, then a caption, then SFX). '' when the panel has no lettering at all.
function firstLetteringText(metrics) {
  const balloon = metrics.balloons.find((b) => b.line.trim());
  if (balloon) return balloon.line.trim();
  const box = metrics.captionBoxes.find((b) => b.text);
  return box ? box.text : '';
}

/**
 * Analyze the parsed pages of ONE comic script for lettering overflows.
 *
 * @param {Array<{ panels: Array<object> }>} pages  parseComicScript(...).pages
 * @param {object} [config]  threshold overrides (see DEFAULT_LETTERING_THRESHOLDS)
 * @returns {Array<object>} flat list of violations, each:
 *   { kind, pageNumber, panelNumber?, balloonIndex?, boxIndex?, speaker?, count,
 *     threshold, limitLabel, severity, anchorQuote }
 *   `kind` ∈ 'balloon-words' | 'caption-words' | 'panel-words' | 'panel-balloons' | 'page-words'.
 *   `pageNumber` / `panelNumber` are 1-based (panel within its page).
 */
export function analyzeComicLettering(pages, config) {
  const t = sanitizeLetteringThresholds(config);
  const list = Array.isArray(pages) ? pages : [];
  const violations = [];
  list.forEach((page, pageIdx) => {
    const pageNumber = pageIdx + 1;
    const panels = Array.isArray(page?.panels) ? page.panels : [];
    let pageWords = 0;
    panels.forEach((panel, panelIdx) => {
      const panelNumber = panelIdx + 1;
      const m = panelLetteringMetrics(panel);
      pageWords += m.totalWords;

      // An individual balloon over the per-balloon word ceiling — the most
      // actionable signal (split it, or move some to a caption).
      m.balloons.forEach((balloon, balloonIndex) => {
        if (balloon.words > t.maxWordsPerBalloon) {
          violations.push({
            kind: 'balloon-words',
            pageNumber,
            panelNumber,
            balloonIndex,
            speaker: balloon.speaker,
            count: balloon.words,
            threshold: t.maxWordsPerBalloon,
            limitLabel: 'words in one balloon',
            severity: overflowSeverity(balloon.words, t.maxWordsPerBalloon),
            anchorQuote: balloon.line.trim(),
          });
        }
      });

      // A single caption box over the same per-balloon word ceiling. Caption boxes
      // count as balloons (toward `maxBalloonsPerPanel`) and the threshold's help
      // says it applies to caption boxes too, so an over-stuffed narration box must
      // trip the word limit just like a speech balloon — even when the panel total
      // stays under `maxWordsPerPanel`.
      m.captionBoxes.forEach((box, boxIndex) => {
        if (box.words > t.maxWordsPerBalloon) {
          violations.push({
            kind: 'caption-words',
            pageNumber,
            panelNumber,
            boxIndex,
            count: box.words,
            threshold: t.maxWordsPerBalloon,
            limitLabel: 'words in one caption box',
            severity: overflowSeverity(box.words, t.maxWordsPerBalloon),
            anchorQuote: box.text,
          });
        }
      });

      // The whole panel carries too much lettering across all its balloons.
      if (m.totalWords > t.maxWordsPerPanel) {
        violations.push({
          kind: 'panel-words',
          pageNumber,
          panelNumber,
          count: m.totalWords,
          threshold: t.maxWordsPerPanel,
          limitLabel: 'words in one panel',
          severity: overflowSeverity(m.totalWords, t.maxWordsPerPanel),
          anchorQuote: firstLetteringText(m),
        });
      }

      // Too many discrete balloons fighting for room in one panel.
      if (m.balloonCount > t.maxBalloonsPerPanel) {
        violations.push({
          kind: 'panel-balloons',
          pageNumber,
          panelNumber,
          count: m.balloonCount,
          threshold: t.maxBalloonsPerPanel,
          limitLabel: 'balloons in one panel',
          severity: overflowSeverity(m.balloonCount, t.maxBalloonsPerPanel),
          anchorQuote: firstLetteringText(m),
        });
      }
    });

    // The page's total lettering load would overwhelm the art.
    if (pageWords > t.maxWordsPerPage) {
      violations.push({
        kind: 'page-words',
        pageNumber,
        count: pageWords,
        threshold: t.maxWordsPerPage,
        limitLabel: 'words on one page',
        severity: overflowSeverity(pageWords, t.maxWordsPerPage),
        anchorQuote: '',
      });
    }
  });
  return violations;
}

// Re-export the severity vocabulary so a consumer can reason about ordering
// without importing the registry.
export { LETTERING_SEVERITIES };