superdoc 2.2.1 → 2.3.0

package/dist/layout-engine/layout-engine/src/table-cell-slice.d.ts

@@ -0,0 +1,98 @@
+import { TableCellMeasure, TableCell } from '../../contracts/src/index.js';
+/**
+ * Describes one block in a table cell with renderer-semantic height values.
+ *
+ * Maps each measured block to its global line index range and the spacing /
+ * height values the DOM painter actually applies. Layout decisions that use
+ * these descriptors stay synchronized with `renderTableCell.ts`.
+ */
+export type CellRenderBlock = {
+    kind: 'paragraph' | 'table' | 'other';
+    /** First global line index (inclusive). */
+    globalStartLine: number;
+    /** Past-the-end global line index (exclusive). */
+    globalEndLine: number;
+    /** Per-segment heights matching `getCellLines()` output. */
+    lineHeights: number[];
+    /** `ParagraphMeasure.totalHeight ?? sum(lineHeights)`. */
+    totalHeight: number;
+    /** Height contributing to content flow. 0 for anchored out-of-flow blocks. */
+    visibleHeight: number;
+    isFirstBlock: boolean;
+    isLastBlock: boolean;
+    /** Effective spacing.before (first block: excess over padding.top; others: full). */
+    spacingBefore: number;
+    /** Raw spacing.after; always 0 for last block (renderer skips it). */
+    spacingAfter: number;
+};
+/**
+ * Stateful cursor for the `computePartialRow()` fitting loop.
+ *
+ * Advances one line at a time and reports the rendered cost of each line
+ * including block-boundary spacing and totalHeight promotion. O(1) per step.
+ */
+export interface CellSliceCursor {
+    /**
+     * Compute the rendered cost of including the line at `globalLineIndex`.
+     * Advances internal state — call exactly once per line, in ascending order.
+     * After calling, if the line doesn't fit, break; the cursor state no longer
+     * matters since it won't be used again for this cell.
+     */
+    advanceLine(globalLineIndex: number): number;
+    /**
+     * Minimum rendered cost of the segment at `globalLineIndex`, for
+     * force-progress checks. Pure peek — does not modify cursor state.
+     */
+    minSegmentCost(globalLineIndex: number): number;
+}
+/**
+ * Build an ordered array of block descriptors from a cell's measurement and
+ * block data. Descriptors carry all renderer-semantic information needed by
+ * `computeCellSliceContentHeight` and the fitting cursor.
+ *
+ * **Iteration rule**: driven by measured blocks (source of truth for line
+ * counts). Block data is attached by index when available; missing data
+ * degrades to zero spacing and `totalHeight = sum(lineHeights)`.
+ */
+export declare function describeCellRenderBlocks(cellMeasure: TableCellMeasure, cellBlock: TableCell | undefined, cellPadding: {
+    top: number;
+    bottom: number;
+}): CellRenderBlock[];
+/**
+ * Content-area height of a cell slice `[fromLine, toLine)`.
+ *
+ * Matches the DOM painter's rendering semantics:
+ * - `spacing.before` when rendering from the start of a block
+ * - `totalHeight` promotion for fully rendered paragraphs
+ * - `spacing.after` for fully rendered non-last paragraphs
+ *
+ * Returns content height only — cell padding is NOT included.
+ * O(blocks) per call.
+ */
+export declare function computeCellSliceContentHeight(blocks: CellRenderBlock[], fromLine: number, toLine: number): number;
+/**
+ * Create a stateful cursor for the `computePartialRow()` fitting loop.
+ *
+ * The cursor tracks block boundaries and accumulates spacing / promotion costs
+ * so that each `advanceLine()` call is O(1). If the fitting loop starts from a
+ * continuation (mid-block), the cursor correctly skips spacing.before and
+ * totalHeight promotion for the partially consumed block.
+ */
+export declare function createCellSliceCursor(blocks: CellRenderBlock[], startLine: number): CellSliceCursor;
+/**
+ * Content height of a fully rendered cell, using **measurement** semantics.
+ *
+ * Unlike `describeCellRenderBlocks` + `computeCellSliceContentHeight` (which
+ * use renderer semantics and skip last-block spacing.after), this function
+ * includes last-block spacing.after via `effectiveTableCellSpacing` to match
+ * how `rowMeasure.height` was computed by the measurer. This keeps
+ * `getRowContentHeight()` aligned with `rowMeasure.height` so that
+ * `hasExplicitRowHeightSlack()` compares like-for-like.
+ *
+ * Computes in a single pass without allocating intermediate arrays.
+ * Returns content height only — cell padding is NOT included.
+ */
+export declare function computeFullCellContentHeight(cellMeasure: TableCellMeasure, cellBlock: TableCell | undefined, cellPadding: {
+    top: number;
+    bottom: number;
+}): number;

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

