domotion-svg 0.1.1

package/dist/cursor-overlay.js

@@ -0,0 +1,207 @@
+/**
+ * Cursor / click overlay for animated SVGs (DM-277).
+ *
+ * Paints a macOS-style cursor moving along a user-authored timeline and
+ * QuickTime-style click pulses at click events. Single pointer at a time;
+ * multi-touch is out of scope for v1.
+ *
+ * The overlay is opt-in via `AnimationConfig.cursorOverlay`. The emitted
+ * markup goes inside the viewport-clipped group, after the frame groups,
+ * so it paints above the frame content and is clipped to the viewport.
+ *
+ * Selector resolution: events that target a captured element via `selector`
+ * are resolved by an optional `resolveSelector(sel, frameIndex)` callback
+ * the caller supplies. The frame index is computed from the event's `t`
+ * (each frame's start/end time is derived from the animation timing).
+ *
+ * See docs/13-cursor-overlay.md for the design.
+ */
+const DEFAULT_STYLE = {
+    pointer: "mouse",
+    cursorFill: "rgb(255, 255, 255)",
+    cursorStroke: "rgb(0, 0, 0)",
+    pulseStroke: "rgba(255, 255, 255, 0.95)",
+    pulseStrokeOuter: "rgba(0, 0, 0, 0.4)",
+    pulseDurationMs: 500,
+    pulseRadius: 32,
+    cursorScale: 1,
+};
+/**
+ * Resolve a script into absolute-coord position keyframes + click pulses.
+ * Caller passes a `resolveSelector(sel, frameIndex)` if the script uses
+ * selectors; otherwise pass `null` and selector events become no-ops with
+ * a console warning.
+ */
+export function resolveCursorScript(overlay, totalDurationMs, frameStartTimes, resolveSelector) {
+    const baseStyle = { ...DEFAULT_STYLE, ...overlay.style };
+    const events = [...overlay.events].sort((a, b) => a.t - b.t);
+    const positions = [];
+    const clicks = [];
+    let curX = 0;
+    let curY = 0;
+    let visible = false;
+    const pushKey = (t, x, y, vis) => {
+        positions.push({ t, x, y, visible: vis });
+        curX = x;
+        curY = y;
+        visible = vis;
+    };
+    const frameForT = (t) => {
+        let idx = 0;
+        for (let i = 0; i < frameStartTimes.length; i++) {
+            if (t >= frameStartTimes[i])
+                idx = i;
+            else
+                break;
+        }
+        return idx;
+    };
+    for (const ev of events) {
+        if (ev.type === "show") {
+            pushKey(ev.t, ev.x, ev.y, true);
+        }
+        else if (ev.type === "hide") {
+            pushKey(ev.t, curX, curY, false);
+        }
+        else if (ev.type === "move") {
+            const dur = ev.duration ?? 0;
+            const target = resolveMoveTarget(ev, curX, curY, frameForT(ev.t), resolveSelector);
+            if (target == null)
+                continue;
+            // First time we ever position the cursor — also turn it visible.
+            const becomeVisible = !visible;
+            if (dur > 0) {
+                if (becomeVisible) {
+                    // Hold the cursor at its previous spot until the move begins so we
+                    // don't see it pop in mid-frame; the start keyframe carries `false`
+                    // visibility, the end keyframe carries `true` and the cursor fades
+                    // in at the move's start.
+                    pushKey(ev.t, curX, curY, true);
+                }
+                else {
+                    pushKey(ev.t, curX, curY, true);
+                }
+                pushKey(ev.t + dur, target.x, target.y, true);
+            }
+            else {
+                pushKey(ev.t, target.x, target.y, true);
+            }
+        }
+        else if (ev.type === "click") {
+            const button = ev.button ?? "primary";
+            const style = { ...baseStyle, ...(ev.style ?? {}) };
+            clicks.push({ t: ev.t, x: curX, y: curY, button, style });
+        }
+    }
+    // Always anchor an initial keyframe at t=0 with visibility `false` so the
+    // animation doesn't accidentally show the cursor at (0, 0) before the
+    // first `show` / `move`.
+    if (positions.length === 0 || positions[0].t > 0) {
+        positions.unshift({ t: 0, x: positions[0]?.x ?? 0, y: positions[0]?.y ?? 0, visible: false });
+    }
+    // Anchor a final keyframe at totalDurationMs so animateTransform interpolates
+    // through the whole loop.
+    if (positions[positions.length - 1].t < totalDurationMs) {
+        const last = positions[positions.length - 1];
+        positions.push({ t: totalDurationMs, x: last.x, y: last.y, visible: last.visible });
+    }
+    return { positions, clicks, style: baseStyle };
+}
+function resolveMoveTarget(ev, curX, curY, frameIndex, resolveSelector) {
+    if (ev.to != null)
+        return { x: ev.to.x, y: ev.to.y };
+    if (ev.by != null)
+        return { x: curX + ev.by.dx, y: curY + ev.by.dy };
+    if (ev.selector != null) {
+        if (resolveSelector == null) {
+            // eslint-disable-next-line no-console
+            console.warn(`cursor-overlay: selector "${ev.selector}" used but no resolveSelector provided; skipping`);
+            return null;
+        }
+        const rect = resolveSelector(ev.selector, frameIndex);
+        if (rect == null) {
+            // eslint-disable-next-line no-console
+            console.warn(`cursor-overlay: selector "${ev.selector}" matched no element in frame ${frameIndex}; skipping`);
+            return null;
+        }
+        const cx = rect.x + rect.w / 2 + (ev.offset?.dx ?? 0);
+        const cy = rect.y + rect.h / 2 + (ev.offset?.dy ?? 0);
+        return { x: cx, y: cy };
+    }
+    return null;
+}
+/**
+ * Emit the `<g class="cursor-overlay">` markup for an already-resolved
+ * timeline. Returns "" when the timeline has no positions or every keyframe
+ * is invisible.
+ */
+export function cursorOverlayMarkup(positions, clicks, style, totalDurationMs) {
+    if (positions.length === 0 || totalDurationMs <= 0)
+        return "";
+    const totalSec = totalDurationMs / 1000;
+    // animateTransform with values + keyTimes drives the cursor's translate.
+    const valueStrs = [];
+    const keyTimes = [];
+    for (const p of positions) {
+        valueStrs.push(`${num(p.x)},${num(p.y)}`);
+        keyTimes.push((p.t / totalDurationMs).toFixed(4));
+    }
+    // SMIL animateTransform requires keyTimes to start at 0 and end at 1; the
+    // resolveCursorScript anchor at t=0 and t=totalDurationMs guarantees this.
+    // Visibility timeline: opacity flips between 0 and 1 at keyframes whose
+    // `visible` differs from the previous one. Use `discrete` calc-mode for
+    // step-wise transitions (no interpolation between 0 and 1).
+    const visValues = [];
+    for (const p of positions)
+        visValues.push(p.visible ? "1" : "0");
+    const cursorPath = macosCursorPath(style.cursorScale);
+    // Pulse SVG fragments — one per click, with timing keyed off `t`.
+    const pulseMarkup = clicks.map((c, i) => buildPulseFragment(c, i, totalDurationMs)).join("\n");
+    return `  <g class="cursor-overlay" pointer-events="none">
+    <g class="cursor-arrow" opacity="0">
+      <animateTransform attributeName="transform" type="translate" values="${valueStrs.join("; ")}" keyTimes="${keyTimes.join("; ")}" dur="${totalSec}s" repeatCount="indefinite" fill="freeze" />
+      <animate attributeName="opacity" values="${visValues.join(";")}" keyTimes="${keyTimes.join(";")}" dur="${totalSec}s" repeatCount="indefinite" calcMode="discrete" fill="freeze" />
+      ${cursorPath}
+    </g>
+${pulseMarkup}
+  </g>`;
+}
+/** Build the SVG fragment for a single click pulse. */
+function buildPulseFragment(c, idx, totalDurationMs) {
+    const beginSec = (c.t / 1000).toFixed(3);
+    const durSec = (c.style.pulseDurationMs / 1000).toFixed(3);
+    const r0 = 4;
+    const r1 = c.style.pulseRadius;
+    const innerR = r1 * 0.55;
+    // Right-half-disc fill for secondary clicks.
+    let secondaryHalf = "";
+    if (c.button === "secondary") {
+        const halfPath = `M ${num(c.x)} ${num(c.y - innerR)} A ${num(innerR)} ${num(innerR)} 0 0 1 ${num(c.x)} ${num(c.y + innerR)} Z`;
+        secondaryHalf = `
+    <path d="${halfPath}" fill="rgba(0,0,0,0.2)" opacity="0">
+      <animate attributeName="opacity" values="0; 1; 0" keyTimes="0; 0.2; 1" dur="${durSec}s" begin="${beginSec}s" fill="freeze" />
+    </path>`;
+    }
+    return `    <g class="cursor-click cursor-click-${idx}">
+      <circle cx="${num(c.x)}" cy="${num(c.y)}" r="${r0}" fill="none" stroke="${c.style.pulseStrokeOuter}" stroke-width="2" opacity="0">
+        <animate attributeName="r" values="${r0}; ${r1}" keyTimes="0; 1" dur="${durSec}s" begin="${beginSec}s" fill="freeze" />
+        <animate attributeName="opacity" values="0; 0.9; 0" keyTimes="0; 0.15; 1" dur="${durSec}s" begin="${beginSec}s" fill="freeze" />
+      </circle>
+      <circle cx="${num(c.x)}" cy="${num(c.y)}" r="${r0}" fill="none" stroke="${c.style.pulseStroke}" stroke-width="1" opacity="0">
+        <animate attributeName="r" values="${r0}; ${r1 - 1}" keyTimes="0; 1" dur="${durSec}s" begin="${beginSec}s" fill="freeze" />
+        <animate attributeName="opacity" values="0; 0.95; 0" keyTimes="0; 0.15; 1" dur="${durSec}s" begin="${beginSec}s" fill="freeze" />
+      </circle>${secondaryHalf}
+    </g>`;
+}
+/** macOS-style cursor arrow path. The hot point (0, 0) sits at the tip. */
+function macosCursorPath(scale) {
+    // Path approximates the macOS pointer: tip at (0, 0), tail extends down and
+    // right with a small notch. Stroked white with a thin black outline so it
+    // reads on any background.
+    const d = "M 0 0 L 0 16 L 4 12 L 7 18 L 9 17 L 6 11 L 12 11 Z";
+    const transform = scale !== 1 ? ` transform="scale(${num(scale)})"` : "";
+    return `<path d="${d}" fill="rgb(255,255,255)" stroke="rgb(0,0,0)" stroke-width="1" stroke-linejoin="round"${transform} />`;
+}
+function num(n) {
+    return Number(n.toFixed(2)).toString();
+}

