domotion-svg 0.1.1

package/dist/text-renderer.test.js

@@ -0,0 +1,150 @@
+import { describe, expect, it } from "vitest";
+import { rasterGlyphOverlays, renderSingleLineText } from "./text-renderer.js";
+describe("rasterGlyphOverlays — emoji bitmap sizing (DM-381)", () => {
+    // The captured per-char rect spans the line-box height (~lineHeight) and
+    // the glyph advance — bigger than what Chrome actually paints, which is
+    // the em-square (fontSize × fontSize) anchored to the baseline. The
+    // overlay emits the bitmap at em-square size centered in the rect so the
+    // <image> dims match Chrome's painted region instead of being stretched
+    // out to the full line-box.
+    const seg = {
+        text: "😀",
+        x: 347.7, y: 695.4, width: 23, height: 25,
+        rasterGlyphs: [{
+                charIndex: 0,
+                rect: { x: 347.7, y: 695.4, width: 23, height: 25 },
+                dataUri: "data:image/png;base64,iVBORw0KGgo="
+            }]
+    };
+    it("emits the bitmap at the captured rect coords + dims (DM-401 / DM-411 / DM-414)", () => {
+        // The screenshot was captured from Chrome's actual paint at this rect,
+        // so re-embedding at the same coords + dims preserves the painted
+        // geometry pixel-for-pixel. Avoid the prior em-square-stretch which
+        // squished tall line-box rects horizontally and rendered emojis
+        // visibly larger than Chrome's actual paint.
+        const out = rasterGlyphOverlays(seg, 22, "ct1");
+        expect(out).toContain('x="347.7"');
+        expect(out).toContain('y="695.4"');
+        expect(out).toContain('width="23"');
+        expect(out).toContain('height="25"');
+        expect(out).toContain('preserveAspectRatio="none"');
+    });
+    it("ignores fontSize for sizing — the captured rect dims are authoritative", () => {
+        const segWithFs = { ...seg, fontSize: 32 };
+        const out = rasterGlyphOverlays(segWithFs, 16, "ct1");
+        expect(out).toContain('width="23"');
+        expect(out).toContain('height="25"');
+    });
+    it("returns empty when there are no resolved dataUris", () => {
+        const empty = { ...seg, rasterGlyphs: [{ charIndex: 0, rect: seg.rect, dataUri: undefined }] };
+        expect(rasterGlyphOverlays(empty, 22, "ct1")).toBe("");
+    });
+    it("returns empty when the segment has no rasterGlyphs at all", () => {
+        expect(rasterGlyphOverlays({ ...seg, rasterGlyphs: undefined }, 22, "ct1")).toBe("");
+    });
+});
+describe("renderSingleLineText — pseudo-only segment positioning (DM-495)", () => {
+    // When a host element has no main text and only a positioned ::after / ::before
+    // pseudo, the segment carries its own x/y/color/fontSize. Before DM-495 the
+    // single-segment path read host-level fields exclusively, so the pseudo's
+    // text was emitted at translate(0,0) in the host's color (typically the
+    // inherited default black) instead of at the pseudo's anchor in its own
+    // CSS-declared color. Capture sets host textLeft/textTop/textWidth from
+    // the pseudo seg in this case, and the renderer reads seg.color /
+    // seg.fontSize / seg.fontWeight / seg.fontAscent so all per-pseudo
+    // overrides flow through.
+    const baseStyles = {
+        color: "rgb(0,0,0)",
+        fontSize: "16px",
+        fontFamily: "-apple-system, sans-serif",
+        fontWeight: "400",
+        fontStyle: "normal",
+        direction: "ltr",
+        textDecorationLine: "none",
+        textDecorationColor: "currentcolor",
+        textDecorationStyle: "solid",
+    };
+    const makeEl = (seg) => ({
+        tag: "span",
+        x: 100, y: 50, width: 200, height: 80,
+        textLeft: seg.x, textTop: seg.y, textWidth: seg.width, textHeight: seg.height,
+        fontAscent: seg.fontAscent,
+        text: seg.text,
+        textSegments: [seg],
+        styles: baseStyles,
+    });
+    it("renders the pseudo's own color, not the host's color", () => {
+        const seg = {
+            text: "TAG",
+            x: 108, y: 56, width: 22, height: 11,
+            color: "rgb(255, 255, 255)",
+            fontSize: 11,
+            fontWeight: "400",
+            fontAscent: 9,
+        };
+        const out = renderSingleLineText({
+            el: makeEl(seg),
+            idPrefix: "t",
+            clipId: "ct0",
+            fillColor: "rgb(0,0,0)",
+        });
+        expect(out).toContain('fill="rgb(255, 255, 255)"');
+        expect(out).not.toContain('fill="rgb(0,0,0)"');
+    });
+    it("anchors the path at the pseudo's x/y, not at the SVG origin", () => {
+        const seg = {
+            text: "TAG",
+            x: 108, y: 56, width: 22, height: 11,
+            color: "rgb(255, 255, 255)",
+            fontSize: 11,
+            fontWeight: "400",
+            fontAscent: 9,
+        };
+        const out = renderSingleLineText({
+            el: makeEl(seg),
+            idPrefix: "t",
+            clipId: "ct0",
+            fillColor: "rgb(0,0,0)",
+        });
+        // baselineY = textTop + fontAscent = 56 + 9 = 65
+        expect(out).toMatch(/transform="translate\(108,\s*65\)"/);
+        expect(out).not.toContain('translate(0,0)');
+    });
+    it("uses the pseudo's fontSize when set, not the host's", () => {
+        const seg = {
+            text: "T",
+            x: 108, y: 56, width: 8, height: 11,
+            color: "rgb(255, 255, 255)",
+            fontSize: 11,
+            fontWeight: "400",
+            fontAscent: 9,
+        };
+        // Host fontSize is 16, pseudo is 11 — output should reflect 11px scale.
+        const elWithLargerHost = { ...makeEl(seg), styles: { ...baseStyles, fontSize: "16px" } };
+        const outAt11 = renderSingleLineText({
+            el: elWithLargerHost,
+            idPrefix: "t",
+            clipId: "ct0",
+            fillColor: "rgb(0,0,0)",
+        });
+        // The inner glyph scale = fontSize / unitsPerEm. For typical fonts (UPM
+        // ~2048), 11/2048 ≈ 0.00537; 16/2048 ≈ 0.00781. Spot-check the small one.
+        expect(outAt11).toMatch(/scale\(0\.00[0-9]+,/);
+        // Negative comparison: the host-fontSize scale shouldn't appear.
+        expect(outAt11).not.toContain('scale(0.00781,');
+    });
+    it("falls back to host fillColor when seg.color is absent", () => {
+        const seg = {
+            text: "TAG",
+            x: 108, y: 56, width: 22, height: 11,
+            fontAscent: 9,
+        };
+        const out = renderSingleLineText({
+            el: makeEl(seg),
+            idPrefix: "t",
+            clipId: "ct0",
+            fillColor: "rgb(34, 139, 34)",
+        });
+        expect(out).toContain('fill="rgb(34, 139, 34)"');
+    });
+});

package/dist/text-to-path.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Text-to-Path Converter
+ *
+ * Uses fontkit to convert text strings into SVG <path> outlines using
+ * the actual macOS system fonts. Glyphs are deduplicated using SVG
+ * <defs>/<use> — each unique glyph shape is defined once and referenced
+ * everywhere it appears.
+ */
+interface FontInstance {
+    layout(text: string, features?: string[]): {
+        glyphs: Array<{
+            id: number;
+            path: {
+                commands: Array<{
+                    command: string;
+                    args: number[];
+                }>;
+            };
+            advanceWidth: number;
+            codePoints?: number[];
+        }>;
+        positions: Array<{
+            xAdvance: number;
+            yAdvance: number;
+            xOffset: number;
+            yOffset: number;
+        }>;
+    };
+    unitsPerEm: number;
+    ascent: number;
+    descent: number;
+    underlinePosition: number;
+    underlineThickness: number;
+    /** Available OpenType feature tags (e.g. ['liga', 'kern', 'smcp']). Used by
+     *  the synthesized-small-caps path to detect when smcp is missing. */
+    availableFeatures?: string[];
+    "OS/2"?: {
+        yStrikeoutPosition?: number;
+        yStrikeoutSize?: number;
+    };
+}
+/**
+ * Open a webfont buffer with fontkit and register it under the given family
+ * name (case-insensitive). `weight` is a CSS numeric weight (100-900); 400
+ * when omitted. `style` is "normal" / "italic" / "oblique"; treated as italic
+ * for any non-normal value.
+ *
+ * `unicodeRange` mirrors the `@font-face { unicode-range: ... }` descriptor as
+ * a list of inclusive `[from, to]` codepoint intervals. Google-Fonts-style
+ * partitioning declares the same `(family, weight)` pair across multiple
+ * `@font-face` rules, each with a distinct `unicode-range` (Latin, Latin Ext,
+ * Cyrillic, Greek, Vietnamese, …). Without honoring the descriptor,
+ * `pickWebfontVariant` may return the Cyrillic-only partition for a Latin
+ * text run — the run lays out as .notdef tofu (DM-517).
+ *
+ * Buffers must be decompressed already — fontkit's `create()` reads TTF/OTF
+ * directly. WOFF2/WOFF bytes are decompressed in `loadWebfont()` (capture.ts)
+ * before they reach this function.
+ */
+export declare function registerWebfont(family: string, weight: number, style: string, buffer: Buffer, unicodeRange?: Array<[number, number]>): void;
+/** True iff `cp` falls in any of the inclusive `[from, to]` intervals. */
+export declare function unicodeRangeCovers(ranges: Array<[number, number]> | undefined, cp: number): boolean;
+/**
+ * DM-557: codepoint-aware variant pick for partitioned webfonts. Filters
+ * registered variants by whether their `unicode-range` covers `codepoint`
+ * (per CSS Fonts 4 §11.5 — a partition only declares it can shape glyphs
+ * within its declared range), then scores by (italic, weight) like
+ * `pickWebfontVariant`. Returns null when no registered variant covers the
+ * codepoint — the caller is expected to walk the system fallback chain in
+ * that case.
+ *
+ * Used by the run-splitter in `textToPathMarkup` to route per-codepoint
+ * within a Google-Fonts-style partitioned family (Geist@400 split across
+ * Latin/Latin-Ext/Cyrillic/etc.). Without this, the Latin-biased
+ * `pickWebfontVariant` is the single primary font for the whole text and
+ * codepoints outside its range fall straight to system fonts — losing the
+ * matching Cyrillic/Greek/Latin-Ext partition that's registered but
+ * unselected.
+ */
+export declare function pickWebfontVariantForCodepoint(family: string, weight: number, fontSize: number, slant: number, codepoint: number): FontInstance | null;
+/**
+ * Test-only: return metadata for the variant `pickWebfontVariant` would
+ * choose, without resolving variation axes / returning a FontInstance. Lets
+ * unit tests verify scoring (weight, italic, unicode-range) without needing
+ * to introspect glyph paths.
+ */
+export declare function __pickWebfontVariantMetaForTest(family: string, weight: number, italic: boolean): {
+    weight: number;
+    italic: boolean;
+    unicodeRange?: Array<[number, number]>;
+} | null;
+/** Test-only meta variant for `pickWebfontVariantForCodepoint` (DM-557). */
+export declare function __pickWebfontVariantMetaForCodepointForTest(family: string, weight: number, italic: boolean, codepoint: number): {
+    weight: number;
+    italic: boolean;
+    unicodeRange?: Array<[number, number]>;
+} | null;
+/** Drop all registered webfonts. Call at the start of a fresh capture run. */
+export declare function clearWebfonts(): void;
+export declare function registerLocalFontAlias(family: string, resolvedKey: string, weight?: number, italic?: boolean): void;
+/**
+ * Ordered list of fallback font keys to try when the primary font lacks a
+ * glyph for `codepoint`. Caller iterates the chain and picks the first font
+ * whose `glyphForCodePoint(cp).id !== 0`. Returns an empty array when no
+ * fallback is needed (caller should keep using primary).
+ *
+ * Order matches Chrome's macOS CoreText fallback per Unicode block, verified
+ * empirically by probing Chrome's painted width vs each candidate font's
+ * natural advance (DM-241 follow-up audit). Apple Symbols stays as the final
+ * safety net so we never end up with a .notdef tofu — better to draw a
+ * slightly-wrong glyph than nothing.
+ */
+/**
+ * Pick the PingFang regional variant key (or `hiragino-jp` for Japanese)
+ * that matches the element's computed `lang`. Returns null when the lang
+ * is empty / unknown — caller should fall through to the default `pingfang-sc`
+ * route in that case. DM-394.
+ *
+ * Matches BCP-47 language tags: the primary subtag wins, with a Han-script
+ * subtag (`Hans` / `Hant`) overriding region for the simplified-vs-traditional
+ * split. Examples:
+ *   "zh-TW"           → pingfang-tc
+ *   "zh-Hant"         → pingfang-tc
+ *   "zh-Hant-HK"      → pingfang-hk (region is more specific than script)
+ *   "zh-HK"           → pingfang-hk
+ *   "zh-MO"           → pingfang-mo
+ *   "zh-CN" / "zh-Hans" / "zh" / "" → null (caller picks pingfang-sc)
+ *   "ja" / "ja-JP"    → hiragino-jp (PingFang has no JP subfont on macOS)
+ */
+export declare function pingfangKeyForLang(lang: string | undefined): string | null;
+export declare function fallbackFontChain(codepoint: number, primaryKey?: string, lang?: string): string[];
+/** @deprecated Single-key wrapper for back-compat — prefer `fallbackFontChain`. */
+export declare function fallbackFontKey(codepoint: number): string | null;
+export declare function resolveFontKey(fontFamily: string): string;
+/**
+ * Get all glyph <defs> accumulated so far. Call this once when building the final SVG.
+ * Returns SVG markup to place inside a <defs> block.
+ */
+export declare function getGlyphDefs(): string;
+/** Clear the glyph registry (call between independent SVG generations). */
+export declare function clearGlyphDefs(): void;
+export interface TextPathResult {
+    /** SVG markup: <use> references for each glyph */
+    markup: string;
+    /** Actual rendered width in CSS pixels */
+    width: number;
+}
+/**
+ * Convert a text string to SVG markup using <use> references to glyph defs.
+ *
+ * Positioning modes (in order of preference):
+ *   1. xOffsets (per-char x in CSS pixels, relative to text origin) — used
+ *      when the capture layer measured each character's actual rect.left.
+ *      This eliminates per-character drift because glyph placement matches
+ *      exactly what the browser painted (including kerning, letter-spacing,
+ *      optical-size effects, etc.).
+ *   2. targetWidth — scales native fontkit advances uniformly so the total
+ *      width matches Chrome. Good for single-line text where per-char drift
+ *      is small. Kept as a fallback for inputs/textarea values (no per-char
+ *      rect data) and legacy callers.
+ *   3. Native fontkit advances — if neither is provided.
+ */
+export declare function textToPathMarkup(text: string, fontSize: number, fontFamily: string, fontWeight: string, targetWidth?: number, 
+/** CSS-pixel x offsets per visible char, relative to the text origin. */
+xOffsets?: number[], 
+/** CSS font-style ('italic' / 'oblique' / 'normal'). Drives SF Pro's slnt. */
+fontStyle?: string, 
+/**
+ * OpenType feature tags to enable for shaping (e.g. ['smcp'] for
+ * `font-variant: small-caps`). Threaded through to every fontkit
+ * `font.layout()` call so single-char and multi-char shaping both pick the
+ * substituted glyph. Empty / undefined means default shaping. (DM-294)
+ */
+features?: string[], 
+/** BCP-47 language tag from the element's computed `lang` attribute. Routes
+ *  Han fallbacks to the matching PingFang regional variant — `zh-TW` / `zh-Hant`
+ *  → PingFang TC, `zh-HK` → PingFang HK, `zh-MO` → PingFang MO, `ja` →
+ *  Hiragino Kaku, otherwise PingFang SC. (DM-394) */
+lang?: string): TextPathResult | null;
+/**
+ * Render text as SVG markup using path outlines with <defs>/<use> deduplication.
+ * Returns a <g> element containing <use> references, positioned at (x, y) top.
+ */
+export declare function renderTextAsPath(text: string, x: number, y: number, fontSize: number, fontFamily: string, fontWeight: string, fill: string, _clipPath?: string, 
+/** Chrome's measured text width — used to scale glyph positions for accurate layout */
+targetWidth?: number, 
+/** Per-char x offsets relative to this text's origin (CSS pixels). */
+xOffsets?: number[], 
+/** CSS font-style; 'italic' / 'oblique' activate SF Pro's slnt axis. */
+fontStyle?: string, 
+/**
+ * Captured `canvas.measureText().fontBoundingBoxAscent` (px) — distance
+ * from line-box top to baseline as Chrome will paint it. Overrides the
+ * fontkit-derived ascent below, which is HHEA-based and disagrees with
+ * Chrome on macOS for Helvetica/Arial/Times/Georgia/Menlo/Courier (Chrome
+ * uses winAscent there). Per-font metric-selection rules are fragile to
+ * derive but trivial to read from the browser. See SK-1267 / DM-237.
+ */
+ascentOverride?: number, 
+/**
+ * OpenType feature tags forwarded to fontkit (e.g. ['smcp'] when CSS
+ * `font-variant: small-caps` is in effect on this run). DM-294.
+ */
+features?: string[], 
+/** BCP-47 language tag for locale-aware Han fallback variant routing
+ *  (PingFang TC / HK / MO, or Hiragino Kaku for `ja`). DM-394. */
+lang?: string): string | null;
+/**
+ * Check if text-to-path conversion is available for a font family.
+ */
+export declare function isTextToPathAvailable(fontFamily: string): boolean;
+export interface DecorationMetrics {
+    /** Underline stroke center, px below baseline (positive = below). */
+    underlineOffsetY: number;
+    underlineThickness: number;
+    /** Line-through stroke center, px above baseline (positive = above). */
+    strikeoutOffsetY: number;
+    strikeoutThickness: number;
+    /** Overline stroke center, px above baseline (positive = above). */
+    overlineOffsetY: number;
+    overlineThickness: number;
+}
+/**
+ * Resolve text-decoration line placement from the font's actual `post`/`OS/2`
+ * tables (SK-1236). Chromium uses these same metric tables, so reading them
+ * directly tightens decoration alignment vs the previous fontSize-fraction
+ * approximation — most visible on SF Mono (underline ~0.75px higher than the
+ * generic 15%-of-fontSize estimate) and on large-fontSize text.
+ *
+ * Returns offsets in px from the baseline (sign convention noted on each
+ * field). Falls back to the legacy 15%/30%/95% approximations when the font
+ * fails to resolve.
+ */
+export declare function getDecorationMetrics(fontFamily: string, fontSize: number, fontWeight: string | number, fontStyle?: string, 
+/** CSS `text-decoration-thickness` — when set to a length value (e.g. "5px"),
+ *  overrides the auto thickness. Pass `undefined` or `auto` to use the auto
+ *  rule. DM-431. */
+thicknessOverride?: string, 
+/** CSS `text-underline-offset` — when set to a length value, adds this much
+ *  EXTRA distance below the baseline (on top of the auto offset). DM-431. */
+underlineOffsetCss?: string): DecorationMetrics;
+/**
+ * Compute X-range gaps where the underline rect [decorationCenterY - thickness/2,
+ * decorationCenterY + thickness/2] crosses glyph ink for `text` rendered in
+ * the given font. Returns gaps in the text's local coordinate system (X=0 at
+ * the run's anchor — caller adds segX to translate). Used to honor
+ * `text-decoration-skip-ink: auto` on solid / double underlines, matching
+ * Chromium's `decoration_line_painter.cc::ComputeUnderlineSkipFromIntercepts`.
+ *
+ * Algorithm: shape via fontkit, walk each glyph's path, flatten quadratic /
+ * cubic Beziers to short polylines, find segment-vs-horizontal-line
+ * intersections at the rect's top and bottom Y. Per glyph, the gap spans
+ * `[minIntersectX - pad, maxIntersectX + pad]` where pad = 0.5 * thickness
+ * (matches Chromium's `kIntersectionExtension`).
+ *
+ * `decorationCenterYRel` is in baseline-relative screen coords (positive =
+ * below baseline). Returns `[]` when font isn't resolvable, no glyphs cross
+ * the rect, or shaping throws. (DM-446.)
+ */
+export declare function computeSkipInkGaps(text: string, fontSize: number, fontFamily: string, fontWeight: string | number, fontStyle?: string, decorationCenterYRel?: number, decorationThickness?: number, features?: string[], 
+/** Chromium-measured run width — when set, intercepts are scaled to match
+ *  so gaps line up with the painted glyph positions even when fontkit's
+ *  layout disagrees with HarfBuzz at sub-px scale. */
+targetWidth?: number): Array<[number, number]>;
+export {};