@@ -0,0 +1,21 @@
+import { DomPainterOptions, PaintSnapshot } from './index.js';
+import { PageDecorationProvider } from './renderer.js';
+import { FlowBlock, Layout, Measure, ResolvedLayout } from '../../../contracts/src/index.js';
+export declare const emptyResolved: ResolvedLayout;
+/**
+ * Test-only bridge: accepts old-style `{ blocks, measures, ...options }` and
+ * returns a painter whose `paint()` automatically builds a `DomPainterInput`.
+ */
+export declare function createTestPainter(opts: {
+    blocks?: FlowBlock[];
+    measures?: Measure[];
+} & DomPainterOptions): {
+    paint(layout: Layout, mount: HTMLElement, mapping?: unknown): void;
+    setData(blocks: FlowBlock[], measures: Measure[], hb?: FlowBlock[], hm?: Measure[], fb?: FlowBlock[], fm?: Measure[]): void;
+    setResolvedLayout(rl: ResolvedLayout | null): void;
+    setProviders(header?: PageDecorationProvider, footer?: PageDecorationProvider): void;
+    getMountedPageIndices(): number[];
+    getPaintSnapshot(): PaintSnapshot | null;
+    setShowFormattingMarks(showFormattingMarks: boolean): void;
+    dispose(): void;
+};

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

@@ -0,0 +1,13 @@
+import { ChartModel, DrawingGeometry } from '../../../contracts/src/index.js';
+/**
+ * Create a chart element from a ChartDrawing block.
+ * Routes to the correct renderer based on chart type, with placeholder fallback.
+ */
+export declare function createChartElement(doc: Document, chartData: ChartModel | undefined, geometry: DrawingGeometry): HTMLElement;
+/**
+ * Create a placeholder for charts with missing data or unsupported types.
+ * Preserves layout dimensions and is print-visible.
+ */
+export declare function createChartPlaceholder(doc: Document, container: HTMLElement, label: string): HTMLElement;
+/** Format a numeric tick value for chart axis labels. */
+export declare function formatTickValue(value: number): string;

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

@@ -0,0 +1,10 @@
+/**
+ * DOM Painter Constants — Compatibility Re-exports
+ *
+ * The source of truth for these constants 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 { DOM_CLASS_NAMES } from '../../../dom-contract/src/index.js';
+export type { DomClassName } from '../../../dom-contract/src/index.js';

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

@@ -0,0 +1,10 @@
+export type CssToken = {
+    css: string;
+    fallback: string;
+};
+/**
+ * Creates a CSS variable token with a fallback value.
+ * The `css` string is used in real browsers (supports var()).
+ * The `fallback` is used in environments that don't (e.g., jsdom in tests).
+ */
+export declare const cssToken: (varName: string, fallback: string) => CssToken;

