@openpresentation/opf-render 0.9.0 → 0.11.0

package/dist/fonts-node.js

@@ -1,10 +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 { 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) {
@@ -16,14 +22,37 @@ async function verifiedFile(file, expected, details) {
   return bytes;
 }
 
-async function loadPack(pack) {
+// 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 BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === pack)) {
+  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});
@@ -33,39 +62,146 @@ async function loadPack(pack) {
       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});
+      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, 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));
+
+/**
+ * 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;
+  // 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
+ * FontFaceInput entries; Node callers may pass `path` instead of `data`. They come first, so the
+ * real family resolves as an exact face ahead of any replacement. */
+async function callerFaces(faces = []) {
+  if (!Array.isArray(faces)) throw new OPFFontError("invalid-font-data", "faces must be an array of font entries.");
+  const entries = [], fontFiles = [];
+  for (const face of faces) {
+    if (face?.data instanceof Uint8Array) { entries.push(face); continue; }
+    if (typeof face?.path !== "string") throw new OPFFontError("invalid-font-data", "Each caller face needs data (Uint8Array) or a file path.");
+    let data;
+    try { data = await readFile(face.path); } catch (error) { throw new OPFFontError("font-resource-unavailable", `Cannot read caller font file ${face.path}.`, {file:face.path, cause:error.code}); }
+    const {path:file, ...rest} = face;
+    entries.push({...rest, data:new Uint8Array(data)});
+    fontFiles.push(path.resolve(file));
+  }
   return {entries, fontFiles};
 }
 
+async function withFaces(loaded, faces) {
+  if (!faces?.length) return loaded;
+  const own = await callerFaces(faces);
+  return {...loaded, entries:[...own.entries, ...loaded.entries], fontFiles:[...own.fontFiles, ...loaded.fontFiles]};
+}
+
 /** Bundled, openly licensed faces. No system font discovery or network requests. */
-export async function loadBundledFontRegistry(options = {}) {
-  const {entries, fontFiles} = await loadPack("base");
-  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(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);
   }
