domotion-svg 0.5.0 → 0.6.0

package/README.md

@@ -1,4 +1,6 @@
-# Domotion
+<p align="center">
+  <img src="examples/output/domotion-word-demo.svg" alt="Domotion — an animated wordmark cycling through twenty neon-retro typographic variants of the word domotion" width="600">
+</p>
 
 DOM-to-animated-SVG renderer. Captures HTML/CSS rendered in headless Chromium and converts the captured tree into a self-contained SVG with optional CSS animations — pixel-faithful to what Chromium painted, scales crisply at any size, and embeds without external assets.
 
@@ -39,6 +41,9 @@ yourself to keep the first job's runtime down.
 The fastest way in is the `domotion` CLI — no TypeScript, no Playwright bring-up. Point it at a URL or HTML file:
 
 ```bash
+# Zero-install: run the published CLI straight from npm.
+npx domotion-svg capture https://example.com -o example.svg
+
 # Capture a URL as SVG.
 domotion capture https://example.com -o example.svg
 
@@ -61,19 +66,44 @@ domotion animate ./demo.json
 
 The config describes each frame (input, duration, transition) plus a declarative surface for interaction demos: continuous-session frames that carry client-side state across steps (omit `input` / set `"continue": true`), DOM-mutation and interaction actions, richer readiness waits (`waitForText` / `waitForGone` / `waitForCount`), typing / tap / svg / blink overlays that can anchor to an element's box, an on-screen `cursor` (explicit or `"auto"`), `vars` + `${}` interpolation, and a small `evaluate` escape hatch. See `domotion --help` for the full grammar and the [Quick start](https://brianwestphal.github.io/domotion/start/quickstart/) for a walkthrough.
 
+### Export to video
+
+The package also ships a standalone `svg-to-video` CLI that renders an animated SVG (a `domotion animate` output, or any CSS-/SMIL-animated SVG) to a video file. It steps the animation timeline frame by frame in Chromium for frame-accurate timing, then pipes the frames to **ffmpeg** (a required external dependency — install via `brew` / `apt` / `winget`).
+
+```bash
+# h264/mp4 at 30fps, contained to 1280px wide.
+svg-to-video demo.svg -o demo.mp4 --width 1280
+
+# 60fps VP9/webm with looping background music.
+svg-to-video demo.svg -o demo.webm --format vp9 --fps 60 --music bed.mp3
+```
+
+Supports target size (`--width`/`--height`, aspect-preserving), `--fps`, `--format` / `--container`, supersampling (`--scale`), background music / foreground audio / captions, and a disk-space pre-flight. See `svg-to-video --help`.
+
+### Reviewing a regression
+
+If a capture comes out looking different from how Chromium painted the source page, the package ships an `svg-review` CLI to help you file a focused bug report. Capture once with `--debug` to get a reproduction bundle (HAR + the Chromium screenshot of the source + the SVG we produced), then open the bundle in the local review UI:
+
+```sh
+domotion capture https://example.com --debug -o example.svg
+svg-review --expected example.debug/expected.png --actual example.debug/actual.svg
+```
+
+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.
+
 ### Scripting API
 
 When you outgrow the CLI — custom interaction loops, programmatic frame composition, custom overlays — the same primitives are available as a library:
 
 ```ts
-import { captureElementTree, elementTreeToSvg, launchChromium, wrapSvg } from "domotion-svg";
+import { captureElementTree, elementTreeToSvg, launchChromium } from "domotion-svg";
 
 const browser = await launchChromium();
 const page = await browser.newPage();
 await page.setContent(`<div style="padding:20px;color:white;background:#0d1117">Hello</div>`);
 
 const tree = await captureElementTree(page, "body", { x: 0, y: 0, width: 800, height: 200 });
-const svg = wrapSvg(elementTreeToSvg(tree, 800, 200), 800, 200);
+const svg = elementTreeToSvg(tree, 800, 200);
 
 console.log(svg);
 await browser.close();

package/dist/animation/animator.d.ts

