@beltype/cli 0.1.3 → 0.1.4

package/README.md

@@ -1,12 +1,25 @@
 # beltype
 
-The BelType command line. It prints a finished HTML document to PDF: Cicero cuts the document into pages in the browser, and Caster prints the pages Cicero presented. Chromium's own print is never called, so the run needs only Playwright's bare headless shell.
+The BelType command line. It prints a finished HTML document to PDF: Cicero cuts the document into pages in the browser, and Caster prints the pages Cicero presented. There are two printers: Caster, the default, and Chromium's own print (`--printer chromium`), which prints the same pages Cicero presented. Under Caster the run needs only Playwright's bare headless shell.
 
 ```bash
 beltype print paper/index.html            # writes paper/index.pdf
 beltype print paper/index.html -o paper.pdf
+beltype print paper/index.html --printer chromium --check --trace trace.json
 ```
 
+## Flags
+
+One shape across BelType: every package declares a table of name, accepted values and default (`@beltype/common/flags`), and `--flag <owner>.<name>=<value>`, repeatable, sets a row of any of them. `beltype print --help` lists the tables. A value outside a row, or a name no table holds, is refused by name. The defaults reproduce the previous behaviour exactly.
+
+```bash
+beltype print paper/index.html --flag caster.shaper=fontkit --flag cicero.composed=true
+```
+
+- `--printer caster|chromium`: who prints the pages Cicero presented. Chromium prints them one sheet to a page; it refuses, naming `--printer caster`, when the pages are not all one size.
+- `--trace <file.json>`: where the run's time went. `process` is node's clock around each step (launch, context, load, cut, print, transfer, close, write), `cicero` is Cicero's own `performance.measure` entries, `caster` is Caster's report (`ms` per stage and `timing`; `null` under Chromium), with the versions and the resolved flags. It is written even when the run refuses, with the step that refused.
+- `--check`: the proof that the PDF is the screen. Each presented page is screenshotted at 96 dpi, the PDF is rasterised at 96 dpi and the pairs are diffed into `<name>.check/` (`screen-N.png`, `print-N.png`, `diff-N.png`, `check.json`). It reports a share of differing pixels per page and a mean, and never fails the run. It tolerates one pixel of slip, because the screen's pages sit at fractional heights (A4 is 1122.52 px) and Skia and mupdf shade letter edges differently.
+
 The document is plain HTML, CSS and the files beside it. The run answers every request from the document's folder, on a made-up `.invalid` address, and refuses anything else by name: a document that asks for a file it does not have, or for anything on a network, prints nothing. Fonts must be declared with `@font-face` and their files, because Caster embeds every face it draws.
 
 ## The sample
@@ -46,6 +59,6 @@ The companions come from the organization's repositories as git dependencies, ea
 ```bash
 pnpm install
 pnpm run check    # tsc over src and test, strict
-pnpm test         # prints the specimen and reads the file back with mupdf
+pnpm test         # prints the specimen under each printer, and reads the files back with mupdf
 pnpm run build    # dist/, which the beltype command runs
 ```

package/dist/src/check.js

