@openpresentation/opf-render 0.0.1 → 0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # OPF Render
 
-Deterministic local renderer for Open Presentation Format documents. This repo is the Phase 1 toolkit lane for SVG, PNG, and PDF output.
+Deterministic local renderer for Open Presentation Format documents. The shared SVG core implements validation, catalog resolution, placeholder binding and text layout. Node APIs additionally convert SVG to PNG and raster-backed PDF.
 
 ## Scope
 
@@ -8,9 +8,48 @@ Deterministic local renderer for Open Presentation Format documents. This repo i
 - Repository: `OpenPresentation/opf-render`
 - License: MIT
 - Compatibility target: `@openpresentation/opf`
-- Planned public API: `renderSvg(opf, opts)`, `svgToPng(svg, opts)`, and `svgToPdf(svgs, opts)`
+- Public API: `renderSvg(opf, opts)`, `renderSvgDeck(opf, opts)`, `resolvePresentation(opf, opts)`, `svgToPng(svg, opts)`, and `svgToPdf(svgs, opts)`
 
-Feature implementation is intentionally not in this provisioning slice. The first implementation task owns validation, catalog resolution, placeholder binding, SVG emission, and deterministic golden tests.
+`renderSvg` renders a single slide selected by `opts.slideIndex` (default `0`). `renderSvgDeck` returns one SVG string per slide. Both validate OPF at the boundary via `@openpresentation/opf`, resolve inline and bundled catalogs locally, and emit byte-stable SVG for the same input.
+
+```js
+import { renderSvgDeck } from "@openpresentation/opf-render";
+
+const svgs = renderSvgDeck(opf, { trace: true });
+```
+
+Set `trace: true` to stamp rendered SVG elements with `data-opf-path` values such as `slides.0.title`; omit it for smaller production SVG.
+
+PNG and PDF conversion APIs are async because they load the local raster/PDF engines on demand:
+
+```js
+import { renderSvgDeck, svgToPdf, svgToPng } from "@openpresentation/opf-render";
+
+const svgs = renderSvgDeck(opf);
+const png = await svgToPng(svgs[0], { scale: 1 });
+const pdf = await svgToPdf(svgs, { scale: 1 });
+```
+
+`svgToPng` returns PNG bytes for one SVG. `svgToPdf` accepts one SVG or an array of SVGs and returns PDF bytes with one slide per page. The SVG page `width`/`height` or `viewBox` determines the PDF page size; `scale` controls raster density only.
+
+## Browser preview and fonts (preview APIs)
+
+Use `@openpresentation/opf-render/svg` for browser rendering without Node dependencies. Browser-aware bundlers also select this shared SVG implementation for the root import; Node's root import retains PNG/PDF conversion.
+
+```js
+import { renderSvg } from '@openpresentation/opf-render/svg';
+import { loadBrowserFontRegistry } from '@openpresentation/opf-render/fonts-browser';
+
+const fonts = await loadBrowserFontRegistry(fontFileEntries);
+container.innerHTML = renderSvg(presentation, {
+  textMeasurement: fonts.textMeasurement,
+});
+// fonts.dispose() when its canvases are unmounted.
+```
+
+Each entry contains `url` or `data: Uint8Array`, with optional `family`, `weight`, `italic` and `license`. The loader registers browser FontFaces using the same bytes used for measurement. It fetches only URLs supplied by the host, supports an AbortSignal and custom fetch, and awaits font loading. Use pinned static faces and retain their licenses. For standalone SVG export also pass `embeddedFonts: fonts.embeddedFonts`; embedding is unnecessary for each live draft after browser fonts are loaded.
+
+The new entries require coordinated preview builds of OPF and the toolkit. The sibling OPF repository's `pnpm pack:ecosystem` prepares local npm tarballs; older registry releases do not include these APIs. See `opf/docs/live-editor.md` for installation and the fidelity contract. Identical SVG geometry does not guarantee identical raster pixels across browser engines or PowerPoint.
 
 ## Runtime Policy
 
@@ -23,22 +62,50 @@ The package runtime must stay local and deterministic:
 - No clock, locale, random, or system-font fallback drift in render output
 - Host applications own auth, storage, queues, analytics, collaboration, and product workflow
 
