@beltype/cli 0.1.3 → 0.1.5

package/README.md

@@ -1,14 +1,44 @@
 # 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
+beltype serve                             # the same, behind HTTP: see below
 ```
 
+## 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.
+- `SOURCE_DATE_EPOCH=<seconds>` (an environment variable, not a flag): the moment the file says it was made, whole seconds since 1970 as the reproducible-builds convention has it. Set, the file's `/CreationDate` and `/ModDate` are that instant and the same document printed twice gives the same bytes; unset, they are the wall clock.
+
 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.
 
+## beltype serve
+
+`beltype serve` is `beltype print` behind an HTTP door, in Gotenberg's shape: one Chromium kept warm, and forme kept warm in a shared worker that every document's page hands its display list to, so a print skips the browser's launch and forme's cold first write. A print is still `beltype print`'s: Cicero cuts and Caster prints in the document's own page, answered from the files it was posted with.
+
+```bash
+beltype serve --port 3000
+curl -F index.html=@index.html -F paper.css=@paper.css -F fonts/a.woff2=@fonts/a.woff2 -F caster.writer=forme http://127.0.0.1:3000/print -o out.pdf
+```
+
+- `POST /print`, `multipart/form-data`. `index.html` is required; every other file keeps its form field name as its path relative to the document (`fonts/a.woff2`), plain segments with `/` separators, never absolute and never `..`. A field that is not a file is a flag, `<owner>.<name>` = value (`caster.writer=forme`, `cicero.…`); `beltype.check` is refused. A field `created` (an ISO 8601 instant) fixes the file's dates, else `SOURCE_DATE_EPOCH`, else the clock. The answer is `200 application/pdf` with `X-Beltype-Pages`, `X-Beltype-Words` and `X-Beltype-Warnings` (the count); `422` with `beltype print`'s sentence where the document is refused (a file it asked for and was not given, among them); `400` for a bad request; `413` over the upload limit; `504` over the time limit; `500` otherwise, after which the browser is restarted.
+- `GET /health`: `{ "status": "up", "chromium": …, "prints": …, "queued": … }`, or `503` with `"status": "restarting"` while the browser starts again.
+- `--host 127.0.0.1`, `--port 3000`, `--max-upload 50` (MB), `--timeout 60` (seconds per print), `--restart-after 100` (prints before the browser is restarted).
+- One print runs at a time; the others wait their turn. After every start the server prints a built-in document twice under forme (the log shows both writes), so the first request is warm.
+- It binds `127.0.0.1` unless `--host` says otherwise, and fetches nothing from a network: a document that asks for anything it was not posted is refused by name, as in `beltype print`. The built-in warm-up document ships one font, Source Sans 3 (SIL OFL), in `assets/warmup/`.
+
 ## The sample
 
 `paper`, from [`@beltype/specimens`](https://codeberg.org/BelType/specimens), is a short scientific article on A4 (its data are invented). It exercises what a paged document needs:
@@ -46,6 +76,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/assets/warmup/OFL-SourceSans3.txt

@@ -0,0 +1,93 @@
+Copyright 2010-2020 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe in the United States and/or other countries.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

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,63 @@
+/**
+ * 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')}`;
+}
+/** The instant `SOURCE_DATE_EPOCH` names (whole seconds since 1970, the reproducible-builds convention), as an ISO 8601 string; undefined where the variable is not set. @throws {ValidationError} where it is not whole seconds. */
+export function createdFromEnv(env = process.env) {
+    const epoch = env['SOURCE_DATE_EPOCH'];
+    if (epoch === undefined || epoch === '')
+        return undefined;
+    if (!/^\d{1,15}$/.test(epoch))
+        throw new ValidationError(`beltype: SOURCE_DATE_EPOCH is whole seconds since 1970; got "${epoch}".`);
+    return new Date(Number(epoch) * 1000).toISOString();
+}

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,52 @@ 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 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.
+ */
+export async function printInPage(run) {
     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 formePort = run.sharedWriter ? new SharedWorker(caster.formeSharedWorkerUrl(), { type: 'module', name: 'forme' }).port : undefined;
+        const printed = await caster.print({ document, ...(run.created !== undefined ? { created: run.created } : {}), ...(formePort ? { formePort } : {}) }, run.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,82 @@
+/**
+ * The `beltype` command.
+ *
+ * @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.
+ *
+ * @packageDocumentation
+ */
+import { parseArgs } from 'node:util';
+import { BelTypeError, ValidationError } from '@beltype/common/errors';
+import { checkLines } 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>]...';
+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' }
+        } });
+    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}".`);
+        return Number(raw);
+    };
+    const server = await serve({
+        host: values.host,
+        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)
+    });
+    const stop = () => { void server.close().then(() => process.exit(0)); };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+}
+async function main(argv) {
+    if (argv[0] === 'serve') {
+        await serveVerb(argv.slice(1));
+        return -1;
+    }
+    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 created = createdFromEnv();
+    const result = await print(input, output, { given, ...(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)
+        for (const line of checkLines(result.check))
+            console.log(line);
+    return 0;
+}
+main(process.argv.slice(2)).then((code) => { if (code >= 0)
+    process.exit(code); }, (error) => {
+    console.error(error instanceof BelTypeError ? error.message : error);
+    process.exit(1);
+});