superdoc 2.2.0 → 2.3.0

package/dist/layout-engine/painters/dom/src/features/math/converters/phantom.d.ts

@@ -0,0 +1,17 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:phant (phantom) to MathML <mphantom> or styled <mpadded>.
+ *
+ * OMML structure:
+ *   m:phant → m:phantPr (optional: m:show, m:zeroWid, m:zeroAsc, m:zeroDesc), m:e (content)
+ *
+ * MathML output:
+ *   Full phantom (default): <mphantom> content </mphantom>
+ *   Visible with zeroed dimensions: <mpadded> with width/height/depth="0"
+ *
+ * A phantom reserves the space its content would occupy but renders invisibly.
+ * Property flags can zero-out individual dimensions or force visibility.
+ *
+ * @spec ECMA-376 §22.1.2.81
+ */
+export declare const convertPhantom: MathObjectConverter;

package/dist/layout-engine/painters/dom/src/features/math/converters/pre-sub-superscript.d.ts

@@ -0,0 +1,25 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:sPre (pre-sub-superscript) to MathML <mmultiscripts>.
+ *
+ * OMML structure:
+ *   m:sPre → m:sPrePr (optional), m:sub (subscript), m:sup (superscript), m:e (base)
+ *
+ * Note: element order differs from m:sSubSup — in m:sPre the base (m:e) is the
+ * LAST child, not the first. The converter uses tag-based lookup (not position)
+ * so any order is accepted.
+ *
+ * MathML output:
+ *   <mmultiscripts>
+ *     <mrow>base</mrow>
+ *     <mprescripts/>
+ *     <mrow>sub</mrow>
+ *     <mrow>sup</mrow>
+ *   </mmultiscripts>
+ *
+ * The <mprescripts/> separator tells MathML that the scripts that follow
+ * are placed to the left of the base rather than to the right.
+ *
+ * @spec ECMA-376 §22.1.2.99
+ */
+export declare const convertPreSubSuperscript: MathObjectConverter;

package/dist/layout-engine/painters/dom/src/features/math/converters/radical.d.ts

@@ -0,0 +1,14 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:rad (radical) to MathML <msqrt> or <mroot>.
+ *
+ * OMML structure:
+ *   m:rad → m:radPr (optional: m:degHide), m:deg (degree), m:e (radicand)
+ *
+ * MathML output:
+ *   - degree hidden → <msqrt><mrow>radicand</mrow></msqrt>
+ *   - degree shown  → <mroot><mrow>radicand</mrow><mrow>degree</mrow></mroot>
+ *
+ * @spec ECMA-376 §22.1.2.88
+ */
+export declare const convertRadical: MathObjectConverter;

package/dist/layout-engine/painters/dom/src/features/math/converters/sub-superscript.d.ts

@@ -0,0 +1,13 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:sSubSup (sub-superscript) to MathML <msubsup>.
+ *
+ * OMML structure:
+ *   m:sSubSup → m:sSubSupPr (optional), m:e (base), m:sub (subscript), m:sup (superscript)
+ *
+ * MathML output:
+ *   <msubsup> <mrow>base</mrow> <mrow>sub</mrow> <mrow>sup</mrow> </msubsup>
+ *
+ * @spec ECMA-376 §22.1.2.103
+ */
+export declare const convertSubSuperscript: MathObjectConverter;

package/dist/layout-engine/painters/dom/src/features/math/converters/subscript.d.ts

@@ -0,0 +1,13 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:sSub (subscript) to MathML <msub>.
+ *
+ * OMML structure:
+ *   m:sSub → m:sSubPr (optional), m:e (base), m:sub (subscript)
+ *
+ * MathML output:
+ *   <msub> <mrow>base</mrow> <mrow>sub</mrow> </msub>
+ *
+ * @spec ECMA-376 §22.1.2.101
+ */
+export declare const convertSubscript: MathObjectConverter;

package/dist/layout-engine/painters/dom/src/features/math/converters/superscript.d.ts

@@ -0,0 +1,13 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:sSup (superscript) to MathML <msup>.
+ *
+ * OMML structure:
+ *   m:sSup → m:sSupPr (optional), m:e (base), m:sup (superscript)
+ *
+ * MathML output:
+ *   <msup> <mrow>base</mrow> <mrow>sup</mrow> </msup>
+ *
+ * @spec ECMA-376 §22.1.2.105
+ */
+export declare const convertSuperscript: MathObjectConverter;

package/dist/layout-engine/painters/dom/src/features/math/converters/upper-limit.d.ts

