domotion-svg 0.1.1

package/dist/coretext-helper.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Native macOS glyph-outline extraction via the CoreText helper binary
+ * (`tools/macos-glyph-extractor`). DM-385 / DM-388.
+ *
+ * Used as the path-extraction backend for fonts whose outlines fontkit
+ * can't read — primarily PingFang, whose outlines live in the proprietary
+ * Apple `hvgl` table. The helper opens the font through CoreText (which
+ * understands `hvgl`) and returns SVG path data we can drop into the same
+ * `<defs>`/`<use>` pipeline as fontkit-extracted glyphs.
+ *
+ * The wrapper exposes a fontkit-compatible subset of the `Font` API (the
+ * fields `text-to-path.ts` reads): `unitsPerEm`, ascent/descent, underline /
+ * strikeout metrics, `glyphForCodePoint`, `getGlyph`, and `layout`. The
+ * renderer treats it interchangeably with a fontkit Font.
+ */
+export declare function isCoretextHelperAvailable(): boolean;
+interface PathCommand {
+    command: string;
+    args: number[];
+}
+interface CoretextGlyph {
+    id: number;
+    advanceWidth: number;
+    path: {
+        commands: PathCommand[];
+    };
+    codePoints?: number[];
+}
+export interface CoretextFontInstance {
+    unitsPerEm: number;
+    ascent: number;
+    descent: number;
+    underlinePosition: number;
+    underlineThickness: number;
+    "OS/2"?: {
+        yStrikeoutPosition?: number;
+        yStrikeoutSize?: number;
+    };
+    availableFeatures?: string[];
+    glyphForCodePoint(cp: number): CoretextGlyph;
+    getGlyph(id: number): CoretextGlyph;
+    layout(text: string, features?: string[]): {
+        glyphs: CoretextGlyph[];
+        positions: Array<{
+            xAdvance: number;
+            yAdvance: number;
+            xOffset: number;
+            yOffset: number;
+        }>;
+    };
+}
+export declare function createCoretextFont(spec: {
+    postscriptName?: string;
+    fontPath?: string;
+}): CoretextFontInstance | null;
+/** Drop the in-memory glyph-resolution caches. Currently a no-op since each
+ *  `createCoretextFont` returns its own closure-bound cache, but exposed for
+ *  parity with `clearWebfonts` / `clearGlyphDefs`. */
+export declare function clearCoretextCache(): void;
+export {};

package/dist/coretext-helper.js