@@ -5,6 +5,7 @@
  * animated SVG with CSS keyframe transitions.
  */
 import { type CursorOverlay, type SelectorResolver } from "./cursor-overlay.js";
+import type { MagicMove } from "./magic-move.js";
 export interface AnimationFrame {
     /** SVG content for this frame (from dom-to-svg) */
     svgContent: string;
@@ -28,11 +29,26 @@ export interface AnimationFrame {
          * `crossfade` (default) overlaps fade-out and fade-in. `push-left` slides
          * the outgoing frame off and the incoming frame in from the right.
          * `scroll` keeps both visible during the transition. `cut` is instant —
-         * no fade, no slide. For `cut`, `duration` is ignored.
+         * no fade, no slide. For `cut`, `duration` is ignored. `magic-move` blends
+         * shared elements between the two frames — matched elements slide from
+         * their old position to their new one while added/removed elements
+         * cross-fade (DM-898; see `docs/53-magic-move-transition.md`). It requires
+         * the per-frame `magicMove` bridge layer (built caller-side from the
+         * element trees); when that's absent it degrades to `crossfade`.
          */
-        type: "crossfade" | "push-left" | "scroll" | "cut";
+        type: "crossfade" | "push-left" | "scroll" | "cut" | "magic-move";
         duration: number;
     };
+    /**
+     * Magic-move bridge layer for this frame's transition to the next, built by
+     * the caller via `buildMagicMove(prevTree, nextTree, …)`. Present only when
+     * `transition.type === "magic-move"` and both frames' element trees were
+     * available; the animator shows it during the transition window (moved
+     * elements slide, added fade in, removed fade out) between the hard-cut prev
+     * and next frame blobs. When `transition.type` is `magic-move` but this is
+     * null, the animator falls back to `crossfade`.
+     */
+    magicMove?: MagicMove | null;
     /** Overlays: typing, tap ripple */
     overlays?: AnimationOverlay[];
     /**
@@ -228,5 +244,13 @@ export interface AnimationConfig {
      * uses `selector`; otherwise pass undefined / null.
      */
     resolveSelector?: SelectorResolver;
+    /**
+     * Canvas background color painted behind every frame (a full-viewport
+     * `<rect>`). Mirrors the single-frame path's `transparentRootBgRect`
+     * (DM-554): pass the captured page's root background so animated output
+     * matches `capture` output. Omitted / `"transparent"` / `"rgba(0, 0, 0, 0)"`
+     * → no rect, i.e. a transparent SVG that composites over a host background.
+     */
+    background?: string;
 }
 export declare function generateAnimatedSvg(config: AnimationConfig): string;

package/dist/animation/animator.js

