superdoc 2.2.1 → 2.4.0-next.1

package/dist/layout-engine/painters/dom/src/runs/tracked-changes.d.ts

@@ -0,0 +1,90 @@
+import { Run, TextRun, TrackedChangeKind, TrackedChangeMeta, TrackedChangesMode } from '../../../../contracts/src/index.js';
+import { TrackedChangesRenderConfig } from './types.js';
+export declare const TRACK_CHANGE_BASE_CLASS: Record<TrackedChangeKind, string>;
+/**
+ * Resolve the color used for the kind-level tracked-change CSS variable family.
+ *
+ * Plain insertion/deletion semantic colors are the default change-kind palette.
+ * When an author color is present it remains the visible insert/delete/format
+ * highlight color. Side/structural semantic categories (`move-from`,
+ * `table-insertion`, `table-cell-insertion`, `cell-merge`, etc.) are explicit
+ * semantic paint roles and keep semantic precedence.
+ */
+export declare const resolveTrackedChangeVisualColor: (layer: TrackedChangeMeta) => string | undefined;
+/**
+ * Stamps the element-scoped CSS variable family for a single tracked-change
+ * layer from its resolved visual color. `meta.color` remains the per-author
+ * color and is still surfaced separately as `data-track-change-author-color`.
+ * The painter reads only paint-ready metadata; color resolution (overrides /
+ * resolver / fallback) happened upstream in layout-adapter. Focused backgrounds
+ * are derived from the visual color with alpha and only when it is a hex string
+ * `colorWithAlpha` can safely extend (named/non-hex visual colors still set
+ * border/text but never fabricate a derived background).
+ */
+export declare const applyTrackedChangeColorVariables: (elem: HTMLElement, layer: TrackedChangeMeta) => void;
+export declare const TRACK_CHANGE_MODIFIER_CLASS: Record<TrackedChangeKind, Record<TrackedChangesMode, string | undefined>>;
+/**
+ * Stamps the semantic class + datasets for a tracked-change layer. Shared by
+ * inline, row-level, and cell-level paint paths so the dataset/class vocabulary
+ * stays identical. Only fields that are present are stamped; this never reads
+ * or writes the author `color` dataset. The semantic datasets are namespaced
+ * (`data-track-change-semantic-*`, `-type`, `-subtype`, `-target-kind`,
+ * `-semantic-anchor-scope`) so they never collide with the existing author/
+ * structural datasets even when row + cell metadata coexist.
+ */
+export declare const applySemanticTrackedChangeMetadata: (elem: HTMLElement, meta: TrackedChangeMeta) => void;
+type TrackedChangeCarrier = Partial<Pick<TextRun, 'trackedChange' | 'trackedChanges'>>;
+type TrackedChangeDecoratable = Run | TrackedChangeCarrier;
+export declare const getTrackedChangeLayers: (carrier: TrackedChangeDecoratable) => TrackedChangeMeta[];
+export declare const resolveTrackedChangesConfig: (block: {
+    attrs?: unknown;
+}) => TrackedChangesRenderConfig;
+/**
+ * Applies a structural row-level tracked change (inserted/deleted whole row) to
+ * a single table cell element, reusing the exact same machinery as inline runs:
+ * the shared {@link TrackedChangeMeta}, the `TRACK_CHANGE_BASE_CLASS`
+ * (`track-insert-dec` / `track-delete-dec`), the `TRACK_CHANGE_MODIFIER_CLASS`
+ * mode map (insert → review:highlighted / original:hidden / final:normal;
+ * delete → review:highlighted / original:normal / final:hidden), and
+ * `applyTrackedChangeColorVariables` for the tracked-change CSS variable family
+ * (author colors own plain insert/delete highlights; semantic categories own
+ * move/table/cell visuals).
+ *
+ * The painter renders a row as cells appended to a container (there is no
+ * `<tr>` element), so the row's tracked-change visual is applied to each cell.
+ * Boundary-safe: this lives in the painter and only reads paint-ready
+ * `TrackedChangeMeta` from contracts.
+ *
+ * @param elem - The cell element to decorate.
+ * @param meta - The row's resolved tracked-change metadata.
+ * @param config - Tracked-changes mode/enabled (same source inline runs use).
+ */
+export declare const applyRowTrackedChangeToCell: (elem: HTMLElement, meta: TrackedChangeMeta, config: TrackedChangesRenderConfig) => void;
+/**
+ * Applies a cell-level structural tracked change (SD-3481
+ * `TableCellAttrs.trackedChange`: cell insertion/deletion, merge, or split) to a
+ * single table cell element. Mirrors {@link applyRowTrackedChangeToCell} but
+ * carries its own marker class {@link TRACK_CHANGE_CELL_CLASS} so cell-level CSS
+ * never affects inline spans or row-level decorations, and supports the
+ * `format` kind (merge/split paint through the `--sd-tracked-changes-format-*`
+ * family).
+ *
+ * Visual color uses {@link resolveTrackedChangeVisualColor} via
+ * {@link applyTrackedChangeColorVariables}; semantic class/datasets come from
+ * {@link applySemanticTrackedChangeMetadata}.
+ *
+ * Coexistence with a row-level tracked change: when this cell already carries a
+ * row-level decoration (`track-row-cell-dec`), the row keeps ownership of the
+ * shared single-value datasets and same-kind color variable family (row
+ * precedence). Different-kind cell metadata still stamps its own independent
+ * variable family (for example format vars for a cell merge inside an inserted
+ * row), and the semantic datasets/classes are always added so neither
+ * structural marker is dropped.
+ *
+ * @param elem - The cell element to decorate.
+ * @param meta - The cell's resolved tracked-change metadata.
+ * @param config - Tracked-changes mode/enabled (same source inline runs use).
+ */
+export declare const applyCellTrackedChangeToCell: (elem: HTMLElement, meta: TrackedChangeMeta, config: TrackedChangesRenderConfig) => void;
+export declare const applyTrackedChangeDecorations: (elem: HTMLElement, run: TrackedChangeDecoratable, config: TrackedChangesRenderConfig) => void;
+export {};

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

