domotion-svg 0.4.2 → 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
 
@@ -59,21 +64,46 @@ For a multi-frame animated SVG, write a small JSON config and run `domotion anim
 domotion animate ./demo.json
 ```
 
-The config describes each frame (input URL or HTML file, duration, transition, optional pre-capture actions like `click` / `fill` / `scroll` / `hover`). See `domotion --help` for the full grammar and the [Quick start](https://brianwestphal.github.io/domotion/start/quickstart/) for a walkthrough.
+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[];
     /**
@@ -69,6 +85,17 @@ export interface TypingOverlay {
      * sits on a clean background.
      */
     bgHeight?: number;
+    /**
+     * DM-870: render a blinking insertion caret. The bar sweeps the type
+     * position while typing, then parks at the end of the text and blinks
+     * (opacity 1↔0) until the frame ends. `true` uses defaults (the typing
+     * `color`, 2px wide, ~530ms cadence); an object overrides them.
+     */
+    caret?: boolean | {
+        color?: string;
+        width?: number;
+        blinkMs?: number;
+    };
 }
 export interface TapOverlay {
     kind: "tap";
@@ -122,7 +149,29 @@ export interface SvgOverlay {
         delay?: number;
     };
 }
-export type AnimationOverlay = TypingOverlay | TapOverlay | SvgOverlay;
+/**
+ * DM-871: a standalone blinking bar/box, for carets/dots not tied to a typing
+ * overlay — a recording dot, an attention pulse on a focused field, a cursor.
+ * Renders a rect that toggles opacity on a `periodMs` cycle for the frame's
+ * hold (sugar over a rect + a repeating opacity animation).
+ */
+export interface BlinkOverlay {
+    kind: "blink";
+    /** Top-left corner in the captured frame's coordinate space. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Full on/off cycle in ms (default 1000). */
+    periodMs?: number;
+    /** Fill color (default a light gray). */
+    color?: string;
+    /** Corner radius — set to half the width/height for a dot. */
+    radius?: number;
+    /** Ms after the frame becomes visible before blinking starts. Default 0. */
+    delay?: number;
+}
+export type AnimationOverlay = TypingOverlay | TapOverlay | SvgOverlay | BlinkOverlay;
 /**
  * Animate a CSS property on captured elements that match a selector, while
  * the frame is held on screen. The selector is resolved against the source
@@ -154,6 +203,17 @@ export interface IntraFrameAnimation {
     easing?: string;
     /** Ms after the frame becomes visible before animation starts. Default 0. */
     delay?: number;