+Dependency policy:
+
+- `@openpresentation/opf` is the compatibility source for schemas, validation, and bundled catalogs.
+- `@resvg/resvg-js` is used only for local SVG rasterization in Node; it makes no network calls and does not require a browser.
+- `pdf-lib` assembles PDF bytes locally. Metadata timestamps are disabled so repeated PDF output is byte-stable for the same SVG input and options.
+- Bundled OFL Roboto and Roboto Mono TTF files provide the default deterministic font fallback.
+- `svgToPng` and `svgToPdf` disable system-font loading by default. Hosts that require branded fonts should pass explicit `fontFiles` or `fontDirs`; `loadSystemFonts: true` is an opt-in escape hatch and can make output environment-dependent.
+
+Browser support boundary: `renderSvg`, `renderSvgDeck`, and `resolvePresentation` are browser-importable pure JavaScript APIs. `svgToPng` and `svgToPdf` are Node APIs in this package version because they depend on the Node build of resvg.
+
 ## Development
 
 ```sh
 npm ci
 npm run build
+npm run typecheck
 npm run validate
+npm test
+```
+
+When this repo is checked out beside `openpresentation/opf`, `npm test` also renders every `examples/**/*.opf.json` deck twice and asserts byte-identical SVG output. Golden PNG drift is checked on every run against all 805 slides from the installed core package, identified by a content digest. Changed or missing corpora fail; Git history cannot skip the gate. To generate a review candidate after an intentional visual change:
+
+```sh
+npm run golden:update
 ```
 
 ## Release Lane
 
-Public npm package publication is handled by `.github/workflows/release.yml` with npm provenance.
+Public npm package publication is handled by `.github/workflows/npm-publish.yml` with npm provenance.
 
 Required first-publish setup:
 
 1. An npm owner for the `@openpresentation` scope must run the first publish or reserve/grant the `@openpresentation/opf-render` package.
-2. Configure npm Trusted Publishing for GitHub repository `OpenPresentation/opf-render` and workflow `.github/workflows/release.yml`.
-3. Publish by creating a GitHub Release or manually running the Release workflow after CI passes.
+2. Configure npm Trusted Publishing for GitHub repository `OpenPresentation/opf-render` and workflow `.github/workflows/npm-publish.yml`.
+3. Publish by pushing a git tag matching `opf-render-v<version>` or `@openpresentation/opf-render@v<version>` (the tag must match the `package.json` version), or by manually running the workflow after CI passes.
 
 This repo does not require an npm automation token when Trusted Publishing is configured.
+
+## Shared dynamic composition (local development)
+
+The current checkout uses `@openpresentation/opf/composition` for portable geometry. Slides can select `auto`, `row`, `column`, or `grid`, set weighted tracks, and request path-specific overflow diagnostics. See the sibling OPF repo's `docs/dynamic-composition.md` for the complete contract.
+
+Version 0.1.0 requires the published `@openpresentation/opf@^0.4.0` for composition, pagination and measured text. A clean `npm ci && npm test` uses registry packages and runs the full raster corpus without sibling checkouts. For coordinated source development, build OPF and run `node scripts/link-ecosystem.mjs` there; `pnpm test:ecosystem` checks editing, rendering, editable PowerPoint geometry and import together.
+
+For actual font measurement, load `loadBundledFontRegistry()` from `@openpresentation/opf-render/fonts-node`, then pass its `textMeasurement` to rendering and its `embeddedFonts` to SVG export. Pass its `fontFiles` to PNG/PDF conversion. The browser-safe `@openpresentation/opf-render/fonts` entry accepts local font bytes. Missing fonts/glyphs fail explicitly; aliases and fallback are opt-in and recorded in `registry.substitutions`. Bundled font license notices travel with embedded SVG fonts.
+
+Raster updates produce an HTML gallery and `artifacts/golden/candidate.json`; they never overwrite the approved baseline automatically. See [baseline review and known limitations](test/golden/README.md).

package/dist/font-compatibility.js

