domotion-svg 0.1.1 → 0.2.2

package/README.md

@@ -16,6 +16,14 @@ Domotion captures real HTML/CSS as it renders in Chromium, then emits a single i
 
 Early — extracted in 2026-04 from the slicekit project where it had been incubating as `tools/svg-demo-gen`. APIs may still shift while the project's external surface stabilizes.
 
+## Platform support
+
+Domotion ships as a normal npm package and is **designed** to work on macOS, Linux, and Windows — the captured SVG is meant to be pixel-faithful to Chromium on whichever platform the capture is running on (CoreText fallback on macOS, fontconfig on Linux, DirectWrite on Windows).
+
+**Today it's only actively tested and calibrated on macOS.** Linux and Windows are roadmap items: cross-platform system-font path discovery, per-platform fallback-font chains calibrated against the host Chromium, optional bundled fallback fonts when no local match resolves, and CI coverage on both platforms. The package will install and run on Linux/Windows, but text rendering won't yet match the host Chromium as faithfully as it does on macOS.
+
+If you'd like to help with cross-platform support — testing on Linux or Windows, reporting issues you hit, or sending fixes — please open an issue or PR on [GitHub](https://github.com/brianwestphal/domotion). Bug reports against macOS are also welcome.
+
 ## Install
 
 ```bash

package/dist/{animator.d.ts → animation/animator.d.ts}

@@ -8,6 +8,18 @@ import { type CursorOverlay, type SelectorResolver } from "./cursor-overlay.js";
 export interface AnimationFrame {
     /** SVG content for this frame (from dom-to-svg) */
     svgContent: string;
+    /**
+     * Per-element viewBox-cull keyframes CSS (DM-603). The caller runs
+     * `cullElementsOutsideViewBox()` on the captured tree before `elementTreeToSvg()` — that
+     * mutates `displayNone` / `cullClass` on each element (which the renderer
+     * surfaces) and returns the keyframes blocks that map each `cull-N` class
+     * to its visible window. The animator splices this CSS into the scene-wide
+     * `<style>` block.
+     *
+     * When omitted, no culling happens — callers passing pre-rendered
+     * `svgContent` strings without the cull CSS get unchanged behavior.
+     */
+    cullCss?: string;
     /** Duration this frame is shown (ms) */
     duration: number;
     /** Transition to next frame */
@@ -22,7 +34,7 @@ export interface AnimationFrame {
         duration: number;
     };
     /** Overlays: typing, tap ripple */
-    overlays?: Overlay[];
+    overlays?: AnimationOverlay[];
     /**
      * Intra-frame property animations. Run during this frame's hold time.
      * The CLI / `DemoRecorder` resolves selectors against the DOM at capture
@@ -99,7 +111,7 @@ export interface SvgOverlay {
         delay?: number;
     };
 }
-export type Overlay = TypingOverlay | TapOverlay | SvgOverlay;
+export type AnimationOverlay = TypingOverlay | TapOverlay | SvgOverlay;
 /**
  * Animate a CSS property on captured elements that match a selector, while
  * the frame is held on screen. The selector is resolved against the source

package/dist/{animator.js → animation/animator.js}

@@ -4,7 +4,7 @@
  * Takes captured SVG frame content and composes them into a single
  * animated SVG with CSS keyframe transitions.
  */
-import { mergeFrames } from "./frame-merge.js";
+import { mergeFrames } from "../tree-ops/frame-merge.js";
 import { cursorOverlayMarkup, resolveCursorScript } from "./cursor-overlay.js";
 export function generateAnimatedSvg(config) {
     const { width, height, frames } = config;
@@ -50,13 +50,27 @@ export function generateAnimatedSvg(config) {
         const transEndPct = pct(timeOffset + frame.duration + transDur, totalDuration);
         const prevFrame = i > 0 ? frames[i - 1] : null;
         const entersViaPush = prevFrame?.transition?.type === "push-left";
+        const entersViaScroll = prevFrame?.transition?.type === "scroll";
+        // Both push-left and scroll overlap their transition with the next
+        // frame's entry — the next frame is already sliding in while the current
+        // one slides out, so its show window starts at `timeOffset - prevTransDur`
+        // rather than at `startPct`.
+        const entersViaOverlap = entersViaPush || entersViaScroll;
         const prevTransDur = prevFrame != null ? transitionDuration(prevFrame) : 300;
-        const enterStartPct = entersViaPush
+        const enterStartPct = entersViaOverlap
             ? pct(timeOffset - prevTransDur, totalDuration)
             : startPct;
         if (transType === "push-left") {
             // Push: slide in from right, slide out to left
             frameGroups.push(`  <g class="f f-${i}"><clipPath id="fc-${i}"><rect width="${width}" height="${height}" /></clipPath><g clip-path="url(#fc-${i})" class="fp fp-${i}">\n${frame.svgContent}\n  </g></g>`);
+            // DM-599: parallel `fd-${i}` animation snaps `display` between none /
+            // inline at the visibility boundary so the browser can skip painting
+            // this frame's content while it's fully off-screen between cycles.
+            // Window is [enterStartPct .. transEndPct] (when the slide has fully
+            // exited the viewBox); 0.01% pad on each side keeps the snap inside the
+            // existing opacity:0 bookend.
+            const visStart = enterStartPct;
+            const visEnd = transEndPct;
             keyframes.push(`
     @keyframes fp-${i} {
       0%, ${Math.max(0, parseFloat(enterStartPct) - 0.1).toFixed(2)}% { transform: translateX(${entersViaPush ? width : 0}px); }
@@ -70,21 +84,38 @@ export function generateAnimatedSvg(config) {
       ${enterStartPct}% { opacity: 1; }
       ${transEndPct}% { opacity: 1; }
       ${Math.min(100, parseFloat(transEndPct) + 0.1).toFixed(2)}%, 100% { opacity: 0; }
-    }
-    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; }
+    }${buildDisplayKeyframes(`fd-${i}`, visStart, visEnd)}
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }
     .fp-${i} { animation: fp-${i} ${totalSec.toFixed(2)}s infinite; }`);
         }
         else if (transType === "scroll") {
-            // Scroll: keep visible, no fade during scroll, fade only at end
-            frameGroups.push(`  <g class="f f-${i}">\n${frame.svgContent}\n  </g>`);
-            const fadeEndPct = pct(timeOffset + frame.duration + transDur + 200, totalDuration);
-            const prevEnd = i > 0 ? `${Math.max(0, parseFloat(startPct) - 0.1).toFixed(2)}%,` : "";
+            // DM-609: `scroll` now means real geometric scroll between two frames
+            // (was opacity-only — see DM-604 §10a "replace with new geometric
+            // semantics"). Vertical equivalent of `push-left`: incoming frame
+            // slides up from the bottom of the viewport, outgoing slides up off
+            // the top. Uses height instead of width and translateY instead of
+            // translateX, otherwise identical machinery (incl. the cull-friendly
+            // `fd-${i}` display animation).
+            const entersViaScroll = prevFrame?.transition?.type === "scroll";
+            frameGroups.push(`  <g class="f f-${i}"><clipPath id="fc-${i}"><rect width="${width}" height="${height}" /></clipPath><g clip-path="url(#fc-${i})" class="fp fp-${i}">\n${frame.svgContent}\n  </g></g>`);
+            const visStart = enterStartPct;
+            const visEnd = transEndPct;
             keyframes.push(`