@@ -0,0 +1,13 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:limUpp (upper limit) to MathML <mover>.
+ *
+ * OMML structure:
+ *   m:limUpp → m:limUppPr (optional), m:e (base), m:lim (limit expression placed above)
+ *
+ * MathML output:
+ *   <mover> <mrow>base</mrow> <mrow>lim</mrow> </mover>
+ *
+ * @spec ECMA-376 §22.1.2.56
+ */
+export declare const convertUpperLimit: MathObjectConverter;

package/dist/layout-engine/painters/dom/src/features/math/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Math Formula — rendering feature module
+ *
+ * Converts OMML (Office Math Markup Language) to MathML for browser-native rendering.
+ * Uses a registry pattern so each OMML math object type can be implemented independently.
+ *
+ * @ooxml m:oMath — inline math zone
+ * @ooxml m:oMathPara — display math paragraph
+ * @ooxml m:r, m:t — math runs and text
+ * @ooxml m:f, m:rad, m:sSup, m:sSub, m:d, m:nary, m:m, ... — math objects (18 types)
+ * @spec ECMA-376 §22.1 (Math)
+ */
+export { convertOmmlToMathml, registerMathObjectConverter, MATHML_NS } from './omml-to-mathml.js';
+export type { OmmlJsonNode, MathObjectConverter } from './types.js';

package/dist/layout-engine/painters/dom/src/features/math/omml-to-mathml.d.ts

@@ -0,0 +1,18 @@
+import { MathObjectConverter } from './types.js';
+export declare const MATHML_NS = "http://www.w3.org/1998/Math/MathML";
+/**
+ * Convert an OMML JSON tree to a MathML <math> DOM element.
+ *
+ * @param ommlJson - The OMML JSON tree (from a mathInline or mathBlock node's originalXml)
+ * @param doc - The document object for creating DOM elements
+ * @returns A <math> element ready to be inserted into the DOM, or null if conversion fails
+ */
+export declare function convertOmmlToMathml(ommlJson: unknown, doc: Document): Element | null;
+/**
+ * Register a converter for an OMML math object type.
+ * Used by community contributors to add support for individual math objects.
+ *
+ * @param elementName - The OMML element name (e.g., 'm:f', 'm:rad')
+ * @param converter - The converter function
+ */
+export declare function registerMathObjectConverter(elementName: string, converter: MathObjectConverter): void;

package/dist/layout-engine/painters/dom/src/features/math/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Represents an OMML XML node in the xml2json format used by SuperDoc's converter.
+ */
+export type OmmlJsonNode = {
+    /** Element name (e.g., 'm:oMath', 'm:f', 'm:r') */
+    name?: string;
+    /** Node type ('element', 'text', etc.) */
+    type?: string;
+    /** XML attributes (e.g., { 'm:val': 'center' }) */
+    attributes?: Record<string, string>;
+    /** Child elements */
+    elements?: OmmlJsonNode[];
+    /** Text content (for text nodes) */
+    text?: string;
+};
+/**
+ * Converter function for a single OMML math object.
+ *
+ * Community contributors implement this interface to add support for
+ * individual math objects (fractions, radicals, matrices, etc.).
+ *
+ * @param node - The OMML JSON node to convert (e.g., an m:f element)
+ * @param doc - The document object for creating MathML elements
+ * @param convertChildren - Recursive converter for child OMML elements.
+ *   Call this to convert nested math content (arguments like m:e, m:num, m:den).
+ * @returns A MathML DOM element, or null to fall back to text extraction
+ *
+ * @example
+ * ```typescript
+ * // Implementing m:f (fraction) → <mfrac>
+ * const convertFraction: MathObjectConverter = (node, doc, convertChildren) => {
+ *   const num = node.elements?.find(e => e.name === 'm:num');
+ *   const den = node.elements?.find(e => e.name === 'm:den');
+ *   const frac = doc.createElementNS(MATHML_NS, 'mfrac');
+ *   frac.appendChild(convertChildren(num?.elements ?? []));
+ *   frac.appendChild(convertChildren(den?.elements ?? []));
+ *   return frac;
+ * };
+ * ```
+ */
+export type MathObjectConverter = (node: OmmlJsonNode, doc: Document, convertChildren: (children: OmmlJsonNode[]) => DocumentFragment) => Node | null;

package/dist/layout-engine/painters/dom/src/images/drawing-image.d.ts

