@openpresentation/opf-render 0.13.1 → 0.15.0

package/dist/fonts-browser.d.ts

@@ -1,7 +1,9 @@
 import type {
+  EnsureResult,
   FontFaceInput,
   FontRegistry,
   FontRegistryOptions,
+  FontsHandle,
 } from "./fonts.js";
 import type { AutoScriptSelection, BundledFontPackage, LazyFont, ScriptSelection } from "./fonts-node.js";
 import type { RenderSvgOptions } from "./svg.js";
@@ -53,9 +55,29 @@ export interface BrowserFontRegistry extends FontRegistry {
   /** Names of the script-pack packages loaded so far. */
   readonly loadedScriptPackages: string[];
 }
-export declare function loadBrowserFontRegistry(
-  entries: BrowserFontInput[],
+/**
+ * The fonts handle of a browser: the faces you list, registered with the document, and on demand the script and vendored faces a deck
+ * draws. Pass it as `{ fonts }` to `renderSvg`, `renderSlideSvg`, `<opf-deck>` and the player, core `paginate` and `validate`, and the editor.
+ * The registry behind it keeps the lower-level loaders (`ensureLazyFonts`, `ensureScripts`, `loadScripts`, `pendingLazyFonts`, `pendingScripts`).
+ */
+export interface BrowserFontsHandle extends FontsHandle {
+  readonly registry: BrowserFontRegistry;
+  /** Remove every face this handle added from the document. */
+  dispose(): void;
+  /**
+   * Load the vendored and script faces the presentation draws (each hash-verified, all or nothing), repeating while loading changes what
+   * is needed. Cheap when nothing is needed. Besides `signal`, the call takes the `renderSvg` options the document resolves with
+   * (`catalogs`, ...) over the loader's `renderOptions`. A document that does not resolve rejects with what `renderSvg` throws for it; after
+   * `dispose()` it rejects with `font-registry-disposed`.
+   */
+  ensure(presentation: unknown, options?: { signal?: AbortSignal } & Partial<RenderSvgOptions>): Promise<EnsureResult>;
+  /** Synchronous: the vendored files and script packages `ensure` would fetch. Empty means a render can start now. Throws what `renderSvg` throws for a document that does not resolve. */
+  pending(presentation: unknown, renderOptions?: Partial<RenderSvgOptions>): string[];
+}
+export declare function loadFonts(
   options?: FontRegistryOptions & {
+    /** The faces to register at startup (the host's startup set; the rest can be `extraLazyFonts`). Each is fetched from `url` or taken from `data`, and verified when it has a `sha256`. */
+    faces?: BrowserFontInput[];
     document?: Document;
     fetch?: typeof fetch;
     signal?: AbortSignal;
@@ -84,7 +106,7 @@ export declare function loadBrowserFontRegistry(
      */
     renderOptions?: Partial<RenderSvgOptions>;
   },
-): Promise<BrowserFontRegistry>;
+): Promise<BrowserFontsHandle>;
 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(

package/dist/fonts-browser.js

@@ -1,6 +1,7 @@
-import { createFontRegistry, OPFFontError } from "./fonts.js";
+import { createFontRegistry, OPFFontError } from "./font-registry.js";
 import { lazyFontEntries, lazyFontList, normalizeExtraLazyFonts } from "./lazy-font-list.js";
 import { lazyFacesNeeded } from "./lazy-fonts.js";
+import { BUNDLED_FONT_MANIFEST } from "./font-manifest.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, splitStartupFaces } from "./lazy-font-list.js";
@@ -20,8 +21,8 @@ async function verifyDigest(entry, data, subtle) {
     );
 }
 
-/** Fetch only host-selected font files, then use those exact bytes for shaping and CSS. */
-export async function loadBrowserFontRegistry(entries, options = {}) {
+// The registry behind `loadFonts`: fetch only host-selected font files, then use those exact bytes for shaping and CSS.
+async function loadRegistry(entries, options = {}) {
   // Validate the host's extra faces first: a bad list must not leave startup faces registered in the document with no registry to dispose.
   const extraLazy = normalizeExtraLazyFonts(options.extraLazyFonts);
   const documentRef = options.document ?? globalThis.document;
@@ -267,3 +268,53 @@ export async function loadBrowserFontRegistry(entries, options = {}) {
     },
   });
 }