package/dist/layout-engine/painters/dom/src/features/feature-registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Rendering Feature Registry
+ *
+ * Maps OOXML elements to their rendering feature modules.
+ * This is the primary lookup table for agents and developers.
+ *
+ * To find where an OOXML element renders: search this file.
+ * To add a new rendering feature: add an entry here first.
+ *
+ * Each entry specifies:
+ * - feature: human-readable feature name (matches folder name)
+ * - module: import path relative to this file
+ * - handles: list of OOXML element paths this feature renders
+ * - spec: ECMA-376 section reference
+ */
+export declare const RENDERING_FEATURES: {
+    readonly 'w:pBdr': {
+        readonly feature: "paragraph/borders";
+        readonly module: "../paragraph/borders";
+        readonly handles: readonly ["w:pBdr/w:top", "w:pBdr/w:bottom", "w:pBdr/w:left", "w:pBdr/w:right", "w:pBdr/w:between", "w:pBdr/w:bar"];
+        readonly spec: "§17.3.1.24";
+    };
+    readonly 'w:shd': {
+        readonly feature: "paragraph/borders";
+        readonly module: "../paragraph/borders";
+        readonly handles: readonly ["w:shd/@w:fill", "w:shd/@w:val", "w:shd/@w:color"];
+        readonly spec: "§17.3.1.31";
+    };
+    readonly 'w:bidi': {
+        readonly feature: "inline-direction";
+        readonly module: "./inline-direction";
+        readonly handles: readonly ["w:pPr/w:bidi", "w:rPr/w:rtl"];
+        readonly spec: "§17.3.1.1";
+    };
+    readonly 'm:oMath': {
+        readonly feature: "math";
+        readonly module: "./math";
+        readonly handles: readonly ["m:oMath", "m:oMathPara", "m:r", "m:t", "m:f", "m:rad", "m:sSup", "m:sSub", "m:sSubSup", "m:sPre", "m:d", "m:nary", "m:acc", "m:bar", "m:groupChr", "m:limLow", "m:limUpp", "m:func", "m:m", "m:eqArr", "m:borderBox", "m:box", "m:phant"];
+        readonly spec: "§22.1";
+    };
+};

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

@@ -0,0 +1,22 @@
+/**
+ * Inline Direction - rendering feature module
+ *
+ * Centralises paragraph base-direction and run-level RTL/bidi handling
+ * used by DomPainter:
+ * - Detecting whether a paragraph is RTL
+ * - Applying dir="rtl" and the correct text-align to an element
+ * - Resolving text-align for RTL vs LTR (justify -> right/left)
+ * - Deciding whether segment-based (absolute) positioning is safe
+ *
+ * Scope is paragraph/run inline bidi handling only. Table visual
+ * direction (w:bidiVisual, ECMA-376 §17.4.1) is a separate orthogonal
+ * axis owned by the painter's table rendering path. Writing mode
+ * (w:textDirection, ECMA-376 §17.3.1.41 paragraph / §17.4.72 cell;
+ * values in §17.18.93 ST_TextDirection) is another separate axis.
+ *
+ * @ooxml w:pPr/w:bidi - paragraph bidirectional flag
+ * @ooxml w:rPr/w:rtl  - run-level right-to-left flag
+ * @spec  ECMA-376 §17.3.1.1 (bidi), §17.3.2.30 (rtl)
+ */
+export { applyRtlStyles, resolveTextAlign, shouldUseSegmentPositioning } from './rtl-styles.js';
+export { resolveRunDirectionAttribute, normalizeRtlDateTokenForWordParity, RTL_DATE_LIKE_TOKEN_RE, STRONG_RTL_CHAR_RE, LATIN_DIGIT_NEUTRAL_ONLY_RE, type RunDirAttribute, } from './run-direction.js';

package/dist/layout-engine/painters/dom/src/features/inline-direction/rtl-styles.d.ts