@@ -0,0 +1,48 @@
+/** Curated substitution policy. Metric means upstream intent, not universal pixel identity. */
+const metric = (requestedFamily, substitutes, source, note = "Standard regular, bold, italic and bold italic styles; verify coverage and font versions.") => ({requestedFamily, substitutes, compatibility:"metric", weights:[400,700], source, note});
+const visual = (requestedFamily, substitutes, note = "Approximate appearance; measure again and expect reflow.") => ({requestedFamily, substitutes, compatibility:"visual", note});
+export const FONT_COMPATIBILITY = Object.freeze([
+  metric("Calibri",["Carlito"],"https://github.com/googlefonts/carlito"),
+  metric("Cambria",["Caladea"],"https://chromium.googlesource.com/external/fontconfig/+/refs/heads/main/conf.d/30-metric-aliases.conf","Fontconfig compatibility mapping; font-version and repertoire differences require verification."),
+  metric("Arial",["Arimo","Liberation Sans"],"https://github.com/google/fonts/blob/main/ofl/arimo/DESCRIPTION.en_us.html"),
+  metric("Times New Roman",["Tinos","Liberation Serif"],"https://github.com/google/fonts/blob/main/ofl/tinos/DESCRIPTION.en_us.html"),
+  metric("Courier New",["Cousine","Liberation Mono"],"https://github.com/google/fonts/blob/main/apache/cousine/DESCRIPTION.en_us.html"),
+  {...visual("Georgia",["Gelasio"],"Individual advances match the tested Georgia, but optional ligatures change shaped widths by up to 2.02% in our corpus. Treated as approximate until feature parity is supported."),source:"https://github.com/SorkinType/Gelasio"},
+  metric("Arial Narrow",["Liberation Sans Narrow"],"https://github.com/liberationfonts/liberation-sans-narrow","Separate legacy distribution and license; not included in Liberation 2 or this bundle."),
+  visual("Calibri Light",["Carlito"],"The bundled Carlito family has no Light face. This replacement is approximate."),
+  visual("Aptos",["Source Sans 3","Carlito"]),
+  visual("Aptos Display",["Source Sans 3","Carlito"]),
+  visual("Aptos Narrow",["Liberation Sans Narrow"]),
+  visual("Aptos Mono",["Cousine","Liberation Mono"]),
+  visual("Segoe UI",["Open Sans","Noto Sans"]),
+  visual("Tahoma",["Arimo","Noto Sans"]),
+  visual("Verdana",["DejaVu Sans"]),
+  visual("Trebuchet MS",["Ubuntu","Open Sans"]),
+  visual("Century Gothic",["Montserrat","URW Gothic"]),
+  visual("Franklin Gothic",["Libre Franklin"]),
+  visual("Gill Sans",["Cabin","Lato"]),
+  visual("Garamond",["EB Garamond"]),
+  visual("Palatino Linotype",["TeX Gyre Pagella"]),
+  visual("Book Antiqua",["TeX Gyre Pagella"]),
+  visual("Bookman Old Style",["TeX Gyre Bonum"]),
+  visual("Century Schoolbook",["TeX Gyre Schola"]),
+  visual("Consolas",["Inconsolata","Cousine"]),
+  visual("Lucida Console",["Liberation Mono","Cousine"]),
+  visual("Lucida Sans Unicode",["Noto Sans","DejaVu Sans"]),
+  visual("Impact",["Anton","Oswald"]),
+  visual("Rockwell",["Arvo","Roboto Slab"]),
+  visual("Baskerville",["Libre Baskerville"]),
+  visual("Bodoni MT",["Libre Bodoni"]),
+  visual("Didot",["GFS Didot"]),
+  visual("Candara",["Lato"]),
+  visual("Corbel",["Source Sans 3","Lato"]),
+  visual("Constantia",["Merriweather"]),
+  visual("Ebrima",["Noto Sans"]),
+  visual("Microsoft Sans Serif",["Liberation Sans","Arimo"]),
+  ...["MS Gothic","Meiryo","Yu Gothic"].map(name=>visual(name,["Noto Sans CJK JP"])),
+  visual("SimSun",["Noto Serif CJK SC"]),
+  ...["SimHei","Microsoft YaHei"].map(name=>visual(name,["Noto Sans CJK SC"])),
+  visual("Malgun Gothic",["Noto Sans CJK KR"]),
+  visual("Microsoft JhengHei",["Noto Sans CJK TC"]),
+].map(rule=>Object.freeze({...rule,substitutes:Object.freeze(rule.substitutes),...(rule.weights?{weights:Object.freeze(rule.weights)}:{})})));
+export const EXPERIMENTAL_FONT_CANDIDATES = Object.freeze([Object.freeze({requestedFamily:"Aptos",substitute:"Akasia",source:"https://codeberg.org/bloudraad/akasia",note:"Upstream claims metric compatibility in twelve styles. Not bundled or automatically selected; OPF conformance testing is pending. No Narrow or Display compatibility is implied."})]);