-    @keyframes fv-${i} {
-      0%, ${prevEnd} ${fadeEndPct}, 100% { opacity: 0; }
-      ${startPct}, ${transEndPct} { opacity: 1; }
+    @keyframes fp-${i} {
+      0%, ${Math.max(0, parseFloat(enterStartPct) - 0.1).toFixed(2)}% { transform: translateY(${entersViaScroll ? height : 0}px); }
+      ${startPct}% { transform: translateY(0); }
+      ${holdEndPct}% { transform: translateY(0); }
+      ${transEndPct}% { transform: translateY(-${height}px); }
+      ${Math.min(100, parseFloat(transEndPct) + 0.1).toFixed(2)}%, 100% { transform: translateY(-${height}px); }
     }
-    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; }`);
+    @keyframes fv-${i} {
+      0%, ${Math.max(0, parseFloat(enterStartPct) - 0.1).toFixed(2)}% { opacity: 0; }
+      ${enterStartPct}% { opacity: 1; }
+      ${transEndPct}% { opacity: 1; }
+      ${Math.min(100, parseFloat(transEndPct) + 0.1).toFixed(2)}%, 100% { opacity: 0; }
+    }${buildDisplayKeyframes(`fd-${i}`, visStart, visEnd)}
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }
+    .fp-${i} { animation: fp-${i} ${totalSec.toFixed(2)}s infinite; }`);
         }
         else {
             // Crossfade or cut: opacity in/out.
@@ -105,14 +136,16 @@ export function generateAnimatedSvg(config) {
                 const endNum = parseFloat(transEndPct);
                 const beforeStart = Math.max(0, startNum - 0.001).toFixed(3);
                 const afterEnd = Math.min(100, endNum + 0.001).toFixed(3);
+                // DM-599: cut already uses step-end on the opacity animation, so we
+                // fold display into the same keyframes block — both snap together.
                 keyframes.push(`
     @keyframes fv-${i} {
-      0% { opacity: 0; }
-      ${beforeStart}% { opacity: 0; }
-      ${startNum.toFixed(3)}% { opacity: 1; }
-      ${endNum.toFixed(3)}% { opacity: 1; }
-      ${afterEnd}% { opacity: 0; }
-      100% { opacity: 0; }
+      0% { opacity: 0; display: none; }
+      ${beforeStart}% { opacity: 0; display: none; }
+      ${startNum.toFixed(3)}% { opacity: 1; display: inline; }
+      ${endNum.toFixed(3)}% { opacity: 1; display: inline; }
+      ${afterEnd}% { opacity: 0; display: none; }
+      100% { opacity: 0; display: none; }
     }
     .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; animation-timing-function: step-end; }`);
             }
@@ -123,12 +156,14 @@ export function generateAnimatedSvg(config) {
                 const prevEnd = i > 0
                     ? `${Math.max(0, parseFloat(fadeInStartPct) - 0.01).toFixed(2)}%,`
                     : "";
+                // DM-599: visible window spans the full fade — fadeInStart through
+                // transEnd (display stays `inline` while opacity interpolates).
                 keyframes.push(`
     @keyframes fv-${i} {
       0%, ${prevEnd} ${transEndPct}, 100% { opacity: 0; }
       ${startPct}, ${holdEndPct} { opacity: 1; }
-    }
-    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; }`);
+    }${buildDisplayKeyframes(`fd-${i}`, fadeInStartPct, transEndPct)}
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }`);
             }
         }
         // Overlays
@@ -156,6 +191,11 @@ export function generateAnimatedSvg(config) {
     // Compose final SVG with XML declaration for proper UTF-8
     const sharedDefsMarkup = config.sharedDefs ?? "";
     const animationCss = buildIntraFrameAnimationCss(frames, frameTiming, totalSec);
+    // DM-603: per-frame viewBox-cull keyframes — each frame's caller pre-ran
+    // `cullElementsOutsideViewBox()` and we splice the resulting blocks into the scene-wide
+    // <style>. The keyframes reference `var(--scene-dur)`; we expose that
+    // variable on the root selector below.
+    const cullCss = frames.map((f) => f.cullCss ?? "").filter((s) => s !== "").join("\n");
     // Cursor overlay (DM-277). The frame start times let the resolver pick
     // which frame's selector matches apply at each event's timestamp.
     let overlayMarkup = "";
@@ -175,8 +215,9 @@ export function generateAnimatedSvg(config) {
     <clipPath id="viewport-clip"><rect width="${width}" height="${height}" /></clipPath>${sharedDefsMarkup}
   </defs>
   <style>
-    .f { opacity: 0; }
-    ${keyframes.join("\n")}${animationCss}
+    :root { --scene-dur: ${totalSec.toFixed(2)}s; }
+    .f { opacity: 0; display: none; }
+    ${keyframes.join("\n")}${animationCss}${cullCss === "" ? "" : "\n" + cullCss}
   </style>
   <g clip-path="url(#viewport-clip)">
   <rect width="${width}" height="${height}" fill="#0d1117" />
@@ -261,6 +302,32 @@ function renderTapOverlay(overlay, frameIdx, frameStart, totalDuration, totalSec
 function pct(ms, total) {
     return `${((ms / total) * 100).toFixed(2)}%`;
 }
+/**
+ * DM-599: build a step-end keyframes block that toggles `display` between
+ * `none` and `inline` around a visible window. Used in parallel with the
+ * opacity-controlling `fv-*` animation so the browser can skip painting the
+ * frame entirely while it's outside its show window (the dominant cost on
+ * long multi-frame demos with complex captured content).
+ *
+ * `visibleStartPct` / `visibleEndPct` accept either a numeric-style string
+ * (`"12.34"`) or one with a trailing `%` (`"12.34%"`) — `pct()` returns the
+ * latter and the unmerged-path keyframes feed either form.
+ */
+function buildDisplayKeyframes(name, visibleStartPct, visibleEndPct) {
+    const start = parseFloat(String(visibleStartPct));
+    const end = parseFloat(String(visibleEndPct));
+    const startMinus = Math.max(0, start - 0.01).toFixed(3);
+    const endPlus = Math.min(100, end + 0.01).toFixed(3);
+    return `
+    @keyframes ${name} {
+      0% { display: none; }
+      ${startMinus}% { display: none; }
+      ${start.toFixed(3)}% { display: inline; }
+      ${end.toFixed(3)}% { display: inline; }
+      ${endPlus}% { display: none; }
+      100% { display: none; }
+    }`;
+}
 /**
  * Render a frame-local SVG overlay. The embedded SVG markup is wrapped in a
  * `<g transform="translate(x y)" clip-path="..."/>` and an inner
@@ -344,6 +411,8 @@ function composeMergedSvg(config, frameTiming, totalSec) {
     const { css, merged } = mergeFrames(framesSvg, frameTiming, "t");
     const sharedDefsMarkup = config.sharedDefs ?? "";
     const animationCss = buildIntraFrameAnimationCss(frames, frameTiming, totalSec);
+    // DM-603: viewBox-cull keyframes from each frame's pre-pass (see unmerged path).
+    const cullCss = frames.map((f) => f.cullCss ?? "").filter((s) => s !== "").join("\n");
     // Cursor overlay (DM-277). Same emission as the unmerged path — the
     // overlay sits above the merged frame group, clipped to the viewport.
     const totalDuration = totalSec * 1000;
@@ -365,7 +434,7 @@ function composeMergedSvg(config, frameTiming, totalSec) {
   </defs>
   <style>
     :root { --scene-dur: ${totalSec.toFixed(2)}s; }
-${css}${animationCss}
+${css}${animationCss}${cullCss === "" ? "" : "\n" + cullCss}
   </style>
   <g clip-path="url(#viewport-clip)">
   <rect width="${width}" height="${height}" fill="#0d1117" />

package/dist/{animator.test.js → animation/animator.test.js}

@@ -50,6 +50,26 @@ describe("animator", () => {
         });
         expect((svg.match(/<rect width="50" height="50" fill="green"\/>/g) ?? []).length).toBe(1);
     });
+    it("DM-609: scroll transition is now a vertical push (translateY), not opacity-only", () => {
+        // The `scroll` transition used to be opacity-only (a misnomer). Per
+        // DM-604 §10a, it's been replaced with real geometric semantics: the
+        // outgoing frame slides up off the top while the next slides up from
+        // the bottom. We verify by checking for translateY in the emitted CSS.
+        const svg = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                { svgContent: `<rect/>`, duration: 1000, transition: { type: "scroll", duration: 200 } },
+                { svgContent: `<rect/>`, duration: 1000 },
+            ],
+        });
+        expect(svg).toContain("translateY");
+        // The clipPath wrapper is added too (frames are clipped to viewport
+        // during the slide so they don't show outside their region).
+        expect(svg).toMatch(/<clipPath id="fc-\d+">/);
+        // The fp-N keyframes (transform animation) get emitted alongside fv-N
+        // (opacity) and fd-N (display) — mirrors the push-left structure.
+        expect(svg).toMatch(/@keyframes fp-0/);
+    });
     it("non-crossfade transitions are unaffected", () => {
         const svg = generateAnimatedSvg({
             width: 100,
@@ -152,6 +172,74 @@ describe("animator", () => {
         expect(svg).toContain("transform: translateY(240px)");
         expect(svg).toContain("transform: translateY(0px)");
     });
+    it("DM-599: push-left frame gets a paired fd-N display animation alongside fv-N", () => {
+        // push-left is unmergeable (the merge fast path only takes crossfade/cut),
+        // so it goes through the unmerged emit path that emits per-frame fv-/fp-
+        // blocks. The DM-599 optimization adds an fd-N keyframes block that
+        // toggles `display: none ↔ inline` so the frame is dropped from paint
+        // outside its show window.
+        const svg = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                { svgContent: `<rect/>`, duration: 1000, transition: { type: "push-left", duration: 200 } },
+                { svgContent: `<rect/>`, duration: 1000 },
+            ],
+        });
+        // Both frames get an fd-N keyframes block …
+        expect(svg).toMatch(/@keyframes fd-0\s*{/);
+        expect(svg).toMatch(/@keyframes fd-1\s*{/);
+        // … alongside the existing fv-N opacity block.
+        expect(svg).toMatch(/@keyframes fv-0\s*{/);
+        // The keyframes flip display between none and inline.
+        expect(svg).toMatch(/display:\s*none/);
+        expect(svg).toMatch(/display:\s*inline/);
+        // The frame's CSS rule lists BOTH animations, with the fd one tagged
+        // step-end so the display flip is instant (not snap-at-50% of segment).
+        expect(svg).toMatch(/\.f-0\s*{\s*animation:[^}]*fv-0[^}]*,[^}]*fd-0[^}]*step-end/);
+        // The base .f rule sets display:none so frames start hidden until the
+        // keyframe flips them in.
+        expect(svg).toMatch(/\.f\s*{[^}]*display:\s*none/);
+    });
+    it("DM-599: cut frames fold display into fv-N (same step-end timing)", () => {
+        // Three explicit `cut` frames — the all-mergeable check trips and these
+        // route through the MERGE pipeline. But a non-mergeable transition mixed
+        // in (e.g. push-left) would route this through the unmerged path. We
+        // verify the unmerged path's cut branch here by mixing.
+        const svg = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                { svgContent: `<rect fill="red"/>`, duration: 1000, transition: { type: "push-left", duration: 100 } },
+                { svgContent: `<rect fill="blue"/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
+                { svgContent: `<rect fill="green"/>`, duration: 1000 },
+            ],
+        });
+        // The "cut" frame's fv-N keyframes carry the display toggle inline (no
+        // separate fd-N block) since cut already uses step-end on fv-N.
+        const fv1Match = svg.match(/@keyframes fv-1\s*{[\s\S]*?\n\s*}/);
+        expect(fv1Match).not.toBeNull();
+        expect(fv1Match[0]).toMatch(/display:\s*none/);
+        expect(fv1Match[0]).toMatch(/display:\s*inline/);
+        // The "cut" frame uses ONLY fv-1 (no fd-1 — it's folded in).
+        expect(svg).not.toMatch(/@keyframes fd-1\s*{/);
+    });
+    it("DM-599: merged-path keyframes emit display alongside opacity", () => {
+        // Two crossfade frames with different content route through the merge
+        // pipeline. Per-element visibility classes (tN) now toggle BOTH opacity
+        // and display so the browser can skip painting hidden elements.
+        const svg = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                { svgContent: `<rect fill="red" width="50" height="50"/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
+                { svgContent: `<rect fill="blue" width="50" height="50"/>`, duration: 1000 },
+            ],
+        });
+        // Each tN keyframe stop with opacity:1 also has display:inline; each
+        // opacity:0 stop has display:none.
+        const tN = svg.match(/@keyframes t\d+\s*{[\s\S]*?\n\s*}/);
+        expect(tN).not.toBeNull();
+        expect(tN[0]).toMatch(/opacity:\s*1;\s*display:\s*inline/);
+        expect(tN[0]).toMatch(/opacity:\s*0;\s*display:\s*none/);
+    });
     it("cut transition: timeline boundary is exactly at the frame edge", () => {
         // For two frames each held 1000ms with cut transitions and no overlap,
         // the visibility flip should land at exactly 50% of the scene.

package/dist/animation/index.d.ts

@@ -0,0 +1,2 @@
+export { generateAnimatedSvg, type AnimationConfig, type AnimationFrame, type AnimationOverlay, type TypingOverlay, type TapOverlay, type SvgOverlay, type IntraFrameAnimation, } from "./animator.js";
+export { cursorOverlayMarkup, resolveCursorScript, type CursorOverlay, type CursorEvent, type CursorMoveEvent, type CursorClickEvent, type CursorShowEvent, type CursorHideEvent, type CursorStyle, type SelectorResolver, } from "./cursor-overlay.js";

package/dist/animation/index.js

@@ -0,0 +1,7 @@
+// Public surface of the animation pipeline. The composer
+// (`generateAnimatedSvg`) consumes per-frame element trees + transition /
+// overlay config and emits one self-contained SVG with `@keyframes` cross-
+// fade / push-left / scroll / cut transitions and optional typing / tap /
+// SVG / cursor overlays.
+export { generateAnimatedSvg, } from "./animator.js";
+export { cursorOverlayMarkup, resolveCursorScript, } from "./cursor-overlay.js";

package/dist/capture/embed.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Image-embed pipeline: turn `<img src>`, `background-image: url(...)`,
+ * `mask-image: url(...)`, `border-image-source: url(...)`, and
+ * `list-style-image: url(...)` URLs into self-contained data URIs the renderer
+ * can inline into the SVG output. Three pieces:
+ *
+ *  1. `embedAsDataUri` / `_dataUriCache` — synchronous local-file / cached
+ *     data-URI lookup used by the renderer at emit time.
+ *  2. `embedResizedDataUri` / `_resizedDataUriCache` / `_activeHiDPIFactor` —
+ *     DM-540 size-tagged variant: returns a pre-resized data URI when the
+ *     resize pre-pass (`resizeEmbeddedImages`) populated the cache for the
+ *     consumer's CSS box, falling back to the source-resolution URI otherwise.
+ *  3. `embedRemoteImages` — async pre-pass that fetches every http(s) URL
+ *     referenced by the captured tree and stashes the bytes in
+ *     `_dataUriCache`. Yields a self-contained SVG that renders in image
+ *     viewers (Preview, QuickLook, etc.) that block remote resources from
+ *     local files.
+ */
+import type { CapturedElement, CaptureWarning } from "./types.js";
+/**
+ * @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>>;
+export declare function setActiveHiDPIFactor(n: number): void;
+/**
+ * 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>;