@peripheries/renderer 0.23.0 → 0.24.0

package/dist/types/forms/model.d.ts

@@ -1,43 +1,27 @@
 import { type Condition } from './conditions.js';
-/**
- * A form as the forms runtime reads it (forms-as-pages.md §4.2–§4.3): steps, an overlay on the
- * page's flat cells, each holding items (cells) and the questions they ask. Where it comes from
- * is an adapter's business: a page's `layout.steps` (`fromPageSteps`) or, until forms are pages
- * (SCH M3b), the legacy definition (the host's adapter). Pure: no React, no network.
- */
 export type FormQuestion = {
-    /** The answer's key: what conditions, progress and the port name. */
     key: string;
     label: string;
     required: boolean;
-    /** Enter may move on from it (forms-as-pages.md §4.3): a one-line question. */
     singleLine: boolean;
     when?: Condition | null;
-    /** The question node an answer is saved against (answer_save's p_question_node), when the form is a page. */
     node?: string;
-    /** How to ask it, from the question node's state: what a cell renders its control from. */
     definition?: FormQuestionDefinition;
 };
-/**
- * A question's definition as its node's state holds it (forms-as-pages.md §4.2): the control's
- * type, its options, validation and help. The runtime passes it through to the cell untouched.
- */
 export type FormQuestionDefinition = {
     type: string;
-    options?: unknown[];
-    validation?: Record<string, unknown>;
-    description?: string;
-    helpText?: string;
+    options?: unknown[] | null;
+    validation?: Record<string, unknown> | null;
+    description?: string | null;
+    helpText?: string | null;
 };
 export type FormItemKind = 'question' | 'content' | 'document' | 'review' | 'upload' | 'other';
-/** One cell of a step: its questions, if any. */
 export type FormItem = {
     id: string;
     kind: FormItemKind;
     questions: FormQuestion[];
     when?: Condition | null;
 };
