domotion-svg 0.16.0 → 0.18.0

package/FEATURES.md

@@ -57,7 +57,11 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [x] **replaced-video-poster**: `<video poster=…>` paused — poster image captured
 - [x] **replaced-canvas-overlay**: `<canvas>` under a positioned `<div z-index:10>` overlay — overlay does NOT bleed into the canvas snapshot
 - [x] **replaced-canvas-fixed-overlay**: `<canvas>` under a sibling-positioned `<div>` painting on top — sibling does NOT bleed into the canvas snapshot
-- [x] **replaced-iframe-same-origin**: same-origin `<iframe>` (srcdoc) — iframe content paints into the snapshot
+- [x] **replaced-iframe-same-origin** (DM-1441): same-origin `<iframe>` (srcdoc) — content **recurses into native SVG** (crisp/scalable/selectable), not rastered; pixel-identical to the prior snapshot. See [docs/81](docs/81-iframe-recursion.md).
+- [x] **iframe-recursion-bordered** (DM-1441): same-origin iframe recursion through a non-zero border + padding on the iframe — inner document's origin lands at the iframe **content box** and the inner subtree clips to it.
+- [x] **iframe-canvas-bg-fill** (DM-1448): recursed iframe **taller than its content** — the inner document's propagated canvas background (html-bg-or-else-body-bg) fills the whole inner viewport, so the strip below the content paints the canvas color instead of showing through to the outer page.
+- [x] **iframe-inner-clip-mask** (DM-1446): recursed iframe whose inner content uses `clip-path: url(#id)` + `mask-image: url(#id)` defined in the **iframe's own** `<defs>` — fragment refs resolve against `el.ownerDocument`, so the `<clipPath>`/`<mask>` defs hoist and paint (clipped circle + masked square-with-hole, 0.00%). (Inner `element(#id)` paint refs are frame-aware — DM-1447 — though CSS `element()` itself is unsupported in Chromium / dormant, DM-1450; tall-iframe canvas-bg fill shipped in DM-1448.)
+- [x] **cross-origin iframe recursion** (DM-1442): `--cross-origin-frames "*"|host[:port],…` (config: `captureCrossOriginFrames`) recurses **allowlisted** cross-origin frames into native SVG by launching Chromium with web security disabled; non-allowlisted frames stay raster. Default off + a stderr security warning (disabling web security disables CORS). Unit + e2e tested (`tests/cross-origin-iframe-recursion.e2e.test.ts`). See [docs/81](docs/81-iframe-recursion.md).
 - [x] **snapshot-isolation-pseudo-overlay** (DM-458, `tests/snapshot-isolation.tsx`): canvas covered by a sibling's `::after` pseudo overlay. Inspection-style — decodes the captured snapshot's PNG data URI and asserts no overlay-color pixels leaked through. Catches regressions in the hide-everything-else stylesheet that a comparison-style fixture wouldn't.
 
 ### Showcase Integration Tests

package/README.md

@@ -14,7 +14,7 @@
 
 **Domotion turns real HTML/CSS into one self-contained, animated SVG** — an accurate reproduction of the rendered page, with optional animation and simulated interaction built in. Text is emitted as real glyph paths, so it looks identical across browsers; the output scales crisply at any size and embeds anywhere with a plain `<img>`, no external assets.
 
-Beyond raw capture it ships a **template library** that turns a few flags into a polished animated SVG, **terminal-session capture** (a recording → an animated terminal), multi-frame **animation** with transitions, overlays, and simulated interaction, **device-chrome** framing, **nested compositing** (animated layers inside animated layers), one-command **SVG → MP4/WebM**, and a fidelity **review** tool.
+Beyond raw capture it ships a **template library** that turns a few flags into a polished animated SVG, **terminal-session capture** (a recording → an animated terminal), **scroll capture** (a long page replayed as one self-contained scrolling SVG), multi-frame **animation** with transitions, overlays, and simulated interaction, **device-chrome** framing, **nested compositing** (animated layers inside animated layers), one-command **SVG → MP4/WebM**, and a fidelity **review** tool.
 
 <p align="center">
   <img src="examples/output/hero-product-demo.svg" alt="An analytics dashboard assembling itself inside a browser window — KPI cards rise in, a bar chart grows with its peak highlighted, a search query types itself, and a nav item is clicked — all in one self-contained animated SVG" width="760">
@@ -74,8 +74,13 @@ domotion capture ./demo.html \
 
 # Capture HTML piped on stdin.
 cat demo.html | domotion capture - -o demo.svg
