superdoc 2.2.1 → 2.4.0-next.1

package/dist/layout-engine/painters/dom/src/paragraph-hash-utils.d.ts

@@ -0,0 +1,13 @@
+import { ParagraphBorders, ParagraphBorder, TableBorders, TableBorderValue, CellBorders, BorderSpec } from '../../../contracts/src/index.js';
+/**
+ * Hash helpers are duplicated from layout-bridge to avoid a circular dependency
+ * (layout-bridge imports DOM_CLASS_NAMES from painter-dom). Keep these helpers
+ * in sync with layout-bridge when formatting changes need cache invalidation.
+ */
+export declare const hashParagraphBorder: (border: ParagraphBorder) => string;
+export declare const hashParagraphBorders: (borders: ParagraphBorders) => string;
+export declare const hashBorderSpec: (border: BorderSpec) => string;
+export declare const hashTableBorderValue: (borderValue: TableBorderValue | undefined) => string;
+export declare const hashTableBorders: (borders: TableBorders | undefined) => string;
+export declare const hashCellBorders: (borders: CellBorders | undefined) => string;
+export { getRunBooleanProp, getRunNumberProp, getRunStringProp, getRunUnderlineColor, getRunUnderlineStyle, hasBooleanProp, hasNumberProp, hasStringProp, } from './runs/hash.js';

package/dist/layout-engine/painters/dom/src/persistent-page-surface.d.ts

