superdoc 2.2.1 → 2.3.0

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

@@ -0,0 +1,66 @@
+import { Line, LineSegment, Run } from '../../../../contracts/src/index.js';
+type UnderlinePaintRun = {
+    underline?: {
+        style?: string;
+        color?: string;
+    } | null;
+    fontSize?: number;
+    color?: string;
+};
+type UnderlineSource = Run | UnderlinePaintRun;
+export declare const underlineStyleForRun: (run: UnderlineSource) => string | undefined;
+export declare const canPaintUnderlineAsBorder: (run: UnderlineSource) => boolean;
+/**
+ * Whether the line-level underline overlay may own this run's underline (SD-3330).
+ *
+ * Scoped to the styles a single CSS `border-top` reproduces faithfully: `single`, `double`,
+ * `dotted`, `dashed`. Everything else stays on its existing path on purpose, so the overlay
+ * never silently flattens a distinct style into solid inside a "continuous" line:
+ * - `none` paints nothing (rejected by canPaintUnderlineAsBorder);
+ * - `wave`, `thick`, and the OOXML heavy/compound spellings (`dotDash`, `dashLongHeavy`, ...) a
+ *   border-top cannot draw - they keep their current (degraded) per-run rendering.
+ *
+ * `words` is NOT solved end-to-end here. canPaintUnderlineAsBorder rejects a literal `words`, but
+ * the v1 adapter's normalizeUnderlineStyle collapses OOXML `words` to `single` BEFORE paint, so a
+ * `words` underline reaches this layer as `single` and gets overlaid - it does not reproduce Word's
+ * "underline the words, not the tab whitespace". Fixing that needs an importer/adapter change and is
+ * out of scope for the seam fix; the guard here is only defensive for a producer that passes `words` raw.
+ *
+ * Color is a separate axis: this gate is style-only, and underlineBorderForRun does not resolve
+ * theme/`auto` underline colors (it uses the literal color string, as the prior border path did),
+ * so theme-color fidelity is out of scope here too.
+ *
+ * Mixed lines stay per-run: a single-underlined tab can be overlaid while an adjacent wavy run
+ * keeps its native text-decoration.
+ */
+export declare const canPaintUnderlineOverlay: (run: UnderlineSource) => boolean;
+export declare const underlineBorderForRun: (run: UnderlineSource) => string | undefined;
+export declare const renderInlineTabRun: (run: Extract<Run, {
+    kind: "tab";
+}>, line: Line, doc: Document, layoutEpoch: number, styleId?: string, paintUnderline?: boolean, 
+/**
+ * Measured tab width in pixels, pre-resolved by the caller from Line.tabWidths
+ * keyed by block.runs index. Preferred over run.width because it survives
+ * FlowBlock re-projection that creates fresh run objects (run.width not re-set).
+ */
+tabWidthFromCache?: number) => HTMLElement;
+export declare const renderPositionedTabRun: (run: Extract<Run, {
+    kind: "tab";
+}>, line: Line, doc: Document, layoutEpoch: number, tabStartX: number, indentOffset: number, immediateNextSegment?: LineSegment, styleId?: string, paintUnderline?: boolean) => {
+    element: HTMLElement;
+    tabEndX: number;
+    actualTabWidth: number;
+};
+/**
+ * Distance, in pixels from the top of the line box, at which a tab's underline
+ * (border-bottom) should be drawn so it lines up with the `text-decoration`
+ * underline of adjacent text runs.
+ *
+ * The line box places the baseline at `half-leading + ascent` from its top
+ * (the remaining `half-leading + descent` sits below). `text-decoration`
+ * underlines render slightly below the baseline, so we add a small gap that
+ * scales with font size (capped by the descent). This is geometry derived from
+ * the resolved line metrics. The painter never measures the DOM (SD-2957).
+ */
+export declare const underlineOffsetFromLineTop: (line: Line) => number;
+export {};

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

@@ -0,0 +1,35 @@
+import { Run, TextRun } from '../../../../contracts/src/index.js';
+import { FragmentRenderContext } from '../renderer.js';
+import { BROWSER_DEFAULT_FONT_SIZE } from '../styles.js';
+import { RunRenderContext, TrackedChangesRenderConfig } from './types.js';
+/**
+ * Underline thickness in px, scaled to font size. Shared by text runs
+ * (`text-decoration-thickness`) and tab underlines (border width) so a run's
+ * underline renders as a single uniform weight across text and tab characters,
+ * matching Word, on any display density (SD-3330). The divisor approximates the
+ * font's natural underline weight (≈ what `text-decoration-thickness: auto`
+ * produces) while staying deterministic across platforms.
+ *
+ * Rounded to an integer px because CSS borders snap to integer device pixels
+ * while `text-decoration-thickness` keeps fractional values; using an integer
+ * makes the tab border and the text underline rasterize to the same line weight.
+ */
+export declare const underlineThicknessPx: (fontSize: number) => number;
+/**
+ * Applies run styling properties to a DOM element.
+ *
+ * @param element - The HTML element to style
+ * @param run - The run object containing styling information
+ * @param _isLink - Whether this run is part of a hyperlink. Note: This parameter
+ *                  is kept for API compatibility but no longer affects behavior -
+ *                  inline colors are now applied to all runs (including links) to
+ *                  ensure OOXML hyperlink character styles appear correctly.
+ */
+export declare const applyRunStyles: (element: HTMLElement, run: Run, _isLink?: boolean, resolvePhysical?: (cssFontFamily: string, face: {
+    weight: "400" | "700";
+    style: "normal" | "italic";
+}) => string) => void;
+export declare const resolveRunText: (run: Run, context: FragmentRenderContext) => string;
+export declare const extractLinkData: (run: Run) => import('./types.js').LinkRenderData | null;
+export declare const renderTextRun: (run: TextRun, context: FragmentRenderContext, renderContext: RunRenderContext, trackedConfig?: TrackedChangesRenderConfig) => HTMLElement | null;
+export { BROWSER_DEFAULT_FONT_SIZE };

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 page-window 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;