+
+# Capture a long page as one animated scrolling SVG (scrolls to the bottom over 8s).
+domotion capture https://example.com --scroll "down:bottom/8s" -o scroll.svg
 ```
 
+Same-origin `<iframe>` content is recursed into the capture as native, selectable SVG rather than flattened to a screenshot; opt into cross-origin frames you trust with `--cross-origin-frames "<hosts>"`.
+
 For a multi-frame animated SVG, write a small JSON config and run `domotion animate`:
 
 ```bash
@@ -147,7 +152,7 @@ svg-review --expected example.debug/expected.png --actual example.debug/actual.s
 
 The browser opens a single review card showing the expected / actual / diff PNGs. Arrow keys cycle through the three at full size; drag on any image to mark a problem region and caption it. The side panel builds a GitHub-issue-ready Markdown block as you go — copy it, then file the issue at <https://github.com/brianwestphal/domotion/issues/new> and attach `expected.png` + `actual.svg` so a maintainer can reproduce.
 
-For an *animated* SVG, the package also ships `svg-scrubber` — a local video-style bench to play / pause / scrub / mark an in-out range, export the current frame as PNG, export the range as MP4, or trim it to a new self-contained animated SVG.
+For an *animated* SVG, the package also ships `svg-scrubber` — a local video-style bench to play / pause / scrub / mark an in-out range, export the current frame as PNG, export the range as MP4, or trim it to a new self-contained animated SVG. Add `--review` to file a focused issue against a moment in the timeline: it writes an importable `.ticket` (frame time, range, and drawn regions) the same way `svg-review` builds a report for a still.
 
 ### Scripting API
 

package/dist/animation/animator.js

@@ -6,6 +6,7 @@
  */
 import { cursorOverlayMarkup, resolveCursorScript } from "./cursor-overlay.js";
 import { escapeHtml } from "../utils/escapeHtml.js";
+import { isTransparentBackground } from "../utils/transparent-background.js";
 import { DEFAULT_TRANSITION_MS, frameAdvanceMs, transitionDurationMs } from "./frame-timeline.js";
 import { offsetEmbeddedAnimatedSvgTimeline } from "./embed-timeline.js";
 import { KEYFRAME_EPSILON, padAfter, padBefore } from "../utils/keyframe-pad.js";
@@ -38,7 +39,7 @@ function emitMagicMoveFrame(i, frame, mm, startPct, holdEndPct, transEndPct, tot
       ${afterH}% { opacity: 0; visibility: hidden; }
       100% { opacity: 0; visibility: hidden; }
     }
