domotion-svg 0.4.2 → 0.5.0

package/README.md

@@ -59,7 +59,7 @@ 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.
 
 ### Scripting API
 

package/dist/animation/animator.d.ts

@@ -69,6 +69,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 +133,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 +187,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;

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;
@@ -74,15 +74,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,15 +103,15 @@ 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; }
@@ -191,6 +191,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;
@@ -337,6 +342,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 +352,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 +369,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 +432,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 +558,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 +591,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/animator.test.js

@@ -20,35 +20,45 @@ describe("animator", () => {
         expect(topDefs).not.toBeNull();
         expect(topDefs[0]).toContain(`id="g0"`);
     });
-    it("crossfade-only scenes route through the merge pipeline (no per-frame fv- groups)", () => {
-        // With the merge pipeline, an all-crossfade scene is reduced to a single
-        // element tree with per-element visibility timelines — NOT per-frame
-        // opacity groups. fv-N keyframes (the old model) should be absent;
-        // timeline classes (tN) should appear when frames differ.
+    it("crossfade transition composites full frames (per-frame opacity fade, not an element merge)", () => {
+        // A crossfade transition dissolves between two complete, independently
+        // z-ordered sub-SVGs. It must NOT flatten them into one deduped element
+        // tree — doing so loses per-frame stacking (a later frame's background can
+        // occlude its own foreground) and step-end-switches at the midpoint
+        // instead of fading. So a crossfade emits per-frame fv- groups with an
+        // interpolated opacity fade, and each frame's content survives intact —
+        // NOT the merge pipeline's tN timeline classes.
         const svg = generateAnimatedSvg({
             width: 100,
             height: 100,
             frames: [
                 { svgContent: `<rect fill="red" width="50" height="50"/>`, duration: 1000, transition: { type: "crossfade", duration: 200 } },
-                { svgContent: `<rect fill="blue" width="50" height="50"/>`, duration: 1000 },
+                { svgContent: `<rect fill="blue" width="50" height="50"/>`, duration: 1000, transition: { type: "crossfade", duration: 200 } },
             ],
         });
-        expect(svg).not.toMatch(/@keyframes fv-/);
-        expect(svg).toMatch(/@keyframes t\d+/);
+        expect(svg).toMatch(/@keyframes fv-/);
+        expect(svg).not.toMatch(/@keyframes t\d+/);
+        expect(svg).toContain(`<rect fill="red" width="50" height="50"/>`);
+        expect(svg).toContain(`<rect fill="blue" width="50" height="50"/>`);
         expect(svg).toContain("--scene-dur");
     });
-    it("crossfade: identical content across frames is rendered once", () => {
-        // Regression test for SK-662 — stable elements should not be re-drawn per
-        // frame. Two frames with the same <rect> should produce exactly one <rect>.
+    it("cut: composites each frame as a complete sub-SVG (DM-865 — no element merge)", () => {
+        // DM-865: the element-merge fast path is gone — cut composites each frame
+        // like crossfade. So identical content across frames is emitted once PER
+        // frame (not deduped into one), gated by per-frame fv-N opacity. The merge
+        // mis-rendered near-identical (continuous-session) frames; compositing
+        // keeps each frame's layout intact.
         const svg = generateAnimatedSvg({
             width: 100,
             height: 100,
             frames: [
-                { svgContent: `<rect width="50" height="50" fill="green"/>`, duration: 500, transition: { type: "crossfade", duration: 100 } },
-                { svgContent: `<rect width="50" height="50" fill="green"/>`, duration: 500 },
+                { svgContent: `<rect width="50" height="50" fill="green"/>`, duration: 500, transition: { type: "cut", duration: 0 } },
+                { svgContent: `<rect width="50" height="50" fill="green"/>`, duration: 500, transition: { type: "cut", duration: 0 } },
             ],
         });
-        expect((svg.match(/<rect width="50" height="50" fill="green"\/>/g) ?? []).length).toBe(1);
+        expect((svg.match(/<rect width="50" height="50" fill="green"\/>/g) ?? []).length).toBe(2);
+        expect(svg).toMatch(/@keyframes fv-/);
+        expect(svg).not.toMatch(/@keyframes t\d+\s*{/);
     });
     it("DM-609: scroll transition is now a vertical push (translateY), not opacity-only", () => {
         // The `scroll` transition used to be opacity-only (a misnomer). Per
@@ -105,7 +115,7 @@ describe("animator", () => {
         const bDur = b.match(/--scene-dur:\s*([0-9.]+)s/)?.[1];
         expect(aDur).toBe(bDur);
     });
-    it("cut transition: routes through the merge fast path (no fv-N groups)", () => {
+    it("cut transition: composites with per-frame fv-N groups (DM-865 — no element merge)", () => {
         const svg = generateAnimatedSvg({
             width: 100, height: 100,
             frames: [
@@ -114,8 +124,9 @@ describe("animator", () => {
                 { svgContent: `<rect fill="green" width="50" height="50"/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
             ],
         });
-        expect(svg).not.toMatch(/@keyframes fv-/);
-        expect(svg).toMatch(/@keyframes t\d+/);
+        expect(svg).toMatch(/@keyframes fv-/);
+        expect(svg).not.toMatch(/@keyframes t\d+\s*{/);
+        expect((svg.match(/class="f f-\d+"/g) ?? []).length).toBe(3);
         // 3 frames × 1000ms hold + 3 × 0ms cut transitions = 3000ms total.
         expect(svg).toMatch(/--scene-dur:\s*3\.00s/);
     });
@@ -152,6 +163,69 @@ describe("animator", () => {
         // Timing function passes through.
         expect(svg).toContain("ease-out");
     });
+    it("DM-869: repeating animation loops on its own clock with iteration-count + alternate", () => {
+        const svg = generateAnimatedSvg({
+            width: 100,
+            height: 100,
+            frames: [
+                {
+                    svgContent: `<rect class="anim-caret"/>`,
+                    duration: 2000,
+                    animations: [{ animId: "caret", property: "opacity", from: "1", to: "0", duration: 530, repeat: "infinite", alternate: true }],
+                },
+            ],
+        });
+        // Loops on its own 530ms clock, infinite + alternating — NOT the global scene clock.
+        expect(svg).toMatch(/\.anim-caret\s*{[^}]*animation:\s*f0-caret-0\s+530ms\s+infinite\s+alternate/);
+        // Simple two-stop from→to cycle (no 4-stop global-clock hold).
+        expect(svg).toMatch(/@keyframes f0-caret-0\s*{\s*0%\s*{\s*opacity:\s*1;\s*}\s*100%\s*{\s*opacity:\s*0;\s*}\s*}/);
+    });
+    it("DM-869: finite repeat emits the count and (without alternate) no direction", () => {
+        const svg = generateAnimatedSvg({
+            width: 100,
+            height: 100,
+            frames: [
+                {
+                    svgContent: `<rect class="anim-p"/>`,
+                    duration: 2000,
+                    animations: [{ animId: "p", property: "opacity", from: "1", to: "0.3", duration: 400, repeat: 3 }],
+                },
+            ],
+        });
+        expect(svg).toMatch(/\.anim-p\s*{[^}]*animation:\s*f0-p-0\s+400ms\s+3\s*;/);
+        expect(svg).not.toContain("alternate");
+    });
+    it("DM-870: typing-overlay caret emits a position-tracked, step-end blinking bar", () => {
+        const svg = generateAnimatedSvg({
+            width: 200,
+            height: 80,
+            frames: [{ svgContent: `<rect/>`, duration: 3000, overlays: [{ kind: "typing", text: "hi there", x: 10, y: 40, caret: true }] }],
+        });
+        expect(svg).toContain(`class="t0-caret"`);
+        expect(svg).toMatch(/@keyframes t0-caret-pos/);
+        expect(svg).toMatch(/@keyframes t0-caret-blink/);
+        // Position track is linear; the blink toggles with step-end (hard on/off).
+        expect(svg).toMatch(/\.t0-caret\s*{[^}]*linear[^}]*step-end/);
+    });
+    it("DM-870: typing overlay without the caret option emits no caret", () => {
+        const svg = generateAnimatedSvg({
+            width: 200,
+            height: 80,
+            frames: [{ svgContent: `<rect/>`, duration: 3000, overlays: [{ kind: "typing", text: "hi", x: 10, y: 40 }] }],
+        });
+        expect(svg).not.toContain("-caret");
+    });
+    it("DM-871: blink overlay emits a step-end toggling rect", () => {
+        const svg = generateAnimatedSvg({
+            width: 100,
+            height: 100,
+            frames: [{ svgContent: `<rect/>`, duration: 2000, overlays: [{ kind: "blink", x: 10, y: 10, width: 12, height: 12, periodMs: 800, color: "#ef4444", radius: 6 }] }],
+        });
+        expect(svg).toMatch(/<rect class="blink0"[^>]*fill="#ef4444"/);
+        expect(svg).toContain('rx="6"');
+        expect(svg).toMatch(/@keyframes blink0/);
+        expect(svg).toMatch(/\.blink0\s*{[^}]*step-end/);
+    });
     it("intra-frame animation: translateY desugars to transform: translateY()", () => {
         const svg = generateAnimatedSvg({
             width: 100, height: 100,
@@ -228,23 +302,21 @@ describe("animator", () => {
         // The "cut" frame uses ONLY fv-1 (no fd-1 — it's folded in).
         expect(svg).not.toMatch(/@keyframes fd-1\s*{/);
     });
-    it("DM-599/DM-641: merged-path keyframes emit visibility alongside opacity", () => {
-        // Two crossfade frames with different content route through the merge
-        // pipeline. Per-element visibility classes (tN) now toggle BOTH opacity
-        // and visibility so the browser can skip painting hidden elements.
+    it("DM-599/DM-641: cut fv-N keyframes emit visibility alongside opacity", () => {
+        // Cut composites (DM-865); its fv-N keyframes flip BOTH opacity and
+        // visibility at the frame boundary (step-end) so the browser can skip
+        // painting a frame that's off screen.
         const svg = generateAnimatedSvg({
             width: 100, height: 100,
             frames: [
                 { svgContent: `<rect fill="red" width="50" height="50"/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
-                { svgContent: `<rect fill="blue" width="50" height="50"/>`, duration: 1000 },
+                { svgContent: `<rect fill="blue" width="50" height="50"/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
             ],
         });
-        // Each tN keyframe stop with opacity:1 also has visibility:visible; each
-        // opacity:0 stop has visibility:hidden.
-        const tN = svg.match(/@keyframes t\d+\s*{[\s\S]*?\n\s*}/);
-        expect(tN).not.toBeNull();
-        expect(tN[0]).toMatch(/opacity:\s*1;\s*visibility:\s*visible/);
-        expect(tN[0]).toMatch(/opacity:\s*0;\s*visibility:\s*hidden/);
+        const fv = svg.match(/@keyframes fv-\d+\s*{[\s\S]*?\n\s*}/);
+        expect(fv).not.toBeNull();
+        expect(fv[0]).toMatch(/opacity:\s*1;\s*visibility:\s*visible/);
+        expect(fv[0]).toMatch(/opacity:\s*0;\s*visibility:\s*hidden/);
     });
     it("DM-641: never emits `display: none` keyframes (would park Chromium's animation engine)", () => {
         // Regression. The repro from the ticket: a multi-frame animation with

package/dist/capture/script/index.js

@@ -1512,7 +1512,15 @@ export const captureScript = (args) => {
         || (parseFloat(rootCs.borderBottomWidth) || 0) > 0
         || (parseFloat(rootCs.borderLeftWidth) || 0) > 0;
     const rootBg = rootCs.backgroundColor;
-    const rootHasBg = rootBg != null && rootBg !== 'rgba(0, 0, 0, 0)' && rootBg !== 'transparent';
+    // DM-855: also capture the root when it carries a gradient/image background,
+    // not just a solid color. `backgroundColor` is `transparent` for a
+    // gradient-only <body>, so checking it alone made us skip capturing the root
+    // element and drop its background entirely. Treating a non-`none`
+    // `background-image` as "has background" captures the root as a normal
+    // element, routing its gradient through the existing element-gradient path.
+    const rootBgImage = rootCs.backgroundImage;
+    const rootHasBgImage = rootBgImage != null && rootBgImage !== 'none' && rootBgImage !== '';
+    const rootHasBg = (rootBg != null && rootBg !== 'rgba(0, 0, 0, 0)' && rootBg !== 'transparent') || rootHasBgImage;
     // DM-365: invalid HTML like <p>foo<div>bar</div>baz</p> auto-closes the <p>
     // when the <div> opens, leaving "baz" as a direct text-node child of <body>.
     // Chrome paints it; we'd miss it if we only walked root.children (Element