package/dist/cursor-overlay.test.d.ts

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

package/dist/cursor-overlay.test.js

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { cursorOverlayMarkup, resolveCursorScript } from "./cursor-overlay.js";
+const TOTAL = 4000;
+const FRAME_STARTS = [0, 1500, 3000];
+describe("resolveCursorScript: position keyframes", () => {
+    it("anchors a hidden keyframe at t=0 even when the script starts later", () => {
+        const overlay = {
+            events: [{ type: "show", t: 500, x: 100, y: 200 }],
+        };
+        const r = resolveCursorScript(overlay, TOTAL, FRAME_STARTS, null);
+        expect(r.positions[0]).toMatchObject({ t: 0, visible: false });
+        expect(r.positions.find((p) => p.t === 500)).toMatchObject({ x: 100, y: 200, visible: true });
+        expect(r.positions[r.positions.length - 1].t).toBe(TOTAL);
+    });
+    it("resolves `to` (absolute), `by` (relative), and `selector` move targets", () => {
+        const overlay = {
+            events: [
+                { type: "show", t: 0, x: 10, y: 20 },
+                { type: "move", t: 100, to: { x: 50, y: 60 } },
+                { type: "move", t: 200, by: { dx: 10, dy: -5 } },
+                { type: "move", t: 300, selector: ".btn" },
+            ],
+        };
+        const resolveSelector = () => ({ x: 200, y: 300, w: 80, h: 24 });
+        const r = resolveCursorScript(overlay, TOTAL, FRAME_STARTS, resolveSelector);
+        const at100 = r.positions.find((p) => p.t === 100);
+        const at200 = r.positions.find((p) => p.t === 200);
+        const at300 = r.positions.find((p) => p.t === 300);
+        expect(at100).toMatchObject({ x: 50, y: 60 });
+        expect(at200).toMatchObject({ x: 60, y: 55 });
+        // Center of (200, 300, 80, 24) is (240, 312).
+        expect(at300).toMatchObject({ x: 240, y: 312 });
+    });
+    it("emits two keyframes for a duration move (start + end) so SMIL interpolates", () => {
+        const overlay = {
+            events: [
+                { type: "show", t: 0, x: 0, y: 0 },
+                { type: "move", t: 1000, to: { x: 100, y: 100 }, duration: 500 },
+            ],
+        };
+        const r = resolveCursorScript(overlay, TOTAL, FRAME_STARTS, null);
+        const at1000 = r.positions.find((p) => p.t === 1000);
+        const at1500 = r.positions.find((p) => p.t === 1500);
+        expect(at1000).toMatchObject({ x: 0, y: 0, visible: true });
+        expect(at1500).toMatchObject({ x: 100, y: 100, visible: true });
+    });
+    it("captures clicks with the cursor's current position at the click's t", () => {
+        const overlay = {
+            events: [
+                { type: "show", t: 0, x: 30, y: 40 },
+                { type: "click", t: 100, button: "primary" },
+                { type: "move", t: 200, to: { x: 80, y: 80 } },
+                { type: "click", t: 300, button: "secondary" },
+            ],
+        };
+        const r = resolveCursorScript(overlay, TOTAL, FRAME_STARTS, null);
+        expect(r.clicks).toHaveLength(2);
+        expect(r.clicks[0]).toMatchObject({ t: 100, x: 30, y: 40, button: "primary" });
+        expect(r.clicks[1]).toMatchObject({ t: 300, x: 80, y: 80, button: "secondary" });
+    });
+});
+describe("cursorOverlayMarkup: SVG emission", () => {
+    it("includes a cursor-arrow group and a click pulse per click", () => {
+        const overlay = {
+            events: [
+                { type: "show", t: 0, x: 50, y: 50 },
+                { type: "click", t: 200, button: "primary" },
+                { type: "click", t: 600, button: "secondary" },
+            ],
+        };
+        const r = resolveCursorScript(overlay, TOTAL, FRAME_STARTS, null);
+        const svg = cursorOverlayMarkup(r.positions, r.clicks, r.style, TOTAL);
+        expect(svg).toContain('class="cursor-overlay"');
+        expect(svg).toContain('class="cursor-arrow"');
+        expect(svg).toContain('class="cursor-click cursor-click-0"');
+        expect(svg).toContain('class="cursor-click cursor-click-1"');
+        // Secondary click adds the right-half-disc fill.
+        expect(svg).toContain('rgba(0,0,0,0.2)');
+    });
+    it("emits empty string when there are no events", () => {
+        const r = resolveCursorScript({ events: [] }, TOTAL, FRAME_STARTS, null);
+        const svg = cursorOverlayMarkup(r.positions, r.clicks, r.style, TOTAL);
+        // Even with no events, resolveCursorScript anchors t=0 and t=total
+        // (both invisible). The markup is non-empty but contains no clicks.
+        expect(svg).toContain('class="cursor-overlay"');
+        expect(svg).not.toContain('class="cursor-click');
+    });
+});