-  return Object.assign(createFontRegistry(entries,{substitutionPolicy:"metric",...options}),{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. */
-export async function prepareNodeFonts({pack = "base", ...options} = {}) {
+export async function prepareNodeFonts({pack = "base", embedScriptFonts = false, ...options} = {}) {
   if (pack !== "base" && pack !== "office") throw new OPFFontError("invalid-font-pack", "Choose the base or office font pack.", {pack});
   const registry = await (pack === "base" ? loadBundledFontRegistry(options) : loadOfficeFontRegistry(options));
+  // Script faces are large (CJK faces are 5-10 MB each). Raster output reads them
+  // from fontFiles; embed them in standalone SVG only on request. The default Noto Sans fallback is always offered
+  // (embed "used"), so an SVG carries it exactly when its text draws it.
+  const embeddedFonts = registry.selectEmbeddedFonts(face => embedScriptFonts || !face.scripts || face.fallbackOnly);
   return {
     registry,
     manifest:BUNDLED_FONT_MANIFEST,
     options:{
       textMeasurement:registry.textMeasurement,
-      embeddedFonts:registry.embeddedFonts,
+      embeddedFonts,
       fontFiles:[...registry.fontFiles],
       useBundledFonts:false,
       loadSystemFonts:false,

package/dist/fonts.d.ts

@@ -1,21 +1,103 @@
 import type { TextMeasurement, TextStyle } from "@openpresentation/opf/composition";
-export interface FontFaceInput { data: Uint8Array; family?: string; weight?: number; italic?: boolean; postscriptName?: string; license?: 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 FontResolution { requestedFamily:string; sourceFamily:string; resolvedFamily:string; requestedWeight:number; resolvedWeight:number; italic:boolean; compatibility:FontCompatibility; fontFace?:TextStyle['fontFace']; path?:string; source?:string; note?:string }
+export interface FontReplacementMeasurement { replacement:string; meanAbsWidthDelta:number; meanWidthDelta:number; maxAbsWidthDelta:number; styles:number; reference:string }
+export interface FontResolution {
+  requestedFamily:string; sourceFamily:string; resolvedFamily:string; requestedWeight:number; resolvedWeight:number; italic:boolean; compatibility:FontCompatibility;
+  /** True when the face is not the chosen family itself (policy replacement, alias, script replacement or fallback).
+   * Exporters keep writing sourceFamily; the face only drives measurement and drawing (FF-31). */
+  substitute:boolean;
+  /** A visual replacement without the requested italic/upright style draws the other style. */
+  styleFallback?:true;
+  fontFace?:TextStyle['fontFace']; path?:string; source?:string; note?:string;
+  /** The provisional owner decision the replacement follows, if any. */
+  decision?:string;
+  /** Measured width difference of the declared replacement against the real font. */
+  measured?:FontReplacementMeasurement;
+  licenseClass?:FontPolicyEntry['licenseClass']; availability?:FontPolicyEntry['availability'];
+}
+/** One OPF font policy row (snapshot of opf spec/reference/font-policy.json, decisions applied). */
+export interface FontPolicyEntry {
+  family:string; licenseClass:"open"|"proprietary-standard"|"proprietary-nonstandard"; license:string;
+  availability:("windows"|"windows-optional"|"macos"|"office"|"office-cloud")[]; embeddableByOpf:boolean;
+  replacement:{family:string; compatibility:"metric"|"visual"; decision?:string; metricModeFallback?:true; weight?:number; measured:FontReplacementMeasurement|null; source?:string}|null;
+  alternates?:string[];
+}
+export declare const FONT_POLICY: readonly Readonly<FontPolicyEntry>[];
+export declare const FONT_POLICY_SOURCE: Readonly<{version:number; path:string; sha256:string}>;
+/** Provisional owner decisions applied to the snapshot (owner may revise). */
+export declare const FONT_POLICY_DECISIONS: Readonly<Record<string, unknown>>;
+export declare function fontPolicyFor(family:string): Readonly<FontPolicyEntry>|undefined;
 export interface FontRegistryOptions {
   aliases?: Record<string,string>; fallbackFamily?: string; strictGlyphs?: boolean;
   substitutionPolicy?: "none" | "metric" | "visual";
   themeFonts?: Partial<Record<"majorLatin"|"minorLatin"|"majorEastAsia"|"minorEastAsia"|"majorComplexScript"|"minorComplexScript",string>>;
 }
-export declare const FONT_COMPATIBILITY: readonly Readonly<{requestedFamily:string;substitutes:readonly string[];compatibility:"metric"|"visual";weights?:readonly number[];source?:string;note:string}>[];
+export declare const FONT_COMPATIBILITY: readonly Readonly<{requestedFamily:string;substitutes:readonly string[];compatibility:"metric"|"visual";weights?:readonly number[];weight?:number;source?:string;measured?:FontReplacementMeasurement;decision?:string;metricModeFallback?:true;licenseClass?:FontPolicyEntry['licenseClass'];note:string}>[];
 export declare const EXPERIMENTAL_FONT_CANDIDATES: readonly Readonly<{requestedFamily:string;substitute:string;source:string;note:string}>[];
+export interface FaceDescription { family:string; weight:number; italic:boolean; scripts?:string[] }
 export interface FontRegistry {
-  textMeasurement: TextMeasurement & {outlineBounds: NonNullable<TextMeasurement['outlineBounds']>};
+  textMeasurement: TextMeasurement & {outlineBounds: NonNullable<TextMeasurement['outlineBounds']>; resolveFont(style: TextStyle): FontResolution};
   clearSubstitutions(): void;
   resolveFont(style: TextStyle): FontResolution;
   readonly embeddedFonts: EmbeddedFont[];
+  /** Embedded faces matching `predicate`; large script faces can stay with raster fontFiles. */
+  selectEmbeddedFonts(predicate: (face: FaceDescription) => boolean): EmbeddedFont[];
+  /** 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;
+
+/** OOXML script slot. */
+export type ScriptRole = "latin" | "eastAsian" | "complexScript";
+export interface ScriptFontSlots { latin: string; eastAsian: string; complexScript: string }
+/** Core `resolveScriptFonts` output, or the same shape. `serif` prefers serif replacements. */
+export interface ScriptFontProfile {
+  heading?: ScriptFontSlots; body?: ScriptFontSlots;
+  supplement?: { script: string; heading: string; body: string };
+  script?: string; bcp47?: string; lang?: string; direction?: "ltr" | "rtl"; rtl?: boolean;
+  languageSource?: "document" | "option" | "default"; scriptRole?: ScriptRole; serif?: boolean;
+}
+export interface ScriptRun { text: string; script: string; role: ScriptRole }
+export interface PlannedRun { text: string; family: string; own: boolean; stack?: string[] }
+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;
+  /** Script-aware measurement; undefined without a measurement provider. */
+  readonly textMeasurement?: TextMeasurement;
+}
+export declare const SCRIPT_FONT_FAMILIES: Readonly<Record<string, Readonly<{ sans?: string; serif?: string }>>>;
+export declare const SCRIPT_FONT_REPLACEMENTS: readonly Readonly<{requestedFamily:string;script:string;substitutes:readonly string[];compatibility:"visual";note:string}>[];
+export declare function scriptOfCharacter(character: string): string;
+export declare function scriptFontRole(script: string): ScriptRole;
+export declare function itemizeScripts(text: string, profile?: ScriptFontProfile): ScriptRun[];
+/** Script keys in the strings of a JSON value. The profile's own script counts unless `includeLanguage` is false; `ignoreKeys` are not visited. */
+export declare function detectScripts(value: unknown, profile?: ScriptFontProfile, options?: { includeLanguage?: boolean; ignoreKeys?: readonly string[] }): string[];
+export declare function designatedFamilies(script: string, serif?: boolean): string[];
+export declare function scriptFontAliases(families: Iterable<string>): Record<string, string>;
+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, 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,6 +1,11 @@
 import { create } from "fontkit";
-import { FONT_COMPATIBILITY } from "./font-compatibility.js";
-export { FONT_COMPATIBILITY, EXPERIMENTAL_FONT_CANDIDATES } 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, 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, 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; }
@@ -15,10 +20,34 @@ 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 (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) {
+  const row = fontPolicyFor(family), details = {path:style.path, fontFamily:family, substitutionPolicy:policy};
+  const hook = `supply licensed '${family}' font files (prepareNodeFonts({faces}) or createFontRegistry entries)`;
+  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. */
 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;
@@ -38,22 +67,42 @@ export function createFontRegistry(entries, options = {}) {
     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";
-    return {family,familyGroup,fontFace,weight,italic,font,data,format,license:entry.license,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);
-  }
+    // 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();
-  const aliases = new Map(Object.entries(options.aliases ?? {}).map(([from,to])=>[validFamily(from).toLowerCase(),validFamily(to)]));
+  // 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);
@@ -68,33 +117,56 @@ export function createFontRegistry(entries, options = {}) {
     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);
-    let matching = findFamily(family), compatibility = "exact", rule;
+    let matching = findFamily(family), compatibility = "exact", rule, targetWeight = weight, styleFallback = false, via = "family";
     const encodedSymbol = /^(wingdings(?: [23])?|webdings|symbol)$/i.test(family);
     if (!matching.length && encodedSymbol) throw new OPFFontError("font-encoding-required", `Font '${family}' requires character mapping before substitution.`, {path:style.path,fontFamily:family});
     if (!matching.length && aliases.has(family.toLowerCase())) {
-      matching = findFamily(aliases.get(family.toLowerCase())); compatibility = "visual";
+      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;
-      if (candidate && (policy==="visual" || tier==="metric")) {
-        for (const substitute of candidate.substitutes) {
-          const available = findFamily(substitute).filter(face=>face.italic===!!style.italic && (tier!=="metric" || face.weight===weight));
-          if (available.length) { matching=available; compatibility=tier; rule=candidate; break; }
+      // 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 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; }
+          if (available.length) { matching=available; compatibility=substituteTier; rule={...candidate, substituteIndex:index}; targetWeight=wanted; via="replacement"; break; }
         }
       }
     }
     // Equations require an explicit math-aware choice; never fall through to body text.
     if (!matching.length && /^(cambria math|stix two math|noto sans math)$/i.test(family)) throw new OPFFontError("math-font-required", `Supply '${family}' or an explicit math-font alias.`, {path:style.path});
-    if (!matching.length && options.fallbackFamily) { matching=findFamily(options.fallbackFamily); compatibility="generic"; }
-    if (!matching.length) throw new OPFFontError("font-unavailable", `No local font face for '${family}'.`, {path:style.path,fontFamily:family});
-    matching = matching.filter(face=>face.italic===!!style.italic);
+    if (!matching.length && options.fallbackFamily) { matching=findFamily(options.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.
+    if (!styled.length && style.italic && matching.length && matching.every(face=>face.scripts)) { 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-weight)-Math.abs(b.weight-weight) || a.weight-b.weight);
+    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!==weight && compatibility!=="generic") compatibility="visual";
-    const resolution={requestedFamily:requested,sourceFamily:family,resolvedFamily:face.family,requestedWeight:weight,resolvedWeight:face.weight,italic:face.italic,compatibility,...(face.fontFace?{fontFace:{...face.fontFace}}:{}),...(style.path?{path:style.path}:{}),...(rule?{source:rule.source,note:rule.note}:{})};
-    if (face.family.toLowerCase()!==family.toLowerCase() || face.weight!==weight) substitutions.set(JSON.stringify([requested,weight,!!style.italic,style.path]),resolution);
+    if ((face.weight!==targetWeight || styleFallback) && compatibility!=="generic") compatibility="visual";
+    // 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;
+    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]}:{})};
+    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;
@@ -108,7 +180,10 @@ export function createFontRegistry(entries, options = {}) {
   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=resolveFace(style);
-    let value=face.cache.get(text);
+    // 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;
@@ -116,7 +191,19 @@ export function createFontRegistry(entries, options = {}) {
       }
     }
     if(value===undefined||includeOutline&&!Object.hasOwn(value,'outline')) {
-      const run=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) {
+        // 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).
+        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 bounds=run.bbox,unit=face.font.unitsPerEm;
@@ -124,8 +211,8 @@ export function createFontRegistry(entries, options = {}) {
           ?{x:bounds.minX/unit,y:-bounds.maxY/unit,width:bounds.width/unit,height:bounds.height/unit}:null;
       }
       if (text.length<=2048) {
-        if (face.cache.size>=512&&!face.cache.has(text)) face.cache.delete(face.cache.keys().next().value);
-        face.cache.set(text,value);
+        if (face.cache.size>=512&&!face.cache.has(key)) face.cache.delete(face.cache.keys().next().value);
+        face.cache.set(key,value);
       }
     }
     return value;
@@ -136,10 +223,33 @@ export function createFontRegistry(entries, options = {}) {
     return bounds===null?null:{x:bounds.x*size,y:bounds.y*size,width:bounds.width*size,height:bounds.height*size};
   };
   return {
-    textMeasurement: {measure,resolveStyle,outlineBounds},
+    // 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()]; },
-    get embeddedFonts() { return faces.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)}`})); },
+    // 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]}:{}),...(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,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)}`})); }
 }