domotion-svg 0.1.1

package/src/conic-raster.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from "vitest";
+import { rasterizeConic, resolveConicStops } from "./conic-raster.js";
+import { parseConicGradient } from "./gradients.js";
+
+function pixel(buf: Buffer, w: number, x: number, y: number): { r: number; g: number; b: number; a: number } {
+  const i = (y * w + x) * 4;
+  return { r: buf[i], g: buf[i + 1], b: buf[i + 2], a: buf[i + 3] };
+}
+
+describe("resolveConicStops (DM-549)", () => {
+  it("auto-distributes stops without explicit positions", () => {
+    const g = parseConicGradient("conic-gradient(red, yellow, green, blue)");
+    const stops = resolveConicStops(g!.stops);
+    expect(stops).toHaveLength(4);
+    expect(stops[0].offset).toBe(0);
+    expect(stops[1].offset).toBeCloseTo(1 / 3);
+    expect(stops[2].offset).toBeCloseTo(2 / 3);
+    expect(stops[3].offset).toBe(1);
+  });
+
+  it("preserves explicit angle positions", () => {
+    const g = parseConicGradient("conic-gradient(red 0deg, yellow 90deg, blue 180deg)");
+    const stops = resolveConicStops(g!.stops);
+    expect(stops[0].offset).toBe(0);
+    expect(stops[1].offset).toBe(0.25);
+    expect(stops[2].offset).toBe(0.5);
+  });
+
+  it("emits hard stops as adjacent positions with same offset boundary", () => {
+    const g = parseConicGradient("conic-gradient(red 0% 25%, blue 25% 50%)");
+    const stops = resolveConicStops(g!.stops);
+    expect(stops).toHaveLength(4);
+    // The two middle stops both sit at 0.25.
+    expect(stops[1].offset).toBe(0.25);
+    expect(stops[2].offset).toBe(0.25);
+  });
+});
+
+describe("rasterizeConic: smooth color sweep (DM-549)", () => {
+  const g = parseConicGradient("conic-gradient(red, blue)")!;
+  const w = 32, h = 32;
+  const buf = rasterizeConic(g, w, h);
+
+  it("produces a non-empty buffer of the right size", () => {
+    expect(buf.length).toBe(w * h * 4);
+  });
+
+  it("paints pure red at the top center (sweep origin)", () => {
+    // Just below the top edge at center x → angle ≈ 0 → first stop = red.
+    const px = pixel(buf, w, 16, 0);
+    expect(px.r).toBeGreaterThan(240);
+    expect(px.g).toBeLessThan(20);
+    expect(px.b).toBeLessThan(20);
+    expect(px.a).toBe(255);
+  });
+
+  it("paints pure red at the bottom center too (last stop wraps to first)", () => {
+    // The non-repeating gradient has only two stops (red at 0, blue at 1).
+    // At the bottom-center (angle ≈ 180°) we're at fraction 0.5 — that's
+    // the midpoint between red and blue, not pure red.
+    const px = pixel(buf, w, 16, h - 1);
+    // Halfway between rgb(255,0,0) and rgb(0,0,255) is rgb(128,0,128).
+    expect(px.r).toBeGreaterThan(100);
+    expect(px.r).toBeLessThan(160);
+    expect(px.b).toBeGreaterThan(100);
+    expect(px.b).toBeLessThan(160);
+  });
+});
+
+describe("rasterizeConic: hard-stop checkerboard (DM-549, the canonical case)", () => {
+  // The 19-deep-color-mix tile: `repeating-conic-gradient(#ddd 0 25%, white 0 50%) 0/24px 24px`
+  // produces a four-quadrant alternating tile. We rasterize a 24×24 tile.
+  const g = parseConicGradient("repeating-conic-gradient(#ddd 0 25%, white 0 50%)")!;
+  const w = 24, h = 24;
+  const buf = rasterizeConic(g, w, h);
+
+  it("top-right quadrant (12 → 3 o'clock sweep, 0..25%) is #ddd", () => {
+    const px = pixel(buf, w, 18, 6);
+    // #ddd = rgb(221, 221, 221)
+    expect(px.r).toBe(221);
+    expect(px.g).toBe(221);
+    expect(px.b).toBe(221);
+  });
+
+  it("bottom-right quadrant (3 → 6 o'clock sweep, 25..50%) is white", () => {
+    const px = pixel(buf, w, 18, 18);
+    expect(px.r).toBe(255);
+    expect(px.g).toBe(255);
+    expect(px.b).toBe(255);
+  });
+
+  it("bottom-left quadrant (6 → 9 o'clock sweep, 50..75% wraps to #ddd) is #ddd", () => {
+    // Repeating period is 50% (one #ddd quadrant + one white quadrant), so
+    // the 50..75% sweep wraps back to #ddd.
+    const px = pixel(buf, w, 6, 18);
+    expect(px.r).toBe(221);
+    expect(px.g).toBe(221);
+    expect(px.b).toBe(221);
+  });
+
+  it("top-left quadrant (9 → 12 o'clock sweep, 75..100% wraps to white) is white", () => {
+    const px = pixel(buf, w, 6, 6);
+    expect(px.r).toBe(255);
+    expect(px.g).toBe(255);
+    expect(px.b).toBe(255);
+  });
+});
+
+describe("rasterizeConic: from <angle> rotates the origin (DM-549)", () => {
+  const g = parseConicGradient("conic-gradient(from 90deg, red 0% 25%, blue 25% 50%)")!;
+  const w = 32, h = 32;
+  const buf = rasterizeConic(g, w, h);
+
+  it("with from=90deg, the red 0..25% wedge sits at 3-6 o'clock (right side, going down)", () => {
+    // CSS `from 90deg` shifts the sweep origin 90deg clockwise from the top:
+    //   0%  → 3 o'clock (right)
+    //   25% → 6 o'clock (bottom)
+    // The red wedge spans 0..25%, so a point at the right edge slightly
+    // below center sits at frac ≈ 0.0..0.125 — pure red.
+    const px = pixel(buf, w, w - 1, h / 2 + 2);
+    expect(px.r).toBeGreaterThan(240);
+    expect(px.b).toBeLessThan(20);
+  });
+
+  it("with from=90deg, the top-center is past the 50% boundary (clamped to blue)", () => {
+    // Top-center: angle ≈ 0deg from north. After from=90deg shift: frac ≈ 0.75.
+    // Past the last stop (0.5) → clamps to blue.
+    const px = pixel(buf, w, w / 2, 1);
+    expect(px.b).toBeGreaterThan(240);
+    expect(px.r).toBeLessThan(20);
+  });
+});
+
+describe("rasterizeConicGradients pre-pass + buildConicGradientDef end-to-end (DM-549/550)", () => {
+  it("populates the conic tile cache and the renderer emits <pattern><image>", async () => {
+    const { rasterizeConicGradients } = await import("./conic-raster.js");
+    const { _conicTileCache } = await import("./dom-to-svg.js");
+    _conicTileCache.clear();
+
+    // Minimal captured-tree shape with a conic-gradient bg layer.
+    const tree: any = [{
+      tagName: "div",
+      x: 0, y: 0, width: 24, height: 24,
+      styles: {
+        backgroundImage: "repeating-conic-gradient(#ddd 0 25%, white 0 50%)",
+        backgroundSize: "24px 24px",
+      },
+      children: [],
+    }];
+
+    await rasterizeConicGradients(tree as any, { hiDPIFactor: 2 });
+
+    const layer = "repeating-conic-gradient(#ddd 0 25%, white 0 50%)";
+    const sizeCache = _conicTileCache.get(layer);
+    expect(sizeCache).toBeDefined();
+    expect(sizeCache!.has("24x24")).toBe(true);
+    const dataUri = sizeCache!.get("24x24")!;
+    expect(dataUri.startsWith("data:image/png;base64,")).toBe(true);
+  });
+
+  it("dedupes (layerText, tileSize) tuples — multiple consumers share one cache entry", async () => {
+    const { rasterizeConicGradients } = await import("./conic-raster.js");
+    const { _conicTileCache } = await import("./dom-to-svg.js");
+    _conicTileCache.clear();
+
+    const layer = "conic-gradient(red, blue)";
+    // Three sibling elements all painting the same conic.
+    const tree: any = [
+      { tagName: "div", x: 0, y: 0, width: 100, height: 100, styles: { backgroundImage: layer }, children: [] },
+      { tagName: "div", x: 0, y: 100, width: 100, height: 100, styles: { backgroundImage: layer }, children: [] },
+      { tagName: "div", x: 0, y: 200, width: 100, height: 100, styles: { backgroundImage: layer }, children: [] },
+    ];
+    await rasterizeConicGradients(tree as any, { hiDPIFactor: 2 });
+    const sizeCache = _conicTileCache.get(layer);
+    // All three consumers have the same rect (100×100, default size=auto so
+    // tile == element) — cache should have exactly one entry.
+    expect(sizeCache?.size).toBe(1);
+    expect(sizeCache?.has("100x100")).toBe(true);
+  });
+
+  it("skips trees with no conic content (no cache pollution)", async () => {
+    const { rasterizeConicGradients } = await import("./conic-raster.js");
+    const { _conicTileCache } = await import("./dom-to-svg.js");
+    _conicTileCache.clear();
+
+    const tree: any = [{
+      tagName: "div",
+      x: 0, y: 0, width: 100, height: 100,
+      styles: {
+        backgroundImage: "linear-gradient(red, blue)",
+      },
+      children: [],
+    }];
+    await rasterizeConicGradients(tree as any, { hiDPIFactor: 2 });
+    expect(_conicTileCache.size).toBe(0);
+  });
+});
+
+describe("rasterizeConic: at <position> moves the center (DM-549)", () => {
+  const g = parseConicGradient("conic-gradient(at 0% 0%, red, blue)")!;
+  const w = 32, h = 32;
+  const buf = rasterizeConic(g, w, h);
+
+  it("with center at (0,0), the bottom-right is far from origin and blends red→blue", () => {
+    // Bottom-right pixel: angle from (0,0) is 135° measured from screen-down.
+    // That's frac ≈ 0.375 in the conic sweep (from-top, clockwise) which lies
+    // in the red→blue interpolation.
+    const px = pixel(buf, w, w - 1, h - 1);
+    // Should be a mix, neither pure red nor pure blue.
+    expect(px.r).toBeGreaterThan(60);
+    expect(px.b).toBeGreaterThan(60);
+  });
+});

