@openpresentation/opf-render 0.9.0 → 0.10.0

package/dist/fonts-browser.d.ts

@@ -3,9 +3,12 @@ import type {
   FontRegistry,
   FontRegistryOptions,
 } from "./fonts.js";
+import type { BundledFontPackage, ScriptSelection } from "./fonts-node.js";
 export interface BrowserFontInput extends Omit<FontFaceInput, "data"> {
   data?: Uint8Array;
   url?: string;
+  /** Reviewed SHA-256 (hex); verified with Web Crypto before the face is used. */
+  sha256?: string;
 }
 export declare function loadBrowserFontRegistry(
   entries: BrowserFontInput[],
@@ -13,5 +16,12 @@ export declare function loadBrowserFontRegistry(
     document?: Document;
     fetch?: typeof fetch;
     signal?: AbortSignal;
+    crypto?: { subtle: SubtleCrypto };
   },
 ): Promise<FontRegistry & { dispose(): void }>;
+export declare function scriptFontPackages(scripts: ScriptSelection): BundledFontPackage[];
+/** Hash-pinned browser entries for the script pack, served by the host from `baseUrl`. */
+export declare function scriptFontEntries(
+  scripts: ScriptSelection,
+  options: { baseUrl: string },
+): (BrowserFontInput & { url: string; family: string; weight: number; italic: boolean; sha256: string; scripts: string[]; package: string; license: string })[];

package/dist/fonts-browser.js

@@ -1,4 +1,20 @@
 import { createFontRegistry, OPFFontError } from "./fonts.js";
