domotion-svg 0.19.1 → 0.20.0

package/dist/animation/animator.js

@@ -10,7 +10,8 @@ import { isTransparentBackground } from "../utils/transparent-background.js";
 import { rootSvgA11y } from "../render/format.js";
 import { DEFAULT_TRANSITION_MS, frameAdvanceMs, transitionDurationMs } from "./frame-timeline.js";
 import { offsetEmbeddedAnimatedSvgTimeline } from "./embed-timeline.js";
-import { KEYFRAME_EPSILON, padAfter, padBefore } from "../utils/keyframe-pad.js";
+import { KEYFRAME_EPSILON, cullOverlapPct, padAfter, padBefore } from "../utils/keyframe-pad.js";
+import { interpolateCssValue, resolveEasing } from "./easing.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]),
@@ -30,29 +31,32 @@ function emitMagicMoveFrame(i, frame, mm, startPct, holdEndPct, transEndPct, tot
     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.
+    // DM-1511: opacity does the cut; a SEPARATE wide-overlap `fd-` `visibility`
+    // track handles paint-culling so Firefox can't flash a transparent gap at the
+    // hand-off (it composites `visibility` off the opacity clock).
     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 step-end infinite; }`);
+      0% { opacity: 0; }
+      ${beforeS}% { opacity: 0; }
+      ${sNum.toFixed(3)}% { opacity: 1; }
+      ${hNum.toFixed(3)}% { opacity: 1; }
+      ${afterH}% { opacity: 0; }
+      100% { opacity: 0; }
+    }${buildDisplayKeyframes(`fd-${i}`, startPct, holdEndPct, totalSec)}
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s step-end infinite, fd-${i} ${totalSec.toFixed(2)}s step-end infinite; }`);
     // 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 step-end infinite; }`);
+      0% { opacity: 0; }
+      ${beforeH}% { opacity: 0; }
+      ${hNum.toFixed(3)}% { opacity: 1; }
+      ${tNum.toFixed(3)}% { opacity: 1; }
+      ${afterT}% { opacity: 0; }
+      100% { opacity: 0; }
+    }${buildDisplayKeyframes(`mmd-${i}`, holdEndPct, transEndPct, totalSec)}
+    .mm-${i} { animation: mmv-${i} ${totalSec.toFixed(2)}s step-end infinite, mmd-${i} ${totalSec.toFixed(2)}s step-end infinite; }`);
     // 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.
@@ -127,16 +131,19 @@ holdToEnd) {
         const endNum = parseFloat(transEndPct);
         const beforeStart = padBefore(startNum, KEYFRAME_EPSILON.cull, 3);
         const afterEnd = padAfter(endNum, KEYFRAME_EPSILON.cull, 3);
+        // DM-1511: opacity does the cut (tight overlap, Firefox-safe); `visibility`
+        // is a SEPARATE wide-overlap paint-cull track so Firefox can't flash a
+        // transparent gap at the hand-off. (Previously one combined keyframe.)
         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 step-end infinite; }`);
+      0% { opacity: 0; }
+      ${beforeStart}% { opacity: 0; }
+      ${startNum.toFixed(3)}% { opacity: 1; }
+      ${endNum.toFixed(3)}% { opacity: 1; }
+      ${afterEnd}% { opacity: 0; }
+      100% { opacity: 0; }
+    }${buildDisplayKeyframes(`fd-${i}`, startPct, transEndPct, totalSec)}
+    .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s step-end infinite, fd-${i} ${totalSec.toFixed(2)}s step-end infinite; }`);
     }
     else {
         const prevEnd = i > 0
@@ -151,7 +158,7 @@ holdToEnd) {
             keyframes.push(`
     @keyframes fv-${i} {
       ${offSeg}${startPct}, 100% { opacity: 1; }
-    }${buildDisplayKeyframes(`fd-${i}`, fadeInStartPct, "100")}
+    }${buildDisplayKeyframes(`fd-${i}`, fadeInStartPct, "100", totalSec)}
     .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }`);
         }
         else {
@@ -159,7 +166,7 @@ holdToEnd) {
     @keyframes fv-${i} {
       0%, ${prevEnd} ${transEndPct}, 100% { opacity: 0; }
       ${startPct}, ${holdEndPct} { opacity: 1; }
-    }${buildDisplayKeyframes(`fd-${i}`, fadeInStartPct, transEndPct)}
+    }${buildDisplayKeyframes(`fd-${i}`, fadeInStartPct, transEndPct, totalSec)}
     .f-${i} { animation: fv-${i} ${totalSec.toFixed(2)}s infinite, fd-${i} ${totalSec.toFixed(2)}s infinite step-end; }`);
         }
     }