@@ -0,0 +1,5 @@
+import { DrawingBlock, ShapeGroupChild, TextPart } from '../../../../contracts/src/index.js';
+import { BuildImageHyperlinkAnchor } from './types.js';
+export declare const createDrawingImageElement: (doc: Document, block: DrawingBlock, buildImageHyperlinkAnchor: BuildImageHyperlinkAnchor) => HTMLElement;
+export declare const createShapeGroupImageElement: (doc: Document, child: ShapeGroupChild) => HTMLElement;
+export declare const createShapeTextImageElement: (doc: Document, part: TextPart) => HTMLElement;

package/dist/layout-engine/painters/dom/src/images/hyperlink.d.ts

@@ -0,0 +1,2 @@
+import { ImageHyperlink } from '../../../../contracts/src/index.js';
+export declare const buildImageHyperlinkAnchor: (doc: Document, imageEl: HTMLElement, hyperlink: ImageHyperlink | undefined, display: "block" | "inline-block") => HTMLElement;

package/dist/layout-engine/painters/dom/src/images/image-block.d.ts

@@ -0,0 +1,15 @@
+import { ImageBlock, ImageDrawing } from '../../../../contracts/src/index.js';
+import { BuildImageHyperlinkAnchor } from './types.js';
+type BlockImageSource = ImageBlock | ImageDrawing;
+export type CreateBlockImageContentOptions = {
+    doc: Document;
+    block: BlockImageSource;
+    className?: string;
+    clipContainer?: HTMLElement;
+    imageDisplay?: 'block' | 'inline-block';
+    hyperlinkDisplay?: 'block' | 'inline-block';
+    buildImageHyperlinkAnchor?: BuildImageHyperlinkAnchor;
+};
+export declare const resolveBlockImageClipPath: (block: unknown) => string;
+export declare const createBlockImageContent: ({ doc, block, className, clipContainer, imageDisplay, hyperlinkDisplay, buildImageHyperlinkAnchor, }: CreateBlockImageContentOptions) => HTMLElement;
+export {};

package/dist/layout-engine/painters/dom/src/images/image-clip-path.d.ts

@@ -0,0 +1,17 @@
+export declare const readImageClipPathValue: (value: unknown) => string;
+/**
+ * Resolves a clip-path value to a trimmed non-empty string, or undefined if invalid.
+ */
+export declare function resolveClipPath(value: unknown): string | undefined;
+/**
+ * Applies clip-path and optional scale/translate (for inset() srcRect) to an element.
+ * When the clipPath is inset(top% right% bottom% left%), also sets transform so the
+ * visible portion fills the element and is aligned to top-left.
+ *
+ * When `options.clipContainer` is provided, `overflow: hidden` is set on it so the
+ * scaled image doesn't paint outside its layout box.  This pairs the two operations
+ * that are always needed together for cropped images.
+ */
+export declare function applyImageClipPath(el: HTMLElement, clipPath: unknown, options?: {
+    clipContainer?: HTMLElement;
+}): void;

package/dist/layout-engine/painters/dom/src/images/image-fragment.d.ts

@@ -0,0 +1,34 @@
+import { ImageFragment, ResolvedImageItem, SdtMetadata } from '../../../../contracts/src/index.js';
+import { FragmentRenderContext } from '../renderer.js';
+import { BuildImageHyperlinkAnchor } from './types.js';
+import { TrackedChangesRenderConfig } from '../runs/types.js';
+type RenderImageFragmentOptions = {
+    doc: Document | null;
+    fragment: ImageFragment;
+    context: FragmentRenderContext;
+    resolvedItem?: ResolvedImageItem;
+    applyResolvedFragmentFrame: (el: HTMLElement, item: ResolvedImageItem, fragment: ImageFragment, section?: 'body' | 'header' | 'footer') => void;
+    applyFragmentFrame: (el: HTMLElement, fragment: ImageFragment, section?: 'body' | 'header' | 'footer') => void;
+    applyFragmentWrapperZIndex: (el: HTMLElement, fragment: ImageFragment) => void;
+    applySdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    applyContainerSdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    buildImageHyperlinkAnchor: BuildImageHyperlinkAnchor;
+    createErrorPlaceholder: (blockId: string, error: unknown) => HTMLElement;
+    trackedConfig: TrackedChangesRenderConfig;
+};
+export declare const buildImageGeometryTransform: (attrs: {
+    width: number;
+    height: number;
+    rotation?: number;
+    flipH?: boolean;
+    flipV?: boolean;
+}) => string;
+export declare const applyImageGeometryTransform: (target: HTMLElement, attrs: {
+    width: number;
+    height: number;
+    rotation?: number;
+    flipH?: boolean;
+    flipV?: boolean;
+}) => void;
+export declare const renderImageFragment: ({ doc, fragment, context, resolvedItem, applyResolvedFragmentFrame, applyFragmentFrame, applyFragmentWrapperZIndex, applySdtDataset, applyContainerSdtDataset, buildImageHyperlinkAnchor, createErrorPlaceholder, trackedConfig, }: RenderImageFragmentOptions) => HTMLElement;
+export {};