package/dist/fonts-browser.d.ts

@@ -0,0 +1,17 @@
+import type {
+  FontFaceInput,
+  FontRegistry,
+  FontRegistryOptions,
+} from "./fonts.js";
+export interface BrowserFontInput extends Omit<FontFaceInput, "data"> {
+  data?: Uint8Array;
+  url?: string;
+}
+export declare function loadBrowserFontRegistry(
+  entries: BrowserFontInput[],
+  options?: FontRegistryOptions & {
+    document?: Document;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+  },
+): Promise<FontRegistry & { dispose(): void }>;

package/dist/fonts-browser.js

@@ -0,0 +1,61 @@
+import { createFontRegistry, OPFFontError } from "./fonts.js";
+/** Fetch only host-selected font files, then use those exact bytes for shaping and CSS. */
+export async function loadBrowserFontRegistry(entries, options = {}) {
+  const documentRef = options.document ?? globalThis.document;
+  const FontFaceRef = documentRef?.defaultView?.FontFace ?? globalThis.FontFace;
+  if (!documentRef?.fonts || !FontFaceRef)
+    throw new OPFFontError(
+      "font-api-unavailable",
+      "The browser Font Loading API is required.",
+    );
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const faces = await Promise.all(
+    entries.map(async (entry) => {
+      if (entry.data) return entry;
+      if (!entry.url)
+        throw new OPFFontError(
+          "invalid-font-source",
+          "Supply font bytes or a font-file URL.",
+        );
+      const response = await fetcher(entry.url, { signal: options.signal });
+      if (!response.ok)
+        throw new OPFFontError(
+          "font-fetch-failed",
+          `Could not load font (${response.status}).`,
+          { url: entry.url },
+        );
+      return { ...entry, data: new Uint8Array(await response.arrayBuffer()) };
+    }),
+  );
+  const registry = createFontRegistry(faces, options),
+    loaded = [];
+  // Normalize family names using the registry's parsed font metadata.
+  const embedded = registry.embeddedFonts;
+  try {
+    await Promise.all(
+      faces.map(async (entry, index) => {
+        const descriptor = embedded[index];
+        const face = new FontFaceRef(
+          descriptor.family,
+          entry.data.slice().buffer,
+          {
+            weight: String(descriptor.weight),
+            style: descriptor.italic ? "italic" : "normal",
+          },
+        );
+        await face.load();
+        loaded.push(face);
+      }),
+    );
+    for (const face of loaded) documentRef.fonts.add(face);
+    await documentRef.fonts.ready;
+  } catch (error) {
+    for (const face of loaded) documentRef.fonts.delete(face);
+    throw new OPFFontError("font-load-failed", error.message);
+  }
+  return Object.assign(registry, {
+    dispose() {
+      for (const face of loaded) documentRef.fonts.delete(face);
+    },
+  });
+}

package/dist/fonts-node.d.ts

@@ -0,0 +1,4 @@
+import type {FontRegistry,FontRegistryOptions} from "./fonts.js";
+export declare function loadBundledFontRegistry(options?: FontRegistryOptions): Promise<FontRegistry & {fontFiles:string[]}>;
+
+export declare function loadOfficeFontRegistry(options?: FontRegistryOptions & {includeBaseFonts?:boolean}): Promise<FontRegistry & {fontFiles:string[]}>;

package/dist/fonts-node.js

