@openpresentation/opf-render 0.17.0 → 0.18.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import type { RenderFonts, ScriptFonts } from "./fonts.js";
-import type { Catalog, Finding, UnresolvedReferenceDiagnostic } from "@openpresentation/opf";
+import type { Catalog, Finding, SlideSelection, UnresolvedReferenceDiagnostic } from "@openpresentation/opf";
+export type { SlideSelection } from "@openpresentation/opf";
 import type { SlideComposition, LayoutDiagnostic, TextMeasurement } from "@openpresentation/opf/composition";
 export declare const packageName = "@openpresentation/opf-render";
 
@@ -49,8 +50,8 @@ export type RenderDiagnostic = LayoutDiagnostic | {
   placeholder: "label" | "icon";
 };
 
-export interface RenderSvgOptions {
-  /** 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. */
+export interface ToSvgOptions {
+  /** Leave out slides marked `hidden: true` when drawing the whole deck, as the player does. Default false: one SVG per slide. A slide number or selection draws exactly the slides it names. */
   skipHidden?: boolean;
   /**
    * The fonts the deck is laid out and drawn with: the handle `loadFonts()` returns (from `@openpresentation/opf-render/fonts-node` or
@@ -58,18 +59,32 @@ export interface RenderSvgOptions {
    * 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;
   /**
-   * `true` draws every `<text>` as glyph outlines (RR-64): `<use>` of outlines kept once per slide in `<defs>`, so the SVG needs
+   * How the SVG draws text (RR-74). `"fonts"` (default): each SVG embeds, as `@font-face` data, the faces of `fonts.embeddedFonts` its
+   * own text draws (RR-61). `"system"`: no `@font-face` data; 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).
+   *
+   * `"paths"`: every `<text>` drawn as glyph outlines (RR-64): `<use>` of outlines kept once per slide in `<defs>`, so the SVG needs
    * no font and looks the same in every viewer (about 40 KB a slide over the core example decks, against 0.5 to 4 MB of embedded
    * faces). Needs the fonts handle `loadFonts()` returns (`text-as-paths-needs-fonts` otherwise). The text is no longer text: it
-   * cannot be selected, searched or edited in place, and each outlined element is a `role="img"` group labelled with its text for
-   * assistive technology. Each element keeps its `data-opf-*` trace. Text in a colour or bitmap font stays text
-   * (`text-as-paths-kept-text`). Use it for thumbnails, previews and portable SVG files, not for an editing surface or the
-   * vector PDF (which keeps real text from `<text>` SVG). Default false.
+   * cannot be edited in place. The glyphs are shaped by HarfBuzz (the browser's shaper; the Node handle always, a browser handle
+   * given `shapeWasm`), are hidden from assistive technology, and each outlined line is also invisible real text pinned to the
+   * drawn width, so screen readers, selection, copy and find-in-page get the words. Each element keeps its `data-opf-*` trace.
+   * A run stays text, reported as `text-as-paths-fallback` with a `reason`, when its font is a colour or bitmap font
+   * (`"colour-font"`), its face's fsType restricts embedding (`"restricted"`), or it has no pinned width and HarfBuzz and the
+   * layout's measurement disagree on it (`"shaping"`). Use it for thumbnails, previews and portable SVG files, not for an editing
+   * surface or the vector PDF (which keeps real text from `<text>` SVG).
    */
-  textAsPaths?: boolean;
+  text?: "fonts" | "system" | "paths";
+  /**
+   * `false` embeds whole faces (RR-65). By default, with a fonts handle that carries `subsets` (the Node `loadFonts` handle, a browser
+   * handle given `subsetWasm`), each face an SVG embeds is cut to the characters the slide draws, keeping every layout feature, so the
+   * browser draws it exactly like the whole face (over the core example decks a slide's SVG falls from 2.4 MB to 59 KB on average).
+   * Faces whose license does not allow a modified version under their own name (Carlito, Raleway, Lora, Playfair Display, PT Serif,
+   * Merriweather Sans, Source Sans 3), whose fsType forbids subsetting, or that a host supplied, are always embedded whole. Set it to
+   * false for an SVG whose text will be edited outside the renderer.
+   */
+  subsetFonts?: 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. */
@@ -106,18 +121,18 @@ export interface RenderSvgOptions {
   strictReferences?: boolean;
 }
 
-export interface SvgToPngOptions {
+/** The options of `toPng`: the conversion's own, and the `toSvg` options that draw a deck. */
+export interface ToPngOptions extends Omit<ToSvgOptions, "fonts"> {
   /**
-   * The fonts the conversion draws with: the handle `loadFonts()` returns from `/fonts-node` (its `fontFiles`; `useBundledFonts` and
-   * `loadSystemFonts` say whether the bundled base faces are added, default true, and whether system fonts load, default false). Without
-   * it the bundled base faces draw. The same handle goes to `renderSvg`, so the preview and the PNG use the same faces.
+   * The fonts the deck is laid out and drawn with: the handle `loadFonts()` returns from `/fonts-node` (it measures the deck, and its
+   * `fontFiles` draw; `useBundledFonts` and `loadSystemFonts` say whether the bundled base faces are added, default true, and whether
+   * system fonts load, default false), so the preview and the PNG use the same faces. For SVG input it may instead be font folders
+   * (a path or a list of paths), whose faces are added to the bundled base faces. Without it the bundled base faces draw.
    */
-  fonts?: RenderFonts;
+  fonts?: RenderFonts | string | readonly string[];
   scale?: number;
   background?: string;
   dpi?: number;
-  /** Extra directories of font files to draw with. */
-  fontDirs?: string[];
   defaultFontFamily?: string;
   sansSerifFamily?: string;
   monospaceFamily?: string;
@@ -186,14 +201,14 @@ export interface PdfMetadata {
   modificationDate?: Date | string;
 }
 
-export interface SvgToPdfOptions extends SvgToPngOptions {
+export interface ToPdfOptions extends Omit<ToPngOptions, "onDiagnostic"> {
   /**
-   * `"vector"` (default): shapes, gradients and patterns as PDF vector graphics, pictures as images, text as real text
-   * with embedded font subsets (selectable, searchable, correct copy and paste); the fonts are the bundled files, the `fonts` handle's
-   * `fontFiles` and the `fontDirs` you supply, never system fonts. `"raster"`: each slide an image, as before.
+   * `true` draws each slide as an image (`scale`). Default false, a vector PDF: shapes, gradients and patterns as PDF vector graphics,
+   * pictures as images, text as real text with embedded font subsets (selectable, searchable, correct copy and paste); the fonts are
+   * the bundled files, the `fonts` handle's `fontFiles` and the font folders you supply, never system fonts.
    */
-  mode?: "vector" | "raster";
-  /** Vector mode paints the page this colour first (default white, as raster mode composites on white); `"none"` leaves it unpainted. */
+  raster?: boolean;
+  /** A vector PDF paints the page this colour first (default white, as a raster PDF composites on white); `"none"` leaves it unpainted. */
   background?: string;
   /** Vector only. Family drawn for the generic `serif`; default `defaultFontFamily`. */
   serifFamily?: string;
@@ -207,8 +222,8 @@ export interface SvgToPdfOptions extends SvgToPngOptions {
   strict?: boolean;
   /** Vector only. Pixel density of the rare element rasterized because it has no vector form; default 2. */
   rasterFallbackScale?: number;
-  /** Vector only. Receives font embedding reports, substitutions, fallbacks and unsupported features. */
-  onDiagnostic?: (diagnostic: PdfDiagnostic) => void;
+  /** Vector only: font embedding reports, substitutions, fallbacks and unsupported features; given a deck, also the diagnostics of drawing it. */
+  onDiagnostic?: (diagnostic: PdfDiagnostic | RenderDiagnostic) => void;
   /** Vector only. Checked between pages; an abort rejects with the signal's reason. */
   signal?: AbortSignal;
   /** Vector only. Called after each page is written. */
@@ -266,14 +281,32 @@ export declare class OPFRenderError extends Error {
   constructor(code: string, message: string, details?: Record<string, unknown>);
 }
 
-export declare function resolvePresentation(input: unknown, options?: RenderSvgOptions): ResolvedPresentation;
+export declare function resolvePresentation(input: unknown, options?: ToSvgOptions): ResolvedPresentation;
 
-/** The SVG of every slide of the deck, in order. */
-export declare function renderSvg(input: unknown, options?: RenderSvgOptions): string[];
+/** An SVG slide the renderer drew: its text, or its bytes. */
+export type SvgSlide = string | Uint8Array;
 
-/** 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;
+/**
+ * The deck as SVG (RR-73). `toSvg(deck)`: every slide, in order (without the hidden ones under `skipHidden`). `toSvg(deck, 3)`: the
+ * third slide (slides count from 1; out of range throws `slide-out-of-range`). `toSvg(deck, "1-3")` or `toSvg(deck, [1, 3])`: the
+ * selected slides (a malformed selection throws `invalid-slide-selection`). The second argument may be the options instead.
+ */
+export declare function toSvg(input: unknown, options?: ToSvgOptions): string[];
+export declare function toSvg(input: unknown, slide: number, options?: ToSvgOptions): string;
+export declare function toSvg(input: unknown, slides: Exclude<SlideSelection, number>, options?: ToSvgOptions): string[];
 
-export declare function svgToPng(svg: string | Uint8Array, options?: SvgToPngOptions): Promise<Uint8Array>;
+/**
+ * PNG (RR-73) of a deck, drawn with `toSvg` (the slide arguments are `toSvg`'s: one PNG for a slide number, a list otherwise), or of
+ * SVG the renderer drew (one SVG gives one PNG, a list a list). A slide selection with SVG input throws `invalid-conversion-option`.
+ */
+export declare function toPng(svg: Uint8Array | `<${string}`, options?: ToPngOptions): Promise<Uint8Array>;
+export declare function toPng(svgs: readonly SvgSlide[], options?: ToPngOptions): Promise<Uint8Array[]>;
+export declare function toPng(deck: unknown, slide: number, options?: ToPngOptions): Promise<Uint8Array>;
+export declare function toPng(deck: unknown, slides: Exclude<SlideSelection, number>, options?: ToPngOptions): Promise<Uint8Array[]>;
+export declare function toPng(deck: object, options?: ToPngOptions): Promise<Uint8Array[]>;
+/** A string is SVG when it starts with `<`, and the deck's JSON text otherwise. */
+export declare function toPng(source: string, options?: ToPngOptions): Promise<Uint8Array | Uint8Array[]>;
 
-export declare function svgToPdf(svgs: string | Uint8Array | Array<string | Uint8Array>, options?: SvgToPdfOptions): Promise<Uint8Array>;
+/** One PDF (RR-73), a page per slide: of a deck drawn with `toSvg` (every slide, or a selection: `toPdf(deck, "2-4")`), or of SVG slides. */
+export declare function toPdf(source: unknown, options?: ToPdfOptions): Promise<Uint8Array>;
+export declare function toPdf(deck: unknown, slides: SlideSelection, options?: ToPdfOptions): Promise<Uint8Array>;

package/dist/index.js

@@ -1,2 +1,2 @@
 export * from './svg.js';
-export {svgToPng,svgToPdf} from './raster.js';
+export {toPng,toPdf} from './raster.js';

package/dist/lazy-fonts.js

@@ -1,6 +1,6 @@
 import { fontPolicyFor } from "@openpresentation/opf/font-policy";
 import { pickFace } from "./font-registry.js";
-import { renderSvg, resolvePresentation } from "./svg.js";
+import { resolvePresentation, toSvg } from "./svg.js";
 export { lazyFontEntries, lazyFontList } from "./lazy-font-list.js";
 
 /**
@@ -17,7 +17,7 @@ const lc = value => String(value).trim().toLowerCase();
 
 /**
  * Render options that decide how a document resolves (catalogs, validate, date, ...) are forwarded from the host's
- * `renderSvg` options. The analysis supplies its own measurement and reports nothing: callbacks, the host's fonts handle
+ * `toSvg` options. The analysis supplies its own measurement and reports nothing: callbacks, the host's fonts handle
  * (measurement and embedded fonts), asset resolution and tracing are dropped.
  */
 const NOT_RESOLVE_OPTIONS = new Set(["fonts", "onDiagnostic", "trace", "glyphFallback", "imageResolver", "strictAssets", "signal"]);
@@ -27,10 +27,10 @@ function resolveOptionsOf(options) {
 
 /**
  * The font families a presentation's slides resolve (heading, body and code roles of every slide, including per-slide
- * design overrides), as `renderSvg` resolves them with the same `options` (`catalogs`, ...). This is the role families,
+ * design overrides), as `toSvg` resolves them with the same `options` (`catalogs`, ...). This is the role families,
  * not what is drawn: use `presentationFaces` for that.
  *
- * A document that does not resolve throws the error `renderSvg` throws for it (an OPFRenderError such as
+ * A document that does not resolve throws the error `toSvg` throws for it (an OPFRenderError such as
  * `catalog-resolution-failed` for a layout id no catalog has, or `invalid-opf`), never an empty set: a document whose layout comes only from
  * `options.catalogs` needs those catalogs here too.
  */
@@ -57,7 +57,7 @@ function registryView({ faces, policy = "none", aliases = new Map(), fallbackFam
 
 /**
  * The faces a preview of the presentation draws, as `[{family, weight, italic}]`, sorted by family, style and weight. It is
- * the renderer's own layout and painting run with a recording measurement, so it follows exactly what `renderSvg` measures
+ * the renderer's own layout and painting run with a recording measurement, so it follows exactly what `toSvg` measures
  * and draws: the heading and body roles of every slide that draws them, bold and italic runs of rich text, table and cell
  * styles, header and footer furniture, chart labels, metrics, quotes and timelines, the code role only where code is
  * drawn, per-slide design overrides, font scheme and theme resolution, and script slots (a script run is requested in its
@@ -73,8 +73,8 @@ function registryView({ faces, policy = "none", aliases = new Map(), fallbackFam
  * family found. The result is the faces the registry paints, for example `Intos 700` for a 600-weight label of an Aptos
  * deck. A style the registry cannot resolve is left as named (drawing reports it).
  *
- * `options` are the `renderSvg` options the document resolves with (`catalogs`, `date`, `validate`, ...). A document that
- * does not resolve throws what `renderSvg` throws for it.
+ * `options` are the `toSvg` options the document resolves with (`catalogs`, `date`, `validate`, ...). A document that
+ * does not resolve throws what `toSvg` throws for it.
  * @param {unknown} presentation
  * @param {object} [options]
  * @param {{faces: Iterable<{family: string, weight: number, italic: boolean}>, policy?: "none"|"metric"|"visual", aliases?: ReadonlyMap<string, string>, fallbackFamily?: string}} [registry]
@@ -98,7 +98,7 @@ export function presentationFaces(presentation, options = {}, registry) {
     measure(text, size, style) { if (text !== "") record(settle(style)); return String(text).length * size * RECORDED_EM; },
     resolveStyle: settle,
   };
-  renderSvg(presentation, { ...resolveOptionsOf(options), fonts: { textMeasurement } });
+  toSvg(presentation, { ...resolveOptionsOf(options), fonts: { textMeasurement } });
   return [...seen.values()].sort((a, b) => a.family < b.family ? -1 : a.family > b.family ? 1 : Number(a.italic) - Number(b.italic) || a.weight - b.weight);
 }
 
@@ -106,8 +106,8 @@ export function presentationFaces(presentation, options = {}, registry) {
  * The vendored faces (of `lazy`) a presentation draws that the registry does not hold: what a registry loads before it can
  * paint the document as Node paints it with every vendored face loaded. `held` lists the registry's faces
  * (`registry.describeFaces()`), `loaded` the lazy files already loaded; `policy`, `aliases` and `fallbackFamily` are the
- * registry's. `renderOptions` are the `renderSvg` options the document resolves with (`catalogs`, ...), and a document that
- * does not resolve throws what `renderSvg` throws for it. Face level: a bold or italic run added by an edit adds just that face.
+ * registry's. `renderOptions` are the `toSvg` options the document resolves with (`catalogs`, ...), and a document that
+ * does not resolve throws what `toSvg` throws for it. Face level: a bold or italic run added by an edit adds just that face.
  */
 export function lazyFacesNeeded(presentation, renderOptions, { lazy, held, loaded = new Set(), policy = "none", aliases = new Map(), fallbackFamily }) {
   const heldFaces = [...held], heldKeys = new Set(heldFaces.map(faceKeyOf));

package/dist/pdf-fonts.js

@@ -4,7 +4,7 @@ import { isTrueTypeOutlines, subsetTrueType } from "./pdf-subset.js";
 import { hex, name, num, sha256, textString, utf16Hex } from "./pdf-writer.js";
 
 // Font selection, shaping and embedding for the vector PDF export (RR-12). Fonts come only from the faces the
-// caller supplies (the same bundled font files, `fontFiles` and `fontDirs` the PNG preview draws with, and the
+// caller supplies (the same bundled font files, fonts handle or font folders the PNG preview draws with, and the
 // `@font-face` data of the SVG itself); nothing is read from the system and nothing is fetched. A face whose
 // OS/2 embedding bits forbid embedding is never embedded.
 

package/dist/pdf-text.js

@@ -166,7 +166,7 @@ function buildRuns(chunk, env, styleIds, faceCache, linkIds, ownerIds) {
   for (const char of chunk.chars) { levels.push(embedding.levels[unit]); unit += char.ch.length; }
   const mirrored = bidi.getMirroredCharactersMap(text, embedding.levels);
   const runs = [];
-  const chunkInfo = { logical: chunk.chars.filter((char) => !IGNORED.test(char.ch)).map((char) => char.ch).join("") };
+  const chunkInfo = { logical: chunk.chars.filter((char) => !IGNORED.test(char.ch)).map((char) => char.ch).join(""), rtl: baseDirection === "rtl" || /^[⁧‫‮]/.test(text) };
   let current = null;
   unit = 0;
   chunk.chars.forEach((char, index) => {
@@ -179,7 +179,8 @@ function buildRuns(chunk, env, styleIds, faceCache, linkIds, ownerIds) {
     const owner = env.splitByOwner ? linkId(ownerIds, { node: char.owner }) : 0;
     const key = `${resolved.styleId}|${resolved.face.id}|${level}|${char.scope?.id ?? 0}|${linkId(linkIds, char.link)}|${[...char.decoration].sort().join(",")}|${owner}`;
     if (!current || current.key !== key) {
-      current = { chunk: chunkInfo, key, face: resolved.face, style: char.style, level, scope: char.scope, link: char.link, decoration: char.decoration, owner: char.owner, chars: [], text: "", logical: "", weight: resolved.weight, italic: resolved.italic };
+      // `start`: the run's first character in logical order, so a reader can put runs back in reading order (RR-64).
+      current = { chunk: chunkInfo, start: index, key, face: resolved.face, style: char.style, level, scope: char.scope, link: char.link, decoration: char.decoration, owner: char.owner, chars: [], text: "", logical: "", weight: resolved.weight, italic: resolved.italic };
       runs.push(current);
     }
     current.logical += char.ch;
@@ -244,7 +245,9 @@ function shapeRun(run, env) {
   const size = parseFloat(style["font-size"]) || 16;
   const direction = run.level % 2 === 1 ? "rtl" : "ltr";
   const language = openTypeLanguage(style.lang ?? style["xml:lang"]);
-  const glyphs = shape(run.face, run.text, { features: featuresOf(style), language, direction });
+  // RR-64: outlined text is shaped by HarfBuzz (env.shape), the browser's shaper; the vector PDF keeps fontkit.
+  // HarfBuzz takes the BCP 47 tag (`lang`); fontkit the OpenType language system (`language`).
+  const glyphs = (env.shape ?? shape)(run.face, run.text, { features: featuresOf(style), language, lang: style.lang ?? style["xml:lang"], direction });
   const scale = size / run.face.upem;
   const letterSpacing = parseLength(style["letter-spacing"], { fontSize: size }) ?? 0;
   const wordSpacing = parseLength(style["word-spacing"], { fontSize: size }) ?? 0;

package/dist/pdf-vector.js

@@ -89,7 +89,7 @@ class Converter {
         this.reported.add(key);
         this.unsupported(d.code, d.message, { fontFamily: d.fontFamily, codePoint: d.codePoint });
       },
-      unavailable: (families) => this.error("pdf-font-unavailable", `No embeddable font face is available for ${families.length ? `'${families.join("', '")}'` : "the requested text"}. Supply font files (fontFiles/fontDirs) or keep useBundledFonts enabled.`, {}),
+      unavailable: (families) => this.error("pdf-font-unavailable", `No embeddable font face is available for ${families.length ? `'${families.join("', '")}'` : "the requested text"}. Pass the fonts handle or font folders as fonts, or keep useBundledFonts enabled.`, {}),
     };
   }
 
@@ -744,6 +744,9 @@ class Converter {
       run.fill = await this.paint(run.style.fill, run.style, ctx, box, "fill");
       run.stroke = await this.paint(run.style.stroke, run.style, ctx, box, "stroke");
     }
+    // Text with neither fill nor stroke draws nothing (an outlined slide's invisible readable layer, RR-64): it adds no font,
+    // no glyph and no structure to the PDF.
+    if (!runs.some((run) => run.fill || run.stroke)) return;
     // Runs are drawn in visual (left to right) order. Right-to-left runs are marked /ReversedChars so extractors read
     // their characters back to front, and a cluster whose glyph-to-Unicode map cannot give its text (a ligature, a
     // letter split into base and dots, a mirrored bracket) carries /ActualText; a left-to-right run the map cannot
@@ -1225,7 +1228,7 @@ async function listFonts(directory, { readdir, path }) {
 }
 
 /**
- * Convert SVG slides to a vector PDF. `options` carries the resolved conversion settings (see svgToPdf in raster.js).
+ * Convert SVG slides to a vector PDF. `options` carries the resolved conversion settings (see toPdf in raster.js).
  */
 export async function svgsToVectorPdf(svgs, options) {
   const converter = new Converter(options);

package/dist/pdf.d.ts

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

package/dist/pdf.js

@@ -1,4 +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
+// RR-63: the PDF format entry (Node). The default vector `toPdf` 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 `raster: true` 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";
+export { toPdf } from "./raster.js";

package/dist/player.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserFontsHandle } from "./fonts-browser.js";
-import type { RenderSvgOptions } from "./svg.js";
+import type { ToSvgOptions } from "./svg.js";
 
 /**
  * Why a deck could not be loaded, drawn or presented. `code` is stable: `invalid-document`, `fetch-failed`, `fonts-unavailable`,
@@ -19,8 +19,8 @@ export type BlankMode = "none" | "black" | "white";
 export interface PresentOptions {
   /** The self-hosted font root URL (see `copyPreviewFonts`), or a browser fonts handle the page already has (`loadFonts` from `/fonts-browser`). Without it layout uses estimated widths and system fonts. */
   fonts?: string | BrowserFontsHandle;
-  /** Extra `renderSlideSvg` options (catalogs, imageResolver, date, ...). */
-  renderOptions?: Partial<RenderSvgOptions>;
+  /** Extra `toSvg` options (catalogs, imageResolver, date, ...). */
+  renderOptions?: Partial<ToSvgOptions>;
   /** 1-based slide to start on, in the sequence that plays. Default 1. */
   startSlide?: number;
   /** Play hidden slides too. Default false. */

package/dist/player.js

@@ -632,7 +632,7 @@ async function readSource(source, signal) {
  * player covers the page at once (and asks for full screen), then resolves with the running session when the first slide is
  * drawn. Call it from a click or key handler: full screen and the speaker view both need a user gesture.
  *
- * Options: `fonts` (the self-hosted font root URL, or a browser fonts handle from `loadFonts`), `renderOptions` (extra `renderSlideSvg` options),
+ * Options: `fonts` (the self-hosted font root URL, or a browser fonts handle from `loadFonts`), `renderOptions` (extra `toSvg` options),
  * `startSlide` (1-based), `includeHidden`, `fullscreen` (default true), `presenterView` (open the speaker view too),
  * `role: "presenter"` (this window is the speaker view: for a second tab or window of your page), `channel` (name, or `false`
  * for no sync), `container`, `signal` and `now` (an injectable clock).

package/dist/png.d.ts

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

package/dist/png.js

@@ -1,4 +1,4 @@
-// RR-63: the PNG format entry (Node). `svgToPng` loads the optional peers `@resvg/resvg-js` (and `sharp` for WebP and rotated JPEG
+// RR-63: the PNG format entry (Node). `toPng` 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";
+export { toPng } from "./raster.js";

package/dist/raster.js

@@ -1,5 +1,6 @@
 import {prepareRasterImages} from './raster-images.js';
-import {OPFRenderError,packageName} from './svg.js';
+import {OPFRenderError,packageName,toSvg} from './svg.js';
+import {slideArguments,slideSources} from './slide-sources.js';
 import {separateLigatures} from './font-compatibility.js';
 import {monochromeColorFonts,rasterFontFiles} from './color-fonts.js';
 import {pinScriptClusters} from './raster-text.js';
@@ -7,38 +8,47 @@ import {loadConverter} from './converters.js';
 const DEFAULT_DIMENSIONS = { width: 1280, height: 720 };
 const DEFAULT_RASTER_SCALE = 1;
 const DEFAULT_RASTER_BACKGROUND = "#FFFFFF";
-// RR-12: PDF output is vector (selectable text, vector drawing) unless a caller asks for the raster-backed compatibility mode.
-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.
+// The faces a raster or PDF conversion draws with (RR-74: one `fonts`). The fonts handle (`loadFonts()` from `/fonts-node`) gives its
+// `fontFiles`, 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). Font folders (a path or a list of paths) add every
+// face in them to the bundled base faces. Without either 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 };
+  if (typeof fonts === "string" || Array.isArray(fonts)) return { fontFiles: [], fontDirs: stringArray([fonts].flat()), useBundledFonts: true, loadSystemFonts: false };
+  return { fontFiles: stringArray(fonts.fontFiles), fontDirs: [], 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.
+ * PNG (RR-73): a deck drawn with `toSvg` (`toPng(deck)` gives one PNG per slide, `toPng(deck, 3)` the third slide's PNG,
+ * `toPng(deck, "1-3")` those slides'), or SVG the renderer drew (one SVG gives one PNG, a list a list). `fonts` is the handle
+ * `loadFonts()` returns, so the preview and the PNG draw with the same faces, or font folders for SVG input. Without either the
+ * bundled base faces draw.
  */
-export async function svgToPng(svg, options = {}) {
-  const rendered = await rasterizeSvg(svg, options);
-  return rendered.png;
+export async function toPng(source, slides, options) {
+  ({ slides, options } = slideArguments(slides, options));
+  const { svgs, one } = slideSources(source, slides, options, toSvg);
+  const pngs = [];
+  for (const svg of svgs) pngs.push((await rasterizeSvg(svg, options)).png);
+  return one ? pngs[0] : pngs;
 }
 
-/** 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);
+/**
+ * One PDF (RR-73), a page per slide, of a deck drawn with `toSvg` (all slides, or a selection: `toPdf(deck, "2-4")`) or of SVG
+ * slides the renderer drew. Vector by default (selectable text in embedded subsets); `raster: true` draws each slide as an image.
+ * `fonts` is as for `toPng`.
+ */
+export async function toPdf(source, slides, options) {
+  ({ slides, options } = slideArguments(slides, options));
+  const pdfInputs = slideSources(source, slides, options, toSvg).svgs;
   if (!pdfInputs.length) {
-    throw new OPFRenderError("empty-pdf", "svgToPdf requires at least one SVG slide.");
+    throw new OPFRenderError("empty-pdf", "toPdf needs at least one slide.");
   }
-  const mode = options.mode ?? DEFAULT_PDF_MODE;
-  if (mode !== "vector" && mode !== "raster") {
-    throw new OPFRenderError("invalid-conversion-option", 'mode must be "vector" or "raster".', { option: "mode", value: mode });
+  if (options.raster !== undefined && typeof options.raster !== "boolean") {
+    throw new OPFRenderError("invalid-conversion-option", "raster must be true or false.", { option: "raster", value: options.raster });
   }
-  if (mode === "vector") return vectorPdf(pdfInputs, options);
+  if (options.raster !== true) return vectorPdf(pdfInputs, options);
 
   const { PDFDocument } = await loadPdfLib();
   const pdf = await PDFDocument.create({ updateMetadata: false });
@@ -65,7 +75,7 @@ export async function svgToPdf(svgs, options = {}) {
 async function vectorPdf(inputs, options) {
   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" });
+    throw new OPFRenderError("pdf-system-fonts-unsupported", 'Vector PDF output embeds only the font files you supply: so fonts.loadSystemFonts does not apply. Pass a fonts handle with fontFiles, or font folders, or use raster: true.', { option: "fonts.loadSystemFonts" });
   }
   const scale = positiveNumber(options.rasterFallbackScale, "rasterFallbackScale", 2);
   const fontFiles = [
@@ -77,7 +87,7 @@ async function vectorPdf(inputs, options) {
   const {svgsToVectorPdf} = await import("./pdf-vector.js");
   return svgsToVectorPdf(svgs, {
     fontFiles,
-    fontDirs: stringArray(options.fontDirs),
+    fontDirs: settings.fontDirs,
     defaultFontFamily: options.defaultFontFamily ?? "Roboto",
     sansSerifFamily: options.sansSerifFamily ?? options.defaultFontFamily ?? "Roboto",
     monospaceFamily: options.monospaceFamily ?? "Roboto Mono",
@@ -123,7 +133,7 @@ async function rasterizeSvg(svgInput, options) {
   const font = {
     loadSystemFonts: settings.loadSystemFonts,
     fontFiles,
-    fontDirs: stringArray(options.fontDirs),
+    fontDirs: settings.fontDirs,
     defaultFontFamily: options.defaultFontFamily ?? "Roboto",
     sansSerifFamily: options.sansSerifFamily ?? options.defaultFontFamily ?? "Roboto",
     monospaceFamily: options.monospaceFamily ?? "Roboto Mono"
@@ -181,11 +191,6 @@ async function resolveBundledFontFiles() {
   return (await loadFonts()).fontFiles;
 }
 
-function normalizeSvgList(value) {
-  if (Array.isArray(value)) return value;
-  return [value];
-}
-
 function normalizeSvgInput(value) {
   if (typeof value === "string") return value;
   if (value instanceof Uint8Array) return new TextDecoder().decode(value);

package/dist/script-font-pack.js

@@ -65,7 +65,7 @@ const UNDRAWN_VALUE = /^(?:https?|data|blob|pkg|file|mailto):\S*$/i;
 
 // The built-in variables that copy a document value into drawn text: the inline token and the whole-field reference
 // (a logo or photo reference draws a picture, not text).
-const ORGANIZATION_TOKEN = /\{\{\s*organization\.|var:organization\.(?!logo\b)/;
+const ORGANIZATION_TOKEN = /\{\{\s*organization\.|var:organization\.(?!(?:[^.\s]+\.)?logo\b)/;
 const SPEAKER_TOKEN = /\{\{\s*speaker\.|var:speaker\.(?!photo\b|image\b|avatar\b)/;
 const SECTION_TOKEN = /\{\{\s*slide\.section\s*[|}]/;
 
@@ -130,7 +130,7 @@ 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: their `catalogs` (core `Catalog[]`) go to core's `resolveScriptFonts`
+ * `renderOptions` are the host's `toSvg` 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.
  */
@@ -176,8 +176,8 @@ function* namedFontFamilies(value, key) {
  * itemization, so language-dependent punctuation counts), the scripts its font schemes need (`design`, for example
  * Jpan for a Yu Gothic scheme) and the CJK characters that a glyph fallback might have to draw with another CJK face.
  * The text decides, so a document is analyzed without resolving its layouts and catalogs; `renderOptions` (the host's
- * `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.
+ * `toSvg` 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 `toSvg` throws for it.
  */
 export function analyzePresentationScripts(presentation, profile, renderOptions) {
   profile ??= presentationScriptProfile(presentation, renderOptions);
@@ -198,7 +198,7 @@ export function analyzePresentationScripts(presentation, profile, renderOptions)
  * (Japanese, Korean, Simplified or Traditional Chinese) and makes curly quotes, dashes and the ellipsis
  * East Asian. Text the preview never draws (ids, alt text, sources, assets, catalogs, notes) is ignored.
  * Greek and Cyrillic add nothing: the office registry always carries Noto Sans (the glyph-fallback face) and Roboto covers them.
- * Pass `profile` to reuse a resolved profile. Other options are the host's `renderSvg` options (`catalogs`, see `analyzePresentationScripts`).
+ * Pass `profile` to reuse a resolved profile. Other options are the host's `toSvg` options (`catalogs`, see `analyzePresentationScripts`).
  */
 export function detectPresentationScripts(presentation, { profile, ...renderOptions } = {}) {
   return analyzePresentationScripts(presentation, profile, renderOptions).detected;

package/dist/slide-sources.js

@@ -0,0 +1,47 @@
+// RR-73: what `toPng` and `toPdf` draw. They take a deck (an object, or JSON text) and draw it with `toSvg`, or SVG the renderer
+// already drew (a string or bytes starting with `<`, or a list of them). The second argument is a slide selection for a deck (`3`
+// or `"1-3"`, slides counting from 1) or the options, told apart by type, as for `toSvg`.
+import { parseSlideSelection } from "@openpresentation/opf";
+import { OPFRenderError } from "./svg.js";
+
+/** The slide numbers (from 1) a selection names: a list of numbers or text such as "1,3-5"; core's parser, with the renderer's error. */
+export function selectSlides(slides, count) {
+  try {
+    return parseSlideSelection(slides, count, "slides");
+  } catch (error) {
+    throw new OPFRenderError("invalid-slide-selection", error.message, { option: "slides", slideCount: count, cause: error });
+  }
+}
+
+// The 0.17 option names (RR-73, RR-74): pre-v1 there is no alias, but a call that still passes one fails with the new name.
+const RENAMED = { embedFonts: "text: \"system\" (embedFonts: false)", textAsPaths: "text: \"paths\"", mode: "raster: true (vector is the default)", fontDirs: "fonts: a font folder or a list of them" };
+
+/** Throws for an option of 0.17 that 0.18 renamed, naming its replacement. */
+export function rejectRenamedOptions(options, code) {
+  for (const name of Object.keys(RENAMED)) {
+    if (options?.[name] !== undefined) throw new OPFRenderError(code, `The ${name} option was replaced by ${RENAMED[name]}.`, { option: name });
+  }
+}
+
+/** `(slides, options)` with the options moved into place when the second argument is the options object. */
+export function slideArguments(slides, options) {
+  if (slides !== null && typeof slides === "object" && !Array.isArray(slides)) return { slides: undefined, options: slides };
+  return { slides, options: options ?? {} };
+}
+
+const isSvg = (value) => value instanceof Uint8Array || (typeof value === "string" && /^\s*</.test(value));
+
+/**
+ * The SVG slides to convert, and whether the caller asked for one (a slide number, or one SVG): `draw` is `toSvg`, called with the
+ * conversion options for a deck (they carry the fonts handle and the drawing options).
+ */
+export function slideSources(source, slides, options, draw) {
+  rejectRenamedOptions(options, "invalid-conversion-option");
+  if (Array.isArray(source) || isSvg(source)) {
+    if (slides !== undefined) throw new OPFRenderError("invalid-conversion-option", "A slide selection applies to a deck; SVG input is already drawn, so pass the slides you want.", { option: "slides" });
+    if (Array.isArray(source) && !source.every(isSvg)) throw new OPFRenderError("invalid-svg-input", "A list must hold SVG slides (strings or bytes starting with <).");
+    return { svgs: Array.isArray(source) ? source : [source], one: !Array.isArray(source) };
+  }
+  const drawn = draw(source, slides, options);
+  return typeof drawn === "string" ? { svgs: [drawn], one: true } : { svgs: drawn, one: false };
+}