@openpresentation/opf-render 0.14.0 → 0.16.0

package/dist/element.js

@@ -168,19 +168,22 @@ function createElementClass() {
     /** Open the full-screen slideshow (needs a user gesture to enter full screen). Loads the player on first use. */
     async present(options = {}) {
       if (this.#session && !this.#session.closed) return this.#session;
+      // Capture before loading the player: activeElement in the document is the shadow host, not its invoking button.
+      let returnFocus = options.returnFocus ?? this.ownerDocument.activeElement;
+      if (!options.returnFocus) while (returnFocus?.shadowRoot?.activeElement) returnFocus = returnFocus.shadowRoot.activeElement;
       await this.#readyPromise;
       if (!this.#store || !this.#cursor) throw new DeckError("not-ready", "The deck is not loaded yet.");
       const { present } = await import("./player.js");
       const session = await present(this.#deck, {
         store: this.#store, fonts: this.#fonts ?? this.#resolvedFonts, renderOptions: this.#renderOptions,
-        includeHidden: this.includeHidden, startSlide: this.#cursor.number, returnFocus: this.#parts.viewport, ...options,
+        includeHidden: this.includeHidden, startSlide: this.#cursor.number, ...options, returnFocus,
       });
       this.#session = session;
       session.addEventListener("slidechange", (event) => { if (this.#cursor && event.detail?.index !== undefined && this.#cursor.gotoIndex(event.detail.index)) { this.#show({ announce: false }); this.#emitChange(); } });
       session.addEventListener("close", () => {
         if (this.#session === session) this.#session = undefined;
         this.#show({ announce: false });
-        this.#parts.viewport?.focus({ preventScroll: true });
+        if (!returnFocus?.isConnected) this.#parts.viewport?.focus({ preventScroll: true });
         this.dispatchEvent(new CustomEvent("presentend", { detail: { slide: this.#cursor?.number } }));
       });
       this.dispatchEvent(new CustomEvent("presentstart", { detail: { slide: this.#cursor?.number } }));
@@ -253,9 +256,15 @@ function createElementClass() {
       if (this.#documentValue !== undefined) return parseDeckDocument(this.#documentValue);
       const src = this.getAttribute("src");
       if (src) {
-        const response = await fetch(new URL(src, this.ownerDocument.baseURI), { signal, credentials: "same-origin" });
-        if (!response.ok) throw new DeckError("fetch-failed", `The deck could not be loaded (${response.status}).`);
-        return parseDeckDocument(await response.text());
+        const source = new URL(src, this.ownerDocument.baseURI).href;
+        const response = await fetch(source, { signal, credentials: "same-origin" });
+        const details = {source, status: response.status, contentType: response.headers.get("content-type") ?? ""};
+        if (!response.ok) throw new DeckError("fetch-failed", `The deck could not be loaded (${response.status}) from ${source}.`, details);
+        const text = await response.text();
+        try { return parseDeckDocument(text); } catch (cause) {
+          const hint = /^\s*(?:<!doctype\s+html|<html\b|<head\b|<body\b)/i.test(text) ? " The response is HTML; check the deck URL and the host's SPA fallback route." : "";
+          throw new DeckError("invalid-document", `Invalid OPF from ${source} (${details.contentType || "unknown content type"}): ${cause.message}${hint}`, {...details, cause});
+        }
       }
       const inline = this.querySelector(':scope > script[type="application/opf+json"], :scope > script[type="application/json"]');
       if (inline) return parseDeckDocument(inline.textContent ?? "");
@@ -263,7 +272,8 @@ function createElementClass() {
     }
 
     #report(error, fatal) {
-      this.dispatchEvent(new CustomEvent("error", { detail: { code: error.code, message: error.message, fatal } }));
+      const {source, status, contentType} = error.details ?? {};
+      this.dispatchEvent(new CustomEvent("error", { detail: { code: error.code, message: error.message, fatal, ...(source ? {source, status, contentType} : {}) } }));
     }
 
     #prefetch() {
@@ -504,6 +514,8 @@ const escapeHtml = (value) => String(value).replace(/&/g, "&amp;").replace(/</g,
  *
  * `slides`: `"first"` (default: the first slide plus a list of titles), `"all"` or a list of 1-based slide numbers.
  * `embed` puts the document in an `application/opf+json` script child, so the element upgrades without a request.
+ * `fontMode`: `"standalone"` (default, embeds per slide), `"shared"` (one set of font rules in the returned tag), or
+ * `"external"` (no font rules; the host must supply CSS with the exact pinned faces the handle measures).
  */
 export function renderDeckHtml(input, options = {}) {
   const deck = parseDeckDocument(input);
@@ -512,13 +524,23 @@ export function renderDeckHtml(input, options = {}) {
   const wanted = options.slides ?? "first";
   const shown = wanted === "all" ? sequence.map((_, position) => position) : wanted === "first" ? [0] : wanted.map((number) => number - 1).filter((position) => position >= 0 && position < sequence.length);
   const handle = options.fonts !== null && typeof options.fonts === "object" ? options.fonts : undefined;
+  const fontMode = options.fontMode ?? "standalone";
+  if (!["standalone", "shared", "external"].includes(fontMode)) throw new DeckError("invalid-font-mode", "Choose standalone, shared or external SSR fonts.");
+  // Every mode measures with the same handle; external writes no @font-face data (RR-61 `embedFonts: false`).
+  const renderFonts = handle ?? options.renderOptions?.fonts;
+  const sharedRules = new Set();
   const attributes = { src: options.src, slide: options.slide, fonts: handle ? undefined : options.fonts, label: options.label, ...options.attributes };
   const attributeText = Object.entries(attributes).filter(([, value]) => value !== undefined && value !== false).map(([name, value]) => (value === true ? ` ${name}` : ` ${name}="${escapeHtml(value)}"`)).join("")
     + (options.thumbnails ? " thumbnails" : "") + (options.present ? " present" : "") + (options.includeHidden ? " include-hidden" : "");
   const date = options.renderOptions?.date ?? options.date;
   const figures = shown.map((position) => {
     const index = sequence[position];
-    const svg = renderSlideSvg(deck, index, { ...options.renderOptions, ...(handle ? { fonts: handle } : {}), ...(date ? { date } : {}) });
+    let svg = renderSlideSvg(deck, index, { ...options.renderOptions, fonts: renderFonts, ...(fontMode === "external" ? { embedFonts: false } : {}), ...(date ? { date } : {}) });
+    if (fontMode === "shared") svg = svg.replace(/<style>(@font-face[\s\S]*?)<\/style>/g, (_, css) => {
+      // These rules are produced by renderSlideSvg after its used-face selection and validation.
+      for (const rule of css.split("\n")) sharedRules.add(rule);
+      return "";
+    });
     const { width, height } = svgDimensions(svg);
     const prepared = prepareSlideSvg(svg).replace(/^<svg\b/, `<svg style="display:block;width:100%;height:auto;aspect-ratio:${width} / ${height}"`);
     const label = slideLabel(slideInfo(deck, index), position + 1, sequence.length);
@@ -527,5 +549,6 @@ export function renderDeckHtml(input, options = {}) {
   const titles = wanted === "first" && sequence.length > 1
     ? `<nav aria-label="Slides"><ol>${sequence.map((index) => `<li>${escapeHtml(slideInfo(deck, index).title)}</li>`).join("")}</ol></nav>` : "";
   const embedded = options.embed ? `<script type="application/opf+json">${JSON.stringify(deck).replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029")}</script>` : "";
-  return `<${tag}${attributeText}>${figures.join("")}${titles}${embedded}</${tag}>`;
+  const shared = sharedRules.size ? `<style>${[...sharedRules].join("\n")}</style>` : "";
+  return `<${tag}${attributeText}>${shared}${figures.join("")}${titles}${embedded}</${tag}>`;
 }

package/dist/export-browser.d.ts

@@ -13,6 +13,12 @@ export interface BrowserSvgToPngOptions {
 export interface BrowserSvgToPdfOptions extends Pick<SvgToPdfOptions, "mode" | "background" | "serifFamily" | "metadata" | "tagged" | "compress" | "strict" | "rasterFallbackScale" | "defaultFontFamily" | "sansSerifFamily" | "monospaceFamily" | "onDiagnostic"> {
   /** Raster mode: pixel density of each page image (default 2). */
   scale?: number;
+  /**
+   * Raster mode only: the pdf-lib module (`import * as pdfLib from "pdf-lib"`), an optional peer of the renderer that this entry never imports itself, so a
+   * bundle of it holds no PDF library. Without it raster mode tries to import "pdf-lib" by name and rejects with `OPFRenderError` `converter-missing`
+   * when the page cannot. The default vector mode needs no option.
+   */
+  pdfLib?: { PDFDocument: { create(options?: { updateMetadata?: boolean }): Promise<any> } };
   /**
    * The browser fonts handle (`loadFonts` from `/fonts-browser`): every face it holds can be embedded in the PDF, including script faces
    * a standalone SVG does not carry. Faces an SVG embeds as `@font-face` data (the `embeddedFonts` of the handle `renderSvg` was given) need no entry.

package/dist/export-browser.js

@@ -8,6 +8,9 @@ import { OPFRenderError, packageName } from "./svg.js";
 // to hand one over) and nothing is fetched: faces come from the SVG's own @font-face data (the `embeddedFonts` of the fonts handle
 // `renderSvg` was given), from the faces the `fonts` handle holds (`loadFonts` from `/fonts-browser`, so script faces the SVG does not
 // embed reach the PDF too), or from `fontData`.
+//
+// RR-63: this entry imports no converter. The one optional piece is pdf-lib, for `mode: "raster"` only (the default vector PDF
+// needs nothing): the host imports it and passes it as `options.pdfLib`, so a bundler never has to resolve it.
 
 const DEFAULT_DIMENSIONS = { width: 1280, height: 720 };
 const MAX_PIXELS = 40_000_000;
@@ -32,7 +35,7 @@ export async function svgToPng(svg, options = {}) {
  * Convert SVG slides to a PDF, one slide per page (1 SVG pixel is 1 PDF point, as in Node). `mode: "vector"` (default) writes
  * real text, paths, gradients and images; `"raster"` draws each slide as an image (`scale`, default 2). Takes the options of
  * the Node `svgToPdf` that make sense here (`metadata`, `tagged`, `strict`, `compress`, `onDiagnostic`, the generic family
- * names, `rasterFallbackScale`), `fonts` (the handle `loadFonts()` returns: every face it holds can be embedded), `fontData`
+ * names, `rasterFallbackScale`), `pdfLib` (raster mode only: `import * as pdfLib from "pdf-lib"`), `fonts` (the handle `loadFonts()` returns: every face it holds can be embedded), `fontData`
  * (`[{ data, family? }]`, extra face bytes without a handle), `signal` (an AbortSignal, checked between pages) and
  * `onProgress({ page, pages })`.
  */
@@ -70,7 +73,7 @@ export async function svgToPdf(svgs, options = {}) {
 }
 
 async function rasterPdf(inputs, options) {
-  const { PDFDocument } = await import("pdf-lib");
+  const { PDFDocument } = options.pdfLib ?? await importPdfLib();
   const pdf = await PDFDocument.create({ updateMetadata: false });
   pdf.setCreator(packageName);
   pdf.setProducer(packageName);
@@ -87,6 +90,17 @@ async function rasterPdf(inputs, options) {
   return pdf.save({ addDefaultPage: false, useObjectStreams: false });
 }
 
+// pdf-lib for raster mode when the host did not pass it. The specifier is not a literal, so a browser bundler leaves it alone (and
+// never fails for a host that does not install pdf-lib); it resolves where the page can import it by name, for example with an import map.
+async function importPdfLib() {
+  const name = "pdf-lib";
+  try {
+    return await import(/* webpackIgnore: true */ /* @vite-ignore */ name);
+  } catch (error) {
+    throw new OPFRenderError("converter-missing", 'Raster-mode PDF output needs pdf-lib, an optional peer dependency of @openpresentation/opf-render: run `npm install pdf-lib@^1.17.1` and pass it as the pdfLib option (import * as pdfLib from "pdf-lib"). The default vector mode needs nothing.', { package: "pdf-lib", range: "^1.17.1", install: "npm install pdf-lib@^1.17.1", cause: error instanceof Error ? error.message : String(error) });
+  }
+}
+
 // ---------------------------------------------------------------------------------------------------------------------------
 // Canvas
 

package/dist/font-registry.js

@@ -295,8 +295,8 @@ export function createFontRegistry(entries, options = {}) {
     resolveFont(style) { return resolve(style).resolution; },
     clearSubstitutions() { substitutions.clear(); },
     get substitutions() { return [...substitutions.values()]; },
-    // Faces flagged embed:"used" (the open pack, FF-31) are not in this eager list: supplied with selectEmbeddedFonts (or
-    // the `loadFonts` handle's embeddedFonts) they are embedded only in SVGs whose text names their family.
+    // Faces flagged embed:"used" (the open pack, FF-31) are not in this eager list: they come with selectEmbeddedFonts (or the
+    // `loadFonts` handle's embeddedFonts). Whichever list it is given, the SVG writer embeds a face only where its text draws it (RR-61).
     get embeddedFonts() { return embedded(face=>face.embed!=="used"); },
     /** Parsed face metadata in entry order, without encoding font bytes. */
     describeFaces: ()=>faces.map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.scripts?{scripts:[...face.scripts]}:{}),...(face.fallbackOnly?{fallbackOnly:true}:{})})),
@@ -320,5 +320,5 @@ export function createFontRegistry(entries, options = {}) {
       return made.map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.scripts?{scripts:[...face.scripts]}:{})}));
     },
   };
-  function embedded(predicate) { return faces.filter(face=>predicate({family:face.family,weight:face.weight,italic:face.italic,scripts:face.scripts,embed:face.embed,fallbackOnly:face.fallbackOnly})).map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.license ? {license:face.license} : {}),...(face.embed==="used" ? {embed:"used"} : {}),dataUrl:`data:font/${face.format};base64,${base64(face.data)}`})); }
+  function embedded(predicate) { return faces.filter(face=>predicate({family:face.family,weight:face.weight,italic:face.italic,scripts:face.scripts,embed:face.embed,fallbackOnly:face.fallbackOnly})).map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.license ? {license:face.license} : {}),...(face.embed ? {embed:face.embed} : {}),dataUrl:`data:font/${face.format};base64,${base64(face.data)}`})); }
 }

package/dist/fonts-node.js

@@ -25,10 +25,24 @@ async function verifiedFile(file, expected, details) {
 // The default Latin, Cyrillic and Greek glyph-fallback face (the office pack always loads it, fallback-only).
 const FALLBACK_PACKAGE = "@expo-google-fonts/noto-sans";
 
+// RR-63: every `@expo-google-fonts/*` package is an optional peer dependency, so a host installs only the faces it uses. A request that
+// needs packages that are not installed fails once, naming all of them and the install command, instead of one package at a time.
+function requireInstalled(packages, what) {
+  const missing = packages.filter(pkg => {
+    if (pkg.vendored) return false;
+    try { require.resolve(`${pkg.name}/package.json`); return false; } catch { return true; }
+  });
+  if (!missing.length) return;
+  const install = `npm install ${missing.map(pkg => `${pkg.name}@${pkg.version}`).join(" ")}`;
+  throw new OPFFontError("font-resource-unavailable", `${what} needs font packages that are not installed (optional peer dependencies of @openpresentation/opf-render): run \`${install}\`.`, {packages: missing.map(pkg => pkg.name), install});
+}
+
 // `skipped`: an optional npm package that is not installed is recorded there instead of failing (scripts: 'auto').
 // `fallbackOnly`: the faces serve glyph fallback and requests by their own name, never a replacement for another family.
-async function loadPackages(packages, skipped, {fallbackOnly = false} = {}) {
+// `what`: how the request is named in the error for a package that is not installed, for example "The 'office' font pack".
+async function loadPackages(packages, skipped, {fallbackOnly = false, what = "This font request"} = {}) {
   const entries = [], fontFiles = [];
+  if (!skipped) requireInstalled(packages, what);
   for (const pkg of packages) {
     if (pkg.vendored) {
       // FF-31: vendored faces ship inside this package (pkg.vendored, for example fonts/carlito), hash-pinned like the npm packs. The open pack is
@@ -53,7 +67,7 @@ async function loadPackages(packages, skipped, {fallbackOnly = false} = {}) {
       installed = JSON.parse(await readFile(manifestPath, "utf8"));
     } catch (error) {
       if (skipped) { skipped.push({package: pkg.name, version: pkg.version, scripts: [...pkg.scripts]}); continue; }
-      throw new OPFFontError("font-resource-unavailable", `Install ${pkg.name}@${pkg.version} to use this offline font pack.`, {package:pkg.name, cause:error.code});
+      throw new OPFFontError("font-resource-unavailable", `Install ${pkg.name}@${pkg.version} to use ${what}.`, {package:pkg.name, cause:error.code});
     }
     if (installed.version !== pkg.version) throw new OPFFontError("font-version-mismatch", `Expected ${pkg.name}@${pkg.version}; reinstall the pinned package.`, {package:pkg.name, expected:pkg.version, actual:installed.version});
     const directory = path.dirname(manifestPath);
@@ -73,7 +87,7 @@ async function loadPackages(packages, skipped, {fallbackOnly = false} = {}) {
 const renamedAliases = () => Object.fromEntries(BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === "open" && item.renamedFrom).map(item => [item.renamedFrom, item.faces[0].family]));
 // The vendored faces this registry holds that are embed "used": a host that serves fonts itself lists them to copy their files.
 const lazyOf = registry => lazyFontList().filter(face => registry.describeFaces().some(held => held.family === face.family && held.weight === face.weight && held.italic === face.italic));
-const loadPack = pack => loadPackages(BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === pack));
+const loadPack = pack => loadPackages(BUNDLED_FONT_MANIFEST.packages.filter(item => item.pack === pack), undefined, {what: `The '${pack}' font pack`});
 
 /**
  * Adds the script pack. `scripts` is 'all', ISO 15924 codes, or 'auto' (FF-19): detect the scripts the
@@ -86,7 +100,7 @@ async function withScripts(loaded, scripts, {presentation, onDiagnostic, renderO
   // A package the registry already loaded (the default Noto Sans fallback) is never loaded twice.
   const notLoaded = list => list.filter(pkg => !loaded.packages?.includes(pkg.name));
   if (scripts !== "auto") {
-    const extra = await loadPackages(notLoaded(scriptFontPackages(scripts)));
+    const extra = await loadPackages(notLoaded(scriptFontPackages(scripts)), undefined, {what: `The requested script fonts (${Array.isArray(scripts) ? scripts.join(", ") : scripts})`});
     return {...loaded, entries:[...loaded.entries, ...embedUsed(extra.entries)], fontFiles:[...loaded.fontFiles, ...extra.fontFiles], packages:[...(loaded.packages ?? []), ...extra.packages]};
   }
   if (presentation === null || typeof presentation !== "object") throw new OPFFontError("invalid-font-scripts", "scripts: 'auto' needs the presentation whose text decides the scripts.", {scripts});
@@ -160,6 +174,11 @@ async function withFaces(loaded, faces) {
  */
 async function buildRegistry(pack, {scripts, faces, presentation, onDiagnostic, renderOptions, ...options}) {
   let loaded, registryOptions = options;
+  // RR-63: name every npm font package the pack needs at once, before loading any of them.
+  if (pack === "base" || pack === "office") {
+    const packs = pack === "base" ? ["base"] : ["office", ...(options.includeBaseFonts === false ? [] : ["base"])];
+    requireInstalled([...BUNDLED_FONT_MANIFEST.packages.filter(item => packs.includes(item.pack)), ...(pack === "office" ? scriptFontPackages(["Latn"]) : [])], `The '${pack}' font pack`);
+  }
   if (pack === "office") {
     const {entries, fontFiles, packages} = await loadPack("office");
     for (const [include, name] of [[options.includeOpenFonts, "open"], [options.includeBaseFonts, "base"]]) {
@@ -177,7 +196,7 @@ async function buildRegistry(pack, {scripts, faces, presentation, onDiagnostic,
     // an explicit list does; a presentation that does not select Latn keeps it fallback-only.
     const requested = scripts === "auto" && presentation !== null && typeof presentation === "object" ? scriptFontPackages(autoScriptSelection(presentation, renderOptions).scripts).map(pkg => pkg.name)
       : scripts === undefined || scripts === "auto" || (Array.isArray(scripts) && !scripts.length) ? [] : scriptFontPackages(scripts).map(pkg => pkg.name);
-    const fallback = await loadPackages(scriptFontPackages(["Latn"]).filter(pkg => !requested.includes(pkg.name)), undefined, {fallbackOnly:true});
+    const fallback = await loadPackages(scriptFontPackages(["Latn"]).filter(pkg => !requested.includes(pkg.name)), undefined, {fallbackOnly:true, what: "The 'office' font pack (its default glyph-fallback face)"});
     fontFiles.push(...fallback.fontFiles);
     entries.push(...fallback.entries);
     packages.push(...fallback.packages);

package/dist/fonts.d.ts

@@ -8,8 +8,8 @@ export type { FontPolicyEntry } from "@openpresentation/opf/font-policy";
 export { isSymbolEncodedFamily, mapSymbolText, symbolCodeOf } from "@openpresentation/opf/symbol-font-encodings";
 export { scriptFontRole } from "@openpresentation/opf/composition";
 export type { ScriptRole } from "@openpresentation/opf/composition";
-export interface FontFaceInput { data: Uint8Array; family?: string; weight?: number; italic?: boolean; postscriptName?: string; license?: string; /** Serves glyph fallback and requests by its own family only; never a replacement for another family. */ fallbackOnly?: boolean; /** "used" embeds the face in an SVG only when the slide's text names its family (the open pack, FF-31). Default "always". */ embed?: "always" | "used"; /** ISO 15924 scripts a designated script replacement face serves (FF-19). */ scripts?: string[] }
-export interface EmbeddedFont { family: string; weight: number; italic?: boolean; dataUrl: string; license?: string; embed?: "used" }
+export interface FontFaceInput { data: Uint8Array; family?: string; weight?: number; italic?: boolean; postscriptName?: string; license?: string; /** Serves glyph fallback and requests by its own family only; never a replacement for another family. */ fallbackOnly?: boolean; /** Every face is embedded in an SVG only when the slide's text draws it (RR-61). "used" also leaves the face out of the eager `registry.embeddedFonts` list (the open pack, FF-31); "always" embeds it in every SVG. */ embed?: "always" | "used"; /** ISO 15924 scripts a designated script replacement face serves (FF-19). */ scripts?: string[] }
+export interface EmbeddedFont { family: string; weight: number; italic?: boolean; dataUrl: string; license?: string; /** "always": written into every SVG; otherwise only into an SVG whose text draws the face (RR-61). */ embed?: "always" | "used" }
 export type FontCompatibility = "exact" | "metric" | "visual" | "generic";
 export interface FontReplacementMeasurement { replacement:string; meanAbsWidthDelta:number; meanWidthDelta:number; maxAbsWidthDelta:number; styles:number; reference:string }
 export interface FontResolution {
@@ -41,7 +41,7 @@ export declare const EXPERIMENTAL_FONT_CANDIDATES: readonly Readonly<{requestedF
 export interface RenderFonts {
   /** Measures text with the real faces. Without it layout uses core's portable estimate. */
   textMeasurement?: TextMeasurement;
-  /** Faces `renderSvg` writes into each SVG as @font-face data; a face flagged `embed: "used"` only when a slide draws its family. */
+  /** Faces `renderSvg` may write into an SVG as @font-face data: each only into the SVGs whose text draws it (its family, weight and style), unless flagged `embed: "always"` (RR-61). */
   embeddedFonts?: readonly EmbeddedFont[];
   /** Font files the Node raster and PDF conversions draw with. */
   fontFiles?: readonly string[];

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { RenderFonts, ScriptFonts } from "./fonts.js";
-import type { Finding } from "@openpresentation/opf";
+import type { Catalog, Finding, UnresolvedReferenceDiagnostic } from "@openpresentation/opf";
 import type { SlideComposition, LayoutDiagnostic, TextMeasurement } from "@openpresentation/opf/composition";
 export declare const packageName = "@openpresentation/opf-render";
 
@@ -17,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", "stacked-area", "line-with-markers"];
+  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 | {
@@ -45,20 +38,7 @@ export type RenderDiagnostic = LayoutDiagnostic | {
   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;
-} | {
-  /** A layout, theme or colour-scheme id matched no record: the slide composed with no layout record, the `minimal` theme or the `cool-horizon` colour scheme. Never an error. */
-  code: "unresolved-layout" | "unresolved-theme" | "unresolved-color-scheme";
-  path: string;
-  message: string;
-  id: string;
-} | {
+} | UnresolvedReferenceDiagnostic | {
   code: "unresolved-asset";
   path: string;
   message: string;
@@ -74,10 +54,12 @@ export interface RenderSvgOptions {
   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
+   * `/fonts-browser`), or any object with a `textMeasurement` and, to embed faces, an `embeddedFonts` list (each SVG carries only the faces its text draws). Without it layout uses
    * core's portable width estimate and the SVG names the design fonts without embedding them.
    */
   fonts?: RenderFonts;
+  /** `false` writes no `@font-face` data into the SVG (RR-61): the fonts handle still measures and the SVG still names the families, for a host whose page already has the faces (a browser `loadFonts` handle adds them to the document). Default true: each SVG embeds the faces of `fonts.embeddedFonts` its own text draws. */
+  embedFonts?: boolean;
   /** `"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. */
@@ -100,13 +82,18 @@ export interface RenderSvgOptions {
    */
   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 {
@@ -233,7 +220,7 @@ export interface ResolvedSlide {
   index: number;
   path: string;
   slide: unknown;
-  /** The layout record the slide names; absent when it names none or an id no catalog has (the slide then composes with no layout). */
+  /** 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;

package/dist/pdf-vector.js

@@ -724,6 +724,8 @@ class Converter {
         result = { resource, object, width: info.width, height: info.height };
       }
     } catch (error) {
+      // A missing converter is the host's install, not a bad picture: say so instead of writing a PDF without its pictures.
+      if (error?.code === "converter-missing") throw error;
       this.unsupported("pdf-image-skipped", `An embedded image could not be decoded and is not drawn: ${error instanceof Error ? error.message : String(error)}`, { path: tracePath });
     }
     this.images.set(digest, result);

package/dist/pdf.d.ts

@@ -0,0 +1,2 @@
+export { svgToPdf } from "./index.js";
+export type { SvgToPdfOptions, PdfDiagnostic, PdfMetadata } from "./index.js";

package/dist/pdf.js

@@ -0,0 +1,4 @@
+// RR-63: the PDF format entry (Node). The default vector `svgToPdf` needs no converter for text and shapes; it loads the optional peer
+// `sharp` for pictures and `@resvg/resvg-js` for the rare element it rasterizes, and `mode: "raster"` also loads `pdf-lib`. A converter
+// that is not installed rejects with `OPFRenderError` code `converter-missing`. For a page use `@openpresentation/opf-render/export-browser`.
+export { svgToPdf } from "./raster.js";

package/dist/player.d.ts

@@ -7,7 +7,8 @@ import type { RenderSvgOptions } from "./svg.js";
  */
 export declare class DeckError extends Error {
   readonly code: string;
-  constructor(code: string, message: string, options?: { cause?: unknown });
+  readonly details?: {source: string; status?: number; contentType?: string};
+  constructor(code: string, message: string, options?: { cause?: unknown; source?: string; status?: number; contentType?: string });
 }
 
 /** The slide that is showing, in the sequence that plays (hidden slides are not counted). `notes` is plain text. */

package/dist/png.d.ts

@@ -0,0 +1,2 @@
+export { svgToPng } from "./index.js";
+export type { SvgToPngOptions } from "./index.js";

package/dist/png.js

@@ -0,0 +1,4 @@
+// RR-63: the PNG format entry (Node). `svgToPng` loads the optional peers `@resvg/resvg-js` (and `sharp` for WebP and rotated JPEG
+// pictures) on first use and rejects with `OPFRenderError` code `converter-missing` when they are not installed. For a page use
+// `@openpresentation/opf-render/export-browser`.
+export { svgToPng } from "./raster.js";

package/dist/preview-fonts-node.js

@@ -1,7 +1,7 @@
 // RR-28: fill a self-hosted font root (the layout of `preview-fonts.js`) from the installed packages, for hosts that serve
 // `<opf-deck fonts="/opf-fonts/">`. Node only. Every file is copied unmodified and checked against its pinned SHA-256 and
 // every license notice travels with it (LICENSES.txt). Nothing is downloaded: the faces come from this package's `fonts`
-// directory and the installed `@expo-google-fonts/*` packages.
+// directory and the installed `@expo-google-fonts/*` packages (optional peer dependencies of this package: install the ones you copy).
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -50,7 +50,7 @@ export function copyPreviewFonts({ outDir, scripts = false, cwd, manifest = BUND
     const sourceDirectory = pkg.vendored ? within(rendererRoot, pkg.vendored) : resolvePackageDirectory(pkg.name, cwd);
     if (!sourceDirectory || !fs.existsSync(sourceDirectory)) {
       if (pkg.pack === "scripts") { missing.push(pkg.name); continue; }
-      throw new Error(`${pkg.name} is not installed: reinstall @openpresentation/opf-render.`);
+      throw new Error(`${pkg.name} is not installed: it is an optional peer dependency of @openpresentation/opf-render, so run "npm install ${pkg.name}@${pkg.version}".`);
     }
     if (!pkg.vendored) {
       const installed = JSON.parse(fs.readFileSync(path.join(sourceDirectory, "package.json"), "utf8"));

package/dist/raster-images.js

@@ -1,4 +1,5 @@
 import {OPFRenderError} from './svg.js';
+import {isConverterMissing,loadConverter} from './converters.js';
 
 // Resvg does not decode WebP or apply JPEG EXIF orientation, and draws no text of an SVG used as an image (its nested
 // document has no fonts). Replace only affected embedded image hrefs in the private
@@ -27,6 +28,7 @@ export async function prepareRasterImages(svg, {nestedSvg} = {}) {
       const replacement = href[0].slice(0, href[0].indexOf(href[1]) + 1) + png + href[1];
       tag = tag.slice(0, href.index) + replacement + tag.slice(href.index + href[0].length);
     } catch (error) {
+      if (isConverterMissing(error)) throw error;
       throw new OPFRenderError('image-conversion-failed', 'Embedded raster image could not be prepared for PNG/PDF output.', {path, cause:error instanceof Error ? error.message : String(error)});
     }
     output += svg.slice(end, match.index) + tag;
@@ -74,7 +76,7 @@ async function prepareRasterImage(uri) {
   } else if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8 || bytes[2] !== 0xff) {
     throw new Error('Embedded data is not a JPEG image.');
   }
-  const {default:sharp}=await import('sharp');
+  const {default:sharp}=await loadConverter('sharp');
   const decoder=sharp(bytes,{limitInputPixels:40_000_000,animated:false,failOn:'warning'});
   if (!webp) {
     const {orientation}=await decoder.metadata();

package/dist/raster.js

@@ -3,6 +3,7 @@ import {OPFRenderError,packageName} from './svg.js';
 import {separateLigatures} from './font-compatibility.js';
 import {monochromeColorFonts,rasterFontFiles} from './color-fonts.js';
 import {pinScriptClusters} from './raster-text.js';
+import {loadConverter} from './converters.js';
 const DEFAULT_DIMENSIONS = { width: 1280, height: 720 };
 const DEFAULT_RASTER_SCALE = 1;
 const DEFAULT_RASTER_BACKGROUND = "#FFFFFF";
@@ -100,7 +101,7 @@ async function vectorPdf(inputs, options) {
 // The picture decoder of the Node vector export (the browser entry passes a canvas one). sharp loads on first use.
 function sharpImageCodec() {
   let loaded;
-  const sharp = () => (loaded ??= import("sharp").then((module) => module.default));
+  const sharp = () => (loaded ??= loadConverter("sharp").then((module) => module.default));
   return {
     metadata: async (bytes) => (await sharp())(bytes, { limitInputPixels: 40_000_000, animated: false }).metadata(),
     rgba: async (bytes, { orient }) => {
@@ -162,25 +163,8 @@ async function rasterizeSvg(svgInput, options) {
   }
 }
 
-async function loadResvg() {
-  try {
-    return await import("@resvg/resvg-js");
-  } catch (error) {
-    throw new OPFRenderError("png-renderer-unavailable", "PNG/PDF conversion requires the Node runtime dependency @resvg/resvg-js.", {
-      cause: error instanceof Error ? error.message : String(error)
-    });
-  }
-}
-
-async function loadPdfLib() {
-  try {
-    return await import("pdf-lib");
-  } catch (error) {
-    throw new OPFRenderError("pdf-writer-unavailable", "PDF conversion requires the runtime dependency pdf-lib.", {
-      cause: error instanceof Error ? error.message : String(error)
-    });
-  }
-}
+const loadResvg = () => loadConverter("@resvg/resvg-js");
+const loadPdfLib = () => loadConverter("pdf-lib");
 
 async function bundledFontFiles() {
   if (!bundledFontFilesCache) {

package/dist/script-font-pack.js

@@ -92,10 +92,10 @@ export function* drawnStrings(presentation) {
 /**
  * The script profile of a presentation: core `resolveScriptFonts` output, exactly what the renderer plans
  * with. When it throws, the renderer ignores the document language, so the profile is empty and Han text is
- * Simplified Chinese, as drawn.
+ * Simplified Chinese, as drawn. `renderOptions.catalogs` (the host's registered catalogs) resolve as they do for the renderer.
  */
-export function presentationScriptProfile(presentation) {
-  try { return 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 {};
 }
 
@@ -123,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();
@@ -142,7 +142,7 @@ function designScripts(presentation, profile, renderOptions) {
   if (Array.isArray(presentation?.slides)) {
     presentation.slides.forEach((slide, slideIndex) => {
       if (!slide || typeof slide !== "object" || !slide.design || typeof slide.design !== "object") return;
-      try { note(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) {
@@ -172,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.