@@ -0,0 +1,67 @@
+import { ImageHyperlink, ParagraphBlock, Run, SdtMetadata, TrackedChangesMode } from '../../../../contracts/src/index.js';
+import { FragmentRenderContext } from '../renderer.js';
+import { PositionValidationCollector } from '../pm-position-validation.js';
+export type RenderedLineInfo = {
+    el: HTMLElement;
+    top: number;
+    height: number;
+};
+export type TrackedChangesRenderConfig = {
+    mode: TrackedChangesMode;
+    enabled: boolean;
+};
+export type LinkRenderData = {
+    href?: string;
+    target?: string;
+    rel?: string;
+    tooltip?: string | null;
+    dataset?: Record<string, string>;
+    blocked: boolean;
+};
+export type RunRenderContext = {
+    doc: Document;
+    layoutEpoch: number;
+    showFormattingMarks: boolean;
+    contentControlsChrome: 'default' | 'none';
+    /**
+     * Per-document logical->physical font resolver, FACE-aware: the substitute applies only when it
+     * provides the run's face (weight/style), else the logical family passes through (no faux-style).
+     * Undefined => global bundled default (family-level).
+     */
+    resolvePhysical?: (cssFontFamily: string, face: {
+        weight: '400' | '700';
+        style: 'normal' | 'italic';
+    }) => string;
+    pendingTooltips: WeakMap<HTMLElement, string>;
+    getNextLinkId: () => string;
+    applySdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    buildImageHyperlinkAnchor: (child: HTMLElement, hyperlink: ImageHyperlink | undefined, display: string) => HTMLElement;
+    resolveTrackedChangesConfig: (block: ParagraphBlock) => TrackedChangesRenderConfig;
+    applyTrackedChangeDecorations: (elem: HTMLElement, run: Run, config: TrackedChangesRenderConfig) => void;
+    resolveRunSdtId: (run: Run) => {
+        sdtId: string;
+        sdt: SdtMetadata;
+    } | null;
+    createInlineSdtWrapper: (sdt: SdtMetadata) => HTMLElement;
+    syncInlineSdtWrapperTypography: (wrapper: HTMLElement, runForSizing?: Run) => void;
+    expandSdtWrapperPmRange: (wrapper: HTMLElement, pmStart?: number | null, pmEnd?: number | null) => void;
+    /**
+     * Painter-scoped position-coverage collector (dark by default). The run
+     * dispatcher (`renderRun`) records one content-free structural observation
+     * per rendered run through this sink; absent on ad-hoc/test contexts.
+     */
+    positionValidation?: PositionValidationCollector;
+};
+export type RenderLineParams = {
+    block: ParagraphBlock;
+    line: import('../../../../contracts/src/index.js').Line;
+    context: FragmentRenderContext;
+    availableWidthOverride?: number;
+    lineIndex?: number;
+    skipJustify?: boolean;
+    preExpandedRuns?: Run[];
+    resolvedListTextStartPx?: number;
+    indentOffsetOverride?: number;
+    paragraphMarkLeftOffsetOverride?: number;
+    runContext: RunRenderContext;
+};

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

