@beltype/cicero 0.1.6 → 0.1.7

package/dist/src/hyphenate.js

@@ -8,6 +8,7 @@
  * @packageDocumentation
  */
 import enUs from './hyphen-patterns/en-us.js';
+import it from './hyphen-patterns/it.js';
 const LANGS = new Map();
 /** Build a language's trie once. Exposed as data-in, function-out so a future language module registers the same way. */
 export function registerLanguage(data) {
@@ -36,12 +37,13 @@ export function registerLanguage(data) {
     for (const ex of data.exceptions ?? []) {
         exceptions.set(ex.replace(/-/g, ''), ex);
     }
-    const lang = { trie, exceptions, leftmin: data.leftmin, rightmin: data.rightmin };
+    const lang = { trie, exceptions, leftmin: data.leftmin, rightmin: data.rightmin, word: data.word ?? /^()([a-zA-Z]+)()$/ };
     for (const id of data.id)
         LANGS.set(id, lang);
     return lang;
 }
 registerLanguage(enUs);
+registerLanguage(it);
 /** Resolve a lang attribute value to a registered language, or null (no language, no candidates — auto-hyphenation is never guessed). */
 export function languageFor(langAttr) {
     if (!langAttr)
@@ -66,13 +68,19 @@ export function resolveLimits(lang, limits = {}) {
  *
  * @param lang - from `languageFor`; null yields no candidates.
  */
-export function hyphenationOffsets(word, lang, limits = {}) {
+export function hyphenationOffsets(text, lang, limits = {}) {
     if (!lang)
         return [];
     const { before, after, total } = resolveLimits(lang, limits);
-    if (word.length < total || word.length < before + after || !/^[a-zA-Z]+$/.test(word))
+    const found = lang.word.exec(text);
+    if (!found)
         return [];
-    const lower = word.toLowerCase();
+    const lead = found[1].length;
+    const word = found[2];
+    if (word.length < total || word.length < before + after)
+        return [];
+    // Both apostrophes are one letter to a pattern; the replacement keeps every offset.
+    const lower = word.toLowerCase().replace(/’/g, "'");
     const exception = lang.exceptions.get(lower);
     if (exception !== undefined) {
         const offsets = [];
@@ -80,7 +88,7 @@ export function hyphenationOffsets(word, lang, limits = {}) {
         for (const part of exception.split('-').slice(0, -1)) {
             pos += part.length;
             if (pos >= before && word.length - pos >= after)
-                offsets.push(pos);
+                offsets.push(lead + pos);
         }
         return offsets;
     }
@@ -106,7 +114,7 @@ export function hyphenationOffsets(word, lang, limits = {}) {
     for (let p = 2; p < marked.length - 1; p++) {
         const off = p - 1;
         if (points[p] % 2 === 1 && off >= before && word.length - off >= after)
-            offsets.push(off);
+            offsets.push(lead + off);
     }
     return offsets;
 }

package/dist/src/measure.d.ts

@@ -12,7 +12,9 @@ export type MeasureContext = ReturnType<typeof createMeasureContext>;
 /**
  * The intake under *render-identical conditions* (I5): refuse to adjudicate under conditions print will not reproduce. `relaxDpr` is the preview's escape hatch only — decisions are then valid for the screen being looked at, not for print; no gate ever sets it.
  *
- * @throws Error — bare and deliberate (`src/` may not import BelType's error types): a device pixel ratio other than 1 without `relaxDpr`, or a document root whose line-height is not explicit (*render-identical conditions*, I5).
+ * A vertical or sideways root is refused by name too (Codeberg issue 12): every read in this engine is horizontal, the lines by vertical overlap, the cut by a y, the page area by its height, so under `writing-mode: sideways-lr` on the root the text of a positioned paragraph fell below the clip and was never resumed, and the printer's tiling invariant refused what the engine should have. Vertical writing is outside the beta, and a refusal that says so at intake is cheaper than one three tools later.
+ *
+ * @throws Error — bare and deliberate (`src/` may not import BelType's error types): a device pixel ratio other than 1 without `relaxDpr`, a document root whose line-height is not explicit (*render-identical conditions*, I5), or a document root whose writing mode is not `horizontal-tb`.
  */
 export declare function assertRenderConditions(doc: Document, { relaxDpr }?: {
     relaxDpr?: boolean;
@@ -64,13 +66,13 @@ export type PagePublish = {
  * @param contentWidthPx - the page's true content width — the one geometry decisions are valid under (*render-identical conditions*, I5).
  */
 export declare function createMeasureContext(doc: Document, contentWidthPx: number): {
-    container: HTMLElement;
+    container: HTMLDivElement;
     /**
      * Lay out a feed of nodes and force one layout. The caller obtains geometry only through a Gauge report taken afterward — obtaining the report seals the mutation phase (*render-identical conditions*, I5, by type; see gauge.js).
      *
      * @param nodes - cloned feed content; never source elements (*the source document is never written*, C5, and never moved).
      * @param publish - what the page the feed is for publishes on its host (*the page carries its conditions*, 2026-10-21), written on the container so a flow site that reads a page fact is measured with it standing; absent, the container carries none, and such a site reads its reservation.
      */
-    measure(nodes: Node[], publish?: PagePublish | null): HTMLElement;
+    measure(nodes: Node[], publish?: PagePublish | null): HTMLDivElement;
     dispose(): void;
 };

package/dist/src/measure.js

@@ -15,17 +15,23 @@ const NEUTRALIZE_ID = '__beltype-neutralize';
 /**
  * The intake under *render-identical conditions* (I5): refuse to adjudicate under conditions print will not reproduce. `relaxDpr` is the preview's escape hatch only — decisions are then valid for the screen being looked at, not for print; no gate ever sets it.
  *
- * @throws Error — bare and deliberate (`src/` may not import BelType's error types): a device pixel ratio other than 1 without `relaxDpr`, or a document root whose line-height is not explicit (*render-identical conditions*, I5).
+ * A vertical or sideways root is refused by name too (Codeberg issue 12): every read in this engine is horizontal, the lines by vertical overlap, the cut by a y, the page area by its height, so under `writing-mode: sideways-lr` on the root the text of a positioned paragraph fell below the clip and was never resumed, and the printer's tiling invariant refused what the engine should have. Vertical writing is outside the beta, and a refusal that says so at intake is cheaper than one three tools later.
+ *
+ * @throws Error — bare and deliberate (`src/` may not import BelType's error types): a device pixel ratio other than 1 without `relaxDpr`, a document root whose line-height is not explicit (*render-identical conditions*, I5), or a document root whose writing mode is not `horizontal-tb`.
  */
 export function assertRenderConditions(doc, { relaxDpr = false } = {}) {
     const win = doc.defaultView;
     if (!relaxDpr && win.devicePixelRatio !== 1) {
         throw new Error(`I5: unit device pixel ratio required for adjudication, got ${win.devicePixelRatio}`);
     }
-    const lh = win.getComputedStyle(doc.documentElement).lineHeight;
+    const root = win.getComputedStyle(doc.documentElement);
+    const lh = root.lineHeight;
     if (!/^-?[\d.]+px$/.test(lh)) {
         throw new Error(`I5 (DPR ruling): explicit line-height required, document root computes '${lh}'`);
     }
+    if (root.writingMode && root.writingMode !== 'horizontal-tb') {
+        throw new Error(`a vertical or sideways root is outside this engine's beta: the document root computes writing-mode '${root.writingMode}', and every read here is horizontal (the line by vertical overlap, the cut by a y). Write the document horizontal-tb, or print it with another engine.`);
+    }
 }
 /**
  * Await font readiness once — late-arriving truth handled before the first measure, never during adjudication.
@@ -134,16 +140,14 @@ export function createMeasureContext(doc, contentWidthPx) {
         style.textContent = `#${CONTAINER_ID}, #${CONTAINER_ID} * { break-before: auto !important; break-after: auto !important; break-inside: auto !important; orphans: 2 !important; widows: 2 !important; transform: none !important; rotate: none !important; scale: none !important; translate: none !important; perspective: none !important; }`;
         doc.head.appendChild(style);
     }
-    let container = doc.getElementById(CONTAINER_ID);
-    if (!container) {
-        container = doc.createElement('div');
-        container.id = CONTAINER_ID;
-        doc.body.appendChild(container);
-    }
+    // Each context has a container of its own, so two fills in flight never measure in each other's. They share the one id on purpose, transiently: the neutralizing sheet and `reads.ts` select by it, at the specificity the sheet needs against an author's `!important`.
+    const container = doc.createElement('div');
+    container.id = CONTAINER_ID;
+    doc.body.appendChild(container);
     // flow-root: child margins stay inside, so the container's box is the measured flow's coordinate space. Off-viewport, never display:none — display:none has no geometry.
     const css = `position: absolute; left: -100000px; top: 0; width: ${contentWidthPx}px; display: flow-root;`;
     container.style.cssText = css;
-    /** The container is one element for every context, and a run that stops at a page shares it (*the pages are cut as far as they are asked*, 2026-10-12): the presentation composes a page with a context of its own, at its own width, and puts it away — which removes the container and the neutralizing style from under a run that is waiting to go on. So every measure makes sure of both, and of the width it was created for, before it lays anything out. Nothing else changes: where no other context ran in between, all three are already so. */
+    /** A context can stand idle while another runs (*the pages are cut as far as they are asked*, 2026-10-12), and a host may move what it wears, so every measure makes sure of the sheet, the container and the width before it lays anything out. Where nothing moved, all three are already so. */
     const ensure = () => {
         if (!style.isConnected)
             doc.head.appendChild(style);
@@ -171,7 +175,8 @@ export function createMeasureContext(doc, contentWidthPx) {
         },
         dispose() {
             container.remove();
-            style.remove();
+            if (!doc.querySelector(`#${CONTAINER_ID}`))
+                style.remove();
         }
     };
 }

package/dist/src/reads.js

@@ -26,7 +26,7 @@ export const MAX_RUNS = 3;
 /** The reservation a forward layout read stands at during the first run, Egildo's ruling of 2026-10-03: wrong for nearly every reference, so nothing rests on it, and never printed, because the loop keeps the last true values. */
 export const RESERVATION = '0';
 /** A CSS string literal for any text: a quote, a backslash and a line break escaped, nothing else. */
-export const cssString = (text) => `"${String(text).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\a ')}"`;
+export const cssString = (text) => `"${String(text).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/[\u0000-\u001f\u007f]/g, (ch) => `\\${ch.charCodeAt(0).toString(16)} `)}"`;
 /** The selector a delivery is keyed by: the attribute the function reads, at the value this element carries. */
 export const attrSelector = (attr, value) => `[${attr}=${cssString(value)}]`;
 /**

package/dist/src/stonehand.js

@@ -12,6 +12,7 @@
  * @packageDocumentation
  */
 import { isAtom, READS_ITS_CHILDREN } from './word-space.js';
+import { ARTIFACT, hasWord } from './data-beltype.js';
 /**
  * THE MAKE-UP ORDER (*breaks are classified*, I3, amended in the fifth round) — which constraint yields first, and the standing fact that a constraint which has yielded still pulls.
  *
@@ -158,7 +159,7 @@ function walkOf(report, sourceOf, root = null, styleCache = new Map(), forcing =
     const monolithic = (box) => {
         if (box.anonymous)
             return false; // a run of lines, never one unit
-        if (box.laidOutLast)
+        if (box.laidOutLast || box.laidOutFirst)
             return true; // a footer written before its rows: its words stand before the rows in the word space, so no place inside it could be addressed (*the footer before the rows*)
         const live = sourceOf(box.el) ?? box.el;
         const held = isMonolith(box.el, styleOfBox(box), live);
@@ -197,9 +198,11 @@ function walkOf(report, sourceOf, root = null, styleCache = new Map(), forcing =
     /** A row's items are parallel flows too (*every branch gets a place*, 2026-09-21; §2.1's own list — the cells of a row, grid items, flex items). `report.rowOf` is the Gauge's answer: the side-by-side siblings a box stands among, or null. An item's interior offers nothing, exactly as a float's does, and the boundary between two items of one row is not a place in any procession — they stand beside each other, so nothing lies between them on the block axis. A row therefore offers two readings and no more: the boundary before it, on its first item, and the page edge through it. */
     const rowOf = (box) => (box === root ? null : report.rowOf?.(box) ?? null);
     const insideRowItem = (box) => climb(box, (p) => !!rowOf(p), false);
-    /** Does the walk read this box at all? Not an inline box, nothing inside a monolith, a parallel flow or a row item — and a row answers once, at its first item (see `rowOf`). */
+    /** A copy the engine repeats (`artifact`), the table's header on a continuation: furniture with a footprint, no content of the flow, so no break point stands in it (*an artifact is never read*). */
+    const copy = (box) => !box.anonymous && hasWord(box.el, ARTIFACT);
+    /** Does the walk read this box at all? Not an inline box, nothing inside a monolith, a parallel flow, a row item or a repeated copy — and a row answers once, at its first item (see `rowOf`). */
     const walks = (box) => {
-        if (box.inline || insideMonolith(box) || insideParallel(box) || insideRowItem(box))
+        if (box.inline || copy(box) || insideMonolith(box) || insideParallel(box) || insideRowItem(box) || climb(box, copy, false))
             return false;
         const row = rowOf(box);
         return !row || row[0] === box;
@@ -210,7 +213,7 @@ function walkOf(report, sourceOf, root = null, styleCache = new Map(), forcing =
      * A float, an absolutely positioned box and a row are not where it stops: a float's top is where the float was pushed, not the procession's, and a row's first item is not the row's top. The premise is stated rather than proved — that in-flow tops do not go backward in document order — and a negative margin taller than the box above it, or a relative offset, would break it. A table's footer written before its rows broke it too, and is walked where it is laid out instead (`gauge.js`'s `laidOutLast`, case 110).
      */
     const standsBelow = (box, limit, eps) => !rowOf(box) && !parallelBox(box) && box.rect.top > limit + eps;
-    return { report, sourceOf, boxes, win, root, styleCache, forcing, styleOfBox, monolithic, insideMonolith, parallelBox, insideParallel, rowOf, insideRowItem, walks, standsBelow };
+    return { report, sourceOf, boxes, win, root, styleCache, forcing, styleOfBox, monolithic, insideMonolith, parallelBox, insideParallel, rowOf, insideRowItem, copy, walks, standsBelow };
 }
 /** Does this feed hold the box the retreat walk stops at — the first in-flow box whose top lies below the page's limit? The check a bounded feed must pass before anything is decided on it (*the Cast-off bounds the feed*, 2026-09-26): a feed that holds that box gives the walk everything it reads, and one that does not stopped above the edge and is poured again. */
 export function reachesBelowTheEdge({ report, sourceOf, pageStart, contentHeight, eps = 0.25 }) {
@@ -261,7 +264,7 @@ export function firstBelowTheEdge({ report, sourceOf, limit, eps = 0.25, sourced
  * @param a.stats - when given, counts what the collection costs: the boxes it visited, the line stacks it measured and the ones it skipped, and the milliseconds the lines and the end gaps took (`adjudicate` publishes it as the measure's detail).
  */
 function collect(w, { boxes, limit, pageStart, eps, stats }) {
-    const { report, win, root, styleOfBox, monolithic, parallelBox, rowOf, walks, standsBelow } = w;
+    const { report, win, root, styleOfBox, monolithic, parallelBox, rowOf, copy, walks, standsBelow } = w;
     /**
      * §5.3's *leaving room*, priced (*the fragment that wraps itself*, 2026-09-15). *"When a box breaks, its content box extends to fill any remaining fragmentainer extent (leaving room for any margins/borders/padding applied by `box-decoration-break: clone`)."* So a cut inside a box that clones its decoration costs the page that box's block-end border and padding, on top of the content above it — and every ancestor the same cut breaks costs its own.
      *
@@ -344,11 +347,13 @@ function collect(w, { boxes, limit, pageStart, eps, stats }) {
         const siblings = box === root ? [] : report.processionOf(box).filter((b) => !isAbsolutelyPositioned(styleOfBox(b)));
         const si = siblings.indexOf(box);
         // A footer written before its rows offers no boundary before it (*the footer before the rows*, 2026-10-15): the place is after the last row in the layout and before the first in the document, and an address can only say the second.
-        if (si > 0 && !box.laidOutLast) {
+        // Nor does the box after a header written after its rows (the mirror): the place is after the header in the layout and before every row in the document, so the page would hold the header's copy alone.
+        if (si > 0 && !box.laidOutLast && !siblings[si - 1].laidOutFirst) {
             // Two siblings answer here, and they are not always the same one. **The keeps** are the immediately-adjacent box's, because §4.1 names *"a float and an immediately-adjacent in-flow or floated box"* as a Class A pair in as many words — a float's own `break-after` binds the boundary after it, which is §3.1's *should* on floats that this engine honours and Chromium declines. **The position** is the previous in-flow sibling's bottom border edge, because a parallel flow's extent is not a place in the procession the cuts divide (§2.1): the float is laid out beside the content, so the page closes where the previous in-flow box ended and the float's own bottom says nothing about it. Pricing this at the float's bottom is how a 96mm rail put every slab standing beside it off the page — measured, `cases/21-parallel-flows`, where the boundary before the first slab was priced at y 400 in a 264px page area.
             const pair = siblings[si - 1];
             const anchor = last(siblings.slice(0, si).filter((b) => !parallelBox(b))) ?? null;
-            if (anchor) {
+            // Before the rows of a continuation only the repeated header stands, and a copy is furniture (*an artifact is never read*): a boundary there takes nothing of the box, and would send the page back to where the box began.
+            if (anchor && !siblings.slice(0, si).every((b) => parallelBox(b) || copy(b))) {
                 candidates.push({
                     kind: 'A',
                     cls: 'A',
@@ -444,7 +449,7 @@ function collect(w, { boxes, limit, pageStart, eps, stats }) {
         // The place it names is before the box's first in-flow child, past the gap (*the cut divides its ancestors*, 2026-09-29): the page before carries the box's border, its padding and whatever stands in the gap — an empty float, the clearance under it — and the page after resumes the box divided, its first child whole. So the position is the child's outer top, which is the content edge plus the gap; it used to be the box's top plus its border, which put the padding on the next page and offered a break point §4.1 does not provide (`packages/essay/cases/71-the-box-that-begins-a-page`).
         const startGap = box.blockChildren.length ? report.gapAt({ box, edge: 'start' }) : 0;
         const firstInFlow = startGap > eps ? box.blockChildren.find((c) => !parallelBox(c)) : undefined;
-        if (firstInFlow) {
+        if (firstInFlow && !copy(firstInFlow)) {
             const prevSibling = si > 0 ? siblings[si - 1] : null;
             const bs = win.getComputedStyle(box.el);
             candidates.push({

package/dist/src/word-space.d.ts

@@ -216,6 +216,14 @@ export declare function blockChildrenOf(el: Element, isInline?: (el: Element) =>
  * @param el - a clone or a source element.
  */
 export declare function footerBeforeRows(el: Element): boolean;
+/**
+ * Is this a table's header group written after a row or row group of its table, which CSS 2.1 §17.2 lays out before them all the same (*"always displayed before all other rows and row groups"*)?
+ *
+ * @remarks The mirror of {@link footerBeforeRows} (*thead-after-rows-and-tall-footer-lose-rows*, 2026-11-07): the Gauge walks such a header first, the Stonehand offers no place inside it or right after it, and its words stand after the rows in the word space, so a page before its words shows it by its repeated copy alone. One that does not repeat, in a divided table, is refused by the driver. Read by computed display, so a clone answers for its source.
+ *
+ * @param el - a clone or a source element.
+ */
+export declare function headerAfterRows(el: Element): boolean;
 /**
  * The computed style of the box an author declared — the clone's registered source, or the element itself where it is live and connected. `null` for everything else, which is the honest answer rather than a default: a detached clone with no registration is a `<br>` or a filler span the Compositor inserted, and an element nobody declared has no declaration to read.
  *

package/dist/src/word-space.js

@@ -495,6 +495,21 @@ export function footerBeforeRows(el) {
             return true;
     return false;
 }
+/**
+ * Is this a table's header group written after a row or row group of its table, which CSS 2.1 §17.2 lays out before them all the same (*"always displayed before all other rows and row groups"*)?
+ *
+ * @remarks The mirror of {@link footerBeforeRows} (*thead-after-rows-and-tall-footer-lose-rows*, 2026-11-07): the Gauge walks such a header first, the Stonehand offers no place inside it or right after it, and its words stand after the rows in the word space, so a page before its words shows it by its repeated copy alone. One that does not repeat, in a divided table, is refused by the driver. Read by computed display, so a clone answers for its source.
+ *
+ * @param el - a clone or a source element.
+ */
+export function headerAfterRows(el) {
+    if (sourceStyle(el)?.display !== 'table-header-group')
+        return false;
+    for (let s = el.previousElementSibling; s; s = s.previousElementSibling)
+        if (/^table-row(-group)?$/.test(sourceStyle(s)?.display ?? ''))
+            return true;
+    return false;
+}
 /**
  * The computed style of the box an author declared — the clone's registered source, or the element itself where it is live and connected. `null` for everything else, which is the honest answer rather than a default: a detached clone with no registration is a `<br>` or a filler span the Compositor inserted, and an element nobody declared has no declaration to read.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beltype/cicero",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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",