domotion-svg 0.1.1

package/dist/capture.js

@@ -0,0 +1,786 @@
+/**
+ * Page Capture
+ *
+ * Uses Playwright to navigate to a URL, wait for it to settle,
+ * and capture the DOM as SVG via the dom-to-svg converter.
+ */
+import { spawnSync } from "node:child_process";
+import { chromium } from "@playwright/test";
+import { captureElementTree, elementTreeToSvg, embedRemoteImages } from "./dom-to-svg.js";
+import { resizeEmbeddedImages } from "./resize-embedded-images.js";
+import { rasterizeConicGradients } from "./conic-raster.js";
+import { registerLocalFontAlias, registerWebfont } from "./text-to-path.js";
+/**
+ * Launch Chromium via Playwright, auto-installing the browser binary on first
+ * use if it's missing. Use this instead of importing `chromium` from
+ * `@playwright/test` directly when you want a frictionless first-run
+ * experience for users of your tool.
+ *
+ * The install step is `npx playwright install chromium` and runs synchronously
+ * (stdout / stderr inherited) so the user sees its progress. Subsequent calls
+ * are a normal `chromium.launch()` with no overhead.
+ */
+export async function launchChromium(opts) {
+    try {
+        return await chromium.launch(opts);
+    }
+    catch (err) {
+        if (!isMissingBrowserError(err))
+            throw err;
+        console.error("[domotion] Chromium binary not found — installing via 'npx playwright install chromium'…");
+        const result = spawnSync("npx", ["playwright", "install", "chromium"], {
+            stdio: "inherit",
+            shell: process.platform === "win32",
+        });
+        if (result.status !== 0) {
+            throw new Error("[domotion] Failed to auto-install Playwright Chromium. " +
+                "Run 'npx playwright install chromium' manually and try again.");
+        }
+        return chromium.launch(opts);
+    }
+}
+function isMissingBrowserError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return /Executable doesn't exist|playwright install|browserType\.launch.*Failed to launch/i.test(msg);
+}
+export class DemoRecorder {
+    browser = null;
+    context = null;
+    page = null;
+    width;
+    height;
+    baseUrl;
+    selfContained;
+    embedRemoteImagesTimeoutMs;
+    embedRemoteImagesRetries;
+    embedRemoteImagesRetryBackoffMs;
+    embedRemoteImagesResize;
+    embedRemoteImagesHiDPIFactor;
+    constructor(baseUrl, opts) {
+        this.baseUrl = baseUrl;
+        this.width = opts.width;
+        this.height = opts.height;
+        this.selfContained = opts.selfContained ?? false;
+        this.embedRemoteImagesTimeoutMs = opts.embedRemoteImagesTimeoutMs;
+        this.embedRemoteImagesRetries = opts.embedRemoteImagesRetries;
+        this.embedRemoteImagesRetryBackoffMs = opts.embedRemoteImagesRetryBackoffMs;
+        this.embedRemoteImagesResize = opts.embedRemoteImagesResize ?? false;
+        this.embedRemoteImagesHiDPIFactor = opts.embedRemoteImagesHiDPIFactor;
+    }
+    async init(opts) {
+        this.browser = await launchChromium();
+        this.context = await this.browser.newContext({
+            viewport: { width: opts.width, height: opts.height },
+            isMobile: opts.mobile ?? false,
+            ...(opts.mobile ? { userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)" } : {}),
+            ...(opts.colorScheme != null ? { colorScheme: opts.colorScheme } : {}),
+        });
+        // Dev auth if requested
+        if (opts.devUser != null) {
+            const res = await fetch(`${this.baseUrl}/api/v1/auth/dev-login`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ username: opts.devUser }),
+                redirect: "manual",
+            });
+            if (res.ok) {
+                const json = await res.json();
+                const setCookie = res.headers.get("set-cookie") ?? "";
+                if (setCookie !== "") {
+                    const parts = setCookie.split(";")[0].split("=");
+                    await this.context.addCookies([{
+                            name: parts[0],
+                            value: parts.slice(1).join("="),
+                            domain: new URL(this.baseUrl).hostname,
+                            path: "/",
+                        }]);
+                }
+                // Set localStorage for client-side auth
+                await this.context.addInitScript((token) => {
+                    localStorage.setItem("sk_token", token);
+                    localStorage.setItem("sk_csrf", "");
+                }, json.data.token);
+            }
+        }
+        this.page = await this.context.newPage();
+        // DM-479: bump per-page Playwright operation timeouts from the 30 s
+        // default to 90 s. Heavy CSS / font / image loads on real-world sites
+        // and large captures push past 30 s without being genuinely stuck.
+        this.page.setDefaultTimeout(90_000);
+        this.page.setDefaultNavigationTimeout(90_000);
+    }
+    /** Navigate to a URL and capture the visible DOM as SVG. */
+    async captureUrl(path, waitMs = 800, idPrefix = "") {
+        if (this.page == null)
+            throw new Error("Call init() first");
+        await this.page.goto(`${this.baseUrl}${path}`, { waitUntil: "networkidle" });
+        await this.page.waitForTimeout(waitMs);
+        return this.captureCurrent(idPrefix);
+    }
+    /** Capture the current page state as SVG content. */
+    async captureCurrent(idPrefix = "") {
+        if (this.page == null)
+            throw new Error("Call init() first");
+        const tree = await captureElementTree(this.page, "body", {
+            x: 0, y: 0, width: this.width, height: this.height,
+        });
+        if (this.selfContained)
+            await embedRemoteImages(tree, {
+                timeoutMs: this.embedRemoteImagesTimeoutMs,
+                retries: this.embedRemoteImagesRetries,
+                retryBackoffMs: this.embedRemoteImagesRetryBackoffMs,
+            });
+        if (this.selfContained && this.embedRemoteImagesResize) {
+            await resizeEmbeddedImages(tree, { hiDPIFactor: this.embedRemoteImagesHiDPIFactor });
+        }
+        // DM-549: rasterize conic-gradient layers into PNG tiles. No-op when the
+        // tree contains no conic content; otherwise the renderer (DM-550) emits
+        // <pattern><image href="data:..."/></pattern> instead of dropping the layer.
+        await rasterizeConicGradients(tree, { hiDPIFactor: this.embedRemoteImagesHiDPIFactor });
+        return elementTreeToSvg(tree, this.width, this.height, idPrefix, true, this.embedRemoteImagesHiDPIFactor ?? 2);
+    }
+    /**
+     * Capture a full-page (scrollable) DOM as SVG.
+     * Returns SVG content that may be taller than the viewport.
+     */
+    async captureFullPage(idPrefix = "") {
+        if (this.page == null)
+            throw new Error("Call init() first");
+        const pageHeight = await this.page.evaluate(() => document.body.scrollHeight);
+        const tree = await captureElementTree(this.page, "body", {
+            x: 0, y: 0, width: this.width, height: pageHeight,
+        });
+        if (this.selfContained)
+            await embedRemoteImages(tree, {
+                timeoutMs: this.embedRemoteImagesTimeoutMs,
+                retries: this.embedRemoteImagesRetries,
+                retryBackoffMs: this.embedRemoteImagesRetryBackoffMs,
+            });
+        if (this.selfContained && this.embedRemoteImagesResize) {
+            await resizeEmbeddedImages(tree, { hiDPIFactor: this.embedRemoteImagesHiDPIFactor });
+        }
+        // DM-549: rasterize conic-gradient layers — see captureCurrent above.
+        await rasterizeConicGradients(tree, { hiDPIFactor: this.embedRemoteImagesHiDPIFactor });
+        const svgContent = elementTreeToSvg(tree, this.width, pageHeight, idPrefix, true, this.embedRemoteImagesHiDPIFactor ?? 2);
+        return { svgContent, pageHeight };
+    }
+    /** Get the underlying Playwright page for custom interactions. */
+    getPage() {
+        if (this.page == null)
+            throw new Error("Call init() first");
+        return this.page;
+    }
+    /** Get the bounding box of an element (for positioning overlays). */
+    async getBoundingBox(selector) {
+        if (this.page == null)
+            return null;
+        const el = this.page.locator(selector).first();
+        return el.boundingBox();
+    }
+    async close() {
+        await this.browser?.close();
+    }
+}
+/**
+ * Install a `requestfinished` listener that records every font-file URL the
+ * browser fetches into a Set. Returns the set + a detach handle. Pair with
+ * `discoverAndRegisterWebfonts(page, tracker.urls)` after the page loads.
+ *
+ * Needed because `performance.getEntriesByType("resource")` omits
+ * cross-origin fonts that don't send `Timing-Allow-Origin: *` (most CDNs
+ * don't), and most webfonts in the wild are served cross-origin.
+ *
+ * Attach BEFORE navigation so the listener catches the initial fetches.
+ */
+export function attachWebfontTracker(page) {
+    const urls = new Set();
+    const handler = (req) => {
+        const u = req.url();
+        if (/\.(woff2?|ttf|otf)(\?|$)/i.test(u))
+            urls.add(u);
+    };
+    page.on("requestfinished", handler);
+    return { urls, detach: () => page.off("requestfinished", handler) };
+}
+/**
+ * Discover all `@font-face` rules in the page's stylesheets, fetch each
+ * font file via the browser context's request API (so cookies / CORS / auth
+ * follow whatever the browser is using), and register the bytes with
+ * `text-to-path.ts` so the renderer can draw with the actual webfont glyphs
+ * instead of falling through to the system-font substitutes.
+ *
+ * Should be called AFTER `await page.evaluate(() => document.fonts.ready)`
+ * — otherwise late-loading fonts may not be in `document.styleSheets` yet.
+ *
+ * Cross-origin stylesheets whose `cssRules` throw a SecurityError are silently
+ * skipped (we can't enumerate their rules from JS). Same-origin sheets and
+ * inline `<style>` blocks always work.
+ *
+ * Caller is responsible for `clearWebfonts()` between captures if needed.
+ * No-op when the page declares no `@font-face` rules.
+ */
+export async function discoverAndRegisterWebfonts(page, observedFontUrls = []) {
+    const fromPage = await page.evaluate(() => {
+        // tsx/esbuild wraps named arrow consts in `__name(fn, "name")` for nicer
+        // stack traces. That helper isn't injected into page.evaluate's
+        // serialized scope, so we polyfill it here. Without this, our local
+        // helpers below throw "__name is not defined" at construction time.
+        if (typeof window.__name === "undefined") {
+            window.__name = function (fn) { return fn; };
+        }
+        // Parse a CSS `unicode-range` descriptor value into inclusive [from, to]
+        // intervals. Accepts the three forms in CSS Fonts 4 §4.5: single codepoint
+        // (`U+26`), interval (`U+0-7F`), and wildcard (`U+4??`). Returns `null`
+        // when the value is missing/unparseable so the caller treats the variant
+        // as covering the default range U+0..U+10FFFF.
+        const parseUnicodeRangeInline = function (value) {
+            const v = value.trim();
+            if (v === "")
+                return undefined;
+            const out = [];
+            for (const raw of v.split(",")) {
+                const tok = raw.trim().replace(/^U\+/i, "");
+                if (tok === "")
+                    continue;
+                if (tok.includes("?")) {
+                    const lo = parseInt(tok.replace(/\?/g, "0"), 16);
+                    const hi = parseInt(tok.replace(/\?/g, "F"), 16);
+                    if (Number.isFinite(lo) && Number.isFinite(hi))
+                        out.push([lo, hi]);
+                }
+                else if (tok.includes("-")) {
+                    const [a, b] = tok.split("-");
+                    const lo = parseInt(a, 16);
+                    const hi = parseInt(b, 16);
+                    if (Number.isFinite(lo) && Number.isFinite(hi))
+                        out.push([lo, hi]);
+                }
+                else {
+                    const cp = parseInt(tok, 16);
+                    if (Number.isFinite(cp))
+                        out.push([cp, cp]);
+                }
+            }
+            return out.length > 0 ? out : undefined;
+        };
+        const out = [];
+        const seenUrls = new Set();
+        // DM-545: stylesheets whose `cssRules` access threw (cross-origin without
+        // CORS). The Node side fetches their text and parses `@font-face` rules
+        // server-side. Without this, sites that serve their CSS from a CDN
+        // different from the page origin (Stripe → b.stripecdn.com, Apple → many
+        // sub-CDNs, …) miss every CSS-declared font-family alias and the
+        // resource-fallback registers under fontkit's internal `familyName` —
+        // which for license-protected fonts (Sohne) is often a copyright string.
+        const crossOriginSheetUrls = [];
+        // Width-probe helpers are defined inline below as needed. We avoid hoisting
+        // them into named arrow consts because tsx wraps such names in __name(...)
+        // calls (a runtime helper for stack traces) that isn't available inside
+        // page.evaluate's serialized context. (DM-445 — original symptom: the
+        // entire discovery throws "ReferenceError: __name is not defined".)
+        const probeWidthInline = function (familyExpr, weight, style, sample) {
+            const span = document.createElement("span");
+            span.style.cssText = "position:absolute;left:-9999px;top:-9999px;visibility:hidden;font-size:16px;line-height:1;white-space:pre";
+            span.style.fontFamily = familyExpr;
+            span.style.fontWeight = weight;
+            span.style.fontStyle = style;
+            span.textContent = sample;
+            document.body.appendChild(span);
+            const w = span.getBoundingClientRect().width;
+            document.body.removeChild(span);
+            return w;
+        };
+        // Strip trailing weight/style suffix from a local() candidate so the
+        // direct family-name probe hits the installed family. e.g. "Georgia
+        // Italic" → "Georgia". The font-style / font-weight descriptors of the
+        // alias rule already set the right variant, so the probe gets the same
+        // face Chrome's local() lookup would reach.
+        const stripVariantSuffixInline = function (n) {
+            return n.replace(/\s+(Bold Italic|Italic Bold|Bold|Italic|Oblique|Regular|Light|Medium|Semibold|Black)$/i, "").trim();
+        };
+        for (const sheet of Array.from(document.styleSheets)) {
+            let cssRules;
+            try {
+                cssRules = sheet.cssRules;
+            }
+            catch {
+                // Cross-origin sheet — record its URL so the Node side can fetch and
+                // parse it for @font-face rules. (DM-545)
+                if (sheet.href)
+                    crossOriginSheetUrls.push(sheet.href);
+                continue;
+            }
+            for (const rule of Array.from(cssRules)) {
+                if (rule.constructor.name !== "CSSFontFaceRule")
+                    continue;
+                const r = rule;
+                const family = r.style.getPropertyValue("font-family").trim().replace(/^["']|["']$/g, "");
+                const weight = r.style.getPropertyValue("font-weight") || "400";
+                const style = r.style.getPropertyValue("font-style") || "normal";
+                const src = r.style.getPropertyValue("src");
+                // DM-513: parse ALL `url(...) format(...)` pairs and return them in
+                // priority order (woff2 > woff > ttf/otf > unknown). Sites like
+                // Slashdot list legacy `eot`/`svg` (fontkit can't parse) alongside
+                // `woff` — without ordering, we'd grab the eot, fail to register,
+                // and lose every `::before` icon glyph. The Node side iterates the
+                // ranked list and uses the first URL whose response fontkit parses.
+                const srcEntries = [];
+                const urlRe = /url\(\s*["']?([^"')]+)["']?\s*\)(?:\s*format\(\s*["']?([^"')]+)["']?\s*\))?/g;
+                let urlMatch;
+                while ((urlMatch = urlRe.exec(src)) !== null) {
+                    srcEntries.push({ url: urlMatch[1], format: (urlMatch[2] ?? "").toLowerCase() });
+                }
+                const formatRank = (fmt, url) => {
+                    const lower = fmt.toLowerCase();
+                    if (/embedded-opentype|svg/.test(lower))
+                        return -1;
+                    if (lower.includes("woff2") || /\.woff2(\?|$)/i.test(url))
+                        return 4;
+                    if (lower === "woff" || /\.woff(\?|$)/i.test(url))
+                        return 3;
+                    if (/truetype|opentype/.test(lower) || /\.(ttf|otf)(\?|$)/i.test(url))
+                        return 2;
+                    if (/\.eot(\?|$)/i.test(url) || /\.svg(\?|$)/i.test(url))
+                        return -1;
+                    return 1;
+                };
+                const rankedUrls = srcEntries
+                    .map((e) => ({ url: e.url, rank: formatRank(e.format, e.url) }))
+                    .filter((e) => e.rank >= 0)
+                    .sort((a, b) => b.rank - a.rank)
+                    .map((e) => e.url);
+                const m = rankedUrls.length > 0 ? [src, rankedUrls[0]] : null;
+                if (m == null) {
+                    // No url() — but src may carry one or more local() entries. Capture
+                    // the local names so the Node side can register an alias to the
+                    // matching system font (DM-303). Without this, `font-family: Foo`
+                    // where Foo is declared via @font-face { src: local("Georgia") }
+                    // falls through the family chain to the next name and renders in
+                    // the wrong face.
+                    const locals = Array.from(src.matchAll(/local\(\s*["']?([^"')]+?)["']?\s*\)/g)).map((mm) => mm[1].trim()).filter((n) => n !== "");
+                    if (locals.length > 0) {
+                        // Probe to identify which local() candidate Chrome actually
+                        // resolved this alias to. A sample of common monospace + serif
+                        // glyphs ('mIw0') gives us enough horizontal divergence between
+                        // candidates to disambiguate even closely-related faces.
+                        const sample = "mIw0";
+                        // Chrome's local() lookup only matches a font's full name or
+                        // PostScript name (per CSS Fonts 4 §11.2), not its CSS family
+                        // name. So `local("Menlo")` (a family name) fails to match —
+                        // but the @font-face still resolves to the next candidate. To
+                        // figure out which one, render the alias face and compare its
+                        // width to each candidate via DIRECT family-name lookup (which
+                        // does match installed system fonts).
+                        const aliasW = probeWidthInline(`"${family}"`, weight, style, sample);
+                        let resolved = null;
+                        for (const cand of locals) {
+                            const candW = probeWidthInline(`"${stripVariantSuffixInline(cand)}"`, weight, style, sample);
+                            // Tolerate sub-px FP noise; match if widths agree within 0.05px.
+                            if (Math.abs(candW - aliasW) < 0.05) {
+                                resolved = cand;
+                                break;
+                            }
+                        }
+                        out.push({ kind: "local", family, localNames: locals, weight, style, resolvedLocalName: resolved });
+                    }
+                    continue;
+                }
+                const base = sheet.href ?? document.baseURI;
+                let absUrl;
+                try {
+                    absUrl = new URL(m[1], base).href;
+                }
+                catch {
+                    continue;
+                }
+                // Resolve the full ranked URL list to absolute URLs for the Node-side
+                // iterator (DM-513). The first entry IS `absUrl`; the rest are
+                // fallback candidates the Node side tries if fontkit rejects a
+                // higher-priority URL's bytes.
+                const absUrls = [];
+                for (const ru of rankedUrls) {
+                    try {
+                        absUrls.push(new URL(ru, base).href);
+                    }
+                    catch { /* skip */ }
+                }
+                for (const u of absUrls)
+                    seenUrls.add(u);
+                const unicodeRange = parseUnicodeRangeInline(r.style.getPropertyValue("unicode-range") || "");
+                out.push({ kind: "font-face", family, weight, style, url: absUrl, urls: absUrls, unicodeRange });
+            }
+        }
+        for (const entry of performance.getEntriesByType("resource")) {
+            if (!/\.(woff2?|ttf|otf)(\?|$)/i.test(entry.name))
+                continue;
+            if (seenUrls.has(entry.name))
+                continue;
+            seenUrls.add(entry.name);
+            out.push({ kind: "resource", url: entry.name });
+        }
+        return { entries: out, seenUrls: Array.from(seenUrls), crossOriginSheetUrls };
+    });
+    const discovered = fromPage.entries;
+    const seen = new Set(fromPage.seenUrls);
+    // DM-545: fetch each cross-origin stylesheet text and parse `@font-face`
+    // rules server-side. Cross-origin sheets throw on `cssRules` access from
+    // the page context, so without this the page-side walker misses every
+    // CDN-hosted CSS @font-face declaration. Sites affected (verified): Stripe
+    // (b.stripecdn.com), and likely most marketing sites whose CSS is served
+    // from a different host than the page. The resource-fallback path that
+    // ran in this scenario registers under fontkit's internal `familyName`,
+    // which for license-protected fonts (Sohne) is a copyright string —
+    // unmatchable against the CSS-declared `font-family: sohne-var` query.
+    for (const sheetUrl of fromPage.crossOriginSheetUrls ?? []) {
+        let cssText;
+        try {
+            const resp = await page.context().request.get(sheetUrl);
+            if (!resp.ok())
+                continue;
+            cssText = await resp.text();
+        }
+        catch {
+            continue;
+        }
+        for (const face of parseFontFaceRulesFromCssText(cssText, sheetUrl)) {
+            // De-dupe by all URLs in the ranked list — we may have already seen
+            // this src via the resource-fallback (whose entry registers under the
+            // wrong name); having BOTH a font-face entry (correct name) AND a
+            // resource entry (file's internal name) is fine — both will be tried.
+            for (const u of face.urls ?? [face.url])
+                seen.add(u);
+            discovered.push(face);
+        }
+    }
+    for (const url of observedFontUrls) {
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        discovered.push({ kind: "resource", url });
+    }
+    const report = [];
+    for (const item of discovered) {
+        if (item.kind === "local") {
+            // The page-side probe identified which local() candidate Chrome
+            // actually resolved the alias to (by comparing rendered widths). We
+            // route to that one specifically — NOT the first candidate we happen
+            // to recognize — because Chrome's local() lookup only matches a font's
+            // PostScript or full name, not its CSS family name (DM-445). Walking
+            // the candidate list with a family-name-based lookup table would
+            // mis-route e.g. `src: local("Menlo"), local("Monaco")` to Menlo when
+            // Chrome actually paints Monaco (Menlo's PostScript name is
+            // "Menlo-Regular", so the bare "Menlo" form doesn't match).
+            //
+            // If the probe didn't identify a match (none of the candidates
+            // measured the same width as the alias), we fall back to the legacy
+            // family-name lookup over the full candidate list — better than
+            // nothing, and preserves behavior for cases the probe can't resolve
+            // (e.g. an alias whose width happened to disagree with all candidates
+            // due to layout shaping that the simple sample didn't exercise).
+            const declaredWeight = parseWeightDescriptor(item.weight);
+            const declaredStyle = String(item.style ?? "normal").toLowerCase();
+            const declaredItalic = declaredStyle !== "" && declaredStyle !== "normal";
+            const resolved = item.resolvedLocalName;
+            const candidates = resolved != null ? [resolved] : item.localNames;
+            for (const localName of candidates) {
+                const key = systemFontKeyForLocalName(localName);
+                if (key != null) {
+                    registerLocalFontAlias(item.family, key, declaredWeight, declaredItalic);
+                    break;
+                }
+            }
+            continue;
+        }
+        // DM-513: try each URL in the ranked list (highest-priority format first)
+        // until one fetches AND fontkit can parse the bytes. Falls through eot/svg-
+        // first cascades like Slashdot's sdicon font where the woff is the 3rd or
+        // 4th `url()` in `src:`.
+        const candidates = item.kind === "font-face" && Array.isArray(item.urls) && item.urls.length > 0
+            ? item.urls
+            : [item.url];
+        let lastError;
+        let registered = false;
+        for (const candidateUrl of candidates) {
+            try {
+                const resp = await page.context().request.get(candidateUrl);
+                if (!resp.ok()) {
+                    lastError = `HTTP ${resp.status()}`;
+                    continue;
+                }
+                const fetched = Buffer.from(await resp.body());
+                const buf = await ensureNonWoff2(fetched);
+                if (item.kind === "font-face") {
+                    // Verify fontkit can actually parse the bytes before registering;
+                    // otherwise the registry holds an unusable entry and `pickWebfontVariant`
+                    // returns it without scoring against later candidates.
+                    const meta = await readFontMetadata(buf);
+                    if (meta == null) {
+                        lastError = "fontkit could not parse";
+                        continue;
+                    }
+                    const weightNum = parseWeightDescriptor(item.weight);
+                    registerWebfont(item.family, weightNum, item.style, buf, item.unicodeRange);
+                    report.push({ family: item.family, weight: weightNum, style: item.style, url: candidateUrl, source: "font-face", ok: true });
+                }
+                else {
+                    const meta = await readFontMetadata(buf);
+                    if (meta == null) {
+                        lastError = "fontkit could not parse";
+                        continue;
+                    }
+                    registerWebfont(meta.family, meta.weight, meta.italic ? "italic" : "normal", buf);
+                    report.push({ family: meta.family, weight: meta.weight, style: meta.italic ? "italic" : "normal", url: candidateUrl, source: "resource", ok: true });
+                }
+                registered = true;
+                break;
+            }
+            catch (e) {
+                lastError = e instanceof Error ? e.message : String(e);
+            }
+        }
+        if (!registered) {
+            report.push({ family: item.kind === "font-face" ? item.family : "", weight: item.kind === "font-face" ? parseWeightDescriptor(item.weight) : 400, style: item.kind === "font-face" ? item.style : "normal", url: item.url, source: item.kind, ok: false, error: lastError ?? "no candidates" });
+        }
+    }
+    return report;
+}
+/**
+ * Resolve a CSS `local("Name")` argument to a `resolveFontKey`-style key
+ * that matches our on-disk FONT_PATHS table. Returns null when the local
+ * name isn't a system font we know about (so the caller walks to the next
+ * `local()` in the @font-face's src list). DM-303.
+ *
+ * The names we recognize are limited to the families we actually ship paths
+ * for in `text-to-path.ts` — Georgia / Menlo / Monaco / Courier / Times /
+ * Helvetica / Arial. For unknown names we punt; the rest of the font-family
+ * chain (e.g. `, serif`) will catch the gap.
+ */
+function systemFontKeyForLocalName(localName) {
+    const n = localName.toLowerCase().replace(/^["']|["']$/g, "").trim();
+    // Strip a trailing weight/style suffix so "Georgia Bold" / "Georgia Italic"
+    // / "Georgia Bold Italic" all collapse to "georgia" — `getFontInstance`
+    // dispatches to the right sibling file based on the requested CSS weight
+    // and style, so the alias just needs to point at the family.
+    const base = n.replace(/\s+(bold|italic|oblique|regular|light|medium|semibold|black)\b/g, "").trim();
+    if (base === "georgia")
+        return "georgia";
+    if (base === "menlo")
+        return "menlo";
+    if (base === "monaco")
+        return "monaco";
+    if (base === "courier" || base === "courier new")
+        return "courier";
+    if (base === "times new roman")
+        return "times-new-roman";
+    if (base === "times")
+        return "times";
+    if (base === "helvetica" || base === "helvetica neue")
+        return "helvetica";
+    if (base === "arial")
+        return "arial";
+    if (base === "sf pro" || base === "sf pro text" || base === "sf pro display")
+        return "sf-pro";
+    if (base === "sf mono" || base === "sfmono-regular")
+        return "sf-mono";
+    return null;
+}
+async function readFontMetadata(buf) {
+    const fontkit = await import("fontkit");
+    try {
+        const f = fontkit.create(buf);
+        const family = f.familyName ?? "";
+        if (family === "")
+            return null;
+        const weight = (f["OS/2"]?.usWeightClass) ?? 400;
+        const italic = !!(f["OS/2"]?.fsSelection?.italic);
+        return { family, weight, italic };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * If `buf` is WOFF2 (magic `wOF2`), decompress it to plain TTF bytes via
+ * `wawoff2`. Otherwise return the buffer untouched.
+ *
+ * Why we need this: fontkit *parses* WOFF2 fine, but `getVariation()` on a
+ * WOFF2 font returns an instance whose internal stream can't read the
+ * parent's tables (`unitsPerEm` / `layout()` throw). Most webfonts in the
+ * wild are WOFF2, so without this step variable-axis support (DM-228 / 229)
+ * would silently degrade to the registered base instance for every weight.
+ *
+ * Decompressing to TTF before fontkit.create produces a font whose variation
+ * results retain access to all tables — same as a TTF loaded from disk.
+ */
+async function ensureNonWoff2(buf) {
+    if (buf.length < 4)
+        return buf;
+    const isWoff2 = buf[0] === 0x77 && buf[1] === 0x4F && buf[2] === 0x46 && buf[3] === 0x32;
+    if (!isWoff2)
+        return buf;
+    try {
+        // wawoff2 ships no .d.ts; the runtime export is `{ compress, decompress }`.
+        const wawoff = await import("wawoff2");
+        const ttf = await wawoff.decompress(new Uint8Array(buf));
+        return Buffer.from(ttf);
+    }
+    catch {
+        return buf; // fall through: register the WOFF2 anyway, variations just won't work
+    }
+}
+/**
+ * DM-545: parse `@font-face` rules out of a raw CSS text fetched server-side.
+ * Used for cross-origin stylesheets that the page-side `cssRules` walker can't
+ * read. Tolerant scanner — handles top-level `@font-face` and rules nested
+ * inside any number of `@media` / `@supports` / `@layer` / `@container`
+ * blocks (recurses through balanced braces). Returns the same FaceRule shape
+ * the page-side walker emits so the downstream registration loop is uniform.
+ *
+ * Not a full CSS parser — comment-stripping handles `/* … *​/`, but exotic
+ * inputs (custom properties holding @font-face strings, CSSOM-injected rules
+ * that never serialised back to text) aren't covered. Adequate for the
+ * mainstream marketing-site case that motivated the change.
+ */
+export function parseFontFaceRulesFromCssText(cssText, baseUrl) {
+    const stripped = cssText.replace(/\/\*[\s\S]*?\*\//g, "");
+    const out = [];
+    const re = /@font-face\s*\{/gi;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        const start = m.index + m[0].length;
+        let depth = 1;
+        let i = start;
+        while (i < stripped.length && depth > 0) {
+            const c = stripped[i];
+            if (c === "{")
+                depth++;
+            else if (c === "}")
+                depth--;
+            i++;
+        }
+        if (depth !== 0)
+            break;
+        const body = stripped.substring(start, i - 1);
+        const rule = parseFontFaceBody(body, baseUrl);
+        if (rule != null)
+            out.push(rule);
+    }
+    return out;
+}
+function parseFontFaceBody(body, baseUrl) {
+    const familyMatch = /font-family\s*:\s*([^;}]+)/i.exec(body);
+    if (familyMatch == null)
+        return null;
+    const family = familyMatch[1].trim().replace(/^["']|["']$/g, "").trim();
+    if (family === "")
+        return null;
+    const weight = (/font-weight\s*:\s*([^;}]+)/i.exec(body)?.[1].trim()) ?? "400";
+    const style = (/font-style\s*:\s*([^;}]+)/i.exec(body)?.[1].trim()) ?? "normal";
+    const urMatch = /unicode-range\s*:\s*([^;}]+)/i.exec(body);
+    const unicodeRange = urMatch != null ? parseUnicodeRangeDescriptor(urMatch[1]) : undefined;
+    const srcMatch = /src\s*:\s*([\s\S]+?)(?:;|$)/i.exec(body);
+    if (srcMatch == null)
+        return null;
+    const src = srcMatch[1];
+    const srcEntries = [];
+    const urlRe = /url\(\s*["']?([^"')]+)["']?\s*\)(?:\s*format\(\s*["']?([^"')]+)["']?\s*\))?/g;
+    let um;
+    while ((um = urlRe.exec(src)) !== null) {
+        srcEntries.push({ url: um[1], format: (um[2] ?? "").toLowerCase() });
+    }
+    if (srcEntries.length === 0)
+        return null;
+    // Same ranking as the page-side walker (woff2 > woff > ttf/otf, skip
+    // eot/svg). Keeping the two ranks identical means the Node-side iterator
+    // tries URLs in the same order whether they came from the page-side or
+    // server-side path.
+    const formatRank = (fmt, url) => {
+        const lower = fmt.toLowerCase();
+        if (/embedded-opentype|svg/.test(lower))
+            return -1;
+        if (lower.includes("woff2") || /\.woff2(\?|$)/i.test(url))
+            return 4;
+        if (lower === "woff" || /\.woff(\?|$)/i.test(url))
+            return 3;
+        if (/truetype|opentype/.test(lower) || /\.(ttf|otf)(\?|$)/i.test(url))
+            return 2;
+        if (/\.eot(\?|$)/i.test(url) || /\.svg(\?|$)/i.test(url))
+            return -1;
+        return 1;
+    };
+    const ranked = srcEntries
+        .map((e) => ({ url: e.url, rank: formatRank(e.format, e.url) }))
+        .filter((e) => e.rank >= 0)
+        .sort((a, b) => b.rank - a.rank)
+        .map((e) => e.url);
+    if (ranked.length === 0)
+        return null;
+    const absUrls = [];
+    for (const u of ranked) {
+        try {
+            absUrls.push(new URL(u, baseUrl).href);
+        }
+        catch { /* skip */ }
+    }
+    if (absUrls.length === 0)
+        return null;
+    return { kind: "font-face", family, weight, style, url: absUrls[0], urls: absUrls, unicodeRange };
+}
+/**
+ * Parse a CSS `unicode-range` descriptor value (CSS Fonts 4 §4.5) into a list
+ * of inclusive `[from, to]` codepoint intervals. Accepts the three forms:
+ * single (`U+26`), interval (`U+0-7F`), and wildcard (`U+4??`). Multiple
+ * ranges are comma-separated. Returns `undefined` for empty / unparseable
+ * input — callers treat that as the CSS default coverage (U+0..U+10FFFF).
+ *
+ * This is the Node-side twin of the in-page parser inlined inside
+ * `discoverAndRegisterWebfonts`'s `page.evaluate` body. The page-side copy
+ * can't import from here (it runs in the browser context), but the logic must
+ * stay aligned — covered by tests on this exported version.
+ */
+export function parseUnicodeRangeDescriptor(value) {
+    const v = value.trim();
+    if (v === "")
+        return undefined;
+    const out = [];
+    for (const raw of v.split(",")) {
+        const tok = raw.trim().replace(/^U\+/i, "");
+        if (tok === "")
+            continue;
+        if (tok.includes("?")) {
+            const lo = parseInt(tok.replace(/\?/g, "0"), 16);
+            const hi = parseInt(tok.replace(/\?/g, "F"), 16);
+            if (Number.isFinite(lo) && Number.isFinite(hi))
+                out.push([lo, hi]);
+        }
+        else if (tok.includes("-")) {
+            const [a, b] = tok.split("-");
+            const lo = parseInt(a, 16);
+            const hi = parseInt(b, 16);
+            if (Number.isFinite(lo) && Number.isFinite(hi))
+                out.push([lo, hi]);
+        }
+        else {
+            const cp = parseInt(tok, 16);
+            if (Number.isFinite(cp))
+                out.push([cp, cp]);
+        }
+    }
+    return out.length > 0 ? out : undefined;
+}
+function parseWeightDescriptor(value) {
+    // CSS keywords and numeric, including weight ranges like "100 900".
+    const v = value.trim().toLowerCase();
+    if (v === "normal")
+        return 400;
+    if (v === "bold")
+        return 700;
+    // Range form: take the first number.
+    const m = /-?\d+/.exec(v);
+    if (m != null) {
+        const n = parseInt(m[0], 10);
+        if (Number.isFinite(n) && n >= 1 && n <= 1000)
+            return n;
+    }
+    return 400;
+}