@@ -0,0 +1,16 @@
+import { ResolvedPaintItem } from '../../../../contracts/src/index.js';
+import { SdtBoundaryOptions } from './container.js';
+/**
+ * The container-label keys a `computeSdtBoundaries` walk over `resolvedItems`
+ * WOULD add to `sdtLabelsRendered`, without mutating it. This is the pure
+ * "which labels does this page display" function the persistent-page reuse path
+ * compares against recorded per-page label state: label placement is
+ * cross-page prefix state that resolve stamps do not cover, so an untouched
+ * reuse is only safe when the recorded labels equal this expectation.
+ *
+ * Implemented BY running `computeSdtBoundaries` on a scratch copy of the
+ * prefix set (never a hand-maintained mirror), so the two can not drift.
+ * Pages without container items take the allocation-free fast path.
+ */
+export declare const computeExpectedSdtLabelKeys: (resolvedItems: readonly ResolvedPaintItem[], sdtLabelsRendered: ReadonlySet<string>) => ReadonlySet<string>;
+export declare const computeSdtBoundaries: (resolvedItems: readonly ResolvedPaintItem[], sdtLabelsRendered: Set<string>) => Map<number, SdtBoundaryOptions>;

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

@@ -0,0 +1,32 @@
+import { SdtMetadata, StructuredContentMetadata } from '../../../../contracts/src/index.js';
+export { getSdtContainerKey, getSdtContainerKeyForBlock, getSdtContainerMetadata, hasExplicitSdtContainerKey, } from '../../../../contracts/src/index.js';
+export type SdtContainerConfig = {
+    className: string;
+    labelText: string;
+    labelClassName: string;
+    isStart: boolean;
+    isEnd: boolean;
+} | null;
+export type SdtBoundaryOptions = {
+    isStart?: boolean;
+    isEnd?: boolean;
+    widthOverride?: number;
+    paddingBottomOverride?: number;
+    showLabel?: boolean;
+};
+export type SdtAncestorOptions = {
+    ancestorContainerKey?: string | null;
+    ancestorContainerSdt?: SdtMetadata | null;
+    ancestorContainerKeys?: readonly (string | null | undefined)[];
+    ancestorContainerSdts?: readonly (SdtMetadata | null | undefined)[];
+};
+export declare function isStructuredContentMetadata(sdt: SdtMetadata | null | undefined): sdt is StructuredContentMetadata;
+export declare function isDocumentSectionMetadata(sdt: SdtMetadata | null | undefined): sdt is {
+    type: 'documentSection';
+    title?: string | null;
+};
+export declare function getSdtContainerConfig(sdt: SdtMetadata | null | undefined): SdtContainerConfig;
+export declare function shouldRenderSdtContainerChrome(sdt?: SdtMetadata | null, containerSdt?: SdtMetadata | null, options?: SdtAncestorOptions): boolean;
+export declare function getSdtSiblingBoundaries(containerKeys: readonly (string | null)[]): Array<SdtBoundaryOptions | undefined>;
+export declare function applySdtContainerChrome(doc: Document, container: HTMLElement, sdt: SdtMetadata | null | undefined, containerSdt?: SdtMetadata | null | undefined, boundaryOptions?: SdtBoundaryOptions, options?: SdtAncestorOptions, chrome?: 'default' | 'none'): boolean;
+export declare function shouldRebuildForSdtBoundary(element: HTMLElement, boundary: SdtBoundaryOptions | undefined): boolean;

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

