superdoc 2.2.1 → 2.4.0-next.1

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

@@ -0,0 +1,277 @@
+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 persistent-page
+ * 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 = {
+    /** Persistent page roots newly created for a committed scaffold. */
+    persistentPagesCreated: number;
+    /** Persistent page roots reused by index whose exact geometry changed. */
+    persistentPagesUpdated: number;
+    /** Persistent page roots removed by a generation commit (never by scroll). */
+    persistentPagesRemoved: number;
+    /** Pages whose content hydrated into an existing persistent root. */
+    contentHydrated: number;
+    /** Pages whose painter-owned content descendants were removed, root kept. */
+    contentDehydrated: number;
+    /** Hydrated pages reconciled through the fragment-keyed patch. */
+    contentPatched: number;
+    /** Hydrated pages left completely untouched. */
+    contentUntouched: number;
+    /** Hydrated pages whose pm positions were uniformly shifted in place. */
+    contentRemapped: number;
+    /** Hydrated pages whose header/footer DOM refreshed without body rebuild. */
+    contentDecorationsRefreshed: number;
+    /** Hydrated pages demoted from reuse because position drift was not uniform. */
+    contentPmDemoted: 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.
+     */
+    createdPersistentPageIndices: number[];
+    removedPersistentPageIndices: number[];
+    patchedContentPageIndices: number[];
+    untouchedContentPageIndices: number[];
+    decorationRefreshedContentPageIndices: number[];
+    remappedContentPageIndices: number[];
+    pmDemotedContentPageIndices: number[];
+    hydratedContentPageIndices: number[];
+    dehydratedContentPageIndices: number[];
+};
+export declare function createEmptyPaintWorkSummary(): PaintWorkSummary;
+/**
+ * Painter plan P3a: reuse key for one exact page slot on the persistent-page
+ * 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 persistentPageVersionKey(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;
+}
+/**
+ * The subset of `PageContentContext` needed to build a canonical page shell —
+ * the `.superdoc-page` element with exact geometry, chrome, epoch, and layout
+ * boundary stamps, but no content. Persistent scaffold reconciliation builds
+ * shells through this context and hydrates content independently.
+ */
+export type PageShellContext = Pick<PageContentContext, 'doc' | 'layoutEpoch' | 'getEffectivePageStyles' | 'applySemanticPageOverrides'>;
+/**
+ * The exact page box a shell derives from. `ResolvedPage` satisfies it, and
+ * so does a numbers-only scaffold band — the persistent page surface builds
+ * shells without materializing resolved packets.
+ */
+export type PageShellGeometry = {
+    width: number;
+    height: number;
+};
+/** Refresh geometry and document-level presentation without replacing a page. */
+export declare function refreshPageShell(ctx: PageShellContext, el: HTMLElement, page: PageShellGeometry): void;
+/**
+ * Canonical `.superdoc-page` shell: the one place a paginated page element is
+ * created. The persistent scaffold mounts it bare and bounded content
+ * reconciliation hydrates the same element in place.
+ */
+export declare function renderPageShell(ctx: PageShellContext, page: PageShellGeometry): HTMLElement;
+/**
+ * Content half of page painting: resolved fragments, decorations (headers,
+ * footers, behind-doc sections), and column separators, appended to an
+ * existing page shell. Persistent hydration goes through exactly this
+ * function, so a hydrated page is byte-equivalent to one painted
+ * by the content path from scratch — same element, same append order.
+ */
+export declare function hydratePageContent(ctx: PageContentContext, el: HTMLElement, page: ResolvedPage, pageIndex: number): FragmentDomState[];
+export declare function renderPage(ctx: PageContentContext, page: ResolvedPage, pageIndex: number): PageDomState;
+/**
+ * Inverse of {@link hydratePageContent} (default persistent page geometry
+ * plan, Unit 1): remove the painter-owned content descendants from an
+ * existing page root, leaving root identity, root attributes, page order,
+ * exact geometry, and the document scroll extent untouched. The tracked
+ * fragment list is removed first (authoritative retained state), then any
+ * painter-owned straggler matched by class/attribute — a fragment orphaned
+ * from the retained list must not survive dehydration.
+ */
+export declare function dehydratePageContent(el: HTMLElement, state: PageDomState): void;
+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;
+/** Order-insensitive equality over two SDT label key sets. */
+export declare function sdtLabelSetsEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean;
+export type WindowPositionRemapEntry = {
+    fragmentState: FragmentDomState;
+    freshItem: ResolvedPaintItem & {
+        fragment: Fragment;
+    };
+    /** Fresh minus retained fragment pmStart — the exact uniform shift. */
+    deltaPm: number;
+};
+export type WindowPositionRemapPlan = {
+    kind: 'none' | 'remap' | 'demote';
+    drifted: WindowPositionRemapEntry[];
+};
+/**
+ * Painter plan P5: decide whether a version-key-matched page is reusable
+ * untouched (`none`), needs an in-place uniform position remap (`remap` —
+ * resolve stamps are pm-insensitive, so unchanged content legitimately
+ * drifts), or must be demoted to the fragment-keyed patch (`demote`, where
+ * `pmReuseUnsound` forces a REAL rebuild of the offending fragment).
+ *
+ * Fail-closed: one-sided pm, a span-LENGTH change, an interior-pm signature
+ * mismatch (a PM node inserted/moved inside the block emits no run, so
+ * stamps stay equal while interior offsets move), a missing interior key, or
+ * pm-bearing DOM under a fragment with no fragment-level pm all demote —
+ * only a PROVABLY uniform drift is shifted in place.
+ *
+ * Pairing is lockstep by index (review fix): this only runs under versionKey
+ * EQUALITY, and the key is an order-sensitive join of every fragment's
+ * key+geometry+stamp, so equal keys imply identical ordered fragment
+ * sequences — no per-paint key strings or Maps on the steady-state path.
+ */
+export declare function planWindowPositionRemap(state: PageDomState, resolvedPage: ResolvedPage): WindowPositionRemapPlan;

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 {};