@@ -0,0 +1,60 @@
+/**
+ * `--check`: the proof that the PDF is the screen.
+ *
+ * @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.
+ *
+ * @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. */
+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' }));
+    return shots;
+}
+/** The PNG's pixels as RGB, three bytes a pixel. */
+async function rasterOfPng(png) {
+    const mupdf = await import('mupdf');
+    const pix = new mupdf.Image(png).toPixmap();
+    const width = pix.getWidth();
+    const height = pix.getHeight();
+    const n = pix.getNumberOfComponents();
+    const stride = pix.getStride();
+    const src = pix.getPixels();
+    const rgb = new Uint8Array(width * height * 3);
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++)
+            for (let c = 0; c < 3; c++)
+                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');
+    const printed = rasterize(pdf);
+    const screen = await Promise.all(screens.map(rasterOfPng));
+    const diff = diffPages(screen, printed.pages);
+    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, `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 result = { dir, printer, threshold: THRESHOLD, screenPages: screens.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})`}`),
+        `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}`
+    ];
+}

package/dist/src/chromium.js

@@ -0,0 +1,22 @@
+/**
+ * The print sheet `--printer chromium` adds after Cicero's cut.
+ *
+ * @remarks
+ * Chromium prints the pages Cicero presented, one sheet to a page. The sheet sets the page box to the presented pages' one size, breaks after each page, and turns off the screen surround's gap and shadow (`@media screen` in Cicero's root; `page.pdf()` prints under print media, so they are off anyway and the sheet says so).
+ *
+ * @packageDocumentation
+ */
+import { BuildError } from '@beltype/common/errors';
+/** @throws {BuildError} when the presented pages are not all one size: named pages of different sizes need per-size `@page` rules, a later round. */
+export function chromiumSheet(sizes) {
+    const first = sizes[0];
+    if (!first)
+        throw new BuildError('beltype print: --printer chromium found no page Cicero presented.');
+    if (sizes.some((s) => Math.abs(s.w - first.w) > 0.01 || Math.abs(s.h - first.h) > 0.01)) {
+        throw new BuildError('beltype print: the presented pages are not all one size, which --printer chromium does not print yet; use --printer caster.');
+    }
+    return {
+        page: `@page { size: ${first.w}px ${first.h}px; margin: 0 }`,
+        shadow: 'beltype-page { break-after: page; margin: 0; box-shadow: none }'
+    };
+}

package/dist/src/cli.js

@@ -1,33 +1,12 @@
 #!/usr/bin/env node
 /**
- * The `beltype` command.
+ * The `beltype` executable: turns on Node's compile cache, then runs `main.ts`.
  *
  * @remarks
- * One verb so far: `beltype print <file.html> [-o <file.pdf>]`. The output defaults to the input's name with `.pdf`, beside it. A flag the parser does not know is refused, never ignored.
+ * The cache has to be on before the modules it covers are loaded, and a static import is loaded before the importing file's own statements run, so the command itself lives in `main.ts` and is imported here once the cache is enabled. The cache is Node's own, in the operating system's temporary directory (`node-compile-cache`), and holds compiled code only: a few megabytes, rebuilt if it is deleted.
  *
  * @packageDocumentation
  */
-import { parseArgs } from 'node:util';
-import { BelTypeError } from '@beltype/common/errors';
-import { print } from './print.js';
-const USAGE = 'usage: beltype print <file.html> [-o <file.pdf>]';
-async function main(argv) {
-    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { output: { type: 'string', short: 'o' }, help: { type: 'boolean', short: 'h' } } });
-    const [verb, input, ...rest] = positionals;
-    if (values.help || !verb) {
-        console.log(USAGE);
-        return values.help ? 0 : 1;
-    }
-    if (verb !== 'print' || !input || rest.length) {
-        console.error(verb !== 'print' ? `beltype: no verb '${verb}'\n${USAGE}` : USAGE);
-        return 1;
-    }
-    const output = values.output ?? input.replace(/\.html?$/i, '') + '.pdf';
-    const result = await print(input, output);
-    console.log(`${result.output}: ${result.pages} pages, ${result.words} words, ${(result.ms / 1000).toFixed(1)} s`);
-    return 0;
-}
-main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
-    console.error(error instanceof BelTypeError ? error.message : error);
-    process.exit(1);
-});
+import { enableCompileCache } from 'node:module';
+enableCompileCache();
+await import('./main.js');

package/dist/src/compare.js

@@ -0,0 +1,91 @@
+/**
+ * Rasterize a PDF and measure how far two renderings are apart.
+ *
+ * @remarks
+ * Pages are drawn at 96 dpi, RGB, on white. A pixel differs when its largest channel difference exceeds {@link THRESHOLD} of 255 from every pixel within {@link NEIGHBOURHOOD} of it in the other raster. Pages of different sizes are compared over their common area and flagged. The numbers say how far apart two tools are, never which is right.
+ *
+ * Copied from the testbench's `src/compare.ts`, which keeps its own; one shared home waits until a third user appears.
+ *
+ * @packageDocumentation
+ */
+import * as mupdf from 'mupdf';
+export const THRESHOLD = 32;
+/**
+ * How far a pixel may slip, in pixels, and still count as the same. A pixel differs only when nothing within this reach in the other raster is within {@link THRESHOLD} of it, and the same the other way round.
+ *
+ * @remarks
+ * 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. */
+export function rasterize(pdf, dpi = 96) {
+    const doc = mupdf.Document.openDocument(pdf, 'application/pdf');
+    const pages = [];
+    const pngs = [];
+    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 width = pix.getWidth();
+        const height = pix.getHeight();
+        const n = pix.getNumberOfComponents();
+        const stride = pix.getStride();
+        const src = pix.getPixels();
+        const rgb = new Uint8Array(width * height * 3);
+        for (let y = 0; y < height; y++)
+            for (let x = 0; x < width; x++)
+                for (let c = 0; c < 3; c++)
+                    rgb[(y * width + x) * 3 + c] = src[y * stride + x * n + c];
+        pages.push({ width, height, rgb });
+        pngs.push(pix.asPNG());
+    }
+    return { pages, pngs };
+}
+/** 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) {
+    const a = (y * from.width + x) * 3;
+    const r = from.rgb[a], g = from.rgb[a + 1], bl = from.rgb[a + 2];
+    for (let dy = -NEIGHBOURHOOD; dy <= NEIGHBOURHOOD; dy++) {
+        const yy = y + dy;
+        if (yy < 0 || yy >= height)
+            continue;
+        for (let dx = -NEIGHBOURHOOD; dx <= NEIGHBOURHOOD; dx++) {
+            const xx = x + dx;
+            if (xx < 0 || xx >= width)
+                continue;
+            const b = (yy * to.width + xx) * 3;
+            if (Math.abs(r - to.rgb[b]) <= THRESHOLD && Math.abs(g - to.rgb[b + 1]) <= THRESHOLD && Math.abs(bl - to.rgb[b + 2]) <= THRESHOLD)
+                return true;
+        }
+    }
+    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) {
+    const width = Math.min(ref.width, other.width);
+    const height = Math.min(ref.height, other.height);
+    const out = new Uint8Array(width * height * 3);
+    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;
+            if (!matched(other, ref, x, y, width, height) || !matched(ref, other, x, y, width, height)) {
+                differing++;
+                out[o] = 255;
+                out[o + 1] = 0;
+                out[o + 2] = 0;
+            }
+            else
+                for (let c = 0; c < 3; c++)
+                    out[o + c] = 255 - Math.round((255 - ref.rgb[a + c]) * 0.3);
+        }
+    }
+    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() };
+}
+/** Compare two page lists page by page. */
+export function diffPages(ref, other) {
+    const n = Math.min(ref.length, other.length);
+    const pages = Array.from({ length: n }, (_, i) => diffPage(ref[i], other[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

@@ -0,0 +1,54 @@
+/**
+ * The command line's flags: its own table, and the way `--flag <owner>.<name>=<value>` reaches every package's table.
+ *
+ * @remarks
+ * Each package declares its flags with `defineFlags` from `@beltype/common/flags`; the command line reads the tables and parses a string against the row it names. `--trace <file>` takes a free string, which a {@link FlagSpec} row does not express, so it stays a plain `parseArgs` option beside this table.
+ *
+ * @packageDocumentation
+ */
+import { defineFlags } from '@beltype/common/flags';
+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 }
+});
+/**
+ * The tables of the packages, each loaded the first time a run needs it.
+ *
+ * @remarks
+ * `import('@beltype/caster')` loads every module of Caster, which costs about 40 ms in Node, and a plain print does not read its table: the page resolves Caster's defaults itself. So the table is imported when a `--flag caster.*` names it, for `--help`, and for the trace's `flags` field.
+ */
+const LOADERS = {
+    caster: async () => (await import('@beltype/caster')).casterFlags,
+    cicero: async () => (await import('@beltype/cicero/flags')).ciceroFlags,
+    beltype: async () => cliFlags
+};
+const OWNERS = Object.keys(LOADERS);
+/** The table of one owner. */
+export function tableOf(owner) {
+    return LOADERS[owner]();
+}
+/** Read `owner.name=value` strings (the repeated `--flag`) against the tables, loading only the tables they name. @throws {ValidationError} on a malformed string or an unknown owner; {FlagError} on an unknown name or a bad value. */
+export async function parseFlagArgs(args) {
+    const given = { caster: {}, cicero: {}, beltype: {} };
+    for (const arg of args) {
+        const m = /^([^.=]+)\.([^=]+)=(.*)$/s.exec(arg);
+        if (!m)
+            throw new ValidationError(`beltype: --flag takes <owner>.<name>=<value>; got "${arg}".`);
+        const [, owner, name, raw] = m;
+        if (!Object.hasOwn(LOADERS, owner))
+            throw new ValidationError(`beltype: no flag owner '${owner}'. The owners are ${OWNERS.join(', ')}.`);
+        given[owner][name] = (await tableOf(owner)).parse(name, raw);
+    }
+    return given;
+}
+/** Every table, one row a flag: owner, name, values and default. */
+export async function flagsHelp() {
+    const tables = await Promise.all(OWNERS.map((owner) => tableOf(owner)));
+    const rows = tables.flatMap((t) => Object.entries(t.table).map(([name, spec]) => [`${t.owner}.${name}`, spec.values === null ? 'a positive number' : spec.values.map(String).join(' | '), String(spec.default)]));
+    const width = Math.max(...rows.map((r) => r[0].length));
+    const valuesWidth = Math.max(...rows.map((r) => r[1].length));
+    return `${rows.map(([flag, values, def]) => `  ${flag.padEnd(width)}  ${values.padEnd(valuesWidth)}  default ${def}`).join('\n')}`;
+}

package/dist/src/in-page.js

@@ -6,8 +6,12 @@
  *
  * @packageDocumentation
  */
-/** Caster's `prepare()` makes markers real elements before the cut, then Cicero's client paginates the whole document. */
-export async function cutInPage() {
+/**
+ * Caster's `prepare()` makes markers real elements before the cut, then Cicero's client paginates the whole document.
+ *
+ * @param run - `cicero` is the resolved Cicero flags, handed to `run()`; `measures` asks for Cicero's own timings, read after the cut.
+ */
+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.
@@ -17,27 +21,51 @@ export async function cutInPage() {
         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();
+        const answer = await cicero.run(run.cicero);
         await document.fonts.ready;
-        return { pages: answer.pages };
+        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 };
     }
     catch (error) {
         return { refused: String(error?.message ?? error), at };
     }
 }
-/** Caster prints the presented pages; the bytes cross back as base64, the one form `evaluate` carries intact. */
-export async function printInPage() {
+/**
+ * Caster prints the presented pages; the bytes cross back as base64, the one form `evaluate` carries intact.
+ *
+ * @param options - the resolved Caster flags. `printMs` in the answer is Caster's own time in the page, before the bytes are encoded.
+ */
+export async function printInPage(options) {
     try {
+        const t0 = performance.now();
         // @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');
-        const printed = await caster.print({ document });
+        const printed = await caster.print({ document }, options);
+        const printMs = performance.now() - t0;
         const bytes = printed.bytes;
         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 ?? [] };
+        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 })) } };
     }
     catch (error) {
         return { refused: String(error?.message ?? error), at: 'print' };
     }
 }
+/** The size of each page Cicero presented, in CSS px. Cicero's pages live in the root's shadow tree. */
+export function pageSizesInPage() {
+    const root = document.querySelector('beltype-root');
+    return [...(root?.shadowRoot?.querySelectorAll('beltype-page') ?? [])].map((p) => {
+        const r = p.getBoundingClientRect();
+        return { w: r.width, h: r.height };
+    });
+}
+/** Chromium's print sheet: `@page` is document-level, the page-break rule belongs in the shadow tree the pages live in. */
+export function chromiumSheetInPage(sheet) {
+    const doc = document.createElement('style');
+    doc.textContent = sheet.page;
+    document.head.appendChild(doc);
+    const shadow = document.createElement('style');
+    shadow.textContent = sheet.shadow;
+    document.querySelector('beltype-root')?.shadowRoot?.appendChild(shadow);
+}

package/dist/src/main.js

@@ -0,0 +1,51 @@
+/**
+ * The `beltype` command.
+ *
+ * @remarks
+ * One verb so far: `beltype print <file.html> [-o <file.pdf>]`. 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.
+ *
+ * @packageDocumentation
+ */
+import { parseArgs } from 'node:util';
+import { BelTypeError } from '@beltype/common/errors';
+import { checkLines } from './check.js';
+import { cliFlags, flagsHelp, parseFlagArgs } from './flags.js';
+import { print } from './print.js';
+const USAGE = 'usage: beltype print <file.html> [-o <file.pdf>] [--printer caster|chromium] [--check] [--trace <file.json>] [--flag <owner>.<name>=<value>]...';
+async function main(argv) {
+    const { values, positionals } = parseArgs({ args: argv, 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' }
+        } });
+    const [verb, input, ...rest] = positionals;
+    if (values.help || !verb) {
+        console.log(`${USAGE}\n\nflags:\n${await flagsHelp()}`);
+        return values.help ? 0 : 1;
+    }
+    if (verb !== 'print' || !input || rest.length) {
+        console.error(verb !== 'print' ? `beltype: no verb '${verb}'\n${USAGE}` : USAGE);
+        return 1;
+    }
+    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;
+    const output = values.output ?? input.replace(/\.html?$/i, '') + '.pdf';
+    const result = await print(input, output, { given, ...(values.trace !== undefined ? { trace: values.trace } : {}) });
+    console.log(`${result.output}: ${result.pages} pages, ${result.words} words, ${(result.ms / 1000).toFixed(1)} s`);
+    if (result.check)
+        for (const line of checkLines(result.check))
+            console.log(line);
+    return 0;
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+    console.error(error instanceof BelTypeError ? error.message : error);
+    process.exit(1);
+});

package/dist/src/print.js

@@ -2,7 +2,7 @@
  * `beltype print`: a finished HTML document to a PDF, through Cicero and Caster, in Chromium's headless shell.
  *
  * @remarks
- * **One road.** Cicero paginates and Caster prints the pages Cicero presented. Chromium's own print (`page.pdf()`) is never called, which is why the bare headless shell is enough: where Cicero cuts is layout, the same Blink in the shell as in the full binary.
+ * **Two printers.** Cicero paginates, then Caster prints the pages Cicero presented (the default), or `--printer chromium` has Chromium's `page.pdf()` print them. Under Caster the bare headless shell is enough: where Cicero cuts is layout, the same Blink in the shell as in the full binary.
  *
  * **Every request is answered from disk, on one made-up origin.** The browser context's `route` answers the document at its own name, the document's folder at the root, and `/_beltype/` from the companions' built files. A request for anything else is refused and named, and a run that refused anything writes no file, because the print would not be the document.
  *
@@ -12,62 +12,171 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { chromium } from 'playwright-core';
-import { ciceroEngine } from '@beltype/cicero';
+import { ciceroEngine } from '@beltype/cicero/engine';
+import { ciceroFlags } from '@beltype/cicero/flags';
 import { BuildError } from '@beltype/common/errors';
 import { contentType } from '@beltype/common/mime';
-import { cutInPage, printInPage } from './in-page.js';
+import { cutInPage, printInPage, pageSizesInPage, chromiumSheetInPage } from './in-page.js';
+import { cliFlags, tableOf } from './flags.js';
+import { chromiumSheet } from './chromium.js';
+import { screenshotPages, checkPages } from './check.js';
 /** `.invalid` is reserved (RFC 2606), so nothing on a network can ever answer it instead. */
 const ORIGIN = 'https://print.invalid';
 const VIEWPORT = { width: 1200, height: 1600 };
 /** Deterministic text and timers that run while nobody watches the page. */
 const ARGS = ['--font-render-hinting=none', '--force-device-scale-factor=1', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows'];
+const round = (ms) => Math.round(ms * 10) / 10;
 /**
  * Print `input`, an HTML file, to `output`.
  *
  * @throws {BuildError} naming what the document asked for and could not be given, or the step that refused.
  */
-export async function print(input, output) {
+export async function print(input, output, options = {}) {
     const started = performance.now();
-    const html = fs.readFileSync(input, 'utf8');
-    const root = path.dirname(path.resolve(input));
-    const docPath = `/${encodeURIComponent(path.basename(input))}`;
-    // Each companion's built folder, found from a module it exports: common exports no `package.json`.
-    const distOf = (specifier, up) => path.resolve(path.dirname(fileURLToPath(import.meta.resolve(specifier))), ...Array(up).fill('..'));
-    const cicero = ciceroEngine.vendorAssets();
-    const assets = {
-        files: cicero.files,
-        dirs: { ...cicero.dirs, caster: distOf('@beltype/caster', 1), common: distOf('@beltype/common/errors', 0) },
+    // Caster's own defaults are resolved in the page by `caster.print`, so the given values are all the page is handed; its table is loaded for the trace alone, at the end.
+    const flags = {
+        caster: options.given?.caster ?? {},
+        cicero: ciceroFlags.resolve(options.given?.cicero),
+        beltype: cliFlags.resolve(options.given?.beltype)
     };
-    // Caster's modules import common by its package names, which a page resolves only through an import map.
-    const imports = Object.fromEntries(['errors', 'data-beltype', 'mime'].map((m) => [`@beltype/common/${m}`, `/_beltype/common/${m}.js`]));
-    const served = spliceHead(html, `<script type="importmap">${JSON.stringify({ imports })}</script>\n  ${ciceroEngine.headHtml('/')}`);
-    const missing = new Set();
-    const browser = await chromium.launch({ headless: true, args: ARGS });
+    const trace = { process: {}, cicero: [], caster: null, versions: {}, flags: {} };
+    let mark = started;
+    const lap = (key) => {
+        const now = performance.now();
+        trace.process[key] = round(now - mark);
+        mark = now;
+    };
+    let step = 'launch';
+    let chromiumVersion = 'unknown';
     try {
-        const context = await browser.newContext({ viewport: VIEWPORT, serviceWorkers: 'block' });
-        await answerFromDisk(context, missing, { root, docPath, served, assets });
-        const page = await context.newPage();
-        page.on('pageerror', (error) => console.warn(`page error: ${error.message}`));
-        await page.goto(ORIGIN + docPath, { waitUntil: 'load' });
-        const cut = await page.evaluate(cutInPage);
-        if ('refused' in cut || missing.size)
-            throw refusal(missing, 'refused' in cut ? cut : null);
-        const printed = await page.evaluate(printInPage);
-        if ('refused' in printed)
-            throw refusal(missing, printed);
-        await browser.close();
-        if (missing.size)
-            throw refusal(missing, null);
-        for (const warning of printed.warnings)
-            console.warn(typeof warning === 'string' ? warning : JSON.stringify(warning));
-        fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
-        fs.writeFileSync(output, Buffer.from(printed.base64, 'base64'));
-        return { output, pages: printed.pages, words: printed.words, ms: performance.now() - started };
+        const html = fs.readFileSync(input, 'utf8');
+        const root = path.dirname(path.resolve(input));
+        const docPath = `/${encodeURIComponent(path.basename(input))}`;
+        // Each companion's built folder, found from a module it exports: common exports no `package.json`.
+        const distOf = (specifier, up) => path.resolve(path.dirname(fileURLToPath(import.meta.resolve(specifier))), ...Array(up).fill('..'));
+        const cicero = ciceroEngine.vendorAssets();
+        const assets = {
+            files: cicero.files,
+            dirs: { ...cicero.dirs, caster: distOf('@beltype/caster', 1), common: distOf('@beltype/common/errors', 0) },
+        };
+        // Caster's modules import common by its package names, which a page resolves only through an import map.
+        const imports = Object.fromEntries(['errors', 'data-beltype', 'flags', 'mime'].map((m) => [`@beltype/common/${m}`, `/_beltype/common/${m}.js`]));
+        const served = spliceHead(html, `<script type="importmap">${JSON.stringify({ imports })}</script>\n  ${ciceroEngine.headHtml('/')}`);
+        const missing = new Set();
+        const browser = await chromium.launch({ headless: true, args: ARGS });
+        chromiumVersion = browser.version();
+        lap('launch');
+        try {
+            step = 'context';
+            const context = await browser.newContext({ viewport: VIEWPORT, serviceWorkers: 'block' });
+            await answerFromDisk(context, missing, { root, docPath, served, assets });
+            const page = await context.newPage();
+            page.on('pageerror', (error) => console.warn(`page error: ${error.message}`));
+            lap('context');
+            step = 'load';
+            await page.goto(ORIGIN + docPath, { waitUntil: 'load' });
+            lap('load');
+            step = 'cut';
+            const cut = await page.evaluate(cutInPage, { cicero: flags.cicero, measures: options.trace !== undefined });
+            lap('cut');
+            if (!('refused' in cut))
+                trace.cicero = cut.measures;
+            if ('refused' in cut || missing.size)
+                throw refusal(missing, 'refused' in cut ? cut : null);
+            let screens = [];
+            if (flags.beltype.check) {
+                step = 'check';
+                screens = await screenshotPages(page);
+                lap('check');
+            }
+            step = 'print';
+            let bytes;
+            let pages;
+            let words;
+            if (flags.beltype.printer === 'chromium') {
+                const sheet = chromiumSheet(await page.evaluate(pageSizesInPage));
+                await page.evaluate(chromiumSheetInPage, sheet);
+                bytes = await page.pdf({ preferCSSPageSize: true, printBackground: true });
+                pages = await page.locator('beltype-page').count();
+                words = 0;
+                lap('print');
+            }
+            else {
+                const printed = await page.evaluate(printInPage, flags.caster);
+                if ('refused' in printed)
+                    throw refusal(missing, printed);
+                trace.process['print'] = round(printed.printMs);
+                trace.process['transfer'] = round(performance.now() - mark - printed.printMs);
+                mark = performance.now();
+                trace.caster = printed.caster;
+                for (const warning of printed.warnings)
+                    console.warn(typeof warning === 'string' ? warning : JSON.stringify(warning));
+                bytes = Buffer.from(printed.base64, 'base64');
+                pages = printed.pages;
+                words = printed.words;
+            }
+            step = 'close';
+            await browser.close();
+            lap('close');
+            if (missing.size)
+                throw refusal(missing, null);
+            step = 'write';
+            fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+            fs.writeFileSync(output, bytes);
+            lap('write');
+            let check;
+            if (flags.beltype.check) {
+                step = 'check';
+                check = await checkPages(screens, bytes, path.resolve(output).replace(/\.pdf$/i, '') + '.check', flags.beltype.printer);
+                lap('check');
+            }
+            return { output, pages, words, ms: performance.now() - started, ...(check ? { check } : {}) };
+        }
+        finally {
+            await browser.close();
+        }
+    }
+    catch (error) {
+        trace.refused = { step, message: error instanceof Error ? error.message : String(error) };
+        throw error;
     }
     finally {
-        await browser.close();
+        if (options.trace !== undefined) {
+            trace.process['total'] = round(performance.now() - started);
+            trace.versions = versions(chromiumVersion);
+            // After the total: importing Caster's table here costs about 40 ms in Node, which is not the run's.
+            trace.flags = { ...flags, caster: (await tableOf('caster')).resolve(flags.caster) };
+            fs.mkdirSync(path.dirname(path.resolve(options.trace)), { recursive: true });
+            fs.writeFileSync(options.trace, JSON.stringify(trace, null, 2));
+        }
     }
 }
+/** The version of each package the run used, read from the `package.json` above the module that `specifier` resolves to. */
+function versions(chromiumVersion) {
+    const of = (url, name) => {
+        let dir = path.dirname(fileURLToPath(url));
+        for (;;) {
+            const file = path.join(dir, 'package.json');
+            if (fs.existsSync(file)) {
+                const pkg = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (pkg.name === name)
+                    return pkg.version ?? 'unknown';
+            }
+            const up = path.dirname(dir);
+            if (up === dir)
+                return 'unknown';
+            dir = up;
+        }
+    };
+    return {
+        '@beltype/cli': of(import.meta.url, '@beltype/cli'),
+        '@beltype/cicero': of(import.meta.resolve('@beltype/cicero'), '@beltype/cicero'),
+        '@beltype/caster': of(import.meta.resolve('@beltype/caster'), '@beltype/caster'),
+        '@beltype/common': of(import.meta.resolve('@beltype/common/errors'), '@beltype/common'),
+        'playwright-core': of(import.meta.resolve('playwright-core'), 'playwright-core'),
+        chromium: chromiumVersion
+    };
+}
 /** The run's refusal: what it could not answer comes first, because a missing file's name says more than the step it broke. */
 function refusal(missing, answer) {
     if (missing.size)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beltype/cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "beltype, the command line: a finished HTML document printed to PDF by Cicero and Caster in Chromium's headless shell.",
   "type": "module",
   "license": "MIT",
@@ -32,15 +32,15 @@
     ]
   },
   "dependencies": {
-    "@beltype/caster": "0.1.3",
-    "@beltype/cicero": "0.1.4",
-    "@beltype/common": "0.1.1",
+    "@beltype/caster": "0.1.5",
+    "@beltype/cicero": "0.1.5",
+    "@beltype/common": "0.1.2",
+    "mupdf": "1.28.1",
     "playwright-core": "1.63.0"
   },
   "devDependencies": {
     "@beltype/specimens": "0.1.0",
     "@types/node": "^22.20.5",
-    "mupdf": "1.28.1",
     "typescript": "7.0.2"
   },
   "bugs": {