@@ -0,0 +1,7 @@
+import { SdtMetadata } from '../../../../contracts/src/index.js';
+export declare const clearSdtDataset: (el: HTMLElement) => void;
+export declare const applySdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+export declare const applyContainerSdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+export declare const getSdtMetadataId: (metadata: SdtMetadata | null | undefined) => string;
+export declare const getSdtMetadataLockMode: (metadata: SdtMetadata | null | undefined) => string;
+export declare const getSdtMetadataVersion: (metadata: SdtMetadata | null | undefined) => string;

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

@@ -0,0 +1,9 @@
+import { Run, SdtMetadata } from '../../../../contracts/src/index.js';
+import { RunRenderContext } from '../runs/types.js';
+export declare const resolveRunSdtId: (run: Run) => {
+    sdtId: string;
+    sdt: SdtMetadata;
+} | null;
+export declare const createInlineSdtWrapper: (sdt: SdtMetadata, context: RunRenderContext) => HTMLElement;
+export declare const syncInlineSdtWrapperTypography: (wrapper: HTMLElement, runForSizing?: Run) => void;
+export declare const expandSdtWrapperPmRange: (wrapper: HTMLElement, pmStart?: number | null, pmEnd?: number | null) => void;

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

@@ -0,0 +1,29 @@
+import { LayoutSourceIdentity } from '../../../../contracts/src/index.js';
+export type PaintSnapshotStructuredContentBlockEntity = {
+    element: HTMLElement;
+    pageIndex: number;
+    sdtId: string;
+    pmStart?: number;
+    pmEnd?: number;
+    layoutSourceIdentity?: LayoutSourceIdentity;
+};
+export type PaintSnapshotStructuredContentInlineEntity = {
+    element: HTMLElement;
+    pageIndex: number;
+    sdtId: string;
+    pmStart?: number;
+    pmEnd?: number;
+    layoutSourceIdentity?: LayoutSourceIdentity;
+};
+export type SdtSnapshotEntities = {
+    structuredContentBlocks: PaintSnapshotStructuredContentBlockEntity[];
+    structuredContentInlines: PaintSnapshotStructuredContentInlineEntity[];
+};
+type CollectSdtSnapshotEntitiesOptions = {
+    resolvePageIndex: (element: HTMLElement) => number | null;
+    readDatasetNumber: (value: string | null | undefined) => number | null;
+    readLayoutSourceIdentity?: (element: HTMLElement) => LayoutSourceIdentity | undefined;
+    compactObject: <T extends Record<string, unknown>>(input: T) => T;
+};
+export declare const collectSdtSnapshotEntitiesFromDomRoot: (rootEl: HTMLElement, options: CollectSdtSnapshotEntitiesOptions) => SdtSnapshotEntities;
+export {};

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