@@ -735,16 +742,26 @@ function pctNum(ms, total) {
  * `visibleStartPct` / `visibleEndPct` accept either a numeric-style string
  * (`"12.34"`) or one with a trailing `%` (`"12.34%"`) — `pct()` returns the
  * latter and the unmerged-path keyframes feed either form.
+ *
+ * DM-1511: the visible window is padded OUTWARD by a wide wall-clock margin
+ * (`cullOverlapPct`) so adjacent frames' paint windows OVERLAP. The visual cut
+ * is driven by the sibling `opacity` animation (`fv-*`), which Firefox
+ * composites in lock-step; `visibility` is only the paint-cull gate, and a
+ * sub-millisecond visibility hand-off flashed a transparent gap in Firefox at
+ * cut points. Over-wide visibility is harmless — the frame is `opacity:0`
+ * outside its true window — but removes any instant where both neighbors are
+ * `visibility:hidden`. `totalSec` is the scene length used to size the margin.
  */
-function buildDisplayKeyframes(name, visibleStartPct, visibleEndPct) {
+function buildDisplayKeyframes(name, visibleStartPct, visibleEndPct, totalSec) {
     // DM-641: kept the function name for callers but the toggle is now on
     // `visibility`, not `display`, for the same reason as `fv-${i}` above —
     // animating `display` away from an element starting `display: none` never
     // ticks in Chromium.
-    const start = parseFloat(String(visibleStartPct));
-    const end = parseFloat(String(visibleEndPct));
-    const startMinus = padBefore(start, KEYFRAME_EPSILON.display, 3);
-    const endPlus = padAfter(end, KEYFRAME_EPSILON.display, 3);
+    const margin = cullOverlapPct(totalSec * 1000);
+    const start = Math.max(0, parseFloat(String(visibleStartPct)) - margin);
+    const end = Math.min(100, parseFloat(String(visibleEndPct)) + margin);
+    const startMinus = padBefore(start, KEYFRAME_EPSILON.cull, 3);
+    const endPlus = padAfter(end, KEYFRAME_EPSILON.cull, 3);
     return `
     @keyframes ${name} {
       0% { visibility: hidden; }
@@ -816,7 +833,7 @@ holdToEnd = false) {
     @keyframes fv-${i} {
       ${fvEnter}
       100% { opacity: 1; }
-    }${buildDisplayKeyframes(`fd-${i}`, visStart, "100")}
+    }${buildDisplayKeyframes(`fd-${i}`, visStart, "100", totalSec)}
     .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; }`;
     }
@@ -832,7 +849,7 @@ holdToEnd = false) {
       ${fvEnter}
       ${transEndPct} { opacity: 1; }
       ${padAfter(parseFloat(transEndPct), KEYFRAME_EPSILON.slide, 2)}%, 100% { opacity: 0; }
-    }${buildDisplayKeyframes(`fd-${i}`, visStart, visEnd)}
+    }${buildDisplayKeyframes(`fd-${i}`, visStart, visEnd, totalSec)}
     .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; }`;
 }
@@ -914,6 +931,34 @@ function offsetForDirection(dir, w, h) {
  * visible (+ `delay`), animates to `to` over `duration`, then holds at `to`
  * until the loop restarts.
  */
+/**
+ * DM-1512/1513: compose one keyframe stop's declaration from several property
+ * "parts" (a value per fused track). Transform-family tracks
+ * (`translateX`/`translateY`/`scale`/raw `transform`) collapse into a SINGLE
+ * `transform:` — two `transform:` declarations would clobber each other — while
+ * other properties (`opacity`, `clip-path`, …) emit alongside.
+ */
+function composeAnimStop(parts) {
+    const transforms = [];
+    const others = [];
+    for (const p of parts) {
+        if (p.property === "translateX")
+            transforms.push(`translateX(${p.val})`);
+        else if (p.property === "translateY")
+            transforms.push(`translateY(${p.val})`);
+        else if (p.property === "scale")
+            transforms.push(`scale(${p.val})`);
+        else if (p.property === "transform")
+            transforms.push(p.val);
+        else if (p.property === "clipPath")
+            others.push(`clip-path: ${p.val};`);
+        else
+            others.push(`${p.property}: ${p.val};`);
+    }
+    if (transforms.length > 0)
+        others.push(`transform: ${transforms.join(" ")};`);
+    return others.join(" ");
+}
 function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
     const totalMs = totalSec * 1000;
     const out = [];
@@ -930,17 +975,9 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
             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 === "scale")
-                    return `transform: scale(${val});`;
-                if (a.property === "clipPath")
-                    return `clip-path: ${val};`;
-                return `${a.property}: ${val};`;
-            };
+            const tracks = [{ property: a.property, from: a.from, to: a.to }, ...(a.fuse ?? [])];
+            const declFrom = composeAnimStop(tracks.map((t) => ({ property: t.property, val: t.from })));
+            const declTo = composeAnimStop(tracks.map((t) => ({ property: t.property, val: t.to })));
             // DM-1297: SVG transforms are origin-(0,0); a `transformOrigin` makes a
             // scale/rotate/translate resolve about the element's OWN box (e.g. a
             // center-origin scale-pop) instead of the SVG origin. `transform-box:
@@ -949,6 +986,58 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
                 ? ` transform-box: fill-box; transform-origin: ${a.transformOrigin};`
                 : "";
             const animName = `f${i}-${a.animId}-${ai}`;
+            // DM-1517: when a fused track carries its OWN duration/delay/easing, the
+            // tracks no longer share one `animation-timing-function`, so we can't emit
+            // a from/to pair. Instead SAMPLE each track's eased value over its own
+            // window at many stops and emit them with `linear` timing (easing baked
+            // in) — still ONE animation / one timeline. Only for one-shot reveals
+            // (`repeat` loops keep the shared-timing cycle form).
+            const sampledTracks = a.fuse ?? [];
+            const needsSampling = a.repeat == null
+                && sampledTracks.some((t) => t.duration != null || t.delay != null || t.easing != null);
+            if (needsSampling) {
+                const win = tracks.map((t) => {
+                    const tStart = frameStartMs + (t.delay ?? delay);
+                    const tEnd = tStart + (t.duration ?? a.duration);
+                    return {
+                        property: t.property, from: t.from, to: t.to,
+                        startPct: (tStart / totalMs) * 100,
+                        endPct: (tEnd / totalMs) * 100,
+                        ease: resolveEasing(t.easing ?? a.easing),
+                    };
+                });
+                const minStart = Math.min(...win.map((w) => w.startPct));
+                const maxEnd = Math.max(...win.map((w) => w.endPct));
+                // Stops: 0/100 + every track boundary + a fine grid across the active
+                // span so each track's eased curve is well approximated.
+                const stopSet = new Set([0, 100]);
+                for (const w of win) {
+                    stopSet.add(w.startPct);
+                    stopSet.add(w.endPct);
+                }
+                const STEP = 2;
+                for (let p = minStart; p < maxEnd; p += STEP)
+                    stopSet.add(p);
+                const stops = [...stopSet].filter((p) => p >= 0 && p <= 100).sort((x, y) => x - y);
+                const seen = new Set();
+                const body = stops.map((p) => {
+                    const pctStr = p.toFixed(3);
+                    if (seen.has(pctStr))
+                        return "";
+                    seen.add(pctStr);
+                    const parts = win.map((w) => {
+                        const span = w.endPct - w.startPct;
+                        const localT = span > 0 ? Math.min(1, Math.max(0, (p - w.startPct) / span)) : (p >= w.endPct ? 1 : 0);
+                        return { property: w.property, val: interpolateCssValue(w.from, w.to, w.ease(localT)) };
+                    });
+                    return `      ${pctStr}% { ${composeAnimStop(parts)} }`;
+                }).filter((s) => s !== "").join("\n");
+                out.push(`    @keyframes ${animName} {
+${body}
+    }
+    .anim-${a.animId} { animation: ${animName} ${totalSec.toFixed(2)}s linear infinite;${originDecl} }`);
+                continue;
+            }
             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
@@ -971,8 +1060,8 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
                 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)} }
