domotion-svg 0.1.1

package/src/coretext-helper.ts

@@ -0,0 +1,256 @@
+/**
+ * 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: boolean | null = null;
+export function isCoretextHelperAvailable(): boolean {
+  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;
+}
+
+interface PathCommand { command: string; args: number[] }
+
+interface CoretextGlyph {
+  id: number;
+  advanceWidth: number;
+  path: { commands: PathCommand[] };
+  codePoints?: number[];
+}
+
+interface MetaResponse {
+  unitsPerEm: number;
+  ascent: number;
+  descent: number;
+  underlinePosition?: number;
+  underlineThickness?: number;
+  strikeoutPosition?: number;
+  strikeoutThickness?: number;
+}
+
+interface GlyphResponse {
+  id: number;
+  advance: number;
+  bbox: { x: number; y: number; w: number; h: number };
+  d: string;
+}
+
+// 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: string): PathCommand[] {
+  if (d.length === 0) return [];
+  const tokens = d.match(/[MLQCZ]|-?\d+(?:\.\d+)?/g) ?? [];
+  const out: PathCommand[] = [];
+  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;
+}
+
+// Spawn the helper once, request meta + a batch of glyphs in one envelope.
+interface HelperRequest {
+  fonts: Array<{ ref: string; postscriptName?: string; fontPath?: string; size: number }>;
+  queries: Array<
+    | { type: "meta"; fontRef: string }
+    | { type: "glyphs"; fontRef: string; glyphs: Array<{ cp?: number; id?: number }> }
+  >;
+}
+interface HelperResponse {
+  results: Array<MetaResponse & { type: "meta" } | { type: "glyphs"; glyphs: GlyphResponse[] }>;
+}
+
+function callHelper(request: HelperRequest): HelperResponse {
+  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 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 function createCoretextFont(spec: {
+  postscriptName?: string;
+  fontPath?: string;
+}): CoretextFontInstance | null {
+  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: MetaResponse;
+  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<number, CoretextGlyph>();
+  const idToGlyph = new Map<number, CoretextGlyph>();
+  const missingCp = new Set<number>();
+
+  function fetchByCps(cps: number[]): void {
+    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: CoretextGlyph = {
+        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: number): CoretextGlyph {
+    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: CoretextGlyph = { id, advanceWidth: 0, path: { commands: [] } };
+      idToGlyph.set(id, empty);
+      return empty;
+    }
+    const g = r.glyphs[0];
+    const glyph: CoretextGlyph = {
+      id: g.id,
+      advanceWidth: g.advance,
+      path: { commands: parseSvgPath(g.d) }
+    };
+    idToGlyph.set(id, glyph);
+    return glyph;
+  }
+
+  function notdef(id = 0): CoretextGlyph {
+    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: number): CoretextGlyph {
+      if (missingCp.has(cp)) return notdef(0);
+      if (!cpToGlyph.has(cp)) fetchByCps([cp]);
+      return cpToGlyph.get(cp) ?? notdef(0);
+    },
+
+    getGlyph(id: number): CoretextGlyph {
+      return fetchById(id);
+    },
+
+    layout(text: string): {
+      glyphs: CoretextGlyph[];
+      positions: Array<{ xAdvance: number; yAdvance: number; xOffset: number; yOffset: number }>;
+    } {
+      // Batch every codepoint in one helper call before assembling the result.
+      const cps: number[] = [];
+      for (const ch of text) cps.push(ch.codePointAt(0)!);
+      fetchByCps(cps);
+
+      const glyphs: CoretextGlyph[] = [];
+      const positions: Array<{ xAdvance: number; yAdvance: number; xOffset: number; yOffset: number }> = [];
+      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(): void {
+  helperAvailable = null;
+}

package/src/cross-origin-font-face.test.ts

@@ -0,0 +1,119 @@
+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/src/cursor-overlay.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import { type CursorOverlay, type SelectorResolver, 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: CursorOverlay = {
+      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: CursorOverlay = {
+      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: SelectorResolver = () => ({ 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: CursorOverlay = {
+      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: CursorOverlay = {
+      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: CursorOverlay = {
+      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');
+  });
+});