package/dist/layout-engine/painters/dom/src/paragraph/borders/border-layer.d.ts

@@ -0,0 +1,59 @@
+import { ParagraphAttrs, ParagraphBorders } from '../../../../../contracts/src/index.js';
+import { BetweenBorderInfo } from './group-analysis.js';
+/**
+ * Computes the indent-aware bounding box for paragraph border/shading layers.
+ * Borders hug the paragraph content, inset by left/right/firstLine/hanging indents.
+ */
+export declare const getParagraphBorderBox: (fragmentWidth: number, indent?: ParagraphAttrs["indent"]) => {
+    leftInset: number;
+    width: number;
+};
+/**
+ * Computes the outward expansion for the border/shading layers based on
+ * the `space` attribute (OOXML: distance between border and text, in points).
+ *
+ * Within between-border groups, suppressed sides don't expand (the gap
+ * extension handles visual continuity instead).
+ *
+ * @spec ECMA-376 §17.3.1.24 — space attribute on pBdr child elements
+ */
+export declare const computeBorderSpaceExpansion: (borders?: ParagraphBorders, betweenInfo?: BetweenBorderInfo) => {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+/**
+ * Builds overlay elements for paragraph shading and borders.
+ * Returns layers in the order they should be appended (shading below borders).
+ *
+ * When `betweenInfo` indicates this fragment is in a border group:
+ * - The border layer extends downward by `gapBelow` px into the paragraph-spacing
+ *   gap, making left/right borders visually continuous across the group.
+ * - `suppressTopBorder` hides the top border for non-first group members.
+ * - `showBetweenBorder` replaces the bottom border with the between definition.
+ *
+ * The `space` attribute on each border side expands the layer outward,
+ * creating padding between the border line and the paragraph text.
+ */
+export declare const createParagraphDecorationLayers: (doc: Document, fragmentWidth: number, attrs?: ParagraphAttrs, betweenInfo?: BetweenBorderInfo) => {
+    shadingLayer?: HTMLElement;
+    borderLayer?: HTMLElement;
+};
+/**
+ * Applies paragraph border styles to an HTML element.
+ *
+ * Handles between-border groups:
+ * - `suppressTopBorder`: skips top border for non-first group members
+ * - `showBetweenBorder`: replaces bottom with the between border definition
+ */
+export declare const applyParagraphBorderStyles: (element: HTMLElement, borders?: ParagraphAttrs["borders"], betweenInfo?: BetweenBorderInfo) => void;
+/**
+ * Stamps between-border info onto an element's dataset for debugging
+ * and incremental update cache invalidation.
+ */
+export declare const stampBetweenBorderDataset: (element: HTMLElement, betweenInfo?: BetweenBorderInfo) => void;
+/**
+ * Applies paragraph shading (background color) to an HTML element.
+ */
+export declare const applyParagraphShadingStyles: (element: HTMLElement, shading?: ParagraphAttrs["shading"]) => void;

package/dist/layout-engine/painters/dom/src/paragraph/borders/group-analysis.d.ts

@@ -0,0 +1,38 @@
+import { ResolvedPaintItem } from '../../../../../contracts/src/index.js';
+/**
+ * Per-fragment rendering info for between-border groups.
+ *
+ * - showBetweenBorder: replace bottom border with the between definition
+ * - suppressTopBorder: hide this fragment's top border (covered by previous fragment's extension)
+ * - gapBelow: px to extend the border layer downward into the paragraph-spacing gap
+ */
+export type BetweenBorderInfo = {
+    showBetweenBorder: boolean;
+    suppressTopBorder: boolean;
+    suppressBottomBorder: boolean;
+    gapBelow: number;
+};
+/**
+ * Pre-computes per-fragment between-border rendering info for a page.
+ *
+ * Two fragments (i, i+1) form a border group pair when:
+ * 1. Both are para fragments (not table/image/drawing)
+ * 2. Neither is a page-split continuation
+ * 3. They represent different logical paragraphs
+ * 4. Both have border definitions
+ * 5. Their full border definitions match (same border group)
+ *
+ * Per ECMA-376 §17.3.1.5: grouping occurs when all border properties are
+ * identical. A `between` border is NOT required — when absent, the group
+ * is rendered as a single box without a separator line.
+ *
+ * For each pair, the first fragment gets:
+ * - showBetweenBorder: true — bottom border replaced with between definition
+ * - gapBelow: px distance to extend border layer into spacing gap
+ *
+ * The second fragment gets:
+ * - suppressTopBorder: true — the previous fragment's extension covers the boundary
+ *
+ * Middle fragments in a chain of 3+ get both flags.
+ */
+export declare const computeBetweenBorderFlags: (resolvedItems: readonly ResolvedPaintItem[]) => Map<number, BetweenBorderInfo>;

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

@@ -0,0 +1,18 @@
+/**
+ * Paragraph Borders — rendering feature module
+ *
+ * Handles all aspects of paragraph border rendering:
+ * - Border group detection (between-border analysis)
+ * - Border/shading DOM layer creation
+ * - CSS border style application
+ *
+ * @ooxml w:pPr/w:pBdr — paragraph border properties
+ * @ooxml w:pPr/w:pBdr/w:top, w:bottom, w:left, w:right — side borders
+ * @ooxml w:pPr/w:pBdr/w:between — between border for grouped paragraphs
+ * @ooxml w:pPr/w:pBdr/w:bar — bar border (vertical line)
+ * @ooxml w:pPr/w:shd — paragraph shading
+ * @spec  ECMA-376 §17.3.1.24 (pBdr), §17.3.1.31 (shd)
+ */
+export { computeBetweenBorderFlags } from './group-analysis.js';
+export type { BetweenBorderInfo } from './group-analysis.js';
+export { createParagraphDecorationLayers, applyParagraphBorderStyles, applyParagraphShadingStyles, getParagraphBorderBox, stampBetweenBorderDataset, computeBorderSpaceExpansion, } from './border-layer.js';

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

@@ -0,0 +1,3 @@
+import { ParaFragment, ResolvedFragmentItem } from '../../../../contracts/src/index.js';
+export type FragmentFrameSection = 'body' | 'header' | 'footer';
+export declare const applyParagraphFragmentPmAttributes: (el: HTMLElement, fragment: ParaFragment, section?: FragmentFrameSection, resolvedItem?: ResolvedFragmentItem) => void;

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

@@ -0,0 +1,25 @@
+import { Line, ParagraphIndent } from '../../../../contracts/src/index.js';
+export type ParagraphLineIndentationParams = {
+    lineEl: HTMLElement;
+    line: Line;
+    indent?: ParagraphIndent;
+    indentLeftPx: number;
+    hasListMarkerLayout: boolean;
+    lineIndex: number;
+    localStartLine: number;
+    continuesFromPrev?: boolean;
+    suppressFirstLineIndent: boolean;
+    resetContinuationTextIndent?: boolean;
+};
+export declare const hasExplicitSegmentPositioning: (line: Line) => boolean;
+export declare const applyParagraphLineIndentation: (params: ParagraphLineIndentationParams) => void;
+export declare const resolveAvailableWidthForLine: (params: {
+    containerWidth: number;
+    line: Line;
+    indentLeftPx: number;
+    indentRightPx: number;
+    firstLineOffset: number;
+    isFirstLine: boolean;
+    isListFirstLine: boolean;
+    resolvedListTextStartPx?: number;
+}) => number;

package/dist/layout-engine/painters/dom/src/paragraph/list-marker.d.ts

@@ -0,0 +1,51 @@
+import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
+import { ParagraphMeasure, ResolvedListMarkerItem, SourceAnchor } from '../../../../contracts/src/index.js';
+import { MinimalMarker, MinimalWordLayout, ResolvedListMarkerGeometry } from '../../../../../../shared/common/list-marker-utils';
+import { MarkerTrackedChangeView } from './marker-tracked-change.js';
+import { TrackedChangesRenderConfig } from '../runs/types.js';
+type PainterListTextStartParams = {
+    wordLayout: MinimalWordLayout | undefined;
+    indentLeftPx: number;
+    hangingIndentPx: number;
+    firstLineIndentPx: number;
+    markerTextWidthPx?: number;
+};
+export declare const resolvePainterListMarkerGeometry: ({ wordLayout, indentLeftPx, hangingIndentPx, firstLineIndentPx, markerTextWidthPx, }: PainterListTextStartParams) => ResolvedListMarkerGeometry | undefined;
+export declare const resolvePainterListTextStartPx: ({ wordLayout, indentLeftPx, hangingIndentPx, firstLineIndentPx, markerTextWidthPx, }: PainterListTextStartParams) => number | undefined;
+type MarkerRunStyle = {
+    fontFamily?: string | null;
+    fontSize?: number | null;
+    bold?: boolean | null;
+    italic?: boolean | null;
+    color?: string | null;
+    letterSpacing?: number | null;
+    vanish?: boolean | null;
+    allCaps?: boolean | null;
+    smallCaps?: boolean | null;
+};
+export declare const createListMarkerElement: (doc: Document, markerText: string, run: MarkerRunStyle, sourceAnchor?: SourceAnchor, resolvePhysical?: ResolvePhysicalFamily, trackedChange?: MarkerTrackedChangeView, trackedChangesConfig?: TrackedChangesRenderConfig) => HTMLElement;
+export declare const renderLegacyListMarker: (params: {
+    doc: Document;
+    lineEl: HTMLElement;
+    wordLayout?: MinimalWordLayout;
+    markerLayout: MinimalMarker;
+    markerMeasure: ParagraphMeasure["marker"];
+    markerTextWidthPx?: number;
+    indentLeftPx: number;
+    hangingIndentPx: number;
+    firstLineIndentPx: number;
+    isRtl?: boolean;
+    sourceAnchor?: SourceAnchor;
+    resolvePhysical?: ResolvePhysicalFamily;
+    trackedChangesConfig?: TrackedChangesRenderConfig;
+}) => void;
+export declare const renderResolvedListMarker: (params: {
+    doc: Document;
+    lineEl: HTMLElement;
+    marker: ResolvedListMarkerItem;
+    isRtl?: boolean;
+    sourceAnchor?: SourceAnchor;
+    resolvePhysical?: ResolvePhysicalFamily;
+    trackedChangesConfig?: TrackedChangesRenderConfig;
+}) => void;
+export {};

package/dist/layout-engine/painters/dom/src/paragraph/marker-tracked-change.d.ts

@@ -0,0 +1,34 @@
+import { TrackedChangesRenderConfig } from '../runs/types.js';
+/**
+ * Permissive view over both marker tracked-change shapes — the contracts
+ * `MarkerTrackedChange` (resolved path) and the `@superdoc/common`
+ * `MinimalMarkerTrackedChange` (legacy `wordLayout.marker` path). Both are
+ * structurally assignable to this view, so neither paint path needs a cast.
+ */
+export interface MarkerTrackedChangeView {
+    id: string;
+    kind: 'insert' | 'delete' | 'format';
+    groupedIds?: readonly string[];
+    type?: string;
+    subtype?: string;
+    targetKind?: string;
+    semanticColorKey?: string;
+    semanticColor?: string;
+    color?: string;
+    author?: string;
+    authorEmail?: string;
+    date?: string;
+    storyKey?: string;
+}
+/** Marker-specific marker class so CSS can target marker review chrome only. */
+export declare const TRACK_CHANGE_MARKER_CLASS = "track-list-marker-dec";
+/**
+ * Stamp a marker glyph span with tracked-change review metadata + Word-like
+ * styling. Shares the run vocabulary (`track-insert-dec` / `track-delete-dec` /
+ * `track-format-dec`, the `--sd-tracked-changes-*` variable family, and the
+ * semantic datasets) so marker and run review decorations stay consistent.
+ *
+ * @param markerEl - The `.superdoc-paragraph-marker` glyph span.
+ * @param tc - The marker tracked-change metadata (resolved or legacy shape).
+ */
+export declare const applyMarkerTrackedChange: (markerEl: HTMLElement, tc: MarkerTrackedChangeView | undefined, config?: TrackedChangesRenderConfig) => void;

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

@@ -0,0 +1,87 @@
+import { DropCapDescriptor, Line, ParagraphBlock, ParagraphMeasure, ResolvedParagraphContent, Run, SdtMetadata, SourceAnchor } from '../../../../contracts/src/index.js';
+import { MinimalWordLayout } from '../../../../../../shared/common/list-marker-utils';
+import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
+import { SdtAncestorOptions, SdtBoundaryOptions } from '../sdt/container.js';
+import { BetweenBorderInfo } from './borders/index.js';
+export type RenderedParagraphLineInfo = {
+    el: HTMLElement;
+    top: number;
+    height: number;
+};
+export type ParagraphRenderLineInput = {
+    block: ParagraphBlock;
+    line: Line;
+    lineIndex: number;
+    isLastLine: boolean;
+    availableWidth?: number;
+    skipJustify?: boolean;
+    preExpandedRuns?: Run[];
+    resolvedListTextStartPx?: number;
+    indentOffsetOverride?: number;
+    paragraphMarkLeftOffsetOverride?: number;
+};
+export type ParagraphRenderLine = (input: ParagraphRenderLineInput) => HTMLElement;
+export type ParagraphRenderDropCap = (descriptor: DropCapDescriptor, measure?: {
+    width: number;
+    height: number;
+    lines: number;
+    mode: 'drop' | 'margin';
+}) => HTMLElement;
+export type ParagraphContainerKind = 'body-fragment' | 'table-cell';
+type ParagraphSpacingPolicy = {
+    isFirstBlock: boolean;
+    isLastBlock: boolean;
+    paddingTop: number;
+};
+export type RenderParagraphContentParams = {
+    doc: Document;
+    frameEl: HTMLElement;
+    block: ParagraphBlock;
+    measure: ParagraphMeasure;
+    containerKind: ParagraphContainerKind;
+    width: number;
+    localStartLine: number;
+    localEndLine: number;
+    linesOverride?: Line[];
+    lineIndexOffset?: number;
+    continuesFromPrev?: boolean;
+    continuesOnNext?: boolean;
+    markerWidth?: number;
+    markerTextWidth?: number;
+    wordLayout?: MinimalWordLayout;
+    resolvedContent?: ResolvedParagraphContent;
+    betweenInfo?: BetweenBorderInfo;
+    sdtBoundary?: SdtBoundaryOptions;
+    spacingPolicy?: ParagraphSpacingPolicy;
+    ancestorContainerKey?: string | null;
+    ancestorContainerSdt?: SdtMetadata | null;
+    ancestorContainerKeys?: SdtAncestorOptions['ancestorContainerKeys'];
+    ancestorContainerSdts?: SdtAncestorOptions['ancestorContainerSdts'];
+    onSdtContainerChrome?: () => void;
+    applySdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    applyContainerSdtDataset?: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    renderLine: ParagraphRenderLine;
+    renderDropCap?: ParagraphRenderDropCap;
+    /**
+     * Per-document logical->physical font resolver for list markers. Threaded from the renderer's
+     * per-document resolver so a marker paints the same physical family it was measured in. Undefined
+     * (or omitted) falls back to the global resolver, matching text runs and field annotations.
+     */
+    resolvePhysical?: ResolvePhysicalFamily;
+    captureLineSnapshot?: (lineEl: HTMLElement, options?: {
+        inTableParagraph?: boolean;
+        wrapperEl?: HTMLElement;
+        sourceAnchor?: SourceAnchor;
+    }) => void;
+    convertFinalParagraphMark?: boolean;
+    lineTopOffset?: number;
+    sourceAnchor?: SourceAnchor;
+    contentControlsChrome?: 'default' | 'none';
+};
+export type RenderParagraphContentResult = {
+    renderedHeight: number;
+    totalHeight: number;
+    renderedLines: RenderedParagraphLineInfo[];
+};
+export declare const renderParagraphContent: (params: RenderParagraphContentParams) => RenderParagraphContentResult;
+export {};

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

@@ -0,0 +1,33 @@
+import { ParaFragment, ResolvedFragmentItem, SdtMetadata } from '../../../../contracts/src/index.js';
+import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
+import { SdtBoundaryOptions } from '../sdt/container.js';
+import { BetweenBorderInfo } from './borders/index.js';
+import { ParagraphRenderLineInput } from './renderParagraphContent.js';
+type ApplyStyles = (el: HTMLElement, styles: Partial<CSSStyleDeclaration>) => void;
+type RenderParagraphFragmentParams = {
+    doc: Document | null;
+    fragment: ParaFragment;
+    sdtBoundary?: SdtBoundaryOptions;
+    betweenInfo?: BetweenBorderInfo;
+    resolvedItem?: ResolvedFragmentItem;
+    applyStyles: ApplyStyles;
+    applyResolvedFragmentFrame: (el: HTMLElement, item: ResolvedFragmentItem, fragment: ParaFragment) => void;
+    applyFragmentFrame: (el: HTMLElement, fragment: ParaFragment) => void;
+    applySdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    applyContainerSdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    renderLine: (input: ParagraphRenderLineInput) => HTMLElement;
+    captureLineSnapshot: (lineEl: HTMLElement, options?: {
+        sourceAnchor?: ResolvedFragmentItem['sourceAnchor'];
+        wrapperEl?: HTMLElement;
+    }) => void;
+    createErrorPlaceholder: (blockId: string, error: unknown) => HTMLElement;
+    contentControlsChrome?: 'default' | 'none';
+    /**
+     * Per-document logical->physical font resolver for the drop cap and list markers. Threaded from
+     * the renderer's per-document resolver so they paint the same physical family they were measured
+     * in. Undefined falls back to the global resolver, matching text runs and field annotations.
+     */
+    resolvePhysical?: ResolvePhysicalFamily;
+};
+export declare const renderParagraphFragment: (params: RenderParagraphFragmentParams) => HTMLElement;
+export {};

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

@@ -0,0 +1,3 @@
+import { ParagraphAttrs } from '../../../../contracts/src/index.js';
+export declare const applyParagraphBlockStyles: (element: HTMLElement, attrs?: ParagraphAttrs) => void;
+export declare const clearParagraphFrameIndentStyles: (element: HTMLElement) => void;