@bli-cockpit/cli 0.2.270 → 0.2.272

package/dist/pdf-byte-scan.js

@@ -0,0 +1,109 @@
+/**
+ * Find the base64 PDFs of one transcript line on its BYTES (BLI-23347), the PDF twin of `image-byte-scan.ts`.
+ *
+ * Claude Code stores a PDF it read twice on one line (`message.content[].content[].source.data` and
+ * `toolUseResult.file.base64`). Two shapes are recognised, both ASCII so a byte offset here is the character
+ * offset on ASCII text:
+ *
+ *  - a whole-string payload: a base64 run that starts right after a `"` with `JVBERi0` (the base64 of
+ *    `%PDF-`), is at least `PDF_MIN_BASE64_CHARS` long and is closed by `"` or by `\"` (a string that was
+ *    itself stored inside a string; `escapeDepth` says which, so the replacement is escaped to match);
+ *  - a data URL `data:application/pdf;base64,` followed by such a run; the whole URL is the replaced range.
+ *
+ * The run is hashed in blocks of 48 Ki characters straight from the line, so neither a string of the
+ * run nor a Buffer of the whole PDF exists here; the first block is sniffed for `%PDF-`. A run whose `=`
+ * characters are not plain trailing padding is not a PDF we can vouch for and is left alone.
+ */
+import { createHash } from "node:crypto";
+const QUOTE = 0x22;
+const BACKSLASH = 0x5c;
+const EQUALS = 0x3d;
+/** Characters per decoded block. A multiple of 4: each block is a whole number of base64 quanta. */
+const BLOCK_CHARS = 48 * 1024;
+/** Below this a "PDF" is a stub, not a document anyone read (a one-line minimal PDF is about 400 bytes). */
+export const PDF_MIN_BASE64_CHARS = 600;
+const BASE64 = new Uint8Array(256);
+for (const range of ["AZ", "az", "09"]) {
+    for (let code = range.charCodeAt(0); code <= range.charCodeAt(1); code += 1)
+        BASE64[code] = 1;
+}
+for (const char of "+/=")
+    BASE64[char.charCodeAt(0)] = 1;
+const START = Buffer.from("JVBERi0", "latin1");
+const DATA_URL = Buffer.from("data:application/pdf;base64,", "latin1");
+const PDF_MAGIC = Buffer.from("%PDF-", "latin1");
+/** Is there any chance this line holds a PDF? */
+export function bytesMayHoldPdf(line) {
+    return line.includes(START) || line.includes(DATA_URL);
+}
+function runEnd(line, from) {
+    let at = from;
+    while (at < line.length && BASE64[line[at]] === 1)
+        at += 1;
+    return at;
+}
+/** sha256 and decoded size of the PDF `line[from, to)` encodes, or null when it is not one we can vouch for. */
+export function digestPdfRun(line, from, to) {
+    const length = to - from;
+    const firstPad = line.subarray(from, to).indexOf(EQUALS);
+    if (firstPad !== -1) {
+        const padCount = length - firstPad;
+        if (padCount > 2 || length % 4 !== 0)
+            return null;
+        for (let at = from + firstPad; at < to; at += 1)
+            if (line[at] !== EQUALS)
+                return null;
+    }
+    const hash = createHash("sha256");
+    let byteSize = 0;
+    for (let at = from; at < to; at += BLOCK_CHARS) {
+        const block = Buffer.from(line.toString("latin1", at, Math.min(to, at + BLOCK_CHARS)), "base64");
+        if (at === from && block.compare(PDF_MAGIC, 0, PDF_MAGIC.length, 0, PDF_MAGIC.length) !== 0)
+            return null;
+        hash.update(block);
+        byteSize += block.byteLength;
+    }
+    return { sha256: hash.digest("hex"), byteSize };
+}
+/** Every embedded PDF in one physical line, in order, with byte offsets inside the line. */
+export function scanPdfsInLine(line) {
+    const found = [];
+    if (line.length < PDF_MIN_BASE64_CHARS)
+        return found;
+    let position = 0;
+    while (position < line.length) {
+        const quoted = nextQuotedStart(line, position);
+        const dataUrl = line.indexOf(DATA_URL, position);
+        if (quoted === -1 && dataUrl === -1)
+            break;
+        const useUrl = dataUrl !== -1 && (quoted === -1 || dataUrl < quoted);
+        const base64Start = useUrl ? dataUrl + DATA_URL.length : quoted;
+        const end = runEnd(line, base64Start);
+        position = Math.max(end, base64Start + 1);
+        if (end - base64Start < PDF_MIN_BASE64_CHARS)
+            continue;
+        let escapeDepth = 0;
+        if (!useUrl) {
+            const plain = end < line.length && line[end] === QUOTE;
+            const escaped = end + 1 < line.length && line[end] === BACKSLASH && line[end + 1] === QUOTE;
+            if (!plain && !escaped)
+                continue;
+            escapeDepth = escaped ? 1 : 0;
+        }
+        else if (dataUrl >= 2 && line[dataUrl - 2] === BACKSLASH && line[dataUrl - 1] === QUOTE) {
+            escapeDepth = 1;
+        }
+        const digest = digestPdfRun(line, base64Start, end);
+        if (!digest)
+            continue;
+        found.push({ replaceStart: useUrl ? dataUrl : base64Start, replaceEnd: end, base64Start, base64End: end, escapeDepth, ...digest });
+    }
+    return found;
+}
+/** The next index at or after `from` where the PDF start sits right after a `"`, or -1. */
+function nextQuotedStart(line, from) {
+    let at = line.indexOf(START, from);
+    while (at !== -1 && !(at > 0 && line[at - 1] === QUOTE))
+        at = line.indexOf(START, at + 1);
+    return at;
+}