@@ -0,0 +1,27 @@
+import { ParagraphAttrs } from '../../../../../contracts/src/index.js';
+/**
+ * Returns true when the paragraph attributes indicate right-to-left direction.
+ */
+export declare const isRtlParagraph: (attrs: ParagraphAttrs | undefined) => boolean;
+/**
+ * Compute the effective CSS text-align for a paragraph.
+ *
+ * DomPainter handles justify via per-line word-spacing, so 'justify'
+ * becomes 'left' (LTR) or 'right' (RTL) to align the last line correctly.
+ * When no explicit alignment is set the default follows the paragraph direction.
+ */
+export declare const resolveTextAlign: (alignment: ParagraphAttrs["alignment"], isRtl: boolean) => string;
+/**
+ * Apply `dir` and `text-align` to an element based on paragraph attributes.
+ * Used by both `renderLine` (line elements) and `applyParagraphBlockStyles`
+ * (fragment wrappers) so the logic stays in one place.
+ */
+export declare const applyRtlStyles: (element: HTMLElement, attrs: ParagraphAttrs | undefined) => boolean;
+/**
+ * Whether the renderer should use absolute-positioned segment layout for a line.
+ *
+ * Returns false for RTL paragraphs: the layout engine computes tab X positions
+ * in LTR order, so for RTL we fall through to inline-flow rendering where the
+ * browser's native bidi algorithm handles tab positioning via dir="rtl".
+ */
+export declare const shouldUseSegmentPositioning: (hasExplicitPositioning: boolean, hasSegments: boolean, isRtl: boolean) => boolean;

package/dist/layout-engine/painters/dom/src/features/inline-direction/run-direction.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Run-level direction helpers for DomPainter.
+ *
+ * These helpers encode paint-time decisions about how to project the OOXML
+ * `w:rPr/w:rtl` signal onto a rendered span's `dir` attribute, plus a narrow
+ * Word-parity workaround for RTL-tagged date-like numeric runs.
+ *
+ * The heuristic is intentionally scoped to current Word-parity fixtures
+ * (SD-3098 mixed-bidi date tokens). It is NOT a full implementation of
+ * §17.3.2.30 semantics - notably absent: `w:dir` embedding (§17.3.2.8),
+ * `w:bdo` override (§17.3.2.3), and `w:lang/@bidi` Hebrew vs Arabic numeric
+ * differences. Those gaps are tracked separately; see SD-2767 follow-ups.
+ *
+ * @spec ECMA-376 §17.3.2.30 (rtl), §17.17.4 (boolean property)
+ */
+/**
+ * Matches numeric date-like tokens such as `2026-03-15`, `15/03/2026`, `1.2.3`.
+ * Used by both the run direction resolver and the paint-time RLM injection
+ * for Word parity on RTL date strings.
+ */
+export declare const RTL_DATE_LIKE_TOKEN_RE: RegExp;
+/**
+ * Matches strong-RTL characters across Hebrew, Arabic, and adjacent RTL scripts
+ * including presentation forms (FB1D-FB4F Hebrew, FB50-FDFF Arabic-A,
+ * FE70-FEFF Arabic-B). The block range covers Hebrew, Arabic, Syriac, NKo,
+ * etc.; the Script properties add presentation forms without including
+ * noncharacters (FDD0-FDEF) or the BOM (FEFF).
+ *
+ * AIDEV-NOTE: also used by editing/runtime mixed-bidi handling. Consolidating
+ * crosses a layer boundary; tracked under SD-3169 follow-ups.
+ */
+export declare const STRONG_RTL_CHAR_RE: RegExp;
+/**
+ * Matches runs whose content is exclusively Latin / digit / neutral. Used as
+ * the "skip per-run dir=rtl" guard: per §17.3.2.30, behavior of w:rtl on
+ * strongly LTR text is unspecified, and Word's empirical output for these
+ * runs does not visually reorder.
+ */
+export declare const LATIN_DIGIT_NEUTRAL_ONLY_RE: RegExp;
+/**
+ * Word-parity workaround for RTL date-like tokens.
+ *
+ * Word internally injects RLM around numeric separators in RTL date strings,
+ * preserving LTR order for the digits while keeping the run RTL. The browser's
+ * UBA alone does not match this. We mirror Word by injecting RLM at paint
+ * time only - the DOM text differs from the PM model and from the exported
+ * OOXML, which both keep the original separators.
+ *
+ * Intentionally narrow: only matches numeric date-like patterns so other
+ * numeric content is unaffected. Scope is current SD-3098 fixtures.
+ */
+export declare const normalizeRtlDateTokenForWordParity: (text: string) => string;
+/**
+ * Compute the `dir` attribute (if any) to apply to a rendered run span.
+ *
+ * Decision table:
+ * - rtl-tagged + empty text -> 'rtl' (no content to classify, honor source signal)
+ * - rtl-tagged + date-like numeric -> 'rtl' (isolates the date as a unit)
+ * - rtl-tagged + contains strong-RTL chars -> 'rtl' (standard case)
+ * - rtl-tagged + only Latin/digit/neutral -> null (per §17.3.2.30, unspecified;
+ *   Word does not visually reorder these, so omit dir to inherit paragraph)
+ * - rtl-tagged + other (e.g. East Asian, symbols outside the neutral set) -> 'rtl' (fail-safe)
+ * - NOT rtl-tagged + date-like numeric text -> 'ltr' (Word-parity: keeps date
+ *   LTR-classified within an RTL paragraph context so digits don't drift)
+ * - NOT rtl-tagged + anything else -> null (let paragraph + UBA decide)
+ */
+export type RunDirAttribute = 'rtl' | 'ltr' | null;
+export declare const resolveRunDirectionAttribute: (opts: {
+    /** Original run text from the model. */
+    runText: string | undefined;
+    /** Post-token-resolution text used for rendering (e.g. field token expansion). */
+    effectiveText: string;
+    /** True when the source OOXML carries `w:rPr/w:rtl`. */
+    isRtlTagged: boolean;
+}) => RunDirAttribute;

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