+export { scriptFontEntries, scriptFontPackages } from "./script-font-pack.js";
+
+async function verifyDigest(entry, data, subtle) {
+  if (entry.sha256 === undefined) return;
+  if (!subtle?.digest)
+    throw new OPFFontError("font-api-unavailable", "Verifying a font SHA-256 requires Web Crypto.");
+  const digest = new Uint8Array(await subtle.digest("SHA-256", data));
+  const actual = [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  if (actual !== String(entry.sha256).toLowerCase())
+    throw new OPFFontError(
+      "font-integrity-mismatch",
+      "The font file differs from its reviewed SHA-256; serve the pinned package.",
+      { url: entry.url, expected: entry.sha256, actual },
+    );
+}
+
 /** Fetch only host-selected font files, then use those exact bytes for shaping and CSS. */
 export async function loadBrowserFontRegistry(entries, options = {}) {
   const documentRef = options.document ?? globalThis.document;
@@ -9,32 +25,38 @@ export async function loadBrowserFontRegistry(entries, options = {}) {
       "The browser Font Loading API is required.",
     );
   const fetcher = options.fetch ?? globalThis.fetch;
+  const subtle = options.crypto?.subtle ?? globalThis.crypto?.subtle;
   const faces = await Promise.all(
     entries.map(async (entry) => {
-      if (entry.data) return entry;
-      if (!entry.url)
-        throw new OPFFontError(
-          "invalid-font-source",
-          "Supply font bytes or a font-file URL.",
-        );
-      const response = await fetcher(entry.url, { signal: options.signal });
-      if (!response.ok)
-        throw new OPFFontError(
-          "font-fetch-failed",
-          `Could not load font (${response.status}).`,
-          { url: entry.url },
-        );
-      return { ...entry, data: new Uint8Array(await response.arrayBuffer()) };
+      let loaded = entry;
+      if (!entry.data) {
+        if (!entry.url)
+          throw new OPFFontError(
+            "invalid-font-source",
+            "Supply font bytes or a font-file URL.",
+          );
+        const response = await fetcher(entry.url, { signal: options.signal });
+        if (!response.ok)
+          throw new OPFFontError(
+            "font-fetch-failed",
+            `Could not load font (${response.status}).`,
+            { url: entry.url },
+          );
+        loaded = { ...entry, data: new Uint8Array(await response.arrayBuffer()) };
+      }
+      // Script-pack entries carry the reviewed hash (FF-19); verify before use.
+      await verifyDigest(entry, loaded.data, subtle);
+      return loaded;
     }),
   );
   const registry = createFontRegistry(faces, options),
     loaded = [];
   // Normalize family names using the registry's parsed font metadata.
-  const embedded = registry.embeddedFonts;
+  const described = registry.describeFaces();
   try {
     await Promise.all(
       faces.map(async (entry, index) => {
-        const descriptor = embedded[index];
+        const descriptor = described[index];
         const face = new FontFaceRef(
           descriptor.family,
           entry.data.slice().buffer,

package/dist/fonts-node.d.ts

@@ -1,17 +1,31 @@
-import type {FontRegistry,FontRegistryOptions,EmbeddedFont} from "./fonts.js";
-export declare function loadBundledFontRegistry(options?: FontRegistryOptions): Promise<FontRegistry & {fontFiles:string[]}>;
+import type {FontRegistry,FontRegistryOptions,EmbeddedFont,FontFaceInput} from "./fonts.js";
+/** A caller-supplied face (FF-31), for example a licensed copy of the real font. Node callers may pass a file path. */
+export type CallerFontFace = FontFaceInput | (Omit<FontFaceInput, "data"> & {path: string});
+/** "all" or ISO 15924 codes (`Jpan`, `Hans`, `Hant`, `Kore`, `Arab`, `Hebr`, `Deva`, `Thai`, ...). */
+export type ScriptSelection = "all" | string[];
+export interface ScriptPackOptions {
+  /** Caller-supplied faces, loaded first so a licensed real font resolves as an exact face (FF-31). */
+  faces?: readonly CallerFontFace[];
+  /** Also load the optional, hash-pinned OFL Noto script pack for these scripts (FF-19). */
+  scripts?: ScriptSelection;
+}
+export declare function loadBundledFontRegistry(options?: FontRegistryOptions & ScriptPackOptions): Promise<FontRegistry & {fontFiles:string[]}>;
 
-export declare function loadOfficeFontRegistry(options?: FontRegistryOptions & {includeBaseFonts?:boolean}): Promise<FontRegistry & {fontFiles:string[]}>;
+export declare function loadOfficeFontRegistry(options?: FontRegistryOptions & ScriptPackOptions & {includeBaseFonts?:boolean}): Promise<FontRegistry & {fontFiles:string[]}>;
 
+export type BundledFontPackage = Readonly<{
+  name:string; version:string; pack:"base"|"office"|"scripts"; source:string;
+  /** ISO 15924 scripts served by a script-pack package. */
+  scripts?: readonly string[];
+  license:string; licenseFile:string; licenseSha256:string;
+  faces:readonly Readonly<{file:string; family:string; weight:number; italic:boolean; sha256:string}>[];
+}>;
 export interface BundledFontManifest {
   readonly version: number;
-  readonly packages: readonly Readonly<{
-    name:string; version:string; pack:"base"|"office"; source:string;
-    license:string; licenseFile:string; licenseSha256:string;
-    faces:readonly Readonly<{file:string; family:string; weight:number; italic:boolean; sha256:string}>[];
-  }>[];
+  readonly packages: readonly BundledFontPackage[];
 }
 export declare const BUNDLED_FONT_MANIFEST: BundledFontManifest;
+export declare function scriptFontPackages(scripts: ScriptSelection): BundledFontPackage[];
 export interface PreparedNodeFonts {
   registry: FontRegistry & {fontFiles:string[]};
   manifest: BundledFontManifest;
@@ -23,4 +37,4 @@ export interface PreparedNodeFonts {
     loadSystemFonts: false;
   };
 }
-export declare function prepareNodeFonts(options?: FontRegistryOptions & {pack?:"base"|"office"; includeBaseFonts?:boolean}): Promise<PreparedNodeFonts>;
+export declare function prepareNodeFonts(options?: FontRegistryOptions & ScriptPackOptions & {pack?:"base"|"office"; includeBaseFonts?:boolean; /** Embed script faces in SVG (large); default false. */ embedScriptFonts?:boolean}): Promise<PreparedNodeFonts>;

package/dist/fonts-node.js

@@ -5,6 +5,8 @@ import { createHash } from "node:crypto";
 import { createFontRegistry, OPFFontError } from "./fonts.js";
 import { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
 export { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
+import { scriptFontPackages } from "./script-font-pack.js";
+export { scriptFontPackages } from "./script-font-pack.js";
 const require = createRequire(import.meta.url);
 
 async function verifiedFile(file, expected, details) {
@@ -16,9 +18,9 @@ async function verifiedFile(file, expected, details) {
   return bytes;
 }
 
-async function loadPack(pack) {
+async function loadPackages(packages) {
   const entries = [], fontFiles = [];
-  for (const pkg of BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === pack)) {
+  for (const pkg of packages) {
     let manifestPath, installed;
     try {
       manifestPath = require.resolve(`${pkg.name}/package.json`);
@@ -33,39 +35,75 @@ 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]} : {})});
     }
   }
   return {entries, fontFiles};
 }
 
+const loadPack = pack => loadPackages(BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === pack));
+
+async function withScripts(loaded, scripts) {
+  if (scripts === undefined || (Array.isArray(scripts) && !scripts.length)) return loaded;
+  const extra = await loadPackages(scriptFontPackages(scripts));
+  return {entries:[...loaded.entries, ...extra.entries], fontFiles:[...loaded.fontFiles, ...extra.fontFiles]};
+}
+
+/** 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 {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");
+export async function loadBundledFontRegistry({scripts, faces, ...options} = {}) {
+  const {entries, fontFiles} = await withFaces(await withScripts(await loadPack("base"), scripts), faces);
   return Object.assign(createFontRegistry(entries,options),{fontFiles});
 }
 
 /** Six pinned open-source Office substitutes, optionally alongside the base Roboto pack. */
-export async function loadOfficeFontRegistry(options = {}) {
+export async function loadOfficeFontRegistry({scripts, faces, ...options} = {}) {
   const {entries, fontFiles} = await loadPack("office");
   if (options.includeBaseFonts !== false) {
     const base = await loadPack("base");
     fontFiles.push(...base.fontFiles);
     entries.push(...base.entries);
   }
-  return Object.assign(createFontRegistry(entries,{substitutionPolicy:"metric",...options}),{fontFiles});
+  const loaded = await withFaces(await withScripts({entries, fontFiles}, scripts), faces);
+  return Object.assign(createFontRegistry(loaded.entries,{substitutionPolicy:"metric",...options}),{fontFiles:loaded.fontFiles});
 }
 
 /** 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.
+  const embeddedFonts = registry.selectEmbeddedFonts(face => embedScriptFonts || !face.scripts);
   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,88 @@
 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 FontFaceInput { data: Uint8Array; family?: string; weight?: number; italic?: boolean; postscriptName?: string; license?: string; /** ISO 15924 scripts a designated script replacement face serves (FF-19). */ scripts?: string[] }
 export interface EmbeddedFont { family: string; weight: number; italic?: boolean; dataUrl: string; license?: string }
 export 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[];
 }
 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;
+  /** 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[];
+export declare function detectScripts(value: unknown, profile?: ScriptFontProfile): string[];
+export declare function designatedFamilies(script: string, serif?: boolean): string[];
+export declare function scriptFontAliases(families: Iterable<string>): Record<string, string>;
+export declare function createScriptFonts(profile?: ScriptFontProfile, measurement?: TextMeasurement): ScriptFonts;
+/** Wrap a measurement so pagination, the renderer and the editor itemize script runs identically. */
+export declare function createScriptTextMeasurement(measurement: TextMeasurement, profile: ScriptFontProfile): TextMeasurement;
+export declare function 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";
+import { openTypeLanguage, scriptFontAliases } from "./script-fonts.js";
+import { fontPolicyFor } from "./font-policy.js";
+import { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
 export { FONT_COMPATIBILITY, EXPERIMENTAL_FONT_CANDIDATES } from "./font-compatibility.js";
+export { FONT_POLICY, FONT_POLICY_DECISIONS, FONT_POLICY_SOURCE, fontPolicyFor } from "./font-policy.js";
+export { SCRIPT_FONT_FAMILIES, SCRIPT_FONT_REPLACEMENTS, createScriptFonts, createScriptTextMeasurement, designatedFamilies, detectScripts, itemizeScripts, openTypeLanguage, scriptFontAliases, scriptFontRole, scriptOfCharacter, textRole } from "./script-fonts.js";
 
 export class OPFFontError extends Error {
   constructor(code, message, details = {}) { super(message); this.name = "OPFFontError"; this.code = code; this.details = details; }
@@ -15,6 +20,29 @@ function validFamily(family) {
   if (typeof family !== "string" || !family.trim() || /[\u0000-\u001f"'\\<>;]/.test(family)) throw new OPFFontError("invalid-font-family", "Font family must be a nonempty plain name.");
   return family;
 }
+const packFor = family => BUNDLED_FONT_MANIFEST.packages.find(pkg=>pkg.faces.some(face=>face.family.toLowerCase()===family.toLowerCase()))?.pack;
+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}.`, 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.");
@@ -38,7 +66,9 @@ 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()};
+    // Script replacement faces (FF-19) declare the ISO 15924 scripts they serve.
+    const scripts = Array.isArray(entry.scripts) && entry.scripts.length ? Object.freeze(entry.scripts.map(String)) : undefined;
+    return {family,familyGroup,fontFace,weight,italic,font,data,format,license:entry.license,scripts,cache:new Map()};
   });
   const duplicates = new Set();
   for (const face of faces) {
@@ -53,7 +83,10 @@ export function createFontRegistry(entries, options = {}) {
     familySlots.set(id,face);
   }
   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.
+  const scriptAliases = scriptFontAliases(new Set(faces.filter(face=>face.scripts).map(face=>face.family)));
+  const aliases = new Map(Object.entries({...scriptAliases,...options.aliases}).map(([from,to])=>[validFamily(from).toLowerCase(),validFamily(to)]));
   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 +101,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=>!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 +164,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 +175,16 @@ export function createFontRegistry(entries, options = {}) {
       }
     }
     if(value===undefined||includeOutline&&!Object.hasOwn(value,'outline')) {
-      const run=face.font.layout(text);
+      const shape=features=>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 +192,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 +204,16 @@ 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)}`})); },
+    get embeddedFonts() { return embedded(()=>true); },
+    /** 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]}:{})})),
+    /** Embedded faces for which `predicate({family,weight,italic,scripts})` holds; large script faces can be left to raster fontFiles. */
+    selectEmbeddedFonts: predicate=>embedded(predicate),
   };
+  function embedded(predicate) { return faces.filter(face=>predicate({family:face.family,weight:face.weight,italic:face.italic,scripts:face.scripts})).map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.license ? {license:face.license} : {}),dataUrl:`data:font/${face.format};base64,${base64(face.data)}`})); }
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { EmbeddedFont } from "./fonts.js";
+import type { EmbeddedFont, ScriptFonts } from "./fonts.js";
 import type { SlideComposition, LayoutDiagnostic, TextMeasurement } from "@openpresentation/opf/composition";
 export declare const packageName = "@openpresentation/opf-render";
 