@@ -0,0 +1,71 @@
+/**
+ * Fallback font-size applied to child elements inside a line container that
+ * carry no explicit fontSize. Matches the browser default so rendering is
+ * preserved after the strut-elimination fix (fontSize: '0' on lines).
+ */
+export declare const BROWSER_DEFAULT_FONT_SIZE = "16px";
+export declare const CLASS_NAMES: {
+    container: string;
+    page: string;
+    fragment: string;
+    line: string;
+    spread: string;
+    pageHeader: string;
+    pageFooter: string;
+    textRun: string;
+};
+export type PageStyles = {
+    background?: string;
+    boxShadow?: string;
+    border?: string;
+    margin?: string;
+    color?: string;
+};
+export declare const DEFAULT_PAGE_STYLES: Required<PageStyles>;
+export declare const containerStyles: Partial<CSSStyleDeclaration>;
+export declare const pageStyles: (width: number, height: number, overrides?: PageStyles) => Partial<CSSStyleDeclaration>;
+export declare const fragmentStyles: Partial<CSSStyleDeclaration>;
+/**
+ * Line container styles. z-index is intentionally not set on the line so that
+ * the resize overlay (and other UI) can stack above content. Only the image
+ * element itself gets z-index for layering within the line (e.g. above tab leaders).
+ */
+export declare const lineStyles: (lineHeight: number) => Partial<CSSStyleDeclaration>;
+/** One document-scoped stylesheet the paint surface requires: head marker attribute + CSS payload. */
+export type SurfaceStylePreflightEntry = {
+    markerAttribute: string;
+    cssText: string;
+};
+export declare const ensurePrintStyles: (doc: Document | null | undefined) => void;
+export declare const ensureDocumentSurfaceStyles: (doc: Document | null | undefined) => void;
+export declare const ensureLinkStyles: (doc: Document | null | undefined) => void;
+export declare const ensureTrackChangeStyles: (doc: Document | null | undefined) => void;
+export declare const ensureFormattingMarksStyles: (doc: Document | null | undefined) => void;
+export declare const ensureSdtContainerStyles: (doc: Document | null | undefined) => void;
+export declare const ensureFieldAnnotationStyles: (doc: Document | null | undefined) => void;
+/**
+ * Injects image selection highlight styles into the document head.
+ * Ensures styles are only injected once per document lifecycle.
+ * @param {Document | null | undefined} doc - The document to inject styles into
+ * @returns {void}
+ */
+export declare const ensureImageSelectionStyles: (doc: Document | null | undefined) => void;
+/**
+ * Injects the MathML <menclose> polyfill into the document head. Required
+ * because no browser paints menclose natively (MathML Core dropped it). See
+ * MATH_MENCLOSE_STYLES for the full rationale.
+ */
+export declare const ensureMathMencloseStyles: (doc: Document | null | undefined) => void;
+/**
+ * Injects footnote/endnote interaction styles (text cursor over note content)
+ * into the document head. Injected once per document lifecycle. (SD-3400)
+ */
+export declare const ensureFootnoteStyles: (doc: Document | null | undefined) => void;
+export declare const SURFACE_STYLE_PREFLIGHT: readonly SurfaceStylePreflightEntry[];
+/**
+ * Installs the full document-scoped style preflight (idempotent, one
+ * `head.querySelector` per marker). The ONLY sanctioned way for a paint entry
+ * to install document-level styles — per-path `ensure*Styles()` call lists
+ * are the drift mechanism this helper exists to kill.
+ */
+export declare const ensureSurfaceStylePreflight: (doc: Document | null | undefined) => void;

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

