domotion-svg 0.17.0 → 0.19.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.d.ts

@@ -74,6 +74,11 @@ export interface AnimationConfig {
     width: number;
     height: number;
     frames: AnimationFrame[];
+    /** DM-1488: accessible name → `role="img"` + `<title>` on the root `<svg>`
+     *  (for inline-`<svg>` embedding). Omit to leave the output unchanged. */
+    title?: string;
+    /** DM-1488: accessible long description → `<desc>` on the root `<svg>`. */
+    desc?: string;
     /**
      * Markup (e.g. `<path id="g0" d="..."/>...`) hoisted into the top-level
      * `<defs>`. Frames can reference these IDs via `<use href="#...">`. Use for

package/dist/animation/animator.js

@@ -6,6 +6,8 @@
  */
 import { cursorOverlayMarkup, resolveCursorScript } from "./cursor-overlay.js";
 import { escapeHtml } from "../utils/escapeHtml.js";
+import { isTransparentBackground } from "../utils/transparent-background.js";
+import { rootSvgA11y } from "../render/format.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 +40,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 +52,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 +113,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 +136,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 +207,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 +347,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 +355,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 +385,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,11 +420,12 @@ 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 a11y = rootSvgA11y(config.title, config.desc);
     const out = `<?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}"${a11y.roleAttr}>${a11y.markup}
   <defs>
     <clipPath id="viewport-clip"><rect width="${width}" height="${height}" /></clipPath>${sharedDefsMarkup}
   </defs>
@@ -879,7 +866,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 +878,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 +986,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/animation/cursor-overlay.d.ts

@@ -153,16 +153,14 @@ resolveCursorAt?: CursorAtResolver | null): {
     cursorTimeline: CursorTimelineEntry[] | null;
 };
 /**
- * Emit the `<g class="cursor-overlay">` markup for an already-resolved
- * timeline. Returns "" when the timeline has no positions or every keyframe
- * is invisible.
- *
- * When `cursorTimeline` is provided (DM-1106), the pointer's GLYPH switches over
- * time to match what was under it: each distinct keyword gets a glyph drawn
- * hotspot-at-origin inside the shared position-animated group, with a discrete
- * opacity track that turns it on only during its windows (and visibility folds
- * in as the all-glyphs-off `null` state). Without a timeline, the single white
- * arrow paints (back-compat).
+ * DM-1507: the cursor overlay is emitted as CSS `@keyframes`, NOT SMIL. SMIL
+ * (`<animateTransform>`/`<animate>`) runs on the SVG's *own* timeline while the
+ * frame animations run on the CSS/document timeline — two clocks that Safari
+ * pauses/throttles independently when the SVG is offscreen (tab-switch, scrolled
+ * away), so the pointer drifted out of sync with the animation on return. Driving
+ * the cursor with CSS puts everything on ONE timeline; they pause and resume
+ * together, so they can't desync. The `@keyframes` are collected into a `<style>`
+ * inside the overlay group and applied via inline `animation:` on each element.
  */
 export declare function cursorOverlayMarkup(positions: KeyframePoint[], clicks: ResolvedClick[], style: CursorStyle, totalDurationMs: number, cursorTimeline?: CursorTimelineEntry[] | null): string;
 export {};

package/dist/animation/cursor-overlay.js

@@ -231,83 +231,104 @@ function resolveMoveTarget(ev, curX, curY, frameIndex, resolveSelector) {
  * in as the all-glyphs-off `null` state). Without a timeline, the single white
  * arrow paints (back-compat).
  */
+/** Small deterministic hash → 6-char base36, used to namespace this overlay's
+ *  `@keyframes` so a composited SVG with several overlays can't collide. */
+function overlayUid(seed) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36).padStart(6, "0").slice(0, 6);
+}
+/** Format a 0..1 keyframe fraction as a CSS keyframe percentage. */
+function pct(frac) {
+    return `${Number((frac * 100).toFixed(4))}%`;
+}
+/**
+ * DM-1507: the cursor overlay is emitted as CSS `@keyframes`, NOT SMIL. SMIL
+ * (`<animateTransform>`/`<animate>`) runs on the SVG's *own* timeline while the
+ * frame animations run on the CSS/document timeline — two clocks that Safari
+ * pauses/throttles independently when the SVG is offscreen (tab-switch, scrolled
+ * away), so the pointer drifted out of sync with the animation on return. Driving
+ * the cursor with CSS puts everything on ONE timeline; they pause and resume
+ * together, so they can't desync. The `@keyframes` are collected into a `<style>`
+ * inside the overlay group and applied via inline `animation:` on each element.
+ */
 export function cursorOverlayMarkup(positions, clicks, style, totalDurationMs, cursorTimeline = null) {
     if (positions.length === 0 || totalDurationMs <= 0)
         return "";
     const totalSec = totalDurationMs / 1000;
-    // animateTransform with values + keyTimes drives the cursor's translate.
-    const valueStrs = [];
-    const keyTimes = [];
-    for (const p of positions) {
-        valueStrs.push(`${num(p.x)},${num(p.y)}`);
-        keyTimes.push((p.t / totalDurationMs).toFixed(4));
-    }
-    // SMIL animateTransform requires keyTimes to start at 0 and end at 1; the
-    // resolveCursorScript anchor at t=0 and t=totalDurationMs guarantees this.
-    const posAnim = `<animateTransform attributeName="transform" type="translate" values="${valueStrs.join("; ")}" keyTimes="${keyTimes.join("; ")}" dur="${totalSec}s" repeatCount="indefinite" fill="freeze" />`;
-    // Pulse SVG fragments — one per click, with timing keyed off `t`.
-    const pulseMarkup = clicks.map((c, i) => buildPulseFragment(c, i, totalDurationMs)).join("\n");
+    const uid = overlayUid(`${totalDurationMs}|${positions.map((p) => `${p.x},${p.y},${p.t}`).join(";")}`);
+    const kf = []; // @keyframes collected here, injected into <style>
+    // Position track — linear translate along the keyframes (holds are duplicate
+    // consecutive values, exactly as under SMIL). keyTimes start at 0 and end at 1.
+    const posName = `co-pos-${uid}`;
+    kf.push(`@keyframes ${posName}{${positions.map((p) => `${pct(p.t / totalDurationMs)}{transform:translate(${num(p.x)}px,${num(p.y)}px)}`).join("")}}`);
+    const posAnim = `${posName} ${totalSec}s linear infinite`;
+    // Pulse fragments — one per click; each pushes its own keyframes into `kf`.
+    const pulseMarkup = clicks.map((c, i) => buildPulseFragment(c, i, uid, kf)).join("\n");
     let pointerGroup;
     if (cursorTimeline != null && cursorTimeline.length > 0) {
-        // DM-1106: one glyph per distinct keyword, each toggled by a discrete
-        // opacity track derived from the keyword timeline. The shared parent group
-        // carries the position animation; glyphs are hotspot-at-origin so each lands
-        // correctly regardless of its own hotspot.
+        // DM-1106: one glyph per distinct keyword, each toggled by a DISCRETE opacity
+        // track (SMIL `calcMode="discrete"` → CSS `step-end`, which holds each value
+        // until the next keyframe). The parent carries the position animation.
         const size = 22 * (style.cursorScale || 1);
-        const tKeyTimes = cursorTimeline.map((e) => (e.t / totalDurationMs).toFixed(4));
         const kinds = Array.from(new Set(cursorTimeline.map((e) => e.cursor).filter((c) => c != null)));
-        const glyphLayers = kinds.map((kind) => {
+        const glyphLayers = kinds.map((kind, gi) => {
             const glyph = cursorGlyphSvg(kind, 0, 0, size, style.cursorStroke);
-            const opVals = cursorTimeline.map((e) => (e.cursor === kind ? "1" : "0"));
-            return `      <g opacity="0">
-        <animate attributeName="opacity" values="${opVals.join(";")}" keyTimes="${tKeyTimes.join(";")}" dur="${totalSec}s" repeatCount="indefinite" calcMode="discrete" fill="freeze" />
+            const gName = `co-glyph-${uid}-${gi}`;
+            kf.push(`@keyframes ${gName}{${cursorTimeline.map((e) => `${pct(e.t / totalDurationMs)}{opacity:${e.cursor === kind ? "1" : "0"}}`).join("")}}`);
+            return `      <g opacity="0" style="animation:${gName} ${totalSec}s step-end infinite">
         ${glyph}
       </g>`;
         }).join("\n");