package/src/conic-raster.ts

@@ -0,0 +1,309 @@
+/**
+ * DM-549 — Conic-gradient rasterizer + tile cache + capture-tree pre-pass.
+ * See `docs/28-conic-gradient.md`.
+ *
+ * SVG has no native conic-gradient primitive. We rasterize each captured
+ * `conic-gradient(...)` / `repeating-conic-gradient(...)` background layer
+ * into a PNG tile (via sharp) and the renderer emits the bytes as
+ * `<pattern><image href="data:image/png;base64,…"/></pattern>` (DM-550).
+ *
+ * The pre-pass walks the captured tree, dedupes (layerText, tileW, tileH)
+ * tuples, rasterizes each unique tuple once at `tile × hiDPIFactor` then
+ * downsamples through sharp's lanczos kernel for antialiased edges, and
+ * stashes the resulting data URI in `_conicTileCache` keyed by
+ * `(layerText, "${tileW}x${tileH}")`.
+ */
+
+import sharp from "sharp";
+import {
+  _conicTileCache,
+  type CapturedElement,
+  type RGBA,
+  parseColor,
+} from "./dom-to-svg.js";
+import { parseConicGradient, type ConicGradient, type ConicStop, type PosValue } from "./gradients.js";
+
+export interface RasterizeConicOptions {
+  /**
+   * Multiplier on each tile's CSS-px dimensions when allocating the raw
+   * pixel buffer. The buffer is then downsampled through sharp.lanczos3 to
+   * the tile size for antialiased hard-stop edges. Default 2.0 — matches the
+   * embed pipeline's `embedRemoteImagesHiDPIFactor` per user direction.
+   * Values < 1 are clamped to 1.
+   */
+  hiDPIFactor?: number;
+}
+
+const DEFAULT_HIDPI_FACTOR = 2;
+const MIN_HIDPI_FACTOR = 1;
+
+/**
+ * Walk the captured tree, identify every conic-gradient background layer
+ * with a known consumer rect, and populate `_conicTileCache` with rasterized
+ * PNG bytes for each unique (layerText, tileW, tileH) tuple.
+ *
+ * Idempotent: re-running with the same tree is a no-op (each tuple's PNG
+ * is already cached).
+ */
+export async function rasterizeConicGradients(
+  tree: CapturedElement[],
+  options: RasterizeConicOptions = {},
+): Promise<void> {
+  const hiDPI = Math.max(MIN_HIDPI_FACTOR, options.hiDPIFactor ?? DEFAULT_HIDPI_FACTOR);
+
+  type Tuple = { layerText: string; gradient: ConicGradient; sizeKey: string; tileW: number; tileH: number };
+  const tuples = new Map<string, Tuple>();
+
+  const consider = (layerText: string, tileW: number, tileH: number): void => {
+    const tw = Math.max(1, Math.round(tileW));
+    const th = Math.max(1, Math.round(tileH));
+    const sizeKey = `${tw}x${th}`;
+    const dedupeKey = `${layerText}\n${sizeKey}`;
+    if (tuples.has(dedupeKey)) return;
+    const sizeCache = _conicTileCache.get(layerText);
+    if (sizeCache != null && sizeCache.has(sizeKey)) return;
+    const gradient = parseConicGradient(layerText);
+    if (gradient == null) return;
+    tuples.set(dedupeKey, { layerText, gradient, sizeKey, tileW: tw, tileH: th });
+  };
+
+  const walk = (els: CapturedElement[]): void => {
+    for (const el of els) {
+      const bgImage = el.styles.backgroundImage;
+      if (bgImage != null && bgImage !== "" && bgImage !== "none" && /conic-gradient/i.test(bgImage)) {
+        const layers = splitTopLevelCommas(bgImage);
+        const sizes = splitTopLevelCommas(el.styles.backgroundSize ?? "auto");
+        for (let li = 0; li < layers.length; li++) {
+          const layer = layers[li].trim();
+          if (!/^(?:repeating-)?conic-gradient\(/i.test(layer)) continue;
+          const sizeCss = (sizes[li] ?? sizes[0] ?? "auto").trim();
+          const tile = computeTileSize(sizeCss, el.width, el.height);
+          consider(layer, tile.w, tile.h);
+        }
+      }
+      if (el.children.length > 0) walk(el.children);
+    }
+  };
+  walk(tree);
+  if (tuples.size === 0) return;
+
+  const tasks = Array.from(tuples.values(), async ({ layerText, gradient, sizeKey, tileW, tileH }) => {
+    try {
+      const renderW = Math.max(1, Math.round(tileW * hiDPI));
+      const renderH = Math.max(1, Math.round(tileH * hiDPI));
+      const raw = rasterizeConic(gradient, renderW, renderH);
+      // Decode raw RGBA → PNG bytes via sharp, downsampling to the CSS-px tile
+      // size with lanczos3 so hard-stop edges keep subpixel antialiasing that
+      // matches Chromium's painted output.
+      const png = await sharp(raw, { raw: { width: renderW, height: renderH, channels: 4 } })
+        .resize(tileW, tileH, { fit: "fill", kernel: "lanczos3" })
+        .png({ compressionLevel: 9 })
+        .toBuffer();
+      const dataUri = `data:image/png;base64,${png.toString("base64")}`;
+      rememberConicTile(layerText, sizeKey, dataUri);
+    } catch {
+      // Per-tuple failure: leave the cache miss in place; renderer falls back
+      // to the parse-failure warning path.
+    }
+  });
+  await Promise.all(tasks);
+}
+
+/**
+ * Rasterize a parsed conic gradient into a raw RGBA buffer of size
+ * `width × height`. Pure CPU; no I/O. Caller is responsible for downsampling
+ * / encoding (this module's pre-pass routes the raw buffer through sharp).
+ *
+ * Algorithm: per pixel, compute the angle from the gradient center, normalize
+ * to a fractional sweep offset in [0, 1), look up the color via stop-list
+ * interpolation, and write RGBA bytes.
+ */
+export function rasterizeConic(
+  gradient: ConicGradient,
+  width: number,
+  height: number,
+): Buffer {
+  const buf = Buffer.allocUnsafe(width * height * 4);
+  const cx = resolvePx(gradient.position.x, width);
+  const cy = resolvePx(gradient.position.y, height);
+  // CSS conic: 0deg = top, sweep clockwise. atan2 in screen coords (y down)
+  // gives angle from +x axis, counterclockwise (mathematical). To convert:
+  //   visualDeg = atan2(y - cy, x - cx) * 180/π + 90  // shift so 0 = top
+  // then add fromAngleDeg, then normalize to [0, 1).
+  // The `+ 90` rotates the +x axis (mathematical 0deg = right) to the top
+  // (CSS 0deg = top). Sweep direction: CSS clockwise == screen clockwise
+  // (both have y increasing downward), so atan2's natural counterclockwise
+  // signing inverts to clockwise correctly when we negate (or equivalently
+  // when the gradient stop offsets increase along clockwise sweep).
+  const stops = resolveConicStops(gradient.stops);
+  if (stops.length === 0) {
+    buf.fill(0);
+    return buf;
+  }
+  const repeating = gradient.repeating === true;
+  let i = 0;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const dx = x + 0.5 - cx;
+      const dy = y + 0.5 - cy;
+      // CSS conic: 0deg = top (12 o'clock), sweep clockwise. atan2(dx, -dy)
+      // gives an angle in [-π, π] where 0 = top and positive sweeps clockwise
+      // (because y increases downward in screen coords, so -dy points toward
+      // the top). Convert to a [0, 1) fractional offset around the sweep.
+      let theta = Math.atan2(dx, -dy);
+      let frac = theta / (Math.PI * 2);
+      frac -= gradient.fromAngleDeg / 360;
+      // Normalize to [0, 1).
+      frac = frac - Math.floor(frac);
+      const color = lookupColor(stops, frac, repeating);
+      buf[i++] = color.r;
+      buf[i++] = color.g;
+      buf[i++] = color.b;
+      buf[i++] = Math.round(color.a * 255);
+    }
+  }
+  return buf;
+}
+
+interface ResolvedStop {
+  rgba: RGBA;
+  offset: number;
+}
+
+/**
+ * Resolve conic-gradient stop offsets for rasterization. Auto-distributes
+ * stops without explicit positions (CSS rule: missing position = midpoint
+ * between neighbors with positions; first defaults to 0; last defaults to 1).
+ * Drops stops whose color can't be parsed.
+ */
+export function resolveConicStops(stops: ConicStop[]): ResolvedStop[] {
+  if (stops.length === 0) return [];
+  const out: { rgba: RGBA; offset?: number; rawPos?: string }[] = stops.map((s) => ({
+    rgba: parseColor(s.color) ?? { r: 0, g: 0, b: 0, a: 0 },
+    offset: s.offset,
+    rawPos: s.rawPos,
+  }));
+  if (out[0].offset == null) out[0].offset = 0;
+  if (out[out.length - 1].offset == null) out[out.length - 1].offset = 1;
+  let i = 0;
+  while (i < out.length) {
+    if (out[i].offset != null) { i++; continue; }
+    let j = i + 1;
+    while (j < out.length && out[j].offset == null) j++;
+    const prev = out[i - 1].offset ?? 0;
+    const next = out[j]?.offset ?? 1;
+    const span = j - i + 1;
+    for (let k = i; k < j; k++) {
+      out[k].offset = prev + ((next - prev) * (k - (i - 1))) / span;
+    }
+    i = j;
+  }
+  // Enforce monotonicity: each stop's effective offset is max(self, previous).
+  let max = out[0].offset!;
+  for (const s of out) {
+    if (s.offset! < max) s.offset = max;
+    if (s.offset! > max) max = s.offset!;
+  }
+  return out.map((s) => ({ rgba: s.rgba, offset: s.offset! }));
+}
+
+/**
+ * Look up the interpolated color at `frac` ∈ [0, 1) in a resolved stop list.
+ * For repeating gradients, mod the input by the stop period before lookup;
+ * for non-repeating, clamp to the first/last stop outside [first.offset, last.offset].
+ */
+function lookupColor(stops: ResolvedStop[], frac: number, repeating: boolean): RGBA {
+  if (stops.length === 1) return stops[0].rgba;
+  const first = stops[0].offset;
+  const last = stops[stops.length - 1].offset;
+  if (repeating) {
+    const period = last - first;
+    if (period > 0) {
+      const t = ((frac - first) / period);
+      const wrapped = t - Math.floor(t);
+      frac = first + wrapped * period;
+    }
+  } else {
+    if (frac <= first) return stops[0].rgba;
+    if (frac >= last) return stops[stops.length - 1].rgba;
+  }
+  // Find the bracketing pair.
+  for (let i = 1; i < stops.length; i++) {
+    if (stops[i].offset >= frac) {
+      const a = stops[i - 1];
+      const b = stops[i];
+      const span = b.offset - a.offset;
+      if (span <= 0) return b.rgba; // hard stop
+      const t = (frac - a.offset) / span;
+      return blendRgba(a.rgba, b.rgba, t);
+    }
+  }
+  return stops[stops.length - 1].rgba;
+}
+
+function blendRgba(a: RGBA, b: RGBA, t: number): RGBA {
+  return {
+    r: Math.round(a.r + (b.r - a.r) * t),
+    g: Math.round(a.g + (b.g - a.g) * t),
+    b: Math.round(a.b + (b.b - a.b) * t),
+    a: a.a + (b.a - a.a) * t,
+  };
+}
+
+function resolvePx(p: PosValue, extent: number): number {
+  if (p.kind === "px") return p.value;
+  return p.value * extent;
+}
+
+/**
+ * Resolve a `background-size` value to a tile (w, h) in CSS px. `auto`,
+ * `cover`, `contain` all map to the element rect (no intrinsic for a
+ * gradient — there's no way to compute a smaller tile). Numeric values
+ * (px / %) resolve normally. Single-axis values default the missing axis
+ * to `auto` per CSS.
+ */
+function computeTileSize(sizeCss: string, elW: number, elH: number): { w: number; h: number } {
+  const trimmed = sizeCss.trim();
+  if (trimmed === "" || trimmed === "auto" || trimmed === "cover" || trimmed === "contain") {
+    return { w: elW, h: elH };
+  }
+  const parts = trimmed.split(/\s+/);
+  const parseDim = (tok: string, basis: number): number => {
+    if (tok === "auto") return basis;
+    const m = /^(-?\d+(?:\.\d+)?|-?\.\d+)(%|px)?$/.exec(tok);
+    if (m == null) return basis;
+    const v = parseFloat(m[1]);
+    const unit = m[2] ?? "px";
+    if (unit === "%") return (v / 100) * basis;
+    return v;
+  };
+  const w = parseDim(parts[0], elW);
+  const h = parts.length > 1 ? parseDim(parts[1], elH) : w;
+  return { w, h };
+}
+
+function rememberConicTile(layerText: string, sizeKey: string, dataUri: string): void {
+  let sizeCache = _conicTileCache.get(layerText);
+  if (sizeCache == null) {
+    sizeCache = new Map<string, string>();
+    _conicTileCache.set(layerText, sizeCache);
+  }
+  sizeCache.set(sizeKey, dataUri);
+}
+
+function splitTopLevelCommas(s: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "(") depth++;
+    else if (c === ")") depth--;
+    else if (c === "," && depth === 0) {
+      out.push(s.slice(start, i));
+      start = i + 1;
+    }
+  }
+  out.push(s.slice(start));
+  return out;
+}

