@peripheries/renderer 0.17.0 → 0.20.0

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

@@ -0,0 +1,427 @@
+/**
+ * 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;
+    height: number;
+    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: () => {
+    breakInside?: string;
+    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;
+}): {
+    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;
+} | undefined, margins: {
+    top?: string;
+    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?: {
+    measure?: string;
+    rail?: {
+        placement?: string;
+        width?: string;
+        gutter?: string;
+    };
+}): PaperGeometryPx | null;
+export {};

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

@@ -0,0 +1,231 @@
+/**
+ * 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;