+    /**
+     * DM-869: repeat count. A positive integer or `"infinite"`. When set, the
+     * animation loops on its own `duration` clock (CSS `animation-iteration-count`)
+     * rather than playing once — turning a property animation into a blink / pulse
+     * / breathe. The loop is only visible while the frame is on screen (the frame
+     * group's visibility gating). `"infinite"` is the robust choice for a looping
+     * scene; a finite count aligns to the frame's first appearance.
+     */
+    repeat?: number | "infinite";
+    /** DM-869: when true, the loop ping-pongs `from`→`to`→`from` (CSS `animation-direction: alternate`). */
+    alternate?: boolean;
 }
 export interface AnimationConfig {
     width: number;
@@ -184,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

@@ -4,7 +4,6 @@
  * Takes captured SVG frame content and composes them into a single
  * animated SVG with CSS keyframe transitions.
  */
-import { mergeFrames } from "../tree-ops/frame-merge.js";
 import { cursorOverlayMarkup, resolveCursorScript } from "./cursor-overlay.js";
 export function generateAnimatedSvg(config) {
     const { width, height, frames } = config;
@@ -25,19 +24,20 @@ export function generateAnimatedSvg(config) {
             t += f.duration + td;
         }
     }
-    // Fast path: if every transition is crossfade (or default) or `cut`, merge
-    // all frames into a single de-duplicated tree with per-element visibility
-    // timelines. `cut` is just `crossfade` with duration 0 — same merge logic
-    // applies; it ends up as step-end keyframes flipping at exact frame
-    // boundaries.
-    const allMergeable = frames.every((f) => {
-        const type = f.transition?.type;
-        return type == null || type === "crossfade" || type === "cut";
-    });
-    const anyOverlays = frames.some((f) => f.overlays != null && f.overlays.length > 0);
-    if (allMergeable && frames.length > 1 && !anyOverlays) {
-        return composeMergedSvg(config, frameTiming, totalSec);
-    }
+    // Every sequence composites: each frame is emitted as a complete, internally
+    // z-ordered `<g class="f f-N">` sub-SVG and switched/faded by opacity.
+    //
+    // There used to be an element-merge fast path (`mergeFrames`) for cut-only
+    // sequences that flattened all frames into one de-duplicated tree to save
+    // bytes. DM-854 took crossfade off it (it dropped per-frame z-order and
+    // step-end-switched instead of fading); DM-865 then showed it also mis-renders
+    // *near-identical* frames — the same DOM evolved across frames, as produced by
+    // continuous-session capture — because differing text in a shared element slot
+    // can't be gated per frame (a bare text node carries no class, and a `<tspan>`
+    // with `visibility:hidden` still advances layout, shifting the surviving
+    // glyph). Compositing has neither problem. The dedup size win can be recovered
+    // later as `<defs>`/symbol-level glyph sharing across intact frame groups,
+    // which preserves each frame's layout (tracked with DM-854/DM-865).
     const frameGroups = [];
     const keyframes = [];
     let timeOffset = 0;
@@ -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`
@@ -74,15 +79,15 @@ export function generateAnimatedSvg(config) {
             keyframes.push(`
     @keyframes fp-${i} {
       0%, ${Math.max(0, parseFloat(enterStartPct) - 0.1).toFixed(2)}% { transform: translateX(${entersViaPush ? width : 0}px); }
-      ${startPct}% { transform: translateX(0); }
-      ${holdEndPct}% { transform: translateX(0); }
-      ${transEndPct}% { transform: translateX(-${width}px); }
+      ${startPct} { transform: translateX(0); }
+      ${holdEndPct} { transform: translateX(0); }
+      ${transEndPct} { transform: translateX(-${width}px); }
       ${Math.min(100, parseFloat(transEndPct) + 0.1).toFixed(2)}%, 100% { transform: translateX(-${width}px); }
     }
     @keyframes fv-${i} {
       0%, ${Math.max(0, parseFloat(enterStartPct) - 0.1).toFixed(2)}% { opacity: 0; }
-      ${enterStartPct}% { opacity: 1; }
-      ${transEndPct}% { opacity: 1; }
+      ${enterStartPct} { opacity: 1; }
+      ${transEndPct} { opacity: 1; }
       ${Math.min(100, parseFloat(transEndPct) + 0.1).toFixed(2)}%, 100% { opacity: 0; }
     }${buildDisplayKeyframes(`fd-${i}`, visStart, visEnd)}
     .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }
@@ -103,20 +108,131 @@ export function generateAnimatedSvg(config) {
             keyframes.push(`
     @keyframes fp-${i} {
       0%, ${Math.max(0, parseFloat(enterStartPct) - 0.1).toFixed(2)}% { transform: translateY(${entersViaScroll ? height : 0}px); }
-      ${startPct}% { transform: translateY(0); }
-      ${holdEndPct}% { transform: translateY(0); }
-      ${transEndPct}% { transform: translateY(-${height}px); }
+      ${startPct} { transform: translateY(0); }
+      ${holdEndPct} { transform: translateY(0); }
+      ${transEndPct} { transform: translateY(-${height}px); }
       ${Math.min(100, parseFloat(transEndPct) + 0.1).toFixed(2)}%, 100% { transform: translateY(-${height}px); }
     }
     @keyframes fv-${i} {
       0%, ${Math.max(0, parseFloat(enterStartPct) - 0.1).toFixed(2)}% { opacity: 0; }
-      ${enterStartPct}% { opacity: 1; }
-      ${transEndPct}% { opacity: 1; }
+      ${enterStartPct} { opacity: 1; }
+      ${transEndPct} { opacity: 1; }
       ${Math.min(100, parseFloat(transEndPct) + 0.1).toFixed(2)}%, 100% { opacity: 0; }
     }${buildDisplayKeyframes(`fd-${i}`, visStart, visEnd)}
     .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }
     .fp-${i} { animation: fp-${i} ${totalSec.toFixed(2)}s infinite; }`);
         }