+
+const MAX_ENSURE_ROUNDS = 4;
+
+/**
+ * The fonts handle for a browser: the faces you list (`faces`, each `{ url | data, family, weight, italic, sha256 }`, fetched and
+ * hash-verified, then registered with the document) and, on demand, the script and vendored faces a deck draws. Pass it as `{ fonts }` to
+ * `renderSvg`, `renderSlideSvg`, `<opf-deck>` and the player, core `paginate` and `validate`, and the editor. `scripts`, `scriptBaseUrl`,
+ * `lazyFontsBaseUrl`, `extraLazyFonts`, `renderOptions`, `signal`, `document`, `fetch`, `crypto` and the registry options
+ * (`substitutionPolicy`, `aliases`, `fallbackFamily`, `themeFonts`, `strictGlyphs`) are as for the registry (see `fonts-browser.d.ts`).
+ * `dispose()` removes every face from the document.
+ */
+export async function loadFonts({ faces = [], ...options } = {}) {
+  const registry = await loadRegistry(faces, options);
+  // The embedded list is base64 of every eager face: compute it once, and again only when faces were added.
+  let embedded, stale = true;
+  const addFaces = registry.addFaces;
+  registry.addFaces = (added) => { const result = addFaces(added); stale = true; return result; };
+  const pending = (presentation, renderOptions) => [
+    ...registry.pendingLazyFonts(presentation, renderOptions).map((face) => face.file),
+    ...registry.pendingScripts(presentation, renderOptions),
+  ];
+  return {
+    textMeasurement: registry.textMeasurement,
+    get embeddedFonts() { if (stale) { embedded = registry.embeddedFonts; stale = false; } return embedded; },
+    registry,
+    manifest: BUNDLED_FONT_MANIFEST,
+    get substitutions() { return registry.substitutions; },
+    /**
+     * Load the vendored and script faces the presentation draws, each hash-verified, all or nothing, and repeat while loading
+     * changes what is needed (a script face can need a vendored one). Cheap when nothing is needed. Besides `signal`, the call
+     * takes the `renderSvg` options the document resolves with (`catalogs`, ...) over the loader's `renderOptions`. A document that
+     * does not resolve rejects with what `renderSvg` throws for it. After `dispose()` it rejects with `font-registry-disposed`.
+     */
+    async ensure(presentation, callOptions = {}) {
+      const lazy = [], scripts = [];
+      let uncovered = [];
+      for (let round = 0; round < MAX_ENSURE_ROUNDS; round++) {
+        const needLazy = registry.pendingLazyFonts(presentation, callOptions).length > 0, needScripts = registry.pendingScripts(presentation, callOptions).length > 0;
+        if (!needLazy && !needScripts) break;
+        callOptions.signal?.throwIfAborted?.();
+        if (needLazy) lazy.push(...(await registry.ensureLazyFonts(presentation, callOptions)));
+        if (needScripts) { const result = await registry.ensureScripts(presentation, callOptions); scripts.push(...result.loaded); uncovered = result.uncovered; }
+      }
+      return { scripts, lazy, uncovered };
+    },
+    /** Synchronous: the files and script packages `ensure` would fetch. Empty means a render can start now. Throws what `renderSvg` throws for a document that does not resolve. */
+    pending,
+    dispose: () => registry.dispose(),
+  };
+}

package/dist/fonts-node.d.ts

@@ -1,4 +1,4 @@
-import type {FontRegistry,FontRegistryOptions,EmbeddedFont,FontFaceInput,ScriptFontProfile} from "./fonts.js";
+import type {FontRegistry,FontRegistryOptions,FontFaceInput,FontsHandle,EnsureResult,ScriptFontProfile} from "./fonts.js";
 import type {RenderSvgOptions} from "./svg.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});