@@ -0,0 +1,25 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:acc (accent / diacritical mark) to MathML <mover accent="true">.
+ *
+ * OMML structure:
+ *   m:acc → m:accPr? (optional: m:chr@m:val), m:e (base expression, required)
+ *
+ * MathML output:
+ *   <mover accent="true">
+ *     <mrow>base</mrow>
+ *     <mo>accent-char</mo>
+ *   </mover>
+ *
+ * ECMA-376 §22.1.2.20 (chr) defines three m:chr states:
+ *   1. m:chr element absent           → default accent char (U+0302)
+ *   2. m:chr present, m:val absent    → character is absent (render bare base)
+ *   3. m:chr present, m:val = "x"     → use x as the accent character
+ *
+ * When the accent character is absent, the base is returned wrapped in <mrow>
+ * with no <mover> wrapper. When m:e itself is absent (invalid per the schema),
+ * the converter returns null so the caller can drop the malformed element.
+ *
+ * @spec ECMA-376 §22.1.2.1 (acc), §22.1.2.2 (accPr), §22.1.2.20 (chr)
+ */
+export declare const convertAccent: MathObjectConverter;

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

@@ -0,0 +1,16 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:bar (overbar/underbar) to MathML <mover> or <munder>.
+ *
+ * OMML structure:
+ *   m:bar → m:barPr (optional: m:pos@m:val="top"|"bot"), m:e (base expression)
+ *
+ * MathML output:
+ *   top:           <mover> <mrow>base</mrow> <mo>&#x203E;</mo> </mover>
+ *   bot (default): <munder> <mrow>base</mrow> <mo>&#x203E;</mo> </munder>
+ *
+ * Word renders an underbar when no position is specified, so the default is "bot".
+ *
+ * @spec ECMA-376 §22.1.2.7
+ */
+export declare const convertBar: MathObjectConverter;

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

