@peripheries/renderer 0.23.0 → 0.23.1

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;