@beltype/cli 0.1.7 → 0.1.8

package/dist/src/check.js

@@ -1,19 +1,72 @@
 /**
- * `--check`: the proof that the PDF is the screen.
+ * `--check`: the PDF compared with the pages Cicero presented in the same run.
  *
  * @remarks
- * Each page Cicero presented is screenshotted at device scale 1 (96 dpi), the PDF is rasterised at 96 dpi with mupdf, and the pairs are diffed (`compare.ts`). Output goes beside the PDF, in `<name>.check/`: `screen-N.png`, `print-N.png`, `diff-N.png` and `check.json`. It reports and never fails; a threshold waits until the first runs show where the noise floor is. `mupdf` is imported here, dynamically, so a plain print never loads it.
+ * Each page Cicero presented is screenshotted at device scale 1 (96 dpi), the PDF is rasterised at 96 dpi with mupdf, and the pairs are diffed (`compare.ts`). Output goes beside the PDF, in `<name>.check/`: `screen-N.png`, `print-N.png`, `diff-N.png` and `check.json`. It is the proof that the printer drew what the engine cut, not a proof against an outside oracle: the acceptance suite of the cast road is that. Under `--check` a page whose share crosses {@link MAX_SHARE}, a page whose worst tile crosses its kind's floor in {@link TILE_FLOORS}, or a page count that differs between screen and print, fails the run ({@link gate}); `--check=report` writes the same report and never fails. `mupdf` is imported here, dynamically, so a plain print never loads it, and it is an optional peer, so a plain install never has it: it is AGPL-3.0, and this package is MIT.
  *
  * @packageDocumentation
  */
 import fs from 'node:fs';
 import path from 'node:path';
-/** Each `beltype-page` clipped to its page box. Playwright's locators pierce the root's open shadow tree. */
+import { BuildError } from '@beltype/common/errors';
+/**
+ * The share of a page's pixels that may differ before the page fails the check: 3.5 %.
+ *
+ * @remarks
+ * Measured 2026-11-08 on Caster's corpus (`fixtures/lists/`, sixteen documents and 37 pages; `convert-images` and `convert-text` refuse at this CLI's Caster pin), with a bled page aligned on its trim: median 0.73 %, 95th percentile 2.26 %. Text pages sit at 0.3 to 1.8 %, the highest cast-divided-row's page 4 at 1.76 %: Skia and mupdf shade glyph edges past the one pixel of slip `compare.ts` allows. The highest page short of a real disagreement is vector-roads' page 2 at 2.88 %, its box opacity and blend over a backdrop drawn in other colours. The threshold is about twice the highest text page. What it catches: the paper's page 2 drawn blank reads 4.98 %, so a lost page or a page whose content moved crosses it; roads' page 2 reads 13.01 %, its blurred shadow drawn as a raster and its text under `blackText: 100k`. What it does not catch: the 120 by 30 CSS px red block in a table that Caster's acceptance suite fails (*on the cast road the oracle is the page Cicero presented*, Caster's DESIGN.md S91) reads 0.40 % of an A4 page, under the noise of a text page; the tile floors ({@link TILE_FLOORS}) hold it.
+ */
+export const MAX_SHARE = 0.035;
+/** The side of a tile in pixels: the 24 px square Caster's acceptance suite reads (*on the cast road the oracle is the page Cicero presented*, Caster's DESIGN.md S91). */
+export const TILE = 24;
+/**
+ * The share of one tile's pixels that may differ before its page fails, by what the page holds: 40 % for each kind.
+ *
+ * @remarks
+ * Measured 2026-11-08 on the same 37 pages as {@link MAX_SHARE}, the worst tile of each. Text pages (18): median 7.1 %, highest 19.62 % (cast-divided-row's page 4, the glyph edges of a table's cells). Picture pages (19): median 12.5 %, highest clean 17.71 % (facsimile-pages' page 2, glyph edges again). Five picture pages read higher, and each is a real disagreement the gate is for, so none sets a floor: roads' page 1 at 43.6 % (its text under `blackText: 100k`, drawn in another black), images' page 1 at 58.3 % (a band of the CMYK JPEG), arithmetic's page 1 at 63.9 % (a JPEG the browser cannot decode and the file carries), roads' page 2 and vector-roads' page 2 at 100 % (a blurred shadow drawn as a raster; box opacity and a blend over a backdrop). The floor is about twice the clean maximum of either kind. S91's 120 by 30 px block fills a tile it lands squarely on, and wherever it falls its 30 rows cover at least 15 of some tile's 24, 62.5 %, half again the floor. The two kinds measured alike once the disagreements were set aside, so the floors are equal; they stay two so that a kind that measures noisier can move alone.
+ */
+export const TILE_FLOORS = { text: 0.4, picture: 0.4 };
+/**
+ * Refuse `--check` before the run spends anything, when mupdf is not installed.
+ *
+ * @throws {BuildError} naming the package, its licence and the command.
+ */
+export async function requireMupdf(load = () => import('mupdf')) {
+    try {
+        await load();
+    }
+    catch (error) {
+        if (error.code !== 'ERR_MODULE_NOT_FOUND')
+            throw error;
+        throw new BuildError('beltype print: --check rasterises with mupdf, which is not installed. It is under the AGPL-3.0, so this package does not bring it: `npm install mupdf@1.28.1` where you run beltype, or print without --check.');
+    }
+}
+/** Whether a presented page holds anything drawn rather than set; runs in the page, so it closes over nothing. Cicero assigns the document's own elements to the page's slots by hand, so a slot is followed to what it holds, and a shadow root into its tree. */
+export function kindInPage(page) {
+    const drawn = new Set(['IMG', 'CANVAS', 'VIDEO', 'SVG', 'IFRAME', 'OBJECT', 'EMBED', 'PICTURE']);
+    const stack = [page];
+    while (stack.length) {
+        const el = stack.pop();
+        if (el !== page) {
+            if (drawn.has(el.tagName.toUpperCase()))
+                return 'picture';
+            const s = getComputedStyle(el);
+            if (s.backgroundImage !== 'none' || s.mixBlendMode !== 'normal' || s.filter !== 'none' || s.boxShadow !== 'none' || Number(s.opacity) < 1)
+                return 'picture';
+        }
+        stack.push(...el.children);
+        if (el.shadowRoot)
+            stack.push(...el.shadowRoot.children);
+        if (el instanceof HTMLSlotElement)
+            stack.push(...el.assignedElements());
+    }
+    return 'text';
+}
+/** Each `beltype-page` clipped to its page box, and what it holds. Playwright's locators pierce the root's open shadow tree. */
 export async function screenshotPages(page) {
     const pages = await page.locator('beltype-page').all();
     const shots = [];
     for (const p of pages)
-        shots.push(await p.screenshot({ type: 'png' }));
+        shots.push({ png: await p.screenshot({ type: 'png' }), kind: await p.evaluate(kindInPage) });
     return shots;
 }
 /** The PNG's pixels as RGB, three bytes a pixel. */