@@ -0,0 +1,38 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:box (grouping container) to MathML <mrow>.
+ *
+ * OMML structure:
+ *   m:box → m:boxPr (optional), m:e (content)
+ *
+ * MathML output:
+ *   <mrow> content </mrow>
+ *
+ * Per §22.1.2.13 / §22.1.2.14, m:box can carry boxPr children that affect
+ * layout and spacing — opEmu (operator emulator), noBreak (disallow line
+ * breaks), aln (alignment point), diff (differential spacing), argSz. These
+ * have no clean MathML equivalent and are currently dropped; the box
+ * degrades to a plain <mrow> that preserves grouping but not the other
+ * semantics. Extend here when any of these need first-class support.
+ *
+ * @spec ECMA-376 §22.1.2.13, §22.1.2.14
+ */
+export declare const convertBox: MathObjectConverter;
+/**
+ * Convert m:borderBox (bordered box) to MathML <menclose>.
+ *
+ * OMML structure:
+ *   m:borderBox → m:borderBoxPr (optional: m:hideTop, m:hideBot, m:hideLeft, m:hideRight,
+ *                                  m:strikeBLTR, m:strikeH, m:strikeTLBR, m:strikeV),
+ *                 m:e (content)
+ *
+ * MathML output:
+ *   <menclose notation="..."> content </menclose>
+ *
+ * By default all four borders are shown (notation="box"). Individual borders
+ * can be hidden via m:hide* flags, and diagonal/horizontal/vertical strikes
+ * can be added via m:strike* flags.
+ *
+ * @spec ECMA-376 §22.1.2.11
+ */
+export declare const convertBorderBox: MathObjectConverter;

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

@@ -0,0 +1,13 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:d (delimiter) to MathML.
+ *
+ * OMML structure:
+ *   m:d → m:dPr (optional: begChr, endChr, sepChr) + one or more m:e expressions
+ *
+ * MathML output:
+ *   <mrow><mo>(</mo> ...content... <mo>)</mo></mrow>
+ *
+ * @spec ECMA-376 §22.1.2.24
+ */
+export declare const convertDelimiter: MathObjectConverter;

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

@@ -0,0 +1,19 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:eqArr (equation array) to MathML <mtable>.
+ *
+ * OMML structure:
+ *   m:eqArr → m:eqArrPr (optional), m:e* (one element per row)
+ *
+ * MathML output:
+ *   <mtable columnalign="left">
+ *     <mtr> <mtd> <mrow>row-content</mrow> </mtd> </mtr>
+ *     ...
+ *   </mtable>
+ *
+ * Unlike m:m (matrix), equation arrays have one cell per row and are
+ * typically left-aligned. Used for systems of equations.
+ *
+ * @spec ECMA-376 §22.1.2.34
+ */
+export declare const convertEquationArray: MathObjectConverter;

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

@@ -0,0 +1,13 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:f (fraction) to MathML <mfrac>.
+ *
+ * OMML structure:
+ *   m:f → m:fPr (optional: type), m:num (numerator), m:den (denominator)
+ *
+ * MathML output:
+ *   <mfrac> <mrow>num</mrow> <mrow>den</mrow> </mfrac>
+ *
+ * @spec ECMA-376 §22.1.2.36
+ */
+export declare const convertFraction: MathObjectConverter;

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

@@ -0,0 +1,16 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:func (function apply) to MathML.
+ *
+ * OMML structure:
+ *   m:func → m:funcPr (optional), m:fName (function name), m:e (argument)
+ *
+ * MathML output:
+ *   <mrow> <mrow>name</mrow> <mo>&#x2061;</mo> <mrow>argument</mrow> </mrow>
+ *
+ * Function names are rendered upright (mathvariant="normal") instead of the
+ * default italic identifier style used by MathML.
+ *
+ * @spec ECMA-376 §22.1.2.39
+ */
+export declare const convertFunction: MathObjectConverter;

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

