@peripheries/renderer 0.23.0 → 0.24.0

package/dist/types/print/page-map.d.ts

@@ -1,104 +1,5 @@
-/**
- * Reading measured blocks out of the rendered DOM, for `paginate()`.
- *
- * ── Why this is separate from the packer AND from the hook ──────────────────
- *
- * `paginate()` is arithmetic and pure. The React hook owns re-measurement and
- * lifecycle. This middle layer is the part that touches the DOM, and it is a
- * plain function taking injected measurers so it can be tested without a
- * browser — jsdom reports every height as 0, so a collector that called
- * `getBoundingClientRect` directly would be untestable in exactly the way that
- * matters.
- *
- * ── The unit of pagination is a BAND, not a cell ───────────────────────────
- *
- * This module's first version treated a document as a vertical stack of cells,
- * one `[data-cell-id]` per block. That is wrong, and it was wrong in a way that
- * produced credible numbers for a whole day.
- *
- * A `/doc` page is a **12-column grid**. Cells sit side by side: two `span 6`
- * profile cards share one row, a `span 8` chart shares a row with a `span 4`
- * stat strip. You cannot put a page break between two cells that are beside
- * each other — the break goes between grid ROWS. So the unit is a *band*: a
- * maximal set of cells whose vertical extents connect.
- *
- * **How many bands the proof document has depends on HOW the width is narrowed**,
- * and getting that wrong is the third measurement error of this same family:
- *
- * - Narrow the grid element alone and it stays a 12-column grid, because the
- *   `container-type: inline-size` ancestor is still 976px wide and the container
- *   query has not fired. Six pairs share rows → **27 bands**.
- * - Narrow that ANCESTOR — which is what layout mode does, and what printing
- *   does to the whole page — and the query fires, the template collapses to a
- *   single 672px column, every `span` becomes full width, and nothing shares a
- *   row → **33 bands**.
- *
- * The second is the truth about paper. A hand-measurement that sets a width on
- * the grid and reads the result is measuring a layout that will never print.
- * The banding code stays necessary regardless: a wider sheet, a landscape
- * profile, or a template whose query threshold sits below 672px all keep the
- * multi-column layout, and then a break between two side-by-side cells is
- * exactly the error this prevents.
- *
- * Two further corrections came out of the same measurement, both from picking
- * the wrong element:
- *
- * 1. **The fragmentation box is the cell's PARENT.** `[data-cell-id]` is the
- *    `.cell-renderer` inside the grid item; the grid item is the element
- *    `CellsRenderer` puts `break-inside`/`break-after` on, and the element the
- *    browser would actually split. Measuring the child loses the constraint on
- *    **28 of 33 cells** and gets a different height on **10 of 33** (a
- *    `SectionHeader` cell is 104px, its grid item 152px).
- * 2. **Constraints are read from computed style, not resolved by name.** The
- *    renderer has already resolved `@printPolicy` through the bundle cascade
- *    and written it onto that grid item. Re-resolving it here would be a second
- *    implementation of a lookup that can disagree with the first; reading the
- *    computed value cannot.
- *
- * ── `reconciles` is the check that would have caught all of this ────────────
- *
- * Everything above the first band, plus every band, plus the gaps between them,
- * must equal the measured height of the container. The old per-cell model
- * summed to 9,973px against a 9,629px container and nothing in the code
- * noticed; the first version of THIS model read `row-gap` off the wrong
- * element, lost all 32 gaps, and came 512px short — caught by the check on its
- * first run against a real document rather than by a third day of measuring.
- *
- * So the map now carries that arithmetic as a field. A map that does not
- * reconcile is not slightly wrong — it is a different document — and a consumer
- * must be able to refuse it rather than draw page edges from it.
- *
- * ── The width problem, and why the map admits it ────────────────────────────
- *
- * A page map is only true at the width it was measured at. Measured on the
- * proof document: at the screen's 976px the document has **no** unpageable blocks;
- * with the grid constrained to the true 672px, `ReportCoverHero` becomes
- * unpageable. A screen-width map is not a slightly-wrong print map — it is
- * missing the overflows.
- *
- * Forcing print width on a document someone is reading reflows it under them,
- * so this module does **not** do it: it measures where the DOM already is and
- * reports `approximate` when that is not print width. Exact maps come from a
- * caller already laying out at print width — layout mode.
- *
- * ── What this still cannot see ─────────────────────────────────────────────
- *
- * `@media print` rules are inert unless the browser is actually printing.
- * Constraining a container to 672px does not activate them. So a
- * map taken this way reflects screen-media geometry at paper width, which is
- * close but not identical — on the proof cover the difference was 261px until the
- * print rule stopped being defeated by an inline style. A consumer that needs
- * the print-media truth needs real print emulation, which this module has no
- * way to request.
- *
- * Charts also settle asynchronously, and measuring before they draw yields
- * heights no assertion here can catch. What this offers against that is
- * `zeroHeightIds` — the boxes that measured 0, the observable signature of "not
- * yet rendered". Re-measurement on mutation belongs to the hook.
- */
 import { type PrintConstraints } from './print-policy.js';
 import type { PaginationBlock } from './paginate.js';
