@openpresentation/opf-render 0.10.0 → 0.11.1

package/dist/fonts-node.js

@@ -1,12 +1,16 @@
 import { readFile } from "node:fs/promises";
 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 { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
+import { lazyFontList } from "./lazy-font-list.js";
 export { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
-import { scriptFontPackages } from "./script-font-pack.js";
-export { scriptFontPackages } from "./script-font-pack.js";
+import { analyzePresentationScripts, nextFallbackPackage, scriptFontPackages, scriptSelectionOf, uncoveredCjkCharacters } from "./script-font-pack.js";
+export { autoScriptSelection, detectPresentationScripts, scriptFontPackages } from "./script-font-pack.js";
+// Script faces are embedded in a standalone SVG only when the slide's text uses their family.
+const embedUsed = entries => entries.map(entry => ({...entry, embed: "used"}));
 const require = createRequire(import.meta.url);
 
 async function verifiedFile(file, expected, details) {
@@ -18,14 +22,37 @@ async function verifiedFile(file, expected, details) {
   return bytes;
 }
 
-async function loadPackages(packages) {
+// The default Latin, Cyrillic and Greek glyph-fallback face (the office pack always loads it, fallback-only).
+const FALLBACK_PACKAGE = "@expo-google-fonts/noto-sans";
+
+// `skipped`: an optional npm package that is not installed is recorded there instead of failing (scripts: 'auto').
+// `fallbackOnly`: the faces serve glyph fallback and requests by their own name, never a replacement for another family.
+async function loadPackages(packages, skipped, {fallbackOnly = false} = {}) {
   const entries = [], fontFiles = [];
   for (const pkg of packages) {
+    if (pkg.vendored) {
+      // FF-31: vendored faces ship inside this package (pkg.vendored, for example fonts/carlito), hash-pinned like the npm packs. The open pack is
+      // embedded in an SVG only when the slide's text names the family (embed "used"); raster output reads the files.
+      const directory = fileURLToPath(new URL(`../${pkg.vendored}/`, import.meta.url));
+      let license = (await verifiedFile(path.join(directory, pkg.licenseFile), pkg.licenseSha256, {package:pkg.name, file:pkg.licenseFile})).toString("utf8");
+      // A notice file carries provenance and upstream copyright lines that the upstream license file omits.
+      if (pkg.noticeFile) license += "\n\n" + (await verifiedFile(path.join(directory, pkg.noticeFile), pkg.noticeSha256, {package:pkg.name, file:pkg.noticeFile})).toString("utf8");
+      // One rule for the vendored faces the SVG embeds only when its text names them: the open pack and any package flagged embed "used" (Intos).
+      const lazy = pkg.pack === "open" || pkg.embed === "used";
+      for (const face of pkg.faces) {
+        const file = path.join(directory, face.file);
+        const data = await verifiedFile(file, face.sha256, {package:pkg.name, file:face.file});
+        fontFiles.push(file);
+        entries.push({data:new Uint8Array(data), family:face.family, weight:face.weight, italic:face.italic, license, ...(lazy ? {embed:"used"} : {})});
+      }
+      continue;
+    }
     let manifestPath, installed;
     try {
       manifestPath = require.resolve(`${pkg.name}/package.json`);
       installed = JSON.parse(await readFile(manifestPath, "utf8"));
     } catch (error) {
+      if (skipped) { skipped.push({package: pkg.name, version: pkg.version, scripts: [...pkg.scripts]}); continue; }
       throw new OPFFontError("font-resource-unavailable", `Install ${pkg.name}@${pkg.version} to use this offline font pack.`, {package:pkg.name, cause:error.code});
     }
     if (installed.version !== pkg.version) throw new OPFFontError("font-version-mismatch", `Expected ${pkg.name}@${pkg.version}; reinstall the pinned package.`, {package:pkg.name, expected:pkg.version, actual:installed.version});
@@ -35,18 +62,69 @@ async function loadPackages(packages) {
       const file = path.join(directory, face.file);
       const data = await verifiedFile(file, face.sha256, {package:pkg.name, file:face.file});
       fontFiles.push(file);
-      entries.push({data:new Uint8Array(data), family:face.family, weight:face.weight, italic:face.italic, license, ...(pkg.scripts ? {scripts:[...pkg.scripts]} : {})});
+      entries.push({data:new Uint8Array(data), family:face.family, weight:face.weight, italic:face.italic, license, ...(pkg.scripts ? {scripts:[...pkg.scripts]} : {}), ...(fallbackOnly ? {fallbackOnly:true, embed:"used"} : {})});
     }
   }
-  return {entries, fontFiles};
+  return {entries, fontFiles, packages:packages.map(pkg => pkg.name)};
 }
 
+// A package that is the renamed successor of a family (Source Sans 3, formerly Source Sans Pro) answers to the
+// old name through a built-in alias, reported visual like other aliases; it is not a claim of the old face.
+const renamedAliases = () => Object.fromEntries(BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === "open" && item.renamedFrom).map(item => [item.renamedFrom, item.faces[0].family]));
+// The vendored faces this registry holds that are embed "used": a host that serves fonts itself lists them to copy their files.
+const lazyOf = registry => lazyFontList().filter(face => registry.describeFaces().some(held => held.family === face.family && held.weight === face.weight && held.italic === face.italic));
 const loadPack = pack => loadPackages(BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === pack));
 
-async function withScripts(loaded, scripts) {
+/**
+ * Adds the script pack. `scripts` is 'all', ISO 15924 codes, or 'auto' (FF-19): detect the scripts the
+ * `presentation` draws and load only their faces. Auto never fails on a missing optional package or a
+ * script no pinned font serves; it reports them through `onDiagnostic` and `selection`.
+ */
+async function withScripts(loaded, scripts, {presentation, onDiagnostic} = {}) {
   if (scripts === undefined || (Array.isArray(scripts) && !scripts.length)) return loaded;
-  const extra = await loadPackages(scriptFontPackages(scripts));
-  return {entries:[...loaded.entries, ...extra.entries], fontFiles:[...loaded.fontFiles, ...extra.fontFiles]};
+  // A package the registry already loaded (the default Noto Sans fallback) is never loaded twice.
+  const notLoaded = list => list.filter(pkg => !loaded.packages?.includes(pkg.name));
+  if (scripts !== "auto") {
+    const extra = await loadPackages(notLoaded(scriptFontPackages(scripts)));
+    return {...loaded, entries:[...loaded.entries, ...embedUsed(extra.entries)], fontFiles:[...loaded.fontFiles, ...extra.fontFiles], packages:[...(loaded.packages ?? []), ...extra.packages]};
+  }
+  if (presentation === null || typeof presentation !== "object") throw new OPFFontError("invalid-font-scripts", "scripts: 'auto' needs the presentation whose text decides the scripts.", {scripts});
+  const selection = scriptSelectionOf(analyzePresentationScripts(presentation)), skipped = [];
+  const extra = await loadPackages(notLoaded(scriptFontPackages(selection.scripts)), skipped);
+  for (const script of selection.unavailable) onDiagnostic?.({code: "script-font-unavailable", script, message: `No pinned open font serves script '${script}'; that text uses the design font.`});
+  for (const item of skipped) 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.`});
+  return {entries:[...loaded.entries, ...embedUsed(extra.entries)], fontFiles:[...loaded.fontFiles, ...extra.fontFiles], packages:[...(loaded.packages ?? []), ...extra.packages],
+    selection:{...selection, packages: scriptFontPackages(selection.scripts).map(item => item.name).filter(name => !skipped.some(item => item.package === name)), notInstalled: skipped.map(item => item.package)}};
+}
+
+/**
+ * scripts: 'auto' with glyph fallback (FF-19): a drawn Han, kana or Hangul character that no loaded script face
+ * has (Japanese-only kanji in a Simplified Chinese run, hanja) needs the next CJK face along the fallback chain.
+ * Adds those packages to the registry and its fontFiles until every such character is covered or the chain ends.
+ */
+async function completeFallback(registry, presentation, loaded, onDiagnostic) {
+  const selection = loaded.selection;
+  if (!selection) return;
+  const seen = new Set([...selection.packages, ...selection.notInstalled]);
+  for (;;) {
+    const analysis = analyzePresentationScripts(presentation), covers = character => registry.scriptFacesCover(character);
+    const next = nextFallbackPackage(analysis, {covers, loaded: seen});
+    if (!next) {
+      const uncovered = uncoveredCjkCharacters(analysis, {covers, limit: 8});
+      if (uncovered.length) { selection.uncovered = uncovered; onDiagnostic?.({code: "script-glyph-uncovered", characters: uncovered, message: `No loaded script face has ${uncovered.map(character => "U+" + character.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")).join(", ")}; the preview reports missing-glyph for them.`}); }
+      return;
+    }
+    seen.add(next.name);
+    const skipped = [], extra = await loadPackages([next], skipped);
+    if (skipped.length) {
+      selection.notInstalled.push(next.name);
+      onDiagnostic?.({code: "script-font-not-installed", package: next.name, scripts: [...next.scripts], message: `Install ${next.name}@${next.version} for glyphs the loaded CJK faces lack.`});
+      continue;
+    }
+    registry.addFaces(embedUsed(extra.entries));
+    loaded.fontFiles.push(...extra.fontFiles);
+    selection.packages.push(next.name);
+  }
 }
 
 /** FF-31: caller-supplied faces, for example the caller's own licensed Aptos files. Plain
@@ -70,25 +148,44 @@ async function callerFaces(faces = []) {
 async function withFaces(loaded, faces) {
   if (!faces?.length) return loaded;
   const own = await callerFaces(faces);
-  return {entries:[...own.entries, ...loaded.entries], fontFiles:[...own.fontFiles, ...loaded.fontFiles]};
+  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, ...options} = {}) {
-  const {entries, fontFiles} = await withFaces(await withScripts(await loadPack("base"), scripts), faces);
-  return Object.assign(createFontRegistry(entries,options),{fontFiles});
+export async function loadBundledFontRegistry({scripts, faces, presentation, onDiagnostic, ...options} = {}) {
+  const {entries, fontFiles, selection} = await withFaces(await withScripts(await loadPack("base"), scripts, {presentation, onDiagnostic}), faces);
+  const registry = Object.assign(createFontRegistry(entries,options),{fontFiles, ...(selection ? {scriptSelection: selection} : {})});
+  registry.lazyFonts = lazyOf(registry);
+  await completeFallback(registry, presentation, {fontFiles, selection}, onDiagnostic);
+  return registry;
 }
 
-/** Six pinned open-source Office substitutes, optionally alongside the base Roboto pack. */
-export async function loadOfficeFontRegistry({scripts, faces, ...options} = {}) {
-  const {entries, fontFiles} = await loadPack("office");
-  if (options.includeBaseFonts !== false) {
-    const base = await loadPack("base");
-    fontFiles.push(...base.fontFiles);
-    entries.push(...base.entries);
+/** 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, ...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);
   }
-  const loaded = await withFaces(await withScripts({entries, fontFiles}, scripts), faces);
-  return Object.assign(createFontRegistry(loaded.entries,{substitutionPolicy:"metric",...options}),{fontFiles:loaded.fontFiles});
+  // 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.
+  const requested = 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}), 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);
+  return registry;
 }
 
 /** One set of verified font inputs for layout, SVG, editor, PPTX, and Node raster export. */
@@ -96,8 +193,9 @@ export async function prepareNodeFonts({pack = "base", embedScriptFonts = false,
   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.
-  const embeddedFonts = registry.selectEmbeddedFonts(face => embedScriptFonts || !face.scripts);
+  // 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);
   return {
     registry,
     manifest:BUNDLED_FONT_MANIFEST,

package/dist/fonts.d.ts

@@ -1,6 +1,6 @@
 import type { TextMeasurement, TextStyle } from "@openpresentation/opf/composition";
-export interface FontFaceInput { data: Uint8Array; family?: string; weight?: number; italic?: boolean; postscriptName?: string; license?: string; /** 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 }
+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";
 export interface FontReplacementMeasurement { replacement:string; meanAbsWidthDelta:number; meanWidthDelta:number; maxAbsWidthDelta:number; styles:number; reference:string }
 export interface FontResolution {
@@ -47,6 +47,10 @@ export interface FontRegistry {
   /** Parsed face metadata in entry order, without encoding font bytes. */
   describeFaces(): FaceDescription[];
   readonly substitutions: FontResolution[];
+  /** True when a loaded script-pack face has a glyph for the character. */
+  scriptFacesCover(character: string): boolean;
+  /** Register more faces (FF-19 script faces once a document needs them). Atomic; returns the added faces' metadata. */
+  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;
@@ -66,6 +70,8 @@ export interface PlannedRun { text: string; family: string; own: boolean; stack?
 export interface ScriptFonts {
   readonly profile: ScriptFontProfile;
   readonly rtl: boolean;
+  /** Glyph fallback notes recorded so far. */
+  readonly fallbacks: readonly GlyphFallbackNote[];
   /** Font runs for text drawn in a resolved latin style. */
   plan(text: string, style: TextStyle): PlannedRun[];
   runWidths(runs: PlannedRun[], size: number, style: TextStyle): number[] | undefined;
@@ -77,12 +83,21 @@ export declare const SCRIPT_FONT_REPLACEMENTS: readonly Readonly<{requestedFamil
 export declare function scriptOfCharacter(character: string): string;
 export declare function scriptFontRole(script: string): ScriptRole;
 export declare function itemizeScripts(text: string, profile?: ScriptFontProfile): ScriptRun[];
-export declare function detectScripts(value: unknown, profile?: ScriptFontProfile): string[];
+/** 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[];
 export declare function designatedFamilies(script: string, serif?: boolean): string[];
 export declare function scriptFontAliases(families: Iterable<string>): Record<string, string>;
-export declare function createScriptFonts(profile?: ScriptFontProfile, measurement?: TextMeasurement): ScriptFonts;
+export interface GlyphFallbackNote { fontFamily: string; fallbackFamily: string; scripts: string[]; characters: string[]; path?: string }
+export interface ScriptFontsOptions {
+  /** `"chain"` (default) draws and measures a character the face lacks with the first bundled face that has it; `"none"` keeps exact faces and a missing glyph raises `missing-glyph`. */
+  glyphFallback?: "chain" | "none";
+  onFallback?: (note: GlyphFallbackNote) => void;
+}
+export declare function createScriptFonts(profile?: ScriptFontProfile, measurement?: TextMeasurement, options?: ScriptFontsOptions): ScriptFonts;
+/** Designated open families a preview tries, in order, for a character its face lacks (own script, deck script, Noto Sans, other CJK, other Noto scripts). */
+export declare function glyphFallbackFamilies(character: string, profile?: ScriptFontProfile, serif?: boolean): string[];
 /** Wrap a measurement so pagination, the renderer and the editor itemize script runs identically. */
-export declare function createScriptTextMeasurement(measurement: TextMeasurement, profile: ScriptFontProfile): TextMeasurement;
+export declare function createScriptTextMeasurement(measurement: TextMeasurement, profile: ScriptFontProfile, options?: ScriptFontsOptions): TextMeasurement;
 export declare function openTypeLanguage(tag: string | undefined): string | undefined;
 /** Heading or body role of a style from its OPF path; undefined without a slide path. */
 export declare function textRole(style: { path?: string } | undefined): "heading" | "body" | undefined;

package/dist/fonts.js

@@ -1,11 +1,11 @@
 import { create } from "fontkit";
-import { FONT_COMPATIBILITY } from "./font-compatibility.js";
+import { FONT_COMPATIBILITY, disabledFeaturesFor } from "./font-compatibility.js";
 import { openTypeLanguage, scriptFontAliases } from "./script-fonts.js";
 import { fontPolicyFor } from "./font-policy.js";
 import { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
-export { FONT_COMPATIBILITY, EXPERIMENTAL_FONT_CANDIDATES } from "./font-compatibility.js";
+export { FONT_COMPATIBILITY, EXPERIMENTAL_FONT_CANDIDATES, disabledFeaturesFor } from "./font-compatibility.js";
 export { FONT_POLICY, FONT_POLICY_DECISIONS, FONT_POLICY_SOURCE, fontPolicyFor } from "./font-policy.js";
-export { SCRIPT_FONT_FAMILIES, SCRIPT_FONT_REPLACEMENTS, createScriptFonts, createScriptTextMeasurement, designatedFamilies, detectScripts, itemizeScripts, openTypeLanguage, scriptFontAliases, scriptFontRole, scriptOfCharacter, textRole } from "./script-fonts.js";
+export { SCRIPT_FONT_FAMILIES, SCRIPT_FONT_REPLACEMENTS, createScriptFonts, createScriptTextMeasurement, designatedFamilies, glyphFallbackFamilies, detectScripts, itemizeScripts, openTypeLanguage, scriptFontAliases, scriptFontRole, scriptOfCharacter, textRole } from "./script-fonts.js";
 
 export class OPFFontError extends Error {
   constructor(code, message, details = {}) { super(message); this.name = "OPFFontError"; this.code = code; this.details = details; }
@@ -20,7 +20,8 @@ function validFamily(family) {
   if (typeof family !== "string" || !family.trim() || /[\u0000-\u001f"'\\<>;]/.test(family)) throw new OPFFontError("invalid-font-family", "Font family must be a nonempty plain name.");
   return family;
 }
-const packFor = family => BUNDLED_FONT_MANIFEST.packages.find(pkg=>pkg.faces.some(face=>face.family.toLowerCase()===family.toLowerCase()))?.pack;
+// The open families load with the office pack (prepareNodeFonts({pack:"office"})).
+const packFor = family => { const pack = BUNDLED_FONT_MANIFEST.packages.find(pkg=>pkg.renamedFrom?.toLowerCase()===family.toLowerCase() || pkg.faces.some(face=>face.family.toLowerCase()===family.toLowerCase()))?.pack; return pack==="open" ? "office" : pack; };
 const percent = value => `${(value*100).toFixed(1)}%`;
 /** FF-31: say why a family has no face and what the caller can do, from the OPF font policy. */
 function unavailableFontError(family, style, policy) {
@@ -41,12 +42,12 @@ function unavailableFontError(family, style, policy) {
     return new OPFFontError("font-unavailable", `No local font face for '${family}'. ${owner} Its declared replacement ${replacement} is visual only${delta}, which substitutionPolicy '${policy}' does not allow. Pass substitutionPolicy: 'visual' to preview with ${candidates.join(" or ")}, or ${hook}. The PPTX names '${family}' either way.`, details);
   if (policy === "none")
     return new OPFFontError("font-unavailable", `No local font face for '${family}'. ${owner} Its declared ${compatibility} replacement is ${replacement}${delta}; substitutionPolicy 'none' does not allow it. Pass substitutionPolicy: '${compatibility}', or ${hook}.`, details);
-  return new OPFFontError("font-unavailable", `No local font face for '${family}'. ${owner} None of its replacements (${candidates.join(", ")}) is loaded${packs.length ? `; load the ${packs.map(pack=>"'"+pack+"'").join(" or ")} font pack` : ""}, or ${hook}.`, details);
+  return new OPFFontError("font-unavailable", `No local font face for '${family}'. ${owner} None of its replacements (${candidates.join(", ")}) is loaded${packs.length ? `; load the ${packs.map(pack=>"'"+pack+"'").join(" or ")} font pack` : ""}, or ${hook}. The PPTX names '${family}' either way.`, details);
 }
 /** Local font files only. The caller explicitly chooses aliases and fallback. */
 export function createFontRegistry(entries, options = {}) {
   if (!Array.isArray(entries) || !entries.length) throw new OPFFontError("empty-font-registry", "Supply at least one font file.");
-  const faces = entries.map(entry => {
+  const makeFace = entry => {
     if (!(entry.data instanceof Uint8Array)) throw new OPFFontError("invalid-font-data", "Font data must be a Uint8Array.");
     const data = entry.data.slice();
     let font;
@@ -68,25 +69,40 @@ export function createFontRegistry(entries, options = {}) {
     const format = signature === "OTTO" ? "otf" : signature === "wOFF" ? "woff" : signature === "wOF2" ? "woff2" : "ttf";
     // Script replacement faces (FF-19) declare the ISO 15924 scripts they serve.
     const scripts = Array.isArray(entry.scripts) && entry.scripts.length ? Object.freeze(entry.scripts.map(String)) : undefined;
-    return {family,familyGroup,fontFace,weight,italic,font,data,format,license:entry.license,scripts,cache:new Map()};
-  });
-  const duplicates = new Set();
-  for (const face of faces) {
-    const id = key(face.family,face.weight,face.italic);
-    if (duplicates.has(id)) throw new OPFFontError("duplicate-font-face", `Duplicate face: ${id}`);
-    duplicates.add(id);
-  }
-  const familySlots = new Map();
-  for (const face of faces) for (const family of new Set([face.family,face.familyGroup])) {
-    const id=key(family,face.weight,face.italic),previous=familySlots.get(id);
-    if(previous && previous!==face) throw new OPFFontError('ambiguous-font-face', `Multiple physical faces match '${family}' at weight ${face.weight}.`, {fontFamily:family,fontWeight:face.weight,italic:face.italic});
-    familySlots.set(id,face);
-  }
+    // "used": a bundled face is embedded in an SVG only when the slide's text names its family.
+    if (entry.embed !== undefined && entry.embed !== "always" && entry.embed !== "used") throw new OPFFontError("invalid-font-embed", "Font embed must be 'always' or 'used'.");
+    // A fallback-only face (the default Noto Sans) serves glyph fallback and explicit requests by its own name,
+    // but never stands in for another family, so loading it does not change what any other font previews with.
+    return {family,familyGroup,fontFace,weight,italic,font,data,format,license:entry.license,embed:entry.embed,scripts,fallbackOnly:entry.fallbackOnly===true,cache:new Map()};
+  };
+  const faces = [], duplicates = new Set(), familySlots = new Map();
+  // Adds faces atomically: every check runs before any face is registered.
+  const register = added => {
+    const ids = new Set(duplicates), slots = new Map(familySlots);
+    for (const face of added) {
+      const id = key(face.family,face.weight,face.italic);
+      if (ids.has(id)) throw new OPFFontError("duplicate-font-face", `Duplicate face: ${id}`);
+      ids.add(id);
+    }
+    for (const face of added) for (const family of new Set([face.family,face.familyGroup])) {
+      const id=key(family,face.weight,face.italic),previous=slots.get(id);
+      if(previous && previous!==face) throw new OPFFontError('ambiguous-font-face', `Multiple physical faces match '${family}' at weight ${face.weight}.`, {fontFamily:family,fontWeight:face.weight,italic:face.italic});
+      slots.set(id,face);
+    }
+    faces.push(...added);
+    for (const id of ids) duplicates.add(id);
+    for (const [id,face] of slots) familySlots.set(id,face);
+  };
+  register(entries.map(makeFace));
   const substitutions = new Map();
   // Loaded script replacement faces stand in for the proprietary script fonts
   // they replace (Meiryo -> Noto Sans JP). Caller aliases take precedence.
-  const scriptAliases = scriptFontAliases(new Set(faces.filter(face=>face.scripts).map(face=>face.family)));
-  const aliases = new Map(Object.entries({...scriptAliases,...options.aliases}).map(([from,to])=>[validFamily(from).toLowerCase(),validFamily(to)]));
+  let aliases = new Map();
+  const buildAliases = () => {
+    const scriptAliases = scriptFontAliases(new Set(faces.filter(face=>face.scripts&&!face.fallbackOnly).map(face=>face.family)));
+    aliases = new Map(Object.entries({...scriptAliases,...options.aliases}).map(([from,to])=>[validFamily(from).toLowerCase(),validFamily(to)]));
+  };
+  buildAliases();
   const policy = options.substitutionPolicy ?? "none";
   if (!["none","metric","visual"].includes(policy)) throw new OPFFontError("invalid-font-policy", "substitutionPolicy must be none, metric, or visual.");
   if (options.fallbackFamily) validFamily(options.fallbackFamily);
@@ -125,7 +141,7 @@ export function createFontRegistry(entries, options = {}) {
           const substituteTier = index===0 ? tier : "visual";
           if (substituteTier==="visual" && !(policy==="visual" || metricFallback && index===0)) continue;
           const exactWeight = substituteTier==="metric" || policy!=="visual";
-          const faces = findFamily(substitute).filter(face=>!exactWeight || face.weight===weight);
+          const faces = findFamily(substitute).filter(face=>!face.fallbackOnly && (!exactWeight || face.weight===weight));
           let available = faces.filter(face=>face.italic===!!style.italic);
           // Visual replacements without the requested style draw the other one and say so.
           if (!available.length && substituteTier==="visual" && policy==="visual" && faces.length) { available = faces.filter(face=>!face.italic); styleFallback = available.length>0; }
@@ -175,7 +191,10 @@ export function createFontRegistry(entries, options = {}) {
       }
     }
     if(value===undefined||includeOutline&&!Object.hasOwn(value,'outline')) {
-      const shape=features=>language?face.font.layout(text,features,undefined,language):features?face.font.layout(text,features):face.font.layout(text);
+      // FF-31: features a policy row turns off in its replacement (Gelasio for Georgia: liga, clig), the
+      // same ones the SVG output turns off, so measured and drawn advances agree.
+      const off=disabledFeaturesFor(face.family),policyFeatures=off&&Object.fromEntries(off.map(tag=>[tag,false]));
+      const shape=extra=>{const features=policyFeatures||extra?{...policyFeatures,...extra}:undefined;return language?face.font.layout(text,features,undefined,language):features?face.font.layout(text,features):face.font.layout(text);};
       let run;
       try { run=shape(); }
       catch (error) {
@@ -209,11 +228,28 @@ export function createFontRegistry(entries, options = {}) {
     resolveFont(style) { return resolve(style).resolution; },
     clearSubstitutions() { substitutions.clear(); },
     get substitutions() { return [...substitutions.values()]; },
-    get embeddedFonts() { return embedded(()=>true); },
+    // Faces flagged embed:"used" (the open pack, FF-31) are not in this eager list: supplied with selectEmbeddedFonts (or
+    // prepareNodeFonts().options.embeddedFonts) they are embedded only in SVGs whose text names their family.
+    get embeddedFonts() { return embedded(face=>face.embed!=="used"); },
     /** Parsed face metadata in entry order, without encoding font bytes. */
-    describeFaces: ()=>faces.map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.scripts?{scripts:[...face.scripts]}:{})})),
+    describeFaces: ()=>faces.map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.scripts?{scripts:[...face.scripts]}:{}),...(face.fallbackOnly?{fallbackOnly:true}:{})})),
     /** Embedded faces for which `predicate({family,weight,italic,scripts})` holds; large script faces can be left to raster fontFiles. */
     selectEmbeddedFonts: predicate=>embedded(predicate),
+    /** True when a loaded script-pack face has a glyph for the character (FF-19 glyph fallback planning). */
+    scriptFacesCover: character => faces.some(face => face.scripts && face.font.hasGlyphForCodePoint(character.codePointAt(0))),
+    /**
+     * Register more faces in this registry (FF-19: script faces are added once a document needs
+     * them). Atomic: on an error no face is added. Returns the added faces' metadata. Text
+     * measurements planned before the call may not know the new faces; plan again afterwards.
+     */
+    addFaces(added) {
+      if (!Array.isArray(added)) throw new OPFFontError("invalid-font-data", "addFaces requires an array of font entries.");
+      const made = added.map(makeFace);
+      register(made);
+      buildAliases();
+      substitutions.clear();
+      return made.map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.scripts?{scripts:[...face.scripts]}:{})}));
+    },
   };
-  function embedded(predicate) { return faces.filter(face=>predicate({family:face.family,weight:face.weight,italic:face.italic,scripts:face.scripts})).map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.license ? {license:face.license} : {}),dataUrl:`data:font/${face.format};base64,${base64(face.data)}`})); }
+  function embedded(predicate) { return faces.filter(face=>predicate({family:face.family,weight:face.weight,italic:face.italic,scripts:face.scripts,embed:face.embed,fallbackOnly:face.fallbackOnly})).map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.license ? {license:face.license} : {}),...(face.embed==="used" ? {embed:"used"} : {}),dataUrl:`data:font/${face.format};base64,${base64(face.data)}`})); }
 }