@@ -0,0 +1,26 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:groupChr (group character) to MathML <munder> or <mover>.
+ *
+ * OMML structure:
+ *   m:groupChr → m:groupChrPr (optional: m:chr@m:val, m:pos@m:val, m:vertJc@m:val), m:e
+ *
+ * MathML output:
+ *   pos="bot" (default): <munder>  <mrow>base</mrow> <mo>char</mo> </munder>
+ *   pos="top":           <mover>   <mrow>base</mrow> <mo>char</mo> </mover>
+ *
+ * Defaults (ECMA-376 §22.1.2.20, §22.1.2.42, §22.1.2.119):
+ *   m:chr absent → U+23DF (bottom curly bracket)
+ *   m:chr present without m:val → hidden character
+ *   m:pos absent → "bot"
+ *   m:vertJc present without m:val → "bot"
+ *
+ * vertJc handling: m:vertJc specifies which edge of the group-character object aligns
+ * with the surrounding baseline. Natural <munder>/<mover> rendering puts the base on
+ * the baseline, which matches (pos=bot, vertJc=top) and (pos=top, vertJc=bot). Word
+ * renders an absent m:vertJc as the natural layout for the given position, so a shift
+ * is only applied when m:vertJc is explicitly set to the non-natural value for the pos.
+ *
+ * @spec ECMA-376 §22.1.2.41
+ */
+export declare const convertGroupCharacter: MathObjectConverter;

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

@@ -0,0 +1,27 @@
+/**
+ * Math Object Converters
+ *
+ * Each converter transforms one OMML math object type into MathML DOM elements.
+ * To add support for a new math object, create a converter file and register it here.
+ *
+ * See types.ts for the MathObjectConverter interface.
+ */
+export { convertMathRun } from './math-run.js';
+export { convertFraction } from './fraction.js';
+export { convertBar } from './bar.js';
+export { convertFunction } from './function.js';
+export { convertDelimiter } from './delimiter.js';
+export { convertSubscript } from './subscript.js';
+export { convertSuperscript } from './superscript.js';
+export { convertSubSuperscript } from './sub-superscript.js';
+export { convertAccent } from './accent.js';
+export { convertPreSubSuperscript } from './pre-sub-superscript.js';
+export { convertEquationArray } from './equation-array.js';
+export { convertRadical } from './radical.js';
+export { convertLowerLimit } from './lower-limit.js';
+export { convertUpperLimit } from './upper-limit.js';
+export { convertNary } from './nary.js';
+export { convertPhantom } from './phantom.js';
+export { convertGroupCharacter } from './group-character.js';
+export { convertMatrix } from './matrix.js';
+export { convertBox, convertBorderBox } from './box.js';

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

@@ -0,0 +1,13 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:limLow (lower limit) to MathML <munder>.
+ *
+ * OMML structure:
+ *   m:limLow → m:limLowPr (optional), m:e (base, e.g. "lim"), m:lim (limit expression)
+ *
+ * MathML output:
+ *   <munder> <mrow>base</mrow> <mrow>lim</mrow> </munder>
+ *
+ * @spec ECMA-376 §22.1.2.54
+ */
+export declare const convertLowerLimit: MathObjectConverter;

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