package/dist/layout-engine/painters/dom/src/images/image-selectors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Image Selector Helpers — Compatibility Re-exports
+ *
+ * The source of truth for these helpers is now `@superdoc/dom-contract`.
+ * These re-exports exist so that existing `painter-dom` consumers continue
+ * to work without import changes. New code should import from
+ * `@superdoc/dom-contract` directly.
+ */
+export { buildImagePmSelector, buildInlineImagePmSelector } from '../../../../dom-contract/src/index.js';

package/dist/layout-engine/painters/dom/src/images/types.d.ts

@@ -0,0 +1,2 @@
+import { ImageHyperlink } from '../../../../contracts/src/index.js';
+export type BuildImageHyperlinkAnchor = (imageEl: HTMLElement, hyperlink: ImageHyperlink | undefined, display: 'block' | 'inline-block') => HTMLElement;

package/dist/layout-engine/painters/dom/src/index.d.ts

@@ -0,0 +1,125 @@
+import { PaintWorkSummary } from './page-content.js';
+import { PageStyles } from './styles.js';
+import { PositionValidationOptions, PositionValidationSummary } from './pm-position-validation.js';
+import { DomPainterInput, DomPainterPageWindowInput, PageDecorationProvider, PaintSnapshot, PositionMapping, FlowMode } from './renderer.js';
+export { DOM_CLASS_NAMES } from './constants.js';
+export type { DomClassName } from './constants.js';
+export { ensureDocumentSurfaceStyles } from './styles.js';
+export { SURFACE_STYLE_PREFLIGHT, ensureSurfaceStylePreflight } from './styles.js';
+export type { SurfaceStylePreflightEntry } from './styles.js';
+export { generateRulerDefinition, generateRulerDefinitionFromPx, createRulerElement, ensureRulerStyles, clampHandlePosition, calculateMarginFromHandle, RULER_CLASS_NAMES, } from './ruler/index.js';
+export type { RulerDefinition, RulerConfig, RulerConfigPx, RulerTick, CreateRulerElementOptions, } from './ruler/index.js';
+export type { PaintSnapshot, PaintSnapshotAnnotationEntity, PaintSnapshotStructuredContentBlockEntity, PaintSnapshotStructuredContentInlineEntity, PaintSnapshotImageEntity, PaintSnapshotEntities, } from './renderer.js';
+export type { DomPainterInput, PositionMapping } from './renderer.js';
+export type { DomPainterPageWindowExactness, DomPainterPageWindowExtent, DomPainterPageWindowInput, DomPainterPageWindowPacket, } from './renderer.js';
+export type { PaintWorkSummary } from './page-content.js';
+export type { RenderedLineInfo } from './runs/index.js';
+export { sanitizeUrl, linkMetrics, applyRunDataAttributes } from './runs/index.js';
+export { applySquareWrapExclusionsToLines } from './utils/anchor-helpers.js';
+export { buildImagePmSelector, buildInlineImagePmSelector } from './images/image-selectors.js';
+export { createPositionValidationCollector, PositionValidationCollector } from './pm-position-validation.js';
+export type { PaintCoordinateModel, RunCoordinateRequirement, PositionValidationConsolePolicy, PaintKind, PaintRealm, PositionValidationSection, PositionRunKind, PositionValidationCode, PositionValidationStructuralKey, PositionValidationGroupRow, PositionValidationRequirementTally, PositionValidationSummary, PositionValidationOptions, RunPositionObservation, } from './pm-position-validation.js';
+/**
+ * Painter plan P7: `'vertical'` is the only paginated arrangement (horizontal
+ * and book modes deleted, product decision 2026-07-05). The presentation axis
+ * is `FlowMode` (`'paginated' | 'semantic'`); this type remains for API-shape
+ * compatibility.
+ */
+export type LayoutMode = 'vertical';
+export type { FlowMode } from './renderer.js';
+export type { PageDecorationPayload, PageDecorationProvider } from './renderer.js';
+export type DomPainterOptions = {
+    pageStyles?: PageStyles;
+    layoutMode?: LayoutMode;
+    flowMode?: FlowMode;
+    /** Gap between pages in pixels (default: 24px) */
+    pageGap?: number;
+    headerProvider?: PageDecorationProvider;
+    footerProvider?: PageDecorationProvider;
+    /** Called with the paint snapshot after each paint cycle completes. */
+    onPaintSnapshot?: (snapshot: PaintSnapshot) => void;
+    /** Render nonprinting formatting marks such as spaces, tabs, and paragraph marks. */
+    showFormattingMarks?: boolean;
+    /** Built-in SDT chrome rendering mode. */
+    contentControlsChrome?: 'default' | 'none';
+    /**
+     * Per-document logical->physical font resolver (a CSS-stack resolver). The painter paints each
+     * run in the family this returns - e.g. Carlito for Calibri - the SAME family measurement used,
+     * so glyph advances match the laid-out positions. Set per painter instance (per document) so two
+     * editors can map one logical family differently. Defaults to the global bundled resolver.
+     */
+    resolvePhysical?: (cssFontFamily: string, face: {
+        weight: '400' | '700';
+        style: 'normal' | 'italic';
+    }) => string;
+    /**
+     * Painter plan P5 §4.6: populate `PaintWorkSummary`'s per-page index arrays
+     * (which pages mounted/unmounted/rebuilt/untouched/remapped). Dark by
+     * default — counters stay O(1) always, but the arrays grow per paint and
+     * are only drained by `consumePaintWorkSummary()`, which product code never
+     * calls; the perf harness enables this for its repaint oracle.
+     */
+    paintWorkAttribution?: boolean;
+    /**
+     * Story-aware position-coverage validation. Dark by default: when omitted or
+     * `{ enabled: false }`, the painter records nothing and `record()` is a single
+     * branch with no allocation. The performance harness enables it (with an
+     * explicit `off | summary | verbose` console policy — never `NODE_ENV`) and
+     * drains it via `consumePositionValidationSummary()`. Each painter instance
+     * owns its collector, so the product surface window and the dense-reference
+     * oracle never mix counts.
+     */
+    positionValidation?: PositionValidationOptions;
+};
+export type DomPainterHandle = {
+    /** Semantic flow only (painter plan P7); paginated documents use `paintPageWindow`. */
+    paint(input: DomPainterInput, mount: HTMLElement, mapping?: PositionMapping): void;
+    /** Paginated flow only (painter plan P7); a dense paint is a full-range window. */
+    paintPageWindow(input: DomPainterPageWindowInput, mount: HTMLElement): void;
+    /**
+     * Painter plan §4.6 (dark observability): page-window paint work since the
+     * last consume. Fields the path cannot attribute yet are 0/null, never
+     * invented (`domNodesCreated` stays null until node counting lands). Since
+     * P5, `pagesPositionRemapped` counts uniform in-place pm shifts on reused
+     * window DOM; the per-page index arrays are populated only when the painter
+     * was created with `paintWorkAttribution: true`.
+     */
+    consumePaintWorkSummary(): PaintWorkSummary;
+    /**
+     * Story-aware position coverage since the last consume, drained and reset.
+     * Content-free and bounded; empty (`checked: 0`) unless the painter was
+     * created with `positionValidation.enabled`.
+     */
+    consumePositionValidationSummary(): PositionValidationSummary;
+    setProviders(header?: PageDecorationProvider, footer?: PageDecorationProvider): void;
+    getMountedPageIndices(): number[];
+    setShowFormattingMarks(showFormattingMarks: boolean): void;
+    dispose(): void;
+};
+export type DenseReferencePainterHandle = DomPainterHandle & {
+    /** Proof-only sequential batch traversal; product surfaces never receive this handle. */
+    paintDensePageBatch(input: DomPainterInput, mount: HTMLElement, startPageIndex: number, endPageIndexExclusive: number): void;
+};
+/**
+ * Thin pass-through factory: instantiates DomPainter with the supplied options
+ * and returns a stable handle that exposes only the rendering-stage API.
+ *
+ * The handle accepts only `DomPainterInput` (resolvedLayout-only).
+ * Header/footer decoration providers must supply both `fragments` and `items`
+ * on their `PageDecorationPayload`.
+ *
+ * Mode ownership (painter plan P7): this handle's `paint()` REJECTS paginated
+ * flow — paginated documents have exactly one paint entry, `paintPageWindow`
+ * (a dense paint is a full-range window). Equivalence oracles and kernel spec
+ * tests that need the paginated dense REFERENCE go through
+ * {@link createDenseReferencePainter} instead.
+ *
+ * v1 EOL (product decision 2026-07-06, P7 review): the v1 PresentationEditor
+ * consumed the deleted surface (paginated `paint()`, `virtualization`/`ruler`
+ * options, `setZoom`/`setVirtualizationPins`) and gets NO compatibility shim —
+ * SuperDoc is v2-only. The staged super-editor dist is the last working v1
+ * print build; rebuilding it against this painter fails BY DESIGN, and the
+ * `mode-ownership.test.ts` battery pins the surface deleted.
+ */
+export declare const createDomPainter: (options: DomPainterOptions) => DomPainterHandle;
+export declare const createDenseReferencePainter: (options: DomPainterOptions) => DenseReferencePainterHandle;

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

