@openpresentation/opf-render 0.13.1 → 0.15.0

package/dist/element.d.ts

@@ -1,4 +1,5 @@
-import type { BrowserFontRegistry } from "./fonts-browser.js";
+import type { BrowserFontsHandle } from "./fonts-browser.js";
+import type { RenderFonts } from "./fonts.js";
 import type { RenderSvgOptions } from "./svg.js";
 import type { PlayerSession, PresentOptions, PlayerSlideChange } from "./player.js";
 export { DeckError } from "./player.js";
@@ -32,10 +33,13 @@ export interface OpfDeckElement extends HTMLElement {
   /** The 1-based number of the showing slide in the sequence that plays; set it to navigate. */
   slide: number;
   readonly total: number;
-  fonts: string;
-  /** A browser font registry the page already has. Wins over `fonts`. */
-  fontRegistry: BrowserFontRegistry | undefined;
-  /** Extra `renderSvg` options (catalogs, imageResolver, date, ...). Set before the deck loads, or call `reload()`. */
+  /**
+   * The fonts the deck draws with: the URL of the self-hosted font root (the `fonts` attribute), or a browser fonts handle the page
+   * already has (`loadFonts` from `/fonts-browser`), which wins over the attribute. The getter returns the handle when one is set, else the
+   * attribute's URL (an empty string without either).
+   */
+  fonts: string | BrowserFontsHandle;
+  /** Extra `renderSlideSvg` options (catalogs, imageResolver, date, ...). Set before the deck loads, or call `reload()`. */
   renderOptions: Partial<RenderSvgOptions>;
   includeHidden: boolean;
   thumbnails: boolean;
@@ -65,7 +69,8 @@ export interface RenderDeckHtmlOptions {
   includeHidden?: boolean;
   src?: string;
   slide?: number;
-  fonts?: string;
+  /** A string is the font root URL written to the tag's `fonts` attribute; an object (a `loadFonts()` handle, or any `RenderFonts`) draws the markup with those fonts and writes no attribute. */
+  fonts?: string | RenderFonts;
   label?: string;
   thumbnails?: boolean;
   present?: boolean;

package/dist/element.js

@@ -6,7 +6,7 @@ import {
   prepareSlideSvg, sanitizeSvgTree, slideInfo, slideLabel, svgDimensions, plainText,
 } from "./deck-runtime.js";
 import { loadPreviewFonts } from "./preview-fonts.js";
-import { renderSvg } from "./svg.js";
+import { renderSlideSvg } from "./svg.js";
 
 export { DeckError } from "./deck-runtime.js";
 export { loadPreviewFonts, previewBaseFaces, previewFontLayout } from "./preview-fonts.js";
@@ -74,7 +74,7 @@ function createElementClass() {
   return class OpfDeckElement extends Base {
     static get observedAttributes() { return ["src", "slide", "fonts", "thumbnails", "controls", "present", "include-hidden", "label", "keyboard"]; }
 
-    #root; #parts = {}; #built = false; #store; #cursor; #deck; #generation = 0; #abort; #documentValue; #fontRegistry; #renderOptions = {};
+    #root; #parts = {}; #built = false; #store; #cursor; #deck; #generation = 0; #abort; #documentValue; #fonts; #renderOptions = {};
     #readyPromise = Promise.resolve(); #state = "idle"; #error; #observer; #thumbsBuilt = false; #pointer; #session; #announce = false;
     #slideAttribute; #sheet;
 
@@ -124,13 +124,20 @@ function createElementClass() {
     /** Number of slides in the sequence that plays. */
     get total() { return this.#cursor?.total ?? 0; }
 
-    /** URL of the self-hosted font root (see the package README). Without it, layout uses estimated widths and system fonts. */
-    get fonts() { return this.getAttribute("fonts") ?? ""; }
-    set fonts(value) { if (value) this.setAttribute("fonts", String(value)); else this.removeAttribute("fonts"); }
-
-    /** A browser font registry the page already has (`loadBrowserFontRegistry`). Wins over `fonts`. */
-    get fontRegistry() { return this.#fontRegistry; }
-    set fontRegistry(value) { this.#fontRegistry = value || undefined; if (this.isConnected && this.#built) this.#start(); }
+    /**
+     * The fonts the deck draws with: the URL of the self-hosted font root (the `fonts` attribute; see the package README), or a
+     * browser fonts handle the page already has (`loadFonts` from `/fonts-browser`), which wins over the attribute. Without either,
+     * layout uses estimated widths and system fonts.
+     */
+    get fonts() { return this.#fonts ?? this.getAttribute("fonts") ?? ""; }
+    set fonts(value) {
+      if (value && typeof value === "object") { this.#fonts = value; if (this.isConnected && this.#built) this.#start(); return; }
+      const had = this.#fonts !== undefined, before = this.getAttribute("fonts");
+      this.#fonts = undefined;
+      if (value) this.setAttribute("fonts", String(value)); else this.removeAttribute("fonts");
+      // Dropping a handle changes what draws even when the attribute keeps its value.
+      if (had && before === this.getAttribute("fonts") && this.isConnected && this.#built) this.#start();
+    }
 
     /** Extra `renderSvg` options (catalogs, imageResolver, date, ...). Set before the deck loads, or call `reload()`. */
     get renderOptions() { return this.#renderOptions; }
@@ -165,7 +172,7 @@ function createElementClass() {
       if (!this.#store || !this.#cursor) throw new DeckError("not-ready", "The deck is not loaded yet.");
       const { present } = await import("./player.js");
       const session = await present(this.#deck, {
-        store: this.#store, fonts: this.#fontRegistry ?? this.#resolvedRegistry, renderOptions: this.#renderOptions,
+        store: this.#store, fonts: this.#fonts ?? this.#resolvedFonts, renderOptions: this.#renderOptions,
         includeHidden: this.includeHidden, startSlide: this.#cursor.number, returnFocus: this.#parts.viewport, ...options,
       });
       this.#session = session;
@@ -182,7 +189,7 @@ function createElementClass() {
 
     // --- loading ----------------------------------------------------------------------------------------------------
 
-    #resolvedRegistry;
+    #resolvedFonts;
 
     #start() {
       this.#abort?.abort();
@@ -202,22 +209,22 @@ function createElementClass() {
         const deck = await this.#readDocument(signal);
         if (stale()) return;
         parseDeckDocument(deck);
-        let registry = this.#fontRegistry;
-        const root = this.fonts;
+        let registry = this.#fonts;
+        const root = this.getAttribute("fonts");
         if (!registry && root) {
           try { registry = await loadPreviewFonts(root, { signal }); } catch (cause) {
             if (stale()) return;
             this.#report(new DeckError("fonts-unavailable", `The fonts at ${root} could not be loaded; the deck draws with estimated layout and system fonts.`, { cause }), false);
           }
         }
-        this.#resolvedRegistry = registry;
+        this.#resolvedFonts = registry;
         const date = this.#renderOptions.date ?? localIsoDate();
         let store = createDeckStore({ document: deck, fonts: registry, renderOptions: this.#renderOptions, date });
         try { await store.ready(signal); } catch (cause) {
           if (stale()) return;
           if (!registry) throw cause;
           this.#report(cause, false);
-          this.#resolvedRegistry = undefined;
+          this.#resolvedFonts = undefined;
           store = createDeckStore({ document: deck, renderOptions: this.#renderOptions, date });
         }
         if (stale()) return;
@@ -491,7 +498,9 @@ const escapeHtml = (value) => String(value).replace(/&/g, "&amp;").replace(/</g,
 /**
  * Server-side markup for a deck: the slides as inline SVG inside the tag, which a page that has not loaded JavaScript (or a
  * crawler, or a reader) shows as it is, and which the element replaces with its own shadow DOM when it upgrades. Pure and
- * synchronous; layout uses estimated widths unless you pass `renderOptions.textMeasurement` (and `embeddedFonts`).
+ * synchronous; layout uses estimated widths unless you pass a fonts handle as `fonts` (an object: `loadFonts()` from
+ * `/fonts-browser`, or one with a `textMeasurement` and `embeddedFonts`). A `fonts` string is the font root URL written to the
+ * element's `fonts` attribute.
  *
  * `slides`: `"first"` (default: the first slide plus a list of titles), `"all"` or a list of 1-based slide numbers.
  * `embed` puts the document in an `application/opf+json` script child, so the element upgrades without a request.
@@ -502,13 +511,14 @@ export function renderDeckHtml(input, options = {}) {
   const sequence = presentableIndexes(deck, { includeHidden: options.includeHidden });
   const wanted = options.slides ?? "first";
   const shown = wanted === "all" ? sequence.map((_, position) => position) : wanted === "first" ? [0] : wanted.map((number) => number - 1).filter((position) => position >= 0 && position < sequence.length);
-  const attributes = { src: options.src, slide: options.slide, fonts: options.fonts, label: options.label, ...options.attributes };
+  const handle = options.fonts !== null && typeof options.fonts === "object" ? options.fonts : undefined;
+  const attributes = { src: options.src, slide: options.slide, fonts: handle ? undefined : options.fonts, label: options.label, ...options.attributes };
   const attributeText = Object.entries(attributes).filter(([, value]) => value !== undefined && value !== false).map(([name, value]) => (value === true ? ` ${name}` : ` ${name}="${escapeHtml(value)}"`)).join("")
     + (options.thumbnails ? " thumbnails" : "") + (options.present ? " present" : "") + (options.includeHidden ? " include-hidden" : "");
   const date = options.renderOptions?.date ?? options.date;
   const figures = shown.map((position) => {
     const index = sequence[position];
-    const svg = renderSvg(deck, { ...options.renderOptions, ...(date ? { date } : {}), slideIndex: index });
+    const svg = renderSlideSvg(deck, index, { ...options.renderOptions, ...(handle ? { fonts: handle } : {}), ...(date ? { date } : {}) });
     const { width, height } = svgDimensions(svg);
     const prepared = prepareSlideSvg(svg).replace(/^<svg\b/, `<svg style="display:block;width:100%;height:auto;aspect-ratio:${width} / ${height}"`);
     const label = slideLabel(slideInfo(deck, index), position + 1, sequence.length);

package/dist/export-browser.d.ts

@@ -1,4 +1,5 @@
 import type { PdfDiagnostic, PdfMetadata, SvgToPdfOptions } from "./index.js";
+import type { FontsHandle } from "./fonts.js";
 export type { PdfDiagnostic, PdfMetadata } from "./index.js";
 
 export interface BrowserSvgToPngOptions {
@@ -12,7 +13,12 @@ export interface BrowserSvgToPngOptions {
 export interface BrowserSvgToPdfOptions extends Pick<SvgToPdfOptions, "mode" | "background" | "serifFamily" | "metadata" | "tagged" | "compress" | "strict" | "rasterFallbackScale" | "defaultFontFamily" | "sansSerifFamily" | "monospaceFamily" | "onDiagnostic"> {
   /** Raster mode: pixel density of each page image (default 2). */
   scale?: number;
-  /** Extra font faces as bytes (TrueType outlines). Faces an SVG embeds as `@font-face` data (renderSvg's `embeddedFonts`) need no entry here. */
+  /**
+   * The browser fonts handle (`loadFonts` from `/fonts-browser`): every face it holds can be embedded in the PDF, including script faces
+   * a standalone SVG does not carry. Faces an SVG embeds as `@font-face` data (the `embeddedFonts` of the handle `renderSvg` was given) need no entry.
+   */
+  fonts?: FontsHandle;
+  /** Extra font faces as bytes (TrueType outlines) when there is no handle. */
   fontData?: Array<{ data: Uint8Array; family?: string }>;
   /** Checked between pages; an abort rejects with the signal's reason (an `AbortError`). */
   signal?: AbortSignal;

package/dist/export-browser.js

@@ -5,8 +5,9 @@ import { OPFRenderError, packageName } from "./svg.js";
 // has the same two names for a page. It uses the same vector PDF converter as Node (fontkit, bidi-js and pako, all pure
 // JavaScript) over the SVG the preview draws, so the text stays real text in the same embedded subsets. What differs from
 // Node is only how pixels are made: a canvas decodes pictures and draws PNGs. No system font is read (a browser has no way
-// to hand one over) and nothing is fetched: faces come from the SVG's own @font-face data (renderSvg's `embeddedFonts`) or
-// from `fontData`.
+// to hand one over) and nothing is fetched: faces come from the SVG's own @font-face data (the `embeddedFonts` of the fonts handle
+// `renderSvg` was given), from the faces the `fonts` handle holds (`loadFonts` from `/fonts-browser`, so script faces the SVG does not
+// embed reach the PDF too), or from `fontData`.
 
 const DEFAULT_DIMENSIONS = { width: 1280, height: 720 };
 const MAX_PIXELS = 40_000_000;
@@ -31,21 +32,21 @@ export async function svgToPng(svg, options = {}) {
  * Convert SVG slides to a PDF, one slide per page (1 SVG pixel is 1 PDF point, as in Node). `mode: "vector"` (default) writes
  * real text, paths, gradients and images; `"raster"` draws each slide as an image (`scale`, default 2). Takes the options of
  * the Node `svgToPdf` that make sense here (`metadata`, `tagged`, `strict`, `compress`, `onDiagnostic`, the generic family
- * names, `rasterFallbackScale`) and `fontData` (`[{ data, family? }]`, extra face bytes), `signal` (an AbortSignal, checked between
- * pages) and `onProgress({ page, pages })`.
+ * names, `rasterFallbackScale`), `fonts` (the handle `loadFonts()` returns: every face it holds can be embedded), `fontData`
+ * (`[{ data, family? }]`, extra face bytes without a handle), `signal` (an AbortSignal, checked between pages) and
+ * `onProgress({ page, pages })`.
  */
 export async function svgToPdf(svgs, options = {}) {
   const inputs = (Array.isArray(svgs) ? svgs : [svgs]).map(svgText);
   if (!inputs.length) throw new OPFRenderError("empty-pdf", "svgToPdf requires at least one SVG slide.");
   const mode = options.mode ?? "vector";
   if (mode !== "vector" && mode !== "raster") throw new OPFRenderError("invalid-conversion-option", 'mode must be "vector" or "raster".', { option: "mode", value: mode });
-  if (options.loadSystemFonts === true) throw new OPFRenderError("pdf-system-fonts-unsupported", "A browser cannot hand system fonts to the PDF export: supply faces as @font-face data or `fontData`.", { option: "loadSystemFonts" });
   if (mode === "raster") return rasterPdf(inputs, options);
   const scale = positive(options.rasterFallbackScale, "rasterFallbackScale", 2);
   const fontCss = fontFaceCss(inputs);
   return svgsToVectorPdf(inputs, {
     fontFiles: [], fontDirs: [],
-    fontData: Array.isArray(options.fontData) ? options.fontData : [],
+    fontData: [...(options.fonts?.registry?.exportFaces?.() ?? []), ...(Array.isArray(options.fontData) ? options.fontData : [])],
     imageCodec: canvasImageCodec(),
     defaultFontFamily: options.defaultFontFamily ?? "Roboto",
     sansSerifFamily: options.sansSerifFamily ?? options.defaultFontFamily ?? "Roboto",

package/dist/font-compatibility.js

@@ -1,8 +1,8 @@
-import { FONT_POLICY } from "./font-policy.js";
+import { FONT_POLICY } from "@openpresentation/opf/font-policy";
 /** Curated substitution policy. Metric means upstream intent, not universal pixel identity. */
 const metric = (requestedFamily, substitutes, source, note = "Standard regular, bold, italic and bold italic styles; verify coverage and font versions.") => ({requestedFamily, substitutes, compatibility:"metric", weights:[400,700], source, note});
 const visual = (requestedFamily, substitutes, note = "Approximate appearance; measure again and expect reflow.") => ({requestedFamily, substitutes, compatibility:"visual", note});
-// Rules before FF-31. Families that the OPF font policy table (src/font-policy.js) lists take their
+// Rules before FF-31. Families that the OPF font policy table (core `FONT_POLICY`) lists take their
 // rule from the table below; the remaining legacy rules keep working for other families.
 const LEGACY = [
   metric("Calibri",["Carlito"],"https://github.com/googlefonts/carlito"),
@@ -58,7 +58,7 @@ const describe = replacement => replacement.measured
  * preview never needs a download. Replacements drive measurement and drawing only; exporters keep
  * writing the chosen family.
  */
-const FROM_POLICY = FONT_POLICY.filter(row => row.replacement).map(row => ({
+const FROM_POLICY = FONT_POLICY.families.filter(row => row.replacement).map(row => ({
   requestedFamily: row.family,
   substitutes: [row.replacement.family, ...(row.alternates ?? [])],
   compatibility: row.replacement.compatibility,
@@ -80,7 +80,7 @@ export const FONT_COMPATIBILITY = Object.freeze([...FROM_POLICY, ...LEGACY.filte
 // The row's metric claim is measured that way, so the renderer must shape (fonts.js) and draw (svg.js)
 // the face that way too. Keyed by the replacement family: a Georgia deck is measured and drawn with
 // Gelasio, and Gelasio requested by name is treated identically, so measurement and drawing never disagree.
-const DISABLED_FEATURES = new Map(FONT_POLICY.filter(row => row.replacement?.disabledFeatures?.length).map(row => [row.replacement.family.toLowerCase(), Object.freeze([...row.replacement.disabledFeatures])]));
+const DISABLED_FEATURES = new Map(FONT_POLICY.families.filter(row => row.replacement?.disabledFeatures?.length).map(row => [row.replacement.family.toLowerCase(), Object.freeze([...row.replacement.disabledFeatures])]));
 /** OpenType feature tags to turn off for a preview face, from the font policy; undefined when none. */
 export function disabledFeaturesFor(family) {
   return typeof family === "string" ? DISABLED_FEATURES.get(family.trim().toLowerCase()) : undefined;

package/dist/font-registry.js

@@ -0,0 +1,324 @@
+import { create } from "fontkit";
+import { FONT_COMPATIBILITY, disabledFeaturesFor } from "./font-compatibility.js";
+import { adjustedFontSize, openTypeLanguage, scriptFontAliases, sizeAdjustFor } from "./script-fonts.js";
+import { fontPolicyFor } from "@openpresentation/opf/font-policy";
+import { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
+import { SYMBOL_SCRIPT, isSymbolEncodedFamily, symbolEncodingFamily, symbolPreviewFaces } from "./symbol-fonts.js";
+
+// The font registry the loaders (`loadFonts` in fonts-node.js and fonts-browser.js) build: faces in, one text measurement out.
+// It is not a public entry point; callers load fonts with `loadFonts` and read `handle.registry`. `/fonts` (fonts.js) re-exports
+// the data and helpers a host may read.
+export class OPFFontError extends Error {
+  constructor(code, message, details = {}) { super(message); this.name = "OPFFontError"; this.code = code; this.details = details; }
+}
+const key = (family, weight, italic) => `${family.toLowerCase()}:${weight}:${!!italic}`;
+function base64(data) {
+  let binary = "";
+  for (let i = 0; i < data.length; i += 32768) binary += String.fromCharCode(...data.subarray(i, i + 32768));
+  return btoa(binary);
+}
+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;
+}
+// The open families load with the office pack (loadFonts({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) {
+  const row = fontPolicyFor(family), details = {path:style.path, fontFamily:family, substitutionPolicy:policy};
+  const hook = `supply licensed '${family}' font files (loadFonts({faces}))`;
+  if (!row) return new OPFFontError("font-unavailable", `No local font face for '${family}'. '${family}' is not in the OPF font policy table, so there is no declared replacement: ${hook}, add an alias, or set fallbackFamily.`, {...details, licenseClass:"unknown"});
+  Object.assign(details, {licenseClass:row.licenseClass});
+  if (!row.replacement) {
+    const pack = packFor(family);
+    return new OPFFontError("font-unavailable", `No local font face for '${family}'. '${family}' is ${row.licenseClass === "open" ? `openly licensed (${row.license})` : row.license}${pack ? `; load the '${pack}' font pack` : `; no pinned renderer pack ships it yet, so supply its font files (for example from @expo-google-fonts/${family.toLowerCase().replace(/ +/g,"-")})`}.`, {...details, ...(pack?{pack}:{})});
+  }
+  const {family:replacement, compatibility, measured} = row.replacement;
+  const candidates = [replacement, ...(row.alternates ?? [])], packs = [...new Set(candidates.map(packFor).filter(Boolean))];
+  Object.assign(details, {replacement, replacementCompatibility:compatibility, candidates, ...(packs.length?{packs}:{}), ...(measured?{measured}:{}), ...(row.replacement.decision?{decision:row.replacement.decision}:{})});
+  const delta = measured ? ` (measured mean width difference ${percent(measured.meanAbsWidthDelta)}, max ${percent(measured.maxAbsWidthDelta)})` : " (not measured against the real font)";
+  const owner = `'${family}' is ${row.license} and OPF never bundles or embeds it.`;
+  if (compatibility === "visual" && policy !== "visual")
+    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}. The PPTX names '${family}' either way.`, details);
+}
+/** Local font files only. The caller explicitly chooses aliases and fallback. */
+// fontkit 2.0.4 cannot decode every OpenType lookup: its GSUB type 8 (reverse chaining contextual single substitution) struct lacks the
+// backtrackGlyphCount field, so the lookup fails with "Not a fixed size" when a feature that references it is applied, and it has no processor
+// for the type anyway. Noto Sans Mongolian 3.x has such a lookup under calt and rclt in every script, so every shaping of the face threw (FF-44).
+// A lookup that cannot be decoded is treated as one that applies nothing (no subtables), so the rest of the feature still runs: advances equal
+// a browser's for the face's Latin and Mongolian samples (test/mongolian-shaping.mjs). Applied only after shaping failed, once per font.
+const lookupsGuarded = new WeakSet();
+export function skipUndecodableLookups(font) {
+  if (lookupsGuarded.has(font)) return false;
+  lookupsGuarded.add(font);
+  let guarded = false;
+  for (const tag of ["GSUB", "GPOS"]) {
+    let list;
+    try { list = font[tag]?.lookupList; } catch { continue; }
+    if (typeof list?.get !== "function") continue;
+    const get = list.get.bind(list);
+    list.get = index => { try { return get(index); } catch { return { lookupType: 1, flags: {}, subTables: [] }; } };
+    guarded = true;
+  }
+  return guarded;
+}
+
+/**
+ * The face a registry draws for `family` (a validated concrete family: theme tokens are already resolved) in `style`, chosen
+ * from `faces` ({family, familyGroup, weight, italic, fallbackOnly?, scripts?}) under the substitution policy, aliases and
+ * fallback family, or an OPFFontError when none applies. Shared by the registry's resolution and by the lazy loader's face
+ * planning (lazy-fonts.js), so the browser loads exactly the faces Node would draw with everything loaded.
+ */
+export function pickFace(faces, family, style, {policy = "none", aliases = new Map(), fallbackFamily} = {}) {
+  const findFamily = name => faces.filter(face=>face.family.toLowerCase()===name.toLowerCase() || face.familyGroup.toLowerCase()===name.toLowerCase());
+  const weight = style.fontWeight ?? 400;
+  let matching = findFamily(family), compatibility = "exact", rule, targetWeight = weight, styleFallback = false, via = "family", encoding;
+  // FF-45: a symbol-encoded family (Symbol, Wingdings, Wingdings 2, Wingdings 3, Webdings) whose own face is not loaded
+  // draws the Unicode equivalent of each code with the first loaded open symbol face (symbol-fonts.js: Noto Sans Symbols 2,
+  // Noto Sans Symbols, Noto Sans Math, or the office pack's Noto Sans). The resolved style carries the encoding so the
+  // planner maps every character; the PPTX keeps the family and the original codes. Without any such face the caller's
+  // fallback family applies, else the request fails as before (font-encoding-required) and names the pack to load.
+  if (!matching.length && isSymbolEncodedFamily(family)) {
+    for (const candidate of symbolPreviewFaces(family)) { const pool = findFamily(candidate); if (pool.length) { matching = pool; break; } }
+    if (matching.length) { compatibility = "visual"; via = "encoding"; encoding = symbolEncodingFamily(family); }
+    else if (!fallbackFamily) throw new OPFFontError("font-encoding-required", `Font '${family}' is symbol-encoded and no open symbol face is loaded: load the symbol faces (loadFonts with scripts: ['${SYMBOL_SCRIPT}'], or scripts: 'auto' with the presentation) or supply '${family}' itself.`, {path:style.path,fontFamily:family,scripts:[SYMBOL_SCRIPT],faces:[...symbolPreviewFaces(family)]});
+  }
+  if (!matching.length && aliases.has(family.toLowerCase())) {
+    matching = findFamily(aliases.get(family.toLowerCase())); compatibility = "visual"; via = "alias";
+  }
+  if (!matching.length && policy!=="none") {
+    const candidate = FONT_COMPATIBILITY.find(entry=>entry.requestedFamily.toLowerCase()===family.toLowerCase());
+    const tier = candidate?.compatibility==="metric" && !candidate.weights.includes(weight) ? "visual" : candidate?.compatibility;
+    // A declared visual replacement is used in visual mode, and in metric mode only when the
+    // policy keeps it as a metric-mode fallback (Cambria -> Caladea); it is still reported visual.
+    // In metric mode the fallback applies only where the pre-FF-31 metric rule did: the declared
+    // replacement at weights 400 and 700, normal or italic, with an exact face weight.
+    const metricFallback = policy!=="visual" && candidate?.metricModeFallback===true && [400,700].includes(weight);
+    const allowVisual = policy==="visual" || metricFallback;
+    if (candidate && (allowVisual || tier==="metric")) {
+      // A family that names its weight (Segoe UI Semibold, Arial Black) selects that weight in
+      // the replacement; its bold style link still selects bold (FF-31).
+      const wanted = candidate.weight ? (weight>=600 ? Math.max(candidate.weight,700) : candidate.weight) : weight;
+      for (const [index, substitute] of candidate.substitutes.entries()) {
+        // Only the declared replacement can carry the row's metric claim; an alternate is visual.
+        const substituteTier = index===0 ? tier : "visual";
+        if (substituteTier==="visual" && !(policy==="visual" || metricFallback && index===0)) continue;
+        const exactWeight = substituteTier==="metric" || policy!=="visual";
+        const pool = findFamily(substitute).filter(face=>!face.fallbackOnly && (!exactWeight || face.weight===weight));
+        let available = pool.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" && pool.length) { available = pool.filter(face=>!face.italic); styleFallback = available.length>0; }
+        if (available.length) { matching=available; compatibility=substituteTier; rule={...candidate, substituteIndex:index}; targetWeight=wanted; via="replacement"; break; }
+      }
+    }
+  }
+  // FF-45: Cambria Math previews with STIX Two Math (the math pack, loaded as a script face: the alias above resolves it
+  // under every policy). Without the pack the policy error below names the pack; the former `math-font-required` failure is gone.
+  if (!matching.length && fallbackFamily) { matching=findFamily(fallbackFamily); compatibility="generic"; via="fallback"; }
+  if (!matching.length) throw unavailableFontError(family, style, policy);
+  const styled = styleFallback ? matching : matching.filter(face=>face.italic===!!style.italic);
+  // Script replacement faces have no italics; use upright glyphs and advances. RR-17 (FF-41): so does a visual preview of a
+  // single-style display face (Anton, Bebas Neue: the families Impact and the open font schemes name), reported visual; PowerPoint
+  // synthesizes the slant of such a face too, so the advances agree and the preview no longer refuses the deck. A strict registry
+  // (policy none) still reports font-style-unavailable.
+  if (!styled.length && style.italic && matching.length && (matching.every(face=>face.scripts) || policy==="visual" && matching.every(face=>!face.italic))) { if (compatibility!=="generic") compatibility="visual"; }
+  else matching = styled;
+  if (!matching.length) throw new OPFFontError("font-style-unavailable", `No ${style.italic ? "italic" : "upright"} face for '${family}'.`, {path:style.path});
+  matching.sort((a,b)=>Math.abs(a.weight-targetWeight)-Math.abs(b.weight-targetWeight) || a.weight-b.weight);
+  const face = matching[0];
+  if ((face.weight!==targetWeight || styleFallback) && compatibility!=="generic") compatibility="visual";
+  return {face, compatibility, rule, styleFallback, via, ...(encoding ? {encoding} : {})};
+}
+
+export function createFontRegistry(entries, options = {}) {
+  if (!Array.isArray(entries) || !entries.length) throw new OPFFontError("empty-font-registry", "Supply at least one font file.");
+  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;
+    try { font = create(data, entry.postscriptName); } catch (error) { throw new OPFFontError("invalid-font-data", error.message); }
+    if (!font?.layout || !font.unitsPerEm) throw new OPFFontError("font-collection", "Select one font from a collection with postscriptName.");
+    const family = validFamily(entry.family ?? font.familyName);
+    // OpenType groups Medium/SemiBold/ExtraBold under a preferred family, while
+    // retaining separate legacy families for four-style native font selectors.
+    // An explicit caller rename owns its namespace and must not add this alias.
+    const familyGroup = entry.family && entry.family.toLowerCase() !== font.familyName?.toLowerCase()
+      ? family : validFamily(font.getName?.('preferredFamily', 'en') ?? family);
+    const linking = font['OS/2']?.fsSelection ?? font.head?.macStyle;
+    const fontFace = linking && typeof linking.bold === 'boolean' && typeof linking.italic === 'boolean'
+      ? {family:validFamily(font.getName?.('fontFamily', 'en') ?? font.familyName ?? family),bold:linking.bold,italic:linking.italic} : undefined;
+    const weight = entry.weight ?? 400;
+    const italic = entry.italic ?? !!font.italicAngle;
+    if (!Number.isInteger(weight) || weight < 1 || weight > 1000) throw new OPFFontError("invalid-font-weight", "Font weight must be between 1 and 1000.");
+    const signature = String.fromCharCode(...data.subarray(0,4));
+    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;
+    // "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.
+  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);
+  const resolve = style => {
+    const requested = validFamily(style?.fontFamily);
+    const weight = style.fontWeight ?? 400;
+    if (!Number.isFinite(weight) || weight < 1 || weight > 1000) throw new OPFFontError("invalid-font-weight", "Font weight must be between 1 and 1000.");
+    // DrawingML theme tokens are resolved before family lookup, never as literal fonts.
+    const themeKey = {"+mj-lt":"majorLatin","+mn-lt":"minorLatin","+mj-ea":"majorEastAsia","+mn-ea":"minorEastAsia","+mj-cs":"majorComplexScript","+mn-cs":"minorComplexScript"}[requested.toLowerCase()];
+    if (requested.startsWith("+") && !themeKey) throw new OPFFontError("unresolved-theme-font", `Unknown theme font '${requested}'.`, {path:style.path});
+    const family = themeKey ? options.themeFonts?.[themeKey] : requested;
+    if (!family || family.startsWith("+")) throw new OPFFontError("unresolved-theme-font", `Supply a concrete theme family for '${requested}'.`, {path:style.path});
+    validFamily(family);
+    const {face, compatibility, rule, styleFallback, via, encoding} = pickFace(faces, family, style, {policy, aliases, fallbackFamily:options.fallbackFamily});
+    // FF-31: `substitute` is true whenever the face is not the chosen family itself (policy
+    // replacement, alias, script replacement or fallback). Exporters keep writing sourceFamily.
+    const substitute = via!=="family", policyRow = substitute ? fontPolicyFor(family) : undefined;
+    // RR-38: a policy row can scale its replacement's size (Arabic Typesetting -> Noto Naskh Arabic: 0.64) so measured and drawn
+    // advances approximate the real font's. It holds only for the face the multiplier was measured on.
+    const sizeAdjust = sizeAdjustFor(policyRow, face.family);
+    const measured = rule?.measured && rule.substituteIndex===0 ? rule.measured : undefined;
+    const resolution={requestedFamily:requested,sourceFamily:family,resolvedFamily:face.family,requestedWeight:weight,resolvedWeight:face.weight,italic:face.italic,compatibility,substitute,...(styleFallback?{styleFallback:true}:{}),...(face.fontFace?{fontFace:{...face.fontFace}}:{}),...(style.path?{path:style.path}:{}),...(rule?{source:rule.source,note:rule.note,...(rule.decision?{decision:rule.decision}:{})}:{}),...(measured?{measured:{...measured}}:{}),...(policyRow?{licenseClass:policyRow.licenseClass,availability:[...policyRow.availability]}:{}),...(sizeAdjust?{sizeAdjust}:{}),...(encoding?{symbolEncoding:encoding}:{})};
+    if (face.family.toLowerCase()!==family.toLowerCase() || face.weight!==weight || face.italic!==!!style.italic) substitutions.set(JSON.stringify([requested,weight,!!style.italic,style.path]),resolution);
+    return {face,resolution};
+  };
+  const resolveFace = style => resolve(style).face;
+  const resolveStyle = style => {
+    const {face,resolution}=resolve(style),resolved={...style,fontFamily:face.family,fontWeight:face.weight,italic:face.italic};
+    // Never carry a stale selection from a previously resolved style.
+    delete resolved.fontFace;
+    delete resolved.symbolEncoding;
+    if(face.fontFace) resolved.fontFace={...face.fontFace};
+    // FF-45: the planner maps a symbol-encoded family's codes (symbol-fonts.js); the face only lends its glyphs.
+    if(resolution.symbolEncoding) resolved.symbolEncoding=resolution.symbolEncoding;
+    return resolved;
+  };
+  const metrics = (text,size,style,includeOutline=false) => {
+    if (typeof text!=='string'||!Number.isFinite(size)||size<=0) throw new OPFFontError('invalid-text-measurement','Text measurement requires a string and a positive finite font size.');
+    const {face,resolution}=resolve(style);
+    // A BCP-47 `lang` selects the font's OpenType language system, as a browser
+    // does for an element's lang (FF-19). Without it, shaping is unchanged.
+    const language=openTypeLanguage(style.lang),key=language?`${language}\u0000${text}`:text;
+    let value=face.cache.get(key);
+    if (value===undefined) {
+      if (options.strictGlyphs!==false) for(const character of text) {
+        if (/\p{Default_Ignorable_Code_Point}/u.test(character)) continue;
+        const code=character.codePointAt(0);
+        if (!face.font.hasGlyphForCodePoint(code)) {
+          // No loaded face has it: the script faces for this text are not loaded (glyph fallback needs a face to fall back to).
+          const loadedElsewhere=faces.some(other=>other!==face&&other.font.hasGlyphForCodePoint(code));
+          throw new OPFFontError("missing-glyph", `Font '${face.family}' cannot display U+${code.toString(16).toUpperCase()}.${loadedElsewhere?"":" No loaded font has it, so glyph fallback has no face to fall back to; if it is a script character, load that script's font (loadFonts with scripts: 'auto' and the presentation, or fonts.ensure(presentation))."}`, {path:style.path,fontFamily:face.family,character,...(loadedElsewhere?{}:{loadedFaceHasGlyph:false})});
+        }
+      }
+    }
+    if(value===undefined||includeOutline&&!Object.hasOwn(value,'outline')) {
+      // 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) {
+        // A lookup fontkit cannot decode (GSUB type 8 in Noto Sans Mongolian) applies nothing; shape again with the rest (FF-44).
+        if (skipUndecodableLookups(face.font)) { try { run=shape(); } catch { /* the mark retry below */ } }
+        // fontkit rejects some mark-attachment lookups (null anchors, for example
+        // Gurmukhi tippi in Noto Sans Gurmukhi). Mark positioning moves marks
+        // without changing advances, so measure again without it (FF-19).
+        if (!run) {
+          try { run=shape({abvm:false,blwm:false,mark:false,mkmk:false}); }
+          catch { throw new OPFFontError("font-shaping-failed", `Font '${face.family}' cannot shape this text.`, {path:style.path,fontFamily:face.family,cause:error?.message}); }
+        }
+      }
+      value={width:run.positions.reduce((total,position)=>total+position.xAdvance,0)/face.font.unitsPerEm,...value};
+      if(includeOutline) {
+        const unit=face.font.unitsPerEm;
+        let bounds=null;
+        // FF-45: fontkit reads COLR v0 layers only; a COLRv1 colour face (Noto Color Emoji) has no outlines it can bound (its
+        // glyf outlines are empty), so its ink box is the face's em box over the run: the colour image fills the em square.
+        try { bounds=run.bbox; } catch { bounds=null; }
+        if(bounds&&[bounds.minX,bounds.minY,bounds.maxX,bounds.maxY].every(Number.isFinite)) value.outline={x:bounds.minX/unit,y:-bounds.maxY/unit,width:bounds.width/unit,height:bounds.height/unit};
+        else if(face.font.directory?.tables?.COLR&&value.width>0) { const ascent=face.font.ascent/unit,descent=face.font.descent/unit; value.outline={x:0,y:-ascent,width:value.width,height:ascent-descent}; }
+        else value.outline=null;
+      }
+      if (text.length<=2048) {
+        if (face.cache.size>=512&&!face.cache.has(key)) face.cache.delete(face.cache.keys().next().value);
+        face.cache.set(key,value);
+      }
+    }
+    // RR-38: the replacement is measured at its adjusted size, the one the SVG draws it at.
+    return {value,scale:resolution.sizeAdjust??1};
+  };
+  const measure=(text,size,style)=>{const {value,scale}=metrics(text,size,style);return value.width*adjustedFontSize(size,scale===1?undefined:scale);};
+  const outlineBounds=(text,size,style)=>{
+    const {value,scale}=metrics(text,size,style,true),bounds=value.outline,drawn=adjustedFontSize(size,scale===1?undefined:scale);
+    return bounds===null?null:{x:bounds.x*drawn,y:bounds.y*drawn,width:bounds.width*drawn,height:bounds.height*drawn};
+  };
+  return {
+    // resolveFont lets exporters tell a substitute from the chosen family (FF-31).
+    textMeasurement: {measure,resolveStyle,outlineBounds,resolveFont:style=>resolve(style).resolution},
+    resolveFont(style) { return resolve(style).resolution; },
+    clearSubstitutions() { substitutions.clear(); },
+    get substitutions() { return [...substitutions.values()]; },
+    // Faces flagged embed:"used" (the open pack, FF-31) are not in this eager list: supplied with selectEmbeddedFonts (or
+    // the `loadFonts` handle's 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]}:{}),...(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),
+    /** Every face as `{family, data}` (the bytes the registry measures with), for the browser PDF export to embed. */
+    exportFaces: ()=>faces.map(face=>({family:face.family,data:face.data})),
+    /** 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,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)}`})); }
+}