@openpresentation/opf-render 0.10.0 → 0.11.0

package/dist/script-font-pack.js

@@ -3,6 +3,10 @@
 // peers, so the renderer install stays small; hosts install only what they use.
 import { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
 import { OPFFontError } from "./fonts.js";
+import * as scriptFontModule from "./script-fonts.js";
+import { scriptOfCharacter, scriptsOfText } from "./script-fonts.js";
+// Optional core exports are read from the namespace so an older published core still loads.
+import * as opfCore from "@openpresentation/opf";
 
 const SCRIPT_ALIASES = Object.freeze({Hira: "Jpan", Kana: "Jpan", Hrkt: "Jpan", Hang: "Kore", Hani: "Hans", Zyyy: "Latn"});
 
@@ -30,11 +34,146 @@ export function scriptFontPackages(scripts) {
  * which `loadBrowserFontRegistry` verifies before use.
  */
 export function scriptFontEntries(scripts, {baseUrl}) {
+  return scriptPackageEntries(scriptFontPackages(scripts), {baseUrl});
+}
+
+/** Browser entries for whole manifest packages (see `scriptFontEntries`). */
+export function scriptPackageEntries(packages, {baseUrl}) {
   if (typeof baseUrl !== "string" || !baseUrl) throw new OPFFontError("invalid-font-source", "scriptFontEntries requires the baseUrl that serves the installed font packages.");
   const root = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
-  return scriptFontPackages(scripts).flatMap(pkg => pkg.faces.map(face => ({
+  return packages.flatMap(pkg => pkg.faces.map(face => ({
     url: `${root}${pkg.name.split("/").pop()}/${face.file}`,
     family: face.family, weight: face.weight, italic: face.italic, sha256: face.sha256,
     scripts: [...pkg.scripts], package: `${pkg.name}@${pkg.version}`, license: pkg.license,
+    // A script face is embedded in a standalone SVG only when the slide's text uses its family.
+    embed: "used",
   })));
 }
+
+// Fields a preview never draws (checked against what the renderer and core composition draw).
+// Everywhere: the schema URL, embedded assets, catalog records, speaker notes, ids, image alt text and sources,
+// links, metadata and typed `extensions` passthrough. On the presentation: name (aria-label fallback), description,
+// filename, author, speaker, audience, purpose, tone, takeaway, duration, tags, narrative, language and version.
+// On a slide: beat. The organization (name) and a slide's section are drawn only as generated header/footer
+// furniture (`organization: true` / `section: true` in a design), so they count only when a design asks for
+// them. Everything else is drawn text: titles, text blocks, list items, runs, table cells, chart labels,
+// categories and series names, code, quotes, metrics, timelines, furniture text.
+const UNDRAWN_KEYS = Object.freeze(["$schema", "assets", "catalogs", "notes", "id", "alt", "altText", "src", "url", "href", "link", "metadata", "extensions"]);
+const UNDRAWN_ROOT_KEYS = Object.freeze(["name", "description", "filename", "author", "authors", "creator", "speaker", "audience", "purpose", "tone", "takeaway", "duration", "tags", "narrative", "language", "license", "version", "keywords"]);
+const UNDRAWN_SLIDE_KEYS = Object.freeze(["beat"]);
+const UNDRAWN_VALUE = /^(?:https?|data|blob|pkg|file|mailto):\S*$/i;
+
+/** True when a design in the presentation turns on generated `field` furniture (`organization` or `section`). */
+function furnitureUses(presentation, field) {
+  const designs = [presentation?.design, ...(Array.isArray(presentation?.slides) ? presentation.slides.map(slide => slide?.design) : [])];
+  const pattern = new RegExp(`"${field}"\\s*:\\s*true`);
+  return designs.some(design => design && pattern.test(JSON.stringify(design)));
+}
+
+/** The strings a preview of this presentation draws. */
+export function* drawnStrings(presentation) {
+  const undrawn = new Set(UNDRAWN_KEYS), undrawnRoot = new Set(UNDRAWN_ROOT_KEYS), undrawnSlide = new Set(UNDRAWN_SLIDE_KEYS);
+  if (!furnitureUses(presentation, "organization")) undrawnRoot.add("organization");
+  if (!furnitureUses(presentation, "section")) undrawnSlide.add("section");
+  function* visit(item, level) {
+    if (typeof item === "string") { if (!UNDRAWN_VALUE.test(item)) yield item; }
+    else if (Array.isArray(item)) for (const child of item) yield* visit(child, level === "slides" ? "slide" : level === "root" ? "deep" : level);
+    else if (item && typeof item === "object") {
+      for (const [key, child] of Object.entries(item)) {
+        if (undrawn.has(key) || (level === "root" && undrawnRoot.has(key)) || (level === "slide" && undrawnSlide.has(key))) continue;
+        yield* visit(child, level === "root" && key === "slides" ? "slides" : "deep");
+      }
+    }
+  }
+  yield* visit(presentation, "root");
+}
+
+/**
+ * The script profile of a presentation: core `resolveScriptFonts` output, exactly what the renderer plans
+ * with. When the installed core has none (published core 0.11.0 and earlier) or it throws, the renderer
+ * ignores the document language, so the profile is empty and Han text is Simplified Chinese, as drawn.
+ */
+export function presentationScriptProfile(presentation) {
+  if (typeof opfCore.resolveScriptFonts === "function") {
+    try { return opfCore.resolveScriptFonts(presentation); } catch { /* the renderer falls back the same way */ }
+  }
+  return {};
+}
+
+const servedScripts = () => new Set(BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === "scripts").flatMap(item => item.scripts));
+const cjkKeys = ["Jpan", "Hans", "Hant", "Kore"];
+const cjkCharacters = new Set(["Hani", "Hira", "Kana", "Hang", "Bopo"]);
+/** True when the renderer has per-character glyph fallback (FF-19 glyphFallbackFamilies). */
+const hasGlyphFallback = () => typeof scriptFontModule.glyphFallbackFamilies === "function";
+
+/**
+ * What a preview of the presentation draws: its script profile, the scripts of its text (the renderer's own
+ * itemization, so language-dependent punctuation counts), and the CJK characters that a glyph fallback might
+ * have to draw with another CJK face.
+ */
+export function analyzePresentationScripts(presentation, profile = presentationScriptProfile(presentation)) {
+  const scripts = new Set(), cjk = new Set();
+  for (const text of drawnStrings(presentation)) {
+    for (const script of scriptsOfText(text, profile)) scripts.add(script);
+    for (const character of text) if (character.codePointAt(0) > 0x2E7F && cjkCharacters.has(scriptOfCharacter(character))) cjk.add(character);
+  }
+  return { profile, detected: [...scripts].sort(), cjk };
+}
+
+/**
+ * Script keys (ISO 15924: `Jpan`, `Hans`, `Arab`, ...) whose faces a preview of this presentation needs.
+ * Text decides, itemized exactly as drawing does: the document language only tells Han text apart
+ * (Japanese, Korean, Simplified or Traditional Chinese) and makes curly quotes, dashes and the ellipsis
+ * East Asian. Text the preview never draws (ids, alt text, sources, assets, catalogs, notes) is ignored.
+ * Greek and Cyrillic add nothing: the office registry always carries Noto Sans (the glyph-fallback face) and Roboto covers them.
+ * Pass `profile` to reuse a resolved profile.
+ */
+export function detectPresentationScripts(presentation, { profile } = {}) {
+  return analyzePresentationScripts(presentation, profile).detected;
+}
+
+/** The scripts of an analysis that a pinned pack serves (`scripts`, the input for `scriptFontPackages`) and those it does not. */
+export function scriptSelectionOf(analysis) {
+  const served = servedScripts();
+  return { detected: analysis.detected, scripts: analysis.detected.filter(script => served.has(script)), unavailable: analysis.detected.filter(script => !served.has(script)) };
+}
+
+/**
+ * What `scripts: 'auto'` loads for a presentation: the `detected` scripts, those a pinned pack serves
+ * (`scripts`, the input for `scriptFontPackages`) and those it does not (`unavailable`, for example
+ * Cherokee or Tifinagh, which draw with whatever the design font covers).
+ */
+export function autoScriptSelection(presentation, options) {
+  return scriptSelectionOf(analyzePresentationScripts(presentation, options?.profile));
+}
+
+/**
+ * The next CJK package a glyph fallback needs (FF-19): a drawn Han, kana or Hangul character that no loaded
+ * script face has (Japanese-only kanji in a Simplified Chinese run, Simplified-only hanzi beside kana, hanja)
+ * takes the first unloaded CJK face along the renderer's fallback chain. `covers(character)` says whether a
+ * loaded script face has the glyph; `loaded` holds the loaded package names. Undefined when nothing is needed,
+ * the renderer has no glyph fallback, or the cap is reached: a character no CJK face covers must not pull in
+ * every CJK package (10 to 20 MiB each), so at most ONE fallback package is loaded beyond the packages the
+ * text's own scripts need. Characters still uncovered then are reported (`uncoveredCjkCharacters`) and the
+ * renderer reports `missing-glyph` for them.
+ */
+export function nextFallbackPackage(analysis, { covers, loaded }) {
+  if (!hasGlyphFallback()) return undefined;
+  const packages = BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === "scripts" && item.scripts.some(script => cjkKeys.includes(script)));
+  const primary = analysis.detected.filter(script => cjkKeys.includes(script)).length;
+  if (packages.filter(item => loaded.has(item.name)).length >= primary + 1) return undefined;
+  for (const character of analysis.cjk) {
+    if (covers(character)) continue;
+    for (const family of scriptFontModule.glyphFallbackFamilies(character, analysis.profile, analysis.profile?.serif === true)) {
+      const pkg = packages.find(item => !loaded.has(item.name) && item.faces.some(face => face.family === family));
+      if (pkg) return pkg;
+    }
+  }
+  return undefined;
+}
+
+/** Drawn Han, kana or Hangul characters (at most `limit`) that no loaded script face covers. Empty without glyph fallback (nothing else would draw them). */
+export function uncoveredCjkCharacters(analysis, { covers, limit = 16 }) {
+  if (!hasGlyphFallback()) return [];
+  return [...analysis.cjk].filter(character => !covers(character)).slice(0, limit);
+}

package/dist/script-fonts.js

@@ -7,6 +7,14 @@
 // face is missing or lacks glyphs falls back to the designated open (OFL Noto)
 // replacement for that script. Licensed fonts are never bundled: a preview names
 // the designated replacement, while the PPTX keeps the chosen family (FF-07).
+//
+// Glyph fallback: a face that lacks a character (a Latin replacement without
+// Cyrillic or Greek, a CJK face without a kanji or hanzi) never fails a preview.
+// As in a browser or PowerPoint font linking, each such character takes the
+// first bundled face that has it along the deterministic chain of
+// `glyphFallbackFamilies`, in measurement and drawing alike, and the substitution
+// is reported as a note. `glyphFallback: "none"` (strict mode) keeps the exact
+// faces and lets a missing glyph raise `missing-glyph`.
 
 const freeze = value => { if (value && typeof value === "object") { for (const child of Object.values(value)) freeze(child); Object.freeze(value); } return value; };
 
@@ -199,16 +207,31 @@ export function itemizeScripts(text, profile) {
   return runs;
 }
 
-/** Script keys (as used by the script font pack) present in the strings of any JSON value. */
-export function detectScripts(value, profile) {
-  const scripts = new Set();
+/**
+ * Non-Latin script keys the renderer would plan runs for in `text`. It applies the same shortcut as drawing
+ * (`createScriptFonts().plan`): Latin, Greek and Cyrillic text is one run in the design font, except that
+ * with an East Asian document language the curly quotes, dashes and ellipsis are East Asian characters.
+ */
+export function scriptsOfText(text, profile) {
+  const source = String(text ?? "");
+  if (latinOnly.test(source) && !(eastAsianLanguage(profile) && eastAsianAmbiguous.test(source))) return [];
+  return itemizeScripts(source, profile).filter(run => run.script !== "Latn").map(run => run.script);
+}
+
+/**
+ * Script keys (as used by the script font pack) present in the strings of any JSON value.
+ * The profile's own script is included too, unless `includeLanguage` is false (then only
+ * text decides). `ignoreKeys` names object keys whose values are not visited.
+ */
+export function detectScripts(value, profile, { includeLanguage = true, ignoreKeys = [] } = {}) {
+  const scripts = new Set(), ignored = new Set(ignoreKeys);
   const visit = item => {
-    if (typeof item === "string") { if (!latinOnly.test(item)) for (const run of itemizeScripts(item, profile)) if (run.script !== "Latn") scripts.add(run.script); }
+    if (typeof item === "string") { for (const script of scriptsOfText(item, profile)) scripts.add(script); }
     else if (Array.isArray(item)) item.forEach(visit);
-    else if (item && typeof item === "object") Object.values(item).forEach(visit);
+    else if (item && typeof item === "object") for (const [key, child] of Object.entries(item)) if (!ignored.has(key)) visit(child);
   };
   visit(value);
-  if (profile?.script && !latinGroup.has(profile.script)) scripts.add(fontKey(profile.script, "", profile));
+  if (includeLanguage && profile?.script && !latinGroup.has(profile.script)) scripts.add(fontKey(profile.script, "", profile));
   return [...scripts].sort();
 }
 
@@ -219,6 +242,35 @@ export function designatedFamilies(script, serif = false) {
   return (serif ? [entry.serif, entry.sans] : [entry.sans, entry.serif]).filter(Boolean);
 }
 
+const hanKeys = ["Jpan", "Hans", "Hant", "Kore"];
+
+/**
+ * Deterministic glyph fallback chain for one character: the designated open
+ * families, in order, that a preview tries when the chosen face lacks the
+ * character (the same order in measurement and drawing).
+ *
+ * 1. the character's own script policy face (`SCRIPT_FONT_FAMILIES`; a Han
+ *    character takes the deck language's face: Japanese, Simplified, Traditional
+ *    or Korean);
+ * 2. the deck language's script face;
+ * 3. Noto Sans, which covers Latin, Cyrillic and Greek;
+ * 4. the other CJK faces (Japanese, Simplified, Traditional, Korean);
+ * 5. every other Noto script face, in `SCRIPT_FONT_FAMILIES` order.
+ *
+ * `profile` is core `resolveScriptFonts` output (or the same shape); serif
+ * profiles prefer the serif face of each script. Families that are not loaded
+ * are skipped by the caller.
+ */
+export function glyphFallbackFamilies(character, profile = {}, serif = profile?.serif === true) {
+  const script = scriptOfCharacter(character);
+  const language = fontKey(profile?.script ?? "Zzzz", "", profile);
+  // A Han character has no script of its own: it takes the deck language's face when that is CJK,
+  // otherwise every CJK face is tried in turn (Japanese, Simplified, Traditional, Korean).
+  const own = script === "Hani" ? (hanKeys.includes(language) ? language : "Zzzz") : fontKey(script, character, profile);
+  const keys = [own, language, "Latn", ...hanKeys, ...Object.keys(SCRIPT_FONT_FAMILIES)];
+  return [...new Set([...new Set(keys)].flatMap(key => designatedFamilies(key, serif)))];
+}
+
 /**
  * Aliases from proprietary script fonts to the first loaded designated
  * replacement. `families` are the loaded script-replacement families.
@@ -286,9 +338,23 @@ const scriptMeasurement = Symbol.for("@openpresentation/opf-render/script-measur
  * plus an optional `serif` flag. `measurement` is an optional font-registry
  * `textMeasurement`; without it the plan names every candidate family in order
  * so the host resolves glyphs per character.
+ *
+ * `options.glyphFallback` is `"chain"` (default: a character its face lacks
+ * takes the first bundled face along `glyphFallbackFamilies`) or `"none"`
+ * (exact faces: a missing glyph raises `missing-glyph`). `options.onFallback`
+ * receives each new substitution note `{fontFamily, fallbackFamily, scripts,
+ * characters, path?}` once; `fallbacks` lists them all.
  */
-export function createScriptFonts(profile = {}, measurement) {
-  const inner = measurement?.[scriptMeasurement]?.inner ?? measurement;
+export function createScriptFonts(profile = {}, measurement, options = {}) {
+  const wrapped = measurement?.[scriptMeasurement];
+  const inner = wrapped?.inner ?? measurement;
+  // Glyph fallback is on unless `glyphFallback: "none"` (strict faces); a wrapped measurement keeps its options.
+  // Only defined keys override: a caller passing `glyphFallback: undefined` must not undo a wrapper's `"none"`.
+  // A renderer-supplied `onFallback` chains with, and does not replace, the wrapper's own.
+  const notifiers = [wrapped?.options?.onFallback, options?.onFallback].filter(notify => typeof notify === "function");
+  options = {...wrapped?.options, ...Object.fromEntries(Object.entries(options ?? {}).filter(([, value]) => value !== undefined)), onFallback: notifiers.length ? note => { for (const notify of notifiers) notify(note); } : undefined};
+  const fallbackEnabled = options.glyphFallback !== "none";
+  const fallbackNotes = new Map();
   const measured = typeof inner?.measure === "function";
   const serif = profile.serif === true;
   // The language the SVG declares (lang) also selects OpenType language systems in measurement.
@@ -333,6 +399,37 @@ export function createScriptFonts(profile = {}, measurement) {
     const supplement = profile.supplement ? {script: profile.supplement.script === "Hang" ? "Kore" : profile.supplement.script, family: useHeading ? profile.supplement.heading : profile.supplement.body} : undefined;
     return {latin: style.fontFamily, eastAsian: slots.eastAsian ?? style.fontFamily, complexScript: slots.complexScript ?? style.fontFamily, supplement};
   };
+  const nonAscii = /[^\u0020-\u007E]/;
+  const cyrillicOrGreek = /[\u0370-\u052F\u1F00-\u1FFF]/;
+  const chains = new Map();
+  const chainFor = character => {
+    const script = scriptOfCharacter(character);
+    let chain = chains.get(script);
+    if (!chain) chains.set(script, chain = glyphFallbackFamilies(character, profile, serif));
+    return chain;
+  };
+  /** Collect that `family` draws characters the chosen `from` face lacks; `flushFallbacks` records them per planned text. */
+  const noteFallback = (pending, from, family, characters) => {
+    if (from === null || from === family) return;
+    const key = `${from}\u0000${family}`;
+    let entry = pending.get(key);
+    if (!entry) pending.set(key, entry = {from, family, characters: new Set()});
+    for (const character of characters) entry.characters.add(character);
+  };
+  const flushFallbacks = (pending, style) => {
+    for (const {from, family, characters} of pending.values()) {
+      const key = `${from}\u0000${family}\u0000${style.path ?? ""}`;
+      let note = fallbackNotes.get(key);
+      const isNew = !note;
+      if (isNew) fallbackNotes.set(key, note = {fontFamily: from, fallbackFamily: family, scripts: [], characters: [], ...(style.path ? {path: style.path} : {})});
+      for (const character of characters) {
+        const script = scriptOfCharacter(character);
+        if (!note.scripts.includes(script)) note.scripts.push(script);
+        if (note.characters.length < 16 && !note.characters.includes(character)) note.characters.push(character);
+      }
+      if (isNew) options.onFallback?.(note);
+    }
+  };
   const candidatesFor = (run, slots) => {
     const list = [run.role === "eastAsian" ? slots.eastAsian : run.role === "complexScript" ? slots.complexScript : slots.latin];
     if (run.script !== "Latn") {
@@ -345,13 +442,22 @@ export function createScriptFonts(profile = {}, measurement) {
   /** Font runs for text drawn in `style` (the resolved latin style). `own` runs use the style's family. */
   const plan = (text, style) => {
     text = String(text ?? "");
-    if (latinOnly.test(text) && !(eastAsianText && eastAsianAmbiguous.test(text))) return [{text, family: style.fontFamily, own: true}];
-    const cacheKey = `${style.fontFamily}\u0000${style.fontWeight ?? 400}\u0000${!!style.italic}\u0000${textRole(style) ?? ""}\u0000${text}`;
+    if (latinOnly.test(text) && !(eastAsianText && eastAsianAmbiguous.test(text))) {
+      // Latin-group text is one run in the latin slot's face, unless that face lacks a character
+      // (Cyrillic or Greek beyond a Latin replacement): then it is planned per character below.
+      if (!fallbackEnabled || !nonAscii.test(text)) return [{text, family: style.fontFamily, own: true}];
+      if (!measured) return cyrillicOrGreek.test(text) ? [{text, family: style.fontFamily, own: false, stack: [style.fontFamily, ...designatedFamilies("Latn", serif)]}] : [{text, family: style.fontFamily, own: true}];
+      const own = resolveName(style.fontFamily, style);
+      if (own === null || covers(own, text, style)) return [{text, family: style.fontFamily, own: true}];
+    }
+    const cacheKey = `${style.fontFamily}\u0000${style.fontWeight ?? 400}\u0000${!!style.italic}\u0000${textRole(style) ?? ""}\u0000${style.path ?? ""}\u0000${text}`;
     const cached = plans.get(cacheKey);
     if (cached) return cached;
     const slots = slotsFor(style);
     const runs = itemizeScripts(text, profile).map(run => ({...run, candidates: candidatesFor(run, slots)}));
+    const pending = new Map();
     const global = [...new Set([...runs.flatMap(run => run.candidates), ...designatedFamilies(fontKey(profile.script ?? "Zzzz", text, profile), serif), ...designatedFamilies("Latn", serif)])];
+    const unique = names => names.map(name => resolveName(name, style)).filter((name, index, all) => name && all.indexOf(name) === index);
     const out = [];
     const push = (text, family, stack) => {
       const own = family === style.fontFamily && (!stack || stack.length === 1);
@@ -361,20 +467,51 @@ export function createScriptFonts(profile = {}, measurement) {
     };
     for (const run of runs) {
       if (!measured) { push(run.text, run.candidates[0], run.candidates); continue; }
+      const chosen = resolveName(run.candidates[0], style);
       const whole = run.candidates.map(family => resolveName(family, style)).find(name => name && covers(name, run.text, style));
-      if (whole) { push(run.text, whole); continue; }
-      // No single candidate covers the run: choose per character, keeping
-      // combining marks and joiners with their base character.
-      const primary = resolveName(run.candidates[0], style) ?? style.fontFamily;
-      let previous = primary;
+      if (whole) {
+        if (whole !== chosen) noteFallback(pending, chosen, whole, [...run.text].filter(character => !covers(chosen ?? whole, character, style)));
+        push(run.text, whole);
+        continue;
+      }
+      // No single candidate covers the run. Split it into grapheme clusters (a base character with
+      // the combining marks and joiners that follow it) and group those into script segments
+      // (common characters stay with their neighbours; white space ends a word). Each segment takes the first face that
+      // covers all of its letters and marks: the chosen face, the previous fallback face, the
+      // other candidates, then the fallback chain. A word is never drawn in two faces when one
+      // face has all of it (Greek beside a Latin serif, a kanji run beside Hangul). A cluster
+      // that face still lacks, mark included, moves whole to the first face that has the cluster,
+      // so a base and its mark are never split across faces.
+      const primary = chosen ?? style.fontFamily;
+      let sticky = null;
+      // The note lists what the chosen face lacks (a mark, not its covered base letter); a cluster it only lacks as a whole lists all.
+      const missingFrom = (face, text) => { const lacking = [...text].filter(character => !covers(face, character, style)); return lacking.length ? lacking : [...text]; };
+      const choose = (subject, sample) => unique([run.candidates[0], ...(sticky ? [sticky] : []), ...run.candidates, ...global, ...(fallbackEnabled ? chainFor(sample) : [])]).find(name => covers(name, subject, style));
+      const segments = [];
       for (const character of run.text) {
-        const script = scriptOfCharacter(character);
-        let family = previous;
-        if (script !== "Zinh") family = [...run.candidates, ...global].map(name => resolveName(name, style)).find(name => name && covers(name, character, style)) ?? primary;
-        push(character, family);
-        previous = family;
+        const script = scriptOfCharacter(character), last = segments.at(-1)?.clusters.at(-1);
+        if (script === "Zinh" && last) { last.text += character; continue; }
+        const weak = script === "Zyyy" || script === "Zinh", segment = segments.at(-1);
+        const cluster = {text: character, base: character, weak};
+        // A segment is one script and one word: white space closes it, so a single lacking mark
+        // moves its word to another face, not the whole sentence.
+        if (segment && !(segment.closed && !weak) && (weak || segment.script === undefined || segment.script === script)) {
+          segment.clusters.push(cluster);
+          if (!weak) segment.script = script; else if (/^\s/.test(character)) segment.closed = true;
+        } else segments.push({script: weak ? undefined : script, clusters: [cluster]});
+      }
+      for (const segment of segments) {
+        const strong = segment.clusters.filter(cluster => !cluster.weak);
+        const face = strong.length ? choose(strong.map(cluster => cluster.text).join(""), strong[0].base) : undefined;
+        for (const cluster of segment.clusters) {
+          const family = face && covers(face, cluster.text, style) ? face : choose(cluster.text, cluster.base) ?? choose(cluster.base, cluster.base) ?? primary;
+          if (family !== primary && family !== chosen) sticky = family;
+          if (chosen !== null && family !== chosen && covers(family, cluster.text, style)) noteFallback(pending, chosen, family, missingFrom(chosen, cluster.text));
+          push(cluster.text, family);
+        }
       }
     }
+    flushFallbacks(pending, style);
     if (plans.size >= 4096) plans.delete(plans.keys().next().value);
     plans.set(cacheKey, out);
     return out;
@@ -392,7 +529,7 @@ export function createScriptFonts(profile = {}, measurement) {
         if (runs.length === 1 && runs[0].own) return inner.measure(text, size, styled(style));
         return runs.reduce((total, run) => total + inner.measure(run.text, size, styleFor(run, style)), 0);
       },
-      [scriptMeasurement]: {inner, profile},
+      [scriptMeasurement]: {inner, profile, options},
     };
     if (typeof inner.outlineBounds === "function") {
       textMeasurement.outlineBounds = (text, size, style) => {
@@ -411,7 +548,7 @@ export function createScriptFonts(profile = {}, measurement) {
       };
     }
   }
-  return {profile, plan, runWidths, textMeasurement, rtl: isRtlProfile(profile)};
+  return {profile, plan, runWidths, textMeasurement, rtl: isRtlProfile(profile), get fallbacks() { return [...fallbackNotes.values()].map(note => ({...note, scripts: [...note.scripts], characters: [...note.characters]})); }};
 }
 
 /**
@@ -420,7 +557,7 @@ export function createScriptFonts(profile = {}, measurement) {
  * replacement). Pass the same wrapper to core pagination, the renderer and the
  * editor so their line breaks agree for non-Latin text.
  */
-export function createScriptTextMeasurement(measurement, profile) {
+export function createScriptTextMeasurement(measurement, profile, options) {
   if (typeof measurement?.measure !== "function") throw new TypeError("createScriptTextMeasurement requires a textMeasurement with measure().");
-  return createScriptFonts(profile, measurement).textMeasurement;
+  return createScriptFonts(profile, measurement, options).textMeasurement;
 }

package/dist/svg.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/svg.js

@@ -8,6 +8,7 @@ import {
 // still loads; resolveScriptFonts ships with core FF-18.
 import * as opfCore from "@openpresentation/opf";
 import { createScriptFonts } from "./script-fonts.js";
+import { disabledFeaturesStyle } from "./font-compatibility.js";
 
 export const packageName = "@openpresentation/opf-render";
 
@@ -485,6 +486,28 @@ function reportLanguageDiagnostic(context, diagnostic) {
   context.options.onDiagnostic?.(diagnostic);
 }
 
+/**
+ * Report a glyph fallback once per resolvePresentation call, family pair and path (FF-19).
+ * It is a note, not an error: the face the font scheme resolved to lacks glyphs for the text,
+ * so a bundled face that has them draws those characters. The PPTX still names the chosen font.
+ */
+function reportGlyphFallback(context, note) {
+  context.glyphFallbackDiagnostics ??= new Set();
+  const key = `${note.fontFamily}\u0000${note.fallbackFamily}\u0000${note.path ?? ""}`;
+  if (context.glyphFallbackDiagnostics.has(key)) return;
+  context.glyphFallbackDiagnostics.add(key);
+  context.options.onDiagnostic?.({
+    code: "font-glyph-fallback",
+    ...(note.path ? { path: note.path } : {}),
+    // The note is reported once per family pair and path: it names characters the face lacks, such as these, not every one.
+    message: `'${note.fontFamily}' lacks glyphs for characters such as ${note.characters.slice(0, 8).map(character => `U+${character.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")}`).join(", ")}; the preview draws those with '${note.fallbackFamily}'. The PPTX keeps the chosen font.`,
+    fontFamily: note.fontFamily,
+    fallbackFamily: note.fallbackFamily,
+    scripts: [...note.scripts],
+    characters: [...note.characters]
+  });
+}
+
 function inferLayoutId(slide) {
   if (slide.layout) return slide.layout;
   if (slide.blocks?.length) return "blank";
@@ -609,7 +632,10 @@ function bindSlide(presentation, slide, layout, index, context) {
   const design = resolveDesign(presentation, slide, context, index);
   // Script fonts (FF-19): each text run is measured and drawn with its script
   // slot's face; the latin slot stays the design font scheme's family.
-  const scriptFonts = createScriptFonts(scriptProfile(presentation, index, design, context), context.options.textMeasurement);
+  const scriptFonts = createScriptFonts(scriptProfile(presentation, index, design, context), context.options.textMeasurement, {
+    glyphFallback: context.options.glyphFallback,
+    onFallback: note => reportGlyphFallback(context, note)
+  });
   const textMeasurement = scriptFonts.textMeasurement ?? context.options.textMeasurement;
   for (const role of ["heading","body","code"]) design.fonts[role] = resolveTextStyle({fontFamily:design.fonts[role],fontWeight:role === "heading" ? 700 : 400},textMeasurement).fontFamily;
   const geometry = composeSlide(slide, { ...design.dimensions, layout, presentation, slideIndex: index, fonts: design.fonts, contentAlignment:design.contentAlignment, titleAlignment:design.titleAlignment, textRasterPadding:context.options.textRasterPadding, contentBox:design.contentBox, textMeasurement, date: context.options.date, socialPlatforms: socialPlatformRecords(context) });
@@ -674,8 +700,7 @@ function renderResolvedSlide(resolved, slideIndex, options) {
   const lang = script?.languageSource === "document" || script?.languageSource === "option" ? script.bcp47 : undefined;
   const { width, height } = bound.design.dimensions;
   const title = bound.slide.title ?? resolved.presentation.name ?? `Slide ${slideIndex + 1}`;
-  const children = [
-    renderEmbeddedFonts(options.embeddedFonts),
+  const content = [
     renderBackground(bound, width, height, options),
     renderSlideImage(bound, options),
     renderBranding(bound, resolved.presentation, width, height, options),
@@ -683,6 +708,7 @@ function renderResolvedSlide(resolved, slideIndex, options) {
     renderFurniture(bound, resolved.presentation, width, height, options, "header"),
     renderFurniture(bound, resolved.presentation, width, height, options, "footer")
   ].filter(Boolean);
+  const children = [renderEmbeddedFonts(embeddedFontsFor(options.embeddedFonts, content)), ...content].filter(Boolean);
 
   return tag(
     "svg",
@@ -1434,6 +1460,13 @@ function paragraphRtl(bound, text) {
  * a textLength spanning differently fonted tspans does not rasterize reliably;
  * the caller then drops its own textLength and anchors at the start.
  */
+// Nested script runs of a line drawn with a flagged face (Gelasio) opt back into default shaping,
+// unless the run itself uses a flagged family (tag() then adds that family's own style).
+function nestedReset(style, run) {
+  const parent = disabledFeaturesStyle(style?.fontFamily);
+  return parent && !disabledFeaturesStyle([run.stack ?? run.family].flat()[0]) ? RESET_POLICY_FEATURES : undefined;
+}
+
 function scriptLine(text, style, bound, type, { rtl = false, placement, trace } = {}) {
   const value = String(text ?? "");
   const scripts = bound.scriptFonts;
@@ -1447,7 +1480,7 @@ function scriptLine(text, style, bound, type, { rtl = false, placement, trace }
   const widths = placement && placement.width > 0 ? scripts.runWidths(runs, placement.fontSize, style) : undefined;
   if (!widths) {
     return { content: isolate(runs.map(run => run.own ? escapeText(run.text)
-      : tag("tspan", { "font-family": fontStack(run.stack ?? run.family, type) }, escapeText(run.text))).join("")) };
+      : tag("tspan", { "font-family": fontStack(run.stack ?? run.family, type), style: nestedReset(style, run) }, escapeText(run.text))).join("")) };
   }
   const total = widths.reduce((sum, width) => sum + width, 0), factor = total > 0 ? placement.width / total : 1;
   let advance = 0, offset = 0;
@@ -1460,6 +1493,7 @@ function scriptLine(text, style, bound, type, { rtl = false, placement, trace }
       x: stableNumber(placement.x + left),
       textLength: width > 0 ? stableNumber(width) : undefined, lengthAdjust: width > 0 ? "spacingAndGlyphs" : undefined,
       "font-family": run.own ? undefined : fontStack(run.family, type),
+      style: run.own ? undefined : nestedReset(style, run),
       ...(trace ? trace(start, offset) : {})
     }, isolate(escapeText(run.text)));
   }).join("");
@@ -1472,6 +1506,49 @@ function segmentSpan(attrs, segment, text, style, bound, type, options) {
   return tag("tspan", { ...attrs, "font-family": scripted.family }, scripted.content);
 }
 
+// Faces flagged embed:"used" (the vendored open, Intos and script-pack faces) are embedded only when the slide's own markup draws
+// them: the family in a font-family list, at a font-weight and font-style some text of the slide takes (attributes are
+// inherited down the element tree, as in SVG). A used family none of whose faces matches a drawn weight and style keeps all
+// its faces, so the browser can always choose. Every other face (the npm packs) is embedded as before.
+function embeddedFontsFor(fonts = [], content) {
+  if (!fonts.some(font => font?.embed === "used")) return fonts;
+  const drawn = drawnFaces(content.join("\n"));
+  const wanted = font => {
+    const triples = drawn.get(String(font.family).toLowerCase());
+    if (!triples) return false;
+    const family = fonts.filter(other => other?.embed === "used" && String(other.family).toLowerCase() === String(font.family).toLowerCase());
+    const matching = family.filter(other => triples.has(`${other.weight}|${other.italic ? "italic" : "normal"}`));
+    return matching.length ? matching.includes(font) : true;
+  };
+  return fonts.filter(font => font?.embed !== "used" || wanted(font));
+}
+
+const FONT_WEIGHT_KEYWORDS = { normal: "400", bold: "700" };
+/** family (lowercase) to the set of "weight|style" pairs the markup draws text in. */
+function drawnFaces(markup) {
+  const drawn = new Map();
+  const tokens = /<(\/?)([A-Za-z][\w:.-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>|<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|[^<]+/g;
+  const stack = [{ families: [], weight: "400", style: "normal", text: false }];
+  const attribute = (attributes, name) => { const found = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`).exec(attributes); return found ? found[1] ?? found[2] : undefined; };
+  for (const [token, close, name, attributes, selfClose] of markup.matchAll(tokens)) {
+    const top = stack.at(-1);
+    if (name === undefined) {
+      if (top.text && /\S/.test(token)) for (const family of top.families) { const set = drawn.get(family) ?? new Set(); set.add(`${top.weight}|${top.style}`); drawn.set(family, set); }
+      continue;
+    }
+    if (close) { if (stack.length > 1) stack.pop(); continue; }
+    const family = attribute(attributes, "font-family"), weight = attribute(attributes, "font-weight"), style = attribute(attributes, "font-style");
+    const next = {
+      families: family === undefined ? top.families : family.split(",").map(item => item.trim().replace(/^&quot;|&quot;$|^["']|["']$/g, "").toLowerCase()).filter(Boolean),
+      weight: weight === undefined ? top.weight : FONT_WEIGHT_KEYWORDS[weight.trim()] ?? weight.trim(),
+      style: style === undefined ? top.style : /italic|oblique/.test(style) ? "italic" : "normal",
+      text: top.text || name === "text",
+    };
+    if (!selfClose) stack.push(next);
+  }
+  return drawn;
+}
+
 function renderEmbeddedFonts(fonts = []) {
   if (!fonts.length) return "";
   const css = fonts.map(font => {
@@ -1541,7 +1618,7 @@ function renderRichLines(value,fit,box,bound,config) {
     if(!flow)return fragments.join('\n');
     const x=alignment==='right'?box.x+box.width:alignment==='center'?box.x+box.width/2:box.x;
     const first=line.fragments[0];
-    return tag('text',{x:stableNumber(x),y:stableNumber(box.y+line.baseline),'text-anchor':alignment==='right'?'end':alignment==='center'?'middle':'start','xml:space':'preserve','font-family':fontStack(first?.style.fontFamily??config.fontFamily,bound.design.fontScheme.type),'font-size':stableNumber(first?.fontSize??fit.fontSize),'font-weight':first?.style.fontWeight??config.fontWeight??400,'font-style':first?.style.italic?'italic':undefined},fragments.join(''));
+    return tag('text',{x:stableNumber(x),y:stableNumber(box.y+line.baseline),'text-anchor':alignment==='right'?'end':alignment==='center'?'middle':'start','xml:space':'preserve','font-family':fontStack(first?.style.fontFamily??config.fontFamily,bound.design.fontScheme.type),'font-size':stableNumber(first?.fontSize??fit.fontSize),'font-weight':first?.style.fontWeight??config.fontWeight??400,'font-style':first?.style.italic?'italic':undefined,[NO_POLICY_FEATURES]:true},fragments.join(''));
   });
   let cursor=0;
   const whole=value.map(run=>typeof run==='string'?run:run.text).join('');
@@ -1694,7 +1771,22 @@ function escapeAttr(value) {
   return escapeText(value).replaceAll('"', "&quot;");
 }
 
+// FF-31: text drawn with a face whose features the font policy turns off (Gelasio for Georgia) says so, so
+// browsers do not ligate what the measurement did not. Only text or tspan elements that name such a family.
+// A flow line's outer text element, which only carries the first fragment's family, opts out: each of its
+// tspans names its own family and gets its own style, so other faces do not inherit ligatures:none.
+const NO_POLICY_FEATURES = Symbol("noPolicyFeatures");
+// Text in another script nested in a flagged run (scriptLine tspans) goes back to default shaping.
+const RESET_POLICY_FEATURES = "font-variant-ligatures:normal;font-feature-settings:normal";
+function withPolicyFeatures(name, attrs) {
+  if (attrs[NO_POLICY_FEATURES]) return attrs;
+  const family = (name === "text" || name === "tspan") && typeof attrs["font-family"] === "string" ? attrs["font-family"].split(",")[0].trim() : undefined;
+  const features = family && disabledFeaturesStyle(family);
+  return features ? { ...attrs, style: attrs.style ? `${attrs.style};${features}` : features } : attrs;
+}
+
 function tag(name, attrs = {}, children = "") {
+  attrs = withPolicyFeatures(name, attrs);
   const serializedAttrs = Object.keys(attrs)
     .filter((key) => attrs[key] !== undefined && attrs[key] !== null && attrs[key] !== false)
     .sort()