@openpresentation/opf-render 0.0.1 → 0.0.2

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. This repo is the Phase 1 toolkit lane for SVG, PNG, and PDF output. The current package implements the validation, catalog resolution, placeholder binding, deterministic text layout, and SVG core that PNG/PDF conversion will build on.
 
 ## Scope
 
@@ -8,9 +8,29 @@ 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.
 
 ## Runtime Policy
 
@@ -23,22 +43,40 @@ 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 against `test/golden/opf-examples-png.sha256.json` when the sibling corpus is at the approved OPF commit. To regenerate the approved PNG hash manifest after an intentional visual change:
+
+```sh
+OPF_EXAMPLES_DIR=/path/to/opf/examples 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.

package/dist/index.d.ts

@@ -13,3 +13,94 @@ 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 {
+  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 {
+  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>;