domotion-svg 0.1.1

package/dist/animator.js

@@ -0,0 +1,424 @@
+/**
+ * SVG Animation Composer
+ *
+ * Takes captured SVG frame content and composes them into a single
+ * animated SVG with CSS keyframe transitions.
+ */
+import { mergeFrames } from "./frame-merge.js";
+import { cursorOverlayMarkup, resolveCursorScript } from "./cursor-overlay.js";
+export function generateAnimatedSvg(config) {
+    const { width, height, frames } = config;
+    const totalDuration = frames.reduce((sum, f) => sum + f.duration + transitionDuration(f), 0);
+    const totalSec = totalDuration / 1000;
+    // Pre-compute per-frame timing windows (used by both the merge pipeline for
+    // timeline keyframes and the atomic push/scroll fallbacks below).
+    const frameTiming = {
+        startPct: [], holdEndPct: [], transEndPct: [],
+    };
+    {
+        let t = 0;
+        for (const f of frames) {
+            const td = transitionDuration(f);
+            frameTiming.startPct.push((t / totalDuration) * 100);
+            frameTiming.holdEndPct.push(((t + f.duration) / totalDuration) * 100);
+            frameTiming.transEndPct.push(((t + f.duration + td) / totalDuration) * 100);
+            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);
+    }
+    const frameGroups = [];
+    const keyframes = [];
+    let timeOffset = 0;
+    for (let i = 0; i < frames.length; i++) {
+        const frame = frames[i];
+        const transDur = transitionDuration(frame);
+        const transType = frame.transition?.type ?? "crossfade";
+        const startPct = pct(timeOffset, totalDuration);
+        const holdEndPct = pct(timeOffset + frame.duration, totalDuration);
+        const transEndPct = pct(timeOffset + frame.duration + transDur, totalDuration);
+        const prevFrame = i > 0 ? frames[i - 1] : null;
+        const entersViaPush = prevFrame?.transition?.type === "push-left";
+        const prevTransDur = prevFrame != null ? transitionDuration(prevFrame) : 300;
+        const enterStartPct = entersViaPush
+            ? pct(timeOffset - prevTransDur, totalDuration)
+            : startPct;
+        if (transType === "push-left") {
+            // Push: slide in from right, slide out to left
+            frameGroups.push(`  <g class="f f-${i}"><clipPath id="fc-${i}"><rect width="${width}" height="${height}" /></clipPath><g clip-path="url(#fc-${i})" class="fp fp-${i}">\n${frame.svgContent}\n  </g></g>`);
+            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); }
+      ${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; }
+      ${Math.min(100, parseFloat(transEndPct) + 0.1).toFixed(2)}%, 100% { opacity: 0; }
+    }
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; }
+    .fp-${i} { animation: fp-${i} ${totalSec.toFixed(2)}s infinite; }`);
+        }
+        else if (transType === "scroll") {
+            // Scroll: keep visible, no fade during scroll, fade only at end
+            frameGroups.push(`  <g class="f f-${i}">\n${frame.svgContent}\n  </g>`);
+            const fadeEndPct = pct(timeOffset + frame.duration + transDur + 200, totalDuration);
+            const prevEnd = i > 0 ? `${Math.max(0, parseFloat(startPct) - 0.1).toFixed(2)}%,` : "";
+            keyframes.push(`
+    @keyframes fv-${i} {
+      0%, ${prevEnd} ${fadeEndPct}, 100% { opacity: 0; }
+      ${startPct}, ${transEndPct} { opacity: 1; }
+    }
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; }`);
+        }
+        else {
+            // Crossfade or cut: opacity in/out.
+            //
+            // For `cut` (transDur === 0): use disjoint keyframes with step-end timing
+            // so opacity flips instantly at frame boundaries with no interpolation
+            // smear — frame N is opaque from startPct to transEndPct EXCLUSIVE, and
+            // 0 outside. Without step-end, linear interpolation between distant
+            // keyframes makes adjacent frames bleed across the entire cycle.
+            //
+            // For crossfade: the fade-in OVERLAPS the previous frame's fade-out so
+            // shared pixels stay visible during the transition. Linear interpolation
+            // is what we want here.
+            frameGroups.push(`  <g class="f f-${i}">\n${frame.svgContent}\n  </g>`);
+            const isCut = transType === "cut" || transDur === 0;
+            if (isCut) {
+                const startNum = parseFloat(startPct);
+                const endNum = parseFloat(transEndPct);
+                const beforeStart = Math.max(0, startNum - 0.001).toFixed(3);
+                const afterEnd = Math.min(100, endNum + 0.001).toFixed(3);
+                keyframes.push(`
+    @keyframes fv-${i} {
+      0% { opacity: 0; }
+      ${beforeStart}% { opacity: 0; }
+      ${startNum.toFixed(3)}% { opacity: 1; }
+      ${endNum.toFixed(3)}% { opacity: 1; }
+      ${afterEnd}% { opacity: 0; }
+      100% { opacity: 0; }
+    }
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; animation-timing-function: step-end; }`);
+            }
+            else {
+                const fadeInStartPct = i > 0
+                    ? pct(Math.max(0, timeOffset - prevTransDur), totalDuration)
+                    : startPct;
+                const prevEnd = i > 0
+                    ? `${Math.max(0, parseFloat(fadeInStartPct) - 0.01).toFixed(2)}%,`
+                    : "";
+                keyframes.push(`
+    @keyframes fv-${i} {
+      0%, ${prevEnd} ${transEndPct}, 100% { opacity: 0; }
+      ${startPct}, ${holdEndPct} { opacity: 1; }
+    }
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; }`);
+            }
+        }
+        // Overlays
+        if (frame.overlays != null) {
+            for (const overlay of frame.overlays) {
+                if (overlay.kind === "typing") {
+                    const { svgMarkup, css } = renderTypingOverlay(overlay, i, timeOffset, timeOffset + frame.duration, totalDuration, totalSec);
+                    frameGroups.push(svgMarkup);
+                    keyframes.push(css);
+                }
+                else if (overlay.kind === "tap") {
+                    const { svgMarkup, css } = renderTapOverlay(overlay, i, timeOffset, totalDuration, totalSec);
+                    frameGroups.push(svgMarkup);
+                    keyframes.push(css);
+                }
+                else if (overlay.kind === "svg") {
+                    const { svgMarkup, css } = renderSvgOverlay(overlay, i, timeOffset, frame.duration, totalDuration, totalSec);
+                    frameGroups.push(svgMarkup);
+                    keyframes.push(css);
+                }
+            }
+        }
+        timeOffset += frame.duration + transDur;
+    }
+    // Compose final SVG with XML declaration for proper UTF-8
+    const sharedDefsMarkup = config.sharedDefs ?? "";
+    const animationCss = buildIntraFrameAnimationCss(frames, frameTiming, totalSec);
+    // Cursor overlay (DM-277). The frame start times let the resolver pick
+    // which frame's selector matches apply at each event's timestamp.
+    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);
+    }
+    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>
+    <clipPath id="viewport-clip"><rect width="${width}" height="${height}" /></clipPath>${sharedDefsMarkup}
+  </defs>
+  <style>
+    .f { opacity: 0; }
+    ${keyframes.join("\n")}${animationCss}
+  </style>
+  <g clip-path="url(#viewport-clip)">
+  <rect width="${width}" height="${height}" fill="#0d1117" />
+${frameGroups.join("\n")}${overlayMarkup}
+  </g>
+</svg>`;
+    return out;
+}
+/**
+ * Effective transition duration for a frame. `cut` is always 0 — the type
+ * means "instant" so any duration on the input is meaningless. Default
+ * (no transition specified) is 300ms (legacy crossfade duration).
+ */
+function transitionDuration(f) {
+    if (f.transition == null)
+        return 300;
+    if (f.transition.type === "cut")
+        return 0;
+    return f.transition.duration;
+}
+function renderTypingOverlay(overlay, frameIdx, frameStart, frameEnd, totalDuration, totalSec) {
+    const delay = overlay.delay ?? 300;
+    const speed = overlay.speed ?? 60;
+    const fontSize = overlay.fontSize ?? 14;
+    const charWidth = fontSize * 0.6;
+    const color = overlay.color ?? "#e6edf3";
+    const typeStartMs = frameStart + delay;
+    const parts = [];
+    const cssRules = [];
+    const id = `t${frameIdx}`;
+    // Background mask
+    if (overlay.bgColor != null) {
+        const bgW = overlay.bgWidth ?? overlay.text.length * charWidth + 8;
+        const bgH = overlay.bgHeight ?? fontSize + 6;
+        const bgStartPct = pct(typeStartMs, totalDuration);
+        const bgEndPct = pct(frameStart + overlay.text.length * speed + delay + 500, totalDuration);
+        parts.push(`  <rect class="${id}-bg" x="${overlay.x - 2}" y="${overlay.y - fontSize + 2}" width="${bgW}" height="${bgH}" fill="${overlay.bgColor}" rx="2" />`);
+        cssRules.push(`
+    @keyframes ${id}-bg { 0%, ${bgStartPct} { opacity: 0; } ${pct(typeStartMs + 50, totalDuration)} { opacity: 1; } ${bgEndPct}, 100% { opacity: 0; } }
+    .${id}-bg { animation: ${id}-bg ${totalSec.toFixed(2)}s infinite; }`);
+    }
+    // Render full text with an animated clip that reveals characters one-by-one.
+    // The overlay must disappear by the time the frame ends — otherwise it'll
+    // leak across the cut boundary and overlap the next frame's content.
+    const textEndMs = typeStartMs + overlay.text.length * speed;
+    const holdEndMs = Math.min(frameStart + 3000, frameEnd);
+    const fullTextWidth = overlay.text.length * charWidth + 4;
+    const textHeight = fontSize + 4;
+    const clipId = `${id}-clip`;
+    // Clip rect animation: width grows from 0 to full text width
+    parts.push(`  <defs><clipPath id="${clipId}"><rect class="${id}-reveal" x="${overlay.x}" y="${overlay.y - fontSize}" width="0" height="${textHeight}" /></clipPath></defs>`);
+    parts.push(`  <text class="${id}-text" x="${overlay.x}" y="${overlay.y}" fill="${color}" font-size="${fontSize}" font-family="'SF Mono', Menlo, Monaco, monospace" clip-path="url(#${clipId})">${escapeXml(overlay.text)}</text>`);
+    const typeStartPct = pct(typeStartMs, totalDuration);
+    const typeEndPct = pct(textEndMs, totalDuration);
+    const holdEndPct = pct(holdEndMs, totalDuration);
+    cssRules.push(`
+    @keyframes ${id}-reveal { 0%, ${typeStartPct} { width: 0; } ${typeEndPct} { width: ${fullTextWidth}px; } ${holdEndPct} { width: ${fullTextWidth}px; } ${pct(holdEndMs + 100, totalDuration)}, 100% { width: 0; } }
+    .${id}-reveal { animation: ${id}-reveal ${totalSec.toFixed(2)}s infinite; }
+    @keyframes ${id}-vis { 0%, ${typeStartPct} { opacity: 0; } ${pct(typeStartMs + 30, totalDuration)} { opacity: 1; } ${holdEndPct} { opacity: 1; } ${pct(holdEndMs + 100, totalDuration)}, 100% { opacity: 0; } }
+    .${id}-text { animation: ${id}-vis ${totalSec.toFixed(2)}s infinite; }`);
+    return { svgMarkup: parts.join("\n"), css: cssRules.join("") };
+}
+function renderTapOverlay(overlay, frameIdx, frameStart, totalDuration, totalSec) {
+    const delay = overlay.delay ?? 50;
+    const tapMs = frameStart + delay;
+    const rippleDur = 500;
+    const id = `tap${frameIdx}`;
+    const tapStartPct = pct(tapMs, totalDuration);
+    const tapPeakPct = pct(tapMs + rippleDur * 0.3, totalDuration);
+    const tapEndPct = pct(tapMs + rippleDur, totalDuration);
+    const svgMarkup = [
+        `  <circle class="${id}" cx="${overlay.x}" cy="${overlay.y}" r="0" fill="rgba(255,255,255,0.35)" />`,
+        `  <circle class="${id}-dot" cx="${overlay.x}" cy="${overlay.y}" r="7" fill="rgba(255,255,255,0.5)" />`,
+    ].join("\n");
+    const css = `
+    @keyframes ${id} { 0%, ${tapStartPct} { r: 0; opacity: 0.4; } ${tapPeakPct} { r: 28; opacity: 0.2; } ${tapEndPct}, 100% { r: 35; opacity: 0; } }
+    .${id} { animation: ${id} ${totalSec.toFixed(2)}s infinite; }
+    @keyframes ${id}-dot { 0%, ${tapStartPct} { opacity: 0; } ${pct(tapMs + 20, totalDuration)} { opacity: 0.6; } ${tapPeakPct} { opacity: 0.2; } ${tapEndPct}, 100% { opacity: 0; } }
+    .${id}-dot { animation: ${id}-dot ${totalSec.toFixed(2)}s infinite; }`;
+    return { svgMarkup, css };
+}
+function pct(ms, total) {
+    return `${((ms / total) * 100).toFixed(2)}%`;
+}
+/**
+ * Render a frame-local SVG overlay. The embedded SVG markup is wrapped in a
+ * `<g transform="translate(x y)" clip-path="..."/>` and an inner
+ * `<g class="ov-<id>">` so `enter`/`exit` / explicit animations can target
+ * the overlay without colliding with classes inside the embedded SVG.
+ */
+function renderSvgOverlay(overlay, frameIdx, frameStart, frameHoldMs, totalDuration, totalSec) {
+    const id = `ov-${frameIdx}-${overlay.animId}`;
+    const clipId = `${id}-clip`;
+    const visibilityId = `${id}-vis`;
+    const overlayEnd = frameStart + frameHoldMs;
+    const visStart = pct(frameStart, totalDuration);
+    const visEnd = pct(overlayEnd, totalDuration);
+    const cssRules = [];
+    // Visibility timeline: hidden until frame start, visible during the hold.
+    cssRules.push(`
+    @keyframes ${visibilityId} { 0%, ${pct(Math.max(0, frameStart - 1), totalDuration)} { opacity: 0; } ${visStart} { opacity: 1; } ${visEnd} { opacity: 1; } ${pct(overlayEnd + 1, totalDuration)}, 100% { opacity: 0; } }
+    .${id} { animation: ${visibilityId} ${totalSec.toFixed(2)}s infinite; }`);
+    // Slide-in entrance (DM-211): translate from off-screen to (0, 0) over
+    // duration ms, starting at frame start + delay.
+    if (overlay.enter != null) {
+        const e = overlay.enter;
+        const easing = e.easing ?? "ease-out";
+        const enterDelay = e.delay ?? 0;
+        const fromStr = offsetForDirection(e.from, overlay.width, overlay.height, true);
+        const enterStart = frameStart + enterDelay;
+        const enterEnd = enterStart + e.duration;
+        const enterId = `${id}-enter`;
+        cssRules.push(`
+    @keyframes ${enterId} { 0% { transform: ${fromStr}; } ${pct(enterStart, totalDuration)} { transform: ${fromStr}; } ${pct(enterEnd, totalDuration)} { transform: translate(0, 0); } 100% { transform: translate(0, 0); } }
+    .${id}-enter { animation: ${enterId} ${totalSec.toFixed(2)}s infinite; animation-timing-function: ${easing}; }`);
+    }
+    // Slide-out exit. Mirror of enter — translate from (0,0) to off-screen.
+    if (overlay.exit != null) {
+        const e = overlay.exit;
+        const easing = e.easing ?? "ease-in";
+        const exitDelay = e.delay ?? 0;
+        const toStr = offsetForDirection(e.from, overlay.width, overlay.height, false);
+        const exitStart = overlayEnd - e.duration - exitDelay;
+        const exitId = `${id}-exit`;
+        cssRules.push(`
+    @keyframes ${exitId} { 0%, ${pct(exitStart, totalDuration)} { transform: translate(0, 0); } ${pct(exitStart + e.duration, totalDuration)} { transform: ${toStr}; } 100% { transform: ${toStr}; } }
+    .${id}-exit { animation: ${exitId} ${totalSec.toFixed(2)}s infinite; animation-timing-function: ${easing}; }`);
+    }
+    // Markup: outer wrapper translates to (x, y) and clips, inner wrapper
+    // carries the visibility class, then the enter/exit transform wrapper, then
+    // the inlined SVG content.
+    const enterClass = overlay.enter != null ? ` ${id}-enter` : "";
+    const exitClass = overlay.exit != null ? ` ${id}-exit` : "";
+    const svgMarkup = `  <g transform="translate(${overlay.x} ${overlay.y})" clip-path="url(#${clipId})">
+    <defs><clipPath id="${clipId}"><rect width="${overlay.width}" height="${overlay.height}"/></clipPath></defs>
+    <g class="${id}${enterClass}${exitClass}">${overlay.innerSvg}</g>
+  </g>`;
+    return { svgMarkup, css: cssRules.join("") };
+}
+/**
+ * Offset string for a slide direction. When `outFrom` is true the offset is
+ * the off-screen starting position (i.e. the overlay sits there before
+ * animating to `(0,0)`). When false, it's the off-screen end position
+ * (overlay animates from `(0,0)` to here on exit).
+ */
+function offsetForDirection(dir, w, h, _outFrom) {
+    if (dir === "top")
+        return `translate(0, -${h}px)`;
+    if (dir === "bottom")
+        return `translate(0, ${h}px)`;
+    if (dir === "left")
+        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);
+    // 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>
+    :root { --scene-dur: ${totalSec.toFixed(2)}s; }
+${css}${animationCss}
+  </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
+ * scene clock so the property holds at `from` until the frame becomes
+ * visible (+ `delay`), animates to `to` over `duration`, then holds at `to`
+ * until the loop restarts.
+ */
+function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
+    const totalMs = totalSec * 1000;
+    const out = [];
+    for (let i = 0; i < frames.length; i++) {
+        const animations = frames[i].animations;
+        if (animations == null || animations.length === 0)
+            continue;
+        const frameStartMs = (frameTiming.startPct[i] / 100) * totalMs;
+        for (let ai = 0; ai < animations.length; ai++) {
+            const a = animations[ai];
+            const delay = a.delay ?? 0;
+            const easing = a.easing ?? "linear";
+            const startMs = frameStartMs + delay;
+            const endMs = startMs + a.duration;
+            const startPct = (startMs / totalMs) * 100;
+            const endPct = (endMs / totalMs) * 100;
+            const propValue = (val) => {
+                if (a.property === "translateX")
+                    return `transform: translateX(${val});`;
+                if (a.property === "translateY")
+                    return `transform: translateY(${val});`;
+                if (a.property === "clipPath")
+                    return `clip-path: ${val};`;
+                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} {
+      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");
+}
+function escapeXml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}

package/dist/animator.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for the SVG animator — specifically the keyframe timing and
+ * shared-defs hoist. Regression tests for SK-662 (flicker + size).
+ */
+export {};

package/dist/animator.test.js

@@ -0,0 +1,169 @@
+/**
+ * Unit tests for the SVG animator — specifically the keyframe timing and
+ * shared-defs hoist. Regression tests for SK-662 (flicker + size).
+ */
+import { describe, it, expect } from "vitest";
+import { generateAnimatedSvg } from "./animator.js";
+describe("animator", () => {
+    it("includes sharedDefs in the top-level <defs>", () => {
+        const svg = generateAnimatedSvg({
+            width: 100,
+            height: 100,
+            sharedDefs: `<path id="g0" d="M0 0L1 1Z"/>`,
+            frames: [
+                { svgContent: `<use href="#g0"/>`, duration: 200 },
+            ],
+        });
+        // The sharedDefs markup should appear inside the top-level <defs> block,
+        // immediately after the viewport clip, NOT inside any frame's <g class="f">.
+        const topDefs = svg.match(/<defs>[\s\S]*?<\/defs>/);
+        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.
+        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 },
+            ],
+        });
+        expect(svg).not.toMatch(/@keyframes fv-/);
+        expect(svg).toMatch(/@keyframes t\d+/);
+        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>.
+        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 },
+            ],
+        });
+        expect((svg.match(/<rect width="50" height="50" fill="green"\/>/g) ?? []).length).toBe(1);
+    });
+    it("non-crossfade transitions are unaffected", () => {
+        const svg = generateAnimatedSvg({
+            width: 100,
+            height: 100,
+            frames: [
+                { svgContent: `<rect/>`, duration: 1000, transition: { type: "push-left", duration: 200 } },
+                { svgContent: `<rect/>`, duration: 1000 },
+            ],
+        });
+        // push-left uses translateX keyframes — presence is enough.
+        expect(svg).toContain("translateX");
+    });
+    it("cut transition: ignores duration on the input", () => {
+        // `cut` is supposed to be instant regardless of what `duration` was passed
+        // (so a config that mistakenly leaves `duration: 9999` on a cut doesn't
+        // bloat the scene). Compare a 9999-duration cut against a 0-duration cut:
+        // they should produce the same scene length.
+        const a = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                { svgContent: `<rect fill="red"/>`, duration: 1000, transition: { type: "cut", duration: 9999 } },
+                { svgContent: `<rect fill="blue"/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
+            ],
+        });
+        const b = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                { svgContent: `<rect fill="red"/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
+                { svgContent: `<rect fill="blue"/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
+            ],
+        });
+        const aDur = a.match(/--scene-dur:\s*([0-9.]+)s/)?.[1];
+        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)", () => {
+        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, transition: { type: "cut", duration: 0 } },
+                { 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+/);
+        // 3 frames × 1000ms hold + 3 × 0ms cut transitions = 3000ms total.
+        expect(svg).toMatch(/--scene-dur:\s*3\.00s/);
+    });
+    it("intra-frame animation: emits @keyframes scoped to frame's visibility window", () => {
+        // DM-209: an animation declared on a frame should compile into a
+        // @keyframes block whose timing maps onto the global scene clock,
+        // gated by the frame's start position.
+        const svg = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                { svgContent: `<rect/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
+                {
+                    svgContent: `<rect/>`,
+                    duration: 2000,
+                    transition: { type: "cut", duration: 0 },
+                    animations: [{
+                            animId: "bar",
+                            property: "width",
+                            from: "0%",
+                            to: "100%",
+                            duration: 2000,
+                            easing: "ease-out",
+                        }],
+                },
+            ],
+        });
+        // Total scene = 3000ms. Frame 1 starts at 33.333%. Animation is during
+        // [frame-start + 0ms, frame-start + 2000ms] = [33.333%, 100%].
+        expect(svg).toMatch(/@keyframes f1-bar-0/);
+        expect(svg).toMatch(/\.anim-bar\s*{[^}]*animation:\s*f1-bar-0/);
+        // Both `from` and `to` values must appear in the keyframe block.
+        expect(svg).toContain("width: 0%");
+        expect(svg).toContain("width: 100%");
+        // Timing function passes through.
+        expect(svg).toContain("ease-out");
+    });
+    it("intra-frame animation: translateY desugars to transform: translateY()", () => {
+        const svg = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                {
+                    svgContent: `<rect/>`,
+                    duration: 1000,
+                    animations: [{
+                            animId: "slide",
+                            property: "translateY",
+                            from: "240px",
+                            to: "0px",
+                            duration: 400,
+                        }],
+                },
+            ],
+        });
+        expect(svg).toContain("transform: translateY(240px)");
+        expect(svg).toContain("transform: translateY(0px)");
+    });
+    it("cut transition: timeline boundary is exactly at the frame edge", () => {
+        // For two frames each held 1000ms with cut transitions and no overlap,
+        // the visibility flip should land at exactly 50% of the scene.
+        const svg = generateAnimatedSvg({
+            width: 100, height: 100,
+            frames: [
+                { svgContent: `<rect fill="red"/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
+                { svgContent: `<rect fill="blue"/>`, duration: 1000, transition: { type: "cut", duration: 0 } },
+            ],
+        });
+        expect(svg).toMatch(/--scene-dur:\s*2\.00s/);
+        // 50.000% boundary — frame 0 fades out and frame 1 fades in at the same instant.
+        expect(svg).toMatch(/50\.000%/);
+    });
+});

package/dist/border-radius.test.d.ts

@@ -0,0 +1 @@
+export {};