-        pointerGroup = `    <g class="cursor-pointer">
-      ${posAnim}
+        pointerGroup = `    <g class="cursor-pointer" style="animation:${posAnim}">
 ${glyphLayers}
     </g>`;
     }
     else {
         // Legacy single-arrow path (no auto cursor-type resolver supplied).
-        const visValues = positions.map((p) => (p.visible ? "1" : "0"));
-        pointerGroup = `    <g class="cursor-arrow" opacity="0">
-      ${posAnim}
-      <animate attributeName="opacity" values="${visValues.join(";")}" keyTimes="${keyTimes.join(";")}" dur="${totalSec}s" repeatCount="indefinite" calcMode="discrete" fill="freeze" />
+        const visName = `co-vis-${uid}`;
+        kf.push(`@keyframes ${visName}{${positions.map((p) => `${pct(p.t / totalDurationMs)}{opacity:${p.visible ? "1" : "0"}}`).join("")}}`);
+        pointerGroup = `    <g class="cursor-arrow" opacity="0" style="animation:${posAnim},${visName} ${totalSec}s step-end infinite">
       ${macosCursorPath(style.cursorScale)}
     </g>`;
     }
     return `  <g class="cursor-overlay" pointer-events="none">
+    <style>${kf.join("")}</style>
 ${pointerGroup}
 ${pulseMarkup}
   </g>`;
 }