-/** `label`: an authored word for the step shown in place of its derived kind's (advisor review, status); the kind stays derived. */
 export type FormStep = {
     id: string;
     title: string;
@@ -54,50 +38,32 @@ export type FormModel = {
     title: string;
     chapters: FormChapter[];
     steps: FormStep[];
-    /** On submit: `warn` lists what's missing and submits; `block` refuses until it's answered (owner, Q-F7; default warn). */
     submitRequired: 'warn' | 'block';
-    /** Back is offered (the template's `allow_back`, default true). */
     allowBack: boolean;
-    /** The form takes a submission (false for a legacy form, which has none); default true. */
     submittable?: boolean;
 };
-/** A step's kind, derived from its cells (§4.2): for labels and progress. */
 export type StepKind = 'answer' | 'read' | 'review' | 'upload' | 'submit';
-/** Where a submission stands (the `submission` layer's status, schema-g2.md §2.7). */
 export type SubmissionStatus = 'in_progress' | 'submitted' | 'changes_requested' | 'completed';
 export type DisplayMode = 'step' | 'question';
-/** Steps, cells and questions whose conditions hold for these answers; a step left with nothing visible is skipped. */
 export declare function visibleSteps(model: FormModel, values: Record<string, unknown>): FormStep[];
 export declare const questionsOf: (step: FormStep) => FormQuestion[];
 export declare function stepKind(step: FormStep, isLast: boolean): StepKind;
-/** Where a person is: a step, and in question mode one of its questions. */
 export type Position = {
     step: string;
     question?: string;
 };
-/** The places Next and Back move through: a step each, or in question mode each question (a step with none counts once). */
 export declare function positionsOf(steps: FormStep[], mode: DisplayMode): Position[];
-/** A position in these steps: the same, else its step's first, else the first. */
 export declare function settle(steps: FormStep[], mode: DisplayMode, at: Position | null): Position | null;
-/** One move on, or back; null at either end. A move across a step boundary is a step change (it pushes history). */
 export declare function move(steps: FormStep[], mode: DisplayMode, at: Position, by: 1 | -1): Position | null;
-/** The contents click (§4.3): that step, in question mode at its first unanswered question, else its first. */
 export declare function goTo(steps: FormStep[], mode: DisplayMode, stepId: string, values: Record<string, unknown>): Position | null;
-/** A question's place (§4.3 question mode, `?question=`): its step, settled for the mode. Null when no visible step has it. */
 export declare function goToQuestion(steps: FormStep[], mode: DisplayMode, key: string): Position | null;
-/** Enter moves on (§4.3): a step with exactly one visible one-line question, or a one-line question in question mode. */
 export declare function enterAdvances(step: FormStep, mode: DisplayMode, question?: string): boolean;
-/** Required questions not yet answered, in order: in one step, or (no step) in the whole form. */
 export declare function missing(steps: FormStep[], values: Record<string, unknown>, stepId?: string): FormQuestion[];
 export type StepProgress = {
     answered: number;
     total: number;
     complete: boolean;
 };
-/**
- * Progress (§4.3): overall, required answered of required visible; per step, answered of visible
- * questions, complete when all its required ones are answered. A read step counts once visited.
- */
 export declare function progress(steps: FormStep[], values: Record<string, unknown>, visited: ReadonlySet<string>): {
     answered: number;
     required: number;
@@ -108,27 +74,17 @@ export declare function progress(steps: FormStep[], values: Record<string, unkno
     };
     perStep: Record<string, StepProgress>;
 };
-/** Answers can't change: submitted or completed (Edit answers reopens a submitted form). */
 export declare const isReadOnlyStatus: (status: SubmissionStatus | null | undefined) => status is "submitted" | "completed";
-/** Step mode on desktop, one question at a time on a phone (§4.3). */
 export declare const defaultMode: (phone: boolean) => DisplayMode;
-/**
- * Steps from a page's overlay (§4.2): `layout.steps: [{ id, title, chapter?, cell_ids, when? }]`
- * and `layout.chapters`, each cell's questions from `questionsOfCell` (the page knows its
- * question cells' bindings). Cells the overlay doesn't name aren't in the form.
- */
 export declare function fromPageSteps(page: {
     name?: string | null;
     layout?: Record<string, unknown> | null;
 }, itemOf: (cellId: string) => FormItem | null): FormModel;
-/** A deep link (§4.3, the URL contract `?mode=&page=&section=&question=`): `section` a step id, `page` a chapter id, `question` a question key. */
 export type FormLink = {
     mode?: 'question';
     page?: string;
     section?: string;
     question?: string;
 };
-/** Where a link lands: the step it names (and question), else its chapter's first step, else the first. */
 export declare function positionFromLink(steps: FormStep[], mode: DisplayMode, link: FormLink): Position | null;
-/** The link to a position, as an assistant reply carries it. */
 export declare function linkTo(steps: FormStep[], mode: DisplayMode, at: Position): FormLink;

package/dist/types/forms/port.d.ts

@@ -1,11 +1,4 @@
-/**
- * How the forms runtime saves (joint-releases.md §2.4): an injected port, so the runtime never
- * names a table or a function. The legacy adapter (the host's, over form_answer_save) implements
- * it in G2; answer_save, form_submit, form_visit and form_reopen (SCH M3b; schema-g2.md §2.7) in
- * G3, with no renderer release. A refusal is a code, never a throw, so it's said in words like an edit's.
- */
 import type { FileAnswer } from '@peripheries/runtime';
-/** The codes a port answers with (schema-g2.md §2.7), and NETWORK when the call didn't arrive. */
 export type FormsRefusal = 'CONFLICT' | 'ANSWER_TYPE' | 'ANSWER_OPTION' | 'ANSWER_REQUIRED' | 'ANSWER_FILE_PATH' | 'ANSWER_VALIDATION' | 'FORM_INCOMPLETE' | 'FORM_NOT_OPEN' | 'FORM_COMPLETED' | 'FORM_STEP_UNKNOWN' | 'NO_CAPABILITY' | 'NETWORK' | (string & {});
 export type FormsResult<T extends object = object> = ({
     ok: true;
@@ -15,11 +8,9 @@ export type FormsResult<T extends object = object> = ({
     message?: string;
     detail?: unknown;
 };
-/** A file to upload for an answer: any Blob with a name (a File in the browser). */
 export type FileToUpload = Blob & {
     readonly name: string;
 };
-/** One answer to save: its key, the question node when the form is a page, and the state it replaces. */
 export type AnswerToSave = {
     key: string;
     node?: string;
@@ -27,31 +18,19 @@ export type AnswerToSave = {
     expectedStateId?: string | null;
 };
 export interface FormsPort {
-    /** Save one answer; the state it wrote is what the next save of that key expects (CONFLICT otherwise). */
     save(answer: AnswerToSave): Promise<FormsResult<{
         stateId?: string | null;
     }>>;
-    /** Submit: `missing` is what the runtime found unanswered (recorded under `warn`; `block` refuses FORM_INCOMPLETE). */
     submit(input: {
         missing: string[];
     }): Promise<FormsResult<{
         status: 'submitted';
         missing: string[];
     }>>;
-    /**
-     * Edit answers (forms-as-pages.md §4.3): a submitted form back to `in_progress`, recorded in the
-     * submission. Refused once staff have completed it (FORM_COMPLETED).
-     */
     reopen(): Promise<FormsResult<{
         status: 'in_progress';
     }>>;
-    /** A step was seen (`submission.visited_steps`): read steps count once visited. A repeat is a no-op. */
     visit(stepId: string): Promise<FormsResult>;
-    /**
-     * Upload a file for a file question, as the viewer: the adapter stores it where answer_save
-     * accepts it and returns the answer to save (`{ v: 1, file }`); saving it is `save`'s. Absent
-     * where the host takes no files.
-     */
     upload?(input: {
         key: string;
         node?: string;
@@ -62,7 +41,6 @@ export interface FormsPort {
             file: FileAnswer;
         };
     }>>;
-    /** A short-lived URL to open a saved file answer, as the viewer (storage decides who may). */
     openFile?(file: FileAnswer): Promise<FormsResult<{
         url: string;
     }>>;

package/dist/types/forms/section.d.ts

@@ -0,0 +1,22 @@
+import type { Condition } from './conditions.js';
+import type { FormQuestionDefinition } from './model.js';
+export type FormContentBlock = {
+    id: string;
+    type: string;
+    when?: Condition | null;
+    [prop: string]: unknown;
+};
+export type FormSection = {
+    id: string;
+    sectionId: string;
+    title: string;
+    description?: string;
+    sectionType?: string;
+    questions: Array<{
+        key: string;
+        label: string;
+        required: boolean;
+        definition: FormQuestionDefinition | null;
+    }>;
+    content: FormContentBlock[];
+};

package/dist/types/print/document-bindings.d.ts

@@ -1,41 +1,4 @@
-/**
- * Values for the region bindings a profile names.
- *
- * ── The gap this closes ─────────────────────────────────────────────────────
- *
- * A profile says WHICH margin box holds WHAT: `instrument`'s footer is
- * `{ left: 'execution-state', right: 'page-x-of-y' }`. Only the second is
- * computable — CSS produces page numbers during pagination. The rest are facts
- * about *this document*, which the bundle cannot know and the host must supply.
- *
- * Until now it supplied none, so every `instrument` page was unprintable:
- * `execution-state` is in `requiredBindings`, and a will that does not say
- * "Not for execution" is a will that does not say it is a draft.
- *
- * ── Why the page declares them, keyed by binding name ───────────────────────
- *
- * `project_page.metadata.document.bindings` — a flat map from binding name to
- * string. Keyed by the binding name itself rather than by some host-side
- * camelCase alias, because a translation layer is one more place for
- * `document-id` and `documentId` to disagree, and because a binding a bundle adds
- * then works with no host change at all.
- *
- * ── What this deliberately does NOT do ──────────────────────────────────────
- *
- * It does not DERIVE anything. `execution-state` could plausibly be computed
- * from a document status — an org's naming system defines DRAFT / REVIEW /
- * FINAL / EXECUTED, and is emphatic that *"`FINAL` and `EXECUTED` are not the
- * same thing… never collapse these"*. Encoding that mapping here would be
- * inventing legal policy in a stylesheet helper, and getting it wrong prints a
- * document asserting the wrong status — the exact failure `requiredBindings`
- * exists to prevent, arriving through the fix for it.
- *
- * So: declared values only. A page that has not declared them stays unprintable,
- * visibly, with the reason on the button. That is the correct state for a
- * document nobody has said the status of.
- */
 import type { PageRegionValues } from './print-stylesheet.js';
-/** The `metadata.document` shape. Open — a profile may name bindings we predate. */
 export interface DocumentBindingsMetadata {
     bindings?: Record<string, unknown>;
 }
@@ -45,32 +8,8 @@ interface PageLike {
 }
 export interface ResolvedBindings {
     values: PageRegionValues;
-    /** Declared keys whose value was not a usable string. Named, never coerced. */
     malformed: string[];
 }
-/**
- * Read declared binding values off a page record.
- *
- * Non-string values are DROPPED and reported rather than stringified. `42` would
- * render as "42" in a footer and look deliberate; `null` would render as "null".
- * A footer is read as an assertion about the document, so a value that arrived
- * by accident must not reach one.
- */
 export declare function resolveRegionBindings(page: PageLike | null | undefined): ResolvedBindings;
-/**
- * The profile id the page names, plus a detector for the second copy of it.
- *
- * `layout.profile` is authoritative — a profile is geometry and belongs beside
- * `structure`. But the proof page carries `metadata.profile` as well, with
- * the same value, and **the host reads only one of them**. Today they agree; the
- * database has 1 page with each key and 0 disagreements. That is two sources for
- * one fact, in sync by luck, with no detector — the shape this pair of repos has
- * now caught four times (`PaperConfig` vs the profile, two type scales, two
- * paginators, and the carried-field lists).
- *
- * Rather than reading both and picking, or silently ignoring one: read `layout`,
- * and say so loudly the moment the copies disagree. Enforcement is cheap here
- * precisely because it is not yet a problem.
- */
 export declare function resolveProfileId(page: PageLike | null | undefined): string | undefined;
 export {};

package/dist/types/print/document-profile.d.ts

@@ -1,49 +1,4 @@
-/**
- * The host's read of a bundle's `documentProfiles`.
- *
- * ── Why the host reads this at all ──────────────────────────────────────────
- *
- * A `DocumentProfile` is authored in the component repo (an org's document
- * bundle owns its profile module) and describes everything two document styles
- * DISAGREE about — sheet, margins, measure, ink, rules, type scale, depth.
- * Most of those are the bundle's business and the host never looks at them.
- *
- * Two are not. `depth.max` and `depth.numbering` are needed **before anything
- * renders**, because the outline is derived from `layout.structure` rather than
- * discovered from the rendered tree (a nav slot is a sibling region, so React
- * context cannot reach it). A value the host needs pre-render cannot arrive
- * through a component prop, so it is lifted off the bundle barrel — exactly the
- * way `ThemeProvider` already is (`loadRemote.ts`).
- *
- * ── Why a resolved map and not `resolveProfile` ─────────────────────────────
- *
- * The bundle exports a plain frozen object with `extends` already applied, so
- * reading configuration never means executing bundle logic. The cost of that
- * trade is that a plain map has no behaviour to throw with — the bundle's
- * `resolveProfile` threw on an unknown id precisely to stop a document
- * rendering in the wrong system. **That behaviour moves here, because the shape
- * we asked for moved it here**.
- *
- * ── The three states, and why the third is not "absent" ─────────────────────
- *
- *   documentProfiles absent              -> host defaults, debug note. Benign:
- *                                           bundles predating the contract.
- *   present, id found                    -> use it.
- *   present, id MISSING                  -> console.warn naming the id AND the
- *                                           ids that ARE present, then defaults.
- *
- * The third case is the one worth the code. Folding it into "absent" makes a
- * page declaring `profile: 'instrument'` against a workbook-only bundle render
- * with a workbook's geometry, orange accents and unbounded depth — which looks
- * like a document rather than like an error. Naming what IS present is what
- * sends the reader to the bundle instead of to the page config.
- */
 import type { LoadedBundle } from '../core/bundles/load.js';
-/**
- * What the resolver reads off a bundle: its `documentProfiles`, and a name for
- * the warnings. The renderer's `LoadedBundle` satisfies it (named by `label`);
- * `key` is the legacy host's name, kept so a caller with only a key still works.
- */
 export type ProfileBundle = Pick<LoadedBundle, 'documentProfiles'> & {
     label?: string;
     key?: string;
@@ -56,24 +11,10 @@ export interface DocumentPageRegionSlots {
     centre?: string;
     right?: string;
 }
-/**
- * Named for CSS `@page` margin boxes. British spelling in, CSS spelling out:
- * `centre` maps to `@bottom-center` at the one place both spellings appear
- * (stage 5's print stylesheet).
- */
 export interface DocumentPageRegions {
     'page-header'?: DocumentPageRegionSlots;
     'page-footer'?: DocumentPageRegionSlots;
 }
-/**
- * The host's structural view of a profile.
- *
- * Deliberately NOT a copy of the bundle's interface. Every field the host does not
- * read is optional here, because the host has no business rejecting a profile
- * over a field it never looks at — and a stricter type would turn each new
- * authoring field into a host release. The fields the host DOES read carry
- * their own runtime guards below; the type is a convenience, not the check.
- */
 export interface DocumentProfile {
     id: ProfileId;
     extends?: ProfileId;
@@ -90,32 +31,13 @@ export interface DocumentProfile {
     };
     measure?: string;
     bodyMeasureCh?: number;
-    /**
-     * The marginalia column, on paper.
-     *
-     * **Not `layout.shell.regions.rail`**, which is the chat panel. Two different
-     * things one word apart, both live in this system's vocabulary, and a reader
-     * who conflates them concludes the rail is already handled.
-     *
-     * `placement: 'column'` establishes a real second column that the PAGE owns —
-     * the bundle's `MetaRail` header is explicit that *"it is not something MetaRail
-     * does to itself"*. `'strip'` and `'none'` establish nothing, which is why
-     * `workbook` and `report` are unaffected by the column geometry.
-     *
-     * `gutter` was shipped by the bundle and absent from this interface until
-     * the column geometry landed, so it was dropped on read — the declared-and-unread shape again,
-     * in the type rather than in the code.
-     */
     rail?: {
         placement: 'strip' | 'column' | 'none';
-        /** Where the column starts, measured from the text block's left edge. */
         axis?: string;
         width?: string;
-        /** Space between the measure and the column. */
         gutter?: string;
     };
     ink?: Partial<Record<DocumentInkRole, string>>;
-    /** `Partial` is load-bearing: an undefined weight is a PROHIBITION, not a gap. */
     rules?: Partial<Record<DocumentRuleWeight, string>>;
     type?: Record<string, unknown>;
     floorPx?: number;
@@ -126,78 +48,19 @@ export interface DocumentProfile {
     };
     fills?: boolean;
     regions?: DocumentPageRegions;
-    /**
-     * `known` absent and `known: []` are DIFFERENT and must stay so. Empty means
-     * "no sectionId is valid"; absent means "not enumerable in advance" — which is
-     * the instrument profile's deliberate state, because articles are generated
-     * from the instrument rather than drawn from a fixed skeleton. Any check that
-     * compares against `known` must guard the absent branch or it fails every
-     * instrument document at once.
-     */
     sections?: {
         required?: string[];
         known?: string[];
     };
-    /**
-     * Region bindings the document MUST NOT be produced without.
-     *
-     * `instrument` declares `['execution-state']`. The reasoning is
-     * domain, not mechanism, and it is the one place the host's general rule is
-     * the wrong rule:
-     *
-     *   Every other missing binding produces a document that is INCOMPLETE.
-     *   This one produces a document that is WRONG ABOUT ITS OWN LEGAL STATUS.
-     *
-     * A draft will that silently loses *"Not for execution"* is, on paper, a will
-     * that does not say it is a draft. So an omitted margin box — correct
-     * everywhere else, because a blank box is indistinguishable from a right one —
-     * fails toward the dangerous side here. `buildPageStylesheet` refuses to
-     * produce the stylesheet at all rather than produce one that misrepresents the
-     * document.
-     *
-     * A **paginator** binding must never appear here. The host cannot supply
-     * `page-x-of-y` — CSS computes it during pagination — so requiring one would
-     * be a permanent, unsatisfiable failure.
-     *
-     * Open `string[]`, not a closed union, for the same reason `ProfileId` is
-     * open: the vocabulary is authored in the component repo, and a binding a bundle
-     * adds must not be a host type error before it is a design question.
-     */
     requiredBindings?: string[];
 }
 export type DocumentProfileMap = Readonly<Record<ProfileId, DocumentProfile>>;
-/**
- * Where the resolved profile came from. Callers that render a diagnostic want
- * to distinguish "the bundle said so" from "nobody said anything".
- */
 export type DocumentProfileSource = 'bundle' | 'defaults';
 export interface ResolvedDocumentProfile {
-    /** `null` when no profile was found. Callers fall back to their own defaults. */
     profile: DocumentProfile | null;
     source: DocumentProfileSource;
-    /**
-     * `profile.depth.max` when it is a usable bound, else `undefined`.
-     *
-     * `undefined` means UNBOUNDED, and that is a real answer rather than a
-     * missing one — the 191 flat `grid` pages have no depth to bound and the
-     * workbook profile's skeleton is flat. `deriveTableOfContents` and
-     * `validateStructure` both treat `maxDepth: undefined` as "do not check".
-     */
     maxDepth: number | undefined;
-    /** `profile.depth.numbering`, defaulting to `'ladder'`. */
     numbering: 'none' | 'ladder';
 }
-/** Test seam. Nothing in the app should need this. */
 export declare function __clearDocumentProfileWarnings(): void;
-/**
- * Resolve `profileId` against an ordered bundle cascade.
- *
- * Order matches the cell cascade — earlier registries win — so a page-level
- * `bundle_refs` entry overrides the org default for the profile the same way it
- * does for a component. A page that declares no profile gets host defaults
- * without a word: that is the 191-flat-page case and it is not a fault.
- *
- * @param registries  Ordered, highest priority first. Loading? Pass `[]`.
- * @param profileId   From `layout.profile`. `undefined` when the page declares none.
- */
 export declare function resolveDocumentProfile(registries: readonly ProfileBundle[], profileId: ProfileId | undefined): ResolvedDocumentProfile;

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

@@ -1,75 +1,9 @@
-/**
- * Is the frozen page map still describing the document that is on the page?
- *
- * ── Why this needs to be asked at all ───────────────────────────────────────
- *
- * `DocPrintContent` measures the document once, assigns its rows to pages, and
- * freezes — because typesetting changes the document it measured, so measuring
- * the already-typeset document gives a different and wrong answer.
- *
- * Freezing needs the document to have finished rendering, and nothing can be
- * sure it has. The settle gate waits for the height to stop changing, and a
- * document that is halfway through drawing its charts STALLS: the height climbs
- * 4,472 → 10,283 → 11,083px in under a second on the proof document, with pauses.
- * Reads taken during a pause are indistinguishable from a finished document by
- * arithmetic. Observed twice: a **6-page map for a 15-page document**, and a
- * **7-page map for a 10,613px document** — and a reload of the same URL giving
- * 15 both times. Same code, two answers, nothing in the output saying which.
- *
- * A prediction cannot be made reliable by tightening it. So the map is checked
- * against the document afterwards, and a stale map fails by thousands of pixels
- * rather than by a rounding error.
- *
- * ── Why the arithmetic lives here and not in the component ─────────────────
- *
- * Because it is the part that was wrong, twice, and both times it FAILED SILENT
- * — a check that cannot conclude looks exactly like a check that passes:
- *
- * 1. It ignored the scaling the typesetting applies, so every document with an
- *    over-tall row looked stale by that row's shrink.
- * 2. It ignored the on-screen page separators — margin and padding, ~66px per
- *    page start, ~792px over 15 pages. That condemned a correct map, unfroze,
- *    measured the now-shorter document, froze, and condemned it again:
- *    an oscillation between 10,283 and 11,083px that sometimes ended with the
- *    document not typeset at all. A check that creates the instability it was
- *    added to detect.
- *
- * Both are arithmetic about heights, testable with numbers, and were shipped
- * un-unit-tested because they lived inside an effect that needs a browser.
- */
 import type { PrintLayout } from './print-layout.js';
-/**
- * The container height to expect once a layout has been applied.
- *
- * Forced page breaks change nothing on screen, so only two things move:
- *
- * - **Scaling shortens** an over-tall row: its box goes from `heightPx` to
- *   `scaledHeightPx`. Subtract the difference.
- * - **Screen separators lengthen** the document: they are margin, border and
- *   padding on each page's first row. Add `screenExtraPx`, which the layout
- *   reports rather than this function re-deriving from the CSS text.
- *
- * @param measuredContainerPx The container height the map was measured from —
- *                            `reconciliation.containerPx`, not a fresh read.
- */
 export declare function expectedHeightAfterTypesetting(measuredContainerPx: number, layout: Pick<PrintLayout, 'scaled' | 'screenExtraPx'>): number;
 export interface Staleness {
     stale: boolean;
-    /** Live height minus expected. Positive means the document grew. */
     deltaPx: number;
     tolerancePx: number;
 }
-/**
- * Half a page of slack.
- *
- * Chosen to sit in the wide gap between the two populations rather than tuned:
- * the things that legitimately move a settled document — a late font, sub-pixel
- * rounding, a border — are tens of pixels, and the observed stale maps were
- * 4,200 and 5,600px adrift. Anything in that range separates them.
- *
- * A floor of 120px, because a document on a very short page would otherwise get
- * a tolerance smaller than one row.
- */
 export declare function stalenessTolerancePx(textBlockPx: number): number;
-/** Compare the document on the page against the map that was frozen for it. */
 export declare function mapStaleness(liveHeightPx: number, expectedPx: number, textBlockPx: number): Staleness;