domotion-svg 0.17.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

@@ -79,6 +79,8 @@ cat demo.html | domotion capture - -o demo.svg
 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
@@ -150,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 };
 }
 /**
@@ -361,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);
         }
@@ -369,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);
         }
@@ -399,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);
         }
@@ -434,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"?>
@@ -879,7 +864,7 @@ function renderSvgOverlay(overlay, frameIdx, frameStart, frameHoldMs, totalDurat
         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) {
@@ -891,7 +876,7 @@ function renderSvgOverlay(overlay, frameIdx, frameStart, frameHoldMs, totalDurat
         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
@@ -999,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/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,6 +115,7 @@ 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. */
@@ -213,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
@@ -232,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

package/dist/capture/index.js

@@ -12,6 +12,7 @@ import { resizeEmbeddedImages } from "../tree-ops/resize-embedded-images.js";
 import { rasterizeConicGradients } from "../render/conic-raster.js";
 import { resetGeneration, registerLocalFontAlias, registerWebfont } from "../render/text-to-path.js";
 import { CAPTURE_SCRIPT } from "./script.generated.js";
+import { parseCrossOriginAllowlist } from "./script/cross-origin.js";
 import { rasterizeBitmapGlyphs } from "./emoji.js";
 import { clipRectForScreenshot } from "./clip-rect.js";
 import { refineInitialLetterPositions } from "./initial-letter-probe.js";
@@ -50,6 +51,24 @@ function isMissingBrowserError(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return /Executable doesn't exist|playwright install|browserType\.launch.*Failed to launch/i.test(msg);
 }
+/**
+ * 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 function crossOriginFramesLaunchArgs(value) {
+    if (parseCrossOriginAllowlist(value) == null)
+        return [];
+    return ["--disable-web-security", "--disable-features=IsolateOrigins,site-per-process"];
+}
 export class DemoRecorder {
     browser = null;
     context = null;
@@ -63,6 +82,7 @@ export class DemoRecorder {
     embedRemoteImagesRetryBackoffMs;
     embedRemoteImagesResize;
     embedRemoteImagesHiDPIFactor;
+    captureCrossOriginFrames;
     constructor(baseUrl, opts) {
         this.baseUrl = baseUrl;
         this.width = opts.width;
@@ -73,9 +93,12 @@ export class DemoRecorder {
         this.embedRemoteImagesRetryBackoffMs = opts.embedRemoteImagesRetryBackoffMs;
         this.embedRemoteImagesResize = opts.embedRemoteImagesResize ?? false;
         this.embedRemoteImagesHiDPIFactor = opts.embedRemoteImagesHiDPIFactor;
+        this.captureCrossOriginFrames = opts.captureCrossOriginFrames;
     }
     async init(opts) {
-        this.browser = await launchChromium();
+        // DM-1442: when cross-origin iframe recursion is requested, launch with web
+        // security disabled so cross-origin contentDocuments are readable.
+        this.browser = await launchChromium({ args: crossOriginFramesLaunchArgs(opts.captureCrossOriginFrames) });
         this.context = await this.browser.newContext({
             viewport: { width: opts.width, height: opts.height },
             isMobile: opts.mobile ?? false,
@@ -158,7 +181,7 @@ export class DemoRecorder {
             throw new Error("Call init() first");
         const tree = await captureElementTree(this.page, "body", {
             x: 0, y: 0, width: this.width, height: this.height,
-        });
+        }, { crossOriginFrames: this.captureCrossOriginFrames });
         return this.renderCapturedTree(tree, this.height, idPrefix);
     }
     /**
@@ -171,7 +194,7 @@ export class DemoRecorder {
         const pageHeight = await this.page.evaluate(() => document.body.scrollHeight);
         const tree = await captureElementTree(this.page, "body", {
             x: 0, y: 0, width: this.width, height: pageHeight,
-        });
+        }, { crossOriginFrames: this.captureCrossOriginFrames });
         const svgContent = await this.renderCapturedTree(tree, pageHeight, idPrefix);
         return { svgContent, pageHeight };
     }
@@ -818,8 +841,8 @@ function parseWeightDescriptor(value) {
  * unsupported features encountered during capture are stored and accessible
  * via getLastCaptureWarnings() / logCaptureWarnings().
  */