package/dist/dark-mode-capture.test.d.ts

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

package/dist/dark-mode-capture.test.js

@@ -0,0 +1,158 @@
+import { describe, expect, it } from "vitest";
+import { rootSvgColorSchemeAttr, transparentRootBgRect, wrapSvg } from "./dom-to-svg.js";
+// DM-552: capture-side propagation of `rootColorScheme` and `rootBgComputed`
+// stamped on the captured tree's root element by CAPTURE_SCRIPT, plus the
+// renderer-side helper that emits `color-scheme="dark"` on the wrapping
+// `<svg>` element. End-to-end CAPTURE_SCRIPT integration is covered by
+// the real-world suite + the dark-mode form-control fixture (DM-553); this
+// file unit-tests the renderer-side surface in isolation.
+function makeRoot(overrides = {}) {
+    return {
+        tag: "body",
+        text: "",
+        x: 0, y: 0, width: 100, height: 100,
+        children: [],
+        styles: {
+            backgroundColor: "rgb(255,255,255)",
+            borderColor: "rgb(0,0,0)",
+            borderWidth: "0",
+            borderRadius: "0",
+            borderTopLeftRadius: "0",
+            borderTopRightRadius: "0",
+            borderBottomRightRadius: "0",
+            borderBottomLeftRadius: "0",
+            borderTopWidth: "0",
+            borderRightWidth: "0",
+            borderBottomWidth: "0",
+            borderLeftWidth: "0",
+            borderTopColor: "rgb(0,0,0)",
+            borderRightColor: "rgb(0,0,0)",
+            borderBottomColor: "rgb(0,0,0)",
+            borderLeftColor: "rgb(0,0,0)",
+            borderTopStyle: "none",
+            borderRightStyle: "none",
+            borderBottomStyle: "none",
+            borderLeftStyle: "none",
+            color: "rgb(0,0,0)",
+            fontSize: "16px",
+            fontFamily: "sans-serif",
+            fontWeight: "400",
+            fontStyle: "normal",
+            lineHeight: "20px",
+            letterSpacing: "normal",
+            textAlign: "left",
+            textTransform: "none",
+            textDecoration: "none",
+            textDecorationLine: "none",
+            textDecorationStyle: "solid",
+            textDecorationColor: "rgb(0,0,0)",
+            textDecorationThickness: "auto",
+            textIndent: "0",
+            textShadow: "none",
+            textWrap: "wrap",
+            whiteSpace: "normal",
+            wordBreak: "normal",
+            overflowWrap: "normal",
+            verticalAlign: "baseline",
+            backgroundImage: "none",
+            backgroundSize: "auto",
+            backgroundPosition: "0% 0%",
+            backgroundRepeat: "repeat",
+            backgroundAttachment: "scroll",
+            backgroundClip: "border-box",
+            backgroundOrigin: "padding-box",
+            opacity: "1",
+            position: "static",
+            top: "auto",
+            left: "auto",
+            right: "auto",
+            bottom: "auto",
+            display: "block",
+            flexDirection: "row",
+            visibility: "visible",
+            zIndex: "auto",
+            transform: "none",
+            transformOrigin: "50% 50%",
+            writingMode: "horizontal-tb",
+            textOrientation: "mixed",
+            cursor: "auto",
+            pointerEvents: "auto",
+            ...overrides,
+        },
+    };
+}
+describe("rootSvgColorSchemeAttr (DM-552)", () => {
+    it("returns empty string when the captured tree is empty", () => {
+        expect(rootSvgColorSchemeAttr([])).toBe("");
+    });
+    it("returns empty string when rootColorScheme is undefined (default scheme is attribute-free — today's SVG byte-identical)", () => {
+        expect(rootSvgColorSchemeAttr([makeRoot()])).toBe("");
+    });
+    it("returns empty string when rootColorScheme is explicitly 'light'", () => {
+        expect(rootSvgColorSchemeAttr([makeRoot({ rootColorScheme: "light" })])).toBe("");
+    });
+    it("returns ` color-scheme=\"dark\"` (with leading space, ready to concat) when rootColorScheme is 'dark'", () => {
+        expect(rootSvgColorSchemeAttr([makeRoot({ rootColorScheme: "dark" })])).toBe(` color-scheme="dark"`);
+    });
+    it("only inspects elements[0] — siblings with mismatched scheme are ignored (only the root carries the page-level signal)", () => {
+        const root = makeRoot({ rootColorScheme: "light" });
+        const sibling = makeRoot({ rootColorScheme: "dark" });
+        expect(rootSvgColorSchemeAttr([root, sibling])).toBe("");
+    });
+});
+describe("wrapSvg with tree option (DM-552)", () => {
+    it("emits a vanilla <svg> when no tree is passed (back-compat)", () => {
+        const out = wrapSvg("<g/>", 100, 50);
+        expect(out).toBe(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 50" width="100" height="50"><g/></svg>`);
+    });
+    it("emits a vanilla <svg> when the tree's root has no rootColorScheme", () => {
+        const out = wrapSvg("<g/>", 100, 50, { tree: [makeRoot()] });
+        expect(out).toBe(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 50" width="100" height="50"><g/></svg>`);
+    });
+    it("includes color-scheme=\"dark\" on the root <svg> when tree's root reports dark scheme", () => {
+        const out = wrapSvg("<g/>", 100, 50, { tree: [makeRoot({ rootColorScheme: "dark" })] });
+        expect(out).toBe(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 50" width="100" height="50" color-scheme="dark"><g/></svg>`);
+    });
+    it("does NOT add color-scheme=\"light\" — the absence of the attribute IS the light default (today's output preserved verbatim)", () => {
+        const out = wrapSvg("<g/>", 100, 50, { tree: [makeRoot({ rootColorScheme: "light" })] });
+        expect(out).not.toContain("color-scheme");
+    });
+});
+describe("transparentRootBgRect (DM-554)", () => {
+    it("returns empty string for an empty tree", () => {
+        expect(transparentRootBgRect([], 100, 50)).toBe("");
+    });
+    it("returns empty string when rootBgComputed is missing (pre-DM-552 capture)", () => {
+        expect(transparentRootBgRect([makeRoot()], 100, 50)).toBe("");
+    });
+    it("returns empty string when rootBgComputed is explicitly transparent (intentional transparent SVG)", () => {
+        expect(transparentRootBgRect([makeRoot({ rootBgComputed: "rgba(0, 0, 0, 0)" })], 100, 50)).toBe("");
+        expect(transparentRootBgRect([makeRoot({ rootBgComputed: "transparent" })], 100, 50)).toBe("");
+    });
+    it("emits a body-bg <rect> with the resolved color when rootBgComputed is set", () => {
+        const out = transparentRootBgRect([makeRoot({ rootBgComputed: "rgb(28, 28, 28)" })], 1280, 800);
+        expect(out).toBe(`<rect width="1280" height="800" fill="rgb(28, 28, 28)" />`);
+    });
+    it("uses the same color whether the scheme is light or dark — the rect mirrors Chromium's resolved bg, not a hardcoded scheme palette", () => {
+        const lightOut = transparentRootBgRect([makeRoot({ rootBgComputed: "rgb(255, 255, 255)", rootColorScheme: "light" })], 100, 50);
+        const darkOut = transparentRootBgRect([makeRoot({ rootBgComputed: "rgb(28, 28, 28)", rootColorScheme: "dark" })], 100, 50);
+        expect(lightOut).toBe(`<rect width="100" height="50" fill="rgb(255, 255, 255)" />`);
+        expect(darkOut).toBe(`<rect width="100" height="50" fill="rgb(28, 28, 28)" />`);
+    });
+});
+describe("wrapSvg with body-bg rect injection (DM-554)", () => {
+    it("emits the body-bg rect BEFORE the inner content so the inner paints on top", () => {
+        const out = wrapSvg("<g class='content'/>", 100, 50, { tree: [makeRoot({ rootBgComputed: "rgb(28, 28, 28)" })] });
+        expect(out).toBe(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 50" width="100" height="50"><rect width="100" height="50" fill="rgb(28, 28, 28)" /><g class='content'/></svg>`);
+    });
+    it("combines color-scheme attr and body-bg rect when the tree has both signals", () => {
+        const tree = [makeRoot({ rootColorScheme: "dark", rootBgComputed: "rgb(28, 28, 28)" })];
+        const out = wrapSvg("<g/>", 100, 50, { tree });
+        expect(out).toContain(`color-scheme="dark"`);
+        expect(out).toContain(`<rect width="100" height="50" fill="rgb(28, 28, 28)" />`);
+    });
+    it("stays byte-identical to today's output when no tree is passed (back-compat)", () => {
+        const out = wrapSvg("<g/>", 100, 50);
+        expect(out).toBe(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 50" width="100" height="50"><g/></svg>`);
+    });
+});

package/dist/dark-mode-form-controls.test.d.ts

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