@@ -0,0 +1,209 @@
+import { Fragment, FlowBlock, ResolvedPage, ResolvedPaintItem } from '../../../contracts/src/index.js';
+import { FragmentRenderContext, PositionMapping } from './renderer.js';
+import { SdtBoundaryOptions } from './sdt/container.js';
+import { BetweenBorderInfo } from './paragraph/borders/index.js';
+import { PageStyles } from './styles.js';
+export type FragmentDomState = {
+    key: string;
+    signature: string;
+    fragment: Fragment;
+    element: HTMLElement;
+    context: FragmentRenderContext;
+    /**
+     * Interior-pm signature captured from the resolved item at render/rebuild
+     * (painter plan P5). Reuse-with-pm-drift is only provably uniform when the
+     * retained and fresh keys are EQUAL; null (older retained state, missing
+     * stamp) fails closed to a rebuild.
+     */
+    pmInteriorVersion: string | null;
+    /**
+     * Whether the rendered DOM carries any `data-pm-*` attribute (root or
+     * descendant), recorded once at render/rebuild. A fragment with pm-bearing
+     * DOM but NO fragment-level pm span cannot prove position freshness and
+     * must never be reused across pm drift (anchored drawings/textboxes whose
+     * blocks lack attrs.pmStart).
+     */
+    hasPmDescendants: boolean;
+};
+export type PageDomState = {
+    element: HTMLElement;
+    fragments: FragmentDomState[];
+};
+/** Fragment-level render work performed by one `patchPage` call. */
+export type PatchPageWork = {
+    fragmentsRendered: number;
+    fragmentsReused: number;
+};
+/**
+ * Painter plan §4.6 (dark observability): work performed by the page-window
+ * paint path, accumulated across paints until consumed. Fields the path
+ * cannot attribute yet are reported as 0/null, never invented:
+ * `domNodesCreated` stays null until node counting is instrumented. Since P5,
+ * `pagesPositionRemapped` counts pages whose reused DOM had its pm attributes
+ * uniformly shifted in place (uniform fresh-shift, proven by the interior-pm
+ * signature — no transaction mapping on the window path).
+ *
+ * The per-page index arrays are populated ONLY when the painter is created
+ * with `paintWorkAttribution: true` (the perf harness's repaint oracle needs
+ * WHICH pages). Dark by default: counters are O(1) forever, but unconsumed
+ * arrays would grow per paint on the product path.
+ */
+export type PaintWorkSummary = {
+    /** Pages newly created (no prior element for the slot). */
+    pagesMounted: number;
+    /** Pages removed because they left the window. */
+    pagesUnmounted: number;
+    /** Pages whose slot survived but whose content was patched or re-rendered. */
+    pagesRebuilt: number;
+    /** Pages left completely untouched (version key match, positions unchanged). */
+    pagesUntouched: number;
+    /**
+     * Retained pages whose header/footer DOM was refreshed after provider
+     * identity changed, without mounting or rebuilding the body page. May
+     * overlap position-remapped pages; never overlaps untouched pages.
+     */
+    pagesDecorationsRefreshed: number;
+    /**
+     * Pages whose content was untouched but whose pm positions were uniformly
+     * shifted in place (painter plan P5): the resolve stamps matched while the
+     * packet-fresh fragment positions drifted — attribute remap, not rebuild.
+     */
+    pagesPositionRemapped: number;
+    /**
+     * Rebuilt pages whose resolve stamps MATCHED but whose position drift could
+     * not be proven a uniform shift (`planPmReuse` demote — e.g. a page mixing
+     * body and notes pm planes under a body edit). A demote is sound painter
+     * behavior, not a reuse regression; the repaint oracle allows exactly these
+     * rebuilds on relevance-UNCHANGED pages (P5x review fix). Always a subset
+     * of the rebuilt counters/arrays.
+     */
+    pagesPmDemoted: number;
+    fragmentsRendered: number;
+    fragmentsReused: number;
+    domNodesCreated: number | null;
+    /**
+     * Per-page attribution for the counters above (painter plan P5 §4.6): the
+     * repaint oracle's subset gates (`rebuilt ⊆ relevance-changed ∩ window`,
+     * `remapped ⊆ full-changed ∩ window`) need to know WHICH pages, not how
+     * many. Accumulated like the counters, drained on consume.
+     */
+    mountedPageIndices: number[];
+    unmountedPageIndices: number[];
+    rebuiltPageIndices: number[];
+    untouchedPageIndices: number[];
+    decorationRefreshedPageIndices: number[];
+    remappedPageIndices: number[];
+    pmDemotedPageIndices: number[];
+};
+export declare function createEmptyPaintWorkSummary(): PaintWorkSummary;
+/**
+ * Painter plan P3a: reuse key for one exact page slot on the page-window
+ * path. Joins everything the painted page DOM depends on for a fixed page
+ * index: the resolve-stage version stamp per item (the product paint-reuse
+ * mechanism), fragment identity + geometry (stamps do not cover geometry),
+ * and, only when body content contains a dynamic field, its page context.
+ * Header/footer providers have a separate decoration-only refresh path, so
+ * their context must not invalidate otherwise reusable body fragments.
+ *
+ * Returns null when any fragment item carries NO resolve stamp — reuse
+ * cannot be proven safe, so the caller must fall back to a fragment-keyed
+ * patch, never to "untouched". Inside that patch, an unstamped fragment is
+ * itself fail-closed: `patchPage` force-rebuilds any fragment whose resolve
+ * signature is empty (two missing stamps must never compare equal).
+ *
+ * Deliberately EXCLUDED: pm/story position attributes — positions are
+ * coordinates, not content, and a keystroke shifts every downstream one.
+ * Since P5 the window path REMAPS instead: a version-key-matched page whose
+ * fragment pm drifted gets an in-place uniform shift when the interior-pm
+ * signature proves the drift uniform (`planWindowPositionRemap`), and demotes
+ * to a real rebuild otherwise (the shared `planPmReuse` decision inside
+ * `patchPage`). The
+ * pass-level paint-equivalence oracle stays RAW-sha (positions kept): remap
+ * is byte-exact, so reused-then-remapped DOM must equal a fresh dense paint
+ * attribute-for-attribute — that exactness is the proof, never normalize it
+ * away at the pass level (only the §7.7 unit tests use the normalized form).
+ */
+export declare function pageWindowVersionKey(page: ResolvedPage, totalPages: number, sectionPageCount: number): string | null;
+/**
+ * The class state `renderPage`/`patchPage` consume, made explicit. The
+ * DomPainter builds one per call (values like `totalPages`, `layoutEpoch`,
+ * and `currentMapping` change between paints); the deep fragment-rendering
+ * call graph stays on the painter and is reached through the function
+ * members.
+ */
+export interface PageContentContext {
+    doc: Document;
+    layoutEpoch: number;
+    totalPages: number;
+    currentMapping: PositionMapping | null;
+    changedBlocks: ReadonlySet<string>;
+    sdtLabelsRendered: Set<string>;
+    getEffectivePageStyles(): PageStyles | undefined;
+    applySemanticPageOverrides(el: HTMLElement): void;
+    getSectionPageCount(page: ResolvedPage): number;
+    renderFragment(fragment: Fragment, context: FragmentRenderContext, sdtBoundary?: SdtBoundaryOptions, betweenInfo?: BetweenBorderInfo, resolvedItem?: ResolvedPaintItem): HTMLElement;
+    renderDecorationsForPage(pageEl: HTMLElement, page: ResolvedPage, pageIndex: number): void;
+    renderColumnSeparators(pageEl: HTMLElement, page: ResolvedPage, pageWidth: number, pageHeight: number): void;
+    updateStoryPositionAttributes(fragmentEl: HTMLElement, resolvedItem: ResolvedPaintItem | undefined): void;
+    updatePositionAttributes(fragmentEl: HTMLElement, mapping: PositionMapping): void;
+    updateFragmentElement(el: HTMLElement, fragment: Fragment, section?: 'body' | 'header' | 'footer', resolvedItem?: ResolvedPaintItem): void;
+}
+export declare function renderPage(ctx: PageContentContext, page: ResolvedPage, pageIndex: number): PageDomState;
+export declare function patchPage(ctx: PageContentContext, state: PageDomState, page: ResolvedPage, pageIndex: number): PatchPageWork;
+export declare function pageContextSignature(context: FragmentRenderContext): string;
+export declare function hasPageContextTokenInBlock(block: FlowBlock | undefined): boolean;
+export declare function needsRebuildForPageContext(currentContext: FragmentRenderContext, nextContext: FragmentRenderContext, resolvedItem: ResolvedPaintItem | undefined): boolean;
+/**
+ * Painter plan P5: shift every painted pm attribute in a fragment subtree by
+ * a KNOWN uniform delta (fresh-vs-retained fragment pmStart — exact for
+ * unchanged content, whose whole span moves together). Fragment-kind
+ * agnostic: tables, drawings, and paragraphs all carry data-pm-* on their
+ * spans, while the fresh-landmark derivation in
+ * `updateStoryPositionAttributes` only understands paragraph-shaped items
+ * (block runs / content lines) and silently no-ops for tables — the raw-sha
+ * paint-equivalence oracle caught exactly that on real table pages.
+ */
+export declare function shiftFragmentPositionAttributes(fragmentEl: HTMLElement, deltaPm: number): void;
+/** The resolve stage's interior-pm signature for this item (painter plan P5), null when unstamped. */
+export declare function resolvedPmInteriorVersion(resolvedItem: ResolvedPaintItem | undefined): string | null;
+/** Fragment-level pm span, or null when either bound is missing. */
+export declare function fragmentPmSpan(fragment: Fragment): {
+    start: number;
+    end: number;
+} | null;
+/** Whether the rendered fragment DOM carries any pm attribute (root or descendant). */
+export declare function elementHasPmAttributes(el: HTMLElement): boolean;
+/** The `pm:<count>:<hash>@<base>` interior version, split for uniformity checks. */
+export declare function pmInteriorParts(version: string | null): {
+    relative: string;
+    base: number | null;
+} | null;
+export type PmReuseDecision = {
+    kind: 'clean';
+} | {
+    kind: 'shift';
+    deltaPm: number;
+} | {
+    kind: 'rebuild';
+};
+/**
+ * Painter plan P5 (review fix): THE single soundness decision for reusing a
+ * stamp-equal fragment across pm drift without a transaction mapping —
+ * consumed by both the window remap planner and `patchPage` so the two paths
+ * can never diverge (a planner "demote" lands on a patch that applies the
+ * SAME rule and rebuilds).
+ *
+ * - `clean`: nothing to do (no pm anywhere, or absolutely identical pm).
+ * - `shift`: drift proven UNIFORM — equal span length, equal relative
+ *   interior offsets, and the interior base moved by exactly the fragment
+ *   delta. Shifting every pm attribute by `deltaPm` is byte-exact.
+ * - `rebuild`: anything unprovable — one-sided pm, span-length change,
+ *   interior redistribution (a moved PM node emits no run), a missing
+ *   interior stamp, interior drift under an equal span, or pm-bearing DOM
+ *   under a fragment with no fragment-level anchor whose interior moved.
+ */
+export declare function planPmReuse(current: Pick<FragmentDomState, 'fragment' | 'pmInteriorVersion' | 'hasPmDescendants'>, freshFragment: Fragment, freshInteriorVersion: string | null): PmReuseDecision;
+export declare function resolvedPaintCacheSignature(resolvedItem: ResolvedPaintItem | undefined): string;
+export declare const fragmentKey: (fragment: Fragment) => string;
+export declare const hasFragmentGeometryChanged: (previous: Fragment, next: Fragment) => boolean;
+export declare const isNonBodyStoryBlockId: (blockId: string | undefined) => boolean;

package/dist/layout-engine/painters/dom/src/paragraph/block-version.d.ts

@@ -0,0 +1,8 @@
+import { ParagraphAttrs, ParagraphBlock } from '../../../../contracts/src/index.js';
+type ParagraphHashFns = {
+    hashString: (seed: number, value: string) => number;
+    hashNumber: (seed: number, value: number | undefined | null) => number;
+};
+export declare const deriveParagraphBlockVersion: (block: ParagraphBlock, getSdtMetadataVersion: (metadata: ParagraphAttrs["sdt"]) => string, readClipPathValue: (value: unknown) => string) => string;
+export declare const hashParagraphBlockForTableVersion: (seed: number, paragraphBlock: ParagraphBlock, hashFns: ParagraphHashFns) => number;
+export {};