@@ -0,0 +1,101 @@
+import { GradientFill, SolidFillWithAlpha, ShapeTextContent } from '../../../contracts/src/index.js';
+/**
+ * Validates and sanitizes a hex color string to prevent XSS attacks.
+ *
+ * Accepts hex colors in the following formats:
+ * - 3-digit hex: #RGB (e.g., #F00)
+ * - 6-digit hex: #RRGGBB (e.g., #FF0000)
+ * - 3-digit hex without #: RGB (e.g., F00)
+ * - 6-digit hex without #: RRGGBB (e.g., FF0000)
+ *
+ * @param color - The color string to validate
+ * @returns The validated and normalized hex color with # prefix, or undefined if invalid
+ *
+ * @example
+ * ```typescript
+ * validateHexColor('#FF0000'); // '#FF0000'
+ * validateHexColor('FF0000'); // '#FF0000'
+ * validateHexColor('#F00'); // '#F00'
+ * validateHexColor('F00'); // '#F00'
+ * validateHexColor('javascript:alert(1)'); // undefined (XSS attempt)
+ * validateHexColor('#GGGGGG'); // undefined (invalid hex)
+ * validateHexColor('red'); // undefined (named colors not supported)
+ * ```
+ */
+export declare function validateHexColor(color: string): string | undefined;
+/**
+ * Creates an SVG gradient element (linear or radial)
+ */
+export declare function createGradient(gradientData: GradientFill, gradientId: string): SVGLinearGradientElement | SVGRadialGradientElement | null;
+/**
+ * Creates an SVG foreignObject with formatted text content
+ */
+export declare function createTextElement(textContent: ShapeTextContent, textAlign: string, width: number, height: number): SVGForeignObjectElement;
+/**
+ * Applies a gradient to all filled elements in an SVG.
+ *
+ * Creates a gradient definition using the provided gradient data and applies it
+ * to all filled elements in the SVG. Uses the shared createGradient utility to
+ * ensure consistent gradient creation with validation.
+ *
+ * Gracefully handles DOM errors to prevent crashes.
+ *
+ * @param svg - The SVG element to apply the gradient to
+ * @param gradientData - The gradient fill configuration
+ *
+ * @example
+ * ```typescript
+ * const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+ * applyGradientToSVG(svg, {
+ *   type: 'gradient',
+ *   gradientType: 'linear',
+ *   angle: 90,
+ *   stops: [
+ *     { position: 0, color: '#FF0000', alpha: 1 },
+ *     { position: 1, color: '#0000FF', alpha: 1 }
+ *   ]
+ * });
+ * ```
+ */
+export declare function applyGradientToSVG(svg: SVGElement, gradientData: GradientFill): void;
+/**
+ * Applies alpha transparency to all filled elements in an SVG.
+ *
+ * Validates the color format before applying to prevent XSS attacks.
+ * Clamps alpha value to the 0-1 range.
+ * Gracefully handles DOM errors to prevent crashes.
+ *
+ * @param svg - The SVG element to apply the fill to
+ * @param alphaData - The solid fill with alpha configuration
+ *
+ * @example
+ * ```typescript
+ * const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+ * applyAlphaToSVG(svg, { type: 'solidWithAlpha', color: '#FF0000', alpha: 0.5 });
+ * ```
+ */
+export declare function applyAlphaToSVG(svg: SVGElement, alphaData: SolidFillWithAlpha): void;
+/**
+ * Generates CSS transform strings from shape attributes
+ */
+export declare function generateTransforms(attrs: {
+    rotation?: number;
+    flipH?: boolean;
+    flipV?: boolean;
+}): string[];
+/**
+ * Generates a unique gradient ID with optional prefix.
+ *
+ * Uses a combination of timestamp, counter, and random string to ensure uniqueness
+ * even when multiple gradients are created in the same millisecond.
+ *
+ * @param prefix - Optional prefix for the gradient ID (defaults to 'gradient')
+ * @returns A unique gradient ID string
+ *
+ * @example
+ * ```typescript
+ * generateGradientId(); // 'gradient-1700000000000-0-abc123def'
+ * generateGradientId('linear'); // 'linear-1700000000000-1-xyz789ghi'
+ * ```
+ */
+export declare function generateGradientId(prefix?: string): string;

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

