domotion-svg 0.2.2 → 0.3.2

package/dist/scroll/hoist-sticky.test.js

@@ -0,0 +1,154 @@
+import { describe, expect, it } from "vitest";
+import { extractStickyWindows } from "./hoist-sticky.js";
+function el(partial, position = "static") {
+    return {
+        text: partial.text ?? "",
+        width: partial.width ?? 100,
+        height: partial.height ?? 20,
+        children: partial.children ?? [],
+        ...partial,
+        styles: {
+            position,
+            ...(partial.styles ?? {}),
+        },
+    };
+}
+// Each segment-tree below is just a list of top-level siblings; production
+// trees go several levels deep but `extractStickyWindows` walks recursively
+// so shallow trees exercise the same logic.
+describe("extractStickyWindows", () => {
+    it("never stuck: sticky element whose y strictly decreases across segments → left inline, no overlays", () => {
+        const seg0 = [el({ tag: "div", x: 0, y: 0 }), el({ tag: "nav", x: 0, y: 200, width: 800, height: 60 }, "sticky")];
+        const seg1 = [el({ tag: "div", x: 0, y: 0 }), el({ tag: "nav", x: 0, y: 100, width: 800, height: 60 }, "sticky")];
+        const seg2 = [el({ tag: "div", x: 0, y: 0 }), el({ tag: "nav", x: 0, y: 0, width: 800, height: 60 }, "sticky")];
+        const r = extractStickyWindows([seg0, seg1, seg2]);
+        expect(r.overlays).toEqual([]);
+        // Trees are unmodified (returned by reference when no strikes apply).
+        expect(r.stripped[0]).toBe(seg0);
+        expect(r.stripped[1]).toBe(seg1);
+        expect(r.stripped[2]).toBe(seg2);
+    });
+    it("always stuck: sticky element at the same y in every segment → one overlay spanning all, stripped from every tree", () => {
+        const stickyEl = (text) => el({ tag: "nav", text, x: 0, y: 0, width: 800, height: 60 }, "sticky");
+        const seg0 = [el({ tag: "div", x: 0, y: 0 }), stickyEl("a")];
+        const seg1 = [el({ tag: "div", x: 0, y: 0 }), stickyEl("b")];
+        const seg2 = [el({ tag: "div", x: 0, y: 0 }), stickyEl("c")];
+        const r = extractStickyWindows([seg0, seg1, seg2]);
+        expect(r.overlays).toHaveLength(1);
+        expect(r.overlays[0].firstSegmentIdx).toBe(0);
+        expect(r.overlays[0].lastSegmentIdx).toBe(2);
+        // Each segment has the sticky element stripped — only the original div remains.
+        for (const tree of r.stripped) {
+            expect(tree).toHaveLength(1);
+            expect(tree[0].tag).toBe("div");
+        }
+    });
+    it("stuck mid-scroll: sticky scrolls for first K segments then stays → inline for K, overlay for the rest", () => {
+        // Seg 0..1: y decreases (in-flow). Seg 2..4: y stays at 60 (stuck).
+        const stick = (y) => el({ tag: "nav", x: 0, y, width: 800, height: 50 }, "sticky");
+        const seg0 = [el({ tag: "main", x: 0, y: 0 }), stick(300)];
+        const seg1 = [el({ tag: "main", x: 0, y: 0 }), stick(180)];
+        const seg2 = [el({ tag: "main", x: 0, y: 0 }), stick(60)];
+        const seg3 = [el({ tag: "main", x: 0, y: 0 }), stick(60)];
+        const seg4 = [el({ tag: "main", x: 0, y: 0 }), stick(60)];
+        const r = extractStickyWindows([seg0, seg1, seg2, seg3, seg4]);
+        expect(r.overlays).toHaveLength(1);
+        expect(r.overlays[0].firstSegmentIdx).toBe(2);
+        expect(r.overlays[0].lastSegmentIdx).toBe(4);
+        // Segs 0–1: still contain the nav (it's in flow, still scrolling).
+        expect(r.stripped[0].find((n) => n.tag === "nav")).not.toBeUndefined();
+        expect(r.stripped[1].find((n) => n.tag === "nav")).not.toBeUndefined();
+        // Segs 2–4: nav has been stripped (it's now on the overlay).
+        expect(r.stripped[2].find((n) => n.tag === "nav")).toBeUndefined();
+        expect(r.stripped[3].find((n) => n.tag === "nav")).toBeUndefined();
+        expect(r.stripped[4].find((n) => n.tag === "nav")).toBeUndefined();
+    });
+    it("two stuck windows: sticks, un-sticks, sticks again → two overlay entries", () => {
+        // Seg 0: in-flow (y=400). Seg 1–2: stuck (y=0). Seg 3: in-flow (y=200).
+        // Seg 4–5: stuck again (y=0).
+        const stick = (y) => el({ tag: "nav", x: 0, y, width: 800, height: 50 }, "sticky");
+        const trees = [
+            [stick(400)],
+            [stick(0)],
+            [stick(0)],
+            [stick(200)],
+            [stick(0)],
+            [stick(0)],
+        ];
+        const r = extractStickyWindows(trees);
+        expect(r.overlays).toHaveLength(2);
+        expect(r.overlays.map((o) => [o.firstSegmentIdx, o.lastSegmentIdx])).toEqual([[1, 2], [4, 5]]);
+        // Seg 0, 3 retain the nav (in-flow).
+        expect(r.stripped[0]).toHaveLength(1);
+        expect(r.stripped[3]).toHaveLength(1);
+        // Seg 1, 2, 4, 5 have the nav stripped.
+        expect(r.stripped[1]).toHaveLength(0);
+        expect(r.stripped[2]).toHaveLength(0);
+        expect(r.stripped[4]).toHaveLength(0);
+        expect(r.stripped[5]).toHaveLength(0);
+    });
+    it("single-segment 'stuck' (length 1 run) does NOT qualify — element stays inline", () => {
+        // A sticky element captured at the same y in only ONE segment is not
+        // stuck (could just be a momentary zero-velocity sample); needs ≥ 2
+        // consecutive same-y segments to count.
+        const stick = (y) => el({ tag: "nav", x: 0, y, width: 800, height: 50 }, "sticky");
+        const r = extractStickyWindows([
+            [stick(100)],
+            [stick(50)],
+            [stick(50)], // start of a potential run (but only 1 segment so far)
+            [stick(0)], // run breaks here
+        ]);
+        // segs 1–2 are at the same y → that's a stuck window of length 2. Length-1
+        // "windows" wouldn't qualify, but 2 does. This case demonstrates the ≥2
+        // threshold actually catches its boundary.
+        expect(r.overlays).toHaveLength(1);
+        expect(r.overlays[0].firstSegmentIdx).toBe(1);
+        expect(r.overlays[0].lastSegmentIdx).toBe(2);
+    });
+    it("non-sticky elements are untouched even at constant y", () => {
+        // A normal element at the same x/y in every segment should NOT be hoisted —
+        // it's not sticky.
+        const trees = [
+            [el({ tag: "header", x: 0, y: 0, width: 800, height: 60 }, "static")],
+            [el({ tag: "header", x: 0, y: 0, width: 800, height: 60 }, "static")],
+            [el({ tag: "header", x: 0, y: 0, width: 800, height: 60 }, "static")],
+        ];
+        const r = extractStickyWindows(trees);
+        expect(r.overlays).toEqual([]);
+    });
+    it("doesn't mutate the input trees", () => {
+        const stickyChild = el({ tag: "nav", x: 0, y: 0, width: 800, height: 50 }, "sticky");
+        const body0 = el({
+            tag: "body", x: 0, y: 0, width: 800, height: 600,
+            children: [el({ tag: "main", x: 0, y: 60 }), stickyChild],
+        });
+        const body1 = el({
+            tag: "body", x: 0, y: 0, width: 800, height: 600,
+            children: [el({ tag: "main", x: 0, y: 60 }), stickyChild],
+        });
+        const tree0 = [body0];
+        const tree1 = [body1];
+        const originalChildren0 = body0.children;
+        extractStickyWindows([tree0, tree1]);
+        expect(body0.children).toBe(originalChildren0);
+        expect(body0.children).toHaveLength(2);
+    });
+    it("matches sticky elements across segments by (tag, size, path-in-tree)", () => {
+        // Same tag/size, but different path-in-tree → treated as DIFFERENT
+        // logical elements and NOT collapsed.
+        const stick1 = (y) => el({ tag: "nav", x: 0, y, width: 800, height: 50 }, "sticky");
+        const trees = [
+            // Sticky nav as the 0th child.
+            [stick1(0), el({ tag: "main", x: 0, y: 50 })],
+            // Sticky nav as the 1st child (different path → different identity).
+            [el({ tag: "main", x: 0, y: 50 }), stick1(0)],
+            [stick1(0), el({ tag: "main", x: 0, y: 50 })],
+        ];
+        const r = extractStickyWindows(trees);
+        // Neither nav matches across segments (path-in-tree differs), so no
+        // stuck windows form. The two seg-0 / seg-2 occurrences would
+        // otherwise be at the same y but only 2 segments are involved and
+        // they're not consecutive — so no run.
+        expect(r.overlays).toEqual([]);
+    });
+});