-    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; animation-timing-function: step-end; }`);
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s step-end infinite; }`);
     // Bridge composite: visible during the transition window only.
     groups.push(`  <g class="f mm-${i}">\n${mm.compositeSvg}\n  </g>`);
     keyframes.push(`
@@ -50,7 +51,7 @@ function emitMagicMoveFrame(i, frame, mm, startPct, holdEndPct, transEndPct, tot
       ${afterT}% { opacity: 0; visibility: hidden; }
       100% { opacity: 0; visibility: hidden; }
     }
-    .mm-${i} { animation: mmv-${i} ${totalSec.toFixed(2)}s infinite; animation-timing-function: step-end; }`);
+    .mm-${i} { animation: mmv-${i} ${totalSec.toFixed(2)}s step-end infinite; }`);
     // Per-element slide / fade keyframes within the window (linear interp).
     // The composite is only visible [holdEnd..transEnd], so the held values
     // outside that window are never painted — they just pin the endpoints.
@@ -111,18 +112,11 @@ function emitMagicMoveFrame(i, frame, mm, startPct, holdEndPct, transEndPct, tot
     }
     return { groups, keyframes };
 }
-/**
- * Emit one crossfade or cut frame (the default transition path): the frame
- * blob plus its opacity keyframes. `cut` (or zero-duration) uses disjoint
- * step-end keyframes so opacity flips instantly with no interpolation smear;
- * crossfade overlaps the fade-in with the previous frame's fade-out, with the
- * visible window driven by `fadeInStartPct` (precomputed by the caller, which
- * knows the overlap state). Extracted from `generateAnimatedSvg` (DM-1089).
- */
-function emitCrossfadeOrCutFrame(i, frame, transType, transDur, startPct, holdEndPct, transEndPct, fadeInStartPct, totalSec, 
+function emitCrossfadeOrCutFrame(i, frame, transType, transDur, win, totalSec, 
 /** DM-1148: the last frame, when the loop must NOT cross-dissolve, holds
  *  opacity 1 to 100% instead of fading out over its transition window. */
 holdToEnd) {
+    const { startPct, holdEndPct, transEndPct, fadeInStartPct } = win;
     const groups = [];
     const keyframes = [];
     groups.push(`  <g class="f f-${i}">\n${frame.svgContent}\n  </g>`);
@@ -141,7 +135,7 @@ holdToEnd) {
       ${afterEnd}% { opacity: 0; visibility: hidden; }
       100% { opacity: 0; visibility: hidden; }
     }
-    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; animation-timing-function: step-end; }`);
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s step-end infinite; }`);
     }
     else {
         const prevEnd = i > 0
@@ -212,18 +206,9 @@ export function dedupeFrameIds(frames) {
         return { ...frame, svgContent: out };
     });
 }
-/**
- * Push-left (horizontal) / scroll (vertical) slide frame. Both emit the SAME
- * clipped frame group and a `slideKeyframes` track — they differ only in the
- * EXIT slide axis (`X`/`Y`) and the slid extent (viewport width / height). The
- * group rect always spans `width × height`. The frame's ENTRANCE is composed
- * separately from `enter` (DM-1414): a slide frame after a crossfade fades in,
- * after a different-axis slide slides in on the predecessor's axis, etc.
- * Extracted from generateAnimatedSvg (DM-1375), mirroring emit*Frame.
- */
-function emitSlideFrame(i, svgContent, exitAxis, exitSize, enter, width, height, enterStartPct, startPct, holdEndPct, transEndPct, totalSec, holdLastFrame) {
-    const group = `  <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${svgContent}\n  </g></g>`;
-    const keyframe = slideKeyframes(i, exitAxis, exitSize, enter, enterStartPct, startPct, holdEndPct, transEndPct, enterStartPct, transEndPct, totalSec, holdLastFrame);
+function emitSlideFrame(i, svgContent, exitAxis, exitSize, enter, dims, win, totalSec, holdLastFrame) {
+    const group = `  <g class="f f-${i}"><clipPath id="fc-${i}"><rect width="${dims.width}" height="${dims.height}" /></clipPath><g clip-path="url(#fc-${i})" class="fp fp-${i}">\n${svgContent}\n  </g></g>`;
+    const keyframe = slideKeyframes(i, exitAxis, exitSize, enter, win.enterStartPct, win.startPct, win.holdEndPct, win.transEndPct, win.enterStartPct, win.transEndPct, totalSec, holdLastFrame);
     return { group, keyframe };
 }
 /**
@@ -290,19 +275,16 @@ export function generateAnimatedSvg(config) {
             };
         });
     }
-    // Pre-compute per-frame timing windows (used by both the merge pipeline for
-    // timeline keyframes and the atomic push/scroll fallbacks below).
-    const frameTiming = {
-        startPct: [], holdEndPct: [], transEndPct: [],
-    };
+    // Pre-compute each frame's start-of-window percentage — the only field
+    // `buildIntraFrameAnimationCss` reads. (The per-frame loop below recomputes the
+    // hold / transition windows it needs locally via `pct()`, so they aren't
+    // collected here.)
+    const frameTiming = { startPct: [] };
     {
         let t = 0;
         for (const f of frames) {
-            const td = transitionDurationMs(f);
             frameTiming.startPct.push((t / totalDuration) * 100);
-            frameTiming.holdEndPct.push(((t + f.duration) / totalDuration) * 100);
-            frameTiming.transEndPct.push(((t + f.duration + td) / totalDuration) * 100);
-            t += f.duration + td;
+            t += f.duration + transitionDurationMs(f);
         }
     }
     // Every sequence composites: each frame is emitted as a complete, internally
@@ -364,7 +346,7 @@ export function generateAnimatedSvg(config) {
             // The parallel `fd-${i}` display snap (inside slideKeyframes) lets the
             // browser skip painting this frame's content while it's fully off-screen
             // between cycles (DM-599).
-            const r = emitSlideFrame(i, frame.svgContent, "X", width, slideEnter, width, height, enterStartPct, startPct, holdEndPct, transEndPct, totalSec, holdLastFrame);
+            const r = emitSlideFrame(i, frame.svgContent, "X", width, slideEnter, { width, height }, { enterStartPct, startPct, holdEndPct, transEndPct }, totalSec, holdLastFrame);
             frameGroups.push(r.group);
             keyframes.push(r.keyframe);
         }
@@ -372,7 +354,7 @@ export function generateAnimatedSvg(config) {
             // DM-609: `scroll` is a real geometric scroll — the vertical equivalent of
             // push-left (translateY over height instead of translateX over width),
             // otherwise identical machinery. Exit slides up; enter per `slideEnter`.
-            const r = emitSlideFrame(i, frame.svgContent, "Y", height, slideEnter, width, height, enterStartPct, startPct, holdEndPct, transEndPct, totalSec, holdLastFrame);
+            const r = emitSlideFrame(i, frame.svgContent, "Y", height, slideEnter, { width, height }, { enterStartPct, startPct, holdEndPct, transEndPct }, totalSec, holdLastFrame);
             frameGroups.push(r.group);
             keyframes.push(r.keyframe);
         }
@@ -402,7 +384,7 @@ export function generateAnimatedSvg(config) {
             // holds-then-cuts — so this is a no-op for cut frames.
             const isCutFrame = transType === "cut" || transDur === 0;
             const holdToEnd = i === frames.length - 1 && config.loopFade !== true && !isCutFrame;
-            const r = emitCrossfadeOrCutFrame(i, frame, transType, transDur, startPct, holdEndPct, transEndPct, fadeInStartPct, totalSec, holdToEnd);
+            const r = emitCrossfadeOrCutFrame(i, frame, transType, transDur, { startPct, holdEndPct, transEndPct, fadeInStartPct }, totalSec, holdToEnd);
             frameGroups.push(...r.groups);
             keyframes.push(...r.keyframes);
         }
@@ -437,7 +419,7 @@ export function generateAnimatedSvg(config) {
     // Default (none / transparent) emits nothing so the SVG composites over the
     // host page, matching the single-frame `transparentRootBgRect` path (DM-554).
     const bg = config.background;
-    const canvasBgRect = (bg != null && bg !== "" && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)")
+    const canvasBgRect = (bg != null && !isTransparentBackground(bg))
         ? `  <rect width="${width}" height="${height}" fill="${bg}" />\n`
         : "";
     const out = `<?xml version="1.0" encoding="UTF-8"?>