+      0% { ${declFrom} }
+      100% { ${declTo} }
     }
     .anim-${a.animId} { animation: ${animName} ${a.duration}ms ${easing} ${startMs.toFixed(0)}ms ${iterations}${direction} both;${originDecl} }`);
             }
@@ -981,10 +1070,10 @@ function buildIntraFrameAnimationCss(frames, frameTiming, totalSec) {
                 // [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)} }
+      0% { ${declFrom} }
+      ${startPct.toFixed(3)}% { ${declFrom} }
+      ${endPct.toFixed(3)}% { ${declTo} }
+      100% { ${declTo} }
     }
     .anim-${a.animId} { animation: ${animName} ${totalSec.toFixed(2)}s ${easing} infinite;${originDecl} }`);
             }

package/dist/animation/easing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Easing evaluation + CSS-value interpolation for BAKED keyframe sampling
+ * (DM-1517). Used by the animator when a fused animation's tracks have different
+ * windows/easings and so can't share one `animation-timing-function`: instead of
+ * a from→to pair, the animator samples each track's eased value at many stops
+ * and emits them with `linear` timing (the easing is baked into the values), so
+ * several property tracks with independent timing still animate as ONE CSS
+ * animation — one timeline, immune to Firefox's off-main-thread desync
+ * (docs/84). Pure functions, no I/O.
+ */
+/** A normalized easing: progress `t` in [0,1] → eased output in [0,1]. */
+export type EasingFn = (t: number) => number;
+/** Solve a CSS `cubic-bezier(x1,y1,x2,y2)` for y at x=t (endpoints (0,0),(1,1)). */
+export declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): EasingFn;
+/**
+ * Parse a CSS easing string into an `EasingFn`. Handles the named keywords and
+ * `cubic-bezier(a,b,c,d)`. `step`/`steps()` and anything unrecognized fall back
+ * to `linear` — the sampled path is for smooth curves; discrete steps don't need
+ * baking (they'd be authored as explicit stops).
+ */
+export declare function resolveEasing(css: string | undefined): EasingFn;
+/**
+ * Interpolate between two CSS value strings at `t` in [0,1] by matching their
+ * numeric tokens pairwise and lerping each, keeping the surrounding literal
+ * skeleton. Handles the value shapes the intra-frame animator produces —
+ * `"0.3"`→`"1"` (scale), `"-0.6em"`→`"0em"` (translate), `"240px"`→`"0px"`,
+ * `"inset(-10% 100% -10% 0)"`→`"inset(-10% 0% -10% 0)"` (clip-path). If the two
+ * strings don't share the same non-numeric skeleton (e.g. different units), it
+ * can't be smoothly interpolated, so it steps at the midpoint.
+ */
+export declare function interpolateCssValue(from: string, to: string, t: number): string;

package/dist/animation/overlay-schema.d.ts

@@ -259,5 +259,22 @@ export declare const intraFrameAnimationSchema: z.ZodObject<{
     delay: z.ZodOptional<z.ZodNumber>;
     repeat: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"infinite">]>>;
     alternate: z.ZodOptional<z.ZodBoolean>;
+    fuse: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        property: z.ZodEnum<{
+            width: "width";
+            clipPath: "clipPath";
+            height: "height";
+            transform: "transform";
+            opacity: "opacity";
+            scale: "scale";
+            translateX: "translateX";
+            translateY: "translateY";
+        }>;
+        from: z.ZodString;
+        to: z.ZodString;
+        duration: z.ZodOptional<z.ZodNumber>;
+        delay: z.ZodOptional<z.ZodNumber>;
+        easing: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type IntraFrameAnimation = z.infer<typeof intraFrameAnimationSchema>;

package/dist/animation/overlay-schema.js