@@ -0,0 +1,205 @@
+/**
+ * Native macOS glyph-outline extraction via the CoreText helper binary
+ * (`tools/macos-glyph-extractor`). DM-385 / DM-388.
+ *
+ * Used as the path-extraction backend for fonts whose outlines fontkit
+ * can't read — primarily PingFang, whose outlines live in the proprietary
+ * Apple `hvgl` table. The helper opens the font through CoreText (which
+ * understands `hvgl`) and returns SVG path data we can drop into the same
+ * `<defs>`/`<use>` pipeline as fontkit-extracted glyphs.
+ *
+ * The wrapper exposes a fontkit-compatible subset of the `Font` API (the
+ * fields `text-to-path.ts` reads): `unitsPerEm`, ascent/descent, underline /
+ * strikeout metrics, `glyphForCodePoint`, `getGlyph`, and `layout`. The
+ * renderer treats it interchangeably with a fontkit Font.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const HELPER_PATH = process.env.DOMOTION_HELPER_PATH
+    ?? path.resolve(HERE, "..", "tools", "macos-glyph-extractor", "domotion-glyph-paths");
+let helperAvailable = null;
+export function isCoretextHelperAvailable() {
+    if (helperAvailable != null)
+        return helperAvailable;
+    if (process.platform !== "darwin") {
+        helperAvailable = false;
+        return false;
+    }
+    if (process.env.DOMOTION_DISABLE_HELPER) {
+        helperAvailable = false;
+        return false;
+    }
+    helperAvailable = existsSync(HELPER_PATH);
+    return helperAvailable;
+}
+// Parse the Swift helper's SVG path-data string into fontkit's command-array
+// format. The helper emits exactly: `M x y`, `L x y`, `Q cx cy x y`,
+// `C c1x c1y c2x c2y x y`, `Z` — space-separated, no relative variants.
+function parseSvgPath(d) {
+    if (d.length === 0)
+        return [];
+    const tokens = d.match(/[MLQCZ]|-?\d+(?:\.\d+)?/g) ?? [];
+    const out = [];
+    let i = 0;
+    const num = () => Number(tokens[i++]);
+    while (i < tokens.length) {
+        const t = tokens[i++];
+        switch (t) {
+            case "M":
+                out.push({ command: "moveTo", args: [num(), num()] });
+                break;
+            case "L":
+                out.push({ command: "lineTo", args: [num(), num()] });
+                break;
+            case "Q":
+                out.push({ command: "quadraticCurveTo", args: [num(), num(), num(), num()] });
+                break;
+            case "C":
+                out.push({ command: "bezierCurveTo", args: [num(), num(), num(), num(), num(), num()] });
+                break;
+            case "Z":
+                out.push({ command: "closePath", args: [] });
+                break;
+        }
+    }
+    return out;
+}
+function callHelper(request) {
+    const proc = spawnSync(HELPER_PATH, [], {
+        input: JSON.stringify(request),
+        encoding: "utf-8",
+        maxBuffer: 64 * 1024 * 1024
+    });
+    if (proc.status !== 0) {
+        throw new Error(`coretext helper failed (exit ${proc.status}): ${proc.stderr}`);
+    }
+    return JSON.parse(proc.stdout);
+}
+export function createCoretextFont(spec) {
+    if (!isCoretextHelperAvailable())
+        return null;
+    // Open at size=1000 first so we can read unitsPerEm. Then re-open at
+    // size=unitsPerEm so all glyph paths come back in design-unit space — this
+    // matches fontkit's coordinate convention so the existing
+    // `scale(fontSize/unitsPerEm, ...)` transform in text-to-path.ts works.
+    let metaResp;
+    try {
+        const probe = callHelper({
+            fonts: [{ ref: "f", postscriptName: spec.postscriptName, fontPath: spec.fontPath, size: 1000 }],
+            queries: [{ type: "meta", fontRef: "f" }]
+        });
+        const r = probe.results[0];
+        if (r.type !== "meta")
+            throw new Error("unexpected response shape");
+        metaResp = r;
+    }
+    catch {
+        return null;
+    }
+    const unitsPerEm = metaResp.unitsPerEm;
+    const renderSize = unitsPerEm;
+    // Per-(cp, id) caches — each glyph is fetched at most once per Node process.
+    const cpToGlyph = new Map();
+    const idToGlyph = new Map();
+    const missingCp = new Set();
+    function fetchByCps(cps) {
+        const need = cps.filter((cp) => !cpToGlyph.has(cp) && !missingCp.has(cp));
+        if (need.length === 0)
+            return;
+        const resp = callHelper({
+            fonts: [{ ref: "f", postscriptName: spec.postscriptName, fontPath: spec.fontPath, size: renderSize }],
+            queries: [{ type: "glyphs", fontRef: "f", glyphs: need.map((cp) => ({ cp })) }]
+        });
+        const r = resp.results[0];
+        if (r.type !== "glyphs")
+            return;
+        for (let i = 0; i < need.length; i++) {
+            const cp = need[i];
+            const g = r.glyphs[i];
+            if (g == null || g.id === 0) {
+                missingCp.add(cp);
+                continue;
+            }
+            const glyph = {
+                id: g.id,
+                advanceWidth: g.advance,
+                path: { commands: parseSvgPath(g.d) },
+                codePoints: [cp]
+            };
+            cpToGlyph.set(cp, glyph);
+            idToGlyph.set(g.id, glyph);
+        }
+    }
+    function fetchById(id) {
+        const cached = idToGlyph.get(id);
+        if (cached != null)
+            return cached;
+        const resp = callHelper({
+            fonts: [{ ref: "f", postscriptName: spec.postscriptName, fontPath: spec.fontPath, size: renderSize }],
+            queries: [{ type: "glyphs", fontRef: "f", glyphs: [{ id }] }]
+        });
+        const r = resp.results[0];
+        if (r.type !== "glyphs") {
+            const empty = { id, advanceWidth: 0, path: { commands: [] } };
+            idToGlyph.set(id, empty);
+            return empty;
+        }
+        const g = r.glyphs[0];
+        const glyph = {
+            id: g.id,
+            advanceWidth: g.advance,
+            path: { commands: parseSvgPath(g.d) }
+        };
+        idToGlyph.set(id, glyph);
+        return glyph;
+    }
+    function notdef(id = 0) {
+        return { id, advanceWidth: 0, path: { commands: [] } };
+    }
+    return {
+        unitsPerEm,
+        ascent: metaResp.ascent ?? 0,
+        descent: metaResp.descent ?? 0,
+        underlinePosition: metaResp.underlinePosition ?? 0,
+        underlineThickness: metaResp.underlineThickness ?? 0,
+        "OS/2": {
+            yStrikeoutPosition: metaResp.strikeoutPosition,
+            yStrikeoutSize: metaResp.strikeoutThickness
+        },
+        availableFeatures: [],
+        glyphForCodePoint(cp) {
+            if (missingCp.has(cp))
+                return notdef(0);
+            if (!cpToGlyph.has(cp))
+                fetchByCps([cp]);
+            return cpToGlyph.get(cp) ?? notdef(0);
+        },
+        getGlyph(id) {
+            return fetchById(id);
+        },
+        layout(text) {
+            // Batch every codepoint in one helper call before assembling the result.
+            const cps = [];
+            for (const ch of text)
+                cps.push(ch.codePointAt(0));
+            fetchByCps(cps);
+            const glyphs = [];
+            const positions = [];
+            for (const cp of cps) {
+                const g = cpToGlyph.get(cp) ?? notdef(0);
+                glyphs.push(g);
+                positions.push({ xAdvance: g.advanceWidth, yAdvance: 0, xOffset: 0, yOffset: 0 });
+            }
+            return { glyphs, positions };
+        }
+    };
+}
+/** Drop the in-memory glyph-resolution caches. Currently a no-op since each
+ *  `createCoretextFont` returns its own closure-bound cache, but exposed for
+ *  parity with `clearWebfonts` / `clearGlyphDefs`. */
+export function clearCoretextCache() {
+    helperAvailable = null;
+}