-export async function captureElementTree(page, selector = "body", viewport) {
-    const { tree } = await captureElementTreeWithWarnings(page, selector, viewport);
+export async function captureElementTree(page, selector = "body", viewport, opts) {
+    const { tree } = await captureElementTreeWithWarnings(page, selector, viewport, opts);
     return tree;
 }
 /**
@@ -839,7 +862,7 @@ export async function captureElementTreeWithWarnings(page, selector = "body", vi
     // external refs exist; a fetch failure leaves the ref intact so the walk
     // warns as before.
     await inlineExternalSvgRefs(page);
-    const result = await page.evaluate(`(${CAPTURE_SCRIPT})({sel: ${JSON.stringify(selector)}, vp: ${JSON.stringify(viewport)}})`);
+    const result = await page.evaluate(`(${CAPTURE_SCRIPT})({sel: ${JSON.stringify(selector)}, vp: ${JSON.stringify(viewport)}, cof: ${JSON.stringify(opts?.crossOriginFrames ?? "")}})`);
     const typed = result;
     const warnings = typed.warnings ?? [];
     _resetLastCaptureWarnings(warnings);
@@ -1210,21 +1233,71 @@ async function rasterizeReplacedElements(page, tree, viewport, opts) {
  * are display:none / 0-area are filtered at capture time and never reach
  * here. See `docs/22-mask-element-paint-references.md`.
  */
-async function rasterizeMaskSources(page, tree, viewport) {
+export async function rasterizeMaskSources(page, tree, viewport) {
     if (tree.length === 0 || tree[0].maskRasters == null || tree[0].maskRasters.length === 0)
         return;
     const rasters = tree[0].maskRasters;
-    let styleHandle = null;
+    // DM-1447: a mask-image: element(#id) target can live inside a recursed
+    // same-origin <iframe>. Isolating it for the clipped screenshot means hiding
+    // everything in BOTH the top document AND the owning frame, while keeping the
+    // enclosing <iframe> element(s) visible so the target shows through. So inject
+    // the hide-everything CSS into every accessible frame, then per target mark
+    // it (in its own frame) + each enclosing <iframe> element up the chain. The
+    // screenshot clip is already in top-document px (the capture recorded the
+    // rect against the iframe-shifted viewport — DM-1441). For a top-document
+    // target the chain is just the target itself, identical to the prior path.
+    const main = page.mainFrame();
+    const frames = page.frames();
+    const styleHandles = [];
+    const clearMarkers = async () => {
+        for (const f of frames) {
+            try {
+                await f.evaluate(() => document.querySelectorAll("[data-domotion-snapshot-target]").forEach((el) => el.removeAttribute("data-domotion-snapshot-target")));
+            }
+            catch { /* cross-origin / detached frame */ }
+        }
+    };
     try {
-        styleHandle = await page.addStyleTag({ content: SNAPSHOT_HIDE_CSS });
+        for (const f of frames) {
+            try {
+                styleHandles.push(await f.addStyleTag({ content: SNAPSHOT_HIDE_CSS }));
+            }
+            catch { /* cross-origin / detached */ }
+        }
         for (const mr of rasters) {
-            await page.evaluate((rid) => {
-                const prev = document.querySelectorAll("[data-domotion-snapshot-target]");
-                prev.forEach((el) => el.removeAttribute("data-domotion-snapshot-target"));
-                const next = document.querySelector(`[data-domotion-rid="${rid}"]`);
-                if (next != null)
-                    next.setAttribute("data-domotion-snapshot-target", "");
-            }, mr.rid);
+            await clearMarkers();
+            // Locate the frame whose document holds the rid'd target.
+            let owner = null;
+            for (const f of frames) {
+                try {
+                    if (await f.evaluate((rid) => document.querySelector(`[data-domotion-rid="${rid}"]`) != null, mr.rid)) {
+                        owner = f;
+                        break;
+                    }
+                }
+                catch { /* cross-origin / detached */ }
+            }
+            if (owner == null)
+                continue;
+            try {
+                await owner.evaluate((rid) => {
+                    const t = document.querySelector(`[data-domotion-rid="${rid}"]`);
+                    if (t != null)
+                        t.setAttribute("data-domotion-snapshot-target", "");
+                }, mr.rid);
+                // Mark each enclosing <iframe> element up to the main frame so the
+                // target shows through (a visible child shows even inside a hidden
+                // ancestor; the inner frame's own hide-CSS isolates the target there).
+                let f = owner;
+                while (f != null && f !== main) {
+                    const iframeEl = await f.frameElement();
+                    await iframeEl.evaluate((el) => el.setAttribute("data-domotion-snapshot-target", ""));
+                    f = f.parentFrame();
+                }
+            }
+            catch {
+                continue;
+            }
             const clip = clipRectForScreenshot(mr.rect, viewport);
             try {
                 const buf = await page.screenshot({ clip, omitBackground: true, type: "png" });
@@ -1236,15 +1309,10 @@ async function rasterizeMaskSources(page, tree, viewport) {
         }
     }
     finally {
-        try {
-            await page.evaluate(() => {
-                document.querySelectorAll("[data-domotion-snapshot-target]").forEach((el) => el.removeAttribute("data-domotion-snapshot-target"));
-            });
-        }
-        catch { }
-        if (styleHandle != null) {
+        await clearMarkers();
+        for (const h of styleHandles) {
             try {
-                await styleHandle.evaluate((node) => { node.remove(); });
+                await h.evaluate((node) => { node.remove(); });
             }
             catch { }
         }

package/dist/capture/script/cross-origin.d.ts

@@ -0,0 +1,17 @@
+export type CrossOriginAllowEntry = {
+    host: string;
+    port: string | null;
+};
+export type CrossOriginAllowlist = "*" | CrossOriginAllowEntry[];
+/**
+ * Parse the raw `--cross-origin-frames` value into a normalized allowlist, or
+ * `null` when no cross-origin recursion is requested (empty / undefined).
+ * `"*"` (alone or as any entry) collapses to recurse-all.
+ */
+export declare function parseCrossOriginAllowlist(value: string | undefined | null): CrossOriginAllowlist | null;
+/**
+ * Does `frameUrl`'s origin match the allowlist? Default ports are normalized
+ * (http→80, https→443) so `maps.google.com:443` matches `https://maps.google.com/`.
+ * Returns false for an unparseable URL or a null allowlist.
+ */
+export declare function frameHostAllowed(frameUrl: string, allow: CrossOriginAllowlist | null): boolean;

package/dist/capture/script/cross-origin.js

@@ -0,0 +1,83 @@
+// Cross-origin iframe allowlist (DM-1442) — parsing + matching for the
+// `--cross-origin-frames` flag. Pure functions with no DOM / Node deps (only
+// the `URL` global, available in both the page and Node), so this module is
+// BOTH bundled into the page-context capture script (via
+// `src/capture/script/index.ts`, under CAPTURE_SCRIPT discipline) AND imported
+// + unit-tested node-side. See docs/81-iframe-recursion.md.
+//
+// Allowlist grammar (the value of `--cross-origin-frames`):
+//   "*"                       → every cross-origin frame is recursed
+//   "host[:port],host[:port]" → exact-host entries. An entry with a `:port`
+//                               requires an exact host+port match; without a
+//                               port the host matches on ANY port. Subdomains
+//                               are NOT implied (example.com ≠ www.example.com).
+//   "" / undefined            → no cross-origin recursion (null)
+/**
+ * Parse the raw `--cross-origin-frames` value into a normalized allowlist, or
+ * `null` when no cross-origin recursion is requested (empty / undefined).
+ * `"*"` (alone or as any entry) collapses to recurse-all.
+ */
+export function parseCrossOriginAllowlist(value) {
+    if (value == null)
+        return null;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return null;
+    if (trimmed === "*")
+        return "*";
+    const entries = [];
+    for (const raw of trimmed.split(",")) {
+        const part = raw.trim();
+        if (part === "")
+            continue;
+        if (part === "*")
+            return "*"; // a bare * anywhere means "all"
+        // host[:port] — a single trailing `:digits` is the port; everything else is
+        // the host. (Hosts here are plain registrable names / localhost / IPs, so a
+        // simple last-colon split is sufficient.)
+        const colon = part.lastIndexOf(":");
+        if (colon > 0 && /^[0-9]+$/.test(part.slice(colon + 1))) {
+            entries.push({ host: part.slice(0, colon).toLowerCase(), port: part.slice(colon + 1) });
+        }
+        else {
+            entries.push({ host: part.toLowerCase(), port: null });
+        }
+    }
+    return entries.length > 0 ? entries : null;
+}
+/**
+ * Does `frameUrl`'s origin match the allowlist? Default ports are normalized
+ * (http→80, https→443) so `maps.google.com:443` matches `https://maps.google.com/`.
+ * Returns false for an unparseable URL or a null allowlist.
+ */
+export function frameHostAllowed(frameUrl, allow) {
+    if (allow == null)
+        return false;
+    if (allow === "*")
+        return true;
+    let host;
+    let port;
+    try {
+        const u = new URL(frameUrl);
+        host = u.hostname.toLowerCase();
+        port = u.port;
+        if (port === "") {
+            if (u.protocol === "https:")
+                port = "443";
+            else if (u.protocol === "http:")
+                port = "80";
+        }
+    }
+    catch {
+        return false;
+    }
+    for (const entry of allow) {
+        if (entry.host !== host)
+            continue;
+        if (entry.port == null)
+            return true; // host on any port
+        if (entry.port === port)
+            return true; // exact host + port
+    }
+    return false;
+}