@@ -32,29 +85,90 @@ async function rasterOfPng(png) {
                 rgb[(y * width + x) * 3 + c] = src[y * stride + x * n + c];
     return { width, height, rgb };
 }
-/** Rasterise `pdf`, diff it page by page against `screens`, and write the evidence into `dir`. */
-export async function checkPages(screens, pdf, dir, printer) {
-    const { rasterize, diffPages, THRESHOLD } = await import('./compare.js');
+/**
+ * Rasterise `pdf`, diff it page by page against `shots`, and write the evidence into `dir`.
+ *
+ * @remarks
+ * A printed page larger than its screenshot (a bleed and print marks grow Caster's media round the page) is cropped to the presented page before the diff: its bottom-left corner is the page's user-space origin (`rasterize`), so the window is the screenshot's size with its bottom edge there. `print-N.png` stays the whole printed page.
+ *
+ * A tile over its floor is excused where the printer confessed a region over it: each confessed `rect`, grown by the one pixel of slip the diff allows, covers pixels of the screenshot, and a tile is excused when the share of its pixels outside every cover that still differ, counted against what lies outside (at least a quarter of a tile, as at an edge), is at or under the floor. A tile wholly inside a cover is excused; one straddling a cover's edge is excused only when its outside part, on its own, would pass. The tile names the confession that covers most of it. The share is never excused: a confessed region cannot stand for a lost page.
+ */
+export async function checkPages(shots, pdf, dir, printer, confessions = []) {
+    const { rasterize, diffPages, crop, THRESHOLD } = await import('./compare.js');
     const printed = rasterize(pdf);
-    const screen = await Promise.all(screens.map(rasterOfPng));
-    const diff = diffPages(screen, printed.pages);
+    const screen = await Promise.all(shots.map((s) => rasterOfPng(s.png)));
+    const trims = printed.pages.map((p, i) => {
+        const s = screen[i];
+        // a page at a fractional height prints one pixel taller than its screenshot, which the slip covers; only a page grown past that is cropped
+        if (!s || (p.width <= s.width + 1 && p.height <= s.height + 1))
+            return undefined;
+        const o = printed.origins[i];
+        return { x: Math.round(o.x), y: Math.round(o.y) - s.height };
+    });
+    const aligned = printed.pages.map((p, i) => (trims[i] ? crop(p, trims[i].x, trims[i].y, screen[i].width, screen[i].height) : p));
+    const grown = (c, r) => ({ c, x0: Math.max(0, Math.floor(c.rect.x) - 1), y0: Math.max(0, Math.floor(c.rect.y) - 1), x1: Math.min(r.width, Math.ceil(c.rect.x + c.rect.width) + 1), y1: Math.min(r.height, Math.ceil(c.rect.y + c.rect.height) + 1) });
+    const regions = screen.map((r, i) => confessions.filter((c) => c.page === i + 1).map((c) => grown(c, r)));
+    const covers = screen.map((r, i) => {
+        if (!regions[i].length)
+            return undefined;
+        const cover = new Uint8Array(r.width * r.height);
+        for (const g of regions[i])
+            for (let y = g.y0; y < g.y1; y++)
+                cover.fill(1, y * r.width + g.x0, y * r.width + Math.max(g.x0, g.x1));
+        return cover;
+    });
+    const diff = diffPages(screen, aligned, TILE, covers);
     fs.rmSync(dir, { recursive: true, force: true });
     fs.mkdirSync(dir, { recursive: true });
     const pages = diff.pages.map((d, i) => {
         const n = i + 1;
-        fs.writeFileSync(path.join(dir, `screen-${n}.png`), screens[i]);
+        fs.writeFileSync(path.join(dir, `screen-${n}.png`), shots[i].png);
         fs.writeFileSync(path.join(dir, `print-${n}.png`), printed.pngs[i]);
         fs.writeFileSync(path.join(dir, `diff-${n}.png`), d.image);
-        return { page: n, share: d.share, sameSize: d.sameSize, screen: { width: screen[i].width, height: screen[i].height }, print: { width: printed.pages[i].width, height: printed.pages[i].height } };
+        const kind = shots[i].kind;
+        const floor = TILE_FLOORS[kind];
+        const trimAt = trims[i];
+        const excused = [];
+        let tile = { share: 0, x: 0, y: 0 };
+        for (const t of d.tiles) {
+            const overlap = (g) => Math.max(0, Math.min(g.x1, t.x + TILE) - Math.max(g.x0, t.x)) * Math.max(0, Math.min(g.y1, t.y + TILE) - Math.max(g.y0, t.y));
+            const by = regions[i].reduce((best, g) => { const area = overlap(g); return area > (best?.area ?? 0) ? { c: g.c, area } : best; }, null);
+            if (t.share > floor && by && t.outside <= floor)
+                excused.push({ x: t.x, y: t.y, share: t.share, kind: by.c.kind, element: by.c.element });
+            else if (t.share > tile.share)
+                tile = { share: t.share, x: t.x, y: t.y };
+        }
+        return { page: n, share: d.share, tile, excused, kind, pass: d.share <= MAX_SHARE && tile.share <= floor, sameSize: d.sameSize, screen: { width: screen[i].width, height: screen[i].height }, print: { width: printed.pages[i].width, height: printed.pages[i].height }, ...(trimAt ? { trimAt } : {}) };
     });
-    const result = { dir, printer, threshold: THRESHOLD, screenPages: screens.length, printPages: printed.pages.length, unmatched: diff.unmatched, mean: diff.mean, pages };
+    const result = { dir, printer, threshold: THRESHOLD, maxShare: MAX_SHARE, confessions: [...confessions], screenPages: shots.length, printPages: printed.pages.length, unmatched: diff.unmatched, mean: diff.mean, pages };
     fs.writeFileSync(path.join(dir, 'check.json'), JSON.stringify(result, null, 2));
     return result;
 }
 /** One line a page, and the mean. */
 export function checkLines(r) {
     return [
-        ...r.pages.map((p) => `check page ${p.page}: ${(p.share * 100).toFixed(2)}% differ${p.sameSize ? '' : ` (sizes differ: screen ${p.screen.width}x${p.screen.height}, print ${p.print.width}x${p.print.height})`}`),
+        ...r.pages.map((p) => {
+            const worst = p.excused.reduce((w, t) => (t.share > (w?.share ?? 0) ? t : w), null);
+            const tile = worst && worst.share > p.tile.share ? `worst tile ${(worst.share * 100).toFixed(0)}% at (${worst.x}, ${worst.y}) excused by ${worst.kind} on ${worst.element}` : `worst tile ${(p.tile.share * 100).toFixed(1)}% at (${p.tile.x}, ${p.tile.y})`;
+            return `check page ${p.page}: ${(p.share * 100).toFixed(2)}% differ, ${tile}; a ${p.kind} page${p.sameSize ? '' : ` (sizes differ: screen ${p.screen.width}x${p.screen.height}, print ${p.print.width}x${p.print.height})`}`;
+        }),
         `check mean: ${(r.mean * 100).toFixed(2)}% over ${r.pages.length} pages${r.unmatched ? `; ${r.unmatched} page(s) unmatched (screen ${r.screenPages}, print ${r.printPages})` : ''}; ${r.dir}`
     ];
 }
+/**
+ * Fail the run on what the report found, under `--check`; under `--check=report`, nothing.
+ *
+ * @throws {BuildError} one line a failing page, naming its share where that is over {@link MAX_SHARE}, else its worst tile and the floor of its kind, and its diff picture; and one where the page counts differ.
+ */
+export function gate(r, mode) {
+    if (mode === 'report')
+        return;
+    const lines = r.pages.filter((p) => !p.pass).map((p) => {
+        const why = p.share > r.maxShare ? `${(p.share * 100).toFixed(2)}% differ, over ${(r.maxShare * 100).toFixed(1)}%${p.sameSize ? '' : ' (sizes differ)'}` : `tile at (${p.tile.x}, ${p.tile.y}) differs ${(p.tile.share * 100).toFixed(0)}%, over the ${(TILE_FLOORS[p.kind] * 100).toFixed(0)}% floor for a ${p.kind} page`;
+        return `check page ${p.page} fails: ${why}; ${path.join(r.dir, `diff-${p.page}.png`)}`;
+    });
+    if (r.screenPages !== r.printPages)
+        lines.push(`check fails: the screen has ${r.screenPages} pages and the print ${r.printPages}; ${r.dir}`);
+    if (lines.length)
+        throw new BuildError(lines.join('\n'));
+}

package/dist/src/compare.js

@@ -17,13 +17,22 @@ export const THRESHOLD = 32;
  * The screen's pages sit at fractional heights on Cicero's stack (A4 is 1122.52 px), so the screenshot slips 0 to 1 px against mupdf's exact origin; and Skia and mupdf shade letter edges differently. Without the reach every glyph edge below the slip reads as a difference. This is the reftests' `fuzzy` idea (Web Platform Tests, Mozilla).
  */
 export const NEIGHBOURHOOD = 1;
-/** Draw every page of a PDF. */
+/**
+ * Draw every page of a PDF; `origins` is where each page's user-space origin falls in its picture, in pixels.
+ *
+ * @remarks
+ * The presented page sits on the origin, its bottom-left corner there: Chromium's media is `[0 0 w h]`, and Caster grows its media round the page for a bleed and print marks (`[-31.181 -31.181 371.338 371.338]` on Caster's `roads`) and writes no `/TrimBox`, so the origin is where the trim is found.
+ */
 export function rasterize(pdf, dpi = 96) {
     const doc = mupdf.Document.openDocument(pdf, 'application/pdf');
     const pages = [];
     const pngs = [];
+    const origins = [];
     for (let i = 0; i < doc.countPages(); i++) {
-        const pix = doc.loadPage(i).toPixmap(mupdf.Matrix.scale(dpi / 72, dpi / 72), mupdf.ColorSpace.DeviceRGB, false);
+        const page = doc.loadPage(i);
+        const t = page.getTransform();
+        origins.push({ x: t[4] * dpi / 72, y: t[5] * dpi / 72 });
+        const pix = page.toPixmap(mupdf.Matrix.scale(dpi / 72, dpi / 72), mupdf.ColorSpace.DeviceRGB, false);
         const width = pix.getWidth();
         const height = pix.getHeight();
         const n = pix.getNumberOfComponents();
@@ -37,7 +46,16 @@ export function rasterize(pdf, dpi = 96) {
         pages.push({ width, height, rgb });
         pngs.push(pix.asPNG());
     }
-    return { pages, pngs };
+    return { pages, pngs, origins };
+}
+/** The `width` by `height` window of `r` whose top-left corner is (x, y), clipped to `r`. */
+export function crop(r, x, y, width, height) {
+    const x0 = Math.max(0, Math.min(x, r.width)), y0 = Math.max(0, Math.min(y, r.height));
+    const w = Math.min(width, r.width - x0), h = Math.min(height, r.height - y0);
+    const rgb = new Uint8Array(w * h * 3);
+    for (let row = 0; row < h; row++)
+        rgb.set(r.rgb.subarray(((y0 + row) * r.width + x0) * 3, ((y0 + row) * r.width + x0 + w) * 3), row * w * 3);
+    return { width: w, height: h, rgb };
 }
 /** Whether the pixel at (x, y) of `from` is within the threshold of any pixel of `to` within {@link NEIGHBOURHOOD} of (x, y), clipped at the edges. */
 function matched(from, to, x, y, width, height) {
@@ -58,18 +76,30 @@ function matched(from, to, x, y, width, height) {
     }
     return false;
 }
-/** Compare two pages over their common area; the picture is that area, the reference faded and the pixels that still differ after the slip red. */
-export function diffPage(ref, other) {
+/** Compare two pages over their common area, read in `tile`-pixel squares; the picture is that area, the reference faded and the pixels that still differ after the slip red. `cover`, one byte a pixel of `ref`, marks the pixels a tile's `outside` leaves out. */
+export function diffPage(ref, other, tile = 24, cover) {
     const width = Math.min(ref.width, other.width);
     const height = Math.min(ref.height, other.height);
     const out = new Uint8Array(width * height * 3);
+    const across = Math.ceil(width / tile);
+    const count = across * Math.ceil(height / tile);
+    const tiles = new Uint32Array(count);
+    const outside = new Uint32Array(count);
+    const covered = new Uint32Array(count);
     let differing = 0;
     for (let y = 0; y < height; y++) {
         for (let x = 0; x < width; x++) {
             const a = (y * ref.width + x) * 3;
             const o = (y * width + x) * 3;
+            const t = Math.floor(y / tile) * across + Math.floor(x / tile);
+            const inCover = cover ? cover[y * ref.width + x] === 1 : false;
+            if (inCover)
+                covered[t]++;
             if (!matched(other, ref, x, y, width, height) || !matched(ref, other, x, y, width, height)) {
                 differing++;
+                tiles[t]++;
+                if (!inCover)
+                    outside[t]++;
                 out[o] = 255;
                 out[o + 1] = 0;
                 out[o + 2] = 0;
@@ -81,11 +111,20 @@ export function diffPage(ref, other) {
     }
     const pix = new mupdf.Pixmap(mupdf.ColorSpace.DeviceRGB, [0, 0, width, height], false);
     pix.getPixels().set(out);
-    return { share: width * height ? differing / (width * height) : 0, sameSize: ref.width === other.width && ref.height === other.height, width, height, image: pix.asPNG() };
+    const least = tile * tile / 4;
+    const diffs = [];
+    tiles.forEach((n, i) => {
+        if (!n)
+            return;
+        const x = (i % across) * tile, y = Math.floor(i / across) * tile;
+        const area = (Math.min(x + tile, width) - x) * (Math.min(y + tile, height) - y);
+        diffs.push({ x, y, share: n / Math.max(area, least), outside: outside[i] / Math.max(area - covered[i], least) });
+    });
+    return { share: width * height ? differing / (width * height) : 0, sameSize: ref.width === other.width && ref.height === other.height, width, height, tiles: diffs, image: pix.asPNG() };
 }
 /** Compare two page lists page by page. */
-export function diffPages(ref, other) {
+export function diffPages(ref, other, tile = 24, covers = []) {
     const n = Math.min(ref.length, other.length);
-    const pages = Array.from({ length: n }, (_, i) => diffPage(ref[i], other[i]));
+    const pages = Array.from({ length: n }, (_, i) => diffPage(ref[i], other[i], tile, covers[i]));
     return { pages, unmatched: Math.abs(ref.length - other.length), mean: n ? pages.reduce((s, p) => s + p.share, 0) / n : 0 };
 }

package/dist/src/flags.js

@@ -11,8 +11,8 @@ import { ValidationError } from '@beltype/common/errors';
 export const cliFlags = defineFlags('beltype', {
     /** Default `'caster'`: Cicero cuts and Caster prints. `'chromium'` has Chromium print the pages Cicero presented, which is what `check` compares Caster against. */
     printer: { values: ['caster', 'chromium'], default: 'caster' },
-    /** Default `false`: no proof. `true` screenshots each presented page, rasterises the PDF and diffs the pairs into `<name>.check/`. */
-    check: { values: [false, true], default: false }
+    /** Default `false`: no check. `true` screenshots each presented page, rasterises the PDF, diffs the pairs into `<name>.check/` and fails the run on a page over the threshold or a page count that differs; `'report'` writes the same report and never fails. */
+    check: { values: [false, true, 'report'], default: false }
 });
 /**
  * The tables of the packages, each loaded the first time a run needs it.

package/dist/src/in-page.js

@@ -7,21 +7,21 @@
  * @packageDocumentation
  */
 /**
- * Caster's `prepare()` makes markers real elements before the cut, then Cicero's client paginates the whole document.
+ * Caster's `prepare()` makes markers real elements before the cut, and its `ready` loads the faces the document's SVG images set text in, which the document itself never asks for (codeberg.org/BelType/caster issue 11); then Cicero's client paginates the whole document. A face that arrived after the cut would make Cicero cut again under the printer.
  *
- * @param run - `cicero` is the resolved Cicero flags, handed to `run()`; `measures` asks for Cicero's own timings, read after the cut.
+ * @param run - `cicero` is the resolved Cicero flags, handed to `run()`; `measures` asks for Cicero's own timings, read after the cut; `resumeAt` is the address of the first box a mail merge replaced, which makes the cut a resumed run.
  */
 export async function cutInPage(run) {
     let at = 'prepare';
     try {
         // @ts-expect-error a URL the page resolves, not a module the checker can find. A literal on purpose: a computed `import()` is wrapped by `rewriteRelativeImportExtensions` in a helper the page does not have.
         const caster = await import('/_beltype/caster/src/index.js');
-        caster.prepare(document);
+        await caster.prepare(document).ready;
         at = 'paginate';
         const cicero = window.__beltypeCicero;
         if (!cicero?.run)
             return { refused: 'the document loaded no Cicero client, so there is nothing to paginate with', at };
-        const answer = await cicero.run(run.cicero);
+        const answer = await cicero.run(run.resumeAt ? { ...run.cicero, resumeAt: run.resumeAt } : run.cicero);
         await document.fonts.ready;
         const measures = run.measures ? performance.getEntriesByType('measure').filter((m) => m.name.startsWith('cicero:')).map((m) => ({ name: m.name, ms: Math.round(m.duration * 100) / 100, detail: m.detail ?? null })) : [];
         return { pages: answer.pages, measures };
@@ -30,10 +30,37 @@ export async function cutInPage(run) {
         return { refused: String(error?.message ?? error), at };
     }
 }
+/**
+ * A mail merge's first customer, on the template just seated (`src/merge-tab.ts`, bundled and imported by URL).
+ *
+ * @param run - `template` is the template as it was uploaded; `data` the customer.
+ */
+export async function seatMergeInPage(run) {
+    try {
+        // @ts-expect-error a URL the page resolves, not a module the checker can find.
+        const merge = await import('/_beltype/merge/merge.js');
+        merge.seat(run.template, run.data);
+        return { done: true };
+    }
+    catch (error) {
+        return { refused: String(error?.message ?? error), at: 'merge' };
+    }
+}
+/** A later customer of a mail merge, on the document already presented: the changed top-level boxes replaced, or why the template must be seated again. */
+export async function keepMergeInPage(data) {
+    try {
+        // @ts-expect-error a URL the page resolves, not a module the checker can find.
+        const merge = await import('/_beltype/merge/merge.js');
+        return merge.keep(data);
+    }
+    catch (error) {
+        return { refused: String(error?.message ?? error), at: 'merge' };
+    }
+}
 /**
  * Caster prints the presented pages; the bytes cross back as base64, the one form `evaluate` carries intact.
  *
- * @param run - `options` is the resolved Caster flags; `created` is the instant the file says it was made, absent for the wall clock; `sharedWriter` has forme write through a `SharedWorker` the page opens (Caster's `formeSharedWorkerUrl()`), so a host that keeps the page's browser alive keeps the writer warm. `printMs` in the answer is Caster's own time in the page, before the bytes are encoded.
+ * @param run - `options` is the resolved Caster flags; `created` is the instant the file says it was made, absent for the wall clock; `sharedWriter` has forme write through a `SharedWorker` the page opens (Caster's `formeSharedWorkerUrl()`), so a host that keeps the page's browser alive keeps the writer warm. `printMs` in the answer is Caster's own time in the page, before the bytes are encoded; `confessions` is the report's, empty from a Caster that keeps none.
  */
 export async function printInPage(run) {
     try {
@@ -47,7 +74,7 @@ export async function printInPage(run) {
         let binary = '';
         for (let i = 0; i < bytes.length; i += 0x8000)
             binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
-        return { base64: btoa(binary), pages: printed.report.timing?.pages ?? 0, words: printed.report.timing?.words ?? 0, warnings: printed.report.warnings ?? [], printMs, caster: { ms: printed.report.ms ?? {}, timing: printed.report.timing ?? null, fonts: (printed.report.emission?.faces ?? []).map((f) => ({ id: f.id, ms: f.ms ?? null })) } };
+        return { base64: btoa(binary), pages: printed.report.timing?.pages ?? 0, words: printed.report.timing?.words ?? 0, warnings: printed.report.warnings ?? [], deferred: printed.report.deferred ?? [], conformance: printed.report.conformance, printMs, confessions: printed.report.confessions ?? [], caster: { ms: printed.report.ms ?? {}, timing: printed.report.timing ?? null, fonts: (printed.report.emission?.faces ?? []).map((f) => ({ id: f.id, ms: f.ms ?? null })) } };
     }
     catch (error) {
         return { refused: String(error?.message ?? error), at: 'print' };

package/dist/src/main.js

@@ -4,25 +4,31 @@
  * @remarks
  * Two verbs: `beltype print <file.html> [-o <file.pdf>]` and `beltype serve` (see `serve.ts`). The output defaults to the input's name with `.pdf`, beside it. A flag the parser does not know is refused, never ignored.
  *
- * Flags have one shape across BelType: `--flag <owner>.<name>=<value>`, repeatable, names a row of a package's table (`beltype print --help` lists them all). `--printer` and `--check` are the command line's own rows spelled plainly; `--trace <file>` takes a free string, so it is a plain option beside the table.
+ * Flags have one shape across BelType: `--flag <owner>.<name>=<value>`, repeatable, names a row of a package's table (`beltype print --help` lists them all). `--printer` and `--check` are the command line's own rows spelled plainly, and a bare `--check` is `--check=true`; `--trace <file>` takes a free string, so it is a plain option beside the table, and so is `--no-sandbox`, which belongs to the launch and to no package's table.
  *
  * @packageDocumentation
  */
 import { parseArgs } from 'node:util';
 import { BelTypeError, ValidationError } from '@beltype/common/errors';
-import { checkLines } from './check.js';
+import { checkLines, gate } from './check.js';
 import { cliFlags, createdFromEnv, flagsHelp, parseFlagArgs } from './flags.js';
 import { print } from './print.js';
 import { serve } from './serve.js';
-const USAGE = 'usage: beltype serve [--host 127.0.0.1] [--port 3000] [--max-upload 50] [--timeout 60] [--restart-after 100]\n       beltype print <file.html> [-o <file.pdf>] [--printer caster|chromium] [--check] [--trace <file.json>] [--flag <owner>.<name>=<value>]...';
+const USAGE = 'usage: beltype serve [--host 127.0.0.1] [--port 3000] [--max-upload 50] [--timeout 60] [--restart-after 100] [--allowed-hosts <name[:port],…>] [--no-sandbox]\n       beltype print <file.html> [-o <file.pdf>] [--printer caster|chromium] [--check[=report]] [--trace <file.json>] [--no-sandbox] [--flag <owner>.<name>=<value>]...';
 async function serveVerb(argv) {
     const { values } = parseArgs({ args: argv, options: {
             host: { type: 'string', default: '127.0.0.1' },
             port: { type: 'string', default: '3000' },
             'max-upload': { type: 'string', default: '50' },
             timeout: { type: 'string', default: '60' },
-            'restart-after': { type: 'string', default: '100' }
+            'restart-after': { type: 'string', default: '100' },
+            'allowed-hosts': { type: 'string' },
+            'no-sandbox': { type: 'boolean' }
         } });
+    const allowedHosts = (values['allowed-hosts'] ?? '').split(',').map((h) => h.trim()).filter(Boolean);
+    for (const h of allowedHosts)
+        if (!/^([a-z0-9.-]+|\[[0-9a-f:.]+\])(:\d+)?$/i.test(h))
+            throw new ValidationError(`beltype serve: --allowed-hosts takes names as a request's Host header spells them, name or name:port, comma-separated; got "${h}".`);
     const number = (name, raw, min) => {
         if (!/^\d+$/.test(raw) || Number(raw) < min)
             throw new ValidationError(`beltype serve: --${name} is a whole number of at least ${min}; got "${raw}".`);
@@ -33,7 +39,9 @@ async function serveVerb(argv) {
         port: number('port', values.port, 0),
         maxUpload: number('max-upload', values['max-upload'], 1) * 1024 * 1024,
         timeout: number('timeout', values.timeout, 1) * 1000,
-        restartAfter: number('restart-after', values['restart-after'], 1)
+        restartAfter: number('restart-after', values['restart-after'], 1),
+        sandbox: !values['no-sandbox'],
+        allowedHosts
     });
     const stop = () => { void server.close().then(() => process.exit(0)); };
     process.on('SIGINT', stop);
@@ -44,13 +52,14 @@ async function main(argv) {
         await serveVerb(argv.slice(1));
         return -1;
     }
-    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
+    const { values, positionals } = parseArgs({ args: argv.map((a) => (a === '--check' ? '--check=true' : a)), allowPositionals: true, options: {
             output: { type: 'string', short: 'o' },
             help: { type: 'boolean', short: 'h' },
             flag: { type: 'string', multiple: true },
             printer: { type: 'string' },
-            check: { type: 'boolean' },
-            trace: { type: 'string' }
+            check: { type: 'string' },
+            trace: { type: 'string' },
+            'no-sandbox': { type: 'boolean' }
         } });
     const [verb, input, ...rest] = positionals;
     if (values.help || !verb) {
@@ -64,15 +73,17 @@ async function main(argv) {
     const given = await parseFlagArgs(values.flag ?? []);
     if (values.printer !== undefined)
         given.beltype['printer'] = cliFlags.parse('printer', values.printer);
-    if (values.check)
-        given.beltype['check'] = true;
+    if (values.check !== undefined)
+        given.beltype['check'] = cliFlags.parse('check', values.check);
     const output = values.output ?? input.replace(/\.html?$/i, '') + '.pdf';
     const created = createdFromEnv();
-    const result = await print(input, output, { given, ...(values.trace !== undefined ? { trace: values.trace } : {}), ...(created ? { created } : {}) });
+    const result = await print(input, output, { given, sandbox: !values['no-sandbox'], ...(values.trace !== undefined ? { trace: values.trace } : {}), ...(created ? { created } : {}) });
     console.log(`${result.output}: ${result.pages} pages, ${result.words} words, ${(result.ms / 1000).toFixed(1)} s`);
-    if (result.check)
+    if (result.check) {
         for (const line of checkLines(result.check))
             console.log(line);
+        gate(result.check, given.beltype['check']);
+    }
     return 0;
 }
 main(process.argv.slice(2)).then((code) => { if (code >= 0)

package/dist/src/merge-tab.js

@@ -0,0 +1,139 @@
+/**
+ * The mail merge inside the tab: a template's data block opened with one customer's values and rows, its fields written, each `<template data-repeat>` filled.
+ *
+ * @remarks
+ * This file is bundled with `prosemirror-stores` into `assets/merge/merge.js` by `scripts/bundle-merge.ts`, and the page imports that bundle by URL; a change here means running the script. `test/merge-bundle.test.ts` holds the two together.
+ *
+ * **Two roads.** {@link seat} merges into the document just written into the page. {@link keep} merges into a detached copy of the template and replaces only the top-level boxes that differ from the last customer's, through Cicero's patch door, so the sheets, the faces and the unchanged boxes stay. Its answer `{ again }` asks the host to seat the template afresh, and names why: a merge that changes the shape of the body, or that Cicero will not promise, is never forced.
+ *
+ * What it does not do: it reads no CSVW. A table's cells arrive typed as `openBlock` takes them, a string or `{ value, text }`.
+ *
+ * @see codeberg.org/BelType/cli issue 2
+ * @packageDocumentation
+ */
+import { openBlock } from 'prosemirror-stores/graph';
+import { writeMicrodata } from 'prosemirror-stores/microdata';
+const BLOCK = 'script[type="application/ld+json"]';
+/** What Caster's preparation stamps on an element, and Cicero's patch door compares on a top-level box. */
+const SOURCE = 'data-pdf-source';
+let template = '';
+let last = { boxes: [], text: '' };
+let unkept = null;
+/** The table names of a block, each with the `csvw:url` its rows are handed to `openBlock` under. */
+function tablesOf(text) {
+    const tables = new Map();
+    const graph = JSON.parse(text)['@graph'] ?? [];
+    for (const node of graph) {
+        for (const [key, value] of Object.entries(node)) {
+            const table = value;
+            if (table?.['@type'] === 'csvw:Table' && typeof table['csvw:url'] === 'string')
+                tables.set(key, table['csvw:url']);
+        }
+    }
+    return tables;
+}
+/** The fields of one repeated row. */
+function writeRow(row, cells) {
+    for (const field of row.querySelectorAll('[itemprop]')) {
+        const cell = cells[field.getAttribute('itemprop')];
+        if (cell === undefined)
+            continue;
+        const shown = typeof cell === 'string' ? cell : cell.text;
+        if (field.localName === 'data')
+            field.setAttribute('value', typeof cell === 'string' ? cell : String(cell.value));
+        if (field.localName !== 'data' || typeof cell !== 'string')
+            field.textContent = shown;
+    }
+}
+/**
+ * Merge `data` into `doc`: the graph opened on the block, the values set on the document's item, the fields written, the templates replaced by their rows, the block gone.
+ *
+ * @throws {Error} Where the document has no block or no item, or `data` names a table the block does not.
+ */
+function merge(doc, data) {
+    const block = doc.querySelector(BLOCK);
+    if (!block)
+        throw new Error('the template has no data block (<script type="application/ld+json">)');
+    const item = doc.querySelector('[itemscope][itemid]:not([itemprop])')?.getAttribute('itemid');
+    if (!item)
+        throw new Error('the template has no top-level item (an element with itemscope and itemid, and no itemprop)');
+    const text = block.textContent;
+    const tables = tablesOf(text);
+    for (const name of Object.keys(data.rows))
+        if (!tables.has(name))
+            throw new Error(`the data names a table "${name}", and the block has ${[...tables.keys()].join(', ') || 'none'}`);
+    const graph = openBlock(text, { rows: new Map([...tables].map(([name, url]) => [url, data.rows[name] ?? []])) });
+    for (const [key, value] of Object.entries(data.values))
+        graph.set(item, key, value);
+    writeMicrodata(doc.documentElement, graph);
+    for (const repeat of [...doc.querySelectorAll('template[data-repeat]')]) {
+        const name = repeat.getAttribute('data-repeat');
+        const rowElement = repeat.content.firstElementChild;
+        if (rowElement) {
+            for (const cells of data.rows[name] ?? []) {
+                const row = rowElement.cloneNode(true);
+                row.setAttribute('itemscope', '');
+                row.setAttribute('itemprop', name);
+                writeRow(row, cells);
+                repeat.before(row);
+            }
+        }
+        repeat.remove();
+    }
+    block.remove();
+}
+const snapshot = (doc) => ({
+    boxes: [...doc.body.children].map((box) => box.outerHTML),
+    text: [...doc.body.childNodes].filter((node) => node.nodeType === 3).map((node) => node.data.trim()).join(''),
+});
+/**
+ * The first customer on a seated document: `html` is the template as it was uploaded, kept for the customers after.
+ *
+ * @throws {Error} From {@link merge}.
+ */
+export function seat(html, data) {
+    template = html;
+    merge(document, data);
+    last = snapshot(document);
+    // The patch door numbers the boxes the engine took, and nothing keeps a field in the head up to date: a document like this is seated for every customer.
+    unkept = document.head.querySelector('[itemprop]') ? 'a field stands in the head' : document.body.querySelector(':scope > :is(script, style, template, link, meta)') ? 'the body holds a child that is no box' : null;
+}
+/**
+ * A later customer on the document already presented.
+ *
+ * @throws {Error} From {@link merge}.
+ */
+export function keep(data) {
+    if (unkept)
+        return { again: unkept };
+    const handle = window.__beltypeCicero;
+    if (!handle?.box || !handle.patch)
+        return { again: 'the page shows no presented run' };
+    const copy = new DOMParser().parseFromString(template, 'text/html');
+    merge(copy, data);
+    const next = snapshot(copy);
+    if (next.boxes.length !== last.boxes.length)
+        return { again: `the top-level boxes went from ${last.boxes.length} to ${next.boxes.length}` };
+    if (next.text !== last.text)
+        return { again: 'text directly in the body changed' };
+    const fresh = [...copy.body.children];
+    let resumeAt = null;
+    let changed = 0;
+    for (const [i, box] of fresh.entries()) {
+        if (next.boxes[i] === last.boxes[i])
+            continue;
+        const old = handle.box(i);
+        if (!old)
+            return { again: `box ${i} is no flow block` };
+        const stamp = old.getAttribute(SOURCE);
+        if (stamp !== null)
+            box.setAttribute(SOURCE, stamp);
+        const address = handle.patch(i, [], document.adoptNode(box));
+        if (address === null)
+            return { again: `Cicero's patch door refused box ${i}` };
+        resumeAt ??= address;
+        changed++;
+    }
+    last = next;
+    return { resumeAt, changed };
+}