/** * TOC page numbers, offline: print, read where each heading landed from the * printed PDF itself, write those numbers into the TOC, and print again until * the numbers the PDF shows are the numbers its own layout produced. * * Why this strategy (#2903): Chromium's print engine has no CSS * `target-counter()`, and a pagination polyfill (Paged.js) would mean running * a third-party script inside the user's browser profile on untrusted * markdown and re-implementing the layout Chromium already does. Instead the * oracle is the PDF: the TOC links make Chromium (Skia) write one named * destination per target heading — `/Dests << /toc-0 [ /XYZ …] >>` * in the catalog — and the page tree gives each page ref its 1-based number, * the same physical number the `counter(page)` footer prints. * * No script is injected and nothing is fetched, so the offline/sanitization * boundary is unchanged. Every failure is explicit (TocPaginationError → * exit 3): a PDF this parser cannot read, a TOC target with no destination, * or numbers that have not settled after MAX_PRINTS. A TOC with empty * page-number cells is never written. */ import * as fs from "node:fs"; import * as path from "node:path"; /** Prints needed is normally 2 (measure, then confirm); the third absorbs one reflow. */ export const MAX_PRINTS = 3; export class TocPaginationError extends Error { constructor(message: string) { super(message); this.name = "TocPaginationError"; } } const TOC_SECTION = /
[\s\S]*?<\/section>/; const TOC_PAGE_SPAN = /()[^<]*(<\/span>)/g; function decodeAttr(s: string): string { return s .replace(/</g, "<") .replace(/>/g, ">") .replace(/"/g, '"') .replace(/'/g, "'") .replace(/&/g, "&"); } /** * The key a TOC target and its PDF destination share. Chromium names a * destination after the link's URL fragment, percent-encoded (`#café` → * `/caf#25C3#25A9`), so both sides compare percent-decoded. */ function destKey(id: string): string { try { return decodeURIComponent(id); } catch { return id; } } /** TOC target keys, in TOC order. Empty when the document has no TOC. */ export function tocTargets(html: string): string[] { const toc = html.match(TOC_SECTION)?.[0] ?? ""; return [...toc.matchAll(TOC_PAGE_SPAN)].map((m) => destKey(decodeAttr(m[2]))); } /** Write each target's page from `pages` (keyed by tocTargets keys; 0 when unknown) into its TOC cell. */ export function fillTocPages(html: string, pages: ReadonlyMap): string { return html.replace(TOC_SECTION, (toc) => toc.replace(TOC_PAGE_SPAN, (_m, open: string, target: string, close: string, end: string) => `${open}${target}${close}${pages.get(destKey(decodeAttr(target))) ?? 0}${end}`)); } // ─── PDF reading (classic xref, as Chromium/Skia writes it) ─────────────── /** PDF name token (after the slash) → string: `#xx` escapes are UTF-8 bytes. */ function decodePdfName(raw: string): string { const bytes: number[] = []; for (let i = 0; i < raw.length; i++) { if (raw[i] === "#" && /^[0-9a-fA-F]{2}$/.test(raw.slice(i + 1, i + 3))) { bytes.push(parseInt(raw.slice(i + 1, i + 3), 16)); i += 2; } else { bytes.push(raw.charCodeAt(i) & 0xff); } } return Buffer.from(bytes).toString("utf8"); } /** * Named destination (as a tocTargets key) → 1-based page number, read from a PDF's catalog /Dests * dictionary and page tree. Throws TocPaginationError when the file is not a * PDF this reader understands (cross-reference streams, a /Dests name tree). */ export function pdfDestinationPages(pdf: Uint8Array): Map { const fail = (why: string): never => { throw new TocPaginationError(`could not read TOC page numbers from the printed PDF: ${why}`); }; const s = Buffer.from(pdf).toString("latin1"); const startxref = s.match(/startxref\s+(\d+)\s+%%EOF\s*$/); if (!startxref) return fail("no startxref trailer"); const xrefAt = Number(startxref[1]); if (!s.startsWith("xref", xrefAt)) return fail("cross-reference streams are not supported"); const offsets = new Map(); const trailerAt = s.indexOf("trailer", xrefAt); if (trailerAt < 0) return fail("no trailer dictionary"); const table = s.slice(xrefAt + 4, trailerAt).trim().split(/\r?\n|\r/); for (let i = 0; i < table.length;) { const [first, count] = table[i].trim().split(/\s+/).map(Number); for (let k = 0; k < count; k++) { const [off, , kind] = (table[i + 1 + k] ?? "").trim().split(/\s+/); if (kind === "n") offsets.set(first + k, Number(off)); } i += 1 + count; } const object = (num: number): string => { const at = offsets.get(num); if (at === undefined) return fail(`object ${num} is not in the cross-reference table`); const end = s.indexOf("endobj", at); return s.slice(at, end < 0 ? undefined : end); }; const ref = (body: string, key: string): number | null => { const m = body.match(new RegExp(`/${key}\\s+(\\d+)\\s+\\d+\\s+R`)); return m ? Number(m[1]) : null; }; const root = ref(s.slice(trailerAt), "Root") ?? fail("trailer has no /Root"); const catalog = object(root); const pagesRoot = ref(catalog, "Pages") ?? fail("catalog has no /Pages"); const pageNumber = new Map(); const walk = (num: number, depth: number): void => { if (depth > 32) fail("page tree is too deep"); const node = object(num); const kids = node.match(/\/Kids\s*\[([^\]]*)\]/); if (/\/Type\s*\/Pages\b/.test(node) && kids) { for (const k of kids[1].matchAll(/(\d+)\s+\d+\s+R/g)) walk(Number(k[1]), depth + 1); } else { pageNumber.set(num, pageNumber.size + 1); } }; walk(pagesRoot, 0); const pages = new Map(); const destsRef = ref(catalog, "Dests"); if (destsRef === null) { if (/\/Names\s*<<[^>]*\/Dests/.test(catalog)) fail("named destinations in a /Names tree are not supported"); return pages; } for (const m of object(destsRef).matchAll(/\/([^\s()<>[\]{}/%]+)\s*\[\s*(\d+)\s+\d+\s+R/g)) { const page = pageNumber.get(Number(m[2])); if (page !== undefined) pages.set(destKey(decodePdfName(m[1])), page); } return pages; } // ─── Print loop ─────────────────────────────────────────────────────────── /** * Print `html` to `output` with every TOC page cell holding the page its * heading prints on. `print(html, out)` prints one PDF (one browser render). * Returns print's result from the accepted pass. */ export async function printWithTocPages( html: string, output: string, print: (html: string, out: string) => Promise, ): Promise { const targets = tocTargets(html); if (targets.length === 0) return print(html, output); const tmp = path.join(path.dirname(output), `.${path.basename(output)}.toc-pass.pdf`); let pages: ReadonlyMap = new Map(); try { for (let pass = 1; pass <= MAX_PRINTS; pass++) { const result = await print(fillTocPages(html, pages), tmp); const printed = pdfDestinationPages(fs.readFileSync(tmp)); const missing = targets.filter((t) => !printed.has(t)); if (missing.length > 0) { throw new TocPaginationError( `the printed PDF has no destination for TOC target(s) ${missing.map((t) => `#${t}`).join(", ")}; ` + `their links and page numbers would be wrong`); } if (targets.every((t) => pages.get(t) === printed.get(t))) { fs.renameSync(tmp, output); return result; } pages = printed; } throw new TocPaginationError( `TOC page numbers did not settle after ${MAX_PRINTS} prints (adding them reflowed the document); ` + `drop --toc or shorten the longest TOC entries`); } finally { fs.rmSync(tmp, { force: true }); } }