@hyperframes/core 0.8.183 → 0.8.184

package/dist/compiler/compositionScoping.d.ts

@@ -1,7 +1,11 @@
-export declare function scopeCssToComposition(css: string, compositionId: string, scopeSelectorOverride?: string, authoredRootId?: string | null, options?: {
+type ScopeOptions = {
     compoundAuthoredRoot?: boolean;
     scopeRootSelectors?: boolean;
-}): string;
+};
+export declare function scopeCssToComposition(css: string, compositionId: string, scopeSelectorOverride?: string, authoredRootId?: string | null, options?: ScopeOptions): string;
+/** `scopeCssToComposition` for sheets mounted many times: each sheet is scoped once around a
+ * placeholder scope, which each mount's own scope then replaces. */
+export declare function createCompositionCssScoper(): typeof scopeCssToComposition;
 /** Drops repeats of an identical `@font-face` across the given style texts, keeping the last copy:
  * the last matching rule is the one the browser uses, so a rule in between never gains precedence. */
 export declare const dedupeFontFaceRules: (styleTexts: string[]) => string[];
@@ -30,3 +34,4 @@ export declare function wrapInlineScriptWithErrorBoundary(source: string, errorL
  * table goes through `jsonScriptLiteral` — see there for why.
  */
 export declare function buildVariablesByCompScript(variablesByComp: Record<string, Record<string, unknown>>): string | null;
+export {};

package/dist/compiler/compositionScoping.js

@@ -132,22 +132,86 @@ export function scopeCssToComposition(css, compositionId, scopeSelectorOverride,
         return css;
     const scope = scopeSelectorOverride ||
         `[data-composition-id="${escapeCssAttributeValue(trimmedCompositionId)}"]`;
-    let root;
+    const root = parseCss(css);
+    return root ? scopeParsedCss(root, scope, trimmedCompositionId, authoredRootId, options) : "";
+}
+function parseCss(css) {
     try {
-        root = postcss.parse(css);
+        return postcss.parse(css);
     }
     catch {
-        return "";
+        return null;
     }
+}
+function forEachScopedRule(root, visit) {
     root.walkRules((rule) => {
         if (isInsideGlobalAtRule(rule))
             return;
         if (isNestedInsideAnotherRule(rule))
             return;
-        rule.selectors = rule.selectors.map((selector) => scopeSelector(selector, scope, trimmedCompositionId, authoredRootId, options?.compoundAuthoredRoot, options?.scopeRootSelectors));
+        visit(rule);
+    });
+}
+function scopeParsedCss(root, scope, compositionId, authoredRootId, options) {
+    forEachScopedRule(root, (rule) => {
+        rule.selectors = rule.selectors.map((selector) => scopeSelector(selector, scope, compositionId, authoredRootId, options?.compoundAuthoredRoot, options?.scopeRootSelectors));
     });
     return root.toResult({ map: false }).css;
 }
+// Shaped like every scope it stands in for, so each selector test treats the two alike; its only `[` is
+// its first character, so no occurrence of it overlaps another or the text around it.
+const PLACEHOLDER_ID = "hf-scope-placeholder";
+const PLACEHOLDER_SCOPE = `[data-composition-id="${PLACEHOLDER_ID}"]`;
+// No quote, bracket, backslash, space or `$` (a String.replace pattern): such a scope lands verbatim.
+const PLAIN_ID = /^[\w.:-]+$/;
+const PLAIN_SCOPE = /^\[data-composition-id="([\w.:-]+)"\]$/;
+/** `scopeCssToComposition` for sheets mounted many times: each sheet is scoped once around a
+ * placeholder scope, which each mount's own scope then replaces. */
+export function createCompositionCssScoper() {
+    const templates = new Map();
+    return (css, compositionId, scopeSelectorOverride, authoredRootId, options) => {
+        const trimmedId = compositionId.trim();
+        const scope = scopeSelectorOverride ?? "";
+        const scopeId = PLAIN_SCOPE.exec(scope)?.[1];
+        if (!scopeId ||
+            scopeId === trimmedId ||
+            !PLAIN_ID.test(trimmedId) ||
+            trimmedId === PLACEHOLDER_ID)
+            return scopeCssToComposition(css, compositionId, scopeSelectorOverride, authoredRootId, options);
+        const key = JSON.stringify([
+            trimmedId,
+            authoredRootId ?? null,
+            Boolean(options?.compoundAuthoredRoot),
+            Boolean(options?.scopeRootSelectors),
+            css,
+        ]);
+        let template = templates.get(key);
+        if (template === undefined) {
+            template = scopeTemplate(css, trimmedId, authoredRootId, options);
+            templates.set(key, template);
+        }
+        return template === null
+            ? scopeCssToComposition(css, compositionId, scopeSelectorOverride, authoredRootId, options)
+            : template.split(PLACEHOLDER_SCOPE).join(scope);
+    };
+}
+/** Null when the placeholder is already in the sheet, or a selector keeps its raw text (it holds a comment). */
+function scopeTemplate(css, compositionId, authoredRootId, options) {
+    if (css.includes(PLACEHOLDER_SCOPE))
+        return null;
+    if (!css)
+        return css;
+    const root = parseCss(css);
+    if (!root)
+        return "";
+    let rawSelector = false;
+    forEachScopedRule(root, (rule) => {
+        rawSelector ||= Boolean(rule.raws.selector);
+    });
+    return rawSelector
+        ? null
+        : scopeParsedCss(root, PLACEHOLDER_SCOPE, compositionId, authoredRootId, options);
+}
 function isFontFaceAtRule(node) {
     return node.type === "atrule" && node.name.toLowerCase() === "font-face";
 }

package/dist/compiler/htmlBundler.d.ts

@@ -55,6 +55,7 @@ export interface BundleOptions {
     sceneParts?: boolean;
     /** Warn when the compiled HTML breaks the HyperFrames contract (default true). */
     staticGuard?: boolean;
+    /** Called once per build for each project file the build reads or looks for. */
     onRead?: (filePath: string) => void;
 }
 export declare function bundleToSingleHtml(projectDir: string, options?: BundleOptions): Promise<string>;

package/dist/compiler/htmlBundler.js

@@ -312,33 +312,49 @@ function warnAssetTooLargeToInline(assetPath, byteLength) {
     const mb = (byteLength / (1024 * 1024)).toFixed(1);
     console.warn(`[HyperFrames] Not inlining "${assetPath}" (${mb} MB exceeds the ${MAX_INLINE_ASSET_BYTES / (1024 * 1024)} MB inline limit). The bundle may not be self-contained.`);
 }
-function maybeInlineRelativeAssetUrl(urlValue, projectDir, inlineAssets) {
-    if (!inlineAssets)
-        return null;
-    if (!urlValue || !isRelativeUrl(urlValue))
-        return null;
-    const { basePath, suffix } = splitUrlSuffix(urlValue.trim());
-    if (!basePath)
-        return null;
-    const filePath = resolveWithinProject(projectDir, decodeWellFormedEscapes(basePath));
-    if (!filePath)
-        return null;
-    const ext = filePath.toLowerCase().match(/\.[^.]+$/)?.[0] ?? "";
-    const mimeType = INLINE_MIME[ext];
-    if (!mimeType)
-        return null;
-    // Size-check before reading: an oversized asset must not be pulled into memory
-    // just to be discarded.
-    const byteLength = safeStatSize(filePath);
-    if (byteLength !== null && byteLength > MAX_INLINE_ASSET_BYTES) {
-        warnAssetTooLargeToInline(basePath, byteLength);
-        return null;
-    }
-    const content = safeReadFileBuffer(filePath);
-    if (content == null)
-        return null;
-    const dataUrl = `data:${mimeType};base64,${content.toString("base64")}`;
-    return appendSuffixToUrl(dataUrl, suffix);
+/** Inlines relative asset URLs as data: URLs, reading each project file once per build. */
+function createAssetInliner(resolveProjectPath, inlineAssets) {
+    const assets = new Map();
+    const readAsset = (filePath, mimeType) => {
+        // Size-check before reading: an oversized asset must not be pulled into memory
+        // just to be discarded.
+        const byteLength = safeStatSize(filePath);
+        if (byteLength !== null && byteLength > MAX_INLINE_ASSET_BYTES)
+            return { tooLarge: byteLength };
+        const content = safeReadFileBuffer(filePath);
+        return {
+            dataUrl: content === null ? null : `data:${mimeType};base64,${content.toString("base64")}`,
+        };
+    };
+    return (urlValue) => {
+        if (!inlineAssets)
+            return null;
+        if (!urlValue || !isRelativeUrl(urlValue))
+            return null;
+        const { basePath, suffix } = splitUrlSuffix(urlValue.trim());
+        if (!basePath)
+            return null;
+        const filePath = resolveProjectPath(decodeWellFormedEscapes(basePath));
+        if (!filePath)
+            return null;
+        const ext = filePath.toLowerCase().match(/\.[^.]+$/)?.[0] ?? "";
+        const mimeType = INLINE_MIME[ext];
+        if (!mimeType)
+            return null;
+        let asset = assets.get(filePath);
+        if (asset === undefined) {
+            asset = readAsset(filePath, mimeType);
+            assets.set(filePath, asset);
+        }
+        else if ("dataUrl" in asset) {
+            noteRead(filePath);
+        }
+        if ("tooLarge" in asset) {
+            warnAssetTooLargeToInline(basePath, asset.tooLarge);
+            return null;
+        }
+        return asset.dataUrl === null ? null : appendSuffixToUrl(asset.dataUrl, suffix);
+    };
 }
 function isExternalSvgFragmentUse(el, attr, urlValue) {
     if (el.tagName.toLowerCase() !== "use")
@@ -360,7 +376,7 @@ function warnColorGradingLutNotInlined(lutSrc) {
     console.warn(`[HyperFrames] Could not inline color grading LUT "${trimmed}". The rendered bundle may not be self-contained.`);
 }
 // fallow-ignore-next-line complexity
-function rewriteColorGradingLutWithInlinedAssets(value, projectDir) {
+function rewriteColorGradingLutWithInlinedAssets(value, inlineAsset) {
     if (!value.trim().startsWith("{"))
         return value;
     let parsed;
@@ -376,7 +392,7 @@ function rewriteColorGradingLutWithInlinedAssets(value, projectDir) {
     if (typeof lut === "string") {
         // Gated by inlineAssets and inlineColorGradingLuts at the call site above;
         // this call only runs once both have already passed.
-        const inlined = maybeInlineRelativeAssetUrl(lut, projectDir, true);
+        const inlined = inlineAsset(lut);
         if (!inlined) {
             warnColorGradingLutNotInlined(lut);
             return value;
@@ -389,7 +405,7 @@ function rewriteColorGradingLutWithInlinedAssets(value, projectDir) {
     const lutSrc = Reflect.get(lut, "src");
     if (typeof lutSrc !== "string")
         return value;
-    const inlined = maybeInlineRelativeAssetUrl(lutSrc, projectDir, true);
+    const inlined = inlineAsset(lutSrc);
     if (!inlined) {
         warnColorGradingLutNotInlined(lutSrc);
         return value;
@@ -397,7 +413,7 @@ function rewriteColorGradingLutWithInlinedAssets(value, projectDir) {
     Reflect.set(lut, "src", inlined);
     return JSON.stringify(parsed);
 }
-function rewriteSrcsetWithInlinedAssets(srcsetValue, projectDir, inlineAssets) {
+function rewriteSrcsetWithInlinedAssets(srcsetValue, inlineAsset) {
     if (!srcsetValue)
         return srcsetValue;
     return srcsetValue
@@ -409,18 +425,18 @@ function rewriteSrcsetWithInlinedAssets(srcsetValue, projectDir, inlineAssets) {
         const parts = candidate.split(/\s+/);
         if (parts.length === 0)
             return candidate;
-        const maybeInlined = maybeInlineRelativeAssetUrl(parts[0] ?? "", projectDir, inlineAssets);
+        const maybeInlined = inlineAsset(parts[0] ?? "");
         if (maybeInlined)
             parts[0] = maybeInlined;
         return parts.join(" ");
     })
         .join(", ");
 }
-function rewriteCssUrlsWithInlinedAssets(cssText, projectDir, inlineAssets) {
+function rewriteCssUrlsWithInlinedAssets(cssText, inlineAsset) {
     if (!cssText)
         return cssText;
     return cssText.replace(/\burl\(\s*(["']?)([^)"']+)\1\s*\)/g, (_full, quote, rawUrl) => {
-        const maybeInlined = maybeInlineRelativeAssetUrl((rawUrl || "").trim(), projectDir, inlineAssets);
+        const maybeInlined = inlineAsset((rawUrl || "").trim());
         if (!maybeInlined)
             return _full;
         return `url(${quote || ""}${maybeInlined}${quote || ""})`;
@@ -830,7 +846,17 @@ function hoistCompositionScripts(container, opts) {
 }
 export function bundleToSingleHtml(projectDir, options) {
     const bundle = () => bundleProject(projectDir, options);
-    return options?.onRead ? bundleReads.run(options.onRead, bundle) : bundle();
+    const onRead = options?.onRead;
+    if (!onRead)
+        return bundle();
+    const noted = new Set();
+    const noteOnce = (filePath) => {
+        if (noted.has(filePath))
+            return;
+        noted.add(filePath);
+        onRead(filePath);
+    };
+    return bundleReads.run(noteOnce, bundle);
 }
 // A <template> scene has no root or GSAP of its own: bundle it inside the index that mounts it, as render does.
 function readMountedSceneShell(projectDir, entryFile, entryHtml) {
@@ -851,9 +877,29 @@ async function bundleProject(projectDir, options) {
     const entryHtml = readFileSync(indexPath, "utf-8");
     const mountedShell = readMountedSceneShell(projectDir, entryFile, entryHtml);
     const sourceDir = mountedShell ? projectDir : dirname(indexPath);
+    // Every mount of a sub-composition asks again for each of its url()s; isSafePath realpaths the whole chain.
+    const safePaths = new Map();
+    const isSafeProjectPath = (resolved) => {
+        let safe = safePaths.get(resolved);
+        if (safe === undefined) {
+            safe = isSafePath(projectDir, resolved);
+            safePaths.set(resolved, safe);
+        }
+        return safe;
+    };
+    const entryPaths = new Map();
     const resolveEntryPath = (relativePath) => {
-        const resolved = resolve(sourceDir, relativePath);
-        return isSafePath(projectDir, resolved) ? resolved : null;
+        let entry = entryPaths.get(relativePath);
+        if (entry === undefined) {
+            const resolved = resolve(sourceDir, relativePath);
+            entry = isSafeProjectPath(resolved) ? resolved : null;
+            entryPaths.set(relativePath, entry);
+        }
+        return entry;
+    };
+    const resolveProjectPath = (relativePath) => {
+        const resolved = resolve(projectDir, relativePath);
+        return isSafeProjectPath(resolved) ? resolved : null;
     };
     const resolveEntryUrl = (url) => resolveEntryPath(decodedUrlPath(url));
     const readSource = options?.stampHfIds ? ensureHfIds : (html) => html;
@@ -908,13 +954,24 @@ async function bundleProject(projectDir, options) {
     const trackedCompositionHosts = getBundledTrackedCompositionHosts(document);
     const hostIdentityByElement = assignBundledRuntimeCompositionIds(trackedCompositionHosts);
     const subCompositionHosts = trackedCompositionHosts.filter((host) => host.hasAttribute("data-composition-src"));
+    const sceneSources = new Map();
     const subCompResult = inlineSubCompositions(document, subCompositionHosts, {
         resolveHtml: (srcPath) => {
             if (!isRelativeUrl(srcPath))
                 return null;
             const compPath = resolveEntryPath(srcPath);
-            const html = compPath ? safeReadFile(compPath) : null;
-            return html === null ? null : readSource(html);
+            if (!compPath)
+                return null;
+            let source = sceneSources.get(compPath);
+            if (source === undefined) {
+                const html = safeReadFile(compPath);
+                source = html === null ? null : readSource(html);
+                sceneSources.set(compPath, source);
+            }
+            else {
+                noteRead(compPath);
+            }
+            return source;
         },
         parseHtml: parseHTMLContent,
         hostIdentityMap: hostIdentityByElement,
@@ -1150,6 +1207,7 @@ async function bundleProject(projectDir, options) {
     injectTextRenderingRule(document);
     // Inline textual assets
     const inlineAssets = options?.inlineAssets !== false;
+    const inlineAsset = createAssetInliner(resolveProjectPath, inlineAssets);
     for (const el of [...document.querySelectorAll("[src], [href], [poster], [xlink\\:href]")]) {
         for (const attr of ["src", "href", "poster", "xlink:href"]) {
             const value = el.getAttribute(attr);
@@ -1161,7 +1219,7 @@ async function bundleProject(projectDir, options) {
             // Keep the project-relative URL; render/check servers already expose it.
             if (isExternalSvgFragmentUse(el, attr, value))
                 continue;
-            const inlined = maybeInlineRelativeAssetUrl(value, projectDir, inlineAssets);
+            const inlined = inlineAsset(value);
             if (inlined)
                 el.setAttribute(attr, inlined);
         }
@@ -1169,7 +1227,7 @@ async function bundleProject(projectDir, options) {
     for (const el of [...document.querySelectorAll("[srcset]")]) {
         const srcset = el.getAttribute("srcset");
         if (srcset)
-            el.setAttribute("srcset", rewriteSrcsetWithInlinedAssets(srcset, projectDir, inlineAssets));
+            el.setAttribute("srcset", rewriteSrcsetWithInlinedAssets(srcset, inlineAsset));
     }
     // Before inlining, so postcss reads paths not font bytes.
     const liveStyles = [...document.querySelectorAll("style")].filter(isAlwaysAppliedStyle);
@@ -1187,16 +1245,16 @@ async function bundleProject(projectDir, options) {
         document.head.prepend(holder);
     }
     for (const styleEl of document.querySelectorAll("style")) {
-        styleEl.textContent = rewriteCssUrlsWithInlinedAssets(styleEl.textContent || "", projectDir, inlineAssets);
+        styleEl.textContent = rewriteCssUrlsWithInlinedAssets(styleEl.textContent || "", inlineAsset);
     }
     for (const el of [...document.querySelectorAll("[style]")]) {
-        el.setAttribute("style", rewriteCssUrlsWithInlinedAssets(el.getAttribute("style") || "", projectDir, inlineAssets));
+        el.setAttribute("style", rewriteCssUrlsWithInlinedAssets(el.getAttribute("style") || "", inlineAsset));
     }
     if (inlineAssets && options?.inlineColorGradingLuts !== false) {
         for (const el of [...document.querySelectorAll(`[${HF_COLOR_GRADING_ATTR}]`)]) {
             const value = el.getAttribute(HF_COLOR_GRADING_ATTR);
             if (value) {
-                el.setAttribute(HF_COLOR_GRADING_ATTR, rewriteColorGradingLutWithInlinedAssets(value, projectDir));
+                el.setAttribute(HF_COLOR_GRADING_ATTR, rewriteColorGradingLutWithInlinedAssets(value, inlineAsset));
             }
         }
     }
@@ -1277,7 +1335,23 @@ function authoredDefinesPredicate(document) {
     const authoredCss = [...document.querySelectorAll("style:not([data-hf-composition-variables])")]
         .map((s) => s.textContent || "")
         .join("\n");
-    return (id) => new RegExp(`${cssVariableName(id)}\\s*:`).test(authoredCss);
+    const defined = namesBeforeAColon(authoredCss);
+    return (id) => defined.has(cssVariableName(id));
+}
+/** Every `--name` written right before a `:`, including the tail of a longer word (`.a--b:hover`), in one pass. */
+function namesBeforeAColon(css) {
+    const names = new Set();
+    const word = /[\w-]+/g;
+    const colonNext = /\s*:/y;
+    for (let match = word.exec(css); match; match = word.exec(css)) {
+        colonNext.lastIndex = word.lastIndex;
+        if (!colonNext.test(css))
+            continue;
+        const text = match[0];
+        for (let at = text.indexOf("--"); at !== -1; at = text.indexOf("--", at + 1))
+            names.add(text.slice(at));
+    }
+    return names;
 }
 /**
  * Layering for one declarer: authored stylesheet definitions win over

package/dist/compiler/inlineSubCompositions.js

@@ -13,7 +13,7 @@ import { compositionStyle, cssStyleMergeKey, hasSameLink, } from "./scriptRuns.j
  */
 import { rewriteAssetPath, rewriteAssetPaths, rewriteCssAssetUrls, rewriteInlineStyleAssetUrls, } from "./rewriteSubCompPaths.js";
 import { warnUnknownEnumValues } from "../runtime/getVariables.js";
-import { scopeCssToComposition, wrapInlineScriptWithErrorBoundary, scopedModulePrelude, wrapScopedCompositionScript, } from "./compositionScoping.js";
+import { createCompositionCssScoper, wrapInlineScriptWithErrorBoundary, scopedModulePrelude, wrapScopedCompositionScript, } from "./compositionScoping.js";
 import { namespaceCollidingSvgIds, rewriteSvgIdReferencesInCss, } from "./svgIdNamespacing.js";
 import { checkSubCompositionUsability, resolveSubCompositionContent, } from "@hyperframes/parsers/sub-composition-validity";
 import { enumerateNestedCompositionHosts, planCompositionAssembly, extractedCompositionAssets, } from "./compositionAssembly.js";
@@ -110,6 +110,7 @@ export function ensureExternalLinkTag(doc, link) {
 // ---------------------------------------------------------------------------
 // Default helpers
 // ---------------------------------------------------------------------------
+const isDocument = (node) => node.nodeType === 9;
 function defaultBuildScopeSelector(compId) {
     const escaped = compId.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
     return `[data-composition-id="${escaped}"]`;
@@ -146,6 +147,24 @@ export function inlineSubCompositions(document, hosts, options) {
     const externalLinks = [];
     const variablesByComp = {};
     const svgIdScopes = [];
+    // A file mounted many times reads the same; only its scope, ids and variables differ per mount.
+    // Each file is parsed once and only read; a mount edits its own copy.
+    const parsed = new Map();
+    const parseOnce = (html) => {
+        let doc = parsed.get(html);
+        if (!doc) {
+            doc = parseHtml(html);
+            parsed.set(html, doc);
+        }
+        return doc;
+    };
+    const parseCopy = (html) => {
+        const copy = parseOnce(html).cloneNode(true);
+        return isDocument(copy) ? copy : parseHtml(html);
+    };
+    const usability = new Map();
+    const sheetsWithAssetUrls = new Map();
+    const scopeCssToComposition = createCompositionCssScoper();
     const sceneHosts = new Map();
     const queue = hosts.map((element) => ({
         element,
@@ -164,7 +183,12 @@ export function inlineSubCompositions(document, hosts, options) {
         // tolerant (skip, don't throw) — preview and studio must keep bundling
         // around a scene that's still being authored. Lint and the render
         // pre-flight check use the same helper to fail loudly instead.
-        const validity = checkSubCompositionUsability(compHtml, parseHtml);
+        let validity = compHtml == null ? undefined : usability.get(compHtml);
+        if (!validity) {
+            validity = checkSubCompositionUsability(compHtml, parseOnce);
+            if (compHtml != null)
+                usability.set(compHtml, validity);
+        }
         if (!validity.ok) {
             onMissingComposition?.(src, validity.detail);
             continue;
@@ -176,7 +200,7 @@ export function inlineSubCompositions(document, hosts, options) {
             onMissingComposition?.(src);
             continue;
         }
-        const compDoc = parseHtml(compHtml);
+        const compDoc = parseCopy(compHtml);
         // Determine composition IDs
         let compId;
         let runtimeCompId;
@@ -194,7 +218,7 @@ export function inlineSubCompositions(document, hosts, options) {
             onMissingComposition?.(src);
             continue;
         }
-        const contentDoc = parseHtml(contentHtml);
+        const contentDoc = parseCopy(contentHtml);
         if (!contentDoc.documentElement) {
             onMissingComposition?.(src);
             continue;
@@ -259,7 +283,12 @@ export function inlineSubCompositions(document, hosts, options) {
         // sub-comp's html/body/:root rules from clobbering the host document (they
         // are remapped to the composition box); see compositionScoping.
         const scopeSubStyle = (raw) => {
-            const css = rewriteCssAssetUrls(raw, src, assetExists);
+            const sheetKey = JSON.stringify([src, raw]);
+            let css = sheetsWithAssetUrls.get(sheetKey);
+            if (css === undefined) {
+                css = rewriteCssAssetUrls(raw, src, assetExists);
+                sheetsWithAssetUrls.set(sheetKey, css);
+            }
             return scopeCompId
                 ? scopeCssToComposition(css, scopeCompId, runtimeScope || undefined, authoredRootId, {
                     compoundAuthoredRoot: compoundAuthoredRoot === true,

package/dist/fonts/deterministicFonts.d.ts

@@ -105,7 +105,7 @@ export interface FontFetchRetryPolicy {
     /** Initial full-jitter backoff ceiling. Default: 250 ms. */
     baseDelayMs: number;
 }
-/** Test-only reset — the cache is otherwise process-lifetime, shared across calls. */
+/** Test-only reset of the process and disk caches, so the next lookup reaches `fetchImpl`. */
 export declare function _clearGoogleFontCssCacheForTests(): void;
 /**
  * Options for {@link injectDeterministicFontFaces}.

package/dist/fonts/deterministicFonts.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { FONT_ALIAS_MAP, resolveAliasDisplayName } from "./aliases.js";
@@ -1131,9 +1131,44 @@ async function ensureWoff2DataUri(cachePath, woff2Url, familyName, weight, style
     return `data:font/woff2;base64,${readFileSync(cachePath).toString("base64")}`;
 }
 const googleFontCssCache = new Map();
-/** Test-only reset — the cache is otherwise process-lifetime, shared across calls. */
+const GOOGLE_FONT_CSS_CACHE_DIR = "_css";
+/** Test-only reset of the process and disk caches, so the next lookup reaches `fetchImpl`. */
 export function _clearGoogleFontCssCacheForTests() {
     googleFontCssCache.clear();
+    rmSync(join(resolveFontCacheRoot(), GOOGLE_FONT_CSS_CACHE_DIR), { recursive: true, force: true });
+}
+// The lookup names the woff2 files, so it is cached on disk beside them; otherwise each new process
+// asks the network first and, offline, never reaches them. No family slug has an underscore.
+function googleFontCssCachePath(url) {
+    return join(fontCacheDir(GOOGLE_FONT_CSS_CACHE_DIR), `${createHash("sha256").update(url).digest("hex")}.json`);
+}
+function readCachedGoogleFontCss(url) {
+    let cached;
+    try {
+        cached = JSON.parse(readFileSync(googleFontCssCachePath(url), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof cached !== "object" || cached === null)
+        return null;
+    const body = Reflect.get(cached, "body");
+    const status = Reflect.get(cached, "status");
+    return typeof body === "string" && typeof status === "number" ? { ok: true, body, status } : null;
+}
+/** Keeps only a lookup that named faces; written aside and renamed, so a reader never sees half of it. */
+function writeCachedGoogleFontCss(url, body, status) {
+    if (!/@font-face/i.test(body))
+        return;
+    const path = googleFontCssCachePath(url);
+    const partial = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(partial, JSON.stringify({ status, body }), { mode: 0o644 });
+        renameSync(partial, path);
+    }
+    catch {
+        rmSync(partial, { force: true });
+    }
 }
 /** Rejects with `signal`'s own abort reason without cancelling `promise` itself. */
 function raceAgainstAbort(promise, signal) {
@@ -1152,13 +1187,20 @@ function fetchGoogleFontCss(url, familyName, options, attempt) {
     const mode = options.failClosedFontFetch ? `closed${options.retryPolicy.maxAttempts}` : "open";
     const key = `${mode}:${url}`;
     let shared = googleFontCssCache.get(key);
+    const cached = shared ? null : readCachedGoogleFontCss(url);
+    if (cached) {
+        shared = Promise.resolve(cached);
+        googleFontCssCache.set(key, shared);
+    }
     attempt.cssCache = shared ? "hit" : "fresh";
     if (!shared) {
         // The shared fetch must not carry any one caller's abortSignal, or that
         // caller cancelling would fail the lookup for every other waiter.
         shared = fetchFontResource(url, { headers: { "User-Agent": WOFF2_USER_AGENT } }, (response) => response.text(), familyName, "Google Fonts CSS", { ...options, abortSignal: undefined }).then((result) => {
-            if (result.ok)
+            if (result.ok) {
+                writeCachedGoogleFontCss(url, result.body, result.response.status);
                 return { ok: true, body: result.body, status: result.response.status };
+            }
             // A transient status must not stick for the process lifetime.
             if (isRetryableFontFetchStatus(result.response.status))
                 googleFontCssCache.delete(key);
@@ -1415,8 +1457,14 @@ function extractGoogleFontsText(html) {
     // Intentional over-approximation: raw html includes base64, scripts, and
     // class names, but they collapse in the Set and the budget gate catches bloat.
     const uniqueCharacters = new Set();
-    for (const character of new Set([...Array.from(html), ...Array.from(decodedBodyText)])) {
-        addCaseClosure(uniqueCharacters, character, locales);
+    const seen = new Set();
+    for (const text of [html, decodedBodyText]) {
+        for (const character of text) {
+            if (seen.has(character))
+                continue;
+            seen.add(character);
+            addCaseClosure(uniqueCharacters, character, locales);
+        }
     }
     if (hasTextTransformKeyword(html, FULL_WIDTH_KEYWORD_RE))
         addFullwidthVariants(uniqueCharacters);