@openpresentation/opf-render 0.9.0 → 0.11.0

package/dist/fonts-browser.d.ts

@@ -3,9 +3,47 @@ import type {
   FontRegistry,
   FontRegistryOptions,
 } from "./fonts.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[],
@@ -13,5 +51,31 @@ export declare function loadBrowserFontRegistry(
     document?: Document;
     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,4 +1,25 @@
 import { createFontRegistry, OPFFontError } from "./fonts.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;
+  if (!subtle?.digest)
+    throw new OPFFontError("font-api-unavailable", "Verifying a font SHA-256 requires Web Crypto.");
+  const digest = new Uint8Array(await subtle.digest("SHA-256", data));
+  const actual = [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  if (actual !== String(entry.sha256).toLowerCase())
+    throw new OPFFontError(
+      "font-integrity-mismatch",
+      "The font file differs from its reviewed SHA-256; serve the pinned package.",
+      { url: entry.url, expected: entry.sha256, actual },
+    );
+}
+
 /** Fetch only host-selected font files, then use those exact bytes for shaping and CSS. */
 export async function loadBrowserFontRegistry(entries, options = {}) {
   const documentRef = options.document ?? globalThis.document;
@@ -9,52 +30,225 @@ export async function loadBrowserFontRegistry(entries, options = {}) {
       "The browser Font Loading API is required.",
     );
   const fetcher = options.fetch ?? globalThis.fetch;
-  const faces = await Promise.all(
-    entries.map(async (entry) => {
-      if (entry.data) return entry;
-      if (!entry.url)
-        throw new OPFFontError(
-          "invalid-font-source",
-          "Supply font bytes or a font-file URL.",
-        );
-      const response = await fetcher(entry.url, { signal: options.signal });
-      if (!response.ok)
-        throw new OPFFontError(
-          "font-fetch-failed",
-          `Could not load font (${response.status}).`,
-          { url: entry.url },
-        );
-      return { ...entry, data: new Uint8Array(await response.arrayBuffer()) };
+  const subtle = options.crypto?.subtle ?? globalThis.crypto?.subtle;
+  const fetchFaces = (list, signal) => Promise.all(
+    list.map(async (entry) => {
+      let loaded = entry;
+      if (!entry.data) {
+        if (!entry.url)
+          throw new OPFFontError(
+            "invalid-font-source",
+            "Supply font bytes or a font-file URL.",
+          );
+        const response = await fetcher(entry.url, { signal });
+        if (!response.ok)
+          throw new OPFFontError(
+            "font-fetch-failed",
+            `Could not load font (${response.status}).`,
+            { url: entry.url },
+          );
+        loaded = { ...entry, data: new Uint8Array(await response.arrayBuffer()) };
+      }
+      // Script-pack entries carry the reviewed hash (FF-19); verify before use.
+      await verifyDigest(entry, loaded.data, subtle);
+      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 embedded = registry.embeddedFonts;
+  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 = embedded[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,19 +1,77 @@
-import type {FontRegistry,FontRegistryOptions,EmbeddedFont} from "./fonts.js";
-export declare function loadBundledFontRegistry(options?: FontRegistryOptions): Promise<FontRegistry & {fontFiles:string[]}>;
+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).
+   * `"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;
+}
+/** 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 & {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<{
+  /** 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;
+  /** 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;
-  readonly packages: readonly Readonly<{
-    name:string; version:string; pack:"base"|"office"; source:string;
-    license:string; licenseFile:string; licenseSha256:string;
-    faces:readonly Readonly<{file:string; family:string; weight:number; italic:boolean; sha256:string}>[];
-  }>[];
+  readonly packages: readonly BundledFontPackage[];
 }
 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"];
@@ -23,4 +81,4 @@ export interface PreparedNodeFonts {
     loadSystemFonts: false;
   };
 }
-export declare function prepareNodeFonts(options?: FontRegistryOptions & {pack?:"base"|"office"; includeBaseFonts?: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>;