@@ -0,0 +1,144 @@
+import { DocumentBackground, ResolvedPage } from '../../../contracts/src/index.js';
+import { PageContentContext, PageDomState, PaintWorkSummary } from './page-content.js';
+/**
+ * One exact page band of the committed scaffold (numbers-only,
+ * serializable). Structurally compatible with the host pipeline's
+ * `PageScaffoldPage` so a host scaffold's `pages` array — including a lazy
+ * incremental one — is passed through zero-copy.
+ */
+export type DomPainterPersistentScaffoldPage = {
+    index: number;
+    /** Prefix-sum offset of the page's top edge from the document top. */
+    topPx: number;
+    heightPx: number;
+    widthPx: number;
+    /**
+     * Physical page number for the shell's `data-page-number` stamp (page
+     * numbering can restart per section, so it is data, never `index + 1`).
+     * Optional: absent bands leave the stamp to content hydration — the
+     * painter reports, it never invents.
+     */
+    pageNumber?: number;
+};
+/**
+ * The immutable generation-scoped page scaffold. Reference identity IS the
+ * commit identity: the host builds one scaffold object per committed layout
+ * generation and passes the same object to every same-generation content
+ * paint, so the painter's same-generation skip is O(1).
+ */
+export type DomPainterPersistentScaffold = {
+    /** Layout generation that produced this scaffold (the torn-generation fence). */
+    generation: number;
+    pageCount: number;
+    /**
+     * Uniform inter-page gap in px. The persistent surface owns the vertical
+     * rhythm through the mount's flex `gap`, never through spacer nodes, so
+     * `topPx` must equal the prefix sum of heights plus `gapPx` per boundary.
+     */
+    gapPx: number;
+    /** `last.topPx + last.heightPx`; `0` for an empty document. No trailing gap. */
+    totalHeightPx: number;
+    /** Ascending by `index`; `index` must equal the array position. */
+    pages: readonly DomPainterPersistentScaffoldPage[];
+};
+/**
+ * Read-only exact-packet lookup. A `ReadonlyMap<number, ResolvedPage>`
+ * satisfies it; so does a thin facade over a lazily-resolved page array —
+ * the painter reads only the desired content pages, so untouched document
+ * tails are never materialized by a paint.
+ */
+export interface DomPainterPersistentPacketSource {
+    get(pageIndex: number): ResolvedPage | undefined;
+}
+/**
+ * The one paginated reconcile input (plan §Target Architecture). Shells
+ * always cover the whole scaffold; only the desired content set is bounded.
+ */
+export type DomPainterPersistentPageInput = {
+    scaffold: DomPainterPersistentScaffold;
+    /** Pages whose content must be hydrated (visible window + overscan). */
+    desiredContentPageIndices: readonly number[];
+    /** Interaction pins that must stay hydrated regardless of the window. */
+    pinnedContentPageIndices?: readonly number[];
+    /**
+     * Exact resolved packets by page index, consumed only for desired content
+     * pages. A packet stamped with a different layout epoch than
+     * `scaffold.generation` is a torn generation and fails before DOM
+     * mutation; so does packet page geometry that disagrees with the band.
+     */
+    packetsByPageIndex: DomPainterPersistentPacketSource;
+    sectionPageCounts?: Readonly<Record<string, number>>;
+    documentBackground?: DocumentBackground | null;
+    captureSnapshot?: boolean;
+};
+/** Shell registry entry: the persistent page root and its geometry/style reuse key. */
+export type PersistentShellEntry = {
+    element: HTMLElement;
+    shellKey: string;
+};
+/** Bounded content state for one hydrated page. */
+export type PersistentContentEntry = {
+    state: PageDomState;
+    versionKey: string | null;
+    sdtLabels: ReadonlySet<string>;
+};
+type PersistentSurfaceIntegrity = {
+    dirty: boolean;
+    observer: MutationObserver | null;
+    onInvalidated: () => void;
+};
+/** The retained persistent-surface state the painter snapshots and restores. */
+export type PersistentPageSurfaceState = {
+    mount: HTMLElement;
+    /** The committed scaffold; reference identity gates the O(1) skip. */
+    scaffold: DomPainterPersistentScaffold;
+    shells: Map<number, PersistentShellEntry>;
+    content: Map<number, PersistentContentEntry>;
+    integrity: PersistentSurfaceIntegrity;
+};
+/**
+ * The narrow renderer capabilities this module consumes. The deep
+ * fragment/decoration render call graph stays on the painter class and is
+ * reached through the `PageContentContext` it builds.
+ */
+export interface PersistentSurfaceRenderContext {
+    contentContext: PageContentContext;
+    work: PaintWorkSummary;
+    recordPageWork(kind: PersistentPageWorkKind, pageIndex: number): void;
+    /** Read-and-consume the provider-change decorations-dirty flag. */
+    consumeDecorationsDirty(): boolean;
+    /**
+     * Signature of every non-geometry input to the shell's visual styles
+     * (document background, page-style overrides). Folded into the shell reuse
+     * key so a rare document-presentation change refreshes retained roots
+     * while steady generations skip all shell attribute writes.
+     */
+    shellStyleSignature: string;
+    /** Wake the host's canonical planner when foreign DOM work corrupts page roots. */
+    onIntegrityInvalidated: () => void;
+}
+export type PersistentPageWorkKind = 'createdPersistentPageIndices' | 'removedPersistentPageIndices' | 'patchedContentPageIndices' | 'untouchedContentPageIndices' | 'decorationRefreshedContentPageIndices' | 'remappedContentPageIndices' | 'pmDemotedContentPageIndices' | 'hydratedContentPageIndices' | 'dehydratedContentPageIndices';
+/**
+ * Fail-closed scaffold validation: a scaffold is exact geometry or it is
+ * nothing. The prefix-sum pin also proves the flex-gap layout reproduces the
+ * scaffold offsets exactly, which is what lets the surface drop spacers.
+ */
+export declare function validatePersistentScaffold(scaffold: DomPainterPersistentScaffold): void;
+/** Resolve the validated, deduplicated, ascending desired content set. */
+export declare function resolveDesiredContentPageIndices(input: DomPainterPersistentPageInput): number[];
+/**
+ * Read the live shell-plane integrity without mutating page content. The host
+ * uses this before its zero-work skip so external child-list corruption can
+ * never strand the camera over a missing page until some unrelated repaint.
+ */
+export declare function isPersistentPageSurfaceIntact(state: PersistentPageSurfaceState | null): boolean;
+export declare function disposePersistentPageSurfaceState(state: PersistentPageSurfaceState | null): void;
+/**
+ * The one persistent paginated reconcile. Same-scaffold calls skip shell
+ * work in O(1) (reference identity); scaffold identity changes rebuild the
+ * shell registry by page index; the content window reconciles every call.
+ */
+export declare function reconcilePersistentPageSurface(ctx: PersistentSurfaceRenderContext, previous: PersistentPageSurfaceState | null, input: DomPainterPersistentPageInput, mount: HTMLElement): PersistentPageSurfaceState;
+/** Deep-clone the retained planes for the painter's rollback snapshot. */
+export declare function clonePersistentPageSurfaceState(state: PersistentPageSurfaceState | null, clonePageState: (pageState: PageDomState) => PageDomState): PersistentPageSurfaceState | null;
+export {};