@@ -876,25 +858,25 @@ function renderSvgOverlay(overlay, frameIdx, frameStart, frameHoldMs, totalDurat
         const e = overlay.enter;
         const easing = e.easing ?? "ease-out";
         const enterDelay = e.delay ?? 0;
-        const fromStr = offsetForDirection(e.from, overlay.width, overlay.height, true);
+        const fromStr = offsetForDirection(e.from, overlay.width, overlay.height);
         const enterStart = frameStart + enterDelay;
         const enterEnd = enterStart + e.duration;
         const enterId = `${id}-enter`;
         cssRules.push(`
     @keyframes ${enterId} { 0% { transform: ${fromStr}; } ${pct(enterStart, totalDuration)} { transform: ${fromStr}; } ${pct(enterEnd, totalDuration)} { transform: translate(0, 0); } 100% { transform: translate(0, 0); } }
-    .${id}-enter { animation: ${enterId} ${totalSec.toFixed(2)}s infinite; animation-timing-function: ${easing}; }`);
+    .${id}-enter { animation: ${enterId} ${totalSec.toFixed(2)}s ${easing} infinite; }`);
     }
     // Slide-out exit. Mirror of enter — translate from (0,0) to off-screen.
     if (overlay.exit != null) {
         const e = overlay.exit;
         const easing = e.easing ?? "ease-in";
         const exitDelay = e.delay ?? 0;
-        const toStr = offsetForDirection(e.from, overlay.width, overlay.height, false);
+        const toStr = offsetForDirection(e.from, overlay.width, overlay.height);
         const exitStart = overlayEnd - e.duration - exitDelay;
         const exitId = `${id}-exit`;
         cssRules.push(`
     @keyframes ${exitId} { 0%, ${pct(exitStart, totalDuration)} { transform: translate(0, 0); } ${pct(exitStart + e.duration, totalDuration)} { transform: ${toStr}; } 100% { transform: ${toStr}; } }
-    .${id}-exit { animation: ${exitId} ${totalSec.toFixed(2)}s infinite; animation-timing-function: ${easing}; }`);
+    .${id}-exit { animation: ${exitId} ${totalSec.toFixed(2)}s ${easing} infinite; }`);
     }
     // Markup: outer wrapper translates to (x, y) and clips, inner wrapper
     // carries the visibility class, then the enter/exit transform wrapper, then
@@ -908,12 +890,13 @@ function renderSvgOverlay(overlay, frameIdx, frameStart, frameHoldMs, totalDurat
     return { svgMarkup, css: cssRules.join("") };
 }
 /**
- * Offset string for a slide direction. When `outFrom` is true the offset is
- * the off-screen starting position (i.e. the overlay sits there before
- * animating to `(0,0)`). When false, it's the off-screen end position
- * (overlay animates from `(0,0)` to here on exit).
+ * Off-screen offset string for a slide direction — the point the overlay sits
+ * at when fully off-screen on the given side. Enter animates from this offset to
+ * `translate(0,0)`; exit animates from `translate(0,0)` back to it. The offset
+ * is the same for both (the enter-vs-exit direction is carried by the keyframe
+ * construction, not by this function), so it takes only the direction + size.
  */
