@peripheries/renderer 0.16.0 → 0.19.0

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

@@ -0,0 +1,168 @@
+/**
+ * `@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;
+};
+export declare const DEFAULT_MARGINS: {
+    top: string;
+    right: string;
+    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[];
+    constructor(profileId: string | undefined, missing: string[]);
+}
+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

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

@@ -0,0 +1,302 @@
+/**
+ * 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 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<{
+            id?: string;
+        }>;
+    } | null;
+    layout?: {
+        structure?: StructureEntry[];
+    } | 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-view.d.ts

@@ -8,6 +8,7 @@ import type { CellData } from '../core/load-page.js';
 import { type ResolutionContext } from '../core/references.js';
 import type { StackStoreApi } from '../core/store/create-store.js';
 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';
 export type CellEnvironment = {
@@ -40,6 +41,8 @@ export type CellEnvironment = {
     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`). */

package/dist/types/react/page-renderer.d.ts

@@ -4,6 +4,7 @@ import type { PageBundles } from '../core/bundles/page-bundles.js';
 import type { CoreRegistry } from '../core/bundles/resolve.js';
 import type { Diagnostic } from '../core/graph.js';
 import type { PageRuntime } from '../core/load-page.js';
+import type { EditCell, PropSourceEntry } from '../core/sources.js';
 import type { StackStoreApi } from '../core/store/create-store.js';
 import type { PageCell } from '../core/types.js';
 import { type FrameProps } from './cell-view.js';
@@ -38,6 +39,11 @@ export type RendererEnvironment = {
     onCellError?: (cellId: string, error: Error) => void;
     /** A cell's prop reference resolved to nothing (a binding the page gets wrong). */
     onUnresolvedReference?: (cellId: string, ref: string) => void;
+    /**
+     * Each rendered cell's props, leaf by leaf, with where each value came from (INV-DOC-6): what
+     * the edit layer maps to a write function with `editTarget`. Called as each cell renders.
+     */
+    onPropSources?: (cell: EditCell, sources: PropSourceEntry[]) => void;
     /** Reads the page again: a cell whose data or bundle failed offers it as "Try again" (shell audit S1). */
     retry?: () => void;
     /** Extra attributes and style for each cell's frame, e.g. a print policy the host doesn't apply yet. */

package/dist/types/runtime/install.d.ts

@@ -1,12 +1,18 @@
 import { READY_GLOBAL, RESOLVE_GLOBAL, RUNTIME_GLOBAL, type RuntimeSpecifier } from '@peripheries/runtime';
-export type StackRuntime = Record<RuntimeSpecifier, unknown> & Record<string, unknown>;
+/** `@peripheries/ui` is lent by the host (`extra`), not installed by the renderer. */
+export type StackRuntime = Record<Exclude<RuntimeSpecifier, '@peripheries/ui'>, unknown> & Record<string, unknown>;
 type RuntimeGlobals = {
     [RUNTIME_GLOBAL]?: StackRuntime;
     [READY_GLOBAL]?: Promise<void>;
     [RESOLVE_GLOBAL]?: () => void;
     require?: (specifier: string) => unknown;
 };
-export declare function buildRuntime(): StackRuntime;
+/**
+ * The host's module instances by specifier. `extra` is what the host lends beyond the
+ * renderer's own (`@peripheries/ui`), so the published renderer depends on nothing it
+ * doesn't install itself.
+ */
+export declare function buildRuntime(extra?: Record<string, unknown>): StackRuntime;
 /**
  * Puts the host's module instances where the `/_shared/*.js` shims look for
  * them, and releases every shim waiting on the boot promise. Idempotent.
@@ -16,5 +22,5 @@ export declare function buildRuntime(): StackRuntime;
  * at module init, which throws in a browser without it. The runtime modules
  * are already loaded, so it answers synchronously.
  */
-export declare function installRuntime(g?: RuntimeGlobals): StackRuntime;
+export declare function installRuntime(g?: RuntimeGlobals, extra?: Record<string, unknown>): StackRuntime;
 export { runtimeReady } from '../core/bundles/load.js';

package/dist/types/testing/components.d.ts

@@ -14,7 +14,7 @@ type SectionMaps = {
 export declare function Masthead({ title, subtitle }: Props): import("react").JSX.Element;
 /** Authored text arrives as `children` unless the cell has child cells. */
 export declare function Prose({ children }: Props): import("react").JSX.Element;
-/** A section body in the style of acrc's DocumentSection: it owns its section's anchor. */
+/** A section body in the style of an org bundle's DocumentSection: it owns its section's anchor. */
 export declare function DocumentSection({ sectionId, title, body, blocks, children, sectionNumbers, sectionAnchors }: Props & SectionMaps): import("react").JSX.Element;
 /** A same-page citation: `§<number> <title>`, plus the clause's letter when it names one. */
 export declare function SectionReference({ to, sectionReferences }: Props & SectionMaps): import("react").JSX.Element;