domotion-svg 0.1.1

package/dist/dom-to-svg.d.ts

@@ -0,0 +1,1016 @@
+/**
+ * DOM-to-SVG Converter
+ *
+ * Uses Playwright to inspect DOM elements and recreate them as native SVG.
+ */
+import type { Page } from "@playwright/test";
+/**
+ * Convert a `file://` (or absolute filesystem) URL to a base64 data URI so the
+ * generated SVG is self-contained and renders in tools that block local-file
+ * references for security (most online SVG viewers, embeds, etc.). Pass-through
+ * for http(s):// and existing data: URLs. Returns the original string on any
+ * error so failures degrade gracefully.
+ */
+/**
+ * @internal — exposed for `resize-embedded-images.ts` (DM-539). The resize
+ * pre-pass reads source bytes from this cache (populated by `embedRemoteImages`)
+ * and writes per-(URL, size) resized variants into `_resizedDataUriCache`.
+ */
+export declare const _dataUriCache: Map<string, string>;
+/**
+ * @internal — DM-539. Per-source-URL map of sizeKey → resized data URI. The
+ * sizeKey is `${ceil(targetW * hiDPI)}x${ceil(targetH * hiDPI)}`. Populated by
+ * `resizeEmbeddedImages` (only when `embedRemoteImagesResize: true`); read by
+ * `embedResizedDataUri` (DM-540) when the renderer emits an `<image href>`.
+ * Empty at module load — first capture with the resize flag fills it.
+ */
+export declare const _resizedDataUriCache: Map<string, Map<string, string>>;
+/**
+ * @internal — DM-549. Per-conic-gradient-layer-text map of `${tileW}x${tileH}` →
+ * data URI containing rasterized PNG bytes. Populated by `rasterizeConicGradients`
+ * (the conic raster pre-pass) and read by `buildConicGradientDef` (DM-550) when
+ * the renderer emits a `<pattern><image>` for a conic background layer. Empty
+ * at module load — first capture with conic content fills it.
+ */
+export declare const _conicTileCache: Map<string, Map<string, string>>;
+/**
+ * DM-540 — renderer-side lookup for the image-resize-on-embed pipeline.
+ * Returns the resized PNG data URI for `(url, ceil(w * hiDPI), ceil(h * hiDPI))`
+ * when the resize pre-pass populated `_resizedDataUriCache` for that key;
+ * otherwise falls back to `embedAsDataUri(url)` so the renderer behaves
+ * identically to today when resize is disabled (no entries in the resized
+ * cache → source-resolution data URI returned).
+ */
+export declare function embedResizedDataUri(url: string, consumerW: number, consumerH: number, hiDPIFactor?: number): string;
+export interface EmbedRemoteImagesOptions {
+    /**
+     * DM-527: append per-URL fetch failures here as `CaptureWarning` entries.
+     * If omitted, warnings push to the module-global `lastCaptureWarnings`
+     * (visible via `getLastCaptureWarnings` / `logCaptureWarnings`). Concurrent
+     * captures should pass an explicit array to avoid racing on the global.
+     */
+    warnings?: CaptureWarning[];
+    /**
+     * DM-528: per-URL fetch timeout in ms. A stalled CDN host (slow DNS, slow
+     * first-byte, unresponsive origin) would otherwise hang the capture
+     * indefinitely — the parallel `Promise.all` won't resolve until every
+     * fetch settles. With this timeout the slowest fetch caps total pre-pass
+     * time at ~`timeoutMs * (retries + 1) + retryBackoffMs * retries` (since
+     * fetches run in parallel). Timed-out fetches produce a `remote-image`
+     * warning and the URL stays as-is in the SVG. Default 10000.
+     */
+    timeoutMs?: number;
+    /**
+     * DM-529: number of retry attempts for transient failures (5xx response,
+     * network error, or timeout). 4xx responses are not retried — those are
+     * deterministic and a retry would just consume time. The originating
+     * fetch + retries together can take up to
+     * `(retries + 1) * timeoutMs + retries * retryBackoffMs` per URL, so keep
+     * this small. Default 1.
+     */
+    retries?: number;
+    /**
+     * DM-529: delay (ms) between attempts when retrying a transient failure.
+     * Default 500.
+     */
+    retryBackoffMs?: number;
+}
+/**
+ * DM-512: fetch every http(s) image URL referenced by the captured tree and
+ * stash the resolved bytes as a data: URI in the renderer's data-URI cache.
+ * Subsequent calls to `embedAsDataUri` for those URLs return the cached data
+ * URI instead of passing the URL through verbatim — yielding a self-contained
+ * SVG that loads correctly in image viewers (Preview, Finder QuickLook, etc.)
+ * that don't fetch remote resources from local files.
+ *
+ * Walks the captured tree once collecting URLs from: `imageSrc` (for `<img>`),
+ * `pseudoImages[].url` (for `::before`/`::after` content: url(...)), and CSS
+ * `url(...)` tokens inside `styles.backgroundImage` / `.maskImage` /
+ * `.borderImageSource` / `.listStyleImage`. Dedupes per call.
+ *
+ * Per-URL fetch failures (network error, non-2xx, missing Content-Type) leave
+ * the URL in the tree as-is, so the SVG still references it. DM-527: each
+ * failure is surfaced as a `CaptureWarning` (feature: `remote-image`) carrying
+ * the URL and the HTTP status / error class, so callers can trace which images
+ * didn't inline. The warning is appended to `options.warnings` if supplied,
+ * otherwise to `getLastCaptureWarnings()`.
+ */
+export declare function embedRemoteImages(tree: CapturedElement[], options?: EmbedRemoteImagesOptions): Promise<void>;
+export interface TextSegment {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /**
+     * Per-character viewport-absolute x offsets (one entry per visible char in
+     * `text`). When provided, renderers anchor each glyph at xOffsets[i] instead
+     * of summing fontkit advances — closing the per-char drift that accumulates
+     * over long paragraphs. May be undefined when capture couldn't produce it
+     * (e.g. input/textarea values).
+     */
+    xOffsets?: number[];
+    /** Override color for this segment (e.g. ::before / ::after pseudos whose
+     *  CSS `color` differs from the element's). Renderer uses parent fill when
+     *  undefined. */
+    color?: string;
+    /** Override font-size in CSS pixels (e.g. abbr[title]::after { font-size: 0.9em }).
+     *  Undefined means inherit from the element. */
+    fontSize?: number;
+    /** Override font-weight (e.g. li[data-badge]::before { font-weight: bold }).
+     *  Undefined means inherit from the element. */
+    fontWeight?: string;
+    /** Override font-style (e.g. ::first-line { font-style: italic }). */
+    fontStyle?: string;
+    /** Override font-family (e.g. `.icon-angle-right { font-family: 'sdicon' }`
+     *  with `::before { content: '\\e87a' }` — the icon glyph routes through
+     *  the icon webfont, not the parent element's body font). DM-513. */
+    fontFamily?: string;
+    /** Override font-variant (e.g. ::first-line { font-variant: small-caps }).
+     *  When 'small-caps', renderer applies the OpenType `smcp` feature so
+     *  lowercase letters shape as small uppercase forms — Chrome paints them
+     *  the same way and the captured xOffsets already encode the small-caps
+     *  advance widths, so the only thing the renderer needs to change is the
+     *  glyph variant per character. (DM-294) */
+    fontVariant?: string;
+    /**
+     * Override fontBoundingBoxAscent (px) when the segment uses a font/size
+     * different from the element (::before / ::after with custom font-size).
+     * Renderer falls back to the element's fontAscent when this is undefined.
+     */
+    fontAscent?: number;
+    /**
+     * Viewport-relative rectangle (CSS pixels) to screenshot when the WHOLE
+     * segment is raster-worthy — used for ::before / ::after pseudos whose
+     * entire text is a color-bitmap run. Populated by CAPTURE_SCRIPT;
+     * captureElementTree fills in rasterDataUri. Renderer emits one <image>
+     * covering rasterRect and skips the text pipeline entirely. See SK-1058.
+     */
+    rasterRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** data:image/png;base64,… populated by Node-side raster. Renderer checks this. */
+    rasterDataUri?: string;
+    /**
+     * Per-character raster overlays for emoji / color-bitmap codepoints mixed
+     * into an otherwise path-rendered text run (SK-1090). Each entry pins the
+     * char's exact viewport-relative rect; rasterizeBitmapGlyphs fills in
+     * dataUri, and the renderer stamps an <image> on top of the path text at
+     * that rect. Path emission for the underlying glyph is left intact — the
+     * <image> overlays wherever needed, and for pure-emoji codepoints the path
+     * pipeline emits nothing anyway (zero-contour glyph from fontkit).
+     */
+    rasterGlyphs?: Array<{
+        charIndex: number;
+        rect: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        dataUri?: string;
+        /** When true, the underlying text-path emit for this charIndex must be
+         *  suppressed: the raster image is the ONLY paint for this codepoint
+         *  (e.g. ::first-letter drop caps where the styled big-letter raster
+         *  would otherwise sit on top of the body-size path glyph). DM-439. */
+        suppressGlyph?: boolean;
+    }>;
+    /**
+     * Pseudo-element box paint (DM-497): when this segment came from a
+     * `::before` / `::after` whose computed style sets a non-trivial
+     * `background-color` or `border-radius`, the renderer emits a `<rect>` of
+     * these dimensions BEHIND the segment's text glyphs to honor the pseudo
+     * box paint (badge / pill / chip pattern). Coordinates are viewport-relative
+     * and already include padding + border insets so the rect surrounds the
+     * captured text segment with the author-specified inflation.
+     */
+    pseudoBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        /** Pre-resolved srgb-form CSS color (or "transparent"). Renderer parses
+         *  via parseColor and emits as the rect fill. */
+        backgroundColor?: string;
+        /** Resolved px border-radius (CSS shorthand — single value, four-corner
+         *  symmetric). */
+        borderRadius?: number;
+        /** Uniform border (single side-width + color). Per-side variation isn't
+         *  supported in this pass; mixed-style borders fall through. */
+        borderWidth?: number;
+        borderColor?: string;
+    };
+}
+export interface CapturedElement {
+    tag: string;
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /**
+     * If the source DOM had `data-domotion-anim="<id>"` on this element, the id
+     * is captured here. The renderer surfaces it as `class="anim-<id>"` on the
+     * rendered group so an intra-frame animation (DM-209) can target it via CSS
+     * keyframes. The animator (or CLI wrapper) is responsible for setting the
+     * data attribute on the live DOM before capture.
+     */
+    animId?: string;
+    styles: {
+        backgroundColor: string;
+        borderColor: string;
+        borderWidth: string;
+        borderRadius: string;
+        /**
+         * Resolved per-corner border-radius (top-left, top-right, bottom-right,
+         * bottom-left). Chrome returns longhand corner values in pixels even when
+         * the author used percentages, so capturing these lets the renderer pick
+         * a circle radius for `border-radius: 50%` instead of treating the "50"
+         * from the shorthand as a 50-px corner. See SK-1093.
+         */
+        borderTopLeftRadius?: string;
+        borderTopRightRadius?: string;
+        borderBottomRightRadius?: string;
+        borderBottomLeftRadius?: string;
+        /** Per-side border widths as strings (e.g. "6px"). All set together so we can decide uniform-vs-split in the renderer. */
+        borderTopWidth: string;
+        borderRightWidth: string;
+        borderBottomWidth: string;
+        borderLeftWidth: string;
+        borderTopStyle: string;
+        borderRightStyle: string;
+        borderBottomStyle: string;
+        borderLeftStyle: string;
+        borderTopColor: string;
+        borderRightColor: string;
+        borderBottomColor: string;
+        borderLeftColor: string;
+        /**
+         * For table cells: `"collapse"` means the parent table sets
+         * `border-collapse: collapse` so adjacent cells share a single painted
+         * border instead of stacking two adjacent ones. The renderer paints
+         * cell borders centered on the cell edge (no half-inset) in this mode
+         * so that two cells'\'' shared edges overlap exactly into one line
+         * instead of doubling.
+         */
+        borderCollapse: string;
+        overflowX: string;
+        overflowY: string;
+        scrollbarGutter: string;
+        /** el.scrollHeight / scrollWidth vs client* — used to decide whether to paint a scrollbar. */
+        scrollWidth: number;
+        scrollHeight: number;
+        clientWidth: number;
+        clientHeight: number;
+        scrollTop: number;
+        scrollLeft: number;
+        objectFit: string;
+        objectPosition: string;
+        filter: string;
+        backdropFilter: string;
+        /**
+         * DM-476 frosted-glass fallback: when the element has a non-trivial
+         * `backdrop-filter` AND a near-transparent `background-color` (alpha
+         * ≤ 0.1), CAPTURE_SCRIPT reads `document.body`'s computed background
+         * colour and stores it here as a normalised `rgb(...)` / `rgba(...)`
+         * string so the renderer can paint a synthesised opaque fill where
+         * Chromium would have painted blurred underlying pixels. Undefined
+         * when the element doesn't trigger the frosted condition. See
+         * `docs/19-frosted-backdrop-fallback.md`.
+         */
+        frostedBgFallback?: string;
+        mixBlendMode: string;
+        clipPath: string;
+        mask: string;
+        maskImage: string;
+        maskMode: string;
+        maskSize: string;
+        maskPosition: string;
+        maskRepeat: string;
+        maskComposite: string;
+        listStyleType: string;
+        listStyleImage: string;
+        listStylePosition: string;
+        /** CSS `display` (e.g. `block`, `list-item`, `flex`). Used by the
+         *  renderer to detect display:list-item on non-li tags. DM-451. */
+        display?: string;
+        backgroundImage: string;
+        backgroundSize: string;
+        backgroundPosition: string;
+        backgroundRepeat: string;
+        backgroundClip: string;
+        backgroundOrigin: string;
+        backgroundAttachment: string;
+        /**
+         * CSS `-webkit-text-fill-color`. When `backgroundClip` is `text` the
+         * common pattern is `webkit-text-fill-color: transparent` so the
+         * background-image (gradient / url) shows through the glyph shapes —
+         * a "gradient headline" effect (Stripe / Resend / Linear hero copy).
+         * Captured separately because `color` may still report a normal value
+         * when the rendered text is actually transparent. DM-462.
+         */
+        webkitTextFillColor?: string;
+        paddingTop: string;
+        paddingRight: string;
+        paddingBottom: string;
+        paddingLeft: string;
+        /** Intrinsic dimensions per background-image layer (same order as splitTopLevelCommas). */
+        backgroundIntrinsic?: Array<{
+            w: number;
+            h: number;
+        } | null>;
+        borderImageSource: string;
+        borderImageSlice: string;
+        borderImageWidth: string;
+        borderImageOutset: string;
+        borderImageRepeat: string;
+        /** Intrinsic pixel dimensions of a border-image url() source, resolved at capture time. */
+        borderImageIntrinsicWidth?: number;
+        borderImageIntrinsicHeight?: number;
+        zIndex: string;
+        position: string;
+        float: string;
+        /** CSS `order` (flex/grid items). Per CSS Flexbox 1 §5.4.1 and CSS Grid 1
+         *  §17, paint order is order-modified document order — items are painted
+         *  in ascending `order` value, ties broken by source (DOM) order. The
+         *  property has no effect on non-flex/non-grid items but Chrome still
+         *  reports it on every computed style, so we capture unconditionally. */
+        order: string;
+        /** CSS `flex-direction` on a flex container (`row` / `row-reverse` /
+         *  `column` / `column-reverse`). Empirically Chrome paints children of a
+         *  `*-reverse` flex container in REVERSE of their order-modified document
+         *  order, so the rightmost (or bottommost) item paints LAST in every
+         *  flex-direction — matching what users expect from a visually-reordered
+         *  layout. Captured on the parent so the child sorter can read it. */
+        flexDirection: string;
+        /** For <td>/<th> with empty-cells: hide — suppress bg + border. */
+        emptyCellsHidden?: boolean;
+        /** Form-control state captured so we can synthesize native chrome. */
+        inputType?: string;
+        /** CSS `appearance` / `-webkit-appearance` longhand. 'none' means the
+         *  author has opted out of UA chrome — the renderer should let the host
+         *  rect (background / border / border-radius) show through and only
+         *  overlay the :checked indicator. DM-285. */
+        inputAppearance?: string;
+        checked?: boolean;
+        indeterminate?: boolean;
+        disabled?: boolean;
+        progressValue?: number;
+        progressMax?: number;
+        /** Custom CSS on ::-webkit-progress-bar (the track) — when set, overrides the default track. */
+        progressBarBg?: string;
+        progressBarBgImage?: string;
+        progressBarRadius?: string;
+        /** Custom CSS on ::-webkit-progress-value (the fill) — when set, overrides the synthesized fill. */
+        progressValueBg?: string;
+        progressValueBgImage?: string;
+        progressValueRadius?: string;
+        meterValue?: number;
+        meterMin?: number;
+        meterMax?: number;
+        meterLow?: number;
+        meterHigh?: number;
+        meterOptimum?: number;
+        /** Custom CSS on ::-webkit-meter-bar / ::-webkit-meter-*-value pseudo-elements. */
+        meterBarBg?: string;
+        meterBarBgImage?: string;
+        meterBarRadius?: string;
+        meterOptimumBg?: string;
+        meterOptimumBgImage?: string;
+        meterSuboptimumBg?: string;
+        meterSuboptimumBgImage?: string;
+        meterEvenLessGoodBg?: string;
+        meterEvenLessGoodBgImage?: string;
+        detailsOpen?: boolean;
+        /** True when the `<summary>`'s `::marker` was hidden by author CSS
+         *  (e.g. `::marker { color: transparent }` or
+         *  `::-webkit-details-marker { color: transparent }`), so the renderer
+         *  should NOT paint its own UA disclosure triangle on top of the
+         *  author's custom marker. DM-448. */
+        summaryMarkerSuppressed?: boolean;
+        selectChevron?: boolean;
+        /** Text of the currently-selected option, rendered inside the `<select>`
+         *  content rect for closed dropdowns (DM-246). For listbox-mode selects
+         *  (`size > 1` or `multiple`) this is undefined and per-option rendering
+         *  flows through the listbox path instead. */
+        selectDisplayText?: string;
+        /** Captured option list for listbox-mode `<select>` (size > 1 or
+         *  multiple). Each entry is one row the renderer paints inside the
+         *  select's content rect. DM-282. */
+        selectListboxOptions?: Array<{
+            text: string;
+            selected: boolean;
+            disabled: boolean;
+            /** Optgroup label row (italic + bold; not user-selectable). */
+            isOptgroupLabel?: boolean;
+            /** Indented child of an optgroup. */
+            isOptgroupChild?: boolean;
+        }>;
+        accentColor?: string;
+        caretColor?: string;
+        /** For <input type=range/color/date/time/...> — the current value. */
+        inputValue?: string;
+        inputMin?: string;
+        inputMax?: string;
+        inputStep?: string;
+        /** True for inputs with the `multiple` attribute (file / email / select). DM-271. */
+        inputMultiple?: boolean;
+        /** For <input type=file> — name of the first selected file, or empty. */
+        inputFileName?: string;
+        /** Custom-styled <input type=range> ::-webkit-slider-runnable-track / ::-webkit-slider-thumb (SK-1131). */
+        rangeTrackBg?: string;
+        rangeTrackHeight?: string;
+        rangeTrackRadius?: string;
+        /** Resolved gradient text for the slider track (SK-1224). Captured when the rule sets background or background-image to a *-gradient(). */
+        rangeTrackBgImage?: string;
+        rangeThumbBg?: string;
+        rangeThumbWidth?: string;
+        rangeThumbHeight?: string;
+        rangeThumbRadius?: string;
+        /** Resolved gradient text for the slider thumb (SK-1224). */
+        rangeThumbBgImage?: string;
+        /** ::-webkit-slider-runnable-track border shorthand (DM-273). */
+        rangeTrackBorder?: string;
+        /** ::-webkit-slider-thumb border shorthand (DM-273). */
+        rangeThumbBorder?: string;
+        /** ::-webkit-slider-thumb box-shadow (DM-319). Used for the donut-ring
+         *  effect: `box-shadow: 0 0 0 Npx <color>` paints an outer ring of width
+         *  N around the thumb. We only render the spread-only form. */
+        rangeThumbBoxShadow?: string;
+        /** ::-webkit-color-swatch pseudo styles (SK-1223). */
+        colorSwatchBg?: string;
+        colorSwatchBgImage?: string;
+        colorSwatchBorder?: string;
+        colorSwatchRadius?: string;
+        colorSwatchWrapperPadding?: string;
+        /** ::-webkit-inner-spin-button pseudo styles (SK-1223; capture only — renderer pickup is a follow-up). */
+        numberSpinButtonBg?: string;
+        numberSpinButtonBorder?: string;
+        numberSpinButtonRadius?: string;
+        /** ::-webkit-search-cancel-button pseudo styles (SK-1223; capture only — renderer pickup is a follow-up). */
+        searchCancelButtonBg?: string;
+        searchCancelButtonBorder?: string;
+        searchCancelButtonRadius?: string;
+        /** For <input type=file> — captured ::file-selector-button pseudo styles. */
+        fileButtonBg?: string;
+        fileButtonColor?: string;
+        fileButtonBorder?: string;
+        fileButtonBorderRadius?: string;
+        fileButtonPadding?: string;
+        fileButtonFontWeight?: string;
+        fileButtonFontSize?: string;
+        fileButtonFontFamily?: string;
+        fileButtonMarginRight?: string;
+        /** Canvas-measureText width of the button label at the captured font (DM-288).
+         *  Lets the renderer position the trailing 'No file chosen' placeholder at
+         *  exactly Chrome's painted x rather than overestimating via a per-char ratio. */
+        fileButtonLabelWidth?: number;
+        /** CSS outline (drawn outside the border-box, doesn't take layout space). */
+        outlineStyle?: string;
+        outlineWidth?: string;
+        outlineColor?: string;
+        outlineOffset?: string;
+        /** CSS box-shadow (raw value: outset/inset, x y blur spread color, comma-separated). */
+        boxShadow?: string;
+        /** CSS text-shadow (raw value: x y blur color, comma-separated; no inset/spread). */
+        textShadow?: string;
+        /** CSS transform (e.g. `rotate(30deg)`, `scale(1.5)`, `matrix(1,0,0,1,0,0)`). 'none' → no transform. */
+        transform?: string;
+        /** CSS will-change (DM-498): a comma-separated hint listing properties the
+         *  author intends to animate. When the list contains a property whose
+         *  non-initial value WOULD create a stacking context (transform, opacity,
+         *  filter, mask, clip-path, perspective, top/right/bottom/left, position,
+         *  z-index, isolation, mix-blend-mode), the element itself becomes a
+         *  stacking-context root regardless of whether that property has a
+         *  non-initial value applied. Used by `establishesStackingContext`. */
+        willChange?: string;
+        /** CSS contain (DM-498): `layout`, `paint`, `strict`, `content`, `size`,
+         *  or combinations. `paint` / `strict` / `content` (which includes paint)
+         *  create a stacking context per spec. */
+        contain?: string;
+        /** CSS isolation (DM-498): `isolate` creates a stacking context. */
+        isolation?: string;
+        /**
+         * DM-552: page-level color-scheme inferred from the capture context.
+         * Sourced from `matchMedia('(prefers-color-scheme: dark)').matches` at
+         * capture time and ONLY populated on the captured tree's root element
+         * (other elements omit it). Renderer reads this to decide whether to
+         * emit `color-scheme="dark"` on the root `<svg>`.
+         */
+        rootColorScheme?: "light" | "dark";
+        /**
+         * DM-552: `getComputedStyle(document.documentElement).backgroundColor`
+         * resolved by Chromium at capture time. Covers the transparent-root
+         * case where the page declares no background and Chromium fills its
+         * UA default per scheme (`#ffffff` for light, `rgb(28, 28, 28)`-ish
+         * for dark). ONLY populated on the captured tree's root element.
+         */
+        rootBgComputed?: string;
+        /** CSS transform-origin resolved to pixel pair (e.g. `60px 30px`). Defaults to '50% 50%' = bbox center. */
+        transformOrigin?: string;
+        /** CSS writing-mode (`horizontal-tb` | `vertical-rl` | `vertical-lr` | `sideways-rl` | `sideways-lr`). */
+        writingMode?: string;
+        /** CSS text-orientation (`mixed` | `upright` | `sideways`). Used in vertical writing-modes. */
+        textOrientation?: string;
+        /** CSS resize. Non-none on textareas paints the bottom-right resize handle. */
+        resize?: string;
+        /** CSS text-overflow ('clip' | 'ellipsis' | "<string>" | …). Renderer paints
+         *  the truncation marker at the visible right edge when overflow is hidden
+         *  and white-space prevents wrapping. (DM-373) */
+        textOverflow?: string;
+        /** Whitespace handling — needed alongside text-overflow to determine if the
+         *  truncation marker should paint. */
+        whiteSpace?: string;
+        color: string;
+        fontSize: string;
+        fontFamily: string;
+        fontWeight: string;
+        /** 'italic' | 'oblique' | 'normal' — drives the SF Pro slnt axis in
+         *  text-to-path so <em>, <i>, [style=font-style:italic] etc. render
+         *  slanted instead of upright. */
+        fontStyle?: string;
+        opacity: string;
+        lineHeight: string;
+        letterSpacing: string;
+        fontKerning: string;
+        fontStretch: string;
+        fontVariationSettings: string;
+        fontFeatureSettings: string;
+        /** CSS font-variant-caps — 'normal' | 'small-caps' | 'all-small-caps' |
+         *  'petite-caps' | 'all-petite-caps' | 'unicase' | 'titling-caps'.
+         *  Renderer applies the matching OpenType feature (smcp / c2sc / etc.).
+         *  DM-361. */
+        fontVariantCaps?: string;
+        /** CSS direction ('ltr' / 'rtl'). Drives BiDi reordering on RTL paragraphs. */
+        direction?: string;
+        /** BCP-47 language tag inherited from `el.lang` / nearest ancestor `[lang]` /
+         *  `<html lang>`. Routes Han fallback to the matching PingFang regional
+         *  variant (TC / HK / MO) or Hiragino Kaku for `ja`. (DM-394) */
+        lang?: string;
+        /** `text-decoration-line` — 'underline', 'line-through', 'overline', or
+         *  combinations. 'none' means no decoration; renderer draws an SVG line
+         *  below / through / above the text when present. */
+        textDecorationLine?: string;
+        /** `text-decoration-color` — color for the decoration line. Falls back to
+         *  the element's text color when undefined. */
+        textDecorationColor?: string;
+        /** `text-decoration-style` — 'solid' / 'dashed' / 'dotted' / 'double' /
+         *  'wavy'. Undefined or 'solid' = plain line. */
+        textDecorationStyle?: string;
+        /** `text-decoration-thickness` — explicit length (e.g. `5px`) or `auto`.
+         *  When set to a length, overrides the auto thickness in
+         *  `getDecorationMetrics`. DM-431. */
+        textDecorationThickness?: string;
+        /** `text-underline-offset` — extra distance below the baseline for the
+         *  underline stroke. Adds to the auto offset. DM-431. */
+        textUnderlineOffset?: string;
+        /** `text-decoration-skip-ink` — 'auto' (default; break around descenders),
+         *  'none' (always solid), or 'all'. Per Chromium's
+         *  `decoration_line_painter.cc`, only solid + double underlines honor
+         *  skip-ink; dashed / dotted / wavy ignore it. DM-446. */
+        textDecorationSkipInk?: string;
+    };
+    children: CapturedElement[];
+    imageSrc?: string;
+    /** Intrinsic pixel dimensions of <img>, used for object-fit: none. */
+    imageIntrinsic?: {
+        w: number;
+        h: number;
+    };
+    /** True when the <img> failed to load (`complete && naturalWidth === 0`).
+     *  Renderer paints the broken-image fallback (icon + alt text). DM-372. */
+    imageBroken?: boolean;
+    /** <img alt> attribute, painted next to the broken-image icon. DM-372. */
+    imageAlt?: string;
+    /** Intrinsic pixel dimensions of list-style-image on <li>. */
+    listMarkerIntrinsic?: {
+        w: number;
+        h: number;
+    };
+    /** 1-based list-item counter value used to format numeric/alpha markers. */
+    listItemIndex?: number;
+    /** Computed ::marker pseudo styles when set on an <li>. CSS lets authors
+     *  recolor / re-weight / resize the marker independent of the list item
+     *  text (e.g. li::marker { color: #ea580c; font-weight: bold }). See
+     *  SK-1115. */
+    markerColor?: string;
+    markerFontWeight?: string;
+    markerFontSize?: string;
+    /** Computed `::marker { content: ... }`. When non-default ("normal" or
+     *  empty), Chrome paints this string in place of the list-style-type
+     *  bullet/number. Captured as the raw computed value (may include
+     *  surrounding quotes). DM-447. */
+    markerContent?: string;
+    /** Computed `::marker { font-family }`. Defaults to inherit, but authors
+     *  can override (e.g. `font-family: monospace` on numeric markers). */
+    markerFontFamily?: string;
+    /** ::before / ::after pseudo-element image content (content: url(...)). */
+    pseudoImages?: Array<{
+        url: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    svgContent?: string;
+    /** Individual text node segments (for mixed content with interleaved child elements) */
+    textSegments?: TextSegment[];
+    /** Bounding box of all text (union of segments) */
+    textTop?: number;
+    textLeft?: number;
+    textHeight?: number;
+    textWidth?: number;
+    /**
+     * Chrome's `canvas.measureText().fontBoundingBoxAscent` for the element's
+     * computed font (px, integer-rounded). This is the exact distance Chrome
+     * paints from line-box top to baseline — reading it from the browser
+     * sidesteps the fontkit-vs-Chrome metric divergence (Helvetica/Arial/Times
+     * etc on macOS use winAscent, not hhea, while SF Pro has equal metrics; the
+     * "right metric per font" is fragile to derive but trivial to measure).
+     */
+    fontAscent?: number;
+    fontDescent?: number;
+    /**
+     * Per-char x positions for input/textarea value text (SK-1234), measured
+     * via a hidden DOM probe with the same font/value. Lets the renderer
+     * anchor each glyph at the position Chromium would paint instead of
+     * trusting fontkit's native advances (which can drift up to ~0.5px per
+     * char vs HarfBuzz). One entry per UTF-16 code unit; viewport-relative.
+     */
+    inputXOffsets?: number[];
+    /** Rasterized text as PNG data URI (rendered via canvas for cross-browser consistency) */
+    textImageUri?: string;
+    /** Scale factor used for text rasterization (e.g. 2 for retina) */
+    textImageScale?: number;
+    /**
+     * True when `text` came from an input/textarea `placeholder=…` attribute
+     * (value was empty). Renderer paints the text in placeholderColor instead
+     * of the normal text color. See SK-1097 / SK-1100.
+     */
+    isPlaceholderText?: boolean;
+    /** Computed ::placeholder color (normalized). Set when isPlaceholderText. */
+    placeholderColor?: string;
+    /** Computed ::placeholder font-style (e.g. italic). Set when isPlaceholderText. */
+    placeholderFontStyle?: string;
+    /** Computed ::placeholder font-weight. Set when isPlaceholderText. */
+    placeholderFontWeight?: string;
+    /**
+     * Viewport-relative rect of the element's internal content area (minus
+     * borders + padding) that rasterizeBitmapGlyphs should screenshot and
+     * stash on dataUri for the renderer to stamp in place of path text. Used
+     * for <textarea> whose soft-wrap text layout is too involved to replicate
+     * in the path pipeline (see SK-1108) — rely on Chrome's own render of the
+     * content region. Detection happens in CAPTURE_SCRIPT.
+     */
+    elementRaster?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        dataUri?: string;
+    };
+    /**
+     * For <canvas> / <video> / <iframe> / <object> / <embed>: a viewport-relative
+     * content-box rect (border-box minus border + padding) that
+     * rasterizeReplacedElements should screenshot via Playwright and stash on
+     * dataUri. The renderer then emits an <image> at the same rect to cover what
+     * Chrome actually painted in that element's content area, so these element
+     * types stop leaving blank holes in real-world captures. The capture warning
+     * is still emitted because these types are out of the spirit of the path-
+     * based rendering contract — the snapshot is a frozen raster, not a faithful
+     * re-render. See docs/17-replaced-element-snapshots.md (DM-457).
+     */
+    replacedSnapshot?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        rid: string;
+        dataUri?: string;
+    };
+    /**
+     * Image-replacement icon (DM-506): a CSS-sprite icon whose accessible label
+     * is hidden via `text-indent: -9999px; overflow: hidden` (or the modern
+     * `text-indent: <neg>; overflow: hidden; white-space: nowrap` variant). The
+     * element's painted box is rasterised through the `replacedSnapshot` path so
+     * the sprite slice is captured as Chrome painted it; capture also clears
+     * `text` / `textSegments` / `styles.backgroundImage` so the renderer doesn't
+     * double-paint the sliced sprite or leak the off-screen text into the SVG.
+     * `titleText` is the suppressed author text — emitted as an SVG `<title>`
+     * child of the rasterised `<image>` so screen readers and tooltips still
+     * surface the label. See `docs/23-css-sprite-icons.md`.
+     */
+    imageReplacement?: {
+        titleText: string;
+    };
+    /**
+     * <fieldset> with a top-aligned <legend>: Chrome's UA paints the fieldset's
+     * top border at the legend's vertical center (not at fs.y) and notches the
+     * border across the legend's horizontal extent. The captured x/y/width/
+     * height already encode the inset (y shifted down by legend.height/2,
+     * height reduced to match), and this field carries the legend's full
+     * absolute bbox so the renderer can clip the top border behind it via an
+     * even-odd clipPath. DM-342 / DM-343.
+     */
+    fieldsetLegendNotch?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /**
+     * Top-level (root only) collection of `<mask>` definitions referenced by
+     * fragment URLs (`mask-image: url("#id")`) anywhere in the captured tree.
+     * CAPTURE_SCRIPT resolves each fragment id to the corresponding inline
+     * `<mask>` element via `document.getElementById` and serialises its
+     * `outerHTML` here. The renderer copies these into the output `<defs>`
+     * with id rewriting so a captured `<mask id="m1">` becomes a
+     * domotion-prefixed mask def referenced by elements that point at `#m1`.
+     * Same-document only — external `.svg#fragment` refs are deferred (DM-496).
+     * See `docs/21-mask-fragment-references.md`.
+     */
+    maskDefs?: MaskFragmentDef[];
+    /**
+     * DM-494: Raster snapshots of elements referenced by `mask-image:
+     * element(#id)`. Top-level (root only) — same-document only (cross-document
+     * `element()` is not in scope; CSS spec doesn't define it). Each raster is
+     * the actual painted output of the referenced element captured via
+     * `page.screenshot({ clip: rect, omitBackground: true })` after a hide-
+     * everything-else stylesheet, encoded as `data:image/png;base64,…`.
+     * Renderer's `buildMaskDef` looks up the entry by `id` and emits an
+     * `<image>` inside the `<mask>` with `mask-type="luminance"` per Chrome's
+     * `mask-mode: match-source` default for element() references. See
+     * `docs/22-mask-element-paint-references.md`.
+     */
+    maskRasters?: MaskRasterRef[];
+}
+export interface MaskFragmentDef {
+    /** Original DOM id of the captured `<mask>` element. */
+    id: string;
+    /** Verbatim `outerHTML` of the captured `<mask>` element. */
+    outerHTML: string;
+}
+export interface MaskRasterRef {
+    /** DOM id referenced by `mask-image: element(#id)` — used by the renderer
+     *  to look up the raster from the layer reference. */
+    id: string;
+    /** `data:image/png;base64,…` of the referenced element's painted box.
+     *  Populated by `rasterizeMaskSources`; may be undefined if the screenshot
+     *  failed (e.g. clip went off-page) — renderer falls back to no mask
+     *  emission and warns. */
+    dataUri?: string;
+    /** Captured element rect (viewport-relative px). Used by the post-capture
+     *  pass to drive page.screenshot's clip. Renderer doesn't consume this
+     *  directly; the `<image>` placement comes from the consuming element's
+     *  mask-position / mask-size. */
+    width: number;
+    height: number;
+    /** `data-domotion-rid` value attached to the live DOM target so the
+     *  hide-everything-else stylesheet has a unique selector. */
+    rid: string;
+    /** Viewport-relative rect of the referenced element, used by the post-
+     *  capture pass. */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface CaptureWarning {
+    /** Short selector path identifying the element that tripped the warning. */
+    selector: string;
+    /** Feature name (e.g. 'transform', 'backdrop-filter', '<iframe>'). */
+    feature: string;
+    /** Short detail about what's not supported and/or a tracking ticket. */
+    detail: string;
+}
+export declare function getLastCaptureWarnings(): CaptureWarning[];
+/**
+ * Print the last capture's warnings to stderr in a compact format. Useful in
+ * CLI / test scripts that want a one-line-per-warning summary.
+ */
+export declare function logCaptureWarnings(label?: string): void;
+/**
+ * Capture the visual tree of elements within a viewport region. Warnings about
+ * unsupported features encountered during capture are stored and accessible
+ * via getLastCaptureWarnings() / logCaptureWarnings().
+ */
+export declare function captureElementTree(page: Page, selector: string | undefined, viewport: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): Promise<CapturedElement[]>;
+/**
+ * Same capture as `captureElementTree` but returns the warnings inline so
+ * callers running multiple captures concurrently don't race on the
+ * `lastCaptureWarnings` module global. The global is still updated so
+ * single-capture callers using `getLastCaptureWarnings()` keep working.
+ */
+export declare function captureElementTreeWithWarnings(page: Page, selector: string | undefined, viewport: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, opts?: {
+    /** DM-562: when provided, `rasterizeReplacedElements` crops replaced-
+     *  element rects from this PNG instead of taking fresh page.screenshot
+     *  calls. Eliminates timing drift between the expected screenshot and
+     *  rotating cross-origin-iframe content. Caller is responsible for
+     *  ensuring the source covers the same coordinate space as `viewport`. */
+    rasterizeFromImagePath?: string;
+}): Promise<{
+    tree: CapturedElement[];
+    warnings: CaptureWarning[];
+}>;
+/**
+ * Calibrate `fontAscent` on text-bearing elements by scanning a reference
+ * PNG (Chrome's actual paint) for each element's painted ink top, then
+ * back-solving the sub-pixel baseline as
+ * `inkTop - textTop + actualBoundingBoxAscent(text)` where the cap-height
+ * comes from `canvas.measureText(text).actualBoundingBoxAscent` (sub-pixel
+ * accurate, unlike `fontBoundingBoxAscent` which Chrome integer-rounds).
+ *
+ * Closes the residual ±0.6 px text-baseline drift documented in DM-397 /
+ * DM-418. Empirical extraction at capture time — uses Chrome's actual
+ * painted output as ground truth instead of trying to mirror Chromium's
+ * per-platform LayoutNG strut math.
+ *
+ * Caller must provide PNG bytes from a Chrome screenshot of the same
+ * viewport that was captured. For the test pipeline this is the same
+ * `expected.png` we already write to disk for diffing.
+ */
+export declare function calibrateBaselines(page: Page, elements: CapturedElement[], pngBytes: Buffer | Uint8Array): Promise<void>;
+/**
+ * Wrap inner SVG markup (as returned by `elementTreeToSvg`) in a complete
+ * `<svg>` document with the standard namespace, viewBox, and intrinsic size.
+ * This is the boilerplate every standalone-capture user would otherwise write
+ * themselves — call this when you want a self-contained SVG file.
+ */
+export declare function wrapSvg(inner: string, width: number, height: number, opts?: {
+    tree?: CapturedElement[];
+}): string;
+/**
+ * DM-552: returns ` color-scheme="dark"` (with leading space, suitable for
+ * direct concatenation into an `<svg ...>` opening tag) when the captured
+ * tree's root reports `rootColorScheme === "dark"`. Returns an empty string
+ * for the light / no-scheme case so today's SVG output is byte-identical at
+ * the default. Use from any code path that emits a root `<svg>` outside of
+ * `wrapSvg` (e.g., `tests/runner.tsx` and `tests/real-world.tsx` build their
+ * own opening tags so they can inject a body-bg `<rect>` underneath the
+ * captured content).
+ */
+export declare function rootSvgColorSchemeAttr(elements: CapturedElement[]): string;
+/**
+ * DM-554: returns a body-bg `<rect>` markup string for the canvas when the
+ * captured tree's root provides a `rootBgComputed` (set by CAPTURE_SCRIPT
+ * from `getComputedStyle(document.documentElement).backgroundColor`).
+ * Returns an empty string when the field is missing (pre-DM-552 captures)
+ * or the resolved bg is transparent (pages that intend a transparent SVG).
+ *
+ * Used by `wrapSvg` and exported so external consumers that build their
+ * own `<svg>` opening tag (because they need to inject a body-bg rect at a
+ * specific position relative to other root-level rects, e.g. a frame
+ * overlay) can produce the same markup without re-implementing the
+ * fallback chain.
+ */
+export declare function transparentRootBgRect(elements: CapturedElement[], width: number, height: number): string;
+/**
+ * Convert a CapturedElement tree into SVG markup.
+ */
+export declare function elementTreeToSvg(elements: CapturedElement[], width: number, height: number, 
+/** Prefix for clipPath IDs — required when combining multiple frames in one SVG to avoid ID collisions */
+idPrefix?: string, 
+/**
+ * When true (default), include the shared glyph definitions in this frame's
+ * <defs>. Multi-frame animated SVGs should pass false so glyph defs can be
+ * hoisted to the top-level SVG <defs> and shared across frames.
+ */
+includeGlyphDefs?: boolean, 
+/**
+ * DM-540: hiDPI multiplier the renderer uses when looking up resized
+ * variants in `_resizedDataUriCache`. Must match the value passed to
+ * `resizeEmbeddedImages` for the same tree, or the lookup misses and
+ * the renderer falls back to the source-resolution data URI. Default 2.
+ */
+hiDPIFactor?: number): string;
+export interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export declare function parseColor(css: string): RGBA | null;
+/** Per-corner border-radius axis-pair (h = horizontal, v = vertical).
+ *  An elliptical corner has h ≠ v; a circular corner has h = v. */
+export type CornerRadiusPair = {
+    h: number;
+    v: number;
+};
+/** Resolved per-corner border-radius for the four corners of a rect, with
+ *  CSS-spec corner-overlap scaling already applied. `uniform` is true when
+ *  all four corners are circular AND share the same radius, which lets the
+ *  renderer emit a single `<rect rx>` instead of a per-corner `<path>`. */
+export type CornerRadii = {
+    tl: CornerRadiusPair;
+    tr: CornerRadiusPair;
+    br: CornerRadiusPair;
+    bl: CornerRadiusPair;
+    uniform: boolean;
+};
+/** Resolve the four per-corner radii for a captured element, applying CSS's
+ *  corner-overlap scale-down (https://www.w3.org/TR/css-backgrounds-3/#corner-overlap):
+ *  if any edge's two corner radii would together exceed the edge length, all
+ *  four corners are scaled down uniformly. This is what produces the pill
+ *  shape for `border-radius:999px` on a short element — without the spec
+ *  clamp, two adjacent 999-px corners would overlap visibly. Falls back to
+ *  the legacy single `borderRadius` shorthand when the per-corner longhands
+ *  weren't captured (older snapshots). */
+export declare function parseCornerRadii(styles: {
+    borderTopLeftRadius?: string;
+    borderTopRightRadius?: string;
+    borderBottomRightRadius?: string;
+    borderBottomLeftRadius?: string;
+    borderRadius?: string;
+}, width: number, height: number): CornerRadii;
+/** Inset each corner radius by the matching border-side widths, clamping to 0.
+ *  Use this to derive the inner radii used by background clips (where the
+ *  border has eaten into the corner) and inner border strokes. CSS specifies
+ *  that the inner corner is the outer corner pulled in by the adjacent border
+ *  widths (top + left for TL, top + right for TR, etc.). */
+export declare function insetCornerRadii(c: CornerRadii, top: number, right: number, bottom: number, left: number): CornerRadii;
+/** Emit an SVG path `d` attribute for a rounded rectangle with per-corner radii.
+ *  Path goes clockwise from the top-left, using elliptical arc commands at each
+ *  corner. Zero-radius corners collapse to a sharp 90° join. */
+export declare function roundedRectPath(x: number, y: number, w: number, h: number, c: CornerRadii): string;
+/** Emit a rounded-rect SVG element. Uses `<rect rx>` when the corners are
+ *  uniform (cheaper, less markup); falls back to `<path>` for asymmetric or
+ *  elliptical corners. The `attrs` string is injected verbatim — pass in
+ *  fill/stroke/etc. */
+export declare function roundedRectSvg(x: number, y: number, w: number, h: number, c: CornerRadii, attrs: string): string;
+/**
+ * Rewrite a captured `<mask>` element's `outerHTML` so it can be safely
+ * inlined in the output SVG's `<defs>`. The mask's own `id` becomes
+ * `outputId`, and every other DOM id referenced inside the subtree gets
+ * prefixed with `idPrefix` so it can't collide with ids elsewhere in the
+ * output (multi-frame animated SVGs reuse the same prefix model). Every
+ * `url(#X)` reference inside the subtree is updated to point at the
+ * rewritten id. DM-493.
+ */
+export declare function rewriteFragmentMaskDef(outerHTML: string, outputId: string, idPrefix: string): string;
+/**
+ * Reposition a (previously rewritten) `<mask>` outerHTML so its content lives
+ * in the masked element's absolute user-space. CSS `mask-image: url("#id")`
+ * positions the mask source at the masked element's content-box origin, but
+ * SVG `<mask>` with `maskUnits="userSpaceOnUse"` interprets its content
+ * absolutely against the root SVG — so the captured mask coords (which are
+ * relative to the original `<mask>` element) need shifting by `(elX, elY)`.
+ * We do this by:
+ *   1. Forcing `maskUnits="userSpaceOnUse"` on the outer `<mask>`.
+ *   2. Replacing the mask's `x/y/width/height` with the masked element's
+ *      absolute box (so the mask region matches the element).
+ *   3. Wrapping the mask's children in `<g transform="translate(elX, elY)">`.
+ * DM-493.
+ */
+export declare function positionFragmentMaskDef(rewrittenOuterHTML: string, elX: number, elY: number, elW: number, elH: number): string;
+/**
+ * Translate a CSS mask-image value + mask-* siblings into an SVG <mask>.
+ * Handles single-layer gradients and url() sources. Position/size/repeat are
+ * applied via an internal <pattern> for url sources; gradients use direct
+ * gradient fills sized to the element box.
+ *
+ * SVG <mask> uses luminance by default (bright pixels visible). CSS mask-mode
+ * 'alpha' makes the alpha channel control visibility. We set mask-type on the
+ * <mask> element accordingly. Note: Chromium may render mask-mode:'match-source'
+ * differently depending on the source; we pick alpha for gradients and url()
+ * (common case) and respect explicit mask-mode when given.
+ */
+export declare function buildMaskDef(id: string, maskImage: string, elX: number, elY: number, w: number, h: number, maskMode: string, sizeCss: string, posCss: string, repeatCss: string, compositeCss: string, 
+/** DM-494: lookup table for `mask-image: element(#id)` references. Optional —
+ *  callers without element() refs can omit it. The renderer's main caller
+ *  threads through `elementMaskRasters` (collected from tree[0].maskRasters);
+ *  unit tests can pass undefined to exercise the non-element() branches. */
+elementRasters?: ReadonlyMap<string, MaskRasterRef>): {
+    id: string;
+    def: string;
+};
+/**
+ * Translate CSS object-fit + object-position to an SVG preserveAspectRatio
+ * attribute. Best-effort — SVG does not cover every CSS combination exactly.
+ *
+ * Mapping:
+ *   fill         -> 'none' (stretch both axes, may distort)
+ *   contain      -> '<align> meet' (fit inside, letterbox)
+ *   cover        -> '<align> slice' (fill, crop)
+ *   none         -> not representable without intrinsic size info; 'none' stretch is the least-bad default
+ *   scale-down   -> treated as 'contain' (common case; exact rule requires intrinsic size)
+ *
+ * object-position keywords (top/right/bottom/left/center) and '0% 0%' / '100% 100%'
+ * map to xMin/xMid/xMax + yMin/yMid/yMax. Percentages are bucketed to thirds
+ * since SVG has no finer-grained alignment.
+ */
+export declare function preserveAspectRatioFor(fit: string | undefined, pos: string | undefined): string;