domotion-svg 0.8.0 → 0.11.0

package/assets/fonts/LICENSE-last-resort-font.txt

@@ -0,0 +1,94 @@
+This Font Software is licensed under the SIL Open Font License,
+Version 1.1.
+
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font
+creation efforts of academic and linguistic communities, and to
+provide a free and open framework in which fonts may be shared and
+improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply to
+any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software
+components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to,
+deleting, or substituting -- in part or in whole -- any of the
+components of the Original Version, by changing formats or by porting
+the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed,
+modify, redistribute, and sell modified and unmodified copies of the
+Font Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the
+corresponding Copyright Holder. This restriction only applies to the
+primary font name as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created using
+the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+SPDX-License-Identifier: OFL-1.1

package/dist/animation/animator.d.ts

@@ -4,7 +4,7 @@
  * Takes captured SVG frame content and composes them into a single
  * animated SVG with CSS keyframe transitions.
  */
-import { type CursorOverlay, type SelectorResolver } from "./cursor-overlay.js";
+import { type CursorAtResolver, 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) */
@@ -244,6 +244,14 @@ export interface AnimationConfig {
      * uses `selector`; otherwise pass undefined / null.
      */
     resolveSelector?: SelectorResolver;
+    /**
+     * DM-1106: auto cursor-TYPE hit-tester — given a viewport point and frame
+     * index, returns the cursor keyword under it (the caller builds this from the
+     * per-frame captured trees via `cursorAtPoint`). When provided, the overlay
+     * paints the matching glyph per element and switches at boundary crossings;
+     * when omitted, the overlay paints the single arrow.
+     */
+    resolveCursorAt?: CursorAtResolver;
     /**
      * Canvas background color painted behind every frame (a full-viewport
      * `<rect>`). Mirrors the single-frame path's `transparentRootBgRect`

package/dist/animation/animator.js

@@ -5,9 +5,156 @@
  * animated SVG with CSS keyframe transitions.
  */
 import { cursorOverlayMarkup, resolveCursorScript } from "./cursor-overlay.js";
+import { escapeHtml } from "../utils/escapeHtml.js";
+import { DEFAULT_TRANSITION_MS, frameAdvanceMs, transitionDurationMs } from "./frame-timeline.js";
+import { KEYFRAME_EPSILON, padAfter, padBefore } from "../utils/keyframe-pad.js";
+/**
+ * Emit one magic-move frame (DM-898): the frame-i blob (held [start..holdEnd],
+ * hard-cut out), the bridge composite (visible only across [holdEnd..transEnd]),
+ * the per-element slide / fade keyframes within that window, and the
+ * `prefers-reduced-motion` pinning (DM-901 / DM-903). Returns the SVG group
+ * fragments and the `@keyframes`/rule CSS for the caller to splice in.
+ * Extracted from `generateAnimatedSvg`'s per-frame loop (DM-1089) — byte-identical.
+ */
+function emitMagicMoveFrame(i, frame, mm, startPct, holdEndPct, transEndPct, totalSec) {
+    const groups = [];
+    const keyframes = [];
+    const sNum = parseFloat(startPct);
+    const hNum = parseFloat(holdEndPct);
+    const tNum = parseFloat(transEndPct);
+    const beforeS = padBefore(sNum, KEYFRAME_EPSILON.cull, 3);
+    const afterH = padAfter(hNum, KEYFRAME_EPSILON.cull, 3);
+    const beforeH = padBefore(hNum, KEYFRAME_EPSILON.cull, 3);
+    const afterT = padAfter(tNum, KEYFRAME_EPSILON.cull, 3);
+    // Frame i blob: visible only during its hold, hard-cut out at hold end.
+    groups.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.
+    groups.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) {
+        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.
+    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      ")}
+    }`);
+    }
+    return { groups, keyframes };
+}
+/**
+ * Emit one crossfade or cut frame (the default transition path): the frame
+ * blob plus its opacity keyframes. `cut` (or zero-duration) uses disjoint
+ * step-end keyframes so opacity flips instantly with no interpolation smear;
+ * crossfade overlaps the fade-in with the previous frame's fade-out, with the
+ * visible window driven by `fadeInStartPct` (precomputed by the caller, which
+ * knows the overlap state). Extracted from `generateAnimatedSvg` (DM-1089).
+ */
+function emitCrossfadeOrCutFrame(i, frame, transType, transDur, startPct, holdEndPct, transEndPct, fadeInStartPct, totalSec) {
+    const groups = [];
+    const keyframes = [];
+    groups.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 = padBefore(startNum, KEYFRAME_EPSILON.cull, 3);
+        const afterEnd = padAfter(endNum, KEYFRAME_EPSILON.cull, 3);
+        keyframes.push(`
+    @keyframes fv-${i} {
+      0% { opacity: 0; visibility: hidden; }
+      ${beforeStart}% { opacity: 0; visibility: hidden; }
+      ${startNum.toFixed(3)}% { opacity: 1; visibility: visible; }
+      ${endNum.toFixed(3)}% { opacity: 1; visibility: visible; }
+      ${afterEnd}% { opacity: 0; visibility: hidden; }
+      100% { opacity: 0; visibility: hidden; }
+    }
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; animation-timing-function: step-end; }`);
+    }
+    else {
+        const prevEnd = i > 0
+            ? `${padBefore(parseFloat(fadeInStartPct), KEYFRAME_EPSILON.display, 2)}%,`
+            : "";
+        keyframes.push(`
+    @keyframes fv-${i} {
+      0%, ${prevEnd} ${transEndPct}, 100% { opacity: 0; }
+      ${startPct}, ${holdEndPct} { opacity: 1; }
+    }${buildDisplayKeyframes(`fd-${i}`, fadeInStartPct, transEndPct)}
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }`);
+    }
+    return { groups, keyframes };
+}
 export function generateAnimatedSvg(config) {
     const { width, height, frames } = config;
-    const totalDuration = frames.reduce((sum, f) => sum + f.duration + transitionDuration(f), 0);
+    const totalDuration = frames.reduce((sum, f) => sum + frameAdvanceMs(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).
@@ -17,7 +164,7 @@ export function generateAnimatedSvg(config) {
     {
         let t = 0;
         for (const f of frames) {
-            const td = transitionDuration(f);
+            const td = transitionDurationMs(f);
             frameTiming.startPct.push((t / totalDuration) * 100);
             frameTiming.holdEndPct.push(((t + f.duration) / totalDuration) * 100);
             frameTiming.transEndPct.push(((t + f.duration + td) / totalDuration) * 100);
@@ -43,7 +190,7 @@ export function generateAnimatedSvg(config) {
     let timeOffset = 0;
     for (let i = 0; i < frames.length; i++) {
         const frame = frames[i];
-        const transDur = transitionDuration(frame);
+        const transDur = transitionDurationMs(frame);
         const transType = frame.transition?.type ?? "crossfade";
         const startPct = pct(timeOffset, totalDuration);
         const holdEndPct = pct(timeOffset + frame.duration, totalDuration);
@@ -61,7 +208,7 @@ export function generateAnimatedSvg(config) {
         // one slides out, so its show window starts at `timeOffset - prevTransDur`
         // rather than at `startPct`.
         const entersViaOverlap = entersViaPush || entersViaScroll;
-        const prevTransDur = prevFrame != null ? transitionDuration(prevFrame) : 300;
+        const prevTransDur = prevFrame != null ? transitionDurationMs(prevFrame) : DEFAULT_TRANSITION_MS;
         const enterStartPct = entersViaOverlap
             ? pct(timeOffset - prevTransDur, totalDuration)
             : startPct;
@@ -74,24 +221,7 @@ export function generateAnimatedSvg(config) {
             // Window is [enterStartPct .. transEndPct] (when the slide has fully
             // exited the viewBox); 0.01% pad on each side keeps the snap inside the
             // existing opacity:0 bookend.
-            const visStart = enterStartPct;
-            const visEnd = transEndPct;
-            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; }
-    }${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; }`);
+            keyframes.push(slideKeyframes(i, "X", width, entersViaPush, enterStartPct, startPct, holdEndPct, transEndPct, enterStartPct, transEndPct, totalSec));
         }
         else if (transType === "scroll") {
             // DM-609: `scroll` now means real geometric scroll between two frames
@@ -100,27 +230,10 @@ export function generateAnimatedSvg(config) {
             // slides up from the bottom of the viewport, outgoing slides up off
             // the top. Uses height instead of width and translateY instead of
             // translateX, otherwise identical machinery (incl. the cull-friendly
-            // `fd-${i}` display animation).
-            const entersViaScroll = prevFrame?.transition?.type === "scroll";
+            // `fd-${i}` display animation). (`entersViaScroll` is already computed in
+            // the outer scope above — same value, no need to redeclare/shadow it.)
             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>`);
-            const visStart = enterStartPct;
-            const visEnd = transEndPct;
-            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); }
-      ${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; }
-      ${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; }`);
+            keyframes.push(slideKeyframes(i, "Y", height, entersViaScroll, enterStartPct, startPct, holdEndPct, transEndPct, enterStartPct, transEndPct, totalSec));
         }
         else if (transType === "magic-move" && frame.magicMove != null) {
             // DM-898: magic-move. Frame i holds [start..holdEnd] then HARD-CUTS out;
@@ -131,163 +244,21 @@ export function generateAnimatedSvg(config) {
             // 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      ")}
-    }`);
-            }
+            const r = emitMagicMoveFrame(i, frame, frame.magicMove, startPct, holdEndPct, transEndPct, totalSec);
+            frameGroups.push(...r.groups);
+            keyframes.push(...r.keyframes);
         }
         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);
-                // DM-599: cut already uses step-end on the opacity animation, so we
-                // fold visibility into the same keyframes block — both snap together.
-                // DM-641: this used to toggle `display`. The base `.f { display: none }`
-                // rule kept the element out of the render tree at t=0, and Chromium
-                // doesn't tick infinite animations on out-of-tree elements — so the
-                // 0% keyframe never ran and the frame stayed permanently hidden.
-                // Switching to `visibility` leaves the element in the render tree
-                // (still skips painting, which was the DM-599 goal) so the animation
-                // ticks normally.
-                keyframes.push(`
-    @keyframes fv-${i} {
-      0% { opacity: 0; visibility: hidden; }
-      ${beforeStart}% { opacity: 0; visibility: hidden; }
-      ${startNum.toFixed(3)}% { opacity: 1; visibility: visible; }
-      ${endNum.toFixed(3)}% { opacity: 1; visibility: visible; }
-      ${afterEnd}% { opacity: 0; visibility: hidden; }
-      100% { opacity: 0; visibility: hidden; }
-    }
-    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite; animation-timing-function: step-end; }`);
-            }
-            else {
-                const fadeInStartPct = (i > 0 && !entersViaMagicMove)
-                    ? pct(Math.max(0, timeOffset - prevTransDur), totalDuration)
-                    : startPct;
-                const prevEnd = i > 0
-                    ? `${Math.max(0, parseFloat(fadeInStartPct) - 0.01).toFixed(2)}%,`
-                    : "";
-                // DM-599: visible window spans the full fade — fadeInStart through
-                // transEnd (display stays `inline` while opacity interpolates).
-                keyframes.push(`
-    @keyframes fv-${i} {
-      0%, ${prevEnd} ${transEndPct}, 100% { opacity: 0; }
-      ${startPct}, ${holdEndPct} { opacity: 1; }
-    }${buildDisplayKeyframes(`fd-${i}`, fadeInStartPct, transEndPct)}
-    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }`);
-            }
+            // Crossfade or cut: opacity in/out (see emitCrossfadeOrCutFrame). The
+            // crossfade fade-in OVERLAPS the previous frame's fade-out, so its visible
+            // window starts at fadeInStartPct — which depends on the loop's overlap
+            // state (entersViaMagicMove / prevTransDur), so it's computed here.
+            const fadeInStartPct = (i > 0 && !entersViaMagicMove)
+                ? pct(Math.max(0, timeOffset - prevTransDur), totalDuration)
+                : startPct;
+            const r = emitCrossfadeOrCutFrame(i, frame, transType, transDur, startPct, holdEndPct, transEndPct, fadeInStartPct, totalSec);
+            frameGroups.push(...r.groups);
+            keyframes.push(...r.keyframes);
         }
         // Overlays
         if (frame.overlays != null) {
@@ -332,10 +303,10 @@ export function generateAnimatedSvg(config) {
         let acc = 0;
         for (const f of frames) {
             frameStarts.push(acc);
-            acc += f.duration + transitionDuration(f);
+            acc += frameAdvanceMs(f);
         }
-        const resolved = resolveCursorScript(config.cursorOverlay, totalDuration, frameStarts, config.resolveSelector ?? null);
-        overlayMarkup = "\n" + cursorOverlayMarkup(resolved.positions, resolved.clicks, resolved.style, totalDuration);
+        const resolved = resolveCursorScript(config.cursorOverlay, totalDuration, frameStarts, config.resolveSelector ?? null, config.resolveCursorAt ?? null);
+        overlayMarkup = "\n" + cursorOverlayMarkup(resolved.positions, resolved.clicks, resolved.style, totalDuration, resolved.cursorTimeline);
     }
     // Canvas background rect — only when a non-transparent background is given.
     // Default (none / transparent) emits nothing so the SVG composites over the
@@ -360,18 +331,6 @@ ${canvasBgRect}${frameGroups.join("\n")}${overlayMarkup}
 </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;
-}
 /**
  * Wrap `text` into lines no wider than `maxChars` monospace cells, the way a
  * browser textarea does: break on spaces, char-break a word longer than the
@@ -481,7 +440,7 @@ function renderTypingOverlay(overlay, frameIdx, frameStart, frameEnd, totalDurat
         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>`);