package/dist/cross-origin-font-face.test.d.ts

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

package/dist/cross-origin-font-face.test.js

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+import { parseFontFaceRulesFromCssText } from "./capture.js";
+// DM-545: cross-origin stylesheets throw on `cssRules` access from the page
+// context, so we fetch them server-side and parse `@font-face` rules with
+// this helper. Sites affected (verified): Stripe (b.stripecdn.com), and
+// likely most marketing sites whose CSS is served from a different host
+// than the page.
+describe("parseFontFaceRulesFromCssText", () => {
+    const BASE = "https://cdn.example.com/css/site.css";
+    it("returns empty list for CSS with no @font-face rules", () => {
+        expect(parseFontFaceRulesFromCssText("body { color: red; }", BASE)).toEqual([]);
+    });
+    it("parses a single top-level @font-face rule with a single src url()", () => {
+        const css = `@font-face { font-family: "MyFont"; src: url("/fonts/myfont.woff2"); }`;
+        const out = parseFontFaceRulesFromCssText(css, BASE);
+        expect(out).toHaveLength(1);
+        expect(out[0].family).toBe("MyFont");
+        expect(out[0].weight).toBe("400"); // default
+        expect(out[0].style).toBe("normal"); // default
+        expect(out[0].url).toBe("https://cdn.example.com/fonts/myfont.woff2");
+        expect(out[0].urls).toEqual(["https://cdn.example.com/fonts/myfont.woff2"]);
+    });
+    it("parses font-weight, font-style, and unicode-range descriptors", () => {
+        const css = `
+      @font-face {
+        font-family: "Geist";
+        font-weight: 400;
+        font-style: italic;
+        src: url("/g.woff2") format("woff2");
+        unicode-range: U+0000-00FF, U+0131;
+      }`;
+        const out = parseFontFaceRulesFromCssText(css, BASE);
+        expect(out).toHaveLength(1);
+        expect(out[0].family).toBe("Geist");
+        expect(out[0].weight).toBe("400");
+        expect(out[0].style).toBe("italic");
+        expect(out[0].unicodeRange).toEqual([[0x0000, 0x00ff], [0x0131, 0x0131]]);
+    });
+    it("ranks src urls woff2 > woff > ttf/otf, skipping eot/svg", () => {
+        const css = `@font-face {
+      font-family: "sdicon";
+      src: url("/sdicon.eot"),
+           url("/sdicon.eot?#iefix") format("embedded-opentype"),
+           url("/sdicon.woff") format("woff"),
+           url("/sdicon.ttf") format("truetype"),
+           url("/sdicon.svg#sdicon") format("svg");
+    }`;
+        const out = parseFontFaceRulesFromCssText(css, BASE);
+        expect(out).toHaveLength(1);
+        // woff first (woff2 not present), then ttf. eot/svg dropped.
+        expect(out[0].urls).toEqual([
+            "https://cdn.example.com/sdicon.woff",
+            "https://cdn.example.com/sdicon.ttf",
+        ]);
+    });
+    it("recurses into @media-nested @font-face (Stripe pattern)", () => {
+        const css = `
+      @media (min-width: 600px) {
+        @font-face {
+          font-family: sohne-var;
+          src: url(/sohne.woff2) format("woff2-variations");
+          font-weight: 1 1000;
+        }
+      }`;
+        const out = parseFontFaceRulesFromCssText(css, BASE);
+        expect(out).toHaveLength(1);
+        expect(out[0].family).toBe("sohne-var");
+        expect(out[0].weight).toBe("1 1000");
+        expect(out[0].url).toBe("https://cdn.example.com/sohne.woff2");
+    });
+    it("strips CSS comments before parsing (no false positives in /* @font-face */ comment)", () => {
+        const css = `
+      /* @font-face { font-family: "ShouldNotMatch"; src: url("nope.woff2"); } */
+      @font-face { font-family: "Real"; src: url("real.woff2"); }
+    `;
+        const out = parseFontFaceRulesFromCssText(css, BASE);
+        expect(out).toHaveLength(1);
+        expect(out[0].family).toBe("Real");
+    });
+    it("handles unquoted family names and resolves relative urls against the base", () => {
+        const css = `@font-face { font-family: MyFont; src: url(./fonts/x.woff2); }`;
+        const out = parseFontFaceRulesFromCssText(css, "https://cdn.example.com/css/site.css");
+        expect(out).toHaveLength(1);
+        expect(out[0].family).toBe("MyFont");
+        expect(out[0].url).toBe("https://cdn.example.com/css/fonts/x.woff2");
+    });
+    it("returns multiple rules when the CSS declares many @font-face entries", () => {
+        const css = `
+      @font-face { font-family: A; src: url(a.woff2); }
+      @font-face { font-family: B; src: url(b.woff2); font-weight: 700; }
+      @font-face { font-family: C; src: url(c.woff2); font-style: italic; }
+    `;
+        const out = parseFontFaceRulesFromCssText(css, BASE);
+        expect(out).toHaveLength(3);
+        expect(out.map((r) => r.family)).toEqual(["A", "B", "C"]);
+        expect(out[1].weight).toBe("700");
+        expect(out[2].style).toBe("italic");
+    });
+    it("skips a rule with no parseable src (all eot/svg)", () => {
+        const css = `@font-face { font-family: X; src: url(x.eot), url(x.svg#x) format("svg"); }`;
+        expect(parseFontFaceRulesFromCssText(css, BASE)).toEqual([]);
+    });
+    it("skips a rule missing font-family", () => {
+        const css = `@font-face { src: url(x.woff2); }`;
+        expect(parseFontFaceRulesFromCssText(css, BASE)).toEqual([]);
+    });
+});