-/** The part of a DOMRect this module needs, in a common coordinate space. */
 export interface ElementRect {
     top: number;
     bottom: number;
@@ -106,175 +7,43 @@ export interface ElementRect {
     width: number;
 }
 export interface CollectOptions {
-    /**
-     * Rect of an element. Injected so this is testable: pass
-     * `(el) => el.getBoundingClientRect()` in a browser.
-     *
-     * `top` and `bottom` must be in one coordinate space across all calls —
-     * banding compares them against each other. Viewport coordinates are fine.
-     */
     measureRect: (el: Element) => ElementRect;
-    /**
-     * The fragmentation properties the browser has resolved for this element.
-     * Injected for the same reason as `measureRect`, and because a real
-     * implementation needs `getComputedStyle`. See `constraintsFromComputedStyle`.
-     */
     readConstraints?: (el: Element) => PrintConstraints | undefined;
-    /**
-     * The fragmentation box for a matched cell. Defaults to the cell's parent,
-     * which is the grid item — see the header. Overridable because a caller with
-     * a different cell wrapper should not have to reimplement banding.
-     */
     boxFor?: (cell: Element) => Element;
-    /** Selector for a cell. Defaults to the host's cell marker. */
     selector?: string;
-    /**
-     * Does this cell OPEN a section, and what is the section called?
-     *
-     * Returns the title, or `undefined` for a cell that opens nothing. The
-     * section's id is the cell's id, so a caller never invents one.
-     *
-     * ── Why this is injected, and why it lives HERE rather than beside the ────
-     * ── running header, which also needs it ──────────────────────────────────
-     *
-     * Because it needs to be inferred exactly once. Two places already wanted
-     * "which rows are section headings": the running header, and now the
-     * specification's pagination rule 01. Two inferences of one fact drift, and
-     * this project has spent a week on exactly that failure in three other
-     * shapes. So the walk that already visits every cell answers it, and both
-     * consumers read the answer.
-     *
-     * Injected rather than hard-coded because the signal is not settled.
-     * Today it is FEC's own `break-after: avoid` plus a heading element, which
-     * selects exactly the seven `*-header` rows on the proof document. If the bundle
-     * adopts the specification's stable section ids it becomes a
-     * config read, and only the caller changes.
-     */
     sectionStart?: (cell: Element, constraints: PrintConstraints | undefined) => string | undefined;
-    /**
-     * Does a DELIBERATE blank page precede this cell?
-     *
-     * Injected like `sectionStart`, and for the same reason: it comes from the
-     * page config, which this module has no business reading. `paginate` needs it
-     * because a blank page changes the page count and therefore where every
-     * subsequent break falls — it cannot be added after the map the way the
-     * hover controls are.
-     */
     blankBefore?: (cellId: string) => boolean;
 }
-/** A row of the document: the cells that share it, and its geometry. */
 export interface Band {
-    /** Member cell ids joined by `+`. Stable, and readable in a page listing. */
     id: string;
     members: string[];
-    /** Offset of the band's top from the container's top, in CSS px. */
     topPx: number;
-    /** Band height. The row gap is NOT included — see `blocks`. */
     heightPx: number;
     constraints?: PrintConstraints;
 }
 export interface CollectedBlocks {
-    /**
-     * One block per band, in reading order, with the row gap folded into every
-     * band but the last — a gap sits below its band in the flow.
-     */
     blocks: PaginationBlock[];
     bands: Band[];
-    /**
-     * The sections found, in document order — `cellId` is the row that opens the
-     * section and doubles as its id.
-     *
-     * Structurally a `SectionMarker` (`running-header.ts`), and deliberately not
-     * imported as one: that module imports `Band` from here, and a type import
-     * back would make the pair circular for the sake of a two-field object.
-     */
     sections: Array<{
         cellId: string;
         title: string;
     }>;
-    /** Width the measurement ran at, in CSS px. The map is only true here. */
     measuredWidthPx: number;
-    /**
-     * Set when `measuredWidthPx` is not the print text-block width, so the map is
-     * indicative rather than exact.
-     */
     approximate?: boolean;
-    /** Boxes whose measured height was 0 — usually "not yet rendered". */
     zeroHeightIds: string[];
-    /**
-     * Does the band model account for the container's height?
-     *
-     * **False means the map is describing a different document** and a consumer
-     * must refuse to present it as precise. This is the assertion whose absence
-     * let a per-cell model over-count the proof document by 344px for a day.
-     */
     reconciles: boolean;
     reconciliation: {
-        /** Anything above the first band, plus every band and the gaps between. */
         modelPx: number;
-        /** The container's own measured height. */
         containerPx: number;
-        /** Space above the first band — unmeasured, and it displaces every edge. */
         leadingPx: number;
     };
 }
-/**
- * Read the bands of a container.
- *
- * @param root         The element that lays the cells out.
- * @param printWidthPx The print text-block width, for the accuracy comparison.
- */
 export declare function collectBlocks(root: Element | null, printWidthPx: number, { measureRect, readConstraints, boxFor, selector, sectionStart, blankBefore }: CollectOptions): CollectedBlocks;
-/**
- * `readConstraints` from a `CSSStyleDeclaration` — what the browser resolved.
- *
- * **Only PROHIBITIONS and FORCED breaks are read. Never a permission.**
- *
- * `orphans` and `widows` were already excluded, and the reason given was right:
- * their computed value is always present (`2` in Chrome, declared or not), so a
- * computed style cannot distinguish "this component declared a threshold" from
- * "nobody has ever mentioned this".
- *
- * What this function's own header then got wrong, for a fortnight: it claimed
- * `break-*` do not have that problem, because their initial value `auto` is
- * *"both the absence of a declaration and a true statement about what the
- * browser will do"*. The second half is true and the first half is the bug.
- * `mayNotSplit` does not ask what the browser will do — it asks **what was
- * declared**, and reads an explicit `auto` as PERMISSION to split. Its own
- * header states the rule: *"absence is not permission"*.
- *
- * So every element on every document reported `breakInside: 'auto'`, because
- * that is what an unstyled element computes to, and the packer read every one
- * of them as a component that had asked to be splittable. The conservative
- * default for the 44 untagged components — *"untagged implies unbreakable"* —
- * was unreachable through this path from the day it was written.
- *
- * The declaration now travels as an attribute the renderer stamps
- * (`PRINT_POLICY_ATTR`), and this function is the fallback for a DOM nobody
- * stamped. In that role it must be conservative in the same direction as
- * absence: `avoid` is a prohibition and `page` an instruction, and both are
- * safe to believe from a computed value because neither is what an element gets
- * for free.
- */
 export declare function constraintsFromComputedStyle(cs: {
     breakInside?: string;
     breakAfter?: string;
     breakBefore?: string;
 }): PrintConstraints | undefined;
-/**
- * The constraints on a fragmentation box: the DECLARATION where there is one,
- * the computed style where there is not.
- *
- * Not a compose of the two. The attribute already carries the composed
- * intrinsic-plus-extrinsic answer — the renderer composed it before writing it
- * — and folding the computed style back in would re-add the `auto` this exists
- * to keep out.
- *
- * The fallback matters and is not defensive padding: `/portal/page/[pageId]`,
- * a print harness and any future headless render reach `collectBlocks` through
- * elements these renderers did not write, and those keep the behaviour they
- * have always had.
- */
 export declare function constraintsFromBox(el: {
     getAttribute(name: string): string | null;
 }, computed: () => {
@@ -282,18 +51,9 @@ export declare function constraintsFromBox(el: {
     breakAfter?: string;
     breakBefore?: string;
 }): PrintConstraints | undefined;
-/** What `forcedBreaksWithin` needs of an element: its element children, in order. */
 type BoxNode = {
     children: ArrayLike<BoxNode>;
 };
-/**
- * A forced break a box's content asks for at its edges (CSS Fragmentation §3.1: a `break-before`
- * on a box's first in-flow child, and a `break-after` on its last, propagate to the box). A
- * component's own page break (core's `PageBreak` is `break-after: page` on its root) sits
- * inside the cell's frame, so the frame's computed style doesn't show it, but Chrome breaks
- * there. Walks the first-child chain for `before` and the last-child chain for `after`; only
- * forced breaks (`page`) propagate.
- */
 export declare function forcedBreaksWithin<T extends BoxNode>(box: T, styleOf: (el: T) => {
     breakAfter?: string;
     breakBefore?: string;
@@ -301,107 +61,20 @@ export declare function forcedBreaksWithin<T extends BoxNode>(box: T, styleOf: (
     breakBefore?: 'page';
     breakAfter?: 'page';
 };
-/**
- * The constraints on a box with the forced breaks its content propagates (forcedBreaksWithin)
- * folded in: a forced break wins over `avoid` on the same edge, as it does in CSS.
- */
 export declare function withForcedBreaks(constraints: PrintConstraints | undefined, forced: {
     breakBefore?: 'page';
     breakAfter?: 'page';
 }): PrintConstraints | undefined;
-/**
- * Build a `readConstraints` from a component-name → policy lookup.
- *
- * The **contract-derived** path, kept for a caller that has no rendered DOM to
- * read (a headless render service resolving policy before layout). Prefer
- * `constraintsFromComputedStyle` where the document is on screen: the renderer
- * has already done this resolution and the DOM cannot disagree with itself.
- *
- * `composeConstraints` is called even for a single link, deliberately: it
- * promotes `atomic` to `breakInside: 'avoid'`, and the render path's failure to
- * call it is exactly how `atomic` once emitted no CSS at all.
- */
 export declare function constraintsResolver(policyFor: (componentName: string) => PrintConstraints | undefined): (componentName: string | null) => PrintConstraints | undefined;
-/**
- * The paper geometry a page map needs, in CSS pixels.
- *
- * The document profile stores lengths as CSS strings (`'8.5in'`, `'0.75in'`) —
- * the right shape for a stylesheet and useless to a packer that works in
- * numbers. This converts once, at the boundary.
- *
- * **Only absolute units are accepted.** `em`, `%` and `vh` are all legal CSS
- * and none of them has a fixed pixel value on paper, so accepting them would
- * mean converting against a font size or a viewport that has nothing to do with
- * the sheet. An unparseable length yields `null` rather than a plausible
- * default: the geometry falling back silently to US Letter is how a document
- * configured for something else would paginate correctly and print wrong.
- */
 export interface PaperGeometryPx {
-    /** Usable height per page — sheet height minus top and bottom margins. */
     textBlockPx: number;
-    /**
-     * The width the CONTENT column lays out at — the profile's `measure` where it
-     * declares one, otherwise the full page box.
-     *
-     * ── Why this is the measure and not sheet-minus-margins ──────────────────
-     *
-     * It was sheet-minus-margins, and the component repo measured what that costs on a
-     * profile whose measure is narrower than its page box. The bundle's `instrument`
-     * states its page as a single sum:
-     *
-     *   1.25in margin · 4.50in measure · 0.25in gutter · 1.50in marginalia · 1.00in margin
-     *
-     * The page box is `8.5 − 1.25 − 1.00 = 6.25in`, and the text column is
-     * specified at **4.50in**. Laying content out across the whole box set it
-     * **39% over measure** and never established the marginalia column at all.
-     *
-     * **`workbook` and `report` are unaffected, and that is arithmetic rather
-     * than a special case:** workbook's measure is `6.85in` and its page box is
-     * `8.5 − 0.95 − 0.70 = 6.85in`. Identical. `report` extends workbook. So
-     * reading the measure changes nothing for either, which is what the
-     * component repo asked for.
-     */
     printWidthPx: number;
-    /**
-     * The full width between the left and right margins.
-     *
-     * Equal to `printWidthPx` unless the profile declares a narrower measure. The
-     * content column occupies `printWidthPx` of it and the remainder is the
-     * gutter plus the marginalia column.
-     */
     pageBoxWidthPx: number;
-    /** The marginalia column reserved beside the content. 0 when there is none. */
     railPx: number;
-    /** Space between the content column and the marginalia column. 0 when none. */
     gutterPx: number;
-    /**
-     * Does the profile's own column arithmetic add up?
-     *
-     * `printWidthPx + gutterPx + railPx` against `pageBoxWidthPx`. False means the
-     * profile's stated sum disagrees with its own sheet and margins, and the
-     * caller is reserving a column from a page that has no room for it.
-     *
-     * Reported rather than clamped, for `reconciles`' reason: a geometry that
-     * does not add up is not slightly wrong, it is describing a different page,
-     * and silently absorbing the difference is how a wrong number survives.
-     * `true` when no rail column is declared — there is nothing to add up.
-     */
     columnsReconcile: boolean;
 }
-/**
- * Parse one CSS absolute length to px, or `null`.
- *
- * Returns `null` for a relative unit, a unitless number that is not zero, or
- * anything unparseable. `0` alone is legal CSS with no unit and means zero.
- */
 export declare function cssLengthToPx(value: string | undefined | null): number | null;
-/**
- * Compute the usable text block from a profile's sheet and margins.
- *
- * Returns `null` when any length is unparseable or the result is not a usable
- * box — the caller then has no geometry, which `paginate` reports as
- * `degenerateGeometry` rather than guessing.
- */
 export declare function paperGeometryPx(sheet: {
     width?: string;
     height?: string;
@@ -410,13 +83,7 @@ export declare function paperGeometryPx(sheet: {
     right?: string;
     bottom?: string;
     left?: string;
-} | undefined, 
-/**
- * The profile's column declarations. Optional, and absent means "the content
- * fills the page box", which is what every profile did before columns existed and
- * what the host default still does.
- */
-columns?: {
+} | undefined, columns?: {
     measure?: string;
     rail?: {
         placement?: string;

package/dist/types/print/paginate.d.ts

@@ -1,231 +1,41 @@
-/**
- * Page boundaries, computed by the host.
- *
- * ── Why the host paginates at all ───────────────────────────────────────────
- *
- * Layers 1–3 of print mode hand rules to the browser and let it paginate:
- * `@page` geometry from the document profile, `@printPolicy` from each
- * component onto the cell wrapper, `node.print` from the page author. That is
- * enough to *print* well and useless for anything else, because **the browser
- * never reports where the pages fell.** Approved by the repo owner 2026-09-03
- * (*"2. Yes to pagination"*).
- *
- * Everything the owner asked for beyond printing needs page boundaries as data:
- * showing page edges on screen, a layout mode that moves a block between pages,
- * knowing which page the cursor is on, and reflowing when a chart no longer
- * fits. None of it is expressible against a browser that paginates privately.
- *
- * ── The split this file exists to make ─────────────────────────────────────
- *
- * **Measuring is DOM work; packing is arithmetic.** They are separated because
- * only one of them can be tested without a browser, and the browser run is
- * exactly where a regression goes unnoticed — the spike that produced the
- * numbers below was a one-off `evaluate_script` whose result no CI could
- * reproduce. So this module takes measured heights as *input* and is pure.
- *
- * ── Measured on the proof document, 2026-09-03 ──────────────────────────────
- *
- * 33 cells, US Letter, 0.75in margins, 96 CSS px/in → text block **912 × 672**.
- * Heights measured with the `display: grid` container constrained to 672px:
- *
- *   total content            9,973 px
- *   perfect packing          10.94 pages  (the floor)
- *   every block atomic       14 pages     (the conservative worst case)
- *   blocks that cannot fit   2  — `ReportCoverHero` 1,150 px,
- *                                 `DecumulationSimulator` 952 px
- *
- * **The first version of these numbers was measured wrong** and was corrected:
- * the width was applied to `firstCell.parentElement`, which is the
- * first cell's own wrapper, so one of 33 cells reflowed. That produced 9,215 px,
- * 10.1 pages and a single overflow — and a conclusion that content barely grows
- * at print width, drawn from the one element that had actually been narrowed.
- * Twelve cells change; the document grows 13.4%.
- *
- * Two consequences that shape the rules below:
- *
- * 1. **The 3-page spread between 10.94 and 14 is what accurate `@printPolicy`
- *    tagging buys.** So `breakInside: 'auto'` has to be honoured as a positive
- *    assertion, not folded into the default — otherwise the packer cannot
- *    realise the tagging it is being given.
- * 2. **A block can exceed the page.** `ReportCoverHero` at 1,150px does not fit
- *    on its own page, so "give an unplaceable atomic block its own page" is not
- *    a complete answer and this module must be able to say *"this does not fit"*
- *    rather than silently clipping it.
- */
 import type { PrintConstraints } from './print-policy.js';
-/** One measured, packable thing. Usually a cell; the packer does not care. */
 export interface PaginationBlock {
     id: string;
-    /** Rendered height at the PRINT text-block width, not the screen width. */
     heightPx: number;
-    /**
-     * The block's effective constraints — already composed down its nesting
-     * chain by `composeConstraints`. This module does not compose: composition is
-     * a property of the tree and packing is a property of the sequence, and
-     * conflating them is how `atomic` came to mean two things.
-     */
     constraints?: PrintConstraints;
-    /**
-     * A DELIBERATE blank page immediately before this block.
-     *
-     * Distinct from the empty page `breakPage` refuses to emit: that guard exists
-     * because an ACCIDENTAL blank sheet is a defect. This one is asked for, so it
-     * is carried as data and emitted as its own page with no blocks.
-     */
     blankPageBefore?: boolean;
-    /**
-     * The section this block belongs to, for the specification's pagination
-     * rule 01. Blocks sharing an id must be CONTIGUOUS — a section is a run of
-     * the document, not a tag scattered through it.
-     *
-     * Optional, and absent means "no section": rule 01 simply does not fire, and
-     * a document with no sections paginates exactly as it did before. That is the
-     * right default while the host still INFERS sections from the DOM rather than
-     * reading declared ids.
-     */
     sectionId?: string;
 }
 export interface PaginateOptions {
-    /** Usable height per page: sheet height minus top and bottom margins. */
     textBlockPx: number;
-    /**
-     * How far an over-tall block may be squeezed to keep its heading with it.
-     *
-     * When a block too tall for a page is preceded by a `break-after: avoid`
-     * heading, the heading is brought onto its page and the block gets what is
-     * left. That only helps if what is left is still enough — below this ratio
-     * the heading is left behind instead, because a stranded heading is a
-     * typographic fault and an illegible chart is a useless one.
-     *
-     * 0.6 by default, matching `buildPrintLayout`'s `scaleFloor`: this decides
-     * whether the row CAN be scaled and that decides how far. Two numbers that
-     * must agree, and the default is the same literal in both — if you change one,
-     * pass the other.
-     */
     keepWithNextScaleFloor?: number;
-    /**
-     * Rule 01: *"A section that fills half a page or more starts a new page."*
-     *
-     * The specification's own words (`Document System.pdf` p11), and its own
-     * reason: *"Members flip and file by section, and a section that begins
-     * mid-page is hard to find again."* It is the one pagination rule that is
-     * unambiguously the host's — a component cannot know what half a page is, and
-     * neither can a page config; only the packer holds the geometry and the
-     * measured height of the run.
-     *
-     * Expressed as a RATIO rather than the literal `0.5`, because the threshold
-     * is a judgement about findability and not a fact about paper. `0` disables
-     * the rule; `1` would mean "only a section that fills a whole page".
-     *
-     * **This is the one number in this file that came from the specification
-     * rather than from a measurement**, which is worth saying out loud: if it
-     * turns out to be wrong, it is wrong upstream and the fix is a conversation,
-     * not a tuning pass.
-     */
     sectionFillRatio?: number;
 }
 export interface PlacedBlock {
     id: string;
     heightPx: number;
-    /**
-     * This entry is the CONTINUATION of a block that began on an earlier page,
-     * not a second block with the same id. `heightPx` here is the portion on
-     * this page, so summing a page's `heightPx` gives its real occupancy.
-     */
     continues?: boolean;
-    /**
-     * The block's FULL measured height, present only when it spans pages.
-     *
-     * `heightPx` is always this page's share, so the invariant *"a page's block
-     * heights sum to its `usedPx`"* holds everywhere. Without this the whole size
-     * would be unrecoverable from the map.
-     */
     totalHeightPx?: number;
-    /**
-     * True when the block is taller than the space remaining and is *permitted*
-     * to split, so it continues onto the following page.
-     *
-     * **The host does not know WHERE inside the block the break falls** — that is
-     * the browser's line-breaking, and this packer sees an opaque height. So a
-     * spanning block reports which pages it touches and no more. A page map that
-     * claimed a split position it cannot compute would be worse than one that
-     * admits the gap.
-     */
     spansPages?: number;
 }
 export interface PaginatedPage {
-    /**
-     * This page is a deliberate blank — no blocks, and it prints the notice.
-     *
-     * The ONLY page in a map that may have an empty `blocks` array. Every other
-     * empty page is a bug, which is why this is a positive marker rather than a
-     * count of the blocks.
-     */
     blank?: boolean;
-    /** 1-based, because it is a page number shown to a person. */
     index: number;
     blocks: PlacedBlock[];
     usedPx: number;
-    /** Never negative: a page that overflows reports the overflow separately. */
     wastePx: number;
 }
 export interface PaginationOverflow {
     id: string;
     heightPx: number;
     textBlockPx: number;
-    /** How much taller than a whole empty page this block is. */
     excessPx: number;
-    /**
-     * The height this block actually gets, which is NOT always a whole page.
-     *
-     * A block too tall for a page is given its own page — unless it was preceded
-     * by a heading that declares `break-after: avoid`, in which case the heading
-     * comes with it and the block gets what is left. The consumer that scales the
-     * row has to scale it to THIS, not to the sheet, or it will scale to a height
-     * that its heading is already occupying part of.
-     */
     availablePx: number;
 }
 export interface PageMap {
     pages: PaginatedPage[];
-    /**
-     * Blocks that cannot fit a page even alone AND are not permitted to split.
-     *
-     * Reported rather than thrown, and rather than clipped. `ReportCoverHero` is
-     * a real instance (1,150px against 912px), and the only useful thing to do
-     * with it is tell somebody — the fix is a tagging or component decision, not
-     * a packing one.
-     */
     overflows: PaginationOverflow[];
-    /**
-     * Total content height ÷ page height. A lower bound, and **unreachable in
-     * principle** — do not read it as a target.
-     *
-     * It assumes blocks may be packed in any order. A document may not: **page
-     * order is reading order**, so a chart cannot be moved ahead of its heading
-     * to fill a gap. For a fixed sequence of unsplittable blocks, placing each
-     * one on the current page if it fits and starting a new page otherwise
-     * already minimises the page count — so the greedy pass in `paginate` is
-     * optimal, and the gap between it and `idealPages` is not slack a better
-     * algorithm can recover.
-     *
-     * On the proof document that gap is **14 vs 10.94**, and I twice described it as
-     * something tagging or better packing would close.
-     * Neither can. The only levers are fewer atomic blocks (a tagging decision,
-     * now made and exhausted — it bought zero pages), scaling a block to fit (a
-     * component decision), or less content.
-     *
-     * Kept because it is a useful *diagnostic*: a large gap says the document is
-     * made of big indivisible blocks, which is a content fact worth surfacing in
-     * layout mode. It is not a performance figure.
-     */
     idealPages: number;
-    /**
-     * Set when `textBlockPx` was not a usable page height, so nothing was
-     * paginated and every block sits on one page. Present rather than silent
-     * because a one-page map is otherwise indistinguishable from a short
-     * document.
-     */
     degenerateGeometry?: boolean;
 }
 export declare function paginate(blocks: readonly PaginationBlock[], { textBlockPx, keepWithNextScaleFloor, sectionFillRatio }: PaginateOptions): PageMap;