+        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})">${escapeHtml(line)}</text>`);
         cssRules.push(`
     @keyframes ${id}-rev${li} { 0%, ${lineStartPct} { width: 0; } ${lineEndPct} { width: ${lineWidth}px; } ${holdEndPct} { width: ${lineWidth}px; } ${disappearPct}, 100% { width: 0; } }
     .${id}-rev${li} { animation: ${id}-rev${li} ${totalSec.toFixed(2)}s infinite; }`);
@@ -598,8 +557,8 @@ function buildDisplayKeyframes(name, visibleStartPct, visibleEndPct) {
     // ticks in Chromium.
     const start = parseFloat(String(visibleStartPct));
     const end = parseFloat(String(visibleEndPct));
-    const startMinus = Math.max(0, start - 0.01).toFixed(3);
-    const endPlus = Math.min(100, end + 0.01).toFixed(3);
+    const startMinus = padBefore(start, KEYFRAME_EPSILON.display, 3);
+    const endPlus = padAfter(end, KEYFRAME_EPSILON.display, 3);
     return `
     @keyframes ${name} {
       0% { visibility: hidden; }
@@ -610,6 +569,33 @@ function buildDisplayKeyframes(name, visibleStartPct, visibleEndPct) {
       100% { visibility: hidden; }
     }`;
 }