package/dist/index.d.ts

@@ -32,6 +32,15 @@ export declare const engineDefaults: Readonly<{
 }>;
 
 export type RenderDiagnostic = LayoutDiagnostic | {
+  /** A face lacked glyphs for the text; a bundled fallback face draws them in the preview. A note, not an error. */
+  code: "font-glyph-fallback";
+  path?: string;
+  message: string;
+  fontFamily: string;
+  fallbackFamily: string;
+  scripts: string[];
+  characters: string[];
+} | {
   code: "unsupported-pattern" | "date-needs-value" | "language-preview-unavailable" | "language-preview-unresolved" | "paragraph-direction-unavailable";
   path: string;
   message: string;
@@ -55,6 +64,8 @@ export type RenderDiagnostic = LayoutDiagnostic | {
 
 export interface RenderSvgOptions {
   textMeasurement?: TextMeasurement;
+  /** `"chain"` (default): a character the resolved face lacks is drawn with the first bundled face that has it, and reported as `font-glyph-fallback`. `"none"`: exact faces, a missing glyph raises `missing-glyph`. */
+  glyphFallback?: "chain" | "none";
   /** Unscaled reference-pixel clearance around supplied vector text outlines; default 1. */
   textRasterPadding?: number;
   embeddedFonts?: EmbeddedFont[];

package/dist/lazy-font-list.js

@@ -0,0 +1,23 @@
+import { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
+import { OPFFontError } from "./fonts.js";
+
+// FF-31: the vendored faces (the open families and Intos) are not in a registry's eager list. Browser hosts load them
+// on demand from separate hash-pinned files; Node hosts and build scripts list them to copy the files.
+
+/** Every vendored face: family, style, its file relative to the package root, its pinned sha256 and its package. */
+export function lazyFontList(manifest = BUNDLED_FONT_MANIFEST) {
+  return Object.freeze(manifest.packages.filter(pkg => pkg.vendored && (pkg.pack === "open" || pkg.embed === "used")).flatMap(pkg => pkg.faces.map(face => Object.freeze({
+    package: pkg.name, family: face.family, weight: face.weight, italic: face.italic,
+    file: `${pkg.vendored}/${face.file}`, sha256: face.sha256, license: pkg.license,
+    ...(pkg.renamedFrom ? { renamedFrom: pkg.renamedFrom } : {}),
+  }))));
+}
+
+/** Hash-pinned browser entries for the vendored faces, served by the host from `baseUrl` at their package-relative paths. */
+export function lazyFontEntries(options, list = lazyFontList()) {
+  const baseUrl = options?.baseUrl;
+  if (typeof baseUrl !== "string" || !baseUrl) throw new OPFFontError("invalid-font-source", "lazyFontEntries needs a baseUrl, where the host serves the package's fonts directory.");
+  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  return list.map(face => ({ url: `${base}${face.file}`, family: face.family, weight: face.weight, italic: face.italic, sha256: face.sha256, package: face.package }));
+}
+

package/dist/lazy-fonts.js

@@ -0,0 +1,52 @@
+import { fontPolicyFor } from "./font-policy.js";
+import { resolvePresentation } from "./svg.js";
+export { lazyFontEntries, lazyFontList } from "./lazy-font-list.js";
+
+/**
+ * FF-31: the vendored faces (the open families and Intos) are not in a registry's eager list. Browser hosts load them
+ * on demand, from separate hash-pinned files, when a document's font families resolve to them. This module holds the
+ * pure parts (which faces exist, which a presentation needs); fonts-browser.js does the fetching.
+ */
+
+const lc = value => String(value).trim().toLowerCase();
+
+/** The font families a presentation's slides resolve (heading, body and code roles), or an empty set for a document that does not resolve. */
+export function presentationFamilies(presentation) {
+  const families = new Set();
+  let resolved;
+  try { resolved = resolvePresentation(presentation, {}); } catch { return families; }
+  for (const slide of resolved.slides) for (const family of Object.values(slide.design?.fonts ?? {})) if (typeof family === "string" && family) families.add(family);
+  return families;
+}
+
+/**
+ * The vendored faces a document needs that the registry does not hold, following the registry's own order and substitution
+ * policy: the family itself, an alias target, then (unless the policy is "none") the declared replacement and, under
+ * "visual", its alternates. The first candidate the registry already has ends the search (it will resolve to that); the
+ * first vendored candidate is needed, whole family, so the browser resolves exactly what Node resolves with everything
+ * loaded, and nothing is downloaded for a family the policy would not resolve.
+ * @param {Iterable<string>} families families the document resolves
+ * @param {{lazy: readonly object[], hasFamily: (family: string) => boolean, loaded?: ReadonlySet<string>, policy?: "none"|"metric"|"visual", aliases?: ReadonlyMap<string, string>}} context
+ */
+export function lazyFontsFor(families, { lazy, hasFamily, loaded = new Set(), policy = "visual", aliases = new Map() }) {
+  const byFamily = new Map();
+  for (const face of lazy) { const list = byFamily.get(lc(face.family)) ?? []; list.push(face); byFamily.set(lc(face.family), list); }
+  const needed = new Set();
+  for (const family of families) {
+    if (hasFamily(family)) continue;
+    if (byFamily.has(lc(family))) { needed.add(lc(family)); continue; }
+    const target = aliases.get(lc(family));
+    if (target && (hasFamily(target) || byFamily.has(lc(target)))) { if (!hasFamily(target)) needed.add(lc(target)); continue; }
+    if (policy === "none") continue;
+    const row = fontPolicyFor(family), replacement = row?.replacement;
+    const route = [];
+    // Metric mode uses a metric replacement, or a visual one its policy row keeps as a metric-mode fallback; alternates are visual only.
+    if (replacement && (policy === "visual" || replacement.compatibility === "metric" || replacement.metricModeFallback)) route.push(replacement.family);
+    if (policy === "visual") route.push(...(row?.alternates ?? []));
+    for (const candidate of route) {
+      if (hasFamily(candidate)) break;
+      if (byFamily.has(lc(candidate))) { needed.add(lc(candidate)); break; }
+    }
+  }
+  return [...needed].flatMap(family => byFamily.get(family)).filter(face => !loaded.has(face.file));
+}

package/dist/raster.js

@@ -1,5 +1,6 @@
 import {prepareRasterImages} from './raster-images.js';
 import {OPFRenderError,packageName} from './svg.js';
+import {separateLigatures} from './font-compatibility.js';
 const DEFAULT_DIMENSIONS = { width: 1280, height: 720 };
 const DEFAULT_RASTER_SCALE = 1;
 const DEFAULT_RASTER_BACKGROUND = "#FFFFFF";
@@ -40,7 +41,8 @@ export async function svgToPdf(svgs, options = {}) {
 
 async function rasterizeSvg(svgInput, options) {
   const { Resvg } = await loadResvg();
-  const svg = await prepareRasterImages(normalizeSvgInput(svgInput));
+  // FF-31: resvg ignores the SVG's ligature properties, so separate the letters a Gelasio ligature would join.
+  const svg = separateLigatures(await prepareRasterImages(normalizeSvgInput(svgInput)));
   const scale = positiveNumber(options.scale, "scale", DEFAULT_RASTER_SCALE);
   const fontFiles = [
     ...(options.useBundledFonts === false ? [] : await bundledFontFiles()),