-function offsetForDirection(dir, w, h, _outFrom) {
+function offsetForDirection(dir, w, h) {
     if (dir === "top")
         return `translate(0, -${h}px)`;
     if (dir === "bottom")
@@ -1001,7 +984,7 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
       ${endPct.toFixed(3)}% { ${propValue(a.to)} }
       100% { ${propValue(a.to)} }
     }
-    .anim-${a.animId} { animation: ${animName} ${totalSec.toFixed(2)}s infinite; animation-timing-function: ${easing};${originDecl} }`);
+    .anim-${a.animId} { animation: ${animName} ${totalSec.toFixed(2)}s ${easing} infinite;${originDecl} }`);
             }
         }
     }

package/dist/animation/composite.js

@@ -29,6 +29,7 @@
  * one-transform-animation-per-element rule, layer transforms live on the layer's
  * own wrapper group, separate from the nested content's animations.
  */
+import { isTransparentBackground } from "../utils/transparent-background.js";
 import { namespaceEmbeddedAnimatedSvg } from "./embed-namespace.js";
 import { offsetEmbeddedAnimatedSvgTimeline } from "./embed-timeline.js";
 import { parseSvgIntrinsicSize, fmt, clampPct } from "./svg-meta.js";
@@ -163,10 +164,9 @@ export function composeAnimatedLayers(layers, opts) {
         }
         groups.push(`<g class="${token}layer"${clipAttr}${groupStyle}>${nested}</g>`);
     }
-    // Transparent when empty / `transparent` / a fully-transparent rgba (matched
-    // whitespace-insensitively, so `rgba(0,0,0,0)` and `rgba(0, 0, 0, 0)` both count).
-    const bgNorm = (opts.background ?? "").replace(/\s+/g, "").toLowerCase();
-    const bg = bgNorm === "" || bgNorm === "transparent" || bgNorm === "rgba(0,0,0,0)"
+    // Transparent (no backdrop rect) for every transparent CSS form — keywords,
+    // zero-alpha hex, zero-alpha rgba()/hsla() — via the canonical predicate.
+    const bg = isTransparentBackground(opts.background ?? "")
         ? ""
         : `<rect width="${width}" height="${height}" fill="${opts.background}"/>`;
     const defs = defsParts.join("");

package/dist/capture/embed.js