@@ -0,0 +1,44 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { createFontRegistry } from "./fonts.js";
+const require = createRequire(import.meta.url);
+/** Bundled, openly licensed faces. No system font discovery or network requests. */
+export async function loadBundledFontRegistry(options = {}) {
+  const definitions = [
+    ["roboto","400Regular","Roboto_400Regular",400,false],
+    ["roboto","500Medium","Roboto_500Medium",500,false],
+    ["roboto","600SemiBold","Roboto_600SemiBold",600,false],
+    ["roboto","700Bold","Roboto_700Bold",700,false],
+    ["roboto","800ExtraBold","Roboto_800ExtraBold",800,false],
+    ["roboto","400Regular_Italic","Roboto_400Regular_Italic",400,true],
+    ["roboto","700Bold_Italic","Roboto_700Bold_Italic",700,true],
+    ["roboto-mono","400Regular","RobotoMono_400Regular",400,false],
+    ["roboto-mono","700Bold","RobotoMono_700Bold",700,false],
+  ];
+  const licenses = Object.fromEntries(await Promise.all(["roboto","roboto-mono"].map(async pkg=>[pkg,await readFile(require.resolve(`@expo-google-fonts/${pkg}/LICENSE_FONT`),"utf8")])));
+  const fontFiles = definitions.map(([pkg,directory,name])=>require.resolve(`@expo-google-fonts/${pkg}/${directory}/${name}.ttf`));
+  const entries = await Promise.all(definitions.map(async ([pkg,,,weight,italic],index)=>({license:licenses[pkg],data:new Uint8Array(await readFile(fontFiles[index])),weight,italic})));
+  return Object.assign(createFontRegistry(entries,options),{fontFiles});
+}
+
+/** Six pinned open-source Office substitutes, optionally alongside the base Roboto pack. */
+export async function loadOfficeFontRegistry(options = {}) {
+  const packages = ["carlito","caladea","arimo","tinos","cousine","gelasio"];
+  const styles = [["400Regular",400,false],["400Regular_Italic",400,true],["700Bold",700,false],["700Bold_Italic",700,true]];
+  const entries = [], fontFiles = [];
+  for (const pkg of packages) {
+    const name = pkg[0].toUpperCase()+pkg.slice(1);
+    const license = await readFile(require.resolve(`@expo-google-fonts/${pkg}/LICENSE_FONT`),"utf8");
+    for (const [directory,weight,italic] of styles) {
+      const path = require.resolve(`@expo-google-fonts/${pkg}/${directory}/${name}_${directory}.ttf`);
+      fontFiles.push(path);
+      entries.push({data:new Uint8Array(await readFile(path)),weight,italic,license});
+    }
+  }
+  if (options.includeBaseFonts !== false) {
+    const base = await loadBundledFontRegistry();
+    fontFiles.push(...base.fontFiles);
+    for (const face of base.embeddedFonts) entries.push({...face,data:Uint8Array.from(Buffer.from(face.dataUrl.split(",")[1],"base64"))});
+  }
+  return Object.assign(createFontRegistry(entries,{substitutionPolicy:"metric",...options}),{fontFiles});
+}

package/dist/fonts.d.ts

@@ -0,0 +1,21 @@
+import type { TextMeasurement, TextStyle } from "@openpresentation/opf/composition";
+export interface FontFaceInput { data: Uint8Array; family?: string; weight?: number; italic?: boolean; postscriptName?: string; license?: string }
+export interface EmbeddedFont { family: string; weight: number; italic?: boolean; dataUrl: string; license?: string }
+export type FontCompatibility = "exact" | "metric" | "visual" | "generic";
+export interface FontResolution { requestedFamily:string; sourceFamily:string; resolvedFamily:string; requestedWeight:number; resolvedWeight:number; italic:boolean; compatibility:FontCompatibility; path?:string; source?:string; note?:string }
+export interface FontRegistryOptions {
+  aliases?: Record<string,string>; fallbackFamily?: string; strictGlyphs?: boolean;
+  substitutionPolicy?: "none" | "metric" | "visual";
+  themeFonts?: Partial<Record<"majorLatin"|"minorLatin"|"majorEastAsia"|"minorEastAsia"|"majorComplexScript"|"minorComplexScript",string>>;
+}
+export declare const FONT_COMPATIBILITY: readonly Readonly<{requestedFamily:string;substitutes:readonly string[];compatibility:"metric"|"visual";weights?:readonly number[];source?:string;note:string}>[];
+export declare const EXPERIMENTAL_FONT_CANDIDATES: readonly Readonly<{requestedFamily:string;substitute:string;source:string;note:string}>[];
+export interface FontRegistry {
+  textMeasurement: TextMeasurement;
+  clearSubstitutions(): void;
+  resolveFont(style: TextStyle): FontResolution;
+  readonly embeddedFonts: EmbeddedFont[];
+  readonly substitutions: FontResolution[];
+}
+export declare class OPFFontError extends Error { code:string; details:Record<string,unknown>; constructor(code:string,message:string,details?:Record<string,unknown>) }
+export declare function createFontRegistry(entries: FontFaceInput[], options?: FontRegistryOptions): FontRegistry;

