superdoc 2.2.1 → 2.4.0-next.1

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,130 @@
+import { PaintWorkSummary } from './page-content.js';
+import { PageStyles } from './styles.js';
+import { PositionValidationOptions, PositionValidationSummary } from './pm-position-validation.js';
+import { DomPainterInput, PageDecorationProvider, PaintSnapshot, PositionMapping, FlowMode } from './renderer.js';
+import { DomPainterPersistentPageInput } from './persistent-page-surface.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 { DomPainterPersistentPacketSource, DomPainterPersistentPageInput, DomPainterPersistentScaffold, DomPainterPersistentScaffoldPage, } from './persistent-page-surface.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 live persistent surface and the fresh-state
+     * persistent-page oracle never mix counts.
+     */
+    positionValidation?: PositionValidationOptions;
+};
+export type DomPainterHandle = {
+    /** Semantic flow only (painter plan P7); paginated documents use the persistent reconcile. */
+    paint(input: DomPainterInput, mount: HTMLElement, mapping?: PositionMapping): void;
+    /**
+     * The persistent paginated reconcile (default persistent page geometry
+     * plan): a generation-scoped scaffold publishes every page root atomically
+     * and keeps it mounted for the whole layout generation; only content
+     * descendants are virtualized. Paginated flow only.
+     */
+    paintPersistentPages(input: DomPainterPersistentPageInput, mount: HTMLElement): void;
+    /** Live integrity probe used to prevent zero-work skips over a corrupted shell plane. */
+    isPersistentPageSurfaceIntact(): boolean;
+    /** Wake-up callback for foreign page-root DOM corruption. */
+    setPersistentSurfaceInvalidationHandler(handler?: () => void): void;
+    /** Ascending hydrated content page indices of the persistent surface. */
+    getHydratedContentPageIndices(): number[];
+    /**
+     * Painter plan §4.6 (dark observability): persistent-page 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;
+    getPersistentPageIndices(): number[];
+    setShowFormattingMarks(showFormattingMarks: boolean): void;
+    dispose(): 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: `paint()` serves semantic flow and rejects paginated flow;
+ * paginated documents and fresh-state oracles both use the one persistent
+ * page reconcile.
+ *
+ * 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;