@@ -85,18 +85,21 @@ function embedAsDataUri(url) {
 }
 /**
  * DM-540 — active hiDPI multiplier used by `embedResizedDataUri` lookups
- * during a single `elementTreeToSvg` invocation. Set at entry to that
- * function (via `setActiveHiDPIFactor`) and reset on exit. Must match the
- * value passed to `resizeEmbeddedImages` for the same tree, otherwise the
- * lookup misses and the renderer falls back to the source-resolution data
- * URI.
+ * during a single `elementTreeToSvg` invocation. `elementTreeToSvgInner` sets it
+ * (via `setActiveHiDPIFactor`) as the FIRST thing it does on EVERY call, so each
+ * render reads its own value and a stale value can't leak across renders — it's
+ * only ever read (as the `embedResizedDataUri` default) inside the render that
+ * just set it. Must match the value passed to `resizeEmbeddedImages` for the
+ * same tree, otherwise the lookup misses and the renderer falls back to the
+ * source-resolution data URI.
  *
  * Module-scoped because the resize lookup is buried in a dozen helper
  * functions (border-image, repeat-pattern, list marker, pseudo-image,
  * background-layer); threading the factor through every signature would
  * touch every call site and grow the renderer surface area for no
  * functional benefit. Captures run sequentially per Node event loop so
- * there's no concurrency hazard.
+ * there's no concurrency hazard. (DM-1435: considered a save/restore scope
+ * guard like `withRenderTextMode`, but set-at-entry already prevents the leak.)
  */
 let _activeHiDPIFactor = 2;
 export function setActiveHiDPIFactor(n) {

package/dist/capture/emoji.d.ts

@@ -17,6 +17,14 @@
  */
 import type { Page } from "@playwright/test";
 import type { CapturedElement } from "./types.js";
+/**
+ * Reset the process-global emoji caches — the opened Apple Color Emoji font and
+ * the extracted sbix-bitmap cache. These are process-stable (the system font
+ * doesn't change between renders), so this isn't needed per-generation; it
+ * exists for convention parity with `clearEmbeddedImageCaches()` and for test
+ * isolation / forcing a re-open. DM-1435.
+ */
+export declare function clearEmojiCaches(): void;
 /**
  * Snap an Apple Color Emoji sbix bitmap to the SQUARE box Chrome actually
  * paints it in.

package/dist/capture/emoji.js

@@ -18,12 +18,25 @@
 import { existsSync } from "node:fs";
 import * as fontkit from "fontkit";
 import { clipRectForScreenshot } from "./clip-rect.js";
+import { forEachElement } from "../tree-ops/for-each-element.js";
 const APPLE_COLOR_EMOJI_PATH = "/System/Library/Fonts/Apple Color Emoji.ttc";
 let _aceFont = null;
 let _aceFontLoaded = false;
 // Available sbix strikes on macOS Apple Color Emoji.ttc.
 const SBIX_STRIKES = [20, 26, 32, 40, 48, 52, 64, 96, 160];
 const _sbixCache = new Map();
+/**
+ * Reset the process-global emoji caches — the opened Apple Color Emoji font and
+ * the extracted sbix-bitmap cache. These are process-stable (the system font
+ * doesn't change between renders), so this isn't needed per-generation; it
+ * exists for convention parity with `clearEmbeddedImageCaches()` and for test
+ * isolation / forcing a re-open. DM-1435.
+ */
+export function clearEmojiCaches() {
+    _aceFont = null;
+    _aceFontLoaded = false;
+    _sbixCache.clear();
+}
 // Only take the sbix path when the glyph rect is roughly emoji-shaped (wide
 // enough relative to its height). Narrow rects are usually text-presentation
 // dingbats / partial clusters where the page-screenshot fallback is safer.
@@ -201,51 +214,46 @@ export async function rasterizeBitmapGlyphs(page, tree, viewport) {
     //    otherwise path-rendered plain-text run; renderer stamps an <image>
     //    over each char on top of the text path.
     const candidates = [];
-    const walk = (els) => {
-        for (const el of els) {
-            // Element-level raster (SK-1108): textarea content region, too
-            // involved to word-wrap in the path pipeline. Key on text+size+color so
-            // identical textareas dedupe to one screenshot.
-            if (el.elementRaster != null) {
-                const er = el.elementRaster;
-                // DM-936: include text-decoration + text-underline-position in the
-                // dedupe key so 3 identical-text `.vert.pos-{left,right,auto}`
-                // columns don't collapse to the same screenshot (the underline
-                // paints in different places per pos-* but tag+text+color+size
-                // alone hashes them all together → wrong-side underline in 2/3
-                // of the columns). Same for text-shadow / writing-mode variants.
-                // All the decoration keys are typed reads off CapturedStyles now; only
-                // the `text-decoration` shorthand isn't captured (just the longhands),
-                // so narrow-cast that single fallback read.
-                const s = el.styles;
-                const tdShorthand = s.textDecoration;
-                const tdKey = `${s.textDecorationLine ?? tdShorthand ?? ""}|${s.textUnderlinePosition ?? ""}|${s.textUnderlineOffset ?? ""}|${s.textDecorationStyle ?? ""}|${s.textDecorationColor ?? ""}|${s.textDecorationThickness ?? ""}|${s.textShadow ?? ""}|${s.writingMode ?? ""}`;
-                candidates.push({
-                    rect: { x: er.x, y: er.y, width: er.width, height: er.height },
-                    key: `el|${el.tag}|${el.text}|${el.styles.color}|${el.styles.fontSize}|${er.width}x${er.height}|${tdKey}`,
-                    setDataUri: (uri) => { er.dataUri = uri; },
-                });
-            }
-            if (el.textSegments != null) {
-                for (const seg of el.textSegments) {
-                    if (seg.rasterRect != null) {
-                        candidates.push({
-                            rect: seg.rasterRect,
-                            key: `seg|${seg.text}|${seg.color ?? ""}|${seg.fontSize ?? ""}|${seg.fontWeight ?? ""}`,
-                            setDataUri: (uri) => { seg.rasterDataUri = uri; },
-                        });
-                    }
-                    if (seg.rasterGlyphs != null) {
-                        for (const g of seg.rasterGlyphs)
-                            queueRasterGlyph(g, seg, el, candidates);
-                    }
+    forEachElement(tree, (el) => {
+        // Element-level raster (SK-1108): textarea content region, too
+        // involved to word-wrap in the path pipeline. Key on text+size+color so
+        // identical textareas dedupe to one screenshot.
+        if (el.elementRaster != null) {
+            const er = el.elementRaster;
+            // DM-936: include text-decoration + text-underline-position in the
+            // dedupe key so 3 identical-text `.vert.pos-{left,right,auto}`
+            // columns don't collapse to the same screenshot (the underline
+            // paints in different places per pos-* but tag+text+color+size
+            // alone hashes them all together → wrong-side underline in 2/3
+            // of the columns). Same for text-shadow / writing-mode variants.
+            // All the decoration keys are typed reads off CapturedStyles now; only
+            // the `text-decoration` shorthand isn't captured (just the longhands),
+            // so narrow-cast that single fallback read.
+            const s = el.styles;
+            const tdShorthand = s.textDecoration;
+            const tdKey = `${s.textDecorationLine ?? tdShorthand ?? ""}|${s.textUnderlinePosition ?? ""}|${s.textUnderlineOffset ?? ""}|${s.textDecorationStyle ?? ""}|${s.textDecorationColor ?? ""}|${s.textDecorationThickness ?? ""}|${s.textShadow ?? ""}|${s.writingMode ?? ""}`;
+            candidates.push({
+                rect: { x: er.x, y: er.y, width: er.width, height: er.height },
+                key: `el|${el.tag}|${el.text}|${el.styles.color}|${el.styles.fontSize}|${er.width}x${er.height}|${tdKey}`,
+                setDataUri: (uri) => { er.dataUri = uri; },
+            });
+        }
+        if (el.textSegments != null) {
+            for (const seg of el.textSegments) {
+                if (seg.rasterRect != null) {
+                    candidates.push({
+                        rect: seg.rasterRect,
+                        key: `seg|${seg.text}|${seg.color ?? ""}|${seg.fontSize ?? ""}|${seg.fontWeight ?? ""}`,
+                        setDataUri: (uri) => { seg.rasterDataUri = uri; },
+                    });
+                }
+                if (seg.rasterGlyphs != null) {
+                    for (const g of seg.rasterGlyphs)
+                        queueRasterGlyph(g, seg, el, candidates);
                 }
             }
-            if (el.children.length > 0)
-                walk(el.children);
         }
-    };
-    walk(tree);
+    });
     if (candidates.length === 0)
         return;
     const cache = new Map();

package/dist/capture/index.d.ts

@@ -66,6 +66,16 @@ export interface CaptureOptions {
      * Values < 1 are clamped to 1.
      */
     embedRemoteImagesHiDPIFactor?: number;
+    /**
+     * DM-1442: opt-in cross-origin `<iframe>` recursion. `"*"` recurses every
+     * cross-origin frame; a comma-separated `host[:port]` list recurses only
+     * frames whose origin matches an entry (exact host; `:port` requires an exact
+     * port, otherwise any port). Undefined / omitted leaves cross-origin frames
+     * as raster snapshots (same-origin frames recurse regardless). Enabling this
+     * launches Chromium with web security disabled — which also disables CORS, so
+     * only use it on trusted pages. See docs/81-iframe-recursion.md.
+     */
+    captureCrossOriginFrames?: string;
 }
 /**
  * Launch Chromium via Playwright, auto-installing the browser binary on first
@@ -78,6 +88,20 @@ export interface CaptureOptions {
  * are a normal `chromium.launch()` with no overhead.
  */
 export declare function launchChromium(opts?: LaunchOptions): Promise<Browser>;
+/**
+ * DM-1442: Chromium launch args needed to make cross-origin `<iframe>`
+ * documents readable from the in-page capture script. `--disable-web-security`
+ * lifts the Same-Origin Policy on cross-document access; the
+ * `--disable-features` flag co-locates frames in one renderer process so the
+ * cross-origin `contentDocument` is reachable (some builds need it, harmless on
+ * those that don't). Returns `[]` when `value` requests no cross-origin
+ * recursion, so callers can spread it unconditionally:
+ * `launchChromium({ args: crossOriginFramesLaunchArgs(value) })`.
+ *
+ * NOTE: disabling web security also disables CORS — only launch this way when
+ * capturing your own / trusted pages. Callers should print a visible warning.
+ */
+export declare function crossOriginFramesLaunchArgs(value: string | undefined | null): string[];
 export declare class DemoRecorder {
     private browser;
     private context;
@@ -91,10 +115,19 @@ export declare class DemoRecorder {
     private embedRemoteImagesRetryBackoffMs;
     private embedRemoteImagesResize;
     private embedRemoteImagesHiDPIFactor;
+    private captureCrossOriginFrames;
     constructor(baseUrl: string, opts: CaptureOptions);
     init(opts: CaptureOptions): Promise<void>;
     /** Navigate to a URL and capture the visible DOM as SVG. */
     captureUrl(path: string, waitMs?: number, idPrefix?: string): Promise<string>;
+    /**
+     * Shared post-capture pipeline (DM-1434): self-contained remote-image
+     * embedding + optional resize + conic-gradient rasterization, then reset the
+     * generation-scoped caches and render the tree to SVG body markup at `height`.
+     * `captureCurrent` (viewport) and `captureFullPage` (scrollable) differ only in
+     * the height, so they both funnel through here.
+     */
+    private renderCapturedTree;
     /** Capture the current page state as SVG content. */
     captureCurrent(idPrefix?: string): Promise<string>;
     /**
@@ -131,6 +164,32 @@ export declare function attachWebfontTracker(page: Page): {
     urls: Set<string>;
     detach: () => void;
 };
+/**
+ * Discover all `@font-face` rules in the page's stylesheets, fetch each
+ * font file via the browser context's request API (so cookies / CORS / auth
+ * follow whatever the browser is using), and register the bytes with
+ * `text-to-path.ts` so the renderer can draw with the actual webfont glyphs
+ * instead of falling through to the system-font substitutes.
+ *
+ * Should be called AFTER `await page.evaluate(() => document.fonts.ready)`
+ * — otherwise late-loading fonts may not be in `document.styleSheets` yet.
+ *
+ * Cross-origin stylesheets whose `cssRules` throw a SecurityError are silently
+ * skipped (we can't enumerate their rules from JS). Same-origin sheets and
+ * inline `<style>` blocks always work.
+ *
+ * Caller is responsible for `clearWebfonts()` between captures if needed.
+ * No-op when the page declares no `@font-face` rules.
+ */
+type FaceRule = {
+    kind: "font-face";
+    family: string;
+    weight: string;
+    style: string;
+    url: string;
+    urls?: string[];
+    unicodeRange?: Array<[number, number]>;
+};
 /** One row of the report returned by discoverAndRegisterWebfonts. */
 type WebfontRegisterReport = {
     family: string;
@@ -155,15 +214,7 @@ export declare function discoverAndRegisterWebfonts(page: Page, observedFontUrls
  * that never serialised back to text) aren't covered. Adequate for the
  * mainstream marketing-site case that motivated the change.
  */
-export declare function parseFontFaceRulesFromCssText(cssText: string, baseUrl: string): Array<{
-    kind: "font-face";
-    family: string;
-    weight: string;
-    style: string;
-    url: string;
-    urls?: string[];
-    unicodeRange?: Array<[number, number]>;
-}>;
+export declare function parseFontFaceRulesFromCssText(cssText: string, baseUrl: string): FaceRule[];
 /**
  * Parse a CSS `unicode-range` descriptor value (CSS Fonts 4 §4.5) into a list
  * of inclusive `[from, to]` codepoint intervals. Accepts the three forms:
@@ -187,6 +238,8 @@ export declare function captureElementTree(page: Page, selector: string | undefi
     y: number;
     width: number;
     height: number;
+}, opts?: {
+    crossOriginFrames?: string;
 }): Promise<CapturedElement[]>;
 /**
  * Same capture as `captureElementTree` but returns the warnings inline so
@@ -206,10 +259,37 @@ export declare function captureElementTreeWithWarnings(page: Page, selector: str
      *  rotating cross-origin-iframe content. Caller is responsible for
      *  ensuring the source covers the same coordinate space as `viewport`. */
     rasterizeFromImagePath?: string;
+    /** DM-1442: the raw `--cross-origin-frames` allowlist value (`"*"` or a
+     *  comma-separated `host[:port]` list). Passed into the capture script so
+     *  cross-origin iframes whose origin is on the list recurse into native SVG
+     *  instead of staying a raster snapshot. Requires the browser to have been
+     *  launched with web security disabled (see `crossOriginFramesLaunchArgs`).
+     *  Same-origin recursion (Phase 1) happens regardless. */
+    crossOriginFrames?: string;
 }): Promise<{
     tree: CapturedElement[];
     warnings: CaptureWarning[];
 }>;
+/**
+ * DM-494: Rasterise each element referenced by `mask-image: element(#id)`.
+ * Mirrors `rasterizeReplacedElements` (doc 17): hide-everything-else
+ * stylesheet → screenshot the target's painted box → encode as a data URI →
+ * stash on `tree[0].maskRasters[i].dataUri`. The renderer's `buildMaskDef`
+ * picks up the data URI from the root tree's lookup table when it sees an
+ * `element()` mask layer.
+ *
+ * Same-document only — CSS spec doesn't define cross-document `element()`.
+ * Always-on (no opt-in flag) — dedupe by referenced id (one screenshot per
+ * unique target regardless of how many consumers reference it). Targets that
+ * are display:none / 0-area are filtered at capture time and never reach
+ * here. See `docs/22-mask-element-paint-references.md`.
+ */
+export declare function rasterizeMaskSources(page: Page, tree: CapturedElement[], viewport: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): Promise<void>;
 /**
  * Calibrate `fontAscent` on text-bearing elements by scanning a reference
  * PNG (Chrome's actual paint) for each element's painted ink top, then