@@ -222,4 +222,35 @@ export const intraFrameAnimationSchema = z.object({
     repeat: z.union([z.number(), z.literal("infinite")]).optional(),
     /** DM-869: when true, the loop ping-pongs `from`→`to`→`from` (CSS `animation-direction: alternate`). */
     alternate: z.boolean().optional(),
+    /**
+     * DM-1512/1513: additional property tracks fused into THIS animation so they
+     * animate as ONE CSS animation on one element — a single timeline that can't
+     * desync. Firefox composites `opacity`/`transform` off the main thread and,
+     * under load, can demote one of two SEPARATE animations to the main thread
+     * while the other stays on the compositor, drifting them apart (e.g. a fade
+     * running ahead of its slide/scale). A single animation is always sampled at
+     * one instant regardless of thread, so fusing removes that failure mode.
+     *
+     * By default each fused track rides the primary entry's window (`delay` +
+     * `duration`) and `easing`, emitted as from/to stops. A track MAY override
+     * `duration` / `delay` / `easing` for independent timing (e.g. a fast fade over
+     * a slower slide, or a different curve) — when any track does, the whole
+     * animation is emitted by SAMPLING each track's eased value over its own window
+     * at many stops with `linear` timing (DM-1517), so it stays one animation / one
+     * timeline. The primary `property` is track 0; these are the rest. Multiple
+     * transform-family tracks (`translateX`/`translateY`/`scale`/`transform`) are
+     * composed into a single `transform:` declaration; other properties (`opacity`,
+     * `clip-path`, …) emit alongside. See docs/84-viewer-browser-support.md.
+     */
+    fuse: z.array(z.object({
+        property: z.enum(["width", "height", "opacity", "transform", "translateX", "translateY", "scale", "clipPath"]),
+        from: z.string(),
+        to: z.string(),
+        /** Override the primary's duration for this track (ms). Triggers sampling. */
+        duration: z.number().optional(),
+        /** Override the primary's delay for this track (ms). Triggers sampling. */
+        delay: z.number().optional(),
+        /** Override the primary's easing for this track. Triggers sampling. */
+        easing: z.string().optional(),
+    })).optional(),
 });

package/dist/cli/animate.d.ts

@@ -678,6 +678,23 @@ export declare const animateConfigSchema: z.ZodObject<{
                 translateY: "translateY";
             }>;
             transformOrigin: z.ZodOptional<z.ZodString>;
+            fuse: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                property: z.ZodEnum<{
+                    width: "width";
+                    clipPath: "clipPath";
+                    height: "height";
+                    transform: "transform";
+                    opacity: "opacity";
+                    scale: "scale";
+                    translateX: "translateX";
+                    translateY: "translateY";
+                }>;
+                from: z.ZodString;
+                to: z.ZodString;
+                duration: z.ZodOptional<z.ZodNumber>;
+                delay: z.ZodOptional<z.ZodNumber>;
+                easing: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
             selector: z.ZodString;
             repeat: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"infinite">]>>;
         }, z.core.$strip>>>;

package/dist/cli/animate.js

@@ -734,6 +734,7 @@ async function buildCapturedFrame(fc, i, ctx) {
                 repeat: a.repeat,
                 alternate: a.alternate,
                 transformOrigin: a.transformOrigin,
+                fuse: a.fuse,
             });
         }
     }

package/dist/templates/builtin/kinetic-text.d.ts