package/dist/layout-engine/painters/dom/src/pm-position-validation.d.ts

@@ -0,0 +1,149 @@
+import { LayoutStoryKind, LayoutStoryLocator } from '../../../contracts/src/index.js';
+/**
+ * Which editor coordinate model the host is painting under. The host owns this
+ * choice; the painter never infers editor semantics from the presence of a
+ * number.
+ *
+ * - `legacy-pm`: v1 input — every text-bearing run requires a document-global
+ *   `pmStart`/`pmEnd` span.
+ * - `editor-neutral-story`: v2 — body runs still carry compatibility PM spans
+ *   during migration, but named stories (headers/footers/notes/textboxes) are
+ *   addressed by story identity, not a body PM offset.
+ */
+export type PaintCoordinateModel = 'legacy-pm' | 'editor-neutral-story';
+/** The coordinate obligation a single run must satisfy, once classified. */
+export type RunCoordinateRequirement = 'legacy-pm-required' | 'story-identity-required' | 'visual-only' | 'not-addressable';
+/** Console verbosity. `off` is production and the performance `--quiet` mode. */
+export type PositionValidationConsolePolicy = 'off' | 'summary' | 'verbose';
+/** Which painter produced the observation (kept isolated per painter instance). */
+export type PaintKind = 'persistent-page' | 'persistent-page-oracle' | 'semantic';
+/** Execution realm, for cross-realm report comparison. */
+export type PaintRealm = 'node-headless' | 'browser-inline' | 'browser-worker' | 'product';
+export type PositionValidationSection = 'body' | 'header' | 'footer';
+export type PositionRunKind = 'text' | 'image' | 'field' | 'math';
+/** Structural issue codes. None carry content. */
+export type PositionValidationCode = 'missing-start' | 'missing-end' | 'missing-both' | 'invalid-range' | 'identity-missing' | 'story-section-mismatch' | 'unexpected-story';
+/**
+ * The content-free structural tuple that keys aggregation and is echoed in
+ * `unexpectedKeys`. Every field is a small enum or boolean — never an id or
+ * text.
+ */
+export interface PositionValidationStructuralKey {
+    coordinateModel: PaintCoordinateModel;
+    requirement: RunCoordinateRequirement;
+    storyKind: LayoutStoryKind;
+    storyNamed: boolean;
+    section: PositionValidationSection;
+    runKind: PositionRunKind;
+    code?: PositionValidationCode;
+}
+export interface PositionValidationGroupRow extends PositionValidationStructuralKey {
+    checked: number;
+    valid: number;
+    issues: number;
+}
+export interface PositionValidationRequirementTally {
+    checked: number;
+    valid: number;
+    issues: number;
+}
+/**
+ * Bounded, content-free snapshot of one painter's validation coverage since the
+ * last consume. Safe to serialize into a performance report.
+ */
+export interface PositionValidationSummary {
+    enabled: boolean;
+    coordinateModel: PaintCoordinateModel;
+    paintKind: PaintKind;
+    realm: PaintRealm;
+    /** Total runs observed. */
+    checked: number;
+    /** Runs that met their requirement. */
+    valid: number;
+    /** Runs that failed their requirement (checked - valid). */
+    issues: number;
+    issuesByCode: Record<PositionValidationCode, number>;
+    byRequirement: Record<RunCoordinateRequirement, PositionValidationRequirementTally>;
+    /** Distinct verbose lines withheld after the verbose cap was reached. */
+    suppressedConsole: number;
+    /** Distinct structural groups seen (<= MAX_GROUPS retained). */
+    groupCount: number;
+    /** Run observations not retained after MAX_GROUPS distinct keys (still counted in totals). */
+    groupsOverflowed: number;
+    /** Aggregate rows, capped at MAX_GROUPS, most-issues first. */
+    groups: PositionValidationGroupRow[];
+    /** First unexpected (issue-bearing) structural keys, capped and content-free. */
+    unexpectedKeys: PositionValidationStructuralKey[];
+}
+/** A single run's content-free observation, handed to the collector. */
+export interface RunPositionObservation {
+    runKind: PositionRunKind;
+    section: PositionValidationSection;
+    story?: LayoutStoryLocator;
+    pmStart?: number | null;
+    pmEnd?: number | null;
+    /**
+     * True for render-only dynamic display text (PAGE / NUMPAGES / section-page
+     * fields) that mints no editable coordinate. Such runs are `visual-only`.
+     */
+    renderOnly?: boolean;
+}
+export interface PositionValidationOptions {
+    /** Dark by default; the perf harness enables it for its proof. */
+    enabled?: boolean;
+    /** Host-selected coordinate model. Defaults to the strict `legacy-pm`. */
+    coordinateModel?: PaintCoordinateModel;
+    /** Console policy. Defaults to `off` (counters only). */
+    policy?: PositionValidationConsolePolicy;
+    /** Which painter this is; keeps oracle and product coverage separable. */
+    paintKind?: PaintKind;
+    /** Execution realm for report comparison. */
+    realm?: PaintRealm;
+}
+/**
+ * Derive the story kind used for classification and reporting. The story
+ * locator, when present, is authoritative; otherwise we fall back to the paint
+ * section. Never defaults an absent-yet-non-body story to `body`.
+ */
+export declare const resolveStoryKind: (section: PositionValidationSection, story: LayoutStoryLocator | undefined) => LayoutStoryKind;
+/**
+ * Pure classification: which coordinate obligation does this run carry?
+ * Exported for unit testing.
+ */
+export declare const classifyRequirement: (coordinateModel: PaintCoordinateModel, storyKind: LayoutStoryKind, renderOnly: boolean) => RunCoordinateRequirement;
+/**
+ * Painter-scoped collector. One instance per `DomPainter`. Bounded memory:
+ * counters are O(1), the group map is capped at MAX_GROUPS, and no per-run
+ * event array is ever retained.
+ */
+export declare class PositionValidationCollector {
+    private readonly enabled;
+    private readonly coordinateModel;
+    private readonly policy;
+    private readonly paintKind;
+    private readonly realm;
+    private groups;
+    private groupsOverflowed;
+    private checked;
+    private valid;
+    private issues;
+    private issuesByCode;
+    private byRequirement;
+    private unexpectedKeys;
+    private unexpectedKeysSeen;
+    private verboseKeysSeen;
+    private verboseLines;
+    private suppressedConsole;
+    constructor(options?: PositionValidationOptions);
+    get isEnabled(): boolean;
+    record(obs: RunPositionObservation): void;
+    /** Verbose-mode: one content-free warning per NEW structural key, capped. */
+    private emitVerbose;
+    /** Drain and reset. The documented pass boundary. */
+    consume(): PositionValidationSummary;
+    /** Read without draining (for assertions / mid-run inspection). */
+    peek(): PositionValidationSummary;
+    private buildSummary;
+    private reset;
+}
+export declare const createPositionValidationCollector: (options?: PositionValidationOptions) => PositionValidationCollector;