+/**
+ * Slide-transition keyframes (push-left / scroll). The two transitions are the
+ * same machinery on different axes: `push-left` slides horizontally (axis `X`,
+ * `size` = width), `scroll` slides vertically (axis `Y`, `size` = height). The
+ * incoming frame starts off-screen (`+size`) only when the predecessor was the
+ * same slide type (`entersSliding`), holds at 0 across its show window, then
+ * exits to `-size`. 0.1% pads on each bookend keep the snap inside the
+ * opacity:0 frame. Emits the fp/fv/fd keyframes + the `.f-`/`.fp-` rules.
+ */
+function slideKeyframes(i, axis, size, entersSliding, enterStartPct, startPct, holdEndPct, transEndPct, visStart, visEnd, totalSec) {
+    return `
+    @keyframes fp-${i} {
+      0%, ${padBefore(parseFloat(enterStartPct), KEYFRAME_EPSILON.slide, 2)}% { transform: translate${axis}(${entersSliding ? size : 0}px); }
+      ${startPct} { transform: translate${axis}(0); }
+      ${holdEndPct} { transform: translate${axis}(0); }
+      ${transEndPct} { transform: translate${axis}(-${size}px); }
+      ${padAfter(parseFloat(transEndPct), KEYFRAME_EPSILON.slide, 2)}%, 100% { transform: translate${axis}(-${size}px); }
+    }
+    @keyframes fv-${i} {
+      0%, ${padBefore(parseFloat(enterStartPct), KEYFRAME_EPSILON.slide, 2)}% { opacity: 0; }
+      ${enterStartPct} { opacity: 1; }
+      ${transEndPct} { opacity: 1; }
+      ${padAfter(parseFloat(transEndPct), KEYFRAME_EPSILON.slide, 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; }`;
+}
 /**
  * Render a frame-local SVG overlay. The embedded SVG markup is wrapped in a
  * `<g transform="translate(x y)" clip-path="..."/>` and an inner
@@ -744,6 +730,3 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
     }
     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;");
-}