@@ -10,9 +10,14 @@
  * Same two animation constraints as `background-loop` (doc 71): only one
  * intra-frame animation applies per captured element, and SVG transforms are
  * origin-(0,0). So each animated unit is a `.kt-w-N` transform-wrapper (rise /
- * slide via origin-safe translateX/translateY) around a `.kt-wi-N` opacity-inner
- * (fade). The reveal is one-shot (no repeat): units hold `from` until their
- * staggered turn, animate in, then hold `to` so the headline stays assembled.
+ * slide via origin-safe translateX/translateY) around a `.kt-wi-N` inner span.
+ * DM-1512/1513: the move and the fade are FUSED into that one wrapper animation
+ * (via the animation entry's `fuse` list) rather than a separate opacity
+ * animation on the inner span — one CSS timeline can't desync under Firefox's
+ * off-main-thread compositing (see docs/84). The `.kt-wi-N` inner span is now
+ * inert (it just carries the glyph). The reveal is one-shot (no repeat): units
+ * hold `from` until their staggered turn, animate in, then hold `to` so the
+ * headline stays assembled.
  */
 import { z } from "zod";
 import type { AnimateConfig } from "../../cli/animate.js";

package/dist/templates/builtin/kinetic-text.js

@@ -10,9 +10,14 @@
  * Same two animation constraints as `background-loop` (doc 71): only one
  * intra-frame animation applies per captured element, and SVG transforms are
  * origin-(0,0). So each animated unit is a `.kt-w-N` transform-wrapper (rise /
- * slide via origin-safe translateX/translateY) around a `.kt-wi-N` opacity-inner
- * (fade). The reveal is one-shot (no repeat): units hold `from` until their
- * staggered turn, animate in, then hold `to` so the headline stays assembled.
+ * slide via origin-safe translateX/translateY) around a `.kt-wi-N` inner span.
+ * DM-1512/1513: the move and the fade are FUSED into that one wrapper animation
+ * (via the animation entry's `fuse` list) rather than a separate opacity
+ * animation on the inner span — one CSS timeline can't desync under Firefox's
+ * off-main-thread compositing (see docs/84). The `.kt-wi-N` inner span is now
+ * inert (it just carries the glyph). The reveal is one-shot (no repeat): units
+ * hold `from` until their staggered turn, animate in, then hold `to` so the
+ * headline stays assembled.
  */
 import { runSingleFrameGenerator } from "../run-single-frame.js";
 import { z } from "zod";
@@ -256,39 +261,41 @@ export function buildKineticAnimations(p, plan) {
     // `boomerang`: each unit assembles then disassembles forever, phase-offset by
     // its stagger. `loop`: one-shot; the infinitely-looping scene replays it.
     const loopFields = p.loop === "boomerang" ? { repeat: "infinite", alternate: true } : {};
+    // DM-1512/1513: each unit's move + fade is emitted as ONE animation on the
+    // wrapper (`.kt-w-*`), with the fade FUSED into the move via `fuse` rather than
+    // a separate opacity animation on the inner span. One CSS animation is one
+    // timeline, so the fade and the move stay in perfect sync — immune to
+    // Firefox's off-main-thread compositing, which under load demotes one of two
+    // SEPARATE animations to the main thread and drifts them apart (a fade running
+    // ahead of its slide/scale). The fused fade rides the move's window + easing.
+    // See docs/84-viewer-browser-support.md.
+    const fade = [{ property: "opacity", from: "0", to: "1" }];
     for (const line of plan.lines) {
         for (const units of line) {
             for (const u of units) {
                 const delay = u.index * p.staggerMs;
-                // Fade in (all variants), on the inner span.
-                anims.push({
-                    selector: `.kt-wi-${u.index}`,
-                    property: "opacity",
-                    from: "0",
-                    to: "1",
-                    duration: p.revealMs,
-                    delay,
-                    easing: "ease-out",
-                    ...loopFields,
-                });
-                // Move/reveal in, on the wrapper. `fade` has no wrapper animation.
+                const sel = `.kt-w-${u.index}`;
                 if (p.variant === "rise") {
-                    anims.push({ selector: `.kt-w-${u.index}`, property: "translateY", from: "0.55em", to: "0em", duration: p.revealMs, delay, easing: "cubic-bezier(0.22,1,0.36,1)", ...loopFields });
+                    anims.push({ selector: sel, property: "translateY", from: "0.55em", to: "0em", duration: p.revealMs, delay, easing: "cubic-bezier(0.22,1,0.36,1)", fuse: fade, ...loopFields });
                 }
                 else if (p.variant === "slide") {
-                    anims.push({ selector: `.kt-w-${u.index}`, property: "translateX", from: "-0.6em", to: "0em", duration: p.revealMs, delay, easing: "cubic-bezier(0.22,1,0.36,1)", ...loopFields });
+                    anims.push({ selector: sel, property: "translateX", from: "-0.6em", to: "0em", duration: p.revealMs, delay, easing: "cubic-bezier(0.22,1,0.36,1)", fuse: fade, ...loopFields });
                 }
                 else if (p.variant === "clip") {
                     // Left-to-right wipe via the `clipPath` intra-frame property (doc 08):
                     // `inset(0 100% 0 0)` clips everything but the left edge; animating the
                     // right inset to 0 reveals the unit left→right.
-                    anims.push({ selector: `.kt-w-${u.index}`, property: "clipPath", from: "inset(-10% 100% -10% 0)", to: "inset(-10% 0% -10% 0)", duration: p.revealMs, delay, easing: "cubic-bezier(0.22,1,0.36,1)", ...loopFields });
+                    anims.push({ selector: sel, property: "clipPath", from: "inset(-10% 100% -10% 0)", to: "inset(-10% 0% -10% 0)", duration: p.revealMs, delay, easing: "cubic-bezier(0.22,1,0.36,1)", fuse: fade, ...loopFields });
                 }
                 else if (p.variant === "pop") {
                     // Scale-pop: grow from small to full about the unit's OWN CENTER
                     // (`transformOrigin`, DM-1297), with a back-eased overshoot. Without the
                     // center origin an SVG scale would shrink toward the canvas corner.
-                    anims.push({ selector: `.kt-w-${u.index}`, property: "scale", from: "0.3", to: "1", duration: p.revealMs, delay, easing: "cubic-bezier(0.34,1.56,0.64,1)", transformOrigin: "center", ...loopFields });
+                    anims.push({ selector: sel, property: "scale", from: "0.3", to: "1", duration: p.revealMs, delay, easing: "cubic-bezier(0.34,1.56,0.64,1)", transformOrigin: "center", fuse: fade, ...loopFields });
+                }
+                else {
+                    // `fade` variant: no move — just the fade, on the wrapper.
+                    anims.push({ selector: sel, property: "opacity", from: "0", to: "1", duration: p.revealMs, delay, easing: "ease-out", ...loopFields });
                 }
             }
         }

package/dist/templates/builtin/lower-third.d.ts

@@ -37,9 +37,10 @@ export declare const lowerThirdParamsSchema: z.ZodObject<{
 export type LowerThirdParams = z.infer<typeof lowerThirdParamsSchema>;
 /**
  * Build the standalone HTML for the banner. Pure function (no I/O) so it's unit-
- * testable without a browser. The `.lt` wrapper fades (opacity) and the inner
- * `.lt-panel` slides (translateY) — two distinct selectors so the intra-frame
- * animations target different elements and never collide on one animId.
+ * testable without a browser. The `.lt-panel` slides (translateY) with the fade
+ * (opacity) FUSED into the same animation (DM-1512/1513) — one CSS timeline so
+ * the two can't desync under Firefox's off-main-thread compositing. `.lt` is a
+ * bare flex wrapper around the single `.lt-panel`.
  */
 export declare function buildLowerThirdHtml(p: LowerThirdParams): string;
 export declare const lowerThirdTemplate: Template<LowerThirdParams>;

package/dist/templates/builtin/lower-third.js

@@ -39,9 +39,10 @@ function alignmentFor(position) {
 }
 /**
  * Build the standalone HTML for the banner. Pure function (no I/O) so it's unit-
- * testable without a browser. The `.lt` wrapper fades (opacity) and the inner
- * `.lt-panel` slides (translateY) — two distinct selectors so the intra-frame
- * animations target different elements and never collide on one animId.
+ * testable without a browser. The `.lt-panel` slides (translateY) with the fade
+ * (opacity) FUSED into the same animation (DM-1512/1513) — one CSS timeline so
+ * the two can't desync under Firefox's off-main-thread compositing. `.lt` is a
+ * bare flex wrapper around the single `.lt-panel`.
  */
 export function buildLowerThirdHtml(p) {
     const { justify, align } = alignmentFor(p.position);
@@ -109,9 +110,13 @@ export const lowerThirdTemplate = {
             width: params.width,
             height: params.height,
             durationMs: params.holdMs,
+            // DM-1512/1513: slide + fade FUSED into one animation on `.lt-panel` (the
+            // sole child of `.lt`, so fading it is equivalent to fading `.lt`). One
+            // CSS animation = one timeline, so the fade and slide can't desync under
+            // Firefox's off-main-thread compositing under load. The fade rides the
+            // slide's 600ms/cubic window (was a separate 450ms/ease-out track).
             animations: [
-                { selector: ".lt", property: "opacity", from: "0", to: "1", duration: 450, easing: "ease-out" },
-                { selector: ".lt-panel", property: "translateY", from: rise, to: "0px", duration: 600, easing: "cubic-bezier(0.22,1,0.36,1)" },
+                { selector: ".lt-panel", property: "translateY", from: rise, to: "0px", duration: 600, easing: "cubic-bezier(0.22,1,0.36,1)", fuse: [{ property: "opacity", from: "0", to: "1" }] },
             ],
         });
     },

package/dist/utils/keyframe-pad.d.ts

@@ -22,3 +22,27 @@ export declare const KEYFRAME_EPSILON: {
 export declare function padBefore(pct: number, epsilon: number, precision: number): string;
 /** Percentage nudged UP by `epsilon` (capped at 100), printed at `precision`. */
 export declare function padAfter(pct: number, epsilon: number, precision: number): string;
+/**
+ * DM-1511: Firefox composites a `visibility` animation off the main-thread /
+ * opacity clock. At a step-end frame hand-off it can drop the OUTGOING frame's
+ * paint a few compositor frames BEFORE the incoming frame starts painting,
+ * flashing the transparent page-through gap for ~30-70ms — the "hard flash to
+ * white/transparent at cut points" bug. Chromium and Safari keep the two in
+ * lock-step, so a sub-millisecond overlap is enough there; Firefox is not.
+ *
+ * The fix is to drive the visual cut with `opacity` alone (Firefox composites
+ * that correctly, and the tight `cull` overlap already guarantees a seamless
+ * hand-off) and use `visibility` ONLY as the paint-cull gate (DM-599), with its
+ * visible window padded WIDE — a fixed wall-clock margin on each side — so
+ * adjacent frames' paint windows overlap well past any compositor slop. The
+ * frame is `opacity:0` outside its true window, so the wide visibility window is
+ * never itself visible; it only means a frame is *paintable* a little early and
+ * a little late, which is harmless.
+ *
+ * Expressed as wall-clock (not a fixed %) so the overlap always beats the
+ * compositor slop, which is a handful of vsync frames regardless of how long the
+ * scene is. 150 ms is ~2x the largest gap observed (~70 ms).
+ */
+export declare const VISIBILITY_CULL_OVERLAP_MS = 150;
+/** `VISIBILITY_CULL_OVERLAP_MS` as a percentage of a scene `totalMs` long. */
+export declare function cullOverlapPct(totalMs: number): number;

package/dist/utils/keyframe-pad.js

@@ -26,3 +26,29 @@ export function padBefore(pct, epsilon, precision) {
 export function padAfter(pct, epsilon, precision) {
     return Math.min(100, pct + epsilon).toFixed(precision);
 }
+/**
+ * DM-1511: Firefox composites a `visibility` animation off the main-thread /
+ * opacity clock. At a step-end frame hand-off it can drop the OUTGOING frame's
+ * paint a few compositor frames BEFORE the incoming frame starts painting,
+ * flashing the transparent page-through gap for ~30-70ms — the "hard flash to
+ * white/transparent at cut points" bug. Chromium and Safari keep the two in
+ * lock-step, so a sub-millisecond overlap is enough there; Firefox is not.
+ *
+ * The fix is to drive the visual cut with `opacity` alone (Firefox composites
+ * that correctly, and the tight `cull` overlap already guarantees a seamless
+ * hand-off) and use `visibility` ONLY as the paint-cull gate (DM-599), with its
+ * visible window padded WIDE — a fixed wall-clock margin on each side — so
+ * adjacent frames' paint windows overlap well past any compositor slop. The
+ * frame is `opacity:0` outside its true window, so the wide visibility window is
+ * never itself visible; it only means a frame is *paintable* a little early and
+ * a little late, which is harmless.
+ *
+ * Expressed as wall-clock (not a fixed %) so the overlap always beats the
+ * compositor slop, which is a handful of vsync frames regardless of how long the
+ * scene is. 150 ms is ~2x the largest gap observed (~70 ms).
+ */
+export const VISIBILITY_CULL_OVERLAP_MS = 150;
+/** `VISIBILITY_CULL_OVERLAP_MS` as a percentage of a scene `totalMs` long. */
+export function cullOverlapPct(totalMs) {
+    return totalMs > 0 ? (VISIBILITY_CULL_OVERLAP_MS / totalMs) * 100 : 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domotion-svg",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "DOM-to-animated-SVG renderer. Captures HTML/CSS via Playwright Chromium and converts it to self-contained SVG with CSS animations — pixel-faithful demos that scale crisply and load lazily.",
   "license": "MIT",
   "author": "Brian Westphal",

package/schemas/animate-config.schema.json

@@ -1355,6 +1355,47 @@
                 "alternate": {
                   "type": "boolean"
                 },
+                "fuse": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "property": {
+                        "type": "string",
+                        "enum": [
+                          "width",
+                          "height",
+                          "opacity",
+                          "transform",
+                          "translateX",
+                          "translateY",
+                          "scale",
+                          "clipPath"
+                        ]
+                      },
+                      "from": {
+                        "type": "string"
+                      },
+                      "to": {
+                        "type": "string"
+                      },
+                      "duration": {
+                        "type": "number"
+                      },
+                      "delay": {
+                        "type": "number"
+                      },
+                      "easing": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "property",
+                      "from",
+                      "to"
+                    ]
+                  }
+                },
                 "selector": {
                   "type": "string"
                 }