@@ -0,0 +1,47 @@
+import { OmmlJsonNode, MathObjectConverter } from '../types.js';
+type MathAtomTag = 'mi' | 'mo' | 'mn';
+/**
+ * Split a math run's text into MathML atoms, matching Word's OMML2MML.XSL.
+ *
+ * Rules (ECMA-376 §22.1.2.116 example + Annex L.6.1.13):
+ * - Consecutive digits — optionally containing one decimal point between digits —
+ *   group into a single `<mn>`.
+ * - Each recognized operator character becomes its own `<mo>`.
+ * - Every other character becomes its own `<mi>`.
+ *
+ * Example: `"n+1"` → `[<mi>n</mi>, <mo>+</mo>, <mn>1</mn>]`.
+ */
+export declare function tokenizeMathText(text: string): Array<{
+    tag: MathAtomTag;
+    content: string;
+}>;
+/**
+ * Convert an m:r (math run) element to MathML atoms.
+ *
+ * m:r contains:
+ * - m:rPr (math run properties: script, style, normal text flag)
+ * - m:t (text content)
+ * - Optionally w:rPr (WordprocessingML run properties for formatting)
+ *
+ * The run's text is split per-character into `<mi>` / `<mo>` / `<mn>` atoms
+ * per Word's OMML2MML.XSL. For a single-atom run (common case — a one-letter
+ * variable, single operator, or an all-digit number) the converter returns a
+ * single Element. For a multi-atom run (e.g. "→∞", "x+1") it returns a
+ * DocumentFragment whose children become siblings of the parent mrow.
+ *
+ * @spec ECMA-376 §22.1.2.116 (t) — example shows multi-char mixed runs as the
+ *   normal authored shape; §22.1.2.58 (lit) implies operators are classified
+ *   per-character by default.
+ */
+export declare const convertMathRun: MathObjectConverter;
+/**
+ * Convert an m:r inside m:fName (m:func's function-name slot). Word's
+ * OMML2MML.XSL keeps each letter-sequence whole while still splitting out
+ * digits and operators — so `sin` stays `<mi>sin</mi>`, but `log_2` becomes
+ * `<mi>log</mi><mo>_</mo><mn>2</mn>`.
+ *
+ * Returns a single Element for single-atom runs or a DocumentFragment when
+ * the run emits multiple atoms. Returns null for empty text.
+ */
+export declare function convertMathRunAsFunctionName(node: OmmlJsonNode, doc: Document): Node | null;
+export {};

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

@@ -0,0 +1,23 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:m (matrix) to MathML <mtable>.
+ *
+ * OMML structure:
+ *   m:m → m:mPr (optional: mcs/mcJc/baseJc/plcHide — only plcHide applied), m:mr* (rows)
+ *     m:mr → m:e* (cells; empty m:e creates a positional gap per §22.1.2.32)
+ *
+ * MathML output:
+ *   <mtable>
+ *     <mtr>
+ *       <mtd> <mrow>cell-content</mrow> </mtd>
+ *       ...
+ *     </mtr>
+ *     ...
+ *   </mtable>
+ *
+ * Empty cells render a U+25A1 placeholder by default (§22.1.2.83 plcHide="0").
+ * When m:plcHide is present with val "1"/"true" or no val, the placeholder is suppressed.
+ *
+ * @spec ECMA-376 §22.1.2.60
+ */
+export declare const convertMatrix: MathObjectConverter;

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

@@ -0,0 +1,23 @@
+import { MathObjectConverter } from '../types.js';
+/**
+ * Convert m:nary (n-ary operator) to MathML.
+ *
+ * OMML structure:
+ *   m:nary → m:naryPr (optional: m:chr@m:val, m:limLoc@m:val, m:subHide, m:supHide),
+ *            m:sub (lower limit, optional), m:sup (upper limit, optional), m:e (body)
+ *
+ * MathML shape depends on which limits are shown and the limit location:
+ *
+ *   Both limits, subSup (default for integrals):
+ *     <mrow><msubsup><mo>∫</mo><mrow>sub</mrow><mrow>sup</mrow></msubsup><mrow>body</mrow></mrow>
+ *   Both limits, undOvr (default for ∑, ∏, ⋃, ...):
+ *     <mrow><munderover><mo>∑</mo><mrow>sub</mrow><mrow>sup</mrow></munderover><mrow>body</mrow></mrow>
+ *
+ *   Only sub:      <msub>   / <munder>  + <mo> + <mrow>sub</mrow>
+ *   Only sup:      <msup>   / <mover>   + <mo> + <mrow>sup</mrow>
+ *   Neither:       bare <mo> inside the outer <mrow>
+ *
+ * @spec ECMA-376 §22.1.2.70 (m:nary), §22.1.2.72 (m:naryPr),
+ *       §22.1.2.53 (m:limLoc), §22.1.2.20 (m:chr), §22.9.2.7 (ST_OnOff)
+ */
+export declare const convertNary: MathObjectConverter;