@@ -39,10 +39,6 @@ export interface ScriptPackOptions {
 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; /** Set on a host's extra lazy face (`extraLazyFonts`, `package: "host"`): where the host serves the file from. */ readonly url?: 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; /** 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;
@@ -74,15 +70,35 @@ export interface BundledFontManifest {
 }
 export declare const BUNDLED_FONT_MANIFEST: BundledFontManifest;
 export declare function scriptFontPackages(scripts: ScriptSelection): BundledFontPackage[];
-export interface PreparedNodeFonts {
-  registry: NodeFontRegistry;
-  manifest: BundledFontManifest;
-  options: {
-    textMeasurement: FontRegistry["textMeasurement"];
-    embeddedFonts: EmbeddedFont[];
-    fontFiles: string[];
-    useBundledFonts: false;
-    loadSystemFonts: false;
-  };
+/** The fonts handle of Node: the verified bundled faces (and any you supply) for layout, SVG, editor, PPTX and Node raster export. */
+export interface NodeFontsHandle extends FontsHandle {
+  readonly registry: NodeFontRegistry;
+  readonly manifest: BundledFontManifest;
+  /** Every font file the handle holds, for `svgToPng` and `svgToPdf`; includes the script faces `ensure` loaded. */
+  readonly fontFiles: string[];
+  /** The files are already in `fontFiles`, so a conversion adds no bundled faces. */
+  readonly useBundledFonts: false;
+  /** System fonts never load: the output does not depend on the machine. */
+  readonly loadSystemFonts: false;
+  /**
+   * Load the script faces the presentation's text needs that this handle does not hold (what `scripts: "auto"` does at load, for another
+   * presentation), including the CJK face a glyph fallback needs. Cheap when nothing is missing; `embeddedFonts` and `fontFiles` then include
+   * the new faces. A package that is not installed or a script no pinned font serves is reported once through `onDiagnostic`.
+   * Resolves with the packages this call added (`scripts`; `lazy` is empty: Node loads every vendored face with its pack).
+   */
+  ensure(presentation: unknown, options?: { onDiagnostic?: ScriptPackOptions["onDiagnostic"]; renderOptions?: Partial<RenderSvgOptions> }): Promise<EnsureResult>;
+  /** Synchronous: the script packages the presentation needs that are not loaded yet. */
+  pending(presentation: unknown, renderOptions?: Partial<RenderSvgOptions>): string[];
+}
+export interface LoadFontsOptions extends FontRegistryOptions, ScriptPackOptions {
+  /** `base` (default): the bundled Roboto faces. `office`: the metric and visual substitutes for the Office families plus the open families font schemes select. `none`: only the `faces` you supply. */
+  pack?: "base" | "office" | "none";
+  /** With pack "office": add the base Roboto faces too; default true. */
+  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;
 }
-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>;
+/** Load verified, bundled, openly licensed fonts: no system font discovery, no network. Pass the handle as `{ fonts }` to every deck-level function. */
+export declare function loadFonts(options?: LoadFontsOptions): Promise<NodeFontsHandle>;

package/dist/fonts-node.js

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { createFontRegistry, OPFFontError } from "./fonts.js";
+import { createFontRegistry, OPFFontError } from "./font-registry.js";
 import { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
 import { lazyFontList } from "./lazy-font-list.js";
 export { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
@@ -106,7 +106,7 @@ async function withScripts(loaded, scripts, {presentation, onDiagnostic, renderO
 async function completeFallback(registry, presentation, loaded, onDiagnostic, renderOptions) {
   const selection = loaded.selection;
   if (!selection) return;
-  const seen = new Set([...selection.packages, ...selection.notInstalled]);
+  const seen = new Set([...(loaded.packages ?? []), ...selection.packages, ...selection.notInstalled]);
   for (;;) {
     const analysis = analyzePresentationScripts(presentation, undefined, renderOptions), covers = character => registry.scriptFacesCover(character);
     const next = nextFallbackPackage(analysis, {covers, loaded: seen});
@@ -124,6 +124,7 @@ async function completeFallback(registry, presentation, loaded, onDiagnostic, re
     }
     registry.addFaces(embedUsed(extra.entries));
     loaded.fontFiles.push(...extra.fontFiles);
+    loaded.packages?.push(next.name);
     selection.packages.push(next.name);
   }
 }
@@ -152,63 +153,122 @@ async function withFaces(loaded, faces) {
   return {...loaded, entries:[...own.entries, ...loaded.entries], fontFiles:[...own.fontFiles, ...loaded.fontFiles]};
 }
 
-/** Bundled, openly licensed faces. No system font discovery or network requests. */
-export async function loadBundledFontRegistry({scripts, faces, presentation, onDiagnostic, renderOptions, ...options} = {}) {
-  const {entries, fontFiles, selection} = await withFaces(await withScripts(await loadPack("base"), scripts, {presentation, onDiagnostic, renderOptions}), faces);
-  const registry = Object.assign(createFontRegistry(entries,options),{fontFiles, ...(selection ? {scriptSelection: selection} : {})});
+/**
+ * Build the registry of a pack: `base` (the bundled Roboto faces), `office` (the metric and visual substitutes for the Office
+ * families plus the open families font schemes select, FF-31, optionally alongside the base) or `none` (only the caller's
+ * `faces`). Returns the live registry and what was loaded (`entries`, `fontFiles`, `packages`, `selection`), which `ensure` extends.
+ */
+async function buildRegistry(pack, {scripts, faces, presentation, onDiagnostic, renderOptions, ...options}) {
+  let loaded, registryOptions = options;
+  if (pack === "office") {
+    const {entries, fontFiles, packages} = await loadPack("office");
+    for (const [include, name] of [[options.includeOpenFonts, "open"], [options.includeBaseFonts, "base"]]) {
+      if (include === false) continue;
+      const extra = await loadPack(name);
+      fontFiles.push(...extra.fontFiles);
+      entries.push(...extra.entries);
+      packages.push(...extra.packages);
+    }
+    // Noto Sans (regular, bold, italic, bold italic) is the default Latin, Cyrillic and Greek fallback face
+    // (glyph fallback), so Georgia with Russian text previews without the scripts option. It is embedded in an
+    // SVG only when the slide's text draws it (embed "used"); raster output reads it from fontFiles. Unless the
+    // caller asked for it with scripts it is fallback-only, so no other family's preview changes. "auto" counts as asking for it when the
+    // presentation itself selects Latn (a Sylfaen scheme: Noto Sans is its designated replacement, which a fallback-only face never is), as
+    // an explicit list does; a presentation that does not select Latn keeps it fallback-only.
+    const requested = scripts === "auto" && presentation !== null && typeof presentation === "object" ? scriptFontPackages(autoScriptSelection(presentation, renderOptions).scripts).map(pkg => pkg.name)
+      : scripts === undefined || scripts === "auto" || (Array.isArray(scripts) && !scripts.length) ? [] : scriptFontPackages(scripts).map(pkg => pkg.name);
+    const fallback = await loadPackages(scriptFontPackages(["Latn"]).filter(pkg => !requested.includes(pkg.name)), undefined, {fallbackOnly:true});
+    fontFiles.push(...fallback.fontFiles);
+    entries.push(...fallback.entries);
+    packages.push(...fallback.packages);
+    loaded = await withFaces(await withScripts({entries, fontFiles, packages}, scripts, {presentation, onDiagnostic, renderOptions}), faces);
+    // A package that is the renamed successor of a family answers to the old name through a built-in alias.
+    const aliases = options.includeOpenFonts === false ? options.aliases : {...renamedAliases(), ...options.aliases};
+    registryOptions = {substitutionPolicy:"metric", ...options, ...(aliases ? {aliases} : {})};
+  } else {
+    loaded = await withFaces(await withScripts(pack === "none" ? {entries:[], fontFiles:[], packages:[]} : await loadPack("base"), scripts, {presentation, onDiagnostic, renderOptions}), faces);
+  }
+  loaded.packages ??= [];
+  const registry = Object.assign(createFontRegistry(loaded.entries, registryOptions), {fontFiles: loaded.fontFiles, ...(loaded.selection ? {scriptSelection: loaded.selection} : {})});
   registry.lazyFonts = lazyOf(registry);
-  await completeFallback(registry, presentation, {fontFiles, selection}, onDiagnostic, renderOptions);
-  return registry;
+  await completeFallback(registry, presentation, loaded, onDiagnostic, renderOptions);
+  return {registry, loaded};
 }
 
-/** Office substitutes plus the open families that font schemes select (FF-31),
- * optionally alongside the base Roboto pack. `includeOpenFonts: false` leaves the open families out. */
-export async function loadOfficeFontRegistry({scripts, faces, presentation, onDiagnostic, renderOptions, ...options} = {}) {
-  const {entries, fontFiles, packages} = await loadPack("office");
-  for (const [include, pack] of [[options.includeOpenFonts, "open"], [options.includeBaseFonts, "base"]]) {
-    if (include === false) continue;
-    const extra = await loadPack(pack);
-    fontFiles.push(...extra.fontFiles);
-    entries.push(...extra.entries);
-    packages.push(...extra.packages);
+/**
+ * Load the faces a text needs that this handle does not hold yet: what `scripts: "auto"` does at load, run again for another
+ * presentation (an edit that adds a script, another deck on the same handle). Cheap when nothing is needed. A package that is not
+ * installed, or a script no pinned font serves, is reported once through `onDiagnostic`. Resolves with the script packages this
+ * call added (`scripts`; `lazy` is always empty here: Node loads every vendored face with its pack) and the drawn CJK
+ * characters no loaded face covers.
+ */
+async function ensureFonts(registry, loaded, presentation, {onDiagnostic, renderOptions} = {}) {
+  if (presentation === null || typeof presentation !== "object") throw new OPFFontError("invalid-font-scripts", "ensure needs the presentation whose text decides the scripts.");
+  const selection = (loaded.selection ??= {detected: [], scripts: [], unavailable: [], packages: [], notInstalled: []});
+  registry.scriptSelection = selection;
+  const before = loaded.packages.length;
+  const wanted = scriptSelectionOf(analyzePresentationScripts(presentation, undefined, renderOptions));
+  const held = new Set([...loaded.packages, ...selection.notInstalled]);
+  const skipped = [];
+  const extra = await loadPackages(scriptFontPackages(wanted.scripts).filter(pkg => !held.has(pkg.name)), skipped);
+  if (extra.entries.length) registry.addFaces(embedUsed(extra.entries));
+  loaded.fontFiles.push(...extra.fontFiles);
+  loaded.packages.push(...extra.packages);
+  selection.packages.push(...extra.packages);
+  for (const item of skipped) {
+    selection.notInstalled.push(item.package);
+    onDiagnostic?.({code: "script-font-not-installed", package: item.package, scripts: item.scripts, message: `Install ${item.package}@${item.version} to preview ${item.scripts.join(", ")} text with its designated open font.`});
+  }
+  for (const script of wanted.unavailable) if (!selection.unavailable.includes(script)) {
+    selection.unavailable.push(script);
+    onDiagnostic?.({code: "script-font-unavailable", script, message: `No pinned open font serves script '${script}'; that text uses the design font.`});
   }
-  // Noto Sans (regular, bold, italic, bold italic) is the default Latin, Cyrillic and Greek fallback face
-  // (glyph fallback), so Georgia with Russian text previews without the scripts option. It is embedded in an
-  // SVG only when the slide's text draws it (embed "used"); raster output reads it from fontFiles. Unless the
-  // caller asked for it with scripts it is fallback-only, so no other family's preview changes. "auto" counts as asking for it when the
-  // presentation itself selects Latn (a Sylfaen scheme: Noto Sans is its designated replacement, which a fallback-only face never is), as
-  // an explicit list does; a presentation that does not select Latn keeps it fallback-only.
-  const requested = scripts === "auto" && presentation !== null && typeof presentation === "object" ? scriptFontPackages(autoScriptSelection(presentation, renderOptions).scripts).map(pkg => pkg.name)
-    : scripts === undefined || scripts === "auto" || (Array.isArray(scripts) && !scripts.length) ? [] : scriptFontPackages(scripts).map(pkg => pkg.name);
-  const fallback = await loadPackages(scriptFontPackages(["Latn"]).filter(pkg => !requested.includes(pkg.name)), undefined, {fallbackOnly:true});
-  fontFiles.push(...fallback.fontFiles);
-  entries.push(...fallback.entries);
-  packages.push(...fallback.packages);
-  const loaded = await withFaces(await withScripts({entries, fontFiles, packages}, scripts, {presentation, onDiagnostic, renderOptions}), faces);
-  const aliases = options.includeOpenFonts === false ? options.aliases : {...renamedAliases(), ...options.aliases};
-  const registry = Object.assign(createFontRegistry(loaded.entries,{substitutionPolicy:"metric",...options,...(aliases?{aliases}:{})}),{fontFiles:loaded.fontFiles, ...(loaded.selection ? {scriptSelection: loaded.selection} : {})});
-  registry.lazyFonts = lazyOf(registry);
   await completeFallback(registry, presentation, loaded, onDiagnostic, renderOptions);
-  return registry;
+  return {scripts: loaded.packages.slice(before), lazy: [], uncovered: selection.uncovered ? [...selection.uncovered] : []};
 }
 
-/** One set of verified font inputs for layout, SVG, editor, PPTX, and Node raster export. */
-export async function prepareNodeFonts({pack = "base", embedScriptFonts = false, ...options} = {}) {
-  if (pack !== "base" && pack !== "office") throw new OPFFontError("invalid-font-pack", "Choose the base or office font pack.", {pack});
-  const registry = await (pack === "base" ? loadBundledFontRegistry(options) : loadOfficeFontRegistry(options));
-  // Script faces are large (CJK faces are 5-10 MB each). Raster output reads them
-  // from fontFiles; embed them in standalone SVG only on request. The default Noto Sans fallback is always offered
-  // (embed "used"), so an SVG carries it exactly when its text draws it.
-  const embeddedFonts = registry.selectEmbeddedFonts(face => embedScriptFonts || !face.scripts || face.fallbackOnly);
+/**
+ * The fonts handle: one set of verified font inputs for layout, SVG, editor, PPTX and Node raster export. Pass it as `{ fonts }` to
+ * `renderSvg`, `renderSlideSvg`, `svgToPng`, `svgToPdf`, core `paginate` and `validate`, and `toPptx`.
+ *
+ * Bundled, openly licensed faces only: no system font discovery and no network requests. `pack`: `base` (default, Roboto),
+ * `office` (the Office substitutes and the open families) or `none` (only the `faces` you supply). Everything else
+ * (`substitutionPolicy`, `aliases`, `fallbackFamily`, `themeFonts`, `strictGlyphs`, `includeBaseFonts`, `includeOpenFonts`,
+ * `faces`, `scripts`, `presentation`, `onDiagnostic`, `renderOptions`) goes to the registry. `embedScriptFonts` embeds the large script
+ * faces in standalone SVG (default false: raster output reads them from `fontFiles`).
+ */
+export async function loadFonts({pack = "base", embedScriptFonts = false, ...options} = {}) {
+  if (pack !== "base" && pack !== "office" && pack !== "none") throw new OPFFontError("invalid-font-pack", "Choose the base, office or none font pack.", {pack});
+  const {registry, loaded} = await buildRegistry(pack, options);
+  // Script faces are large (CJK faces are 5-10 MB each). Raster output reads them from fontFiles; embed them in standalone SVG only
+  // on request. The default Noto Sans fallback is always offered (embed "used"), so an SVG carries it exactly when its text draws it.
+  const selectEmbedded = () => registry.selectEmbeddedFonts(face => embedScriptFonts || !face.scripts || face.fallbackOnly);
+  // The embedded list is base64 of every face: computed on first use, and again after `ensure` added faces.
+  let embeddedFonts, fontFiles = [...registry.fontFiles];
+  const refresh = () => { embeddedFonts = undefined; fontFiles = [...registry.fontFiles]; };
   return {
+    textMeasurement: registry.textMeasurement,
+    get embeddedFonts() { return (embeddedFonts ??= selectEmbedded()); },
+    get fontFiles() { return fontFiles; },
+    useBundledFonts: false,
+    loadSystemFonts: false,
     registry,
-    manifest:BUNDLED_FONT_MANIFEST,
-    options:{
-      textMeasurement:registry.textMeasurement,
-      embeddedFonts,
-      fontFiles:[...registry.fontFiles],
-      useBundledFonts:false,
-      loadSystemFonts:false,
+    manifest: BUNDLED_FONT_MANIFEST,
+    get substitutions() { return registry.substitutions; },
+    /** Load the script faces the presentation's text needs (see `ensureFonts`); `embeddedFonts` and `fontFiles` then include them. */
+    async ensure(presentation, callOptions = {}) {
+      const result = await ensureFonts(registry, loaded, presentation, {onDiagnostic: callOptions.onDiagnostic ?? options.onDiagnostic, renderOptions: {...options.renderOptions, ...callOptions.renderOptions}});
+      refresh();
+      return result;
+    },
+    /** Synchronous: the script packages the presentation needs that are not loaded yet. Empty means `ensure` loads nothing. */
+    pending(presentation, renderOptions) {
+      const held = new Set([...loaded.packages, ...(loaded.selection?.notInstalled ?? [])]);
+      const analysis = analyzePresentationScripts(presentation, undefined, {...options.renderOptions, ...renderOptions});
+      const primary = scriptFontPackages(scriptSelectionOf(analysis).scripts).map(pkg => pkg.name).filter(name => !held.has(name));
+      if (primary.length) return primary;
+      const next = nextFallbackPackage(analysis, {covers: character => registry.scriptFacesCover(character), loaded: held});
+      return next ? [next.name] : [];
     },
   };
 }

package/dist/fonts.d.ts

@@ -1,4 +1,13 @@
-import type { TextMeasurement, TextStyle } from "@openpresentation/opf/composition";
+import type { TextMeasurement, TextStyle, ScriptRole } from "@openpresentation/opf/composition";
+import type { FontPolicyEntry } from "@openpresentation/opf/font-policy";
+import type { LazyFont } from "./fonts-node.js";
+// Core owns these: the font policy table and lookup, the symbol-font code rules and the script slot of a script. They are core's own
+// exports (the same objects), not copies.
+export { FONT_POLICY, fontPolicyFor } from "@openpresentation/opf/font-policy";
+export type { FontPolicyEntry } from "@openpresentation/opf/font-policy";
+export { isSymbolEncodedFamily, mapSymbolText, symbolCodeOf } from "@openpresentation/opf/symbol-font-encodings";
+export { scriptFontRole } from "@openpresentation/opf/composition";
+export type { ScriptRole } from "@openpresentation/opf/composition";
 export interface FontFaceInput { data: Uint8Array; family?: string; weight?: number; italic?: boolean; postscriptName?: string; license?: string; /** Serves glyph fallback and requests by its own family only; never a replacement for another family. */ fallbackOnly?: boolean; /** "used" embeds the face in an SVG only when the slide's text names its family (the open pack, FF-31). Default "always". */ embed?: "always" | "used"; /** ISO 15924 scripts a designated script replacement face serves (FF-19). */ scripts?: string[] }
 export interface EmbeddedFont { family: string; weight: number; italic?: boolean; dataUrl: string; license?: string; embed?: "used" }
 export type FontCompatibility = "exact" | "metric" | "visual" | "generic";
@@ -17,18 +26,6 @@ export interface FontResolution {
   measured?:FontReplacementMeasurement;
   licenseClass?:FontPolicyEntry['licenseClass']; availability?:FontPolicyEntry['availability'];
 }
-/** One OPF font policy row (snapshot of opf spec/reference/font-policy.json, decisions applied). */
-export interface FontPolicyEntry {
-  family:string; licenseClass:"open"|"proprietary-standard"|"proprietary-nonstandard"; license:string;
-  availability:("windows"|"windows-optional"|"macos"|"office"|"office-cloud")[]; embeddableByOpf:boolean;
-  replacement:{family:string; compatibility:"metric"|"visual"; decision?:string; metricModeFallback?:true; weight?:number; measured:FontReplacementMeasurement|null; source?:string}|null;
-  alternates?:string[];
-}
-export declare const FONT_POLICY: readonly Readonly<FontPolicyEntry>[];
-export declare const FONT_POLICY_SOURCE: Readonly<{version:number; path:string; sha256:string}>;
-/** Provisional owner decisions applied to the snapshot (owner may revise). */
-export declare const FONT_POLICY_DECISIONS: Readonly<Record<string, unknown>>;
-export declare function fontPolicyFor(family:string): Readonly<FontPolicyEntry>|undefined;
 export interface FontRegistryOptions {
   aliases?: Record<string,string>; fallbackFamily?: string; strictGlyphs?: boolean;
   substitutionPolicy?: "none" | "metric" | "visual";
@@ -36,6 +33,42 @@ export interface FontRegistryOptions {
 }
 export declare const FONT_COMPATIBILITY: readonly Readonly<{requestedFamily:string;substitutes:readonly string[];compatibility:"metric"|"visual";weights?:readonly number[];weight?:number;source?:string;measured?:FontReplacementMeasurement;decision?:string;metricModeFallback?:true;licenseClass?:FontPolicyEntry['licenseClass'];note:string}>[];
 export declare const EXPERIMENTAL_FONT_CANDIDATES: readonly Readonly<{requestedFamily:string;substitute:string;source:string;note:string}>[];
+/**
+ * What the deck-level functions read from their `fonts` option: `renderSvg`, `renderSlideSvg` and `<opf-deck>` take the measurement and
+ * the faces to embed; `svgToPng` and `svgToPdf` (Node) take the font files; core `paginate`, `validate` and `resolveSlideContext` take the
+ * measurement. The object `loadFonts()` returns is a `FontsHandle`, which extends this; any object with these fields works.
+ */
+export interface RenderFonts {
+  /** Measures text with the real faces. Without it layout uses core's portable estimate. */
+  textMeasurement?: TextMeasurement;
+  /** Faces `renderSvg` writes into each SVG as @font-face data; a face flagged `embed: "used"` only when a slide draws its family. */
+  embeddedFonts?: readonly EmbeddedFont[];
+  /** Font files the Node raster and PDF conversions draw with. */
+  fontFiles?: readonly string[];
+  /** Whether a conversion adds the bundled base faces to `fontFiles`. Default true; a handle that already holds them says false. */
+  useBundledFonts?: boolean;
+  /** Whether the raster conversion loads system fonts. Default false (the output never depends on the machine). */
+  loadSystemFonts?: boolean;
+}
+/** What `fonts.ensure(presentation)` loaded: the script packages and vendored faces that were missing, and drawn CJK characters no face covers. */
+export interface EnsureResult { scripts: string[]; lazy: LazyFont[]; uncovered: string[] }
+/** The fonts handle `loadFonts()` returns from `/fonts-node` and `/fonts-browser`: pass it as `{ fonts }` to every deck-level function. */
+export interface FontsHandle extends RenderFonts {
+  readonly textMeasurement: FontRegistry["textMeasurement"];
+  readonly embeddedFonts: EmbeddedFont[];
+  /** The face registry behind the handle (shaping, resolution, lazy and script loading). */
+  readonly registry: FontRegistry;
+  /** The pinned manifest of the bundled font packages. */
+  readonly manifest: { readonly version: number; readonly packages: readonly object[] };
+  /** The substitutions made so far (a requested family drawn with another face), as `registry.substitutions`. */
+  readonly substitutions: FontResolution[];
+  /** Load the script (and, in a browser, vendored) faces the presentation's text needs. Cheap when nothing is missing. */
+  ensure(presentation: unknown, options?: object): Promise<EnsureResult>;
+  /** Synchronous: the files and script packages `ensure` would load. Empty means a render can start now. */
+  pending(presentation: unknown, renderOptions?: object): string[];
+  /** Remove the faces this handle added to the document (a browser handle). */
+  dispose?(): void;
+}
 export interface FaceDescription { family:string; weight:number; italic:boolean; scripts?:string[] }
 export interface FontRegistry {
   textMeasurement: TextMeasurement & {outlineBounds: NonNullable<TextMeasurement['outlineBounds']>; resolveFont(style: TextStyle): FontResolution};
@@ -46,6 +79,8 @@ export interface FontRegistry {
   selectEmbeddedFonts(predicate: (face: FaceDescription) => boolean): EmbeddedFont[];
   /** Parsed face metadata in entry order, without encoding font bytes. */
   describeFaces(): FaceDescription[];
+  /** Every face as `{ family, data }`, the bytes the registry measures with. */
+  exportFaces(): { family: string; data: Uint8Array }[];
   readonly substitutions: FontResolution[];
   /** True when a loaded script-pack face has a glyph for the character. */
   scriptFacesCover(character: string): boolean;
@@ -53,10 +88,7 @@ export interface FontRegistry {
   addFaces(entries: FontFaceInput[]): { family: string; weight: number; italic: boolean; scripts?: string[] }[];
 }
 export declare class OPFFontError extends Error { code:string; details:Record<string,unknown>; constructor(code:string,message:string,details?:Record<string,unknown>) }
-export declare function createFontRegistry(entries: FontFaceInput[], options?: FontRegistryOptions): FontRegistry;
 
-/** OOXML script slot. */
-export type ScriptRole = "latin" | "eastAsian" | "complexScript";
 export interface ScriptFontSlots { latin: string; eastAsian: string; complexScript: string }
 /** Core `resolveScriptFonts` output, or the same shape. `serif` prefers serif replacements. */
 export interface ScriptFontProfile {
@@ -81,7 +113,6 @@ export interface ScriptFonts {
 export declare const SCRIPT_FONT_FAMILIES: Readonly<Record<string, Readonly<{ sans?: string; serif?: string }>>>;
 export declare const SCRIPT_FONT_REPLACEMENTS: readonly Readonly<{requestedFamily:string;script:string;substitutes:readonly string[];compatibility:"visual";note:string}>[];
 export declare function scriptOfCharacter(character: string): string;
-export declare function scriptFontRole(script: string): ScriptRole;
 export declare function itemizeScripts(text: string, profile?: ScriptFontProfile): ScriptRun[];
 /** Script keys in the strings of a JSON value. The profile's own script counts unless `includeLanguage` is false; `ignoreKeys` are not visited. */
 export declare function detectScripts(value: unknown, profile?: ScriptFontProfile, options?: { includeLanguage?: boolean; ignoreKeys?: readonly string[] }): string[];
@@ -107,17 +138,7 @@ export declare const SYMBOL_PLACEHOLDER: string;
 export declare const SYMBOL_PREVIEW_FACES: Readonly<Record<SymbolFontFamily, readonly string[]>>;
 /** Every open face a symbol preview may draw with. */
 export declare const SYMBOL_FACE_FAMILIES: readonly string[];
-/** Per family: the verified font version and, for codes 0x20..0xFF in order, `[unicode, advance, reason?]` (hex code points joined with '+', font units). */
-export declare const SYMBOL_ENCODINGS: readonly Readonly<{ family: SymbolFontFamily; version: string; unitsPerEm: number; mapped: number; codes: readonly (readonly [string | null, number | null, string?])[] }>[];
-/** Which core table (spec/reference/symbol-font-encodings.json) the snapshot came from. */
-export declare const SYMBOL_ENCODINGS_SOURCE: Readonly<{ version: number; path: string; sha256: string }>;
-export declare function isSymbolEncodedFamily(family: string): boolean;
-export declare function symbolEncodingFor(family: string): (typeof SYMBOL_ENCODINGS)[number] | undefined;
 export declare function symbolPreviewFaces(family: string): readonly string[];
-/** The symbol code (0x20..0xFF) of one character: a private-use U+F0xx, an ASCII or Latin-1 character, or a Windows-1252 character at 0x80..0x9F; null for anything else. */
-export declare function symbolCodeOf(character: string): number | null;
-/** Normalise text in a symbol-encoded family: per character its code (null when not a code), the Unicode equivalent to draw (or null with a reason) and the verified font's advance in em. */
-export declare function mapSymbolText(family: string, text: string): { source: string; code: number | null; unicode: string | null; advance: number | null; reason?: string }[];
 /** Wrap a measurement so pagination, the renderer and the editor itemize script runs identically. */
 export declare function createScriptTextMeasurement(measurement: TextMeasurement, profile: ScriptFontProfile, options?: ScriptFontsOptions): TextMeasurement;
 export declare function openTypeLanguage(tag: string | undefined): string | undefined;