package/src/coretext-extractor.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import { spawnSync } from "node:child_process";
+import { existsSync, openSync } from "node:fs";
+import path from "node:path";
+import * as fontkit from "fontkit";
+
+// DM-385 / DM-387: validates the Swift CoreText helper.
+// Tests are skipped automatically when:
+//   - we're not on macOS (the helper is platform-specific)
+//   - the helper binary isn't built yet (developer hasn't run build.sh)
+// so this file doesn't break Linux/Windows CI before DM-389/DM-390 land.
+
+const HELPER = path.resolve(
+  path.dirname(new URL(import.meta.url).pathname),
+  "..",
+  "tools",
+  "macos-glyph-extractor",
+  "domotion-glyph-paths"
+);
+
+const helperAvailable = process.platform === "darwin" && existsSync(HELPER);
+const describeHelper = helperAvailable ? describe : describe.skip;
+
+interface GlyphResult {
+  id: number;
+  advance: number;
+  bbox: { x: number; y: number; w: number; h: number };
+  d: string;
+}
+interface MetaResult {
+  unitsPerEm: number;
+  ascent: number;
+  descent: number;
+  underlinePosition?: number;
+  underlineThickness?: number;
+  strikeoutPosition?: number;
+  strikeoutThickness?: number;
+}
+
+function callHelper(request: unknown): { results: any[] } {
+  const proc = spawnSync(HELPER, [], {
+    input: JSON.stringify(request),
+    encoding: "utf-8"
+  });
+  if (proc.status !== 0) {
+    throw new Error(`helper exit ${proc.status}: ${proc.stderr}`);
+  }
+  return JSON.parse(proc.stdout);
+}
+
+describeHelper("CoreText glyph extractor", () => {
+  it("extracts the Helvetica H outline at 100pt", () => {
+    const response = callHelper({
+      fonts: [{ ref: "h", postscriptName: "Helvetica", size: 100 }],
+      queries: [
+        { type: "meta", fontRef: "h" },
+        { type: "glyphs", fontRef: "h", glyphs: [{ cp: 0x48 }] }
+      ]
+    });
+
+    const meta = response.results[0] as MetaResult;
+    const glyphResult = response.results[1] as { glyphs: GlyphResult[] };
+
+    expect(meta.unitsPerEm).toBe(2048);
+    const H = glyphResult.glyphs[0];
+    expect(H.id).toBeGreaterThan(0);
+    expect(H.d).toMatch(/^M /);
+    expect(H.d).toMatch(/Z$/);
+    expect(H.advance).toBeGreaterThan(60);
+    expect(H.advance).toBeLessThan(80);
+  });
+
+  it("extracts PingFang 漢 (U+6F22) where fontkit can't (DM-382)", () => {
+    const response = callHelper({
+      fonts: [{ ref: "p", postscriptName: "PingFangSC-Regular", size: 22 }],
+      queries: [{ type: "glyphs", fontRef: "p", glyphs: [{ cp: 0x6F22 }] }]
+    });
+    const result = response.results[0] as { glyphs: GlyphResult[] };
+    const han = result.glyphs[0];
+    expect(han.id).toBeGreaterThan(0);
+    expect(han.d.length).toBeGreaterThan(0);
+    expect(han.advance).toBeGreaterThan(0);
+  });
+
+  it("agrees with fontkit on Helvetica H advance within 1%", () => {
+    const SIZE = 100;
+    const response = callHelper({
+      fonts: [{ ref: "h", postscriptName: "Helvetica", size: SIZE }],
+      queries: [
+        { type: "meta", fontRef: "h" },
+        { type: "glyphs", fontRef: "h", glyphs: [{ cp: 0x48 }] }
+      ]
+    });
+    const meta = response.results[0] as MetaResult;
+    const ctH = (response.results[1] as { glyphs: GlyphResult[] }).glyphs[0];
+
+    const collection = fontkit.openSync("/System/Library/Fonts/Helvetica.ttc") as any;
+    const helvetica = collection.getFont != null ? collection.getFont("Helvetica") : collection;
+    const fkGlyph = helvetica.glyphForCodePoint(0x48);
+    const fkAdvancePoints = (fkGlyph.advanceWidth * SIZE) / meta.unitsPerEm;
+
+    expect(Math.abs(ctH.advance - fkAdvancePoints)).toBeLessThan(fkAdvancePoints * 0.01);
+  });
+
+  it("returns id=0 / empty path for codepoints the font lacks", () => {
+    const response = callHelper({
+      fonts: [{ ref: "h", postscriptName: "Helvetica", size: 16 }],
+      queries: [{ type: "glyphs", fontRef: "h", glyphs: [{ cp: 0x6F22 }] }] // Han ideograph in Helvetica
+    });
+    const result = response.results[0] as { glyphs: GlyphResult[] };
+    expect(result.glyphs[0].id).toBe(0);
+    expect(result.glyphs[0].d).toBe("");
+  });
+
+  it("accepts pre-resolved glyph ids in addition to codepoints", () => {
+    const probe = callHelper({
+      fonts: [{ ref: "h", postscriptName: "Helvetica", size: 16 }],
+      queries: [{ type: "glyphs", fontRef: "h", glyphs: [{ cp: 0x48 }] }]
+    });
+    const id = (probe.results[0] as { glyphs: GlyphResult[] }).glyphs[0].id;
+
+    const byId = callHelper({
+      fonts: [{ ref: "h", postscriptName: "Helvetica", size: 16 }],
+      queries: [{ type: "glyphs", fontRef: "h", glyphs: [{ id }] }]
+    });
+    const byIdGlyph = (byId.results[0] as { glyphs: GlyphResult[] }).glyphs[0];
+    expect(byIdGlyph.id).toBe(id);
+    expect(byIdGlyph.d.length).toBeGreaterThan(0);
+  });
+});