@peripheries/renderer 0.23.0 → 0.23.1

package/dist/types/print/print-stylesheet.d.ts

@@ -1,79 +1,7 @@
-/**
- * `@page` geometry, generated from a `DocumentProfile`.
- *
- * ── One source, and it is the profile ───────────────────────────────────────
- *
- * `03-print-strategy.md` §2 specified a `PaperConfig` on the layout contract.
- * That is superseded: `DocumentProfile` already carries `sheet`, `margins`,
- * `measure`, `floorPx` and `regions`, it is authored where the design lives, and
- * it is already lifted off the bundle barrel. A second geometry source would be
- * the exact thing §2 argued against — *"it distributes the page definition
- * across every file that has an opinion"* — with the added twist that the two
- * sources would disagree in a way only a printed page could reveal.
- *
- * ── Why the host injects margin-box content as literals ─────────────────────
- *
- * MEASURED, Chromium 151, this session:
- *
- *   CSS.supports('string-set', 'docCode content(text)')  -> false
- *   CSS.supports('content', 'string(docCode)')           -> false
- *
- * and, inserted into a real stylesheet, both are **dropped by the parser**:
- * `h1 { string-set: … }` round-trips as `h1 { }`, and
- * `@page { @bottom-left { content: string(docCode) } }` as `@bottom-left { }`.
- * Literal strings and `counter(page)`/`counter(pages)` both survive.
- *
- * So Chromium does not implement the GCPM `string()` mechanism, and a footer
- * cannot pull text out of the document. **This is a third silent-failure mode**
- * beside the two `03` §4 already lists (`preferCSSPageSize`, margin boxes not
- * inheriting the body font): the declaration is dropped at parse time, the
- * margin box renders empty, and nothing anywhere reports it.
- *
- * The host therefore resolves each region slot to a literal at build time —
- * which it can, because it knows the document — and refuses to emit a slot it
- * cannot resolve rather than emitting one that will silently render blank.
- */
 import type { DocumentProfile } from './document-profile.js';
-/**
- * Values for the region slots a profile names, keyed by slot name.
- *
- * `instrument` asks for `execution-state` bottom-left and `page-x-of-y`
- * bottom-right. The second is a built-in; the first is document-derived and has
- * to be supplied here.
- */
 export type PageRegionValues = Readonly<Record<string, string>>;
-/** Test seam. Nothing in the app should need this. */
 export declare function __clearPrintStylesheetWarnings(): void;
-/**
- * Cross-check the bundle's paginator vocabulary against what the host can render.
- *
- * A document bundle exports `PAGINATOR_BINDINGS` — the bindings the host must NOT try to
- * supply, because CSS computes them during pagination. The host holds the other
- * half: the CSS expression each one becomes. Today the two lists agree exactly
- * (`page-x-of-y`, `page-number`, `page-count`), arrived at independently on both
- * sides — which is reassuring and completely unenforced.
- *
- * The divergence that matters is one-directional. If the bundle adds a fourth binding
- * — `page-of-section`, say — the host has no expression for it, `values` will
- * never contain it (correctly: nobody may supply a paginator binding), and the
- * margin box is **silently omitted**. The document loses a footer and nothing
- * reports it, which is the failure this whole module is built to refuse.
- *
- * So the check runs at bundle load, once, and names the gap. The host cannot fix
- * it at runtime — an expression has to be written — but a named gap is a
- * two-minute change and a silent one is a reprint.
- */
 export declare function checkPaginatorBindings(bindings: unknown, debugLabel: string): string[];
