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
/**
* proseExport.js — Prose series export (issue #2181).
*
* The shipping step for a prose-format series: once the quality-engine phases
* produce publishable prose, this stitches the drafted issue prose (in arc
* order, grouped into volume breaks) into three downloadable artifacts:
*
* 1. Compiled manuscript — Markdown with front matter, volume breaks, and
* chapter headings. Reuses the same `collectManuscriptSections` stitching
* the editorial passes use (arc-ordered, drafted-prose-only), so the
* exported prose is the same text the editor and the LLM see; only the
* surrounding front matter / volume / chapter framing is added here.
* 2. ePub — an OCF (zip) container: `mimetype` + container.xml
* + an OPF package manifest + a nav doc + per-volume XHTML chapters + CSS,
* plus the cover image from the existing cover stage. Packaged in-repo with
* `server/lib/zipWriter.js` (no epub dependency, per the dependency policy).
* 3. Print-interior PDF — a trade-format interior (trim size, margins,
* running heads, title page, chapter openers) built on the same `@cantoo/pdf-lib`
* plumbing as `volumePdf.js` / `comicPdf.js`.
*
* All three are assembled on demand and streamed straight to the response — no
* on-disk artifact, so a re-export always reflects the freshest manuscript.
*
* The pure helpers (markdown/XHTML/OPF builders + the paginator) are exported
* via `__testing` so the export shape is unit-tested without touching disk.
*/
import { PDFDocument, rgb, StandardFonts } from '@cantoo/pdf-lib';
import { createZip } from '../../lib/zipWriter.js';
import { slugifyForFilename } from '../../lib/civitai.js';
import { readImageFromMedia, detectImageKind } from '../../lib/pdfImageEmbed.js';
import { resolveExportSettings, TRIM_SIZES, DEFAULT_TRIM_SIZE } from '../../lib/proseExportSettings.js';
import { getSeries } from './series.js';
import { listSeasons } from './seasons.js';
import { collectManuscriptSections } from './arcPlanner.js';
import { codedError } from '../../lib/codedError.js';
export const ERR_NO_PROSE = 'PIPELINE_PROSE_EXPORT_NO_CONTENT';
// ---------------------------------------------------------------------------
// Section gathering — the shared front for all three exports.
// ---------------------------------------------------------------------------
/**
* Collect the drafted prose sections in arc order and group them into volumes
* by `seasonId`. Returns `{ series, sections, volumes }` where `volumes` is an
* ordered list of `{ id, title, number, sections }`. Sections that don't map to
* a known season (or a series with no seasons) fall into a single implicit
* volume so nothing is dropped. Throws ERR_NO_PROSE when no issue has drafted
* prose.
*/
export async function gatherProse(seriesId) {
const series = await getSeries(seriesId);
// Prose export = the `prose` stage ONLY. The default stageOrder
// (MANUSCRIPT_STAGES) also picks up comicScript/teleplay, which would package
// non-prose text (screenplay/comic-script markup) into an ePub/manuscript; a
// prose series' authored artifact is its `prose` stage. `idea` is excluded
// either way (never export an outline as finished prose).
const sections = await collectManuscriptSections(seriesId, { stageOrder: ['prose'] });
if (!sections.length) {
throw codedError(
'No drafted prose to export — write or import prose on at least one issue first.',
ERR_NO_PROSE,
);
}
const seasons = await listSeasons(seriesId);
const volumes = groupIntoVolumes(sections, seasons);
return { series, sections, volumes };
}
/**
* Group ordered sections into volumes by seasonId, preserving section order.
* Season order comes from the series' `seasons[]` (by `number` then order of
* appearance); an unknown/absent seasonId collapses into one trailing
* "Unassigned" volume. When the series has zero seasons every section lands in a
* single untitled volume. Pure — exported via __testing.
*/
export function groupIntoVolumes(sections, seasons = []) {
const seasonById = new Map((seasons || []).map((s) => [s.id, s]));
const buckets = new Map(); // seasonId|'__none__' → { season, sections }
for (const sec of sections) {
const key = sec.seasonId && seasonById.has(sec.seasonId) ? sec.seasonId : '__none__';
if (!buckets.has(key)) buckets.set(key, { season: seasonById.get(sec.seasonId) || null, sections: [] });
buckets.get(key).sections.push(sec);
}
// Order volumes by the season list's order; the implicit "__none__" bucket
// always sorts last.
const ordered = [];
for (const s of (seasons || [])) {
if (buckets.has(s.id)) ordered.push(buckets.get(s.id));
}
if (buckets.has('__none__')) ordered.push(buckets.get('__none__'));
// A series whose sections all landed in __none__ and had no season match →
// just that one bucket. Number volumes sequentially for display.
return ordered.map((b, idx) => ({
id: b.season?.id || `__vol-${idx + 1}`,
number: b.season?.number || idx + 1,
title: b.season?.title || (ordered.length > 1 ? `Volume ${idx + 1}` : ''),
sections: b.sections,
}));
}
// ---------------------------------------------------------------------------
// 1) Compiled manuscript (Markdown)
// ---------------------------------------------------------------------------
/**
* Build the compiled-manuscript Markdown string: YAML front matter (title /
* author / date), then each volume as a `# Volume` break, then each issue as a
* `## Chapter` heading followed by its prose. Single-volume series omit the
* volume break. Pure over `{ series, volumes }` — exported via __testing.
*/
export function buildManuscriptMarkdown({ series, volumes }, settings) {
const cfg = settings || resolveExportSettings(series);
const lines = [];
lines.push('---');
lines.push(`title: ${yamlValue(cfg.titlePageTitle)}`);
if (cfg.titlePageSubtitle) lines.push(`subtitle: ${yamlValue(cfg.titlePageSubtitle)}`);
if (cfg.titlePageAuthor) lines.push(`author: ${yamlValue(cfg.titlePageAuthor)}`);
lines.push(`date: ${new Date().toISOString().slice(0, 10)}`);
lines.push('---');
lines.push('');
if (cfg.dedication) {
lines.push(`> ${cfg.dedication.replace(/\n/g, '\n> ')}`);
lines.push('');
}
const multiVolume = volumes.length > 1;
for (const vol of volumes) {
if (multiVolume) {
lines.push(`# ${vol.title || `Volume ${vol.number}`}`);
lines.push('');
}
for (const sec of vol.sections) {
const heading = sec.title ? `Chapter ${sec.number} — ${sec.title}` : `Chapter ${sec.number}`;
lines.push(`## ${heading}`);
lines.push('');
lines.push((sec.content || '').trim());
lines.push('');
}
}
return `${lines.join('\n').trimEnd()}\n`;
}
const yamlValue = (v) => {
const s = String(v ?? '');
// Quote when the value could confuse a YAML parser (colons, leading specials).
return /[:#\-\[\]{}&*!|>'"%@`]/.test(s) ? JSON.stringify(s) : s;
};
export async function buildManuscriptFile(seriesId) {
const { series, volumes } = await gatherProse(seriesId);
const settings = resolveExportSettings(series);
const markdown = buildManuscriptMarkdown({ series, volumes }, settings);
return {
text: markdown,
filename: `${slugifyForFilename(series.name || 'series')}-manuscript.md`,
};
}
// ---------------------------------------------------------------------------
// 2) ePub (OCF container)
// ---------------------------------------------------------------------------
const escapeXml = (s) => String(s ?? '')
.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>')
.replace(/"/g, '"').replace(/'/g, ''');
// Render one section's plain-text prose into XHTML paragraphs. Blank-line-
// separated blocks become <p>; single newlines inside a block become <br/>.
export function proseToXhtmlBody(content) {
const blocks = String(content || '').split(/\n{2,}/).map((b) => b.trim()).filter(Boolean);
if (!blocks.length) return '<p></p>';
return blocks.map((b) => `<p>${escapeXml(b).replace(/\n/g, '<br/>')}</p>`).join('\n');
}
// One XHTML chapter document for a whole volume (its chapters stacked). A
// volume-title header is emitted only for multi-volume books.
export function buildChapterXhtml(vol, { multiVolume }) {
const parts = [];
parts.push('<?xml version="1.0" encoding="UTF-8"?>');
parts.push('<!DOCTYPE html>');
parts.push('<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops">');
parts.push(`<head><title>${escapeXml(vol.title || `Volume ${vol.number}`)}</title>`);
parts.push('<link rel="stylesheet" type="text/css" href="style.css"/></head>');
parts.push('<body>');
if (multiVolume) parts.push(`<h1 class="volume-title">${escapeXml(vol.title || `Volume ${vol.number}`)}</h1>`);
for (const sec of vol.sections) {
const heading = sec.title ? `Chapter ${sec.number} — ${sec.title}` : `Chapter ${sec.number}`;
parts.push(`<section epub:type="chapter" id="ch-${escapeXml(sec.issueId)}">`);
parts.push(`<h2 class="chapter-title">${escapeXml(heading)}</h2>`);
parts.push(proseToXhtmlBody(sec.content));
parts.push('</section>');
}
parts.push('</body></html>');
return parts.join('\n');
}
// The OPF package document (EPUB 3): metadata + manifest + spine.
export function buildOpf({ settings, volumes, coverImage, bookId }) {
const items = [];
const spine = [];
items.push('<item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>');
items.push('<item id="style" href="style.css" media-type="text/css"/>');
if (coverImage) {
items.push(`<item id="cover-image" href="${escapeXml(coverImage.name)}" media-type="${coverImage.mediaType}" properties="cover-image"/>`);
}
volumes.forEach((vol, idx) => {
const id = `vol${idx + 1}`;
items.push(`<item id="${id}" href="${id}.xhtml" media-type="application/xhtml+xml"/>`);
spine.push(`<itemref idref="${id}"/>`);
});
const modified = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
const lines = [];
lines.push('<?xml version="1.0" encoding="UTF-8"?>');
lines.push('<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="book-id">');
lines.push('<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">');
lines.push(`<dc:identifier id="book-id">${escapeXml(bookId)}</dc:identifier>`);
lines.push(`<dc:title>${escapeXml(settings.titlePageTitle)}</dc:title>`);
lines.push('<dc:language>en</dc:language>');
if (settings.titlePageAuthor) lines.push(`<dc:creator>${escapeXml(settings.titlePageAuthor)}</dc:creator>`);
if (settings.titlePageSubtitle) lines.push(`<dc:description>${escapeXml(settings.titlePageSubtitle)}</dc:description>`);
lines.push(`<meta property="dcterms:modified">${modified}</meta>`);
if (coverImage) lines.push('<meta name="cover" content="cover-image"/>');
lines.push('</metadata>');
lines.push(`<manifest>${items.join('')}</manifest>`);
lines.push(`<spine>${spine.join('')}</spine>`);
lines.push('</package>');
return lines.join('\n');
}
// The EPUB 3 nav document (table of contents).
export function buildNavXhtml({ settings, volumes }) {
const multiVolume = volumes.length > 1;
const lis = [];
volumes.forEach((vol, idx) => {
const href = `vol${idx + 1}.xhtml`;
const label = multiVolume ? (vol.title || `Volume ${vol.number}`) : (settings.titlePageTitle || 'Text');
lis.push(`<li><a href="${href}">${escapeXml(label)}</a></li>`);
});
return [
'<?xml version="1.0" encoding="UTF-8"?>',
'<!DOCTYPE html>',
'<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops">',
`<head><title>${escapeXml(settings.titlePageTitle)}</title></head>`,
'<body>',
'<nav epub:type="toc" id="toc"><h1>Contents</h1>',
`<ol>${lis.join('')}</ol>`,
'</nav>',
'</body></html>',
].join('\n');
}
const EPUB_CSS = `body { font-family: serif; line-height: 1.5; margin: 5%; }
h1.volume-title { text-align: center; margin: 2em 0; page-break-before: always; }
h2.chapter-title { text-align: center; margin: 2em 0 1em; page-break-before: always; }
p { margin: 0; text-indent: 1.5em; }
p:first-of-type { text-indent: 0; }
`;
const CONTAINER_XML = `<?xml version="1.0" encoding="UTF-8"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
<rootfiles>
<rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
</rootfiles>
</container>`;
// Resolve the series cover image (if any) into `{ name, mediaType, bytes }` for
// the ePub manifest. `series.coverImage` is a plain filename string (stamped by
// the cover filename hooks / setSeriesCoverImage). Returns null when there's no
// rendered cover — the ePub is still valid without one.
async function resolveCoverImage(series) {
const filename = typeof series?.coverImage === 'string' && series.coverImage ? series.coverImage : null;
if (!filename) return null;
const bytes = await readImageFromMedia(filename, { subject: 'series cover image' }).catch(() => null);
if (!bytes) return null;
const kind = detectImageKind(bytes, filename);
if (!kind) return null;
const mediaType = kind === 'png' ? 'image/png' : 'image/jpeg';
const ext = kind === 'png' ? 'png' : 'jpg';
return { name: `cover.${ext}`, mediaType, bytes };
}
/**
* Build the ePub as a Buffer. The OCF spec requires the `mimetype` entry to be
* first and stored (uncompressed) — everything else is deflated. Returns
* `{ bytes, filename }`.
*/
export async function buildEpub(seriesId) {
const { series, volumes } = await gatherProse(seriesId);
const settings = resolveExportSettings(series);
const bookId = `urn:portos:series:${series.id}`;
const coverImage = await resolveCoverImage(series);
const multiVolume = volumes.length > 1;
// OCF requires `mimetype` to be the FIRST entry, stored (uncompressed). It is
// first in this list, and its 20-byte payload never shrinks under deflate, so
// `createZip`'s "keep deflate only when smaller" rule stores it — satisfying
// the spec while the bulkier text entries below still compress.
const entries = [
{ name: 'mimetype', data: 'application/epub+zip' },
{ name: 'META-INF/container.xml', data: CONTAINER_XML },
{ name: 'OEBPS/content.opf', data: buildOpf({ settings, volumes, coverImage, bookId }) },
{ name: 'OEBPS/nav.xhtml', data: buildNavXhtml({ settings, volumes }) },
{ name: 'OEBPS/style.css', data: EPUB_CSS },
...volumes.map((vol, idx) => ({ name: `OEBPS/vol${idx + 1}.xhtml`, data: buildChapterXhtml(vol, { multiVolume }) })),
];
if (coverImage) entries.push({ name: `OEBPS/${coverImage.name}`, data: coverImage.bytes });
const bytes = createZip(entries, { compress: true });
return {
bytes,
filename: `${slugifyForFilename(series.name || 'series')}.epub`,
};
}
// ---------------------------------------------------------------------------
// 3) Print-interior PDF
// ---------------------------------------------------------------------------
// Greedy word-wrap a paragraph to `maxWidth` at `size` using @cantoo/pdf-lib font
// metrics. Returns an array of lines. Pure over the font (exported via
// __testing with a stub `widthOfTextAtSize`).
export function wrapText(text, font, size, maxWidth) {
const words = String(text || '').split(/\s+/).filter(Boolean);
const lines = [];
let line = '';
for (const word of words) {
const candidate = line ? `${line} ${word}` : word;
if (font.widthOfTextAtSize(candidate, size) <= maxWidth || !line) {
line = candidate;
} else {
lines.push(line);
line = word;
}
}
if (line) lines.push(line);
return lines;
}
const PDF_FONT_MAP = {
times: { regular: StandardFonts.TimesRoman, bold: StandardFonts.TimesRomanBold, italic: StandardFonts.TimesRomanItalic },
helvetica: { regular: StandardFonts.Helvetica, bold: StandardFonts.HelveticaBold, italic: StandardFonts.HelveticaOblique },
courier: { regular: StandardFonts.Courier, bold: StandardFonts.CourierBold, italic: StandardFonts.CourierOblique },
};
/**
* Build the print-interior PDF as a Uint8Array. Trade-format interior: title
* page → per-volume/-chapter body with running heads (author verso, title
* recto) and page numbers, wrapping the prose to the text block. Reuses the
* `@cantoo/pdf-lib` plumbing from volumePdf.js. Returns `{ bytes, pageCount, filename }`.
*/
export async function buildProsePdf(seriesId) {
const { series, volumes } = await gatherProse(seriesId);
const settings = resolveExportSettings(series);
const trim = TRIM_SIZES[settings.trimSize] || TRIM_SIZES[DEFAULT_TRIM_SIZE];
const { width: pageW, height: pageH } = trim;
const pdf = await PDFDocument.create();
pdf.setTitle(settings.titlePageTitle);
if (settings.titlePageAuthor) pdf.setAuthor(settings.titlePageAuthor);
if (settings.titlePageSubtitle) pdf.setSubject(settings.titlePageSubtitle);
pdf.setProducer('PortOS');
const fontKey = PDF_FONT_MAP[settings.interiorFont] ? settings.interiorFont : 'times';
const font = await pdf.embedFont(PDF_FONT_MAP[fontKey].regular);
const fontBold = await pdf.embedFont(PDF_FONT_MAP[fontKey].bold);
const margin = 54; // 0.75"
const bodySize = 11;
const lineHeight = bodySize * 1.4;
const textW = pageW - margin * 2;
const topY = pageH - margin;
const bottomY = margin + 24; // reserve room for the page-number footer
const runningHead = settings.titlePageTitle;
const author = settings.titlePageAuthor;
let pageNo = 0;
let pageCount = 0;
// --- Title page (no running head / number) ---
const title = pdf.addPage([pageW, pageH]);
pageCount += 1;
{
let cy = pageH * 0.62;
const centered = (text, sz, f) => {
const w = f.widthOfTextAtSize(text, sz);
title.drawText(text, { x: (pageW - w) / 2, y: cy, size: sz, font: f, color: rgb(0, 0, 0) });
cy -= sz * 1.6;
};
centered(settings.titlePageTitle, 24, fontBold);
if (settings.titlePageSubtitle) centered(settings.titlePageSubtitle, 13, font);
cy -= 24;
if (settings.titlePageAuthor) centered(settings.titlePageAuthor, 14, font);
if (settings.dedication) {
cy = pageH * 0.25;
for (const dl of wrapText(settings.dedication, font, 11, textW * 0.8)) {
const w = font.widthOfTextAtSize(dl, 11);
title.drawText(dl, { x: (pageW - w) / 2, y: cy, size: 11, font, color: rgb(0.3, 0.3, 0.3) });
cy -= 11 * 1.4;
}
}
if (settings.copyright) {
const w = font.widthOfTextAtSize(settings.copyright, 8);
title.drawText(settings.copyright.slice(0, 120), { x: (pageW - w) / 2, y: margin + 8, size: 8, font, color: rgb(0.4, 0.4, 0.4) });
}
}
const multiVolume = volumes.length > 1;
let page = null;
let y = 0;
const footer = (p, n) => {
const s = String(n);
const w = font.widthOfTextAtSize(s, 9);
p.drawText(s, { x: (pageW - w) / 2, y: margin, size: 9, font, color: rgb(0.4, 0.4, 0.4) });
};
const header = (p, text) => {
if (!text) return;
const w = font.widthOfTextAtSize(text, 8);
p.drawText(text, { x: (pageW - w) / 2, y: pageH - margin + 6, size: 8, font, color: rgb(0.5, 0.5, 0.5) });
};
const newPage = () => {
// Running head alternates: verso (even page number) = author, recto = title.
pageNo += 1;
page = pdf.addPage([pageW, pageH]);
pageCount += 1;
footer(page, pageNo);
header(page, pageNo % 2 === 0 ? author : runningHead);
y = topY;
};
const ensureSpace = (needed) => {
if (!page || y - needed < bottomY) newPage();
};
for (const vol of volumes) {
if (multiVolume) {
newPage();
y = pageH * 0.5;
const vt = vol.title || `Volume ${vol.number}`;
const w = fontBold.widthOfTextAtSize(vt, 20);
page.drawText(vt, { x: (pageW - w) / 2, y, size: 20, font: fontBold, color: rgb(0, 0, 0) });
y = bottomY; // force a fresh page for the first chapter
}
for (const sec of vol.sections) {
// Chapter opener starts on a fresh page.
newPage();
y = pageH * 0.72;
const heading = sec.title ? `Chapter ${sec.number} — ${sec.title}` : `Chapter ${sec.number}`;
for (const hl of wrapText(heading, fontBold, 16, textW)) {
const w = fontBold.widthOfTextAtSize(hl, 16);
page.drawText(hl, { x: (pageW - w) / 2, y, size: 16, font: fontBold, color: rgb(0, 0, 0) });
y -= 16 * 1.4;
}
y -= lineHeight;
const paras = String(sec.content || '').split(/\n{2,}/).map((p) => p.trim()).filter(Boolean);
for (const para of paras) {
const wrapped = wrapText(para, font, bodySize, textW);
for (let i = 0; i < wrapped.length; i += 1) {
ensureSpace(lineHeight);
// First-line indent for continued paragraphs (not the chapter's first).
const indent = i === 0 ? 18 : 0;
page.drawText(wrapped[i], { x: margin + indent, y, size: bodySize, font, color: rgb(0, 0, 0) });
y -= lineHeight;
}
y -= lineHeight * 0.3; // paragraph gap
}
}
}
const bytes = await pdf.save();
return {
bytes,
pageCount,
filename: `${slugifyForFilename(series.name || 'series')}-interior.pdf`,
};
}
export const __testing = {
groupIntoVolumes,
buildManuscriptMarkdown,
proseToXhtmlBody,
buildChapterXhtml,
buildOpf,
buildNavXhtml,
wrapText,
};