@@ -0,0 +1,185 @@
+import { BorderSpec, CellBorders, TableBorderValue, TableBorders, TableFragment } from '../../../../contracts/src/index.js';
+import { TableCellGridPosition } from './grid-geometry.js';
+/**
+ * Applies a border specification to one side of an HTML element.
+ *
+ * Converts BorderSpec format to CSS border properties and applies them to the specified
+ * side of the element. Handles style conversion (e.g., 'single' → 'solid'), color validation,
+ * and special cases like 'thick' borders which use doubled width.
+ *
+ * @param element - The HTML element to apply the border to
+ * @param side - Which side of the element to apply the border ('Top', 'Right', 'Bottom', or 'Left')
+ * @param border - The border specification to apply, or undefined to skip
+ *
+ * @example
+ * ```typescript
+ * const cell = document.createElement('td');
+ * applyBorder(cell, 'Top', { style: 'single', width: 2, color: '#FF0000' });
+ * // Sets cell.style.borderTop = '2px solid #FF0000'
+ * ```
+ */
+export declare const applyBorder: (element: HTMLElement, side: "Top" | "Right" | "Bottom" | "Left", border?: BorderSpec) => void;
+/**
+ * Applies border specifications to all four sides of a table cell element.
+ *
+ * Convenience function that applies borders to top, right, bottom, and left sides
+ * of an element using applyBorder(). Only applies borders for sides that are defined
+ * in the CellBorders object.
+ *
+ * @param element - The HTML element (typically a table cell) to apply borders to
+ * @param borders - Cell border specifications for each side, or undefined to skip
+ *
+ * @example
+ * ```typescript
+ * const cell = document.createElement('td');
+ * applyCellBorders(cell, {
+ *   top: { style: 'single', width: 1, color: '#000000' },
+ *   left: { style: 'double', width: 2, color: '#FF0000' }
+ * });
+ * ```
+ */
+export declare const applyCellBorders: (element: HTMLElement, borders?: CellBorders) => void;
+/**
+ * Converts a TableBorderValue to a BorderSpec for rendering.
+ *
+ * Handles conversion of table-level border values (which may include {none: true} markers)
+ * to BorderSpec format used by the DOM renderer. Supports both 'width' and legacy 'size'
+ * properties.
+ *
+ * @param value - Table border value to convert, or null/undefined
+ * @returns BorderSpec for rendering, or undefined if value is null/undefined
+ *
+ * @example
+ * ```typescript
+ * const spec = borderValueToSpec({ style: 'single', width: 2, color: '#FF0000' });
+ * // Returns: { style: 'single', width: 2, color: '#FF0000' }
+ *
+ * const none = borderValueToSpec({ none: true });
+ * // Returns: { style: 'none', width: 0 }
+ * ```
+ */
+export declare const borderValueToSpec: (value?: TableBorderValue | null) => BorderSpec | undefined;
+/**
+ * Resolves a table border value with fallback support.
+ *
+ * Attempts to use the explicit border value first, falling back to the fallback value
+ * if the explicit value is undefined or null. This is used when cell borders can come
+ * from either cell-specific definitions or table-level definitions.
+ *
+ * @param explicit - Primary border value to use (e.g., from cell attributes)
+ * @param fallback - Fallback border value (e.g., from table borders)
+ * @returns Resolved BorderSpec, or undefined if both values are undefined/null
+ *
+ * @example
+ * ```typescript
+ * const cellBorder = { style: 'double', width: 3, color: '#FF0000' };
+ * const tableBorder = { style: 'single', width: 1, color: '#000000' };
+ * const result = resolveTableBorderValue(cellBorder, tableBorder);
+ * // Returns BorderSpec from cellBorder (explicit wins)
+ * ```
+ */
+export declare const resolveTableBorderValue: (explicit: TableBorderValue | undefined | null, fallback?: TableBorderValue | undefined | null) => BorderSpec | undefined;
+export declare const isPresentBorder: (b?: BorderSpec) => b is BorderSpec;
+/**
+ * True when a border is EXPLICITLY set to none/nil (`w:val="nil"`/`"none"`), as opposed to
+ * simply unset/absent. The distinction matters for shared interior edges (§17.4.66): an
+ * explicit none on BOTH adjacent cells suppresses the divider, while an unset side inherits
+ * the table's insideH/insideV. Accepts either a CellBorders BorderSpec (`{style:'none'}`) or
+ * a TableBorderValue (`{none:true}`).
+ */
+export declare const isExplicitNoneBorder: (b?: unknown) => boolean;
+/**
+ * OOXML cell-border conflict resolution (ECMA-376 §17.4.66).
+ *
+ * With zero cell spacing, two cells sharing an edge each specify a border; the spec
+ * collapses them to a SINGLE displayed border:
+ *  1. If either side is nil/none/absent, the opposing (present) border is displayed.
+ *  2. Otherwise the border with greater weight wins, where
+ *     weight = (#lines in the style) × (style number).
+ *  3. Equal weight → the style higher on the precedence list (single first) wins.
+ *  4. Identical style → the color with the smaller brightness (R+B+2G, then B+2G, then
+ *     G) wins; finally the first border (reading order) wins.
+ *
+ * @param a - One side's border (the owning cell's, e.g. the lower/right cell)
+ * @param b - The opposing side's border (e.g. the upper/left neighbor)
+ * @returns The single BorderSpec to display, or undefined if neither is present.
+ */
+export declare const resolveBorderConflict: (a?: BorderSpec, b?: BorderSpec) => BorderSpec | undefined;
+/**
+ * Creates a border overlay element for a table fragment.
+ *
+ * Generates an absolutely-positioned div that renders table-level borders (top, right,
+ * bottom, left) on top of the table content. This is used to apply outer table borders
+ * without affecting the table's internal layout.
+ *
+ * @param doc - Document object for creating the overlay element
+ * @param fragment - Table fragment containing dimensions for the overlay
+ * @param tableBorders - Table border specifications
+ * @returns HTMLElement overlay with borders applied, or null if no borders are defined
+ *
+ * @example
+ * ```typescript
+ * const overlay = createTableBorderOverlay(document, fragment, {
+ *   top: { style: 'single', width: 2, color: '#000000' },
+ *   bottom: { style: 'single', width: 2, color: '#000000' }
+ * });
+ * if (overlay) container.appendChild(overlay);
+ * ```
+ */
+export declare const createTableBorderOverlay: (doc: Document, fragment: TableFragment, tableBorders: TableBorders) => HTMLElement | null;
+/**
+ * Resolves cell-specific borders based on cell position within a table.
+ *
+ * Implements a **single-owner border model** to prevent double borders when
+ * rendering tables with absolutely-positioned divs (which don't support CSS
+ * border-collapse). Each shared border is owned by exactly one cell:
+ *
+ * - TOP border: Cell owns its own top (first row uses table.top, others use insideH)
+ * - LEFT border: Cell owns its own left (first col uses table.left, others use insideV)
+ * - BOTTOM border: Only last row renders it (using table.bottom)
+ * - RIGHT border: Only last column renders it (using table.right)
+ *
+ * This ensures each border line is rendered exactly once, eliminating the
+ * double-border issue that occurs when adjacent cells both render their
+ * shared edge.
+ *
+ * @param tableBorders - Table-level border definitions
+ * @param cellPosition - Cell position and span within the table grid
+ * @returns CellBorders object with resolved borders for all four sides
+ *
+ * @example
+ * ```typescript
+ * // For a 3x3 table:
+ * // Cell (0,0): top=table.top, left=table.left, bottom=undefined, right=undefined
+ * // Cell (1,1): top=insideH, left=insideV, bottom=undefined, right=undefined
+ * // Cell (2,2): top=insideH, left=insideV, bottom=table.bottom, right=table.right
+ * ```
+ */
+/**
+ * Checks whether a CellBorders object has at least one explicitly defined side.
+ *
+ * Returns false when borders is undefined/null or when all four sides are undefined.
+ * Used to distinguish "no borders attribute" from "borders attribute present but empty"
+ * (intentionally borderless).
+ *
+ * @param cellBorders - Cell border definitions to check
+ * @returns True if at least one side (top, right, bottom, left) is defined
+ */
+export declare const hasExplicitCellBorders: (cellBorders?: CellBorders) => cellBorders is CellBorders;
+export declare const resolveTableCellBorders: (tableBorders: {
+    top?: TableBorderValue;
+    bottom?: TableBorderValue;
+    left?: TableBorderValue;
+    right?: TableBorderValue;
+    insideH?: TableBorderValue;
+    insideV?: TableBorderValue;
+}, cellPosition: TableCellGridPosition) => CellBorders;
+/**
+ * Swap left↔right on table borders for RTL tables (ECMA-376 Part 4 §14.3.2, §14.3.6).
+ * insideH/insideV and top/bottom are not affected by direction.
+ */
+export declare const swapTableBordersLR: (borders: TableBorders | undefined) => TableBorders | undefined;
+/**
+ * Swap left↔right on cell borders for RTL tables (ECMA-376 Part 4 §14.3.1, §14.3.5).
+ */
+export declare const swapCellBordersLR: (borders: CellBorders | undefined) => CellBorders | undefined;