-/**
- * Host fallback geometry, used when no profile resolves. US Letter.
- *
- * **Exported because the page map needs the same numbers.** Most pages declare
- * no profile — the proof document's `layout` is `columns, shell, structure, type`
- * with no `profile` key — so these, not a profile, are what the live `@page`
- * rule is built from. A page map that fell back to its own copy of "US Letter"
- * would be a second source for the geometry the paginator measures against, and
- * the two agreeing today is not the same as them being one number.
- */
 export declare const DEFAULT_SHEET: {
     width: string;
     height: string;
@@ -84,49 +12,13 @@ export declare const DEFAULT_MARGINS: {
     bottom: string;
     left: string;
 };
-/**
- * Quote a value for use in a CSS `content` string.
- *
- * Not decoration: a document code carrying an apostrophe — or a member name
- * carrying one, which is common — would otherwise terminate the string early
- * and produce a stylesheet that fails to parse from that point on, taking the
- * rest of the `@page` block with it. Backslash first, or it re-escapes the
- * escapes.
- */
 export declare function cssString(value: string): string;
-/**
- * A profile value (a length, a colour, a rule weight) as a CSS token, or undefined when it isn't
- * one. These come from the bundle's profile, never from document data, but a value that could
- * end a declaration or the style element is dropped all the same: letters, digits, `#`, `.`, `,`,
- * `%`, `-`, `_`, `/`, spaces and parentheses, at most 120 characters.
- */
 export declare function cssValue(value: unknown): string | undefined;
 export interface BuildPageStylesheetOptions {
     values?: PageRegionValues;
-    /** Named in warnings so a blank footer is traceable to a document. */
     debugLabel?: string;
-    /**
-     * Throw when a binding in `profile.requiredBindings` cannot be filled.
-     *
-     * **Defaults to `true`, and the default is the whole point.** A caller that
-     * forgets this option gets the refusal; a caller that wants to render anyway
-     * has to say so at the call site, where a reader can see it and ask why. The
-     * inverse default would make "produce a legal instrument that does not say it
-     * is a draft" the thing you get by not thinking about it.
-     *
-     * Screen rendering passes `false` deliberately: `@page` does not apply on
-     * screen, so a missing footer binding misrepresents nothing there. The
-     * artifact path — where the document becomes paper — must not.
-     */
     strict?: boolean;
 }
-/**
- * Thrown when a document cannot be printed without misrepresenting itself.
- *
- * A distinct class rather than a bare `Error` so an artifact endpoint can
- * answer 422-with-a-reason instead of 500-with-a-stack: this is a document
- * that is not printable yet, not a server that broke.
- */
 export declare class MissingRequiredBindingError extends Error {
     readonly profileId: string | undefined;
     readonly missing: string[];
@@ -134,35 +26,8 @@ export declare class MissingRequiredBindingError extends Error {
 }
 export interface PageStylesheet {
     css: string;
-    /**
-     * Unfilled bindings the profile marked required.
-     *
-     * Only ever non-empty when `strict: false` — strict mode throws instead. It
-     * exists so a lenient (screen) caller can still surface the problem before
-     * someone hits print, rather than discovering it on paper.
-     */
     missingRequired: string[];
-    /**
-     * Slots the profile named and the host could not fill.
-     *
-     * Returned rather than only logged so a caller — a print preflight, or the
-     * parity test in stage 9 — can assert on them. A blank margin box is invisible
-     * on screen and only wrong on paper, which is the worst place to find it.
-     */
     unresolvedSlots: string[];
 }
-/**
- * Build the `@page` block for one document.
- *
- * @param profile Resolved profile, or `null` for host defaults.
- */
 export declare function buildPageStylesheet(profile: DocumentProfile | null, options?: BuildPageStylesheetOptions): PageStylesheet;
-/**
- * Profile-derived custom properties for the printed body.
- *
- * Separate from the `@page` block because they cascade to elements, and `@page`
- * is not part of the document tree — a custom property declared inside `@page`
- * is not visible to the body, and one declared on `:root` is not visible to a
- * margin box. Both halves are needed and neither can be dropped into the other.
- */
 export declare function buildPageVariables(profile: DocumentProfile | null): string;

package/dist/types/print/running-header.d.ts

@@ -1,105 +1,19 @@
-/**
- * Running headers and footers that know where they are in the document.
- *
- * ── What this is for ───────────────────────────────────────────────────────
- *
- * The owner: *"I'd like to be able to create a custom print header and footer
- * that updates based on the page layout i.e. page number section continuation
- * etc."*
- *
- * Page numbers were already possible — `counter(page)` in a margin box, and
- * MEASURED to work in Chrome. *"Financial Summary (continued)"* was not, and the
- * reason is recorded in `print-stylesheet.ts`: Chromium drops the GCPM
- * `string()` mechanism at parse time, so a margin box cannot pull text out of
- * the document. Every engine that does this natively (Prince, WeasyPrint) has
- * `string-set`; Chrome has neither.
- *
- * ── Why the host can do it anyway ──────────────────────────────────────────
- *
- * Because the host now knows the pagination. `paginate` assigns every row to a
- * page, and MEASURED this session, Chrome supports **named pages**:
- *
- *   @page secA { @top-left { content: "Financial Summary" } }
- *   .row      { page: secA; }
- *
- * with `counter(page)` staying continuous across them and margin boxes
- * cascading **per box** — a named rule overrides only the slots it redefines,
- * leaving the rest of the default `@page` intact.
- *
- * So the host resolves the running content per page itself and emits one named
- * `@page` rule for each. Nothing is pulled from the document at print time; it
- * is all decided before the stylesheet is written.
- *
- * ── Where a "section" comes from, and why not from config ──────────────────
- *
- * Not from config, because it is not there. The proof page's `layout.structure` is a flat
- * list of `{ cellId }` with no sections and no `sectionId`, and a survey
- * measured 3 `sectionId`s across 2,279 structure nodes with **none** on that
- * document. Its cells are thin refs, so even the component name lives in DSNS
- * rather than the page.
- *
- * It comes from the **rendered document**, on a signal FEC already authors:
- * a row that declares `break-after: avoid` is a row bound to what follows —
- * which is what a section heading is. Measured on the proof document, that selects
- * **exactly** the seven `*-header` rows, all `<h2>`, with no false positives:
- *
- *   summary-header · retirement-header · networth-header · tax-header
- *   insurance-header · decumulation-header · decisions-header
- *
- * Requiring a heading element as well excludes the cover (`<h1>`, and not bound
- * to anything) and the `<h3>`/`<h4>` sub-headings that live *inside* content
- * rows — those are 6 more heading elements that are emphatically not sections.
- *
- * This module takes the markers already resolved. Finding them in the DOM is
- * the caller's job, for the same reason `collectBlocks` takes an injected
- * measurer: a pure function is testable and a DOM walk is not.
- */
 import type { PageMap } from './paginate.js';
 import type { Band } from './page-map.js';
-/** A row that begins a section, and the title it carries. */
 export interface SectionMarker {
-    /** The cell id of the heading row. */
     cellId: string;
     title: string;
 }
 export interface RunningValues {
-    /** 1-based page number. */
     page: number;
-    /** The section this page sits in, or undefined before the first heading. */
     sectionTitle?: string;
-    /**
-     * True when the section started on an EARLIER page.
-     *
-     * The distinction a reader needs: a page headed *"Retirement Analysis"* that
-     * begins the section reads differently from one that carries it on, and
-     * without the marker a reader flipping through cannot tell whether they have
-     * missed the start.
-     */
     continued: boolean;
 }
 export interface ResolveRunningOptions {
-    /** Appended when a section carries over. `' (continued)'` by default. */
     continuedSuffix?: string;
 }
-/**
- * Which section each page is in, and whether it carries over.
- *
- * @param map     From `paginate`, whose pages hold band ids in reading order.
- * @param bands   From `collectBlocks`, to resolve a band id to its member cells.
- * @param markers The section headings, in document order.
- */
 export declare function resolveRunningValues(map: PageMap, bands: readonly Band[], markers: readonly SectionMarker[]): RunningValues[];
-/**
- * The per-page slot values, keyed by slot name.
- *
- * Two names, deliberately few. `section-title` is the bare title;
- * `section-title-continued` is the same title with the suffix when it carries
- * over — a profile chooses which behaviour it wants rather than the host
- * deciding for it, because a footer that says *"Retirement Analysis
- * (continued)"* is right for a report and wrong for a form.
- */
 export declare const RUNNING_SLOTS: readonly ["section-title", "section-title-continued"];
 export type RunningSlot = (typeof RUNNING_SLOTS)[number];
 export declare function isRunningSlot(name: string): name is RunningSlot;
-/** Resolve one page's running slots to literal strings. */
 export declare function runningSlotValues(values: RunningValues, { continuedSuffix }?: ResolveRunningOptions): Partial<Record<RunningSlot, string>>;

package/dist/types/print/structure-print.d.ts

@@ -1,269 +1,46 @@
-/**
- * Writing a person's page-break decision back into `layout.structure`.
- *
- * ── What this is for ───────────────────────────────────────────────────────
- *
- * The owner: *"hover buttons that allow the user to move components either up or
- * down in the print map … do page mappings get persisted so the next time it
- * respects those changes."*
- *
- * They do, and this is the write. Two things had to be settled before it could
- * exist, and both were settled by the people who own them rather than here:
- *
- * - **The vocabulary is FEC's**. `keepWithPrevious`, not
- *   `breakBefore: false`, because an absent boolean and a false one are the same
- *   value across a JSON round-trip — so "no opinion" and "explicitly do not
- *   break" would have been indistinguishable, which is the declared-vs-default
- *   flattening that split a section heading in half.
- * - **The storage is `layout.structure[].print`** (agreed with the agency side, checked
- *   against the database). A template re-sync does not touch an instance page's
- *   `layout`; the standing rule is never to call sync with `rebuild`.
- *
- * ── Why an intent and not a page number ────────────────────────────────────
- *
- * A stored page ASSIGNMENT — "page 7 holds these four rows" — is wrong the
- * instant any height changes: a data refresh, a webfont, a longer client name.
- * A stored INTENT — "start a page before this row" — survives all of them,
- * because it is a statement about a boundary rather than about a layout.
- *
- * ── Why it is a pure function over the structure array ─────────────────────
- *
- * Because the array is the awkward part, not the write. Entries are strings OR
- * objects, sections nest children arbitrarily deep, and the same cell id must not
- * be matched twice. All of that is testable without a database, and none of it is
- * testable through a mutation hook.
- */
 import type { LayoutNode as RuntimeLayoutNode } from '@peripheries/runtime';
 import type { PrintConstraints } from './print-policy.js';
-/**
- * Where a structure row renders outside the flow. The runtime types `slot` as an
- * open string; the print writer only knows this one.
- */
 export type StructureSlot = 'marginalia';
-/**
- * The runtime's `LayoutNode`, with the print block's `blankPageBefore` (a
- * deliberate blank page before the row), which the runtime type does not
- * declare yet. Everything else is the runtime's.
- */
 export type LayoutNode = Omit<RuntimeLayoutNode, 'print' | 'children'> & {
     children?: Array<LayoutNode | string>;
     print?: NonNullable<RuntimeLayoutNode['print']> & {
         blankPageBefore?: boolean;
     };
 };
-/** What a person asked for about a row's position in the page map. */
-export type PageIntent = 
-/** Start a new page at this row. */
-'break-before'
-/** Keep this row on the page above — it may not open a page. */
- | 'keep-with-previous'
-/** No opinion: the packer decides. Clears any previous intent. */
- | 'auto';
-/** A structure entry, as authored. A bare string is shorthand for `{ cellId }`. */
+export type PageIntent = 'break-before' | 'keep-with-previous' | 'auto';
 export type StructureEntry = string | StructureNode;
-/**
- * A `layout.structure` entry, as the print writer sees it.
- *
- * **Not a second declaration.** Every field lives on `LayoutNode`
- * (`@peripheries/runtime`, plus `blankPageBefore` above) — its header records why there
- * is now one. This alias adds exactly two things, both about writing rather
- * than rendering:
- *
- * - **an index signature**, so an authored key the host has never heard of
- *   survives a read-modify-write instead of becoming an excess-property error.
- *   The renderer must not have it: it would switch off excess-property checking
- *   for every node literal there.
- * - **`children` narrowed to `StructureEntry[]`**, so the recursive walks below
- *   stay typed. `LayoutNode.children` is `Array<LayoutNode | string>`, and a
- *   `LayoutNode` is not assignable to a type carrying an index signature.
- *
- * **Add a field to `LayoutNode`, never here.** A field added here is invisible
- * to the renderer — which is exactly how `slot` shipped into one of two types
- * and was found by FEC's drift check rather than by either of us.
- */
 export type StructureNode = Omit<LayoutNode, 'children'> & {
     children?: StructureEntry[];
     [key: string]: unknown;
 };
 export interface SetIntentResult {
     structure: StructureEntry[];
-    /** False when no entry named this cell — the caller must not save a no-op. */
     changed: boolean;
 }
-/**
- * Set one row's page intent, returning a new structure.
- *
- * @param structure The page's `layout.structure`, untouched by this call.
- * @param cellId    The row to set it on.
- * @param intent    What the person asked for.
- */
 export declare function setRowPageIntent(structure: readonly StructureEntry[] | undefined, cellId: string, intent: PageIntent): SetIntentResult;
-/**
- * The `print` block an intent produces, or `undefined` when it produces none.
- *
- * ── Why this is exported ────────────────────────────────────────────────────
- *
- * Because the same intent now has to land in TWO places, per the owner's ruling
- * on where print configuration lives: *"The honest answer is both. If there is
- * an associated process node synced to the config, then it lives in DSNS. But
- * this should update the project_page record anyways."*
- *
- * So `setRowPageIntent` writes the page row's `layout.structure[].print` and
- * `recordCellPrintIntent` writes the cell's DSNS `content.layout.print`. Two
- * call sites, one set of rules — because two copies of these three lines is
- * exactly how a mirror comes to disagree with its source, which is the defect
- * this whole channel keeps meeting.
- *
- * The rules, all three load-bearing:
- *
- * 1. **Both keys are deleted first.** Leaving a stale `breakBefore: true` under
- *    a new `keepWithPrevious: true` produces a node that asks for a break and
- *    asks not to break. `StructureRenderer` resolves that to the break and
- *    warns, so a person pressing "move up" would watch nothing happen and be
- *    told nothing.
- * 2. **`auto` is the ABSENCE of both**, never either set `false`. The
- *    vocabulary is FEC's and `nodePrintStyle` reads a `false` as no
- *    declaration at all — indistinguishable from working.
- * 3. **An empty block is `undefined`, not `{}`.** To a reader `{}` says
- *    "someone had an opinion here", and it would survive every future diff.
- *
- * `breakInside` is never touched: a different decision, authored by someone
- * else, and this function has no opinion about it.
- */
 export declare function printBlockForIntent(existing: StructureNode['print'] | undefined, intent: PageIntent): StructureNode['print'] | undefined;
-/** What intent a `print` block expresses. The inverse of `printBlockForIntent`. */
 export declare function intentOfPrintBlock(print: StructureNode['print'] | undefined): PageIntent;
-/** What intent a row currently carries, for a control that shows its state. */
 export declare function rowPageIntent(structure: readonly StructureEntry[] | undefined, cellId: string): PageIntent;
-/**
- * Every cell's extrinsic `print` block, keyed by cell id.
- *
- * ── Why this exists, and what it cost not to have it ───────────────────────
- *
- * `layout.structure[].print` was honoured by `StructureRenderer` and by nothing
- * else. `usesStructureLayout` routes a page there only for `type: 'document'`
- * or a section-shaped node — **2 of 198** structured pages — so on every other
- * page the extrinsic half was written, mirrored, and dropped at render.
- *
- * Measured end to end on the proof page: a client pressed *"Start a new page here"*,
- * the intent landed in the cell DSNS AND the page row (both verified by query),
- * and the document did not break there. The button worked, the write worked,
- * and the paper never heard about it — which is indistinguishable from a broken
- * feature and is worse, because two records now claim something the reader
- * cannot see.
- *
- * It is the exact mirror of an earlier finding: that found `StructureRenderer`
- * dropping the INTRINSIC `@printPolicy`; this is `CellsRenderer` dropping the
- * EXTRINSIC `node.print`. Two renderers, each honouring one half.
- *
- * Walks children, because a section's rows carry their own intents and a
- * document-type page routes to the other renderer but a `grid` page with
- * children does not.
- */
 export declare function printByCellId(structure: readonly StructureEntry[] | undefined): ReadonlyMap<string, NonNullable<StructureNode['print']>>;
-/**
- * A structure node's extrinsic declaration, as `PrintConstraints`.
- *
- * ── Why this is in lib rather than beside the renderer that had it ─────────
- *
- * It lived in `StructureRenderer`, which is fine while one renderer needs it.
- * **Both do:** `CellsRenderer` renders 196 of 198 structured pages and was
- * dropping the extrinsic half entirely. `StructureRenderer` imports
- * `CellRenderer`, so importing back would make the pair circular — and a
- * second copy is how the two renderers would come to disagree about what a
- * node declared, which is the defect this whole file exists to prevent.
- *
- * **It can only ever TIGHTEN**, which is the component repo's invariant for the extrinsic
- * half (`a node may ADD a break, never RELAX one`). `breakInside` is emitted
- * only for `'avoid'`, never `'auto'`, so composing this after a component's
- * intrinsic policy cannot turn an atomic component splittable — a page author
- * cannot switch off what a component declared about itself.
- *
- * `keepWithPrevious` becomes `breakBefore: 'avoid'`, and a `breakBefore`
- * declared alongside it wins, because CSS Fragmentation §3.2 resolves a forced
- * break over an avoid and the composer follows the enforcer rather than
- * inventing a rule.
- */
 export declare function nodePrintConstraints(node: {
     print?: StructureNode['print'];
 }): PrintConstraints | undefined;
-/**
- * Add or remove a deliberate blank page before a row.
- *
- * Deliberately NOT folded into `setRowPageIntent`: that function owns the
- * break-vocabulary keys and clears the ones it does not set, which is right for
- * three mutually exclusive intents and wrong here. A blank page is an
- * independent decision — a row can both open a page and have a blank one before
- * it — and a person moving a row must not silently delete the blank page they
- * put in front of it.
- *
- * `changed` is false when the row already says this, so a caller can refuse to
- * burn a revision recording nothing.
- */
 export declare function setRowBlankPage(structure: readonly StructureEntry[] | undefined, cellId: string, present: boolean): {
     structure: StructureEntry[];
     changed: boolean;
 };
-/** Does a deliberate blank page precede this row? */
 export declare function rowHasBlankPage(structure: readonly StructureEntry[] | undefined, cellId: string): boolean;
-/**
- * What one write actually changed, per cell.
- *
- * ── Why a write must carry a diff and not a document ────────────────────────
- *
- * Every layout gesture computes a whole new `layout` from the copy in the
- * client's cache and hands it to the writer, which `update`s the row with it.
- * That is a blind overwrite, and it loses every change the cache had not caught
- * up with — the owner: *"if I don't close the layout mode after adding or
- * deleting a blank page any edits I made to other layout configurations get
- * reverted."*
- *
- * The invalidation bug that made the cache stale is fixed separately, and
- * fixing it is not enough: two clicks land inside one refetch, and the second
- * still reverts the first. The durable answer is for the write to state its
- * own scope. Then the row's untouched entries come from the row as read at
- * submit, and a concurrent change to a different cell survives — the same rule
- * `record-state-patch` follows for authored scalars.
- *
- * `undefined` print means REMOVE the block, which is a real gesture (deleting a
- * page break, deleting a blank page) and must not be confused with "unchanged".
- * That is why the result is a list of explicit entries rather than a partial
- * map: absence here means *not part of this write*, and only `print:
- * undefined` means *take it away*.
- */
 export interface RowPrintChange {
     cellId: string;
-    /** The new block, or `undefined` to remove it. */
     print?: NonNullable<StructureNode['print']>;
 }
 export declare function diffRowPrint(base: readonly StructureEntry[] | undefined, next: readonly StructureEntry[] | undefined): RowPrintChange[];
-/**
- * Apply a diff onto a structure read at submit.
- *
- * `missing` names changes whose cell has no entry in the structure being
- * written to — a renamed cell, or a change aimed at a page that has moved on.
- * Reported rather than silently dropped: a write that lands partially and says
- * nothing is the shape this whole area keeps producing.
- */
 export declare function applyRowPrint(structure: readonly StructureEntry[] | undefined, changes: readonly RowPrintChange[]): {
     structure: StructureEntry[];
     changed: boolean;
     missing: string[];
 };
-/**
- * The cell ids a structure hoists out of the flow, by slot.
- *
- * Walks nested entries, because a document structure nests
- * (`{sectionId, children: [{cellId}]}`) and a flat scan finds nothing at depth
- * — the exact false negative a review hit and recorded, where a flat
- * comparison reported 7 and 10 cells "missing" from pages that were complete.
- *
- * Returns ids in document order and de-duplicated. Order matters only if a
- * profile ever allows more than one occupant; today the caller takes the first
- * and the rest are a finding, not a layout.
- */
 export declare function findSlottedCellIds(structure: readonly StructureEntry[] | undefined, slot: StructureSlot): string[];
-/** A page whose cells and structure can be split. Structural minimum, not the full row. */
 type SplittablePage = {
     content?: {
         cells?: Array<{
@@ -275,28 +52,9 @@ type SplittablePage = {
     } | null;
 } & Record<string, unknown>;
 export interface MarginaliaSplit<P> {
-    /** What sets in the measure. The SAME reference as the input when nothing moved. */
     bodyPage: P;
-    /** What sets beside it, or null when nothing is hoisted. */
     marginaliaPage: P | null;
-    /**
-     * Why nothing was hoisted, when nothing was. `null` when the split happened.
-     * `'dangling'` is the one worth surfacing: the row declares a slot naming a
-     * cell the page does not have, which is the dangling-reference class.
-     */
     reason: null | 'no-slot' | 'no-track' | 'dangling';
 }
-/**
- * Split a page into what sets in the measure and what sets in the marginalia.
- *
- * Pure, and separated from the view for one reason: it is the half that can be
- * wrong in a way nobody sees. The DOM placement is visible the moment you open
- * the page; *which cell moved, whether the rest survived, and whether a page
- * that declares nothing is returned untouched* are not.
- *
- * **`bodyPage` is the input reference when nothing moves**, not a shallow copy.
- * A copy would be equal and would still invalidate every downstream memo keyed
- * on identity, on every page in the product — all of which declare no slot.
- */
 export declare function splitMarginalia<P extends SplittablePage>(page: P | null | undefined, marginaliaCellId: string | null | undefined, hasReservedTrack: boolean): MarginaliaSplit<P>;
 export {};

package/dist/types/react/cell-states.d.ts

@@ -1,5 +1,4 @@
 import { Component, type ReactNode } from 'react';
-/** A placeholder the size of the cell's slot, so the page doesn't shift when components arrive. */
 export declare function CellPlaceholder({ state }: {
     state: 'loading' | 'pending';
 }): import("react").JSX.Element;
@@ -9,7 +8,6 @@ export declare function CellNotice({ state, component, onRetry, children }: {
     onRetry?: () => void;
     children: ReactNode;
 }): import("react").JSX.Element;
-/** One cell's crash stays in that cell. */
 export declare class CellErrorBoundary extends Component<{
     cellId: string;
     onError?: (cellId: string, error: Error) => void;

package/dist/types/react/cell-view.d.ts

@@ -11,47 +11,32 @@ import type { ScopeContext } from '../core/store/scope-keys.js';
 import type { EditCell, PropSourceEntry } from '../core/sources.js';
 import type { PageCell } from '../core/types.js';
 import { type LoadPage } from './use-paging.js';
-/** The slot a parent with `each` repeats (core's Repeat): design/ui-consistency.md §2.8. */
 export declare const REPEAT_SLOT = "item";
 export type CellEnvironment = {
     cellsById: Map<string, PageCell>;
     page: ResolutionContext;
     baseProps: unknown;
-    /** null while the page's bundles are loading (and always on the server). */
     bundles: LoadedBundle[] | null;
     bundleFor: (cell: PageCell) => LoadedBundle | null;
-    /** The bundle rows couldn't be read, or a bundle didn't import (PageBundles.failed). */
     bundlesFailed?: boolean;
-    /** Reads the page again, for a cell's "Try again" (RendererEnvironment.retry). */
     retry?: () => void;
     core: CoreRegistry;
     navigate: (to: string) => void;
     store: StackStoreApi;
     scope: ScopeContext;
     context: Record<string, unknown>;
-    /** The signed-in person, for `@viewer.*`. */
     viewer?: unknown;
-    /** Each cell's own data, by cell id (loadPageData). */
     cellData?: Record<string, CellData>;
-    /** Labels the page declares, which no walk's label replaces. */
     declared?: ReadonlySet<string>;
-    /** The actions a cell gets (RendererEnvironment.actionsFor). */
     actionsFor?: (cell: PageCell) => Record<string, CellAction> | undefined;
-    /** Runs a declared action (RendererEnvironment.runAction). */
     runAction?: RunAction;
-    /** Loads a paged label's next page (RendererEnvironment.loadPage). */
     loadPage?: LoadPage;
     onCellError?: (cellId: string, error: Error) => void;
     onUnresolvedReference?: (cellId: string, ref: string) => void;
-    /** Each rendered cell's props, by prop path, with where each value came from (RendererEnvironment.onPropSources). */
     onPropSources?: (cell: EditCell, sources: PropSourceEntry[]) => void;
-    /** An embed cell's page (PageRuntime.embeds), rendered by the page renderer. */
     renderEmbed?: (cellId: string) => ReactNode;
-    /** Where a render-time diagnostic goes (`COMPONENT_UNKNOWN` from `renderComponent`). */
     onDiagnostic?: (d: Diagnostic) => void;
-    /** Extra attributes and style for a cell's frame (RendererEnvironment.frameProps). */
     frameProps?: (cell: PageCell, contract: ComponentContract | undefined) => FrameProps | undefined;
-    /** Props from the page's runtime, merged last (RendererEnvironment.cellProps). */
     cellProps?: (cell: PageCell) => Record<string, unknown> | undefined;
 };
 export type FrameProps = {
@@ -62,6 +47,5 @@ export declare function CellView({ cell, env, nested, injectedProps, }: {
     cell: PageCell;
     env: CellEnvironment;
     nested?: boolean;
-    /** Host-derived facts merged over the resolved props (a structure's numbering, anchors, references). */
     injectedProps?: Record<string, unknown>;
 }): import("react").JSX.Element | null;