package/dist/scroll/pattern.d.ts

@@ -1,11 +1,17 @@
 /**
- * Scroll-pattern grammar — parser (DM-605, design from DM-604).
+ * Scroll-pattern grammar — parser.
  *
  * Pure parser. Input string → AST. Does NOT evaluate `selector(...)` against
- * a DOM, nor execute the scroll plan — that's DM-607 (scroll executor).
+ * a DOM, nor execute the scroll plan — that's the responsibility of
+ * `src/scroll/executor.ts`.
  *
- * Grammar reference: `dm604-scroll-grammar.txt` (signed-off draft attached
- * to DM-604). Key rules in brief:
+ * **Canonical grammar reference: `docs/37-scroll-pattern-grammar.md`.** That
+ * doc carries the full EBNF, axis-resolution rules, `until` semantics, speed
+ * / duration / easing handling, and worked examples. When changing this file
+ * (tokenizer, parser, AST shape, error reporting) update doc 37 in the same
+ * commit so the surface stays in sync.
+ *
+ * Key rules in brief:
  *
  *   pattern        = top-segment { "," top-segment }
  *   top-segment    = "(" pattern ")" [until]
@@ -42,8 +48,19 @@ export interface ScrollAction {
     /** Explicit direction prefix; absent when the action's direction is implied. */
     direction?: "up" | "down" | "left" | "right";
     target: ScrollTarget;