@@ -32,9 +32,16 @@ export declare const engineDefaults: Readonly<{
 }>;
 
 export type RenderDiagnostic = LayoutDiagnostic | {
-  code: "unsupported-pattern" | "date-needs-value";
+  code: "unsupported-pattern" | "date-needs-value" | "language-preview-unavailable" | "language-preview-unresolved" | "paragraph-direction-unavailable";
   path: string;
   message: string;
+} | {
+  /** A font-scheme id matched no record; the default font scheme (`aptos`) was used as the base. */
+  code: "unresolved-font-scheme";
+  path: string;
+  message: string;
+  id: string;
+  fallback: string;
 } | {
   code: "unresolved-asset";
   path: string;
@@ -48,12 +55,19 @@ export type RenderDiagnostic = LayoutDiagnostic | {
 
 export interface RenderSvgOptions {
   textMeasurement?: TextMeasurement;
+  /** Unscaled reference-pixel clearance around supplied vector text outlines; default 1. */
+  textRasterPadding?: number;
   embeddedFonts?: EmbeddedFont[];
   strictAssets?: boolean;
   imageResolver?: (src: string | undefined, context: { asset: unknown; path: string }) => string | null | undefined;
   onDiagnostic?: (diagnostic: RenderDiagnostic) => void;
   validate?: boolean;
   slideIndex?: number;
+  /**
+   * Today's calendar date (ISO YYYY-MM-DD) for `date: true` header/footer furniture. The renderer
+   * never reads a clock; without it a current date is reported as unresolved content.
+   */
+  date?: string;
   trace?: boolean;
   catalogs?: Record<string, { records?: unknown[] } | unknown[]>;
   catalogSources?: Record<string, { records?: unknown[] } | unknown[]>;
@@ -82,6 +96,10 @@ export interface ResolvedPresentation {
 
 export interface ResolvedSlide {
   geometry: SlideComposition;
+  /** Script font plan for this slide (FF-19): slots, language tags and direction. */
+  scriptFonts: ScriptFonts;
+  /** The script-aware measurement composition used; undefined for estimated layout. */
+  textMeasurement?: TextMeasurement;
   index: number;
   path: string;
   slide: unknown;