@@ -51,6 +51,11 @@ export function generateAnimatedSvg(config) {
         const prevFrame = i > 0 ? frames[i - 1] : null;
         const entersViaPush = prevFrame?.transition?.type === "push-left";
         const entersViaScroll = prevFrame?.transition?.type === "scroll";
+        // DM-898: a frame entered from a magic-move transition appears at its own
+        // start (= the predecessor's transition end), NOT overlap-faded — the
+        // magic-move bridge layer already covered the window, so a crossfade
+        // overlap here would double-show the next frame on top of the bridge.
+        const entersViaMagicMove = prevFrame?.transition?.type === "magic-move" && prevFrame?.magicMove != null;
         // Both push-left and scroll overlap their transition with the next
         // frame's entry — the next frame is already sliding in while the current
         // one slides out, so its show window starts at `timeOffset - prevTransDur`
@@ -117,6 +122,117 @@ export function generateAnimatedSvg(config) {
     .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }
     .fp-${i} { animation: fp-${i} ${totalSec.toFixed(2)}s infinite; }`);
         }
+        else if (transType === "magic-move" && frame.magicMove != null) {
+            // DM-898: magic-move. Frame i holds [start..holdEnd] then HARD-CUTS out;
+            // a bridge composite covers the transition window [holdEnd..transEnd],
+            // inside which matched elements slide prev→next, added elements fade in,
+            // and removed elements fade out. The next frame cuts in at transEnd
+            // (= its own start). The bridge's start state matches the prev frame's
+            // final paint and its end state the next frame's initial paint, so both
+            // hard cuts are seamless. (When `frame.magicMove` is null the type falls
+            // through to the crossfade branch below — the documented fallback.)
+            const mm = frame.magicMove;
+            const sNum = parseFloat(startPct);
+            const hNum = parseFloat(holdEndPct);
+            const tNum = parseFloat(transEndPct);
+            const beforeS = Math.max(0, sNum - 0.001).toFixed(3);
+            const afterH = Math.min(100, hNum + 0.001).toFixed(3);
+            const beforeH = Math.max(0, hNum - 0.001).toFixed(3);
+            const afterT = Math.min(100, tNum + 0.001).toFixed(3);
+            // Frame i blob: visible only during its hold, hard-cut out at hold end.
+            frameGroups.push(`  <g class="f f-${i}">\n${frame.svgContent}\n  </g>`);
+            keyframes.push(`
+    @keyframes fv-${i} {
+      0% { opacity: 0; visibility: hidden; }
+      ${beforeS}% { opacity: 0; visibility: hidden; }
+      ${sNum.toFixed(3)}% { opacity: 1; visibility: visible; }
+      ${hNum.toFixed(3)}% { opacity: 1; visibility: visible; }
+      ${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; }`);
+            // Bridge composite: visible during the transition window only.
+            frameGroups.push(`  <g class="f mm-${i}">\n${mm.compositeSvg}\n  </g>`);
+            keyframes.push(`
+    @keyframes mmv-${i} {
+      0% { opacity: 0; visibility: hidden; }
+      ${beforeH}% { opacity: 0; visibility: hidden; }
+      ${hNum.toFixed(3)}% { opacity: 1; visibility: visible; }
+      ${tNum.toFixed(3)}% { opacity: 1; visibility: visible; }
+      ${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; }`);
+            // 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.
+            //
+            // A dual-render cross-fade copy (DM-903) is BOTH a slide and a fade, so
+            // its element needs two animations. They MUST go in one `animation:`
+            // declaration (comma-joined) — two separate `.cls { animation: … }` rules
+            // would have the later one silently override the former, dropping the
+            // slide. Accumulate per-class animation entries and emit one rule each.
+            const animEntries = new Map();
+            const addAnim = (cls, name) => {
+                const list = animEntries.get(cls) ?? [];
+                list.push(`${name} ${totalSec.toFixed(2)}s infinite`);
+                animEntries.set(cls, list);
+            };
+            for (const s of mm.slides) {
+                // Interpolate the element's transform `from → to` across the window.
+                // The next-appearance copy maps its prev rect → `none` (final next
+                // rect); a cross-fade prev copy maps `none` → its next rect, so both
+                // copies trace the same path (DM-899 geometry; DM-903 paired copies).
+                keyframes.push(`
+    @keyframes mms-${s.cls} {
+      0%, ${hNum.toFixed(3)}% { transform: ${s.from}; }
+      ${tNum.toFixed(3)}%, 100% { transform: ${s.to}; }
+    }`);
+                addAnim(s.cls, `mms-${s.cls}`);
+            }
+            for (const cls of mm.fadeIn) {
+                keyframes.push(`
+    @keyframes mmf-${cls} {
+      0%, ${hNum.toFixed(3)}% { opacity: 0; }
+      ${tNum.toFixed(3)}%, 100% { opacity: 1; }
+    }`);
+                addAnim(cls, `mmf-${cls}`);
+            }
+            for (const cls of mm.fadeOut) {
+                keyframes.push(`
+    @keyframes mmf-${cls} {
+      0%, ${hNum.toFixed(3)}% { opacity: 1; }
+      ${tNum.toFixed(3)}%, 100% { opacity: 0; }
+    }`);
+                addAnim(cls, `mmf-${cls}`);
+            }
+            for (const [cls, entries] of animEntries) {
+                keyframes.push(`    .${cls} { animation: ${entries.join(", ")}; }`);
+            }
+            // DM-901: honor `prefers-reduced-motion: reduce` — pin everything to the
+            // NEXT state instead of animating, so the transition degrades to a
+            // cut-like reveal for motion-sensitive viewers. Slides drop to their
+            // final transform (`none` for the next copy; the prev cross-fade copy is
+            // also hidden via its fade-out below). Added / next-appearance fades snap
+            // to opacity 1; removed / prev-appearance fades snap to opacity 0. Static
+            // CSS, so output stays deterministic; rasterizers default to
+            // `no-preference` and play the full move. (DM-903: the fade rules now
+            // also matter — without pinning fade-out to 0 the prev-appearance copy
+            // would stay visible at full opacity.)
+            const reduceRules = [];
+            if (mm.slides.length > 0)
+                reduceRules.push(`${mm.slides.map((s) => `.${s.cls}`).join(", ")} { animation: none; transform: none; }`);
+            if (mm.fadeIn.length > 0)
+                reduceRules.push(`${mm.fadeIn.map((c) => `.${c}`).join(", ")} { animation: none; opacity: 1; }`);
+            if (mm.fadeOut.length > 0)
+                reduceRules.push(`${mm.fadeOut.map((c) => `.${c}`).join(", ")} { animation: none; opacity: 0; }`);
+            if (reduceRules.length > 0) {
+                keyframes.push(`
+    @media (prefers-reduced-motion: reduce) {
+      ${reduceRules.join("\n      ")}
+    }`);
+            }
+        }
         else {
             // Crossfade or cut: opacity in/out.
             //
@@ -157,7 +273,7 @@ export function generateAnimatedSvg(config) {
     .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; animation-timing-function: step-end; }`);
             }
             else {
-                const fadeInStartPct = i > 0
+                const fadeInStartPct = (i > 0 && !entersViaMagicMove)
                     ? pct(Math.max(0, timeOffset - prevTransDur), totalDuration)
                     : startPct;
                 const prevEnd = i > 0
@@ -221,6 +337,13 @@ export function generateAnimatedSvg(config) {
         const resolved = resolveCursorScript(config.cursorOverlay, totalDuration, frameStarts, config.resolveSelector ?? null);
         overlayMarkup = "\n" + cursorOverlayMarkup(resolved.positions, resolved.clicks, resolved.style, totalDuration);
     }
+    // Canvas background rect — only when a non-transparent background is given.
+    // 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)")
+        ? `  <rect width="${width}" height="${height}" fill="${bg}" />\n`
+        : "";
     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}">
   <defs>
@@ -232,8 +355,7 @@ ${config.fontFaceCss != null && config.fontFaceCss !== "" ? config.fontFaceCss +
     ${keyframes.join("\n")}${animationCss}${cullCss === "" ? "" : "\n" + cullCss}
   </style>
   <g clip-path="url(#viewport-clip)">
-  <rect width="${width}" height="${height}" fill="#0d1117" />
-${frameGroups.join("\n")}${overlayMarkup}
+${canvasBgRect}${frameGroups.join("\n")}${overlayMarkup}
   </g>
 </svg>`;
     return out;

package/dist/animation/index.d.ts

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

package/dist/animation/index.js

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

package/dist/animation/magic-move.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Magic-move transition composer — phase 1 of the Keynote-style magic-move
+ * transition (DM-898 / DM-112; spec in `docs/53-magic-move-transition.md`).
+ *
+ * Builds the "bridge" layer shown during a magic-move transition window: a
+ * single composite, rendered from the NEXT frame's element tree, in which
+ *   - elements that MOVED between the two frames (diff `translated`) slide from
+ *     their previous position to their next one,
+ *   - elements only in the NEXT frame (`added`) fade in,
+ *   - elements only in the PREV frame (`removed`) — appended from the prev tree
+ *     — fade out,
+ *   - everything else (`static` / `modified`) renders in place.
+ * At the window's start the composite matches the PREV frame's final state, and
+ * at its end the NEXT frame's initial state, so the animator hard-cuts the prev
+ * frame out at hold-end and the next frame in at the window end with no visible
+ * jump (see `generateAnimatedSvg`'s magic-move branch).
+ *
+ * Rendering happens HERE (caller-side) rather than inside the animator because
+ * the glyph/font `<defs>` are accumulated globally during rendering and emitted
+ * once by the caller BEFORE `generateAnimatedSvg` runs — re-rendering inside the
+ * animator would reference glyphs missing from the already-finalized defs. (This
+ * refines the original "animator re-renders" sketch in docs/53.)
+ *
+ * v1 scope (DM-898): translate only. Size/style morph is DM-899; `data-magic-key`
+ * author pairing is DM-900; reduced-motion + deeper nesting hardening is DM-901.
+ */
+import type { CapturedElement } from "../capture/types.js";
+/** One element that slides during the transition. The animator interpolates
+ *  `transform: <from> → <to>` over the window. A `translate(dx,dy)` for a pure
+ *  move, the full `translate · scale · translate` affine for a size change
+ *  (DM-899). The next-appearance copy goes `<prev-rect map> → none`; a prev-
+ *  appearance copy in a cross-fade pair goes `none → <next-rect map>` so both
+ *  copies trace the same prev→next path while their opacities swap (DM-903). */
+export interface MagicMoveSlide {
+    /** CSS class the renderer stamped on the element (`anim-<id>`). */
+    cls: string;
+    /** CSS transform at the window start. */
+    from: string;
+    /** CSS transform at the window end (`"none"` for the next-appearance copy). */
+    to: string;
+}
+export interface MagicMove {
+    /** Composite SVG markup shown for the transition window (no XML preamble). */
+    compositeSvg: string;
+    /** Elements that translate prev→next. */
+    slides: MagicMoveSlide[];
+    /** Classes that fade in over the window (`added`). */
+    fadeIn: string[];
+    /** Classes that fade out over the window (`removed`). */
+    fadeOut: string[];
+}
+/**
+ * Build the magic-move bridge layer between two captured trees. Returns `null`
+ * when there is nothing worth animating (no moved / added / removed elements) —
+ * the caller then falls back to `crossfade`.
+ *
+ * `render` turns a list of element roots into SVG markup (the caller passes a
+ * thin `elementTreeToSvg(roots, W, H, prefix, …)` wrapper); injecting it keeps
+ * this module renderer-agnostic and unit-testable.
+ */
+export declare function buildMagicMove(prevTree: CapturedElement | CapturedElement[], nextTree: CapturedElement | CapturedElement[], render: (roots: CapturedElement[], idPrefix: string) => string, idPrefix: string): MagicMove | null;

package/dist/animation/magic-move.js

@@ -0,0 +1,243 @@
+/**
+ * Magic-move transition composer — phase 1 of the Keynote-style magic-move
+ * transition (DM-898 / DM-112; spec in `docs/53-magic-move-transition.md`).
+ *
+ * Builds the "bridge" layer shown during a magic-move transition window: a
+ * single composite, rendered from the NEXT frame's element tree, in which
+ *   - elements that MOVED between the two frames (diff `translated`) slide from
+ *     their previous position to their next one,
+ *   - elements only in the NEXT frame (`added`) fade in,
+ *   - elements only in the PREV frame (`removed`) — appended from the prev tree
+ *     — fade out,
+ *   - everything else (`static` / `modified`) renders in place.
+ * At the window's start the composite matches the PREV frame's final state, and
+ * at its end the NEXT frame's initial state, so the animator hard-cuts the prev
+ * frame out at hold-end and the next frame in at the window end with no visible
+ * jump (see `generateAnimatedSvg`'s magic-move branch).
+ *
+ * Rendering happens HERE (caller-side) rather than inside the animator because
+ * the glyph/font `<defs>` are accumulated globally during rendering and emitted
+ * once by the caller BEFORE `generateAnimatedSvg` runs — re-rendering inside the
+ * animator would reference glyphs missing from the already-finalized defs. (This
+ * refines the original "animator re-renders" sketch in docs/53.)
+ *
+ * v1 scope (DM-898): translate only. Size/style morph is DM-899; `data-magic-key`
+ * author pairing is DM-900; reduced-motion + deeper nesting hardening is DM-901.
+ */
+import { diffTrees, entriesOfKind } from "../tree-ops/tree-diff.js";
+function asRoots(t) {
+    return Array.isArray(t) ? t : [t];
+}
+/** Resolve a tree path (`[rootIdx, childIdx, …]`, per `diffTrees`) to its element. */
+function elementAtPath(roots, path) {
+    let el = roots[path[0]];
+    for (let i = 1; i < path.length && el != null; i++)
+        el = el.children?.[path[i]];
+    return el ?? null;
+}
+/**
+ * CSS `transform` that maps an element rendered at its NEXT rect back onto its
+ * PREV rect — the window-start state the animator interpolates away to `none`.
+ * The element's painted geometry sits at next-space coordinates, so the affine
+ * is `translate(prevOrigin) · scale(prevSize/nextSize) · translate(-nextOrigin)`
+ * (prepend-translate to next origin, scale about it, then place at prev origin).
+ * Pure moves (size unchanged) collapse to a single `translate(dx, dy)` for
+ * smaller, more legible output; a zero next-dimension can't be scaled, so it
+ * also falls back to translate-only.
+ */
+function rectMapTransform(prev, next) {
+    const sizeChanged = Math.abs(prev.width - next.width) > 0.5 || Math.abs(prev.height - next.height) > 0.5;
+    if (!sizeChanged || next.width <= 0 || next.height <= 0) {
+        return `translate(${r(prev.x - next.x)}px, ${r(prev.y - next.y)}px)`;
+    }
+    const sx = prev.width / next.width;
+    const sy = prev.height / next.height;
+    return `translate(${r(prev.x)}px, ${r(prev.y)}px) scale(${r5(sx)}, ${r5(sy)}) translate(${r(-next.x)}px, ${r(-next.y)}px)`;
+}
+/** Round to 2dp (px positions) / 5dp (scale factors), trimming trailing zeros. */
+function r(n) { return Number(n.toFixed(2)); }
+function r5(n) { return Number(n.toFixed(5)); }
+/** True iff `a` is a strict prefix of `b` (i.e. `a` is an ancestor path of `b`). */
+function isAncestorPath(a, b) {
+    if (a.length >= b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Collect every element carrying a `data-magic-key` (`el.magicKey`), keyed by
+ * the attribute value, with its tree path (`[rootIdx, childIdx, …]`, matching
+ * `diffTrees`). First occurrence per key wins — a duplicate key within one
+ * frame is author error; we pair the first. (DM-900)
+ */
+function collectKeyed(roots) {
+    const out = new Map();
+    const walk = (el, path) => {
+        const k = el.magicKey;
+        if (k != null && k !== "" && !out.has(k))
+            out.set(k, { el, path });
+        const kids = el.children ?? [];
+        for (let i = 0; i < kids.length; i++)
+            walk(kids[i], [...path, i]);
+    };
+    for (let i = 0; i < roots.length; i++)
+        walk(roots[i], [i]);
+    return out;
+}
+/**
+ * True iff a matched element's PAINT changed between frames — text content or
+ * a visible style (`color` / `backgroundColor` / `borderColor` / `borderTopColor`
+ * / `opacity`). Gates the DM-903 dual-render cross-fade: geometry-only movers
+ * (same paint, just moved/resized) keep a single copy; paint-changed movers
+ * render prev + next appearances and cross-fade. The fingerprint matcher keys
+ * on (tag, text, children) not style, so a recolored-but-moved element stays
+ * `translated` — style equality has to be checked here, not read off the kind.
+ */
+function appearanceChanged(prev, next) {
+    if ((prev.text ?? "") !== (next.text ?? ""))
+        return true;
+    const p = prev.styles;
+    const q = next.styles;
+    if (p == null || q == null)
+        return false;
+    return p.color !== q.color
+        || (p.backgroundColor ?? "") !== (q.backgroundColor ?? "")
+        || (p.borderColor ?? "") !== (q.borderColor ?? "")
+        || (p.borderTopColor ?? "") !== (q.borderTopColor ?? "")
+        || p.opacity !== q.opacity;
+}
+/** True iff the two rects differ in origin or size beyond the diff tolerance. */
+function rectChanged(p, q) {
+    return Math.abs(q.x - p.x) > 0.5 || Math.abs(q.y - p.y) > 0.5
+        || Math.abs(q.width - p.width) > 0.5 || Math.abs(q.height - p.height) > 0.5;
+}
+/**
+ * Build the magic-move bridge layer between two captured trees. Returns `null`
+ * when there is nothing worth animating (no moved / added / removed elements) —
+ * the caller then falls back to `crossfade`.
+ *
+ * `render` turns a list of element roots into SVG markup (the caller passes a
+ * thin `elementTreeToSvg(roots, W, H, prefix, …)` wrapper); injecting it keeps
+ * this module renderer-agnostic and unit-testable.
+ */
+export function buildMagicMove(prevTree, nextTree, render, idPrefix) {
+    const prevRoots = asRoots(prevTree);
+    const nextRoots = asRoots(nextTree);
+    const diff = diffTrees(prevRoots, nextRoots);
+    // DM-900: author `data-magic-key` force-pairs the same logical element across
+    // frames AHEAD of the fingerprint heuristic. A key present in BOTH trees is a
+    // forced mover that supersedes whatever diffTrees decided for those elements
+    // (the heuristic may have mis-paired them, or — when their content changed —
+    // split them into add + remove, which would cross-fade instead of slide).
+    const prevKeyed = collectKeyed(prevRoots);
+    const nextKeyed = collectKeyed(nextRoots);
+    const keyedMovers = [];
+    const keyedNextPaths = new Set();
+    const keyedPrevPaths = new Set();
+    for (const [key, nx] of nextKeyed) {
+        const pv = prevKeyed.get(key);
+        if (pv == null)
+            continue; // key only in next → genuinely added; leave to heuristic
+        keyedMovers.push({ nextPath: nx.path, prev: pv.el, next: nx.el });
+        keyedNextPaths.add(nx.path.join(","));
+        keyedPrevPaths.add(pv.path.join(","));
+    }
+    // Heuristic movers: any element matched by diffTrees (static / translated /
+    // modified all carry prev + next) whose rect changed in ORIGIN or SIZE —
+    // re-derived from the rects since diffTrees keys its kind on origin only and
+    // size isn't in its fingerprint (a grow-in-place lands as `static`). Skip
+    // elements a key already claimed.
+    const heuristicMovers = entriesOfKind(diff, "static", "translated", "modified")
+        .filter((e) => e.nextPath != null && e.prev != null && e.next != null
+        && !keyedNextPaths.has(e.nextPath.join(","))
+        && rectChanged(e.prev, e.next))
+        .map((e) => ({ nextPath: e.nextPath, prev: e.prev, next: e.next }));
+    // Keyed pairs animate only when their rect actually changed (a keyed but
+    // unmoved element is just static — the key still guaranteed the pairing).
+    const allMovers = [...keyedMovers.filter((m) => rectChanged(m.prev, m.next)), ...heuristicMovers];
+    // Only animate the HIGHEST moved ancestor of each changed subtree: when a
+    // card moves/grows the diff reports every descendant as changed too, but the
+    // ancestor's transform already carries them — animating each would
+    // double-apply. Keep a mover only when no other mover is its ancestor.
+    const allMoverPaths = allMovers.map((m) => m.nextPath);
+    const rootMovers = allMovers.filter((m) => !allMoverPaths.some((p) => isAncestorPath(p, m.nextPath)));
+    // Added / removed, minus anything a key force-paired (those slide, not fade).
+    const added = entriesOfKind(diff, "added")
+        .filter((e) => e.nextPath == null || !keyedNextPaths.has(e.nextPath.join(",")));
+    const removed = entriesOfKind(diff, "removed")
+        .filter((e) => e.prevPath == null || !keyedPrevPaths.has(e.prevPath.join(",")));
+    if (rootMovers.length === 0 && added.length === 0 && removed.length === 0) {
+        return null; // nothing to magic-move → caller uses crossfade
+    }
+    // Clone the next tree so the `animId` annotations we add for the composite
+    // don't leak into the next frame's own (already-rendered / to-be-rendered)
+    // blob. CapturedElement is plain data, so structuredClone is a safe deep copy.
+    const compositeNext = nextRoots.map((r) => structuredClone(r));
+    const slides = [];
+    const fadeIn = [];
+    const fadeOut = [];
+    // Prev-appearance copies + removed subtrees, appended after the next tree so
+    // they render at their prev coordinates.
+    const extraRoots = [];
+    let n = 0;
+    for (const m of rootMovers) {
+        const el = elementAtPath(compositeNext, m.nextPath);
+        if (el == null)
+            continue;
+        const nextId = `${idPrefix}mv${n++}`;
+        el.animId = nextId;
+        // Next-appearance copy: slide from the prev rect to its final next rect.
+        slides.push({ cls: `anim-${nextId}`, from: rectMapTransform(m.prev, m.next), to: "none" });
+        // DM-903: when the element's PAINT also changed (text / color / background
+        // / border / opacity), a single next-appearance copy would snap the new
+        // look on at the window start. Render a SECOND copy at the PREV appearance,
+        // co-moving along the same prev→next path, and cross-fade — prev fades out,
+        // next fades in. Geometry-only movers keep the cheaper single copy (nothing
+        // to cross-fade). The SVG children carry baked-in fills a wrapper can't
+        // restyle, so dual-render + cross-fade is how the paint morph is expressed.
+        if (appearanceChanged(m.prev, m.next)) {
+            fadeIn.push(`anim-${nextId}`);
+            const prevClone = structuredClone(m.prev);
+            const prevId = `${nextId}p`;
+            prevClone.animId = prevId;
+            extraRoots.push(prevClone);
+            // Prev copy renders at its prev rect; map it FORWARD onto the next rect
+            // (rectMapTransform with args swapped) so it traces the same path as the
+            // next copy while fading out.
+            slides.push({ cls: `anim-${prevId}`, from: "none", to: rectMapTransform(m.next, m.prev) });
+            fadeOut.push(`anim-${prevId}`);
+        }
+    }
+    let a = 0;
+    for (const e of added) {
+        if (e.nextPath == null)
+            continue;
+        const el = elementAtPath(compositeNext, e.nextPath);
+        if (el == null)
+            continue;
+        const id = `${idPrefix}in${a++}`;
+        el.animId = id;
+        fadeIn.push(`anim-${id}`);
+    }
+    // Removed elements aren't in the next tree — append their prev subtrees (at
+    // their prev coordinates) so they render where the prev frame had them, and
+    // fade them out. Skip a removed entry nested inside another removed subtree
+    // (its ancestor already carries it).
+    const removedPaths = removed.map((e) => e.prevPath).filter((p) => p != null);
+    let o = 0;
+    for (const e of removed) {
+        if (e.prevPath == null || e.prev == null)
+            continue;
+        if (removedPaths.some((p) => isAncestorPath(p, e.prevPath)))
+            continue;
+        const clone = structuredClone(e.prev);
+        const id = `${idPrefix}out${o++}`;
+        clone.animId = id;
+        extraRoots.push(clone);
+        fadeOut.push(`anim-${id}`);
+    }
+    const compositeSvg = render([...compositeNext, ...extraRoots], idPrefix);
+    return { compositeSvg, slides, fadeIn, fadeOut };
+}