-    /** From the `/<duration>` suffix, in milliseconds. Absent → speed-derived. */
+    /**
+     * From the `/<duration>` suffix, in milliseconds. Absent → derived from
+     * speed (either `speedPxPerSec` below, or the executor's inherited
+     * `defaultSpeed`). Mutually exclusive with `speedPxPerSec` at parse time.
+     */
     durationMs?: number;
+    /**
+     * From the `@<n>pxps` suffix, in pixels-per-second. Overrides the
+     * executor's inherited `defaultSpeed` for THIS action only. Mutually
+     * exclusive with `durationMs` at parse time — the grammar accepts either
+     * `/<duration>` OR `@<speed>` on a single action, not both.
+     */
+    speedPxPerSec?: number;
     /** From the `[easing-name]` suffix. Absent → default (`ease-out`). */
     easing?: Easing;
 }

package/dist/scroll/pattern.js

@@ -1,11 +1,17 @@
 /**
- * Scroll-pattern grammar — parser (DM-605, design from DM-604).
+ * Scroll-pattern grammar — parser.
  *
  * Pure parser. Input string → AST. Does NOT evaluate `selector(...)` against
- * a DOM, nor execute the scroll plan — that's DM-607 (scroll executor).
+ * a DOM, nor execute the scroll plan — that's the responsibility of
+ * `src/scroll/executor.ts`.
  *
- * Grammar reference: `dm604-scroll-grammar.txt` (signed-off draft attached
- * to DM-604). Key rules in brief:
+ * **Canonical grammar reference: `docs/37-scroll-pattern-grammar.md`.** That
+ * doc carries the full EBNF, axis-resolution rules, `until` semantics, speed
+ * / duration / easing handling, and worked examples. When changing this file
+ * (tokenizer, parser, AST shape, error reporting) update doc 37 in the same
+ * commit so the surface stays in sync.
+ *
+ * Key rules in brief:
  *
  *   pattern        = top-segment { "," top-segment }
  *   top-segment    = "(" pattern ")" [until]
@@ -77,6 +83,11 @@ function tokenize(source) {
             i++;
             continue;
         }
+        if (ch === "@") {
+            tokens.push({ kind: "at", text: "@", start: i, end: i + 1 });
+            i++;
+            continue;
+        }
         if (ch === "[") {
             tokens.push({ kind: "lbracket", text: "[", start: i, end: i + 1 });
             i++;
@@ -146,6 +157,11 @@ function tokenize(source) {
             else if (unit === "s" || unit === "ms") {
                 tokens.push({ kind: "duration", text: numText + unit, num, unit, start: numStart, end: i });
             }
+            else if (unit === "pxps") {
+                // <n>pxps — per-action speed (pixels per second). Only valid after
+                // the `@` speed-suffix marker; the parser enforces that placement.
+                tokens.push({ kind: "speed", text: numText + unit, num, unit, start: numStart, end: i });
+            }
             else if (unit === "") {
                 tokens.push({ kind: "number", text: numText, num, start: numStart, end: i });
             }
@@ -258,16 +274,33 @@ class Parser {
         }
         const target = this.parseScrollTarget();
         let durationMs;
+        let speedPxPerSec;
         let easing;
+        // Duration suffix (`/<duration>`) and speed suffix (`@<n>pxps`) are
+        // mutually exclusive on a single action — either pin the action's time,
+        // or pin its speed, not both. The order in which they're tried doesn't
+        // matter since the OTHER branch fires an explicit error if it's seen.
         if (this.peek().kind === "slash") {
             this.consume("slash");
             const dur = this.consume("duration");
             durationMs = durationToMs(dur);
+            if (this.peek().kind === "at") {
+                const conflict = this.peek();
+                throw new ScrollPatternError("Scroll action cannot carry both a `/<duration>` and `@<speed>` suffix", this.source, conflict.start);
+            }
+        }
+        else if (this.peek().kind === "at") {
+            this.consume("at");
+            const sp = this.consume("speed");
+            if (!(sp.num != null && sp.num > 0)) {
+                throw new ScrollPatternError(`Speed must be a positive number of px/s (got "${sp.text}")`, this.source, sp.start);
+            }
+            speedPxPerSec = sp.num;
         }
         if (this.peek().kind === "lbracket") {
             easing = this.parseEasingSuffix();
         }
-        return { kind: "scroll", direction, target, durationMs, easing };
+        return { kind: "scroll", direction, target, durationMs, speedPxPerSec, easing };
     }
     parseScrollTarget() {
         const tok = this.peek();
@@ -437,11 +470,26 @@ function durationToMs(t) {
         return t.num;
     throw new ScrollPatternError(`Unknown duration unit "${t.unit}"`, "", t.start);
 }
+function lengthTokenUnit(t) {
+    // The tokenizer at `tokenize()` only emits `kind: "length"` when unit is
+    // exactly "px" or "%" — this check defends against tokenizer drift so a
+    // future unit-set change can't silently slip through as an `unknown` unit.
+    if (t.unit !== "px" && t.unit !== "%") {
+        throw new ScrollPatternError(`Internal: length token has non-length unit "${String(t.unit)}"`, "", t.start);
+    }
+    return t.unit;
+}
+function lengthTokenNum(t) {
+    if (typeof t.num !== "number" || !Number.isFinite(t.num)) {
+        throw new ScrollPatternError(`Internal: length token missing numeric value`, "", t.start);
+    }
+    return t.num;
+}
 function lengthTokenToLength(t) {
-    return { value: t.num, unit: t.unit };
+    return { value: lengthTokenNum(t), unit: lengthTokenUnit(t) };
 }
 function lengthTokenToSignedLength(t, sign) {
-    return { sign, value: t.num, unit: t.unit };
+    return { sign, value: lengthTokenNum(t), unit: lengthTokenUnit(t) };
 }
 // ── Public entry point ─────────────────────────────────────────────────────
 /**

package/dist/scroll/pattern.test.js

@@ -157,6 +157,48 @@ describe("parseScrollPattern: /<duration> suffix", () => {
         expect(() => parseScrollPattern("720px/")).toThrow(ScrollPatternError);
     });
 });
+// ── Speed suffix @<n>pxps ────────────────────────────────────────────────────
+describe("parseScrollPattern: @<speed> suffix", () => {
+    it("attaches to delta", () => {
+        const a = onlyAction("720px@800pxps");
+        expect(a.speedPxPerSec).toBe(800);
+        expect(a.durationMs).toBeUndefined();
+    });
+    it("attaches to absolute target with direction prefix", () => {
+        const a = onlyAction("down:bottom@1200pxps");
+        expect(a.speedPxPerSec).toBe(1200);
+        expect(a.target).toEqual({ kind: "absolute", anchor: { kind: "named", name: "bottom" }, offsets: [] });
+        expect(a.direction).toBe("down");
+    });
+    it("attaches to anchor with offset arithmetic", () => {
+        const a = onlyAction("up:top + 200px@500pxps");
+        expect(a.speedPxPerSec).toBe(500);
+        expect(a.durationMs).toBeUndefined();
+    });
+    it("speed and easing combine", () => {
+        const a = onlyAction("720px@600pxps[ease-in]");
+        expect(a.speedPxPerSec).toBe(600);
+        expect(a.easing).toEqual({ kind: "named", name: "ease-in" });
+    });
+    it("decimal speed accepted", () => {
+        const a = onlyAction("720px@1500.5pxps");
+        expect(a.speedPxPerSec).toBe(1500.5);
+    });
+    it("@<speed> AND /<duration> on same action throws", () => {
+        expect(() => parseScrollPattern("720px/3s@600pxps")).toThrow(ScrollPatternError);
+        expect(() => parseScrollPattern("720px@600pxps/3s")).toThrow(ScrollPatternError);
+    });
+    it("missing speed after @ throws", () => {
+        expect(() => parseScrollPattern("720px@")).toThrow(ScrollPatternError);
+    });
+    it("zero or negative speed rejected", () => {
+        expect(() => parseScrollPattern("720px@0pxps")).toThrow(ScrollPatternError);
+    });
+    it("unknown unit after @ throws", () => {
+        // `@800px` is invalid — only `pxps` is accepted after `@`.
+        expect(() => parseScrollPattern("720px@800px")).toThrow(ScrollPatternError);
+    });
+});
 // ── Easing suffix [...] ────────────────────────────────────────────────────
 describe("parseScrollPattern: [easing] suffix", () => {
     it("named easing", () => {
@@ -379,8 +421,13 @@ describe("parseScrollPattern: error reporting", () => {
         }
     });
     it("unexpected character", () => {
+        // `#` is not a token in the scroll grammar — must surface as
+        // "Unexpected character". (`720px@3s` USED to land here before DM-669
+        // wired `@` as the speed-suffix marker; it now errors with the more
+        // helpful `Expected speed, got duration` message — see the
+        // `@<speed> suffix` describe block above.)
         try {
-            parseScrollPattern("720px@3s");
+            parseScrollPattern("720px#");
             throw new Error("should have thrown");
         }
         catch (e) {

package/dist/tree-ops/frame-merge.d.ts

@@ -57,6 +57,16 @@ export declare function parseSiblings(src: string): ParsedNode[];
  * including `id`, those two defs would collapse into one and `<use href="#g198"/>`
  * references would break — see frame-merge.test.ts "preserves distinct ids
  * for paths with identical d".
+ *
+ * Resource references (`clip-path`, `mask`, `filter`) are included because
+ * they point at frame-scoped defs whose IDs are unique per frame. Two
+ * wrappers with different clip-path ids are NOT the same logical element
+ * even if every other attribute matches — merging them would (a) drop one
+ * frame's clip-path entirely, and (b) push that frame's unique content
+ * into the merge bucket of a different frame, which then sorts as one
+ * earlier-firstFrame group and lets later-frame siblings (e.g. solid
+ * background rects) emit *after* the content they should sit underneath.
+ * See frame-merge.test.ts "keeps per-frame body bg ordered before content".
  */
 export declare function structuralFingerprint(n: ParsedNode): string;
 export interface MergeResult {

package/dist/tree-ops/frame-merge.js

@@ -135,12 +135,25 @@ function parseAttrs(s) {
  * including `id`, those two defs would collapse into one and `<use href="#g198"/>`
  * references would break — see frame-merge.test.ts "preserves distinct ids
  * for paths with identical d".
+ *
+ * Resource references (`clip-path`, `mask`, `filter`) are included because
+ * they point at frame-scoped defs whose IDs are unique per frame. Two
+ * wrappers with different clip-path ids are NOT the same logical element
+ * even if every other attribute matches — merging them would (a) drop one
+ * frame's clip-path entirely, and (b) push that frame's unique content
+ * into the merge bucket of a different frame, which then sorts as one
+ * earlier-firstFrame group and lets later-frame siblings (e.g. solid
+ * background rects) emit *after* the content they should sit underneath.
+ * See frame-merge.test.ts "keeps per-frame body bg ordered before content".
  */
 export function structuralFingerprint(n) {
     if (n.kind === "text")
         return `T:${n.text}`;
     const a = n.attrs ?? {};
-    const keyAttrs = ["id", "transform", "href", "x", "y", "d", "width", "height", "fill", "role", "class"];
+    const keyAttrs = [
+        "id", "transform", "href", "x", "y", "d", "width", "height",
+        "fill", "role", "class", "clip-path", "mask", "filter",
+    ];
     const pairs = keyAttrs.filter((k) => a[k] != null).map((k) => `${k}=${a[k]}`);
     return `${n.tag}|${pairs.join(",")}`;
 }
@@ -355,9 +368,14 @@ function buildTimelineKeyframes(name, visibleFrames, timing) {
     if (rangeStart != null && prev != null)
         ranges.push([rangeStart, prev]);
     // Build keyframe stops. Use step-end so opacity switches instantly.
-    // DM-599: emit `display: none/inline` alongside opacity so the browser
-    // can skip painting elements that aren't currently in their visible-frames
-    // window. Both properties snap together under step-end timing.
+    // DM-599: emit a paint-skip toggle alongside opacity so the browser can
+    // skip painting elements that aren't currently in their visible-frames
+    // window. DM-641: this was `display: none/inline`, which broke for any
+    // element whose 0% keyframe is `display: none` — Chromium parks the
+    // animation when the element drops out of the render tree and never
+    // ticks the keyframe that would bring it back. Switching to
+    // `visibility` keeps the element rendered (still no paint) so the
+    // animation continues across cycles.
     const stops = []; // (pct, opacity)
     stops.push([0, 0]);
     for (const [lo, hi] of ranges) {
@@ -372,6 +390,6 @@ function buildTimelineKeyframes(name, visibleFrames, timing) {
         stops.push([Math.min(100, offPct + 0.001), 0]);
     }
     stops.push([100, 0]);
-    const lines = stops.map(([p, o]) => `      ${p.toFixed(3)}% { opacity: ${o}; display: ${o === 1 ? "inline" : "none"}; }`);
+    const lines = stops.map(([p, o]) => `      ${p.toFixed(3)}% { opacity: ${o}; visibility: ${o === 1 ? "visible" : "hidden"}; }`);
     return `    @keyframes ${name} {\n${lines.join("\n")}\n    }\n    .${name} { animation: ${name} var(--scene-dur) infinite; animation-timing-function: step-end; }`;
 }

package/dist/tree-ops/frame-merge.test.js

@@ -74,6 +74,34 @@ describe("frame-merge: mergeFrames", () => {
         const kfCount = (r.css.match(/@keyframes /g) ?? []).length;
         expect(kfCount).toBe(2);
     });
+    it("keeps per-frame body bg ordered before content (DM-644)", () => {
+        // Each frame has a body bg <rect> at top-level position 0 followed by
+        // a body-content wrapper <g clip-path="url(#vN-ov)"> at position 1.
+        // The bg fill changes per frame (so each bg is its own group); each
+        // wrapper carries a frame-scoped clip-path id (so each wrapper is also
+        // its own group). The merge must emit them so for *every* frame the
+        // bg precedes that frame's content in document order; otherwise the
+        // later-frame bgs paint over the earlier-frame content slot, hiding
+        // it during the later frame's time window.
+        const frames = [
+            `<rect width="100" height="100" fill="rgb(10,0,20)"/><g clip-path="url(#v0-ov)"><use href="#tA"/></g>`,
+            `<rect width="100" height="100" fill="rgb(0,30,0)"/><g clip-path="url(#v1-ov)"><use href="#tB"/></g>`,
+            `<rect width="100" height="100" fill="rgb(16,0,32)"/><g clip-path="url(#v2-ov)"><use href="#tC"/></g>`,
+        ];
+        const r = mergeFrames(frames, simpleTiming(3));
+        // For each frame, the bg fill must occur in the merged output before
+        // that frame's clip-path id.
+        const findIdx = (needle) => r.merged.indexOf(needle);
+        const fills = ["rgb(10,0,20)", "rgb(0,30,0)", "rgb(16,0,32)"];
+        const clips = ["url(#v0-ov)", "url(#v1-ov)", "url(#v2-ov)"];
+        for (let i = 0; i < 3; i++) {
+            const bgIdx = findIdx(fills[i]);
+            const contentIdx = findIdx(clips[i]);
+            expect(bgIdx, `frame ${i}: bg should appear`).toBeGreaterThanOrEqual(0);
+            expect(contentIdx, `frame ${i}: content wrapper should appear`).toBeGreaterThanOrEqual(0);
+            expect(bgIdx < contentIdx, `frame ${i}: bg fill ${fills[i]} (idx ${bgIdx}) must precede content clip ${clips[i]} (idx ${contentIdx})`).toBe(true);
+        }
+    });
     it("merges wrappers with same fingerprint but differing children (typing case)", () => {
         // Simulates capturing a text input as text is typed: the wrapper <g> at the
         // same transform is logically the same text field; children accumulate.
@@ -124,6 +152,23 @@ describe("frame-merge: structuralFingerprint", () => {
         expect(r.merged).toContain(`id="g113"`);
         expect(r.merged).toContain(`id="g198"`);
     });
+    it("does not match wrappers with different clip-path ids", () => {
+        // DM-644: per-frame body wrappers carry frame-scoped clip-path ids
+        // (`url(#v0-ov1)`, `url(#v1-ov1)`, ...). If clip-path is omitted from
+        // the fingerprint they merge into one group, and frame-1+ siblings
+        // (e.g. body bg rects) end up sorted *after* the merged content.
+        const a = parseSiblings(`<g clip-path="url(#v0-ov1)"/>`)[0];
+        const b = parseSiblings(`<g clip-path="url(#v1-ov1)"/>`)[0];
+        expect(structuralFingerprint(a)).not.toBe(structuralFingerprint(b));
+    });
+    it("does not match wrappers with different mask/filter refs", () => {
+        const mA = parseSiblings(`<g mask="url(#mA)"/>`)[0];
+        const mB = parseSiblings(`<g mask="url(#mB)"/>`)[0];
+        expect(structuralFingerprint(mA)).not.toBe(structuralFingerprint(mB));
+        const fA = parseSiblings(`<g filter="url(#fA)"/>`)[0];
+        const fB = parseSiblings(`<g filter="url(#fB)"/>`)[0];
+        expect(structuralFingerprint(fA)).not.toBe(structuralFingerprint(fB));
+    });
     it("does not apply visibility classes to defs children", () => {
         // Regression: glyph defs introduced in later frames were being given
         // visibility classes (e.g. class="t1"). Then <use href="#gX"/> from a

package/dist/tree-ops/tree-diff.js

@@ -172,7 +172,7 @@ export function entriesOfKind(diff, ...kinds) {
  * per-element keyframes.
  */
 export function dominantTranslate(diff) {
-    const movers = diff.entries.filter((e) => e.kind === "translated");
+    const movers = diff.entries.filter((e) => e.kind === "translated" && typeof e.dx === "number" && typeof e.dy === "number");
     if (movers.length === 0)
         return null;
     // Bucket by rounded (dx, dy) and pick the largest bucket.

package/dist/tree-ops/viewbox-culling.js

@@ -221,12 +221,26 @@ export function cullElementsOutsideViewBox(tree, viewportW, viewportH, animation
     // share a class so we emit one keyframes block per unique interval.
     const windowToClass = new Map();
     const cssBlocks = [];
+    // Walk bottom-up: recurse FIRST, then decide the element's own cull. A
+    // parent can only safely inherit `displayNone` if every descendant is
+    // also fully hidden — children of an `overflow: visible` parent paint
+    // outside the parent's bbox and stay in-viewport even when the parent's
+    // bbox is entirely above/below the viewBox (DM-650: NYT body is
+    // height: 100vh, so at scrollY > 0 the body bbox sits exactly above
+    // the viewport but its descendants are in-viewport). Returns true if
+    // any element in the subtree (including `el` itself) is visible.
     const walk = (el, inheritedCtx) => {
         const { ctx, decision } = decideForElement(el, viewportW, viewportH, inheritedCtx, animsById);
-        if (decision.alwaysHidden) {
+        let anyDescendantVisible = false;
+        if (el.children != null) {
+            for (const child of el.children) {
+                if (walk(child, ctx))
+                    anyDescendantVisible = true;
+            }
+        }
+        if (decision.alwaysHidden && !anyDescendantVisible) {
             el.displayNone = true;
-            // Children inherit displayNone implicitly; don't recurse.
-            return;
+            return false;
         }
         if (decision.visStartPct != null && decision.visEndPct != null) {
             const key = `${r3(decision.visStartPct)},${r3(decision.visEndPct)}`;
@@ -236,37 +250,37 @@ export function cullElementsOutsideViewBox(tree, viewportW, viewportH, animation
                 windowToClass.set(key, className);
                 cssBlocks.push(buildCullKeyframes(className, decision.visStartPct, decision.visEndPct));
             }
-            // Merge with any existing cullClass (shouldn't happen — each pass
-            // assigns at most one — but be defensive).
             el.cullClass = el.cullClass == null || el.cullClass === "" ? className : `${el.cullClass} ${className}`;
         }
-        // Recurse into children with the (possibly newly inherited) animation context.
-        if (el.children != null) {
-            for (const child of el.children)
-                walk(child, ctx);
-        }
+        return true;
     };
     for (const root of roots)
         walk(root, null);
     return { css: cssBlocks.join("\n") };
 }
 /**
- * Step-end `@keyframes` block + class rule that toggles `display: inline`
- * during [visStart, visEnd] and `display: none` outside. The 0.001 % gap
+ * Step-end `@keyframes` block + class rule that toggles `visibility: visible`
+ * during [visStart, visEnd] and `visibility: hidden` outside. The 0.001 % gap
  * pattern keeps the discrete snap point inside a sliver-thin keyframe pair
  * regardless of how the animation timing function is configured on the
  * element.
+ *
+ * DM-641: toggling `display` here breaks the same way `fv-${i}` did — when
+ * a culled element starts the cycle at `display: none` the animation engine
+ * never starts ticking and the element stays hidden forever. Using
+ * `visibility` keeps the element in the render tree (still skips painting)
+ * so the animation runs every cycle.
  */
 function buildCullKeyframes(name, visStartPct, visEndPct) {
     const startMinus = Math.max(0, visStartPct - 0.001).toFixed(3);
     const endPlus = Math.min(100, visEndPct + 0.001).toFixed(3);
     return `    @keyframes ${name} {
-      0% { display: none; }
-      ${startMinus}% { display: none; }
-      ${visStartPct.toFixed(3)}% { display: inline; }
-      ${visEndPct.toFixed(3)}% { display: inline; }
-      ${endPlus}% { display: none; }
-      100% { display: none; }
+      0% { visibility: hidden; }
+      ${startMinus}% { visibility: hidden; }
+      ${visStartPct.toFixed(3)}% { visibility: visible; }
+      ${visEndPct.toFixed(3)}% { visibility: visible; }
+      ${endPlus}% { visibility: hidden; }
+      100% { visibility: hidden; }
     }
     .${name} { animation: ${name} var(--scene-dur) infinite; animation-timing-function: step-end; }`;
 }