@openpresentation/opf-render 0.13.1 → 0.15.0

package/dist/preview-fonts.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserFontRegistry } from "./fonts-browser.js";
+import type { BrowserFontsHandle } from "./fonts-browser.js";
 
 /** One face of the self-hosted font root: where it sits under the root, and its pinned hash. */
 export interface PreviewBaseFace { family: string; weight: number; italic: boolean; file: string; sha256: string; license: string }
@@ -16,8 +16,8 @@ export declare function previewFontLayout(manifest?: unknown, lazyFiles?: readon
 export declare function previewBaseFaces(manifest?: unknown): PreviewBaseFace[];
 
 /**
- * A browser font registry over a self-hosted font root: `<root>/base/<package>/<file>`, `<root>/lazy/fonts/<family>/<file>` and
+ * A browser fonts handle (`loadFonts`) over a self-hosted font root: `<root>/base/<package>/<file>`, `<root>/lazy/fonts/<family>/<file>` and
  * `<root>/scripts/<package>/<file>`. It starts with Roboto Regular and loads other faces on demand, hash-verified, only when a
- * deck draws them. Registries are shared per root on a page.
+ * deck draws them. Handles are shared per root on a page.
  */
-export declare function loadPreviewFonts(root: string, options?: { document?: Document; fetch?: typeof fetch; signal?: AbortSignal; registryOptions?: Record<string, unknown> }): Promise<BrowserFontRegistry>;
+export declare function loadPreviewFonts(root: string, options?: { document?: Document; fetch?: typeof fetch; signal?: AbortSignal; registryOptions?: Record<string, unknown> }): Promise<BrowserFontsHandle>;

package/dist/preview-fonts.js

@@ -8,7 +8,7 @@
 // `copyPreviewFonts` (the `/fonts-node` side of this layout, `preview-fonts-node.js`) fills it from the installed packages.
 // Every file is verified against its pinned SHA-256 by the registry before use, and only the faces a deck draws are fetched.
 import { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
-import { lazyFontList, loadBrowserFontRegistry, splitStartupFaces } from "./fonts-browser.js";
+import { lazyFontList, loadFonts, splitStartupFaces } from "./fonts-browser.js";
 
 /** The directory a package's files sit in under its kind: a vendored family's own name, or the npm package name without its scope. */
 export function previewFontDirectory(pkg) {
@@ -47,9 +47,9 @@ const absolute = (root, document) => {
 const shared = new Map();
 
 /**
- * A browser font registry over a font root. It starts with Roboto Regular (the renderer's fallback family) and loads the rest
- * only when a deck draws it, face by face: vendored faces from `<root>/lazy/`, script faces from `<root>/scripts/`, the other
- * eager faces as the registry's extra lazy faces. One registry is shared by every deck on the page that names the same root.
+ * A browser fonts handle (`loadFonts`) over a font root. It starts with Roboto Regular (the renderer's fallback family) and loads
+ * the rest only when a deck draws it, face by face: vendored faces from `<root>/lazy/`, script faces from `<root>/scripts/`, the
+ * other eager faces as the registry's extra lazy faces. One handle is shared by every deck on the page that names the same root.
  */
 export function loadPreviewFonts(root, options = {}) {
   if (typeof root !== "string" || !root) return Promise.reject(new TypeError("loadPreviewFonts needs the URL of the font root."));
@@ -59,7 +59,8 @@ export function loadPreviewFonts(root, options = {}) {
   const faces = previewBaseFaces();
   const { startup, rest } = splitStartupFaces(faces, { startup: (face) => face.family === "Roboto" && face.weight === 400 && !face.italic });
   const entry = (face) => ({ url: base + face.file, family: face.family, weight: face.weight, italic: face.italic, license: face.license, sha256: face.sha256 });
-  const promise = loadBrowserFontRegistry(startup.map(entry), {
+  const promise = loadFonts({
+    faces: startup.map(entry),
     substitutionPolicy: "visual",
     fallbackFamily: "Roboto",
     scriptBaseUrl: `${base}scripts/`,

package/dist/raster.js

@@ -10,11 +10,24 @@ const DEFAULT_RASTER_BACKGROUND = "#FFFFFF";
 const DEFAULT_PDF_MODE = "vector";
 let bundledFontFilesCache=null;
 
+// The faces a raster or PDF conversion draws with, from the fonts handle (`loadFonts()` from `/fonts-node`): its `fontFiles`, and
+// whether the bundled base faces are added (`useBundledFonts`, default true; a Node handle already holds its own, so it says false) and
+// whether system fonts load (`loadSystemFonts`, default false). Without a handle the bundled base faces draw.
+function fontSettings(options) {
+  const fonts = options.fonts ?? {};
+  return { fontFiles: stringArray(fonts.fontFiles), useBundledFonts: fonts.useBundledFonts !== false, loadSystemFonts: fonts.loadSystemFonts === true };
+}
+
+/**
+ * Convert one SVG (the output of `renderSvg` or `renderSlideSvg`) to PNG bytes. `fonts` is the handle `loadFonts()` returns: the raster draws
+ * with its font files, so the preview and the PNG use the same faces. Without it the bundled base faces draw.
+ */
 export async function svgToPng(svg, options = {}) {
   const rendered = await rasterizeSvg(svg, options);
   return rendered.png;
 }
 
+/** Convert SVG slides (the output of `renderSvg`) to a PDF, one page each. `fonts` is as for `svgToPng`; `mode` is `"vector"` (default) or `"raster"`. */
 export async function svgToPdf(svgs, options = {}) {
   const pdfInputs = normalizeSvgList(svgs);
   if (!pdfInputs.length) {
@@ -49,13 +62,14 @@ export async function svgToPdf(svgs, options = {}) {
 }
 
 async function vectorPdf(inputs, options) {
-  if (options.loadSystemFonts === true) {
-    throw new OPFRenderError("pdf-system-fonts-unsupported", 'Vector PDF output embeds only the font files you supply: loadSystemFonts is not supported with mode "vector". Pass fontFiles/fontDirs, or use mode "raster".', { option: "loadSystemFonts" });
+  const settings = fontSettings(options);
+  if (settings.loadSystemFonts) {
+    throw new OPFRenderError("pdf-system-fonts-unsupported", 'Vector PDF output embeds only the font files you supply: fonts.loadSystemFonts is not supported with mode "vector". Pass a fonts handle with fontFiles (and fontDirs), or use mode "raster".', { option: "fonts.loadSystemFonts" });
   }
   const scale = positiveNumber(options.rasterFallbackScale, "rasterFallbackScale", 2);
   const fontFiles = [
-    ...(options.useBundledFonts === false ? [] : await bundledFontFiles()),
-    ...stringArray(options.fontFiles)
+    ...(settings.useBundledFonts ? await bundledFontFiles() : []),
+    ...settings.fontFiles
   ];
   const svgs = [];
   for (const input of inputs) svgs.push(await prepareRasterImages(normalizeSvgInput(input)));
@@ -100,12 +114,13 @@ async function rasterizeSvg(svgInput, options) {
   const { Resvg } = await loadResvg();
   const scale = positiveNumber(options.scale, "scale", DEFAULT_RASTER_SCALE);
   // FF-45: resvg draws no COLRv1 or OT-SVG colour glyphs; the colour faces stay out of its font list (see color-fonts.js).
+  const settings = fontSettings(options);
   const fontFiles = rasterFontFiles([
-    ...(options.useBundledFonts === false ? [] : await bundledFontFiles()),
-    ...stringArray(options.fontFiles)
+    ...(settings.useBundledFonts ? await bundledFontFiles() : []),
+    ...settings.fontFiles
   ]);
   const font = {
-    loadSystemFonts: options.loadSystemFonts === true,
+    loadSystemFonts: settings.loadSystemFonts,
     fontFiles,
     fontDirs: stringArray(options.fontDirs),
     defaultFontFamily: options.defaultFontFamily ?? "Roboto",
@@ -178,8 +193,8 @@ async function bundledFontFiles() {
 }
 
 async function resolveBundledFontFiles() {
-  const {loadBundledFontRegistry} = await import('./fonts-node.js');
-  return (await loadBundledFontRegistry()).fontFiles;
+  const {loadFonts} = await import('./fonts-node.js');
+  return (await loadFonts()).fontFiles;
 }
 
 function normalizeSvgList(value) {

package/dist/script-font-pack.js

@@ -2,11 +2,9 @@
 // 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";
+import { OPFFontError } from "./font-registry.js";
+import { SCRIPT_FONT_REPLACEMENTS, glyphFallbackFamilies, scriptOfCharacter, scriptsOfText } from "./script-fonts.js";
+import { resolveScriptFonts } from "@openpresentation/opf/composition";
 import { presentationFamilies } from "./lazy-fonts.js";
 import { SYMBOL_SCRIPT, isSymbolEncodedFamily } from "./symbol-fonts.js";
 
@@ -33,7 +31,7 @@ export function scriptFontPackages(scripts) {
  * 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.
+ * which `loadFonts` (browser) verifies before use.
  */
 export function scriptFontEntries(scripts, {baseUrl}) {
   return scriptPackageEntries(scriptFontPackages(scripts), {baseUrl});
@@ -55,17 +53,17 @@ export function scriptPackageEntries(packages, {baseUrl}) {
 // 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,
+// filename, author, audience, purpose, tone, takeaway, duration, tags, narrative, language and version.
+// On a slide: beat. The organization (name), the speaker (name and title) and a slide's section are drawn only as
+// generated header/footer furniture (`organization: true` / `speaker: true` / `section: true` in a design), so they count
+// only when a design asks for them; built-in variables copy their values into slide strings before this runs. 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_ROOT_KEYS = Object.freeze(["name", "description", "filename", "author", "authors", "creator", "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`). */
+/** True when a design in the presentation turns on generated `field` furniture (`organization`, `speaker` 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`);
@@ -76,6 +74,7 @@ function furnitureUses(presentation, field) {
 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, "speaker")) undrawnRoot.add("speaker");
   if (!furnitureUses(presentation, "section")) undrawnSlide.add("section");
   function* visit(item, level) {
     if (typeof item === "string") { if (!UNDRAWN_VALUE.test(item)) yield item; }
@@ -92,21 +91,17 @@ export function* drawnStrings(presentation) {
 
 /**
  * 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.
+ * with. When it throws, the renderer ignores the document language, so the profile is empty and Han text is
+ * Simplified Chinese, as drawn. `renderOptions.catalogs` (the host's registered catalogs) resolve as they do for the renderer.
  */
-export function presentationScriptProfile(presentation) {
-  if (typeof opfCore.resolveScriptFonts === "function") {
-    try { return opfCore.resolveScriptFonts(presentation); } catch { /* the renderer falls back the same way */ }
-  }
+export function presentationScriptProfile(presentation, renderOptions) {
+  try { return resolveScriptFonts(presentation, renderOptions?.catalogs !== undefined ? { catalogs: renderOptions.catalogs } : {}); } 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";
 
 /**
  * ISO 15924 script whose pinned face a family resolves to: a proprietary script font (Yu Gothic: Jpan), a pinned face itself
@@ -116,7 +111,7 @@ function scriptOfFamily(family) {
   const name = String(family ?? "").toLowerCase();
   if (!name) return undefined;
   if (isSymbolEncodedFamily(name)) return SYMBOL_SCRIPT;
-  const rule = scriptFontModule.SCRIPT_FONT_REPLACEMENTS.find(item => item.requestedFamily.toLowerCase() === name);
+  const rule = SCRIPT_FONT_REPLACEMENTS.find(item => item.requestedFamily.toLowerCase() === name);
   if (rule) return rule.script;
   return BUNDLED_FONT_MANIFEST.packages.find(item => item.pack === "scripts" && item.faces.some(face => face.family.toLowerCase() === name))?.scripts[0];
 }
@@ -128,9 +123,9 @@ function scriptOfFamily(family) {
  * scheme (`slide.design`), so each such slide is resolved too. `han` is the CJK script the scheme names, which tells
  * Han-only text apart when the language does not (a Yu Gothic deck whose language is English).
  *
- * `renderOptions` are the host's `renderSvg` options. Core resolves a font scheme id from the document and its bundled catalogs
- * only, while the renderer also reads `renderOptions.catalogs`; when a host passes catalogs the families the renderer resolves
- * per slide count too, so a scheme that exists only in the host's catalogs and names a script font still loads that font.
+ * `renderOptions` are the host's `renderSvg` options: their `catalogs` (core `Catalog[]`) go to core's `resolveScriptFonts`
+ * unchanged, and the families the renderer resolves per slide count too, so a scheme that exists only in the host's catalogs
+ * and names a script font still loads that font.
  */
 function designScripts(presentation, profile, renderOptions) {
   const scripts = new Set();
@@ -144,10 +139,10 @@ function designScripts(presentation, profile, renderOptions) {
     }
   };
   note(profile);
-  if (typeof opfCore.resolveScriptFonts === "function" && Array.isArray(presentation?.slides)) {
+  if (Array.isArray(presentation?.slides)) {
     presentation.slides.forEach((slide, slideIndex) => {
       if (!slide || typeof slide !== "object" || !slide.design || typeof slide.design !== "object") return;
-      try { note(opfCore.resolveScriptFonts(presentation, { slideIndex })); } catch { /* the renderer reports it when it draws the slide */ }
+      try { note(resolveScriptFonts(presentation, { slideIndex, ...(renderOptions?.catalogs !== undefined ? { catalogs: renderOptions.catalogs } : {}) })); } catch { /* the renderer reports it when it draws the slide */ }
     });
   }
   if (renderOptions?.catalogs) {
@@ -177,7 +172,8 @@ function* namedFontFamilies(value, key) {
  * `renderSvg` options) matter only for font schemes the host supplies in `renderOptions.catalogs`, which then resolve
  * like the renderer resolves them; a document that then does not resolve throws what `renderSvg` throws for it.
  */
-export function analyzePresentationScripts(presentation, profile = presentationScriptProfile(presentation), renderOptions) {
+export function analyzePresentationScripts(presentation, profile, renderOptions) {
+  profile ??= presentationScriptProfile(presentation, renderOptions);
   const scripts = new Set(), cjk = new Set();
   const design = designScripts(presentation, profile, renderOptions);
   // Han-only text in a deck whose language is not CJK draws with the scheme's own CJK face when the scheme names one.
@@ -230,13 +226,12 @@ export function autoScriptSelection(presentation, options) {
  * 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 = new Set([...analysis.detected, ...(analysis.design ?? [])].filter(script => cjkKeys.includes(script))).size;
   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)) {
+    for (const family of 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;
     }
@@ -244,8 +239,7 @@ export function nextFallbackPackage(analysis, { covers, loaded }) {
   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). */
+/** Drawn Han, kana or Hangul characters (at most `limit`) that no loaded script face covers. */
 export function uncoveredCjkCharacters(analysis, { covers, limit = 16 }) {
-  if (!hasGlyphFallback()) return [];
   return [...analysis.cjk].filter(character => !covers(character)).slice(0, limit);
 }

package/dist/script-fonts.js

@@ -16,8 +16,10 @@
 // is reported as a note. `glyphFallback: "none"` (strict mode) keeps the exact
 // faces and lets a missing glyph raise `missing-glyph`.
 
-import { fontPolicyFor } from "./font-policy.js";
-import { SYMBOL_PLACEHOLDER, SYMBOL_SCRIPT, mapSymbolText, symbolEncodingFor, symbolPreviewFaces } from "./symbol-fonts.js";
+import { fontPolicyFor } from "@openpresentation/opf/font-policy";
+import { scriptFontRole } from "@openpresentation/opf/composition";
+import { SYMBOL_PLACEHOLDER, SYMBOL_SCRIPT, mapSymbolAdvances, symbolEncodingFamily, symbolPreviewFaces } from "./symbol-fonts.js";
+export { scriptFontRole };
 
 const freeze = value => { if (value && typeof value === "object") { for (const child of Object.values(value)) freeze(child); Object.freeze(value); } return value; };
 
@@ -171,23 +173,10 @@ export function adjustedFontSize(size, adjust) {
 export const EMOJI_FONT_FAMILIES = SCRIPT_FONT_REPLACEMENTS.find(rule => rule.script === "Zsye").substitutes;
 const emojiFaces = new Set(EMOJI_FONT_FAMILIES);
 
-const eastAsianScripts = new Set(["Hani", "Hans", "Hant", "Hanb", "Jpan", "Kore", "Hang", "Jamo", "Hira", "Kana", "Hrkt", "Bopo", "Yiii"]);
-const complexScripts = new Set([
-  "Arab", "Hebr", "Syrc", "Thaa", "Nkoo", "Adlm", "Rohg", "Mand", "Samr",
-  "Deva", "Beng", "Guru", "Gujr", "Orya", "Taml", "Telu", "Knda", "Mlym", "Sinh",
-  "Thai", "Laoo", "Tibt", "Mymr", "Khmr", "Mong", "Bali", "Java", "Lana", "Tale", "Talu", "Cakm", "Olck",
-]);
 const rtlScripts = new Set(["Arab", "Hebr", "Syrc", "Thaa", "Nkoo", "Adlm", "Rohg", "Mand", "Samr"]);
 /** Scripts the latin slot covers directly; never split from the surrounding Latin run. */
 const latinGroup = new Set(["Latn", "Cyrl", "Grek", "Zyyy", "Zinh", "Zzzz"]);
 
-/** OOXML script slot for an ISO 15924 script code (the same table as core `scriptFontRole`). */
-export function scriptFontRole(script) {
-  if (eastAsianScripts.has(script)) return "eastAsian";
-  if (complexScripts.has(script)) return "complexScript";
-  return "latin";
-}
-
 const detected = ["Latn", "Cyrl", "Grek", "Hani", "Hira", "Kana", "Hang", "Bopo", "Yiii", "Arab", "Hebr", "Syrc", "Thaa", "Nkoo", "Adlm", "Rohg", "Mand", "Samr",
   "Deva", "Beng", "Guru", "Gujr", "Orya", "Taml", "Telu", "Knda", "Mlym", "Sinh", "Thai", "Laoo", "Tibt", "Mymr", "Khmr", "Mong", "Bali", "Java", "Lana",
   "Tale", "Talu", "Cakm", "Olck", "Armn", "Geor", "Ethi", "Cher", "Tfng", "Vaii", "Zinh", "Zyyy"].map(code => [code, new RegExp(String.raw`^\p{Script=${code}}$`, "u")]);
@@ -564,7 +553,7 @@ export function createScriptFonts(profile = {}, measurement, options = {}) {
       const hex = item.code.toString(16).toUpperCase().padStart(2, "0");
       if (!entry.codes.includes(hex) && entry.codes.length < 32) { entry.codes.push(hex); if (entry.characters.length < 16) entry.characters.push(item.source); }
     };
-    for (const item of mapSymbolText(encoding, text)) {
+    for (const item of mapSymbolAdvances(encoding, text)) {
       if (item.code === null) { foreign += item.source; continue; }
       flushForeign();
       let drawn = item.unicode, family = null, placeholder = false;
@@ -600,7 +589,7 @@ export function createScriptFonts(profile = {}, measurement, options = {}) {
     text = String(text ?? "");
     // A symbol-encoded family (resolved styles carry `symbolEncoding`; an unresolved style names the family itself) is mapped code by
     // code; `symbolEncoding: null` is the planner's own request for ordinary runs (characters that are not codes).
-    const encoding = style.symbolEncoding === null ? undefined : style.symbolEncoding ?? symbolEncodingFor(style.fontFamily)?.family;
+    const encoding = style.symbolEncoding === null ? undefined : style.symbolEncoding ?? symbolEncodingFamily(style.fontFamily);
     if (encoding) return text ? planSymbols(text, style, encoding) : [{text, family: style.fontFamily, own: true}];
     // An emoji face (Noto Color Emoji for a Segoe UI Emoji run) draws emoji-presentation clusters only: its Latin text and digits
     // are planned per cluster below, where they take a text face (FF-45).

package/dist/svg.d.ts

@@ -1,4 +1,5 @@
-import type { EmbeddedFont, ScriptFonts } from "./fonts.js";
+import type { RenderFonts, ScriptFonts } from "./fonts.js";
+import type { Catalog, Finding, UnresolvedReferenceDiagnostic } from "@openpresentation/opf";
 import type { SlideComposition, LayoutDiagnostic, TextMeasurement } from "@openpresentation/opf/composition";
 export declare const packageName = "@openpresentation/opf-render";
 
@@ -16,19 +17,12 @@ export declare const runtimePolicy: Readonly<{
   deterministicLocalExecution: true;
 }>;
 
+/** What draws when nothing resolves: core's engine defaults (OPF 0.15 ships no catalog records), and the chart type a chart without `type` previews as. */
 export declare const engineDefaults: Readonly<{
-  catalogs: Readonly<Record<string, Readonly<{ source: string }>>>;
-  theme: "minimal";
-  colorScheme: "cool-horizon";
-  language: "english";
-  narrative: "classic-story";
-  tone: "formal";
-  audience: "executives";
-  fontScheme: Readonly<{
-    pptx: Readonly<{ latin: "aptos"; ea: "microsoft-yahei"; cs: "nirmala-ui" }>;
-    google: Readonly<{ latin: "roboto"; ea: "noto-sans-sc"; cs: "noto-sans" }>;
-  }>;
-  chartTypes: readonly ["stacked-column-3x", "stacked-area-3x", "line-with-markers-3x"];
+  theme: typeof import("@openpresentation/opf/composition").ENGINE_DEFAULT_THEME;
+  colorScheme: typeof import("@openpresentation/opf/composition").ENGINE_DEFAULT_COLOR_SCHEME;
+  fontScheme: typeof import("@openpresentation/opf/composition").ENGINE_DEFAULT_FONT_SCHEME;
+  chartType: string;
 }>;
 
 export type RenderDiagnostic = LayoutDiagnostic | {
@@ -41,17 +35,10 @@ export type RenderDiagnostic = LayoutDiagnostic | {
   scripts: string[];
   characters: string[];
 } | {
-  code: "unsupported-pattern" | "variable-example-used" | "date-needs-value" | "language-preview-unavailable" | "language-preview-unresolved" | "paragraph-direction-unavailable";
+  code: "unsupported-pattern" | "variable-example-used" | "variable-builtin-missing" | "date-needs-value" | "language-preview-unresolved";
   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;
-} | {
+} | UnresolvedReferenceDiagnostic | {
   code: "unresolved-asset";
   path: string;
   message: string;
@@ -63,12 +50,18 @@ export type RenderDiagnostic = LayoutDiagnostic | {
 };
 
 export interface RenderSvgOptions {
-  textMeasurement?: TextMeasurement;
+  /** Leave out slides marked `hidden: true`, as the player does. Default false: one SVG per slide. With true the result holds only the visible slides, in order, so an index no longer names the slide at that index. Read by the deck-level `renderSvg`; `renderSlideSvg` draws the slide it is given. */
+  skipHidden?: boolean;
+  /**
+   * The fonts the deck is laid out and drawn with: the handle `loadFonts()` returns (from `@openpresentation/opf-render/fonts-node` or
+   * `/fonts-browser`), or any object with a `textMeasurement` and, to embed faces in each SVG, an `embeddedFonts` list. Without it layout uses
+   * core's portable width estimate and the SVG names the design fonts without embedding them.
+   */
+  fonts?: RenderFonts;
   /** `"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;
@@ -77,34 +70,38 @@ export interface RenderSvgOptions {
   /**
    * Values for the deck's template variables, keyed by variable id (core `resolveVariables`). A deck that uses
    * content variables, or is marked `template: true`, is resolved to a concrete deck first. A template previews with
-   * each unfilled variable's example (reported as `variable-example-used`); a normal deck with an unfilled required
+   * each unfilled variable's example (reported as `variable-example-used`; a built-in such as `{{speaker.name}}` with no source value is reported as `variable-builtin-missing`); a normal deck with an unfilled required
    * variable throws `unfilled-variables`. `false` draws the document as authored, with `{{id}}` tokens and
    * `var:id` references visible and nothing resolved: the view an editor uses while the template itself is edited.
    */
   variables?: Record<string, unknown> | false;
-  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[]>;
   /**
-   * Records for catalog sources the host has already fetched, keyed by the source string a document's
-   * `catalogs.<kind>.source` names (a single source or an ordered array; first match wins, the bundled
-   * default catalog is appended). The renderer never fetches a source itself.
+   * Catalogs the host registered (core `Catalog[]`), passed unchanged to core resolution: a reference the document does not
+   * embed resolves against the catalog whose `source` its group names, and the first entry is the default catalog for bare ids
+   * when the document omits `catalogs.default`. The renderer bundles and fetches no catalog; register the gallery snapshot with
+   * `import { defaultCatalog } from "@openpresentation/opf/catalog"` and `catalogs: [defaultCatalog]`. Omitted: only embedded
+   * records resolve, and anything else draws with core's engine defaults (reported as `unresolved-reference`).
+   * A malformed value throws core's `OPFCatalogsOptionError` (`code: "invalid-catalogs"`); a reference with an undeclared prefix
+   * (`foo:id` without `catalogs.foo`) fails the boundary check (`invalid-opf`, finding `opf/undeclared-catalog`).
    */
-  catalogSources?: Record<string, { records?: unknown[] } | unknown[]>;
+  catalogs?: readonly Catalog[];
+  /** Fail with `unresolved-reference` (an OPFRenderError whose `details.diagnostics` list the references) instead of falling back when a reference resolves nowhere. Default false. */
+  strictReferences?: boolean;
 }
 
 export interface SvgToPngOptions {
+  /** The fonts the conversion draws with (Node): see `SvgToPngOptions` in the main entry. */
+  fonts?: RenderFonts;
   scale?: number;
   background?: string;
   dpi?: number;
-  useBundledFonts?: boolean;
-  loadSystemFonts?: boolean;
-  fontFiles?: string[];
+  /** Extra directories of font files to draw with. */
   fontDirs?: string[];
   defaultFontFamily?: string;
   sansSerifFamily?: string;
@@ -128,7 +125,8 @@ export interface ResolvedSlide {
   index: number;
   path: string;
   slide: unknown;
-  layout: unknown;
+  /** The layout record the slide names; absent when it names none or a reference that resolves nowhere (the slide then composes automatically). */
+  layout?: unknown;
   design: {
     theme: unknown;
     colorScheme: unknown;
@@ -157,15 +155,18 @@ export interface RenderBinding {
 export declare class OPFRenderError extends Error {
   readonly code: string;
   readonly details: Record<string, unknown>;
-  readonly issues?: unknown[];
+  /** `invalid-opf`: the error findings of core `validate(presentation, { only: ["format"] })` (also `details.findings`; `details.report` is the whole report). */
+  readonly findings?: Finding[];
   readonly path?: string;
   constructor(code: string, message: string, details?: Record<string, unknown>);
 }
 
 export declare function resolvePresentation(input: unknown, options?: RenderSvgOptions): ResolvedPresentation;
 
-export declare function renderSvg(input: unknown, options?: RenderSvgOptions): string;
+/** The SVG of every slide of the deck, in order. */
+export declare function renderSvg(input: unknown, options?: RenderSvgOptions): string[];
 
-export declare function renderSvgDeck(input: unknown, options?: RenderSvgOptions): string[];
+/** The SVG of one slide of the deck (`index` is zero-based; out of range throws `slide-index-out-of-range`). */
+export declare function renderSlideSvg(input: unknown, index: number, options?: RenderSvgOptions): string;