@openpresentation/opf-render 0.9.0 → 0.11.0

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,25 @@ export declare const engineDefaults: Readonly<{
 }>;
 
 export type RenderDiagnostic = LayoutDiagnostic | {
-  code: "unsupported-pattern" | "date-needs-value";
+  /** 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;
+} | {
+  /** 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 +64,21 @@ 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[];
   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 +107,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;

package/dist/lazy-font-list.js

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

package/dist/lazy-fonts.js

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

package/dist/raster.js

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

package/dist/script-font-pack.js

@@ -0,0 +1,179 @@
+// Optional script font pack (FF-19): pinned, hash-verified OFL Noto faces that
+// stand in for proprietary script fonts in previews. The packages are optional
+// 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"});
+
+/** Script-pack manifest packages serving `scripts` ("all" or ISO 15924 codes such as `Jpan`, `Arab`). */
+export function scriptFontPackages(scripts) {
+  const available = BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === "scripts");
+  if (scripts === "all") return available;
+  if (!Array.isArray(scripts)) throw new OPFFontError("invalid-font-scripts", "scripts must be 'all' or an array of ISO 15924 script codes.", {scripts});
+  const wanted = new Set();
+  for (const value of scripts) {
+    const code = typeof value === "string" && /^[A-Za-z]{4}$/.test(value) ? value[0].toUpperCase() + value.slice(1).toLowerCase() : undefined;
+    const script = SCRIPT_ALIASES[code] ?? code;
+    if (!script || !available.some(item => item.scripts.includes(script))) {
+      throw new OPFFontError("font-script-unavailable", `No pinned open font serves script '${value}'.`, {script: value, available: [...new Set(available.flatMap(item => item.scripts))].sort()});
+    }
+    wanted.add(script);
+  }
+  return available.filter(item => item.scripts.some(script => wanted.has(script)));
+}
+
+/**
+ * Browser entries for the script pack. `baseUrl` is where the host serves the
+ * installed `@expo-google-fonts/*` packages (for example a copy of
+ * `node_modules/@expo-google-fonts`). Each entry carries the reviewed SHA-256,
+ * 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 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);
+}