package/dist/fonts.js

@@ -0,0 +1,111 @@
+import { create } from "fontkit";
+import { FONT_COMPATIBILITY } from "./font-compatibility.js";
+export { FONT_COMPATIBILITY, EXPERIMENTAL_FONT_CANDIDATES } from "./font-compatibility.js";
+
+export class OPFFontError extends Error {
+  constructor(code, message, details = {}) { super(message); this.name = "OPFFontError"; this.code = code; this.details = details; }
+}
+const key = (family, weight, italic) => `${family.toLowerCase()}:${weight}:${!!italic}`;
+function base64(data) {
+  let binary = "";
+  for (let i = 0; i < data.length; i += 32768) binary += String.fromCharCode(...data.subarray(i, i + 32768));
+  return btoa(binary);
+}
+function validFamily(family) {
+  if (typeof family !== "string" || !family.trim() || /[\u0000-\u001f"'\\<>;]/.test(family)) throw new OPFFontError("invalid-font-family", "Font family must be a nonempty plain name.");
+  return family;
+}
+/** Local font files only. The caller explicitly chooses aliases and fallback. */
+export function createFontRegistry(entries, options = {}) {
+  if (!Array.isArray(entries) || !entries.length) throw new OPFFontError("empty-font-registry", "Supply at least one font file.");
+  const faces = entries.map(entry => {
+    if (!(entry.data instanceof Uint8Array)) throw new OPFFontError("invalid-font-data", "Font data must be a Uint8Array.");
+    const data = entry.data.slice();
+    let font;
+    try { font = create(data, entry.postscriptName); } catch (error) { throw new OPFFontError("invalid-font-data", error.message); }
+    if (!font?.layout || !font.unitsPerEm) throw new OPFFontError("font-collection", "Select one font from a collection with postscriptName.");
+    const family = validFamily(entry.family ?? font.familyName);
+    const weight = entry.weight ?? 400;
+    const italic = entry.italic ?? !!font.italicAngle;
+    if (!Number.isInteger(weight) || weight < 1 || weight > 1000) throw new OPFFontError("invalid-font-weight", "Font weight must be between 1 and 1000.");
+    const signature = String.fromCharCode(...data.subarray(0,4));
+    const format = signature === "OTTO" ? "otf" : signature === "wOFF" ? "woff" : signature === "wOF2" ? "woff2" : "ttf";
+    return {family,weight,italic,font,data,format,license:entry.license,cache:new Map()};
+  });
+  const duplicates = new Set();
+  for (const face of faces) {
+    const id = key(face.family,face.weight,face.italic);
+    if (duplicates.has(id)) throw new OPFFontError("duplicate-font-face", `Duplicate face: ${id}`);
+    duplicates.add(id);
+  }
+  const substitutions = new Map();
+  const aliases = new Map(Object.entries(options.aliases ?? {}).map(([from,to])=>[validFamily(from).toLowerCase(),validFamily(to)]));
+  const policy = options.substitutionPolicy ?? "none";
+  if (!["none","metric","visual"].includes(policy)) throw new OPFFontError("invalid-font-policy", "substitutionPolicy must be none, metric, or visual.");
+  if (options.fallbackFamily) validFamily(options.fallbackFamily);
+  const findFamily = family => faces.filter(face=>face.family.toLowerCase()===family.toLowerCase());
+  const resolve = style => {
+    const requested = validFamily(style?.fontFamily);
+    const weight = style.fontWeight ?? 400;
+    if (!Number.isFinite(weight) || weight < 1 || weight > 1000) throw new OPFFontError("invalid-font-weight", "Font weight must be between 1 and 1000.");
+    // DrawingML theme tokens are resolved before family lookup, never as literal fonts.
+    const themeKey = {"+mj-lt":"majorLatin","+mn-lt":"minorLatin","+mj-ea":"majorEastAsia","+mn-ea":"minorEastAsia","+mj-cs":"majorComplexScript","+mn-cs":"minorComplexScript"}[requested.toLowerCase()];
+    if (requested.startsWith("+") && !themeKey) throw new OPFFontError("unresolved-theme-font", `Unknown theme font '${requested}'.`, {path:style.path});
+    const family = themeKey ? options.themeFonts?.[themeKey] : requested;
+    if (!family || family.startsWith("+")) throw new OPFFontError("unresolved-theme-font", `Supply a concrete theme family for '${requested}'.`, {path:style.path});
+    validFamily(family);
+    let matching = findFamily(family), compatibility = "exact", rule;
+    const encodedSymbol = /^(wingdings(?: [23])?|webdings|symbol)$/i.test(family);
+    if (!matching.length && encodedSymbol) throw new OPFFontError("font-encoding-required", `Font '${family}' requires character mapping before substitution.`, {path:style.path,fontFamily:family});
+    if (!matching.length && aliases.has(family.toLowerCase())) {
+      matching = findFamily(aliases.get(family.toLowerCase())); compatibility = "visual";
+    }
+    if (!matching.length && policy!=="none") {
+      const candidate = FONT_COMPATIBILITY.find(entry=>entry.requestedFamily.toLowerCase()===family.toLowerCase());
+      const tier = candidate?.compatibility==="metric" && !candidate.weights.includes(weight) ? "visual" : candidate?.compatibility;
+      if (candidate && (policy==="visual" || tier==="metric")) {
+        for (const substitute of candidate.substitutes) {
+          const available = findFamily(substitute).filter(face=>face.italic===!!style.italic && (tier!=="metric" || face.weight===weight));
+          if (available.length) { matching=available; compatibility=tier; rule=candidate; break; }
+        }
+      }
+    }
+    // Equations require an explicit math-aware choice; never fall through to body text.
+    if (!matching.length && /^(cambria math|stix two math|noto sans math)$/i.test(family)) throw new OPFFontError("math-font-required", `Supply '${family}' or an explicit math-font alias.`, {path:style.path});
+    if (!matching.length && options.fallbackFamily) { matching=findFamily(options.fallbackFamily); compatibility="generic"; }
+    if (!matching.length) throw new OPFFontError("font-unavailable", `No local font face for '${family}'.`, {path:style.path,fontFamily:family});
+    matching = matching.filter(face=>face.italic===!!style.italic);
+    if (!matching.length) throw new OPFFontError("font-style-unavailable", `No ${style.italic ? "italic" : "upright"} face for '${family}'.`, {path:style.path});
+    matching.sort((a,b)=>Math.abs(a.weight-weight)-Math.abs(b.weight-weight) || a.weight-b.weight);
+    const face = matching[0];
+    if (face.weight!==weight && compatibility!=="generic") compatibility="visual";
+    const resolution={requestedFamily:requested,sourceFamily:family,resolvedFamily:face.family,requestedWeight:weight,resolvedWeight:face.weight,italic:face.italic,compatibility,...(style.path?{path:style.path}:{}),...(rule?{source:rule.source,note:rule.note}:{})};
+    if (face.family.toLowerCase()!==family.toLowerCase() || face.weight!==weight) substitutions.set(JSON.stringify([requested,weight,!!style.italic,style.path]),resolution);
+    return {face,resolution};
+  };
+  const resolveFace = style => resolve(style).face;
+  const resolveStyle = style => { const face=resolveFace(style); return {...style,fontFamily:face.family,fontWeight:face.weight,italic:face.italic}; };
+  const measure = (text,size,style) => {
+    const face=resolveFace(style);
+    let width=face.cache.get(text);
+    if (width===undefined) {
+      if (options.strictGlyphs!==false) for(const character of text) {
+        if (/\p{Default_Ignorable_Code_Point}/u.test(character)) continue;
+        if (!face.font.hasGlyphForCodePoint(character.codePointAt(0))) throw new OPFFontError("missing-glyph", `Font '${face.family}' cannot display U+${character.codePointAt(0).toString(16).toUpperCase()}.`, {path:style.path,fontFamily:face.family,character});
+      }
+      width=face.font.layout(text).positions.reduce((total,position)=>total+position.xAdvance,0)/face.font.unitsPerEm;
+      if (text.length<=2048) {
+        if (face.cache.size>=512) face.cache.delete(face.cache.keys().next().value);
+        face.cache.set(text,width);
+      }
+    }
+    return width*size;
+  };
+  return {
+    textMeasurement: {measure,resolveStyle},
+    resolveFont(style) { return resolve(style).resolution; },
+    clearSubstitutions() { substitutions.clear(); },
+    get substitutions() { return [...substitutions.values()]; },
+    get embeddedFonts() { return faces.map(face=>({family:face.family,weight:face.weight,italic:face.italic,...(face.license ? {license:face.license} : {}),dataUrl:`data:font/${face.format};base64,${base64(face.data)}`})); },
+  };
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import type { EmbeddedFont } from "./fonts.js";
+import type { SlideComposition, LayoutDiagnostic, TextMeasurement } from "@openpresentation/opf/composition";
 export declare const packageName = "@openpresentation/opf-render";
 
 export declare const releaseLane: Readonly<{
@@ -13,3 +15,100 @@ export declare const runtimePolicy: Readonly<{
   requiredNetworkCalls: false;
   deterministicLocalExecution: true;
 }>;
+
+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"];
+}>;
+
+export interface RenderSvgOptions {
+  textMeasurement?: TextMeasurement;
+  embeddedFonts?: EmbeddedFont[];
+  strictAssets?: boolean;
+  imageResolver?: (src: string | undefined, context: { asset: unknown; path: string }) => string | null | undefined;
+  onDiagnostic?: (diagnostic: LayoutDiagnostic) => void;
+  slideIndex?: number;
+  trace?: boolean;
+  catalogs?: Record<string, { records?: unknown[] } | unknown[]>;
+  catalogSources?: Record<string, { records?: unknown[] } | unknown[]>;
+}
+
+export interface SvgToPngOptions {
+  scale?: number;
+  background?: string;
+  dpi?: number;
+  useBundledFonts?: boolean;
+  loadSystemFonts?: boolean;
+  fontFiles?: string[];
+  fontDirs?: string[];
+  defaultFontFamily?: string;
+  sansSerifFamily?: string;
+  monospaceFamily?: string;
+}
+
+export interface SvgToPdfOptions extends SvgToPngOptions {}
+
+export interface ResolvedPresentation {
+  presentation: unknown;
+  engineDefaults: typeof engineDefaults;
+  slides: ResolvedSlide[];
+}
+
+export interface ResolvedSlide {
+  geometry: SlideComposition;
+  index: number;
+  path: string;
+  slide: unknown;
+  layout: unknown;
+  design: {
+    theme: unknown;
+    colorScheme: unknown;
+    fontScheme: unknown;
+    dimensions: { width: number; height: number };
+    background: unknown;
+    backgroundColor: string | null;
+    colors: Record<string, string>;
+    fonts: Record<"heading" | "body" | "code", string>;
+  };
+  titleBindings: RenderBinding[];
+  contentItems: RenderBinding[];
+  blocks: RenderBinding[];
+}
+
+export interface RenderBinding {
+  type: string;
+  field?: string;
+  slot?: string;
+  value: unknown;
+  path: string;
+  placeholderIndex?: number;
+  regionKey?: string;
+}
+
+export declare class OPFRenderError extends Error {
+  readonly code: string;
+  readonly details: Record<string, unknown>;
+  readonly issues?: unknown[];
+  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;
+
+export declare function renderSvgDeck(input: unknown, options?: RenderSvgOptions): string[];
+
+export declare function svgToPng(svg: string | Uint8Array, options?: SvgToPngOptions): Promise<Uint8Array>;
+
+export declare function svgToPdf(svgs: string | Uint8Array | Array<string | Uint8Array>, options?: SvgToPdfOptions): Promise<Uint8Array>;

package/dist/index.js

@@ -1,15 +1,2 @@
-export const packageName = "@openpresentation/opf-render";
-
-export const releaseLane = Object.freeze({
-  githubRepository: "OpenPresentation/opf-render",
-  npmPackage: "@openpresentation/opf-render",
-  compatibilityPackage: "@openpresentation/opf"
-});
-
-export const runtimePolicy = Object.freeze({
-  hostedServiceInCriticalPath: false,
-  telemetry: false,
-  commercialSdkInCriticalPath: false,
-  requiredNetworkCalls: false,
-  deterministicLocalExecution: true
-});
+export * from './svg.js';
+export {svgToPng,svgToPdf} from './raster.js';