+        else 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
@@ -191,6 +307,11 @@ export function generateAnimatedSvg(config) {
                     frameGroups.push(svgMarkup);
                     keyframes.push(css);
                 }
+                else if (overlay.kind === "blink") {
+                    const { svgMarkup, css } = renderBlinkOverlay(overlay, i, timeOffset, timeOffset + frame.duration, totalDuration, totalSec);
+                    frameGroups.push(svgMarkup);
+                    keyframes.push(css);
+                }
             }
         }
         timeOffset += frame.duration + transDur;
@@ -216,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>
@@ -227,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;
@@ -337,6 +464,8 @@ function renderTypingOverlay(overlay, frameIdx, frameStart, frameEnd, totalDurat
     // width-growing clip during the slice of the type timeline when that line's
     // characters are typed (line N starts after line N-1 finishes), so the caret
     // advances down the field exactly as it would in the browser.
+    // DM-870: per-line type timing, collected for the optional caret below.
+    const lineTimings = [];
     let cumChars = 0;
     lines.forEach((line, li) => {
         const lineY = overlay.y + li * lineHeight;
@@ -345,8 +474,11 @@ function renderTypingOverlay(overlay, frameIdx, frameStart, frameEnd, totalDurat
         // is where the caret would sit just after the typed character anyway.
         const lineWidth = line.length * charWidth + charWidth;
         const clipId = `${id}-clip${li}`;
-        const lineStartPct = pct(typeStartMs + (cumChars / visibleChars) * effTypeDur, totalDuration);
-        const lineEndPct = pct(typeStartMs + ((cumChars + line.length) / visibleChars) * effTypeDur, totalDuration);
+        const lineStartMs = typeStartMs + (cumChars / visibleChars) * effTypeDur;
+        const lineEndMs = typeStartMs + ((cumChars + line.length) / visibleChars) * effTypeDur;
+        const lineStartPct = pct(lineStartMs, totalDuration);
+        const lineEndPct = pct(lineEndMs, totalDuration);
+        lineTimings.push({ li, startMs: lineStartMs, endMs: lineEndMs, len: line.length });
         cumChars += line.length;
         parts.push(`  <defs><clipPath id="${clipId}"><rect class="${id}-rev${li}" x="${overlay.x}" y="${lineY - fontSize}" width="0" height="${textHeight}" /></clipPath></defs>`);
         parts.push(`  <text class="${id}-text" x="${overlay.x}" y="${lineY}" fill="${color}" font-size="${fontSize}" font-family="'SF Mono', Menlo, Monaco, monospace" clip-path="url(#${clipId})">${escapeXml(line)}</text>`);
@@ -359,6 +491,48 @@ function renderTypingOverlay(overlay, frameIdx, frameStart, frameEnd, totalDurat
     cssRules.push(`
     @keyframes ${id}-vis { 0%, ${typeStartPct} { opacity: 0; } ${pct(typeStartMs + 30, totalDuration)} { opacity: 1; } ${holdEndPct} { opacity: 1; } ${disappearPct}, 100% { opacity: 0; } }
     .${id}-text { animation: ${id}-vis ${totalSec.toFixed(2)}s infinite; }`);
+    // DM-870: blinking insertion caret. Sweeps the type position while typing
+    // (one linear translate segment per wrapped line, jumping to the next line's
+    // start), then parks at the end of the last line and blinks (step-end opacity
+    // toggle) until the overlay disappears. Two animations on one rect: a linear
+    // position track + a step-end opacity blink.
+    if (overlay.caret != null && overlay.caret !== false && lineTimings.length > 0) {
+        const caretOpts = typeof overlay.caret === "object" ? overlay.caret : {};
+        const caretColor = caretOpts.color ?? color;
+        const caretW = caretOpts.width ?? 2;
+        const blinkMs = caretOpts.blinkMs ?? 530;
+        const last = lineTimings[lineTimings.length - 1];
+        const endX = last.len * charWidth;
+        const endY = last.li * lineHeight;
+        // Position track: hold at line 0 start until typing begins, then sweep each
+        // line, then hold at the text end through the blink + disappear.
+        const posStops = [`0%, ${typeStartPct} { transform: translate(0px, 0px); }`];
+        for (const lt of lineTimings) {
+            posStops.push(`${pct(lt.startMs, totalDuration)} { transform: translate(0px, ${lt.li * lineHeight}px); }`);
+            posStops.push(`${pct(lt.endMs, totalDuration)} { transform: translate(${lt.len * charWidth}px, ${lt.li * lineHeight}px); }`);
+        }
+        posStops.push(`${holdEndPct}, 100% { transform: translate(${endX}px, ${endY}px); }`);
+        // Blink: invisible until typing starts, solid through typing, then toggle
+        // on/off every half-period until the overlay disappears.
+        const blinkStops = [
+            `0%, ${typeStartPct} { opacity: 0; }`,
+            `${pct(typeStartMs + 30, totalDuration)} { opacity: 1; }`,
+            `${pct(textEndMs, totalDuration)} { opacity: 1; }`,
+        ];
+        let t = textEndMs + blinkMs / 2;
+        let on = false;
+        while (t < holdEndMs) {
+            blinkStops.push(`${pct(t, totalDuration)} { opacity: ${on ? 1 : 0}; }`);
+            t += blinkMs / 2;
+            on = !on;
+        }
+        blinkStops.push(`${disappearPct}, 100% { opacity: 0; }`);
+        parts.push(`  <rect class="${id}-caret" x="${overlay.x}" y="${overlay.y - fontSize + 2}" width="${caretW}" height="${fontSize}" fill="${caretColor}" />`);
+        cssRules.push(`
+    @keyframes ${id}-caret-pos { ${posStops.join(" ")} }
+    @keyframes ${id}-caret-blink { ${blinkStops.join(" ")} }
+    .${id}-caret { animation: ${id}-caret-pos ${totalSec.toFixed(2)}s linear infinite, ${id}-caret-blink ${totalSec.toFixed(2)}s step-end infinite; }`);
+    }
     return { svgMarkup: parts.join("\n"), css: cssRules.join("") };
 }
 function renderTapOverlay(overlay, frameIdx, frameStart, totalDuration, totalSec) {
@@ -380,6 +554,29 @@ function renderTapOverlay(overlay, frameIdx, frameStart, totalDuration, totalSec
     .${id}-dot { animation: ${id}-dot ${totalSec.toFixed(2)}s infinite; }`;
     return { svgMarkup, css };
 }
+function renderBlinkOverlay(overlay, frameIdx, frameStart, frameEnd, totalDuration, totalSec) {
+    const id = `blink${frameIdx}`;
+    const period = overlay.periodMs ?? 1000;
+    const color = overlay.color ?? "#e6edf3";
+    const startMs = frameStart + (overlay.delay ?? 0);
+    const radiusAttr = overlay.radius != null ? ` rx="${overlay.radius}" ry="${overlay.radius}"` : "";
+    // Toggle opacity on/off every half-period across the frame's hold, then off.
+    // step-end keeps each state until the next stop (a hard blink, not a fade).
+    const stops = [`0%, ${pct(startMs, totalDuration)} { opacity: 0; }`];
+    let t = startMs;
+    let on = true;
+    while (t < frameEnd) {
+        stops.push(`${pct(t, totalDuration)} { opacity: ${on ? 1 : 0}; }`);
+        t += period / 2;
+        on = !on;
+    }
+    stops.push(`${pct(frameEnd, totalDuration)}, 100% { opacity: 0; }`);
+    const svgMarkup = `  <rect class="${id}" x="${overlay.x}" y="${overlay.y}" width="${overlay.width}" height="${overlay.height}"${radiusAttr} fill="${color}" />`;
+    const css = `
+    @keyframes ${id} { ${stops.join(" ")} }
+    .${id} { animation: ${id} ${totalSec.toFixed(2)}s step-end infinite; }`;
+    return { svgMarkup, css };
+}
 function pct(ms, total) {
     return `${((ms / total) * 100).toFixed(2)}%`;
 }
@@ -483,50 +680,6 @@ function offsetForDirection(dir, w, h, _outFrom) {
         return `translate(-${w}px, 0)`;
     return `translate(${w}px, 0)`; // right
 }
-/**
- * Compose the animated SVG using the frame-merge pipeline. Every element in
- * every frame is reduced to one render with a visibility timeline. Stable
- * elements (prompt, background, typed characters that stay on screen) emit
- * once with opacity: 1 throughout; changing elements get step-end keyframes
- * that flip their opacity at the appropriate frame boundaries.
- */
-function composeMergedSvg(config, frameTiming, totalSec) {
-    const { width, height, frames } = config;
-    const framesSvg = frames.map((f) => f.svgContent);
-    const { css, merged } = mergeFrames(framesSvg, frameTiming, "t");
-    const sharedDefsMarkup = config.sharedDefs ?? "";
-    const animationCss = buildIntraFrameAnimationCss(frames, frameTiming, totalSec);
-    // DM-603: viewBox-cull keyframes from each frame's pre-pass (see unmerged path).
-    const cullCss = frames.map((f) => f.cullCss ?? "").filter((s) => s !== "").join("\n");
-    // Cursor overlay (DM-277). Same emission as the unmerged path — the
-    // overlay sits above the merged frame group, clipped to the viewport.
-    const totalDuration = totalSec * 1000;
-    let overlayMarkup = "";
-    if (config.cursorOverlay != null && config.cursorOverlay.events.length > 0) {
-        const frameStarts = [];
-        let acc = 0;
-        for (const f of frames) {
-            frameStarts.push(acc);
-            acc += f.duration + transitionDuration(f);
-        }
-        const resolved = resolveCursorScript(config.cursorOverlay, totalDuration, frameStarts, config.resolveSelector ?? null);
-        overlayMarkup = "\n" + cursorOverlayMarkup(resolved.positions, resolved.clicks, resolved.style, totalDuration);
-    }
-    return `<?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>
-    <clipPath id="viewport-clip"><rect width="${width}" height="${height}" /></clipPath>${sharedDefsMarkup}
-  </defs>
-  <style>
-${config.fontFaceCss != null && config.fontFaceCss !== "" ? config.fontFaceCss + "\n" : ""}    :root { --scene-dur: ${totalSec.toFixed(2)}s; }
-${css}${animationCss}${cullCss === "" ? "" : "\n" + cullCss}
-  </style>
-  <g clip-path="url(#viewport-clip)">
-  <rect width="${width}" height="${height}" fill="#0d1117" />
-${merged}${overlayMarkup}
-  </g>
-</svg>`;
-}
 /**
  * Compile each frame's intra-frame animations into CSS. Each animation gets
  * a uniquely-named keyframe block whose timing is mapped onto the global
@@ -560,15 +713,33 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
                 return `${a.property}: ${val};`;
             };
             const animName = `f${i}-${a.animId}-${ai}`;
-            // Hold `from` until startPct, animate from→to during [startPct, endPct],
-            // hold `to` afterwards. Pre-frame holds use 0% as the from anchor.
-            out.push(`    @keyframes ${animName} {
+            if (a.repeat != null) {
+                // DM-869: repeating animation (blink / pulse / breathe). The keyframe is
+                // a single from→to cycle on the animation's own `duration` clock, looped
+                // via animation-iteration-count + (optional) direction:alternate. The
+                // loop is only visible while the frame is on screen (the frame group's
+                // visibility gating); `animation-delay` aligns the first cycle to the
+                // frame's appearance. `fill-mode: both` holds `from` before the delay.
+                const iterations = a.repeat === "infinite" ? "infinite" : String(a.repeat);
+                const direction = a.alternate === true ? " alternate" : "";
+                out.push(`    @keyframes ${animName} {
+      0% { ${propValue(a.from)} }
+      100% { ${propValue(a.to)} }
+    }
+    .anim-${a.animId} { animation: ${animName} ${a.duration}ms ${iterations}${direction}; animation-timing-function: ${easing}; animation-delay: ${startMs.toFixed(0)}ms; animation-fill-mode: both; }`);
+            }
+            else {
+                // One-shot: hold `from` until startPct, animate from→to during
+                // [startPct, endPct], hold `to` afterwards, mapped onto the global scene
+                // clock so it replays in sync each scene loop.
+                out.push(`    @keyframes ${animName} {
       0% { ${propValue(a.from)} }
       ${startPct.toFixed(3)}% { ${propValue(a.from)} }
       ${endPct.toFixed(3)}% { ${propValue(a.to)} }
       100% { ${propValue(a.to)} }
     }
     .anim-${a.animId} { animation: ${animName} ${totalSec.toFixed(2)}s infinite; animation-timing-function: ${easing}; }`);
+            }
         }
     }
     return out.length === 0 ? "" : "\n" + out.join("\n");

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";