-/** Build the SVG fragment for a single click pulse. */
-function buildPulseFragment(c, idx, totalDurationMs) {
+/** Build the SVG fragment for a single click pulse, pushing its keyframes into
+ *  `kf`. The expanding ring is `transform:scale` with `non-scaling-stroke` (so
+ *  it matches the old SMIL `r` growth but on the CSS timeline), played once at
+ *  its click time and frozen afterward (`forwards`), like the prior single-fire
+ *  SMIL pulse. */
+function buildPulseFragment(c, idx, uid, kf) {
     const beginSec = (c.t / 1000).toFixed(3);
     const durSec = (c.style.pulseDurationMs / 1000).toFixed(3);
     const r0 = 4;
     const r1 = c.style.pulseRadius;
     const innerR = r1 * 0.55;
+    const outerName = `co-pulse-${uid}-${idx}o`;
+    const innerName = `co-pulse-${uid}-${idx}i`;
+    kf.push(`@keyframes ${outerName}{0%{transform:scale(1);opacity:0}15%{opacity:0.9}100%{transform:scale(${num(r1 / r0)});opacity:0}}`);
+    kf.push(`@keyframes ${innerName}{0%{transform:scale(1);opacity:0}15%{opacity:0.95}100%{transform:scale(${num((r1 - 1) / r0)});opacity:0}}`);
+    const ringStyle = (name) => `transform-box:fill-box;transform-origin:center;vector-effect:non-scaling-stroke;animation:${name} ${durSec}s linear ${beginSec}s 1 forwards`;
     // Right-half-disc fill for secondary clicks.
     let secondaryHalf = "";
     if (c.button === "secondary") {
         const halfPath = `M ${num(c.x)} ${num(c.y - innerR)} A ${num(innerR)} ${num(innerR)} 0 0 1 ${num(c.x)} ${num(c.y + innerR)} Z`;
+        const halfName = `co-pulse-${uid}-${idx}h`;
+        kf.push(`@keyframes ${halfName}{0%{opacity:0}20%{opacity:1}100%{opacity:0}}`);
         secondaryHalf = `
-    <path d="${halfPath}" fill="rgba(0,0,0,0.2)" opacity="0">
-      <animate attributeName="opacity" values="0; 1; 0" keyTimes="0; 0.2; 1" dur="${durSec}s" begin="${beginSec}s" fill="freeze" />
-    </path>`;
+    <path d="${halfPath}" fill="rgba(0,0,0,0.2)" opacity="0" style="animation:${halfName} ${durSec}s linear ${beginSec}s 1 forwards" />`;
     }
     return `    <g class="cursor-click cursor-click-${idx}">
-      <circle cx="${num(c.x)}" cy="${num(c.y)}" r="${r0}" fill="none" stroke="${c.style.pulseStrokeOuter}" stroke-width="2" opacity="0">
-        <animate attributeName="r" values="${r0}; ${r1}" keyTimes="0; 1" dur="${durSec}s" begin="${beginSec}s" fill="freeze" />
-        <animate attributeName="opacity" values="0; 0.9; 0" keyTimes="0; 0.15; 1" dur="${durSec}s" begin="${beginSec}s" fill="freeze" />
-      </circle>
-      <circle cx="${num(c.x)}" cy="${num(c.y)}" r="${r0}" fill="none" stroke="${c.style.pulseStroke}" stroke-width="1" opacity="0">
-        <animate attributeName="r" values="${r0}; ${r1 - 1}" keyTimes="0; 1" dur="${durSec}s" begin="${beginSec}s" fill="freeze" />
-        <animate attributeName="opacity" values="0; 0.95; 0" keyTimes="0; 0.15; 1" dur="${durSec}s" begin="${beginSec}s" fill="freeze" />
-      </circle>${secondaryHalf}
+      <circle cx="${num(c.x)}" cy="${num(c.y)}" r="${r0}" fill="none" stroke="${c.style.pulseStrokeOuter}" stroke-width="2" opacity="0" style="${ringStyle(outerName)}" />
+      <circle cx="${num(c.x)}" cy="${num(c.y)}" r="${r0}" fill="none" stroke="${c.style.pulseStroke}" stroke-width="1" opacity="0" style="${ringStyle(innerName)}" />${secondaryHalf}
     </g>`;
 }
 /** macOS-style cursor arrow path. The hot point (0, 0) sits at the tip. */

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