@beltype/cicero 0.1.4 → 0.1.5

package/README.md

@@ -9,6 +9,8 @@ Cicero is a paged-media engine for the live browser. It cuts a document into pag
 | Import | What |
 | --- | --- |
 | `@beltype/cicero` | The host face: `ciceroEngine` (BelType's engine seam) and `rewriteDocumentSheets`. |
+| `@beltype/cicero/engine` | `ciceroEngine` alone, without the sheet rewriter and its css-tree: a host that only serves a page (BelType's CLI) loads this. |
+| `@beltype/cicero/flags` | `ciceroFlags` alone, the run-wide flags in common's shape. |
 | `@beltype/cicero/rewrite` | `rewriteDocumentSheets` alone, for a page: the host face also carries `ciceroEngine`, which imports node's `url` and so cannot load in a browser. |
 | `@beltype/cicero/client` | The page side: loading it sets `window.__beltypeCicero`, typed in `seam/handle.d.ts`. |
 | `@beltype/cicero/facsimile` | The embedded PDF page (`<object type="application/pdf">`). |

package/dist/seam/flags.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Cicero's run-wide flags, in `@beltype/common`'s shape.
+ *
+ * @remarks
+ * One today: `composed`. The other options of a `run()` call — `until`, `resumeAt` and `layer` — belong to a single call, not to a run, and are not flags; nor is a constant someone may want to tune later, until someone asks.
+ *
+ * This is the node face's table. The client runs in a tab with no way to resolve `@beltype/common`, so `client.ts` keeps the literal `composed = false` as `run()`'s default, and `test/flags.test.ts` pins that literal to this table's default.
+ *
+ * @packageDocumentation
+ */
+export declare const ciceroFlags: {
+    readonly owner: string;
+    readonly table: {
+        /** Default `false`: the browser sets the lines and Cicero reads what it produced. `true` gives them to the Compositor (*the composed mode reaches the operator*, 2026-09-10). */
+        composed: {
+            values: boolean[];
+            default: boolean;
+        };
+    };
+    readonly defaults: import("@beltype/common/flags").FlagValues<{
+        /** Default `false`: the browser sets the lines and Cicero reads what it produced. `true` gives them to the Compositor (*the composed mode reaches the operator*, 2026-09-10). */
+        composed: {
+            values: boolean[];
+            default: boolean;
+        };
+    }>;
+    resolve(given?: Partial<import("@beltype/common/flags").FlagValues<{
+        /** Default `false`: the browser sets the lines and Cicero reads what it produced. `true` gives them to the Compositor (*the composed mode reaches the operator*, 2026-09-10). */
+        composed: {
+            values: boolean[];
+            default: boolean;
+        };
+    }>> | undefined): import("@beltype/common/flags").FlagValues<{
+        /** Default `false`: the browser sets the lines and Cicero reads what it produced. `true` gives them to the Compositor (*the composed mode reaches the operator*, 2026-09-10). */
+        composed: {
+            values: boolean[];
+            default: boolean;
+        };
+    }>;
+    parse(name: string, raw: string): unknown;
+};

package/dist/seam/flags.js

@@ -0,0 +1,15 @@
+/**
+ * Cicero's run-wide flags, in `@beltype/common`'s shape.
+ *
+ * @remarks
+ * One today: `composed`. The other options of a `run()` call — `until`, `resumeAt` and `layer` — belong to a single call, not to a run, and are not flags; nor is a constant someone may want to tune later, until someone asks.
+ *
+ * This is the node face's table. The client runs in a tab with no way to resolve `@beltype/common`, so `client.ts` keeps the literal `composed = false` as `run()`'s default, and `test/flags.test.ts` pins that literal to this table's default.
+ *
+ * @packageDocumentation
+ */
+import { defineFlags } from '@beltype/common/flags';
+export const ciceroFlags = defineFlags('cicero', {
+    /** Default `false`: the browser sets the lines and Cicero reads what it produced. `true` gives them to the Compositor (*the composed mode reaches the operator*, 2026-09-10). */
+    composed: { values: [false, true], default: false }
+});

package/dist/seam/host.d.ts

@@ -2,9 +2,10 @@
  * The host face, `@beltype/cicero`: what a host that is not BelType's CLI needs to paginate a document with Cicero.
  *
  * @remarks
- * `ciceroEngine` is the engine's side of BelType's engine seam (its head, its bootstrap, its vendored assets); `rewriteDocumentSheets` makes a document's sheets Cicero's (the `@page` world renamed, optionally under a layer the host names). The page-side API is the client handle, `window.__beltypeCicero`, typed in `seam/handle.d.ts`.
+ * `ciceroEngine` is the engine's side of BelType's engine seam (its head, its bootstrap, its vendored assets); `rewriteDocumentSheets` makes a document's sheets Cicero's (the `@page` world renamed, optionally under a layer the host names). A host that needs one of them alone imports the subpath (`@beltype/cicero/engine`, `@beltype/cicero/flags`, `@beltype/cicero/rewrite`), since this face loads all three and the sheet rewriter brings css-tree with it (about 24 ms in node). The page-side API is the client handle, `window.__beltypeCicero`, typed in `seam/handle.d.ts`.
  *
  * @packageDocumentation
  */
 export { ciceroEngine } from './index.ts';
 export { rewriteDocumentSheets } from './rewrite-document.ts';
+export { ciceroFlags } from './flags.ts';

package/dist/seam/host.js

@@ -2,9 +2,10 @@
  * The host face, `@beltype/cicero`: what a host that is not BelType's CLI needs to paginate a document with Cicero.
  *
  * @remarks
- * `ciceroEngine` is the engine's side of BelType's engine seam (its head, its bootstrap, its vendored assets); `rewriteDocumentSheets` makes a document's sheets Cicero's (the `@page` world renamed, optionally under a layer the host names). The page-side API is the client handle, `window.__beltypeCicero`, typed in `seam/handle.d.ts`.
+ * `ciceroEngine` is the engine's side of BelType's engine seam (its head, its bootstrap, its vendored assets); `rewriteDocumentSheets` makes a document's sheets Cicero's (the `@page` world renamed, optionally under a layer the host names). A host that needs one of them alone imports the subpath (`@beltype/cicero/engine`, `@beltype/cicero/flags`, `@beltype/cicero/rewrite`), since this face loads all three and the sheet rewriter brings css-tree with it (about 24 ms in node). The page-side API is the client handle, `window.__beltypeCicero`, typed in `seam/handle.d.ts`.
  *
  * @packageDocumentation
  */
 export { ciceroEngine } from './index.js';
 export { rewriteDocumentSheets } from './rewrite-document.js';
+export { ciceroFlags } from './flags.js';

package/dist/seam/rewrite-document.d.ts

@@ -9,6 +9,8 @@
  *
  * **With a layer named, every sheet of the document goes into it** (*the author's sheets in a layer the host names*, 2026-10-17): a `<style>` holds its text wrapped (`wrapInLayer`), and every `<link>` becomes a `<style>` of its wrapped text at the same position. **The address is not kept, on a measurement**: `<style>@import url(<the href>) layer(<name>)</style>` would keep it, and Chromium fetches an imported sheet once for every frame that imports it, but it parses it again in each (measured 2026-10-17 in the studio experiment, an 11 MB sheet in four same-origin frames: +9 MB a further frame linked, +61–74 MB imported), so an import buys a host no shared copy a `<style>` does not, and it hides the sheet from every walk that reads `document.styleSheets`' top level (`@page`, `@font-face` for a printer, `position: fixed`). A host that shared a linked sheet's parsed copy across frames loses that sharing under a layer, and the loss is the host's to weigh. **And the engine's root line-height provision moves into the engine's own layer**, the first one: unlayered, it would outrank every rule of the author's now-layered sheets, the author's own root line-height among them, where it was written to lose every tie. **And the order of the two layers is stated first in the head**, `@layer <the engine's>, <the host's>;` in the engine's own layers element (made where it is not there yet): a layer's place is where it is first named, and a host that seats the author's sheets before the engine's head (the HTML lane, the studio, its print frame) would otherwise name the author's layer before the engine's, putting the engine's `!important` trimming below an author's and its provision above the author's normal rules. Without a layer nothing here changes.
  *
+ * **A replaced `<link>`'s relative addresses are written against its href** (`rebaseUrls`), because a `<style>` resolves them against the document.
+ *
  * **The `<link>` is replaced, not merely disabled.** A disabled link leaves the browser's own copy of the rules out of the CSSOM but leaves the element in the document, and the next thing to walk `document.styleSheets` would meet two sheets where the author wrote one.
  *
  * @packageDocumentation

package/dist/seam/rewrite-document.js

@@ -9,11 +9,13 @@
  *
  * **With a layer named, every sheet of the document goes into it** (*the author's sheets in a layer the host names*, 2026-10-17): a `<style>` holds its text wrapped (`wrapInLayer`), and every `<link>` becomes a `<style>` of its wrapped text at the same position. **The address is not kept, on a measurement**: `<style>@import url(<the href>) layer(<name>)</style>` would keep it, and Chromium fetches an imported sheet once for every frame that imports it, but it parses it again in each (measured 2026-10-17 in the studio experiment, an 11 MB sheet in four same-origin frames: +9 MB a further frame linked, +61–74 MB imported), so an import buys a host no shared copy a `<style>` does not, and it hides the sheet from every walk that reads `document.styleSheets`' top level (`@page`, `@font-face` for a printer, `position: fixed`). A host that shared a linked sheet's parsed copy across frames loses that sharing under a layer, and the loss is the host's to weigh. **And the engine's root line-height provision moves into the engine's own layer**, the first one: unlayered, it would outrank every rule of the author's now-layered sheets, the author's own root line-height among them, where it was written to lose every tie. **And the order of the two layers is stated first in the head**, `@layer <the engine's>, <the host's>;` in the engine's own layers element (made where it is not there yet): a layer's place is where it is first named, and a host that seats the author's sheets before the engine's head (the HTML lane, the studio, its print frame) would otherwise name the author's layer before the engine's, putting the engine's `!important` trimming below an author's and its provision above the author's normal rules. Without a layer nothing here changes.
  *
+ * **A replaced `<link>`'s relative addresses are written against its href** (`rebaseUrls`), because a `<style>` resolves them against the document.
+ *
  * **The `<link>` is replaced, not merely disabled.** A disabled link leaves the browser's own copy of the rules out of the CSSOM but leaves the element in the document, and the next thing to walk `document.styleSheets` would meet two sheets where the author wrote one.
  *
  * @packageDocumentation
  */
-import { rewriteSheet, rewriteNote, isLayerName } from './rewrite.js';
+import { rewriteSheet, rewriteNote, isLayerName, rebaseUrls } from './rewrite.js';
 import { CICERO_INTERFACE, CICERO_PROVISION, LAYER as ENGINE_LAYER, WORDS_RULES, hasWord } from '../src/data-beltype.js';
 import { LAYERS_ID } from '../src/dressing.js';
 /** Is this URL on the document's own origin? A relative href resolves against the document, so the constructor answers both cases at once. */
@@ -112,10 +114,12 @@ export async function rewriteDocumentSheets(doc, judged = new WeakMap(), { layer
             judged.set(node, out.text); // the text the next run will find there
             return;
         }
+        // A `<style>` resolves its addresses against the document, so the sheet's own are written out first.
+        const text = rebaseUrls(out.text, new URL(node.getAttribute('href'), doc.baseURI).href);
         const style = doc.createElement('style');
-        style.textContent = out.text;
+        style.textContent = text;
         node.replaceWith(style); // in place, so the sheet keeps its seat in the cascade
-        judged.set(style, out.text);
+        judged.set(style, text);
     });
     const note = rewriteNote(counts);
     if (note)

package/dist/seam/rewrite.d.ts

@@ -74,5 +74,15 @@ export declare function wrapInLayer(source: string, layer: string): {
     text: string;
     wrapped: boolean;
 };
+/**
+ * A linked sheet's relative addresses, resolved against its own href, for the `<style>` that takes its place (`rewrite-document.js`).
+ *
+ * @remarks A `<style>` resolves `url()` against the document, a `<link>` against the sheet: once a sheet in `css/` is moved into a `<style>`, `url("./font.ttf")` asks for the document's `./font.ttf` (the tester's case, 2026-11-03: a font inside `@media print`, whose opening made the sheet a `<style>`). Paged.js resolves a sheet it inlines the same way. Every `url()` and every `@import "…"` string is written absolute, in place, so no line moves; a sheet css-tree cannot parse is returned as it is.
+ *
+ * ponytail: `url()` and the `@import` string only. A url in a custom property's value (kept raw) or a string in `image-set()` still resolves against the document; add them when a document needs them.
+ *
+ * @param base - the absolute href the sheet was fetched from.
+ */
+export declare function rebaseUrls(source: string, base: string): string;
 /** The console line a host says once per document it rewrote — what moved and why a reader of the sheet will meet two strange forms. */
 export declare function rewriteNote(counts: Partial<Record<string, number>>): string | null;

package/dist/seam/rewrite.js

@@ -522,6 +522,38 @@ function splitPageSelectorLists(source) {
     });
     return { text: applyEdits(source, edits), split: edits.length };
 }
+/** An address the sheet's own href is the base of: not one with a scheme (`data:`, `https:`), and not a fragment, which names the document (`clip-path: url(#c)`). */
+const isRelative = (url) => url !== '' && !url.startsWith('#') && !/^[a-z][a-z\d+.-]*:/i.test(url);
+/**
+ * A linked sheet's relative addresses, resolved against its own href, for the `<style>` that takes its place (`rewrite-document.js`).
+ *
+ * @remarks A `<style>` resolves `url()` against the document, a `<link>` against the sheet: once a sheet in `css/` is moved into a `<style>`, `url("./font.ttf")` asks for the document's `./font.ttf` (the tester's case, 2026-11-03: a font inside `@media print`, whose opening made the sheet a `<style>`). Paged.js resolves a sheet it inlines the same way. Every `url()` and every `@import "…"` string is written absolute, in place, so no line moves; a sheet css-tree cannot parse is returned as it is.
+ *
+ * ponytail: `url()` and the `@import` string only. A url in a custom property's value (kept raw) or a string in `image-set()` still resolves against the document; add them when a document needs them.
+ *
+ * @param base - the absolute href the sheet was fetched from.
+ */
+export function rebaseUrls(source, base) {
+    let ast;
+    try {
+        ast = parse(source, SHEET_OPTIONS);
+    }
+    catch {
+        return source;
+    }
+    const edits = [];
+    const absolute = (url) => `"${new URL(url, base).href}"`;
+    walkStyled(ast, source, SHEET_OPTIONS, {
+        enter(node) {
+            if (node.type === 'Url' && node.loc && isRelative(node.value))
+                edits.push({ start: node.loc.start.offset, end: node.loc.end.offset, text: `url(${absolute(node.value)})` });
+            const first = node.type === 'Atrule' && String(node.name).toLowerCase() === 'import' ? node.prelude?.children?.first : null;
+            if (first?.type === 'String' && first.loc && isRelative(first.value))
+                edits.push({ start: first.loc.start.offset, end: first.loc.end.offset, text: absolute(first.value) });
+        }
+    });
+    return applyEdits(source, edits);
+}
 /** The console line a host says once per document it rewrote — what moved and why a reader of the sheet will meet two strange forms. */
 export function rewriteNote(counts) {
     const parts = [];

package/dist/src/chase.js

@@ -15,7 +15,7 @@
  *
  * @packageDocumentation
  */
-import { MARGIN_CELLS, ALIGN_X, ALIGN_Y, HORIZONTAL_BANDS, bandWidths, translateAlignment } from './margin-boxes.js';
+import { MARGIN_CELLS, ALIGN_X, ALIGN_Y, HORIZONTAL_BANDS, bandTracks, bandWidths, translateAlignment } from './margin-boxes.js';
 import { counterLevels } from './document-state.js';
 import { encodeStringProp, STRING_KEYWORDS } from './gcpm-encoding.js';
 import { cssString } from './reads.js';
@@ -186,9 +186,9 @@ export class BeltypePage extends HTMLElement {
         this.style.containIntrinsicSize = `${pageW}px ${pageH - 1}px`;
         this.#bandWidth = pageW - margins.left - margins.right;
         this.#pageH = pageH;
-        const cw3 = this.#bandWidth / 3;
+        const [wa, wb, wc] = bandTracks(this.#bandWidth);
         const ch3 = (pageH - margins.top - margins.bottom) / 3;
-        this.style.gridTemplateColumns = `${margins.left}px ${cw3}px ${cw3}px ${cw3}px ${margins.right}px`;
+        this.style.gridTemplateColumns = `${margins.left}px ${wa}px ${wb}px ${wc}px ${margins.right}px`;
         this.style.gridTemplateRows = `${margins.top}px ${ch3}px ${ch3}px ${ch3}px ${Math.max(0, margins.bottom - 1)}px`;
     }
     /**

package/dist/src/margin-boxes.d.ts

@@ -35,6 +35,13 @@ export declare const MARGIN_BOXES: string[];
  */
 export declare const ALIGN_X: Record<string, string>;
 export declare const ALIGN_Y: Record<string, string>;
+/**
+ * The three tracks the page grid gives the band between its margins, in CSS px.
+ *
+ * @remarks
+ * Chromium lays a length out in 1/64 px and drops the remainder of every track on its own, so three thirds of 423.307 px are three tracks of 141.09375 and sum to 423.28125 px, while the measure container, one box of that width, floors the whole to 423.296875. A line that fits the one and not the other is measured on one line and shown on two (specimen `trattato`, page 111). The tracks are therefore whole 1/64 px units that sum to the floor of the band, the last one taking the remainder: no third of a unit is left for the grid to drop, and the content area is as wide as the container it was measured in.
+ */
+export declare function bandTracks(band: number): [number, number, number];
 /** The three boxes of each horizontal band, in band order — what `bandWidths` sizes, and the only membership test `chase.js` needs to know which cells leave the outer grid. */
 export declare const HORIZONTAL_BANDS: {
     top: string[];

package/dist/src/margin-boxes.js

@@ -41,6 +41,17 @@ export const MARGIN_BOXES = MARGIN_CELLS.map(([name]) => name);
  */
 export const ALIGN_X = { left: 'flex-start', start: 'flex-start', right: 'flex-end', end: 'flex-end', center: 'center', justify: 'flex-start' };
 export const ALIGN_Y = { top: 'flex-start', 'text-top': 'flex-start', middle: 'center', bottom: 'flex-end', 'text-bottom': 'flex-end' };
+/**
+ * The three tracks the page grid gives the band between its margins, in CSS px.
+ *
+ * @remarks
+ * Chromium lays a length out in 1/64 px and drops the remainder of every track on its own, so three thirds of 423.307 px are three tracks of 141.09375 and sum to 423.28125 px, while the measure container, one box of that width, floors the whole to 423.296875. A line that fits the one and not the other is measured on one line and shown on two (specimen `trattato`, page 111). The tracks are therefore whole 1/64 px units that sum to the floor of the band, the last one taking the remainder: no third of a unit is left for the grid to drop, and the content area is as wide as the container it was measured in.
+ */
+export function bandTracks(band) {
+    const units = Math.floor(band * 64);
+    const third = Math.floor(units / 3);
+    return [third / 64, third / 64, (units - 2 * third) / 64];
+}
 /** The three boxes of each horizontal band, in band order — what `bandWidths` sizes, and the only membership test `chase.js` needs to know which cells leave the outer grid. */
 export const HORIZONTAL_BANDS = {
     top: ['top-left', 'top-center', 'top-right'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beltype/cicero",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Cicero, a paged-media engine for the live browser: it cuts a document into pages under CSS Paged Media and presents them as real frames. Beta.",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,14 @@
       "types": "./dist/seam/host.d.ts",
       "import": "./dist/seam/host.js"
     },
+    "./engine": {
+      "types": "./dist/seam/index.d.ts",
+      "import": "./dist/seam/index.js"
+    },
+    "./flags": {
+      "types": "./dist/seam/flags.d.ts",
+      "import": "./dist/seam/flags.js"
+    },
     "./rewrite": {
       "types": "./dist/seam/rewrite-document.d.ts",
       "import": "./dist/seam/rewrite-document.js"
@@ -53,7 +61,7 @@
     "prepare": "npm run build"
   },
   "dependencies": {
-    "@beltype/common": "0.1.1",
+    "@beltype/common": "0.1.2",
     "css-tree": "^3.2.1",
     "pdfjs-dist": "6.2.108"
   },