package/dist/cursor-overlay.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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.
+ */
+export interface CursorStyle {
+    /** Pointer variant. v1: only `mouse` is rendered (touch falls through to the same arrow glyph). */
+    pointer: "mouse" | "touch";
+    /**
+     * Inner ring + cursor stroke color. Defaults to white with a thin black
+     * outline so the cursor reads on light and dark backgrounds alike.
+     */
+    cursorFill: string;
+    cursorStroke: string;
+    /** Click pulse stroke color. Default white with a black hairline. */
+    pulseStroke: string;
+    pulseStrokeOuter: string;
+    /** Click pulse duration in ms. Default 500. */
+    pulseDurationMs: number;
+    /** Click pulse max radius (outer edge) in px. Default 32. */
+    pulseRadius: number;
+    /** Cursor scale (1 = the 18-px-tall macOS arrow). Default 1. */
+    cursorScale: number;
+}
+export interface CursorMoveEvent {
+    type: "move";
+    /** Time when the move begins, ms from animation start. */
+    t: number;
+    /** Move duration in ms. Default 0 (instant jump). */
+    duration?: number;
+    /** Absolute viewport-coord target. */
+    to?: {
+        x: number;
+        y: number;
+    };
+    /** Relative offset from current cursor position. */
+    by?: {
+        dx: number;
+        dy: number;
+    };
+    /** CSS selector. Cursor moves to the center of the matched element's rect. */
+    selector?: string;
+    /** Optional offset added to `selector`'s resolved center. */
+    offset?: {
+        dx: number;
+        dy: number;
+    };
+}
+export interface CursorClickEvent {
+    type: "click";
+    t: number;
+    /** Default `primary`. `middle` renders identically to `primary`. */
+    button?: "primary" | "secondary" | "middle";
+    /** Per-event style override (merged on top of `CursorOverlay.style`). */
+    style?: Partial<CursorStyle>;
+}
+export interface CursorShowEvent {
+    type: "show";
+    t: number;
+    x: number;
+    y: number;
+}
+export interface CursorHideEvent {
+    type: "hide";
+    t: number;
+}
+export type CursorEvent = CursorMoveEvent | CursorClickEvent | CursorShowEvent | CursorHideEvent;
+export interface CursorOverlay {
+    events: CursorEvent[];
+    /** Default styles for every event. Per-event `style` overrides take precedence. */
+    style?: Partial<CursorStyle>;
+}
+/** Optional resolver for `selector`-based move events. */
+export type SelectorResolver = (sel: string, frameIndex: number) => {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | null;
+interface KeyframePoint {
+    t: number;
+    x: number;
+    y: number;
+    visible: boolean;
+}
+interface ResolvedClick {
+    t: number;
+    x: number;
+    y: number;
+    button: "primary" | "secondary" | "middle";
+    style: CursorStyle;
+}
+/**
+ * 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 declare function resolveCursorScript(overlay: CursorOverlay, totalDurationMs: number, frameStartTimes: number[], resolveSelector: SelectorResolver | null): {
+    positions: KeyframePoint[];
+    clicks: ResolvedClick[];
+    style: CursorStyle;
+};
+/**
+ * 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 declare function cursorOverlayMarkup(positions: KeyframePoint[], clicks: ResolvedClick[], style: CursorStyle, totalDurationMs: number): string;
+export {};