package/dist/pdf-conversion-cache.js

@@ -0,0 +1,91 @@
+/**
+ * What a PDF became, kept on disk by its sha256 so a transcript that is rebuilt every tick does not re-read
+ * the same PDF every tick (BLI-23347).
+ *
+ * One small JSON file per distinct PDF under `<state dir>/pdf-conversions/`: the converted text, or for a
+ * scan the page list (page number, sha256 and size of each page image). Never the PDF, never a page image,
+ * never a path: the text is what the transcript carries anyway. A file written by other rules (a different
+ * `PDF_RULES_VERSION`) or damaged is treated as absent, with the reason logged. At most `MAX_ENTRIES` files
+ * stay; the oldest go first.
+ */
+import { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { PDF_RULES_VERSION } from "@bli-cockpit/telemetry-core";
+const TAG = "[pdf-cache]";
+const DIRECTORY = "pdf-conversions";
+const MAX_ENTRIES = 300;
+const SHA = /^[0-9a-f]{64}$/;
+function fileOf(stateDir, sha256) {
+    return path.join(stateDir, DIRECTORY, `${sha256}.json`);
+}
+function valid(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    if (typeof record["pages"] !== "number" || !Array.isArray(record["notes"]) || !record["notes"].every((note) => typeof note === "string"))
+        return false;
+    if (record["kind"] === "text")
+        return typeof record["body"] === "string";
+    if (record["kind"] !== "scanned" || !Array.isArray(record["pageImages"]))
+        return false;
+    return record["pageImages"].every((entry) => typeof entry === "object" && entry !== null
+        && typeof entry["page"] === "number"
+        && typeof entry["sha256"] === "string" && SHA.test(entry["sha256"])
+        && typeof entry["byteSize"] === "number");
+}
+export async function readCachedPdf(stateDir, sha256) {
+    let raw;
+    try {
+        raw = await readFile(fileOf(stateDir, sha256), "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            console.error(TAG + " entry unreadable, converting again", JSON.stringify({ reason: "cache_read_failed", error_name: error instanceof Error ? error.name : typeof error }));
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.rules !== PDF_RULES_VERSION) {
+            console.error(TAG + " entry made by other rules, converting again", JSON.stringify({ reason: "cache_rules_changed" }));
+            return null;
+        }
+        if (valid(parsed.entry))
+            return parsed.entry;
+    }
+    catch {
+        // Falls through to the damaged-entry log below.
+    }
+    console.error(TAG + " entry damaged, converting again", JSON.stringify({ reason: "cache_entry_invalid", byte_size: raw.length }));
+    return null;
+}
+export async function writeCachedPdf(stateDir, sha256, entry) {
+    const directory = path.join(stateDir, DIRECTORY);
+    const target = fileOf(stateDir, sha256);
+    const partial = `${target}.${process.pid}.partial`;
+    try {
+        await mkdir(directory, { recursive: true });
+        await writeFile(partial, JSON.stringify({ rules: PDF_RULES_VERSION, entry }), "utf8");
+        await rename(partial, target);
+    }
+    catch (error) {
+        await unlink(partial).catch(() => undefined);
+        console.error(TAG + " entry not saved, it will be converted again next time", JSON.stringify({ reason: "cache_write_failed", error_name: error instanceof Error ? error.name : typeof error }));
+        return;
+    }
+    await prune(directory);
+}
+async function prune(directory) {
+    try {
+        const names = (await readdir(directory)).filter((name) => name.endsWith(".json"));
+        if (names.length <= MAX_ENTRIES)
+            return;
+        const aged = await Promise.all(names.map(async (name) => ({ name, mtime: (await stat(path.join(directory, name)).catch(() => null))?.mtimeMs ?? 0 })));
+        aged.sort((a, b) => a.mtime - b.mtime);
+        const drop = aged.slice(0, names.length - MAX_ENTRIES + 50);
+        await Promise.all(drop.map(({ name }) => unlink(path.join(directory, name)).catch(() => undefined)));
+        console.error(TAG + " oldest entries removed", JSON.stringify({ reason: "cache_over_limit", removed: drop.length, kept: names.length - drop.length }));
+    }
+    catch (error) {
+        console.error(TAG + " prune failed", JSON.stringify({ reason: "cache_prune_failed", error_name: error instanceof Error ? error.name : typeof error }));
+    }
+}

package/dist/pdf-convert.js

@@ -0,0 +1,152 @@
+/**
+ * One PDF's bytes to what the transcript keeps (BLI-23347): its text with tables kept, or, for a scan with no
+ * text layer, the PNG of each page's image so the existing image describe door can read it.
+ *
+ * pdf.js comes from `unpdf`, which ships it as one self-contained module: no native dependency, no canvas, so
+ * macOS and Windows behave the same. A scan is not RENDERED (that needs a canvas); each page's largest embedded
+ * image is decoded by pdf.js's own decoders and re-encoded by `pdf-page-image.ts`. A page drawn as vector shapes
+ * with no text and no image has nothing to extract and is named as such.
+ *
+ * Bounded: the document is held once (the caller's bytes), one page's raster at a time, at most
+ * `MAX_TEXT_PAGES` pages of text, `MAX_TEXT_CHARS` of it, `MAX_IMAGE_PAGES` page images, and a wall-clock
+ * budget per document. Hitting a bound is said in `notes`, never silent. Never throws: a document that cannot
+ * be read comes back as `failed` with a reason label.
+ *
+ * CHANGING WHAT THIS PRODUCES (limits, the text/scan rule, pdf-layout.ts heuristics) MUST BUMP
+ * `PDF_RULES_VERSION` in telemetry-core so every collector rebuilds the transcripts it converted.
+ */
+import { IMAGE_DESCRIBE_MAX_BYTES } from "@bli-cockpit/telemetry-core";
+import { layoutPage } from "./pdf-layout.js";
+import { rasterToPagePng } from "./pdf-page-image.js";
+export const MAX_TEXT_PAGES = 300;
+export const MAX_TEXT_CHARS = 400_000;
+export const MAX_IMAGE_PAGES = 8;
+export const MAX_CONVERT_MS = 25_000;
+/** A document whose first pages hold fewer characters per page than this has no usable text layer. */
+const MIN_CHARS_PER_PAGE = 30;
+/** Pages sampled to decide text or scan. */
+const SAMPLE_PAGES = 10;
+let loading;
+/** pdf.js through unpdf, loaded once per process; null (and a logged reason) when the package is missing. */
+async function loadPdfJs() {
+    loading ??= import("unpdf")
+        .then(async (unpdf) => (await unpdf.getResolvedPDFJS()))
+        .catch((error) => {
+        console.error("[pdf-convert] extractor unavailable", JSON.stringify({ reason: "extractor_unavailable", error_name: error instanceof Error ? error.name : typeof error }));
+        return null;
+    });
+    return loading;
+}
+function textItemsOf(content) {
+    const items = [];
+    for (const item of content.items) {
+        if (typeof item.str !== "string" || !item.transform)
+            continue;
+        items.push({ str: item.str, x: item.transform[4], y: item.transform[5], width: item.width ?? 0, size: Math.abs(item.transform[3]) || item.height || 10 });
+    }
+    return items;
+}
+/** Control characters other than tab and newline mean nothing to a reader and break line-oriented tools. */
+function clean(text) {
+    return text.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
+}
+function failure(error, pages) {
+    const name = error instanceof Error ? error.name : typeof error;
+    const reason = name === "PasswordException" ? "password_protected" : name === "InvalidPDFException" || name === "FormatError" ? "not_a_readable_pdf" : "extract_error";
+    return { kind: "failed", reason, pages };
+}
+async function pageRaster(pdfjs, page) {
+    const list = await page.getOperatorList();
+    let best = null;
+    for (let index = 0; index < list.fnArray.length; index += 1) {
+        const op = list.fnArray[index];
+        if (op !== pdfjs.OPS.paintImageXObject && op !== pdfjs.OPS.paintInlineImageXObject)
+            continue;
+        const arg = list.argsArray[index]?.[0];
+        let image = arg;
+        if (typeof arg === "string") {
+            image = page.objs.has(arg) ? page.objs.get(arg) : await new Promise((resolve) => { page.objs.get(arg, resolve); });
+        }
+        const candidate = image;
+        if (!candidate?.data || !candidate.width || !candidate.height || (candidate.kind !== 1 && candidate.kind !== 2 && candidate.kind !== 3))
+            continue;
+        if (!best || candidate.width * candidate.height > best.width * best.height)
+            best = candidate;
+    }
+    return best;
+}
+export async function convertPdf(bytes, now = Date.now) {
+    const started = now();
+    const pdfjs = await loadPdfJs();
+    if (!pdfjs)
+        return { kind: "failed", reason: "extractor_unavailable", pages: null };
+    const task = pdfjs.getDocument({ data: bytes, isEvalSupported: false, disableFontFace: true, useSystemFonts: false, verbosity: 0 });
+    let doc;
+    try {
+        doc = await task.promise;
+        const pages = doc.numPages;
+        // Text first: the first pages decide text or scan, and a text document goes on page by page.
+        const rendered = [];
+        const notes = [];
+        let chars = 0;
+        let sampledChars = 0;
+        let shown = 0;
+        for (let number = 1; number <= Math.min(pages, MAX_TEXT_PAGES); number += 1) {
+            if (now() - started > MAX_CONVERT_MS) {
+                notes.push(`stopped after ${MAX_CONVERT_MS / 1000} s`);
+                break;
+            }
+            const page = await doc.getPage(number);
+            const text = clean(layoutPage(textItemsOf(await page.getTextContent())));
+            page.cleanup();
+            if (number <= SAMPLE_PAGES)
+                sampledChars += text.replace(/\s/g, "").length;
+            if (number === Math.min(pages, SAMPLE_PAGES) && sampledChars < MIN_CHARS_PER_PAGE * number)
+                return await scannedPages(pdfjs, doc, pages, started, now);
+            if (chars + text.length > MAX_TEXT_CHARS) {
+                notes.push(`text cut at ${MAX_TEXT_CHARS} characters`);
+                break;
+            }
+            chars += text.length;
+            rendered.push(text === "" ? `[page ${number}: no text]` : `[page ${number}]\n${text}`);
+            shown = number;
+        }
+        // Nothing read (the time budget was gone before page one): never a text block of nothing in place of a document.
+        if (shown === 0)
+            return { kind: "failed", reason: "time_budget_spent_before_first_page", pages };
+        if (shown < pages)
+            notes.push(`pages 1-${shown} of ${pages} shown`);
+        return { kind: "text", pages, body: rendered.join("\n\n"), notes };
+    }
+    catch (error) {
+        return failure(error, doc?.numPages ?? null);
+    }
+    finally {
+        await task.destroy().catch(() => undefined);
+    }
+}
+async function scannedPages(pdfjs, doc, pages, started, now) {
+    const pageImages = [];
+    const notes = ["no text layer"];
+    const missing = [];
+    const limit = Math.min(pages, MAX_IMAGE_PAGES);
+    for (let number = 1; number <= limit; number += 1) {
+        if (now() - started > MAX_CONVERT_MS) {
+            notes.push(`stopped after ${MAX_CONVERT_MS / 1000} s`);
+            break;
+        }
+        const page = await doc.getPage(number);
+        const raster = await pageRaster(pdfjs, page);
+        page.cleanup();
+        const png = raster ? rasterToPagePng(raster, IMAGE_DESCRIBE_MAX_BYTES - 100_000) : null;
+        if (png)
+            pageImages.push({ page: number, png });
+        else
+            missing.push(number);
+    }
+    if (missing.length > 0)
+        notes.push(`no page image on ${missing.length === 1 ? "page" : "pages"} ${missing.join(", ")}`);
+    if (pages > limit)
+        notes.push(`pages 1-${limit} of ${pages} described`);
+    return { kind: "scanned", pages, pageImages, notes };
+}

package/dist/pdf-layout.js

@@ -0,0 +1,287 @@
+/**
+ * One PDF page's text items to readable text, tables kept (BLI-23347).
+ *
+ * Pure: positioned text items in, a string out. No pdf library, no I/O, so the heuristics are tested on
+ * hand-made items and measured on real PDFs without a parser in the way.
+ *
+ * What it does, in order:
+ *  1. Items are grouped into ROWS by their baseline (y), left to right inside a row.
+ *  2. A page of two justified text columns (a paper) is split at its gutter, so the left column is read
+ *     before the right one; rows that cross the gutter (title, abstract, figure captions) stay whole.
+ *  3. Inside a row, items that sit close together join into one CELL; a gap of about a em starts the next.
+ *  4. Consecutive rows with two or more cells whose cells line up in the same vertical channels become a
+ *     Markdown table (first row is the header). Rows that do not line up stay plain lines, cells apart by
+ *     two spaces, so nothing is invented and nothing is dropped.
+ *
+ * Measured against `pdftotext -layout` on public PDFs: docs/architecture/pdf-transcripts.md.
+ */
+/** A gap wider than this many font sizes starts a new cell. */
+const CELL_GAP_EM = 0.5;
+/** A gap wider than this many font sizes between two items still needs a space when joining them. */
+const WORD_GAP_EM = 0.15;
+/** A vertical jump of more than this many font sizes between rows is a paragraph break (or the end of a table). */
+const BREAK_EM = 1.9;
+/** Rows of one table sit at most this many font sizes apart (booktabs rules add space around the header). */
+const TABLE_ROW_EM = 3;
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted.length === 0 ? 0 : sorted[Math.floor(sorted.length / 2)];
+}
+function toRows(items) {
+    const live = items.filter((item) => item.str.trim() !== "").sort((a, b) => b.y - a.y || a.x - b.x);
+    const rows = [];
+    for (const item of live) {
+        const last = rows[rows.length - 1];
+        if (last && Math.abs(last.y - item.y) <= Math.max(1.5, 0.5 * Math.min(last.size, item.size || last.size))) {
+            last.items.push(item);
+            last.size = Math.max(last.size, item.size);
+        }
+        else {
+            rows.push({ y: item.y, size: item.size || 10, items: [item], cells: [] });
+        }
+    }
+    const merged = attachScripts(rows);
+    for (const row of merged) {
+        row.items.sort((a, b) => a.x - b.x);
+        row.cells = cellsOf(row);
+    }
+    return merged;
+}
+/**
+ * A row of one or two tiny, smaller items right above or below a normal row is a superscript or subscript
+ * (`n·d²`), not a line of its own: it joins that row as `^2` or `_i`. Without this a table whose cells hold
+ * exponents is cut in pieces.
+ */
+function attachScripts(rows) {
+    const out = [];
+    for (let at = 0; at < rows.length; at += 1) {
+        const row = rows[at];
+        const chars = row.items.reduce((sum, item) => sum + item.str.trim().length, 0);
+        const near = [rows[at - 1], rows[at + 1]]
+            .filter((other) => other !== undefined && row.size <= 0.85 * other.size && Math.abs(other.y - row.y) <= 0.85 * other.size)
+            .sort((a, b) => Math.abs(a.y - row.y) - Math.abs(b.y - row.y))[0];
+        if (!near || chars > 6 || row.items.length > 2) {
+            out.push(row);
+            continue;
+        }
+        for (const item of row.items)
+            near.items.push({ ...item, str: `${item.y > near.y ? "^" : "_"}${item.str.trim()}` });
+    }
+    return out.filter((row, index) => out.indexOf(row) === index);
+}
+function cellsOf(row) {
+    const cells = [];
+    let end = Number.NEGATIVE_INFINITY;
+    for (const item of row.items) {
+        const gap = item.x - end;
+        const last = cells[cells.length - 1];
+        const text = item.str.replace(/\s+/g, " ");
+        if (!last || gap > CELL_GAP_EM * row.size) {
+            cells.push({ text: text.trim(), x0: item.x, x1: item.x + item.width });
+        }
+        else {
+            const script = text.startsWith("^") || text.startsWith("_");
+            const spaced = !script && gap > WORD_GAP_EM * row.size && !last.text.endsWith(" ") && !text.startsWith(" ");
+            last.text = (last.text + (spaced ? " " : "") + text).replace(/\s+/g, " ");
+            last.x1 = item.x + item.width;
+        }
+        end = item.x + item.width;
+    }
+    for (const cell of cells)
+        cell.text = cell.text.replace(/\s*(?:\.\s?){4,}\s*/g, " … ").trim();
+    return cells.filter((cell) => cell.text !== "");
+}
+function percentile(values, fraction) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted.length === 0 ? 0 : sorted[Math.min(sorted.length - 1, Math.floor(fraction * sorted.length))];
+}
+const spans = (item, x) => item.x < x - 2 && item.x + item.width > x + 2;
+/**
+ * The x of a gutter that splits two justified text columns, or null. Rows that cross it (title, abstract,
+ * a wide figure or table) stay whole; the caller keeps them. Decided on items, not rows: the two columns'
+ * baselines rarely line up, so a "row" holds one side of the page at a time.
+ */
+export function findGutter(rows) {
+    const items = rows.flatMap((row) => row.items);
+    if (items.length < 40)
+        return null;
+    const left = percentile(items.map((item) => item.x), 0.05);
+    const right = percentile(items.map((item) => item.x + item.width), 0.95);
+    const width = right - left;
+    if (width < 200)
+        return null;
+    const crossing = (x) => items.filter((item) => spans(item, x)).length;
+    let best = left + 0.4 * width;
+    for (let x = best; x <= left + 0.6 * width; x += 2)
+        if (crossing(x) < crossing(best))
+            best = x;
+    const floor = crossing(best);
+    if (floor > 0.04 * items.length)
+        return null;
+    let lo = best;
+    let hi = best;
+    while (crossing(lo - 1) <= floor && lo > left + 0.3 * width)
+        lo -= 1;
+    while (crossing(hi + 1) <= floor && hi < left + 0.7 * width)
+        hi += 1;
+    if (hi - lo < 6)
+        return null;
+    const gutter = (lo + hi) / 2;
+    // Both sides carry text, and the lines of each side run most of the way across their column (justified text).
+    const leftRows = rows.map((row) => row.items.filter((item) => item.x + item.width <= gutter)).filter((side) => side.length > 0);
+    const rightRows = rows.map((row) => row.items.filter((item) => item.x >= gutter)).filter((side) => side.length > 0);
+    if (leftRows.length < 8 || rightRows.length < 8)
+        return null;
+    const leftReach = median(leftRows.map((side) => Math.max(...side.map((item) => item.x + item.width)) - left));
+    const rightReach = median(rightRows.map((side) => Math.max(...side.map((item) => item.x + item.width)) - gutter));
+    if (leftReach < 0.8 * (lo - left) || rightReach < 0.8 * (right - hi))
+        return null;
+    return gutter;
+}
+function crosses(row, gutter) {
+    return row.items.some((item) => spans(item, gutter));
+}
+/** A section of rows read in order: whole rows, or left column then right column. */
+function sections(rows, gutter) {
+    if (gutter === null)
+        return [rows];
+    const out = [];
+    let run = [];
+    const flush = () => {
+        if (run.length === 0)
+            return;
+        const leftItems = run.flatMap((row) => row.items.filter((item) => item.x + item.width / 2 < gutter));
+        const rightItems = run.flatMap((row) => row.items.filter((item) => item.x + item.width / 2 >= gutter));
+        out.push(toRows(leftItems), toRows(rightItems));
+        run = [];
+    };
+    for (const row of rows) {
+        if (crosses(row, gutter)) {
+            flush();
+            out.push([row]);
+        }
+        else {
+            run.push(row);
+        }
+    }
+    flush();
+    return out.filter((section) => section.length > 0);
+}
+/** Column channels of a block of columnar rows: the x ranges where cells of the rows with the most cells sit. */
+function columnsOf(block) {
+    const most = median(block.map((row) => row.cells.length));
+    const spans = block
+        .filter((row) => row.cells.length >= Math.max(2, most))
+        .flatMap((row) => row.cells.map((cell) => [cell.x0, cell.x1]))
+        .sort((a, b) => a[0] - b[0]);
+    const pad = 0.3 * median(block.map((row) => row.size));
+    const columns = [];
+    for (const [x0, x1] of spans) {
+        const last = columns[columns.length - 1];
+        if (last && x0 <= last[1] + pad)
+            last[1] = Math.max(last[1], x1);
+        else
+            columns.push([x0, x1]);
+    }
+    return columns;
+}
+function columnIndex(columns, cell) {
+    const center = (cell.x0 + cell.x1) / 2;
+    let best = 0;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    columns.forEach(([x0, x1], index) => {
+        const distance = center >= x0 && center <= x1 ? 0 : Math.min(Math.abs(center - x0), Math.abs(center - x1));
+        if (distance < bestDistance) {
+            best = index;
+            bestDistance = distance;
+        }
+    });
+    return best;
+}
+function markdownTable(block, columns) {
+    const lines = block.map((row) => {
+        const cells = Array.from({ length: columns.length }, () => "");
+        for (const cell of row.cells) {
+            const at = columnIndex(columns, cell);
+            cells[at] = cells[at] ? `${cells[at]} ${cell.text}` : cell.text;
+        }
+        return `| ${cells.map((text) => text.replace(/\|/g, "\\|")).join(" | ")} |`;
+    });
+    lines.splice(1, 0, `| ${columns.map(() => "---").join(" | ")} |`);
+    return lines.join("\n");
+}
+const plainLine = (row) => row.cells.map((cell) => cell.text).join(row.cells.length > 1 ? "  " : " ");
+/**
+ * A short one-cell row under a columnar row, with another columnar row after it, is the wrapped second line
+ * of one of that row's cells (a table header that wrapped): it joins that cell.
+ */
+function foldContinuations(rows) {
+    const out = [];
+    for (let at = 0; at < rows.length; at += 1) {
+        const row = rows[at];
+        const above = out[out.length - 1];
+        const below = rows[at + 1];
+        if (above && above.cells.length >= 2 && below && below.cells.length >= 2 && row.cells.length === 1 && row.cells[0].text.length <= 24 && above.y - row.y <= TABLE_ROW_EM * row.size) {
+            const cell = row.cells[0];
+            const center = (cell.x0 + cell.x1) / 2;
+            const target = above.cells.find((candidate) => center >= candidate.x0 - 2 && center <= candidate.x1 + 2);
+            if (target) {
+                target.text = `${target.text} ${cell.text}`;
+                target.x0 = Math.min(target.x0, cell.x0);
+                target.x1 = Math.max(target.x1, cell.x1);
+                continue;
+            }
+        }
+        out.push(row);
+    }
+    return out;
+}
+function renderSection(input) {
+    const rows = foldContinuations(input);
+    const out = [];
+    let previous;
+    let at = 0;
+    while (at < rows.length) {
+        const row = rows[at];
+        if (previous && previous.y - row.y > BREAK_EM * Math.max(previous.size, row.size))
+            out.push("");
+        if (row.cells.length >= 2) {
+            // A block: consecutive columnar rows with no paragraph-sized jump between them.
+            let end = at + 1;
+            while (end < rows.length && rows[end].cells.length >= 2 && rows[end - 1].y - rows[end].y <= TABLE_ROW_EM * rows[end].size)
+                end += 1;
+            const block = rows.slice(at, end);
+            const columns = block.length >= 2 ? columnsOf(block) : [];
+            const fullRows = block.filter((member) => member.cells.length === columns.length).length;
+            if (columns.length >= 2 && fullRows >= 2) {
+                out.push(markdownTable(block, columns));
+            }
+            else {
+                for (const member of block)
+                    out.push(plainLine(member));
+            }
+            previous = block[block.length - 1];
+            at = end;
+            continue;
+        }
+        if (row.cells.length === 1)
+            out.push(plainLine(row));
+        previous = row;
+        at += 1;
+    }
+    return out;
+}
+/** One page's items as text. Empty string when the page has no text. */
+export function layoutPage(items) {
+    const rows = toRows(items);
+    if (rows.length === 0)
+        return "";
+    const gutter = findGutter(rows);
+    const lines = [];
+    for (const section of sections(rows, gutter)) {
+        if (lines.length > 0 && lines[lines.length - 1] !== "")
+            lines.push("");
+        lines.push(...renderSection(section));
+    }
+    return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}