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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Pure comic-pacing primitives for the comic editorial checks (#1314) —
* splash-page usage, panel rhythm, and page-turn beat placement. Operates on the
* ALREADY-PARSED comic pages the runner produces from each issue's stored comic
* script (`comicScriptParser.parseComicScript().pages`), so this module stays
* dependency-free (the parser imports out to fileUtils, which the pure editorial
* registry can't), matching nameSimilarity.js / proseTics.js.
*
* A parsed page is `{ rawText, panels: [{ description, caption, dialogue, sfx }] }`.
* These helpers never read ctx, never throw on a malformed page, and return plain
* data the registry's `run(ctx)` shapes into findings (with `ctx.severityDefault`).
*/
// A page with exactly one panel is a splash — a single full-page image. Zero
// panels can't happen for a kept page (the parser drops contentless panels and
// filters empty pages), but guard anyway so a hand-built page array is inert.
export const isSplashPage = (page) => Array.isArray(page?.panels) && page.panels.length === 1;
// The recto/verso layout of a comic interior, 1-indexed by page number.
//
// Print convention: page 1 is a RECTO (the right-hand page, paired with the
// inside front cover). From page 2 on, the reader sees two-page SPREADS —
// verso (even, left) + recto (odd, right). A page turn flips the recto and
// reveals the NEXT spread's pages all at once, so a beat on a page is "visible
// early" (pre-turn) once any page of its spread is on-screen. `beginsSpread`
// marks the first page of each spread — the page that only appears after a turn,
// where a reveal stays hidden until the reader commits to it.
export function comicSpreadLayout(pageCount) {
const n = Number.isInteger(pageCount) && pageCount > 0 ? pageCount : 0;
const layout = [];
for (let p = 1; p <= n; p += 1) {
if (p === 1) {
layout.push({ pageNumber: 1, side: 'recto', spread: 1, beginsSpread: true });
continue;
}
const side = p % 2 === 0 ? 'verso' : 'recto';
const spread = Math.floor(p / 2) + 1;
// A verso (even page) opens each spread after page 1; its recto partner
// completes the same spread. Page 1's spread is opened by page 1 itself.
layout.push({ pageNumber: p, side, spread, beginsSpread: side === 'verso' });
}
return layout;
}
// Collapse whitespace and neutralize markdown fence delimiters in an authored
// string. BOTH renderers below (the page-layout digest AND the reader-map summary)
// embed their output inside a ``` fenced block in the page-turn prompt, so a
// backtick run in any authored text (a panel or a reveal note that quotes
// code/markdown) could otherwise close the fence early and turn the rest of the
// prompt into unstructured text. Backtick fidelity is irrelevant to the model's
// pacing judgment, so collapse any run of backticks to a single quote. Every
// user-authored snippet that reaches either fenced block passes through here.
const fenceSafe = (s) => (typeof s === 'string' ? s.trim().replace(/\s+/g, ' ').replace(/`+/g, "'") : '');
// fenceSafe + truncate to `max` chars, for the per-panel digest snippets.
const clip = (s, max) => {
const t = fenceSafe(s);
return t.length > max ? `${t.slice(0, max)}…` : t;
};
// A compact, type-guarded one-line digest of a panel's content for the page-turn
// LLM context — its description (truncated) PLUS truncated snippets of the
// caption / dialogue / SFX text. The text matters because a reveal or cliffhanger
// is often delivered in a caption or a line of dialogue rather than the visual
// description; a presence-only marker ("caption", "1 dialogue") would hide the
// actual beat from the model, so the snippets are included (not just counts).
function panelDigest(panel) {
if (!panel || typeof panel !== 'object') return '';
const desc = clip(panel.description, 160);
const head = desc || '(no description)';
const extras = [];
const caption = clip(panel.caption, 80);
if (caption) extras.push(`caption: "${caption}"`);
const dialogue = Array.isArray(panel.dialogue) ? panel.dialogue : [];
for (const d of dialogue) {
// Parsed dialogue is `{ character, line }`; tolerate a bare string too.
const speaker = typeof d?.character === 'string' ? d.character.trim() : '';
const line = clip(typeof d === 'string' ? d : d?.line, 80);
if (!line) continue;
extras.push(speaker ? `${speaker}: "${line}"` : `dialogue: "${line}"`);
}
const sfx = clip(panel.sfx, 40);
if (sfx) extras.push(`sfx: ${sfx}`);
return extras.length ? `${head} [${extras.join('; ')}]` : head;
}
// Per-page summary used by both the deterministic rhythm analysis and the
// page-turn LLM context: panel count, splash flag, recto/verso side + spread,
// and a short content digest. `pages` is one issue's parsed comic pages.
export function summarizeComicPages(pages) {
const list = Array.isArray(pages) ? pages : [];
const layout = comicSpreadLayout(list.length);
return list.map((page, i) => {
const panels = Array.isArray(page?.panels) ? page.panels : [];
const pos = layout[i] || { pageNumber: i + 1, side: 'recto', spread: 1, beginsSpread: true };
return {
pageNumber: pos.pageNumber,
panelCount: panels.length,
isSplash: isSplashPage(page),
side: pos.side,
spread: pos.spread,
beginsSpread: pos.beginsSpread,
panels: panels.map(panelDigest),
};
});
}
// Deterministic panel-rhythm + splash analysis over one issue's parsed pages.
// Returns plain signals (no severity / finding text — the registry's run() shapes
// those) so the heuristics stay unit-testable in isolation:
//
// - splashPages — page numbers that are full-page splashes.
// - splashRatio — splashes / total pages (0 when no pages).
// - splashOveruse — true when splashRatio is at/above `splashRatioWarn`
// AND there is more than one splash (a lone splash on a
// short script isn't overuse).
// - backToBackSplashes — runs of >= 2 consecutive splash pages, as
// { startPage, endPage, length }.
// - overcrowded — pages with more than `maxPanelsPerPage` panels, as
// { pageNumber, panelCount }.
// - monotonyRuns — runs of >= `monotonyRunLength` consecutive pages that
// all carry the SAME (multi-panel) panel count, as
// { startPage, endPage, panelCount, length }. Splash
// runs are reported separately, so a monotony run needs
// panelCount >= 2.
export function analyzePanelRhythm(pages, cfg = {}) {
const list = Array.isArray(pages) ? pages : [];
const totalPages = list.length;
const maxPanelsPerPage = Number.isFinite(cfg.maxPanelsPerPage) ? cfg.maxPanelsPerPage : 9;
const splashRatioWarn = Number.isFinite(cfg.splashRatioWarn) ? cfg.splashRatioWarn : 0.25;
const monotonyRunLength = Number.isInteger(cfg.monotonyRunLength) ? cfg.monotonyRunLength : 4;
const counts = list.map((p) => (Array.isArray(p?.panels) ? p.panels.length : 0));
const splashPages = [];
const overcrowded = [];
counts.forEach((c, i) => {
const pageNumber = i + 1;
if (c === 1) splashPages.push(pageNumber);
if (c > maxPanelsPerPage) overcrowded.push({ pageNumber, panelCount: c });
});
const splashRatio = totalPages > 0 ? splashPages.length / totalPages : 0;
const splashOveruse = splashPages.length > 1 && splashRatio >= splashRatioWarn;
// Consecutive-splash runs (length >= 2).
const backToBackSplashes = collectRuns(counts, (c) => c === 1, 2)
.map((r) => ({ startPage: r.start + 1, endPage: r.end + 1, length: r.length }));
// Monotony runs: same multi-panel count repeated for >= monotonyRunLength pages.
// A run of identical splashes is a back-to-back-splash signal, not grid monotony,
// so monotony is gated to panelCount >= 2.
const monotonyRuns = [];
if (monotonyRunLength >= 2) {
let start = 0;
for (let i = 1; i <= counts.length; i += 1) {
if (i < counts.length && counts[i] === counts[start]) continue;
const length = i - start;
const panelCount = counts[start];
if (panelCount >= 2 && length >= monotonyRunLength) {
monotonyRuns.push({ startPage: start + 1, endPage: i, panelCount, length });
}
start = i;
}
}
return { totalPages, splashPages, splashRatio, splashOveruse, backToBackSplashes, overcrowded, monotonyRuns };
}
// Collect runs of >= minLength consecutive entries satisfying `pred`, as
// { start, end, length } (0-indexed, inclusive). Shared by the splash-run scan.
function collectRuns(arr, pred, minLength) {
const runs = [];
let start = -1;
for (let i = 0; i <= arr.length; i += 1) {
const ok = i < arr.length && pred(arr[i]);
if (ok && start === -1) start = i;
if (!ok && start !== -1) {
const length = i - start;
if (length >= minLength) runs.push({ start, end: i - 1, length });
start = -1;
}
}
return runs;
}
// Render one issue's page layout into a compact text block the page-turn-beats
// LLM check passes alongside the manuscript/script so the model knows each page's
// recto/verso side, spread, panel breakdown, and which pages are first-seen only
// after a page turn (`beginsSpread`). Pure + deterministic so it's unit-testable
// and its token cost can be counted into the per-chunk overhead. Returns '' for an
// empty page list. `issueNumber` (when an integer) prefixes the block.
export function comicPageTurnSummary(pages, issueNumber = null) {
const summary = summarizeComicPages(pages);
if (!summary.length) return '';
const lines = summary.map((pg) => {
const turn = pg.beginsSpread ? ', first page after a turn (reveal-safe)' : '';
const kind = pg.isSplash ? 'splash' : `${pg.panelCount} panels`;
const panels = pg.panels.length ? `\n ${pg.panels.map((p, i) => `panel ${i + 1}: ${p}`).join('\n ')}` : '';
return `- Page ${pg.pageNumber} (${pg.side}, spread ${pg.spread}${turn}) — ${kind}${panels}`;
});
const header = Number.isInteger(issueNumber) ? `Issue ${issueNumber} page layout:` : 'Page layout:';
return `${header}\n${lines.join('\n')}`;
}
// Render the authored reader-map REVEALS and CLIFFHANGERS into a compact text
// block the page-turn-beats check passes alongside the script, so the model
// reconciles WHICH beats are big reveals/cliffhangers that need a protected
// page-turn against what the writer logged. Both the timeline beats with kind
// 'reveal' OR 'cliffhanger' (`readerMap.beats`) AND the separate issue-boundary
// cliffhanger list (`readerMap.cliffhangers`) are surfaced — a cliffhanger stored
// as a beat must not be dropped. Pure + deterministic (mirrors
// authoredCliffhangerSummary / authoredSetupPayoffSummary in the registry).
// Returns '' when nothing reveal-like is authored.
const REVEAL_BEAT_KINDS = new Set(['reveal', 'cliffhanger']);
export function authoredRevealSummary(readerMap) {
const beats = Array.isArray(readerMap?.beats) ? readerMap.beats : [];
const cliffs = Array.isArray(readerMap?.cliffhangers) ? readerMap.cliffhangers : [];
const revealLines = beats
.filter((b) => REVEAL_BEAT_KINDS.has(b?.kind))
.map((b) => {
// fenceSafe (not bare trim): the note is embedded in a ``` block in the prompt.
const note = fenceSafe(b?.note);
if (!note) return '';
// Tag a cliffhanger beat so the model can tell it from a mid-issue reveal.
const tag = b?.kind === 'cliffhanger' ? ' [cliffhanger]' : '';
const pos = Number.isFinite(b?.atArcPosition) ? ` (arc position ${b.atArcPosition})` : '';
return `- ${note}${tag}${pos}`;
})
.filter(Boolean);
const cliffLines = cliffs
.map((c) => {
const note = fenceSafe(c?.note);
if (!note) return '';
const at = Number.isInteger(c?.atIssueBoundary) ? ` (ending issue ${c.atIssueBoundary})` : '';
return `- ${note}${at}`;
})
.filter(Boolean);
if (!revealLines.length && !cliffLines.length) return '';
const parts = [];
if (revealLines.length) parts.push(`Authored reveals (beats the writer planted):\n${revealLines.join('\n')}`);
if (cliffLines.length) parts.push(`Authored cliffhangers (issue-boundary tugs):\n${cliffLines.join('\n')}`);
return parts.join('\n\n');
}