@openpresentation/opf-render 0.10.0 → 0.11.1

package/dist/font-policy.js

@@ -5,9 +5,9 @@ const SNAPSHOT=freeze({
  "decisions": {
   "status": "provisional, owner may revise",
   "aptos-preview": {
-   "replacement": "Roboto",
-   "compatibility": "visual",
-   "note": "Default scheme aptos previews with Roboto; the PPTX still names Aptos."
+   "replacement": "Intos",
+   "compatibility": "metric",
+   "note": "Owner policy 2026-09-29: a licensed font the user selects previews with an open replacement that looks similar and has the same size on screen; the PPTX keeps the selected name. Aptos previews with Intos (metric, OFL-1.1, vendored in opf-render); Roboto and Carlito are alternates for registries built without the Intos faces (they are in the opf-render office pack)."
   },
   "segoe-ui-preview": {
    "replacement": "Red Hat Display",
@@ -23,7 +23,7 @@ const SNAPSHOT=freeze({
  },
  "source": {
   "path": "spec/reference/font-policy.json",
-  "sha256": "7368c1f56b8a93c63b09cabb8aa9c5284dd9c8b1fd811f9387b05c175abbd5ac"
+  "sha256": "2616392b58bcaaffef5182c612ad7b562f9187cd099f919ca3abee225a5411a3"
  },
  "families": [
   {
@@ -81,18 +81,20 @@ const SNAPSHOT=freeze({
    "embeddableByOpf": false,
    "replacement": {
     "decision": "aptos-preview",
+    "source": "https://github.com/muglug/intos/tree/fef9315c14da9e4b23b4c3cac8e718998d4e4736",
     "measured": {
-     "replacement": "Roboto",
-     "meanAbsWidthDelta": 0.0215,
-     "meanWidthDelta": 0.0008,
-     "maxAbsWidthDelta": 0.0739,
+     "replacement": "Intos",
+     "meanAbsWidthDelta": 0,
+     "meanWidthDelta": 0,
+     "maxAbsWidthDelta": 0,
      "styles": 4,
      "reference": "Aptos 2.01;O365"
     },
-    "family": "Roboto",
-    "compatibility": "visual"
+    "family": "Intos",
+    "compatibility": "metric"
    },
    "alternates": [
+    "Roboto",
     "Carlito"
    ]
   },
@@ -105,18 +107,20 @@ const SNAPSHOT=freeze({
    ],
    "embeddableByOpf": false,
    "replacement": {
-    "family": "Carlito",
-    "compatibility": "visual",
+    "family": "Intos Display",
+    "compatibility": "metric",
+    "source": "https://github.com/muglug/intos/tree/fef9315c14da9e4b23b4c3cac8e718998d4e4736",
     "measured": {
-     "replacement": "Carlito",
-     "meanAbsWidthDelta": 0.0184,
-     "meanWidthDelta": -0.0057,
-     "maxAbsWidthDelta": 0.0691,
+     "replacement": "Intos Display",
+     "meanAbsWidthDelta": 0,
+     "meanWidthDelta": 0,
+     "maxAbsWidthDelta": 0,
      "styles": 4,
      "reference": "Aptos Display 2.01;O365"
     }
    },
    "alternates": [
+    "Carlito",
     "Roboto"
    ]
   },
@@ -146,17 +150,21 @@ const SNAPSHOT=freeze({
    ],
    "embeddableByOpf": false,
    "replacement": {
-    "family": "Carlito",
-    "compatibility": "visual",
+    "family": "Intos Narrow",
+    "compatibility": "metric",
+    "source": "https://github.com/muglug/intos/tree/fef9315c14da9e4b23b4c3cac8e718998d4e4736",
     "measured": {
-     "replacement": "Carlito",
-     "meanAbsWidthDelta": 0.0233,
-     "meanWidthDelta": 0.0222,
-     "maxAbsWidthDelta": 0.0786,
+     "replacement": "Intos Narrow",
+     "meanAbsWidthDelta": 0,
+     "meanWidthDelta": 0,
+     "maxAbsWidthDelta": 0,
      "styles": 4,
      "reference": "Aptos Narrow 2.01;O365"
     }
-   }
+   },
+   "alternates": [
+    "Carlito"
+   ]
   },
   {
    "family": "Aptos Serif",
@@ -167,10 +175,21 @@ const SNAPSHOT=freeze({
    ],
    "embeddableByOpf": false,
    "replacement": {
-    "family": "Tinos",
-    "compatibility": "visual",
-    "measured": null
-   }
+    "family": "Intos Serif",
+    "compatibility": "metric",
+    "source": "https://github.com/muglug/intos/tree/fef9315c14da9e4b23b4c3cac8e718998d4e4736",
+    "measured": {
+     "replacement": "Intos Serif",
+     "meanAbsWidthDelta": 0,
+     "meanWidthDelta": 0,
+     "maxAbsWidthDelta": 0,
+     "styles": 4,
+     "reference": "Aptos Serif 2.01;240513210638;O365"
+    }
+   },
+   "alternates": [
+    "Tinos"
+   ]
   },
   {
    "family": "Arabic Typesetting",
@@ -675,8 +694,8 @@ const SNAPSHOT=freeze({
     "compatibility": "visual",
     "measured": {
      "replacement": "Source Sans 3",
-     "meanAbsWidthDelta": 0.0157,
-     "meanWidthDelta": 0.0151,
+     "meanAbsWidthDelta": 0.0158,
+     "meanWidthDelta": 0.0152,
      "maxAbsWidthDelta": 0.0521,
      "styles": 4,
      "reference": "Corbel 6.01"
@@ -957,12 +976,16 @@ const SNAPSHOT=freeze({
    "embeddableByOpf": false,
    "replacement": {
     "family": "Gelasio",
-    "compatibility": "visual",
+    "compatibility": "metric",
+    "disabledFeatures": [
+     "liga",
+     "clig"
+    ],
     "measured": {
      "replacement": "Gelasio",
-     "meanAbsWidthDelta": 0.0002,
-     "meanWidthDelta": -0.0002,
-     "maxAbsWidthDelta": 0.0102,
+     "meanAbsWidthDelta": 0,
+     "meanWidthDelta": 0,
+     "maxAbsWidthDelta": 0,
      "styles": 4,
      "reference": "Georgia 5.59"
     },
@@ -982,9 +1005,9 @@ const SNAPSHOT=freeze({
     "compatibility": "visual",
     "measured": {
      "replacement": "Source Sans 3",
-     "meanAbsWidthDelta": 0.051,
-     "meanWidthDelta": 0.0038,
-     "maxAbsWidthDelta": 0.1456,
+     "meanAbsWidthDelta": 0.0511,
+     "meanWidthDelta": 0.0039,
+     "maxAbsWidthDelta": 0.1459,
      "styles": 4,
      "reference": "Gill Sans MT 1.65"
     }
@@ -1098,6 +1121,38 @@ const SNAPSHOT=freeze({
     "Carlito"
    ]
   },
+  {
+   "family": "Intos",
+   "licenseClass": "open",
+   "license": "OFL-1.1",
+   "availability": [],
+   "embeddableByOpf": true,
+   "replacement": null
+  },
+  {
+   "family": "Intos Display",
+   "licenseClass": "open",
+   "license": "OFL-1.1",
+   "availability": [],
+   "embeddableByOpf": true,
+   "replacement": null
+  },
+  {
+   "family": "Intos Narrow",
+   "licenseClass": "open",
+   "license": "OFL-1.1",
+   "availability": [],
+   "embeddableByOpf": true,
+   "replacement": null
+  },
+  {
+   "family": "Intos Serif",
+   "licenseClass": "open",
+   "license": "OFL-1.1",
+   "availability": [],
+   "embeddableByOpf": true,
+   "replacement": null
+  },
   {
    "family": "Kalinga",
    "licenseClass": "proprietary-standard",

package/dist/fonts-browser.d.ts

@@ -3,13 +3,48 @@ import type {
   FontRegistry,
   FontRegistryOptions,
 } from "./fonts.js";
-import type { BundledFontPackage, ScriptSelection } from "./fonts-node.js";
+import type { AutoScriptSelection, BundledFontPackage, LazyFont, ScriptSelection } from "./fonts-node.js";
+export type { LazyFont } from "./fonts-node.js";
+export type { AutoScriptSelection } from "./fonts-node.js";
+export { detectPresentationScripts, autoScriptSelection } from "./fonts-node.js";
 export interface BrowserFontInput extends Omit<FontFaceInput, "data"> {
   data?: Uint8Array;
   url?: string;
   /** Reviewed SHA-256 (hex); verified with Web Crypto before the face is used. */
   sha256?: string;
 }
+export interface BrowserFontRegistry extends FontRegistry {
+  dispose(): void;
+  /** Every vendored face a host can load on demand: family, style, package-relative file and pinned sha256. */
+  readonly lazyFonts: readonly LazyFont[];
+  /**
+   * Load the vendored faces (for example Intos for the default Aptos scheme) the presentation's font families resolve to
+   * under the registry's `substitutionPolicy` (nothing is downloaded for a family the policy would not resolve), once
+   * each, from `lazyFontsBaseUrl`. Fetches and verifies every file, then adds the faces to the document and the registry
+   * together; on failure nothing changes and the call can be retried. Call it before measuring a document. After
+   * `dispose()` it rejects with `font-registry-disposed`.
+   */
+  ensureLazyFonts(presentation: unknown, options?: { signal?: AbortSignal }): Promise<LazyFont[]>;
+  /** Synchronous: the vendored faces the presentation needs under the registry's policy that are not loaded yet. Empty means `ensureLazyFonts` fetches nothing. */
+  pendingLazyFonts(presentation: unknown): LazyFont[];
+
+  /** Load script faces for ISO 15924 codes (or "all") from `scriptBaseUrl`. Resolves with the newly loaded package names. */
+  loadScripts(scripts: ScriptSelection, options?: { signal?: AbortSignal }): Promise<string[]>;
+  /**
+   * Load the script faces the presentation's text needs, once each (FF-19). Cheap when nothing new is
+   * needed. Also loads the CJK face a glyph fallback needs for drawn characters the loaded faces lack. Call it after
+   * edits and render again afterwards: measurements planned earlier do not know the new faces. `signal` belongs to
+   * this call only. `uncovered` lists drawn CJK characters no loaded face covers. At most one CJK face beyond the text's own
+   * scripts is loaded for glyph fallback. If a package fails the others still load and the call rejects with an
+   * OPFFontError whose `details` are `{ loaded: string[]; failed: {package, code, message}[] }`. A failed call (fetch, hash, FontFace load) leaves nothing loaded and can be retried; after
+   * `dispose()` it rejects with `font-registry-disposed`.
+   */
+  ensureScripts(presentation: unknown, options?: { signal?: AbortSignal }): Promise<AutoScriptSelection & { loaded: string[]; uncovered: string[] }>;
+  /** Synchronous: package names the presentation needs that are not loaded yet. Empty means `ensureScripts` fetches nothing, so a host can render immediately. */
+  pendingScripts(presentation: unknown): string[];
+  /** Names of the script-pack packages loaded so far. */
+  readonly loadedScriptPackages: string[];
+}
 export declare function loadBrowserFontRegistry(
   entries: BrowserFontInput[],
   options?: FontRegistryOptions & {
@@ -17,11 +52,30 @@ export declare function loadBrowserFontRegistry(
     fetch?: typeof fetch;
     signal?: AbortSignal;
     crypto?: { subtle: SubtleCrypto };
+    /** Script faces to load once the registry exists: "auto" (with `presentation`), "all" or ISO 15924 codes. Needs `scriptBaseUrl`. */
+    scripts?: ScriptSelection | "auto";
+    /** The presentation whose text decides `scripts: "auto"`. */
+    presentation?: unknown;
+    /** Where the host serves the installed `@expo-google-fonts/*` packages; script faces are fetched from here, hash-verified. */
+    scriptBaseUrl?: string;
+    /** Where the host serves this package's `fonts` directory, so vendored faces (Intos, the open families) load on demand from `<base>/<package-relative file>` (fonts/intos/..., fonts/<family>/...). */
+    lazyFontsBaseUrl?: string;
   },
-): Promise<FontRegistry & { dispose(): void }>;
+): Promise<BrowserFontRegistry>;
 export declare function scriptFontPackages(scripts: ScriptSelection): BundledFontPackage[];
 /** Hash-pinned browser entries for the script pack, served by the host from `baseUrl`. */
 export declare function scriptFontEntries(
   scripts: ScriptSelection,
   options: { baseUrl: string },
 ): (BrowserFontInput & { url: string; family: string; weight: number; italic: boolean; sha256: string; scripts: string[]; package: string; license: string })[];
+/** Every vendored face of this package: family, style, package-relative file, sha256. */
+export declare function lazyFontList(): readonly LazyFont[];
+/** Hash-pinned browser entries for the vendored faces, served by the host from `baseUrl` at their package-relative paths. */
+export declare function lazyFontEntries(options: { baseUrl: string }, list?: readonly LazyFont[]): (BrowserFontInput & { url: string; family: string; weight: number; italic: boolean; sha256: string; package: string })[];
+/** The font families a presentation's slides resolve (heading, body and code roles); empty for a document that does not resolve. */
+export declare function presentationFamilies(presentation: unknown): Set<string>;
+/**
+ * The vendored faces a set of resolved families needs that the registry does not hold, following the registry's own order and
+ * `policy` (default "visual"): the family itself, an alias target, the declared replacement, then its alternates.
+ */
+export declare function lazyFontsFor(families: Iterable<string>, context: { lazy: readonly LazyFont[]; hasFamily(family: string): boolean; loaded?: ReadonlySet<string>; policy?: "none" | "metric" | "visual"; aliases?: ReadonlyMap<string, string> }): LazyFont[];

package/dist/fonts-browser.js

@@ -1,5 +1,10 @@
 import { createFontRegistry, OPFFontError } from "./fonts.js";
-export { scriptFontEntries, scriptFontPackages } from "./script-font-pack.js";
+import { lazyFontEntries, lazyFontList } from "./lazy-font-list.js";
+import { lazyFontsFor, presentationFamilies } from "./lazy-fonts.js";
+import { analyzePresentationScripts, nextFallbackPackage, scriptFontPackages, scriptPackageEntries, scriptSelectionOf, uncoveredCjkCharacters } from "./script-font-pack.js";
+export { autoScriptSelection, detectPresentationScripts, scriptFontEntries, scriptFontPackages } from "./script-font-pack.js";
+export { lazyFontEntries, lazyFontList } from "./lazy-font-list.js";
+export { lazyFontsFor, presentationFamilies } from "./lazy-fonts.js";
 
 async function verifyDigest(entry, data, subtle) {
   if (entry.sha256 === undefined) return;
@@ -26,8 +31,8 @@ export async function loadBrowserFontRegistry(entries, options = {}) {
     );
   const fetcher = options.fetch ?? globalThis.fetch;
   const subtle = options.crypto?.subtle ?? globalThis.crypto?.subtle;
-  const faces = await Promise.all(
-    entries.map(async (entry) => {
+  const fetchFaces = (list, signal) => Promise.all(
+    list.map(async (entry) => {
       let loaded = entry;
       if (!entry.data) {
         if (!entry.url)
@@ -35,7 +40,7 @@ export async function loadBrowserFontRegistry(entries, options = {}) {
             "invalid-font-source",
             "Supply font bytes or a font-file URL.",
           );
-        const response = await fetcher(entry.url, { signal: options.signal });
+        const response = await fetcher(entry.url, { signal });
         if (!response.ok)
           throw new OPFFontError(
             "font-fetch-failed",
@@ -49,34 +54,201 @@ export async function loadBrowserFontRegistry(entries, options = {}) {
       return loaded;
     }),
   );
+  const faces = await fetchFaces(entries, options.signal);
   const registry = createFontRegistry(faces, options),
     loaded = [];
   // Normalize family names using the registry's parsed font metadata.
   const described = registry.describeFaces();
+  // Registers browser FontFaces for faces already parsed by the registry; on failure nothing stays registered.
+  const registerBrowserFaces = async (list, descriptors) => {
+    const added = [];
+    try {
+      await Promise.all(
+        list.map(async (entry, index) => {
+          const descriptor = descriptors[index];
+          const face = new FontFaceRef(
+            descriptor.family,
+            entry.data.slice().buffer,
+            {
+              weight: String(descriptor.weight),
+              style: descriptor.italic ? "italic" : "normal",
+            },
+          );
+          await face.load();
+          added.push(face);
+        }),
+      );
+      for (const face of added) documentRef.fonts.add(face);
+      await documentRef.fonts.ready;
+    } catch (error) {
+      for (const face of added) documentRef.fonts.delete(face);
+      throw new OPFFontError("font-load-failed", error.message);
+    }
+    loaded.push(...added);
+  };
+  await registerBrowserFaces(faces, described);
+
+  // Script faces (FF-19) are loaded lazily, once a document needs them, and only for the scripts it uses.
+  const scriptPackages = new Set();
+  let queue = Promise.resolve(), disposed = false;
+  const gone = () => new OPFFontError("font-registry-disposed", "The font registry was disposed.");
+  const baseUrl = () => {
+    if (typeof options.scriptBaseUrl !== "string" || !options.scriptBaseUrl)
+      throw new OPFFontError("invalid-font-source", "Loading script fonts requires scriptBaseUrl, where the host serves the installed @expo-google-fonts packages.");
+    return options.scriptBaseUrl;
+  };
+  // Loads whole packages. Order matters: fetch and verify, load every FontFace (not yet visible to the document),
+  // then register them with the document and add them to the registry atomically. Nothing is half loaded: on any
+  // failure (fetch, hash, FontFace.load, registry) the document and registry are unchanged and the packages stay
+  // pending, so the next call retries. `signal` belongs to this call only.
+  const loadPackageList = (packages, { signal } = {}) => {
+    const result = queue.then(async () => {
+      if (disposed) throw gone();
+      signal?.throwIfAborted?.();
+      const pending = packages.filter((item) => !scriptPackages.has(item.name));
+      if (!pending.length) return [];
+      const fetched = await fetchFaces(scriptPackageEntries(pending, { baseUrl: baseUrl() }), signal);
+      let browserFaces;
+      try {
+        browserFaces = await Promise.all(fetched.map(async (entry) => {
+          const face = new FontFaceRef(entry.family, entry.data.slice().buffer, { weight: String(entry.weight ?? 400), style: entry.italic ? "italic" : "normal" });
+          await face.load();
+          return face;
+        }));
+      } catch (error) { throw new OPFFontError("font-load-failed", error.message); }
+      if (disposed) throw gone();
+      const shown = [];
+      try {
+        for (const face of browserFaces) { documentRef.fonts.add(face); shown.push(face); }
+        registry.addFaces(fetched);
+      } catch (error) {
+        for (const face of shown) documentRef.fonts.delete(face);
+        throw error;
+      }
+      loaded.push(...browserFaces);
+      for (const item of pending) scriptPackages.add(item.name);
+      try { await documentRef.fonts.ready; } catch { /* the faces are loaded and registered */ }
+      return pending.map((item) => item.name);
+    });
+    queue = result.catch(() => {});
+    return result;
+  };
+  const covers = (character) => registry.scriptFacesCover(character);
+  Object.assign(registry, {
+    /** Load the script faces for explicit ISO 15924 codes (or 'all'). Resolves with the newly loaded package names. `signal` aborts this call's fetches. */
+    loadScripts: (scripts, callOptions) => loadPackageList(scriptFontPackages(scripts), callOptions),
+    /**
+     * Load the script faces the presentation's text needs, once each (FF-19), then the (at most one) CJK face a glyph
+     * fallback needs for characters the loaded faces lack. Cheap when nothing new is needed; call it after edits and
+     * render again afterwards. Resolves with the detected scripts, the packages loaded by this call, the scripts no
+     * pinned font serves and `uncovered`, drawn CJK characters no loaded face covers (the renderer reports
+     * `missing-glyph` for them). Each package loads all or nothing. If some package fails, the others still load: the
+     * call then rejects with an OPFFontError (the first failure's code) whose `details` hold `loaded` (packages this
+     * call did load) and `failed` (`{package, code, message}` per failed package); nothing is lost and a later call
+     * retries only the failures. `signal` aborts this call's fetches.
+     */
+    async ensureScripts(presentation, callOptions) {
+      if (disposed) throw gone();
+      const analysis = analyzePresentationScripts(presentation), selection = scriptSelectionOf(analysis);
+      const loadedNow = [], failed = [];
+      const attempt = async (item) => {
+        try { loadedNow.push(...(await loadPackageList([item], callOptions))); }
+        catch (error) { failed.push({ package: item.name, code: error?.code ?? "font-load-failed", message: error?.message ?? String(error), error }); }
+      };
+      for (const item of scriptFontPackages(selection.scripts)) await attempt(item);
+      // Fallback faces only follow a clean primary load: a failed package would otherwise be judged uncovered.
+      if (!failed.length) for (let next = nextFallbackPackage(analysis, { covers, loaded: scriptPackages }); next && !failed.length; next = nextFallbackPackage(analysis, { covers, loaded: scriptPackages })) await attempt(next);
+      // An aborted call rejects with the signal's reason; packages loaded before the abort stay loaded.
+      if (callOptions?.signal?.aborted) throw callOptions.signal.reason ?? failed[0]?.error;
+      if (failed.length) {
+        const first = failed[0];
+        throw new OPFFontError(first.code, first.message, { loaded: loadedNow, failed: failed.map(({ package: name, code, message }) => ({ package: name, code, message })), cause: first.error });
+      }
+      return { ...selection, loaded: loadedNow, uncovered: uncoveredCjkCharacters(analysis, { covers }) };
+    },
+    /** Synchronous: script-pack packages the presentation needs that are not loaded yet. Empty means `ensureScripts` would fetch nothing. */
+    pendingScripts(presentation) {
+      const analysis = analyzePresentationScripts(presentation);
+      const primary = scriptFontPackages(scriptSelectionOf(analysis).scripts).map((item) => item.name).filter((name) => !scriptPackages.has(name));
+      if (primary.length) return primary;
+      const next = nextFallbackPackage(analysis, { covers, loaded: scriptPackages });
+      return next ? [next.name] : [];
+    },
+  });
+  // FF-31: vendored faces (the open families and Intos) load on demand, once a document needs them. They share the
+  // script loader's queue and disposed state, and the same all-or-nothing order: fetch and verify, load every FontFace,
+  // then add them to the document and the registry together.
+  const lazy = lazyFontList(), lazyLoaded = new Set();
+  const policy = options.substitutionPolicy ?? "none";
+  const aliasTargets = new Map(Object.entries(options.aliases ?? {}).map(([from, to]) => [from.toLowerCase(), to]));
+  const hasFamily = (family) => registry.describeFaces().some((face) => face.family.toLowerCase() === String(family).toLowerCase());
+  const neededLazy = (presentation) => lazyFontsFor(presentationFamilies(presentation), { lazy, hasFamily, loaded: lazyLoaded, policy, aliases: aliasTargets });
+  const lazyBaseUrl = () => {
+    if (typeof options.lazyFontsBaseUrl !== "string" || !options.lazyFontsBaseUrl)
+      throw new OPFFontError("invalid-font-source", "Loading vendored fonts requires lazyFontsBaseUrl, where the host serves the package's fonts directory.");
+    return options.lazyFontsBaseUrl;
+  };
+  Object.assign(registry, {
+    /** Every vendored face a host can load on demand: family, style, package-relative file and pinned sha256. */
+    lazyFonts: lazy,
+    /**
+     * Load the vendored faces the presentation's font families resolve to under the registry's substitution policy (nothing
+     * is downloaded for a family the policy would not resolve), once each. All or nothing: on any failure (fetch, hash,
+     * FontFace.load, registry) the document and registry are unchanged and the call can be retried. Cheap when nothing is
+     * needed. Call it before measuring a document, and again after edits that change fonts. Resolves with the faces added.
+     */
+    ensureLazyFonts(presentation, callOptions = {}) {
+      const result = queue.then(async () => {
+        if (disposed) throw gone();
+        callOptions.signal?.throwIfAborted?.();
+        const pending = neededLazy(presentation);
+        if (!pending.length) return [];
+        const fetched = (await fetchFaces(lazyFontEntries({ baseUrl: lazyBaseUrl() }, pending), callOptions.signal)).map((entry) => ({ ...entry, embed: "used" }));
+        let browserFaces;
+        try {
+          browserFaces = await Promise.all(fetched.map(async (entry) => {
+            const face = new FontFaceRef(entry.family, entry.data.slice().buffer, { weight: String(entry.weight), style: entry.italic ? "italic" : "normal" });
+            await face.load();
+            return face;
+          }));
+        } catch (error) { throw new OPFFontError("font-load-failed", error.message); }
+        if (disposed) throw gone();
+        const shown = [];
+        try {
+          for (const face of browserFaces) { documentRef.fonts.add(face); shown.push(face); }
+          registry.addFaces(fetched);
+        } catch (error) {
+          for (const face of shown) documentRef.fonts.delete(face);
+          throw error;
+        }
+        loaded.push(...browserFaces);
+        for (const item of pending) lazyLoaded.add(item.file);
+        try { await documentRef.fonts.ready; } catch { /* the faces are loaded and registered */ }
+        return pending;
+      });
+      queue = result.catch(() => {});
+      return result;
+    },
+    /** Synchronous: the vendored faces the presentation needs under the registry's policy that are not loaded yet. Empty means `ensureLazyFonts` fetches nothing. */
+    pendingLazyFonts: (presentation) => neededLazy(presentation),
+  });
+  /** Names of the script-pack packages loaded so far. */
+  Object.defineProperty(registry, "loadedScriptPackages", { get: () => [...scriptPackages], enumerable: true });
   try {
-    await Promise.all(
-      faces.map(async (entry, index) => {
-        const descriptor = described[index];
-        const face = new FontFaceRef(
-          descriptor.family,
-          entry.data.slice().buffer,
-          {
-            weight: String(descriptor.weight),
-            style: descriptor.italic ? "italic" : "normal",
-          },
-        );
-        await face.load();
-        loaded.push(face);
-      }),
-    );
-    for (const face of loaded) documentRef.fonts.add(face);
-    await documentRef.fonts.ready;
+    if (options.scripts === "auto") {
+      if (options.presentation === null || typeof options.presentation !== "object")
+        throw new OPFFontError("invalid-font-scripts", "scripts: 'auto' needs the presentation whose text decides the scripts.", { scripts: options.scripts });
+      await registry.ensureScripts(options.presentation, { signal: options.signal });
+    } else if (options.scripts !== undefined && !(Array.isArray(options.scripts) && !options.scripts.length)) {
+      await registry.loadScripts(options.scripts, { signal: options.signal });
+    }
   } catch (error) {
     for (const face of loaded) documentRef.fonts.delete(face);
-    throw new OPFFontError("font-load-failed", error.message);
+    throw error;
   }
   return Object.assign(registry, {
     dispose() {
+      disposed = true;
       for (const face of loaded) documentRef.fonts.delete(face);
     },
   });

package/dist/fonts-node.d.ts

@@ -1,24 +1,68 @@
-import type {FontRegistry,FontRegistryOptions,EmbeddedFont,FontFaceInput} from "./fonts.js";
+import type {FontRegistry,FontRegistryOptions,EmbeddedFont,FontFaceInput,ScriptFontProfile} from "./fonts.js";
 /** A caller-supplied face (FF-31), for example a licensed copy of the real font. Node callers may pass a file path. */
 export type CallerFontFace = FontFaceInput | (Omit<FontFaceInput, "data"> & {path: string});
 /** "all" or ISO 15924 codes (`Jpan`, `Hans`, `Hant`, `Kore`, `Arab`, `Hebr`, `Deva`, `Thai`, ...). */
 export type ScriptSelection = "all" | string[];
+/** What `scripts: "auto"` chose for a presentation (FF-19). */
+export interface AutoScriptSelection {
+  /** Scripts the presentation's drawn text uses, other than Latin, Greek and Cyrillic. */
+  detected: string[];
+  /** The detected scripts a pinned package serves; the input for `scriptFontPackages`. */
+  scripts: string[];
+  /** Detected scripts no pinned open font serves; that text uses the design font. */
+  unavailable: string[];
+}
+/** Script-pack packages that `scripts: "auto"` loaded or found not installed. */
+export interface AppliedScriptSelection extends AutoScriptSelection { packages: string[]; notInstalled: string[]; /** Drawn CJK characters no loaded face covers (glyph fallback stopped at its cap). */ uncovered?: string[] }
+/** Script keys whose faces a preview of the presentation needs: text decides, the document language only tells Han scripts apart. */
+export declare function detectPresentationScripts(presentation: unknown, options?: { profile?: ScriptFontProfile }): string[];
+export declare function autoScriptSelection(presentation: unknown, options?: { profile?: ScriptFontProfile }): AutoScriptSelection;
 export interface ScriptPackOptions {
   /** Caller-supplied faces, loaded first so a licensed real font resolves as an exact face (FF-31). */
   faces?: readonly CallerFontFace[];
-  /** Also load the optional, hash-pinned OFL Noto script pack for these scripts (FF-19). */
-  scripts?: ScriptSelection;
+  /**
+   * Also load the optional, hash-pinned OFL Noto script pack for these scripts (FF-19).
+   * `"auto"` loads only the scripts `presentation` draws (and needs it); a script package that is not installed
+   * is reported through `onDiagnostic` instead of failing.
+   */
+  scripts?: ScriptSelection | "auto";
+  /** The presentation whose text decides `scripts: "auto"`. */
+  presentation?: unknown;
+  /** Receives `script-font-unavailable` and `script-font-not-installed` for `scripts: "auto"`. */
+  onDiagnostic?: (diagnostic: {code: string; message: string; script?: string; package?: string; scripts?: string[]}) => void;
 }
-export declare function loadBundledFontRegistry(options?: FontRegistryOptions & ScriptPackOptions): Promise<FontRegistry & {fontFiles:string[]}>;
+/** A vendored face that an SVG embeds only when its text names the family (the open families and Intos), and that browser hosts load on demand from a separate hash-pinned file. */
+export interface LazyFont { readonly package: string; readonly family: string; readonly weight: number; readonly italic: boolean; /** Path relative to the package root, for example fonts/intos/Intos-Regular.ttf. */ readonly file: string; readonly sha256: string; readonly license: string; readonly renamedFrom?: string }
+export type ScriptFontRegistry = FontRegistry & {fontFiles:string[]; /** Set for `scripts: "auto"`. */ scriptSelection?: AppliedScriptSelection};
+export type NodeFontRegistry = ScriptFontRegistry & {/** The embed "used" faces this registry holds, with the files a host copies to serve them itself. */ lazyFonts: readonly LazyFont[]};
+export declare function loadBundledFontRegistry(options?: FontRegistryOptions & ScriptPackOptions): Promise<NodeFontRegistry>;
 
-export declare function loadOfficeFontRegistry(options?: FontRegistryOptions & ScriptPackOptions & {includeBaseFonts?:boolean}): Promise<FontRegistry & {fontFiles:string[]}>;
+export declare function loadOfficeFontRegistry(options?: FontRegistryOptions & ScriptPackOptions & {includeBaseFonts?:boolean; /** Leave out the open families font schemes select (FF-31); default true. */ includeOpenFonts?:boolean}): Promise<NodeFontRegistry>;
 
 export type BundledFontPackage = Readonly<{
-  name:string; version:string; pack:"base"|"office"|"scripts"; source:string;
+  /** An npm package name, or a plain id for a vendored entry of a git upstream. */
+  name:string;
+  /** The exact npm version, or for a git-upstream vendored entry the pinned upstream commit. */
+  version:string; pack:"base"|"office"|"open"|"scripts"; source:string;
+  /** FF-31: directory inside this package (for example `fonts/carlito`) that holds the vendored faces and notice (`file` and `licenseFile` are relative to it); absent for npm packages. */
+  vendored?: string;
+  /** "used": the package's faces are embedded in an SVG only when its text names the family, and browsers load them on demand (the open pack always does). */
+  embed?: "used";
+  /** An authored provenance and copyright notice in `vendored`, hash-pinned beside the license and appended to it. */
+  noticeFile?: string; noticeSha256?: string;
   /** ISO 15924 scripts served by a script-pack package. */
   scripts?: readonly string[];
   license:string; licenseFile:string; licenseSha256:string;
-  faces:readonly Readonly<{file:string; family:string; weight:number; italic:boolean; sha256:string}>[];
+  /** Vendored from a git upstream: the commit-pinned URL of the notice. Vendored from npm: the notice's path in the npm package. */
+  upstreamLicenseUrl?:string; npmLicenseFile?:string;
+  /** The family this package is the renamed successor of; requests for the old name draw these faces, reported visual. */
+  renamedFrom?:string;
+  reservedFontNames:readonly string[]; upstream:string; copyright:string;
+  faces:readonly Readonly<{file:string; family:string; weight:number; italic:boolean; sha256:string;
+    /** FF-31: the byte-identical upstream release file this face is (sha256 equals the face's own). */
+    upstreamFile?: Readonly<{url:string; sha256:string}>;
+    /** FF-31: for a vendored npm-derived (instanced) face, its path in the npm package it was copied from. */
+    npmFile?: string}>[];
 }>;
 export interface BundledFontManifest {
   readonly version: number;
@@ -27,7 +71,7 @@ export interface BundledFontManifest {
 export declare const BUNDLED_FONT_MANIFEST: BundledFontManifest;
 export declare function scriptFontPackages(scripts: ScriptSelection): BundledFontPackage[];
 export interface PreparedNodeFonts {
-  registry: FontRegistry & {fontFiles:string[]};
+  registry: NodeFontRegistry;
   manifest: BundledFontManifest;
   options: {
     textMeasurement: FontRegistry["textMeasurement"];
@@ -37,4 +81,4 @@ export interface PreparedNodeFonts {
     loadSystemFonts: false;
   };
 }
-export declare function prepareNodeFonts(options?: FontRegistryOptions & ScriptPackOptions & {pack?:"base"|"office"; includeBaseFonts?:boolean; /** Embed script faces in SVG (large); default false. */ embedScriptFonts?:boolean}): Promise<PreparedNodeFonts>;
+export declare function prepareNodeFonts(options?: FontRegistryOptions & ScriptPackOptions & {pack?:"base"|"office"; includeBaseFonts?:boolean; /** With pack "office": leave out the open families (FF-31); default true. */ includeOpenFonts?:boolean; /** Embed script faces in SVG (large); default false. */ embedScriptFonts?:boolean;}): Promise<PreparedNodeFonts>;