@peripheries/renderer 0.17.0 → 0.19.0

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

@@ -0,0 +1,203 @@
+/**
+ * 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;
+};
+export type ProfileId = string;
+export type DocumentInkRole = 'full' | 'muted' | 'subtle' | 'border' | 'accent' | 'accentText' | 'sunken';
+export type DocumentRuleWeight = 'structural' | 'hairline' | 'head' | 'row';
+export interface DocumentPageRegionSlots {
+    left?: string;
+    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;
+    label?: string;
+    sheet?: {
+        width: string;
+        height: string;
+    };
+    margins?: {
+        top: string;
+        right: string;
+        bottom: string;
+        left: string;
+    };
+    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;
+    depth?: {
+        max?: number;
+        indent?: string[];
+        numbering?: 'none' | 'ladder';
+    };
+    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/index.d.ts

@@ -0,0 +1,11 @@
+export * from './document-profile.js';
+export * from './document-bindings.js';
+export * from './page-map.js';
+export * from './paginate.js';
+export * from './print-layout.js';
+export * from './map-staleness.js';
+export * from './print-lint.js';
+export * from './print-policy.js';
+export * from './print-stylesheet.js';
+export * from './running-header.js';
+export * from './structure-print.js';

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

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