@openpresentation/opf-render 0.17.1 → 0.18.1

package/dist/fonts-browser.d.ts

@@ -6,7 +6,7 @@ import type {
   FontsHandle,
 } from "./fonts.js";
 import type { AutoScriptSelection, BundledFontPackage, LazyFont, ScriptSelection } from "./fonts-node.js";
-import type { RenderSvgOptions } from "./svg.js";
+import type { ToSvgOptions } from "./svg.js";
 export type { LazyFont } from "./fonts-node.js";
 export type { AutoScriptSelection } from "./fonts-node.js";
 export { detectPresentationScripts, autoScriptSelection } from "./fonts-node.js";
@@ -26,17 +26,17 @@ export interface BrowserFontRegistry extends FontRegistry {
    * family the policy would not resolve, nor for a weight or style nothing draws), once each, from `lazyFontsBaseUrl`.
    * Fetches and verifies every file, then adds the faces to the document and the registry together; on failure nothing
    * changes and the call can be retried. Call it before measuring a document, and again after edits: an edit that adds a
-   * bold or italic run loads just that face. Besides `signal`, the call takes the `renderSvg` options the document resolves
+   * bold or italic run loads just that face. Besides `signal`, the call takes the `toSvg` options the document resolves
    * with (`catalogs`, ...) over the loader's `renderOptions`. A document that does not resolve rejects with the error
-   * `renderSvg` throws for it. After `dispose()` it rejects with `font-registry-disposed`.
+   * `toSvg` throws for it. After `dispose()` it rejects with `font-registry-disposed`.
    */
-  ensureLazyFonts(presentation: unknown, options?: { signal?: AbortSignal } & Partial<RenderSvgOptions>): Promise<LazyFont[]>;
+  ensureLazyFonts(presentation: unknown, options?: { signal?: AbortSignal } & Partial<ToSvgOptions>): Promise<LazyFont[]>;
   /**
    * Synchronous: the vendored faces the presentation draws under the registry's policy that are not loaded yet. Empty means
-   * `ensureLazyFonts` fetches nothing. `renderOptions` are the `renderSvg` options the document resolves with (`catalogs`, ...)
-   * over the loader's `renderOptions`. Throws what `renderSvg` throws for a document that does not resolve.
+   * `ensureLazyFonts` fetches nothing. `renderOptions` are the `toSvg` options the document resolves with (`catalogs`, ...)
+   * over the loader's `renderOptions`. Throws what `toSvg` throws for a document that does not resolve.
    */
-  pendingLazyFonts(presentation: unknown, renderOptions?: Partial<RenderSvgOptions>): LazyFont[];
+  pendingLazyFonts(presentation: unknown, renderOptions?: Partial<ToSvgOptions>): LazyFont[];
 
   /** Load script faces for ISO 15924 codes (or "all") from `scriptBaseUrl`. Resolves with the newly loaded package names. */
   loadScripts(scripts: ScriptSelection, options?: { signal?: AbortSignal }): Promise<string[]>;
@@ -49,15 +49,15 @@ export interface BrowserFontRegistry extends FontRegistry {
    * OPFFontError whose `details` are `{ loaded: string[]; failed: {package, code, message}[] }`. A failed call (fetch, hash, FontFace load) leaves nothing loaded and can be retried; after
    * `dispose()` it rejects with `font-registry-disposed`.
    */
-  ensureScripts(presentation: unknown, options?: { signal?: AbortSignal } & Partial<RenderSvgOptions>): Promise<AutoScriptSelection & { loaded: string[]; uncovered: string[] }>;
+  ensureScripts(presentation: unknown, options?: { signal?: AbortSignal } & Partial<ToSvgOptions>): Promise<AutoScriptSelection & { loaded: string[]; uncovered: string[] }>;
   /** Synchronous: package names the presentation needs that are not loaded yet. Empty means `ensureScripts` fetches nothing, so a host can render immediately. Text decides, so a document is analyzed without resolving its layouts; `renderOptions.catalogs` matter for font schemes only the host's catalogs have (FF-41). */
-  pendingScripts(presentation: unknown, renderOptions?: Partial<RenderSvgOptions>): string[];
+  pendingScripts(presentation: unknown, renderOptions?: Partial<ToSvgOptions>): string[];
   /** Names of the script-pack packages loaded so far. */
   readonly loadedScriptPackages: string[];
 }
 /**
  * The fonts handle of a browser: the faces you list, registered with the document, and on demand the script and vendored faces a deck
- * draws. Pass it as `{ fonts }` to `renderSvg`, `renderSlideSvg`, `<opf-deck>` and the player, core `paginate` and `validate`, and the editor.
+ * draws. Pass it as `{ fonts }` to `toSvg`, `<opf-deck>` and the player, core `paginate` and `validate`, and the editor.
  * The registry behind it keeps the lower-level loaders (`ensureLazyFonts`, `ensureScripts`, `loadScripts`, `pendingLazyFonts`, `pendingScripts`).
  */
 export interface BrowserFontsHandle extends FontsHandle {
@@ -66,13 +66,13 @@ export interface BrowserFontsHandle extends FontsHandle {
   dispose(): void;
   /**
    * Load the vendored and script faces the presentation draws (each hash-verified, all or nothing), repeating while loading changes what
-   * is needed. Cheap when nothing is needed. Besides `signal`, the call takes the `renderSvg` options the document resolves with
-   * (`catalogs`, ...) over the loader's `renderOptions`. A document that does not resolve rejects with what `renderSvg` throws for it; after
+   * is needed. Cheap when nothing is needed. Besides `signal`, the call takes the `toSvg` options the document resolves with
+   * (`catalogs`, ...) over the loader's `renderOptions`. A document that does not resolve rejects with what `toSvg` throws for it; after
    * `dispose()` it rejects with `font-registry-disposed`.
    */
-  ensure(presentation: unknown, options?: { signal?: AbortSignal } & Partial<RenderSvgOptions>): Promise<EnsureResult>;
-  /** Synchronous: the vendored files and script packages `ensure` would fetch. Empty means a render can start now. Throws what `renderSvg` throws for a document that does not resolve. */
-  pending(presentation: unknown, renderOptions?: Partial<RenderSvgOptions>): string[];
+  ensure(presentation: unknown, options?: { signal?: AbortSignal } & Partial<ToSvgOptions>): Promise<EnsureResult>;
+  /** Synchronous: the vendored files and script packages `ensure` would fetch. Empty means a render can start now. Throws what `toSvg` throws for a document that does not resolve. */
+  pending(presentation: unknown, renderOptions?: Partial<ToSvgOptions>): string[];
 }
 export declare function loadFonts(
   options?: FontRegistryOptions & {
@@ -83,13 +83,14 @@ export declare function loadFonts(
     signal?: AbortSignal;
     /**
      * RR-65: harfbuzzjs's `harfbuzz-subset.wasm` (the URL the host serves it from, its bytes or a compiled WebAssembly.Module). With
-     * it the handle carries `subsets`, and every SVG `renderSvg` draws with this handle embeds each face cut to the characters the
+     * it the handle carries `subsets`, and every SVG `toSvg` draws with this handle embeds each face cut to the characters the
      * slide draws. Without it a browser handle embeds whole faces (the Node handle always subsets).
      */
     subsetWasm?: string | URL | ArrayBuffer | ArrayBufferView | WebAssembly.Module;
     /**
-     * RR-64: harfbuzzjs's `harfbuzz.wasm` (its URL, bytes or a compiled WebAssembly.Module). With it `textAsPaths` shapes outlines with
-     * HarfBuzz, as the browser shapes text; without it a browser handle shapes them with fontkit (the Node handle always uses HarfBuzz).
+     * RR-64: harfbuzzjs's `harfbuzz.wasm` (its URL, bytes or a compiled WebAssembly.Module). With it `text: "paths"` shapes outlines, and
+     * `toPdf` the vector PDF's text, with HarfBuzz, as the browser shapes text; without it a browser handle shapes them with fontkit (the
+     * Node handle always uses HarfBuzz).
      */
     shapeWasm?: string | URL | ArrayBuffer | ArrayBufferView | WebAssembly.Module;
     crypto?: { subtle: SubtleCrypto };
@@ -111,11 +112,11 @@ export declare function loadFonts(
      */
     extraLazyFonts?: readonly ExtraLazyFont[];
     /**
-     * FF-41: the `renderSvg` options the documents resolve with (`catalogs` above all), the default for `pendingLazyFonts`,
+     * FF-41: the `toSvg` options the documents resolve with (`catalogs` above all), the default for `pendingLazyFonts`,
      * `ensureLazyFonts`, `pendingScripts` and `ensureScripts`. A layout or font scheme id that only the host's catalogs have
      * resolves the same way here as it does when the host renders. A call's own options win.
      */
-    renderOptions?: Partial<RenderSvgOptions>;
+    renderOptions?: Partial<ToSvgOptions>;
   },
 ): Promise<BrowserFontsHandle>;
 export declare function scriptFontPackages(scripts: ScriptSelection): BundledFontPackage[];
@@ -138,10 +139,10 @@ export interface ExtraLazyFont { family: string; weight: number; italic?: boolea
 export declare function splitStartupFaces<T extends { family: string; weight: number; italic?: boolean }>(faces: readonly T[], options?: { startup?: (face: T) => boolean }): { startup: T[]; rest: T[] };
 /**
  * The font families a presentation's slides resolve (heading, body and code roles of every slide). `options` are the
- * `renderSvg` options the document resolves with (`catalogs`, ...). A document that does not resolve throws what `renderSvg`
+ * `toSvg` options the document resolves with (`catalogs`, ...). A document that does not resolve throws what `toSvg`
  * throws for it (FF-41: it no longer returns an empty set). This is the role families, not what is drawn: see `presentationFaces`.
  */
-export declare function presentationFamilies(presentation: unknown, options?: Partial<RenderSvgOptions>): Set<string>;
+export declare function presentationFamilies(presentation: unknown, options?: Partial<ToSvgOptions>): Set<string>;
 /** A face request or a drawn face: a family, a weight and a style. */
 export interface FaceRequest { family: string; weight: number; italic: boolean }
 /**
@@ -151,16 +152,16 @@ export interface FaceRequest { family: string; weight: number; italic: boolean }
  * faces are the styles as the document names them. With `registry` (`{faces, policy, aliases, fallbackFamily}`: the faces a
  * registry holds or could hold and its substitution options) every style resolves as that registry resolves it, in the two
  * steps drawing takes (role family, then weight within it), and the result is the faces the registry paints.
- * `options` are the `renderSvg` options the document resolves with; a document that does not resolve throws what `renderSvg`
+ * `options` are the `toSvg` options the document resolves with; a document that does not resolve throws what `toSvg`
  * throws for it.
  */
-export declare function presentationFaces(presentation: unknown, options?: Partial<RenderSvgOptions>, registry?: { faces: Iterable<FaceRequest>; policy?: "none" | "metric" | "visual"; aliases?: ReadonlyMap<string, string>; fallbackFamily?: string }): FaceRequest[];
+export declare function presentationFaces(presentation: unknown, options?: Partial<ToSvgOptions>, registry?: { faces: Iterable<FaceRequest>; policy?: "none" | "metric" | "visual"; aliases?: ReadonlyMap<string, string>; fallbackFamily?: string }): FaceRequest[];
 /**
  * The vendored faces (of `lazy`) a presentation draws that the registry does not hold. `held` is `registry.describeFaces()`,
  * `loaded` the lazy files already loaded; `policy`, `aliases` and `fallbackFamily` are the registry's. Face level: only the
  * drawn faces, so an edit adding a bold run adds one face.
  */
-export declare function lazyFacesNeeded(presentation: unknown, renderOptions: Partial<RenderSvgOptions> | undefined, context: { lazy: readonly LazyFont[]; held: Iterable<FaceRequest>; loaded?: ReadonlySet<string>; policy?: "none" | "metric" | "visual"; aliases?: ReadonlyMap<string, string>; fallbackFamily?: string }): LazyFont[];
+export declare function lazyFacesNeeded(presentation: unknown, renderOptions: Partial<ToSvgOptions> | undefined, context: { lazy: readonly LazyFont[]; held: Iterable<FaceRequest>; loaded?: ReadonlySet<string>; policy?: "none" | "metric" | "visual"; aliases?: ReadonlyMap<string, string>; fallbackFamily?: string }): LazyFont[];
 /**
  * The vendored faces a list of requests needs that the registry does not hold, following the registry's own order and
  * `policy` (default "visual"): the family itself, an alias target, the declared replacement, then its alternates.

package/dist/fonts-browser.js

@@ -97,7 +97,7 @@ async function loadRegistry(entries, options = {}) {
   // Script faces (FF-19) are loaded lazily, once a document needs them, and only for the scripts it uses.
   const scriptPackages = new Set();
   let queue = Promise.resolve(), disposed = false;
-  // FF-41: the `renderSvg` options a document resolves with (`catalogs`, ...). `options.renderOptions` are the defaults; a call's own
+  // FF-41: the `toSvg` options a document resolves with (`catalogs`, ...). `options.renderOptions` are the defaults; a call's own
   // options (everything but `signal`) are added over them, so a host that passes its canvas options gets the same resolution here.
   const renderOptionsFor = (callOptions) => { const { signal: _signal, ...own } = callOptions ?? {}; return { ...options.renderOptions, ...own }; };
   const gone = () => new OPFFontError("font-registry-disposed", "The font registry was disposed.");
@@ -151,7 +151,7 @@ async function loadRegistry(entries, options = {}) {
      * fallback needs for characters the loaded faces lack. Cheap when nothing new is needed; call it after edits and
      * render again afterwards. Resolves with the detected scripts, the packages loaded by this call, the scripts no
      * pinned font serves and `uncovered`, drawn CJK characters no loaded face covers (the renderer reports
-     * `missing-glyph` for them). Besides `signal`, the call takes the `renderSvg` options the document resolves with
+     * `missing-glyph` for them). Besides `signal`, the call takes the `toSvg` options the document resolves with
      * (`catalogs`, ...) over the loader's `renderOptions`. Each package loads all or nothing. If some package fails, the others still load: the
      * call then rejects with an OPFFontError (the first failure's code) whose `details` hold `loaded` (packages this
      * call did load) and `failed` (`{package, code, message}` per failed package); nothing is lost and a later call
@@ -176,7 +176,7 @@ async function loadRegistry(entries, options = {}) {
       }
       return { ...selection, loaded: loadedNow, uncovered: uncoveredCjkCharacters(analysis, { covers }) };
     },
-    /** Synchronous: script-pack packages the presentation needs that are not loaded yet. Empty means `ensureScripts` would fetch nothing. `renderOptions` are the `renderSvg` options the document resolves with (`catalogs`, ...). */
+    /** Synchronous: script-pack packages the presentation needs that are not loaded yet. Empty means `ensureScripts` would fetch nothing. `renderOptions` are the `toSvg` options the document resolves with (`catalogs`, ...). */
     pendingScripts(presentation, renderOptions) {
       const analysis = analyzePresentationScripts(presentation, undefined, renderOptionsFor(renderOptions));
       const primary = scriptFontPackages(scriptSelectionOf(analysis).scripts).map((item) => item.name).filter((name) => !scriptPackages.has(name));
@@ -194,7 +194,7 @@ async function loadRegistry(entries, options = {}) {
   const policy = options.substitutionPolicy ?? "none";
   const aliasTargets = new Map(Object.entries(options.aliases ?? {}).map(([from, to]) => [from.toLowerCase(), to]));
   // Face level (FF-41): the faces the document draws, resolved as the registry resolves them with every vendored face loaded.
-  // A document that does not resolve throws what `renderSvg` throws for it.
+  // A document that does not resolve throws what `toSvg` throws for it.
   const neededLazy = (presentation, callOptions) => lazyFacesNeeded(presentation, renderOptionsFor(callOptions), { lazy, held: registry.describeFaces(), loaded: lazyLoaded, policy, aliases: aliasTargets, fallbackFamily: options.fallbackFamily });
   const lazyBaseUrl = () => {
     if (typeof options.lazyFontsBaseUrl !== "string" || !options.lazyFontsBaseUrl)
@@ -210,8 +210,8 @@ async function loadRegistry(entries, options = {}) {
      * policy (nothing is downloaded for a family the policy would not resolve), once each. All or nothing: on any failure
      * (fetch, hash, FontFace.load, registry) the document and registry are unchanged and the call can be retried. Cheap when
      * nothing is needed. Call it before measuring a document, and again after edits that change fonts. Resolves with the faces
-     * added. Besides `signal`, the call takes the `renderSvg` options the document resolves with (`catalogs`, ...) over the
-     * loader's `renderOptions`; a document that does not resolve rejects with what `renderSvg` throws for it.
+     * added. Besides `signal`, the call takes the `toSvg` options the document resolves with (`catalogs`, ...) over the
+     * loader's `renderOptions`; a document that does not resolve rejects with what `toSvg` throws for it.
      */
     ensureLazyFonts(presentation, callOptions = {}) {
       const result = queue.then(async () => {
@@ -247,7 +247,7 @@ async function loadRegistry(entries, options = {}) {
       queue = result.catch(() => {});
       return result;
     },
-    /** Synchronous: the vendored faces the presentation draws under the registry's policy that are not loaded yet. Empty means `ensureLazyFonts` fetches nothing. `renderOptions` are the `renderSvg` options the document resolves with (`catalogs`, ...). */
+    /** Synchronous: the vendored faces the presentation draws under the registry's policy that are not loaded yet. Empty means `ensureLazyFonts` fetches nothing. `renderOptions` are the `toSvg` options the document resolves with (`catalogs`, ...). */
     pendingLazyFonts: (presentation, renderOptions) => neededLazy(presentation, renderOptions),
   });
   /** Names of the script-pack packages loaded so far. */
@@ -277,7 +277,7 @@ const MAX_ENSURE_ROUNDS = 4;
 /**
  * The fonts handle for a browser: the faces you list (`faces`, each `{ url | data, family, weight, italic, sha256 }`, fetched and
  * hash-verified, then registered with the document) and, on demand, the script and vendored faces a deck draws. Pass it as `{ fonts }` to
- * `renderSvg`, `renderSlideSvg`, `<opf-deck>` and the player, core `paginate` and `validate`, and the editor. `scripts`, `scriptBaseUrl`,
+ * `toSvg`, `<opf-deck>` and the player, core `paginate` and `validate`, and the editor. `scripts`, `scriptBaseUrl`,
  * `lazyFontsBaseUrl`, `extraLazyFonts`, `renderOptions`, `signal`, `document`, `fetch`, `crypto` and the registry options
  * (`substitutionPolicy`, `aliases`, `fallbackFamily`, `themeFonts`, `strictGlyphs`) are as for the registry (see `fonts-browser.d.ts`).
  * `dispose()` removes every face from the document.
@@ -320,7 +320,7 @@ export async function loadFonts({ faces = [], subsetWasm, shapeWasm, ...options
     textMeasurement: registry.textMeasurement,
     get embeddedFonts() { if (stale) { embedded = registry.embeddedFonts; stale = false; } return embedded; },
     registry,
-    // RR-64: the outline engine `renderSvg(deck, { fonts, textAsPaths: true })` draws text with, over this registry's faces.
+    // RR-64: the outline engine `toSvg(deck, { fonts, text: "paths" })` draws text with, over this registry's faces.
     outlines: textOutlines({ registry, shaper }),
     // RR-65: with `subsetWasm`, the subset engine that cuts each face an SVG embeds to the characters the slide draws.
     ...(subsetter ? { subsets: fontSubsets(registry, subsetter) } : {}),
@@ -329,8 +329,8 @@ export async function loadFonts({ faces = [], subsetWasm, shapeWasm, ...options
     /**
      * Load the vendored and script faces the presentation draws, each hash-verified, all or nothing, and repeat while loading
      * changes what is needed (a script face can need a vendored one). Cheap when nothing is needed. Besides `signal`, the call
-     * takes the `renderSvg` options the document resolves with (`catalogs`, ...) over the loader's `renderOptions`. A document that
-     * does not resolve rejects with what `renderSvg` throws for it. After `dispose()` it rejects with `font-registry-disposed`.
+     * takes the `toSvg` options the document resolves with (`catalogs`, ...) over the loader's `renderOptions`. A document that
+     * does not resolve rejects with what `toSvg` throws for it. After `dispose()` it rejects with `font-registry-disposed`.
      */
     async ensure(presentation, callOptions = {}) {
       const lazy = [], scripts = [];
@@ -344,7 +344,7 @@ export async function loadFonts({ faces = [], subsetWasm, shapeWasm, ...options
       }
       return { scripts, lazy, uncovered };
     },
-    /** Synchronous: the files and script packages `ensure` would fetch. Empty means a render can start now. Throws what `renderSvg` throws for a document that does not resolve. */
+    /** Synchronous: the files and script packages `ensure` would fetch. Empty means a render can start now. Throws what `toSvg` throws for a document that does not resolve. */
     pending,
     dispose: () => registry.dispose(),
   };

package/dist/fonts-node.d.ts

@@ -1,5 +1,5 @@
 import type {FontRegistry,FontRegistryOptions,FontFaceInput,FontsHandle,EnsureResult,ScriptFontProfile} from "./fonts.js";
-import type {RenderSvgOptions} from "./svg.js";
+import type {ToSvgOptions} from "./svg.js";
 /** A caller-supplied face (FF-31), for example a licensed copy of the real font. Node callers may pass a file path. */
 export type CallerFontFace = FontFaceInput | (Omit<FontFaceInput, "data"> & {path: string});
 /** "all" or ISO 15924 codes (`Jpan`, `Hans`, `Hant`, `Kore`, `Arab`, `Hebr`, `Deva`, `Thai`, ...). */
@@ -16,9 +16,9 @@ export interface AutoScriptSelection {
 /** Script-pack packages that `scripts: "auto"` loaded or found not installed. */
 export interface AppliedScriptSelection extends AutoScriptSelection { packages: string[]; notInstalled: string[]; /** Drawn CJK characters no loaded face covers (glyph fallback stopped at its cap). */ uncovered?: string[] }
 /** Script keys whose faces a preview of the presentation needs: text decides, the document language only tells Han scripts apart. */
-/** `options` may also carry the `renderSvg` options the document resolves with (`catalogs`): a font scheme that exists only in the host's catalogs and names a script font selects that font's script (FF-41). */
-export declare function detectPresentationScripts(presentation: unknown, options?: { profile?: ScriptFontProfile } & Partial<RenderSvgOptions>): string[];
-export declare function autoScriptSelection(presentation: unknown, options?: { profile?: ScriptFontProfile } & Partial<RenderSvgOptions>): AutoScriptSelection;
+/** `options` may also carry the `toSvg` options the document resolves with (`catalogs`): a font scheme that exists only in the host's catalogs and names a script font selects that font's script (FF-41). */
+export declare function detectPresentationScripts(presentation: unknown, options?: { profile?: ScriptFontProfile } & Partial<ToSvgOptions>): string[];
+export declare function autoScriptSelection(presentation: unknown, options?: { profile?: ScriptFontProfile } & Partial<ToSvgOptions>): AutoScriptSelection;
 export interface ScriptPackOptions {
   /** Caller-supplied faces, loaded first so a licensed real font resolves as an exact face (FF-31). */
   faces?: readonly CallerFontFace[];
@@ -30,10 +30,14 @@ export interface ScriptPackOptions {
   scripts?: ScriptSelection | "auto";
   /** The presentation whose text decides `scripts: "auto"`. */
   presentation?: unknown;
-  /** The `renderSvg` options the presentation resolves with (`catalogs`, ...), for the font schemes `scripts: "auto"` reads (FF-41). */
-  renderOptions?: Partial<RenderSvgOptions>;
-  /** Receives `script-font-unavailable` and `script-font-not-installed` for `scripts: "auto"`. */
-  onDiagnostic?: (diagnostic: {code: string; message: string; script?: string; package?: string; scripts?: string[]}) => void;
+  /** The `toSvg` options the presentation resolves with (`catalogs`, ...), for the font schemes `scripts: "auto"` reads (FF-41). */
+  renderOptions?: Partial<ToSvgOptions>;
+  /**
+   * Receives `script-font-unavailable` and `script-font-not-installed` for `scripts: "auto"`, and from `loadFonts`
+   * `harfbuzz-unavailable` when a harfbuzzjs .wasm (`file`) cannot be loaded, for example in a bundled server that did not ship it:
+   * the handle then has no `subsets`, or shapes outlines with fontkit.
+   */
+  onDiagnostic?: (diagnostic: {code: string; message: string; script?: string; package?: string; scripts?: string[]; file?: string}) => void;
 }
 /** A vendored face that an SVG embeds only when its text names the family (the open families and Intos), and that browser hosts load on demand from a separate hash-pinned file. */
 export interface LazyFont { readonly package: string; readonly family: string; readonly weight: number; readonly italic: boolean; /** Path relative to the package root, for example fonts/intos/Intos-Regular.ttf. */ readonly file: string; readonly sha256: string; readonly license: string; readonly renamedFrom?: string; /** Set on a host's extra lazy face (`extraLazyFonts`, `package: "host"`): where the host serves the file from. */ readonly url?: string }
@@ -74,7 +78,7 @@ export declare function scriptFontPackages(scripts: ScriptSelection): BundledFon
 export interface NodeFontsHandle extends FontsHandle {
   readonly registry: NodeFontRegistry;
   readonly manifest: BundledFontManifest;
-  /** Every font file the handle holds, for `svgToPng` and `svgToPdf`; includes the script faces `ensure` loaded. */
+  /** Every font file the handle holds, for `toPng` and `toPdf`; includes the script faces `ensure` loaded. */
   readonly fontFiles: string[];
   /** The files are already in `fontFiles`, so a conversion adds no bundled faces. */
   readonly useBundledFonts: false;
@@ -86,9 +90,9 @@ export interface NodeFontsHandle extends FontsHandle {
    * the new faces. A package that is not installed or a script no pinned font serves is reported once through `onDiagnostic`.
    * Resolves with the packages this call added (`scripts`; `lazy` is empty: Node loads every vendored face with its pack).
    */
-  ensure(presentation: unknown, options?: { onDiagnostic?: ScriptPackOptions["onDiagnostic"]; renderOptions?: Partial<RenderSvgOptions> }): Promise<EnsureResult>;
+  ensure(presentation: unknown, options?: { onDiagnostic?: ScriptPackOptions["onDiagnostic"]; renderOptions?: Partial<ToSvgOptions> }): Promise<EnsureResult>;
   /** Synchronous: the script packages the presentation needs that are not loaded yet. */
-  pending(presentation: unknown, renderOptions?: Partial<RenderSvgOptions>): string[];
+  pending(presentation: unknown, renderOptions?: Partial<ToSvgOptions>): string[];
 }
 export interface LoadFontsOptions extends FontRegistryOptions, ScriptPackOptions {
   /** `base` (default): the bundled Roboto faces. `office`: the metric and visual substitutes for the Office families plus the open families font schemes select. `none`: only the `faces` you supply. */

package/dist/fonts-node.js

@@ -1,6 +1,4 @@
 import { readFile } from "node:fs/promises";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { createFontRegistry, OPFFontError } from "./font-registry.js";
@@ -9,12 +7,12 @@ import { lazyFontList } from "./lazy-font-list.js";
 import { textOutlines } from "./text-paths.js";
 import { createSubsetter, fontSubsets } from "./font-subset.js";
 import { createShaper } from "./hb-shape.js";
+import { packageRoot, resolveInstalled } from "./node-resolve.js";
 export { BUNDLED_FONT_MANIFEST } from "./font-manifest.js";
 import { analyzePresentationScripts, autoScriptSelection, nextFallbackPackage, scriptFontPackages, scriptSelectionOf, uncoveredCjkCharacters } from "./script-font-pack.js";
 export { autoScriptSelection, detectPresentationScripts, scriptFontPackages } from "./script-font-pack.js";
 // Script faces are embedded in a standalone SVG only when the slide's text uses their family.
 const embedUsed = entries => entries.map(entry => ({...entry, embed: "used"}));
-const require = createRequire(import.meta.url);
 
 async function verifiedFile(file, expected, details) {
   let bytes;
@@ -33,7 +31,7 @@ const FALLBACK_PACKAGE = "@expo-google-fonts/noto-sans";
 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; }
+    try { resolveInstalled(`${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(" ")}`;
@@ -50,7 +48,7 @@ async function loadPackages(packages, skipped, {fallbackOnly = false, what = "Th
     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
       // embedded in an SVG only when the slide's text names the family (embed "used"); raster output reads the files.
-      const directory = fileURLToPath(new URL(`../${pkg.vendored}/`, import.meta.url));
+      const directory = path.join(packageRoot, pkg.vendored);
       let license = (await verifiedFile(path.join(directory, pkg.licenseFile), pkg.licenseSha256, {package:pkg.name, file:pkg.licenseFile})).toString("utf8");
       // A notice file carries provenance and upstream copyright lines that the upstream license file omits.
       if (pkg.noticeFile) license += "\n\n" + (await verifiedFile(path.join(directory, pkg.noticeFile), pkg.noticeSha256, {package:pkg.name, file:pkg.noticeFile})).toString("utf8");
@@ -66,7 +64,7 @@ async function loadPackages(packages, skipped, {fallbackOnly = false, what = "Th
     }
     let manifestPath, installed;
     try {
-      manifestPath = require.resolve(`${pkg.name}/package.json`);
+      manifestPath = resolveInstalled(`${pkg.name}/package.json`);
       installed = JSON.parse(await readFile(manifestPath, "utf8"));
     } catch (error) {
       if (skipped) { skipped.push({package: pkg.name, version: pkg.version, scripts: [...pkg.scripts]}); continue; }
@@ -95,7 +93,7 @@ const loadPack = pack => loadPackages(BUNDLED_FONT_MANIFEST.packages.filter(item
 /**
  * Adds the script pack. `scripts` is 'all', ISO 15924 codes, or 'auto' (FF-19): detect the scripts the
  * `presentation` draws and load only their faces. Auto never fails on a missing optional package or a
- * script no pinned font serves; it reports them through `onDiagnostic` and `selection`. `renderOptions` are the host's `renderSvg`
+ * script no pinned font serves; it reports them through `onDiagnostic` and `selection`. `renderOptions` are the host's `toSvg`
  * options (see `analyzePresentationScripts`).
  */
 async function withScripts(loaded, scripts, {presentation, onDiagnostic, renderOptions} = {}) {
@@ -250,25 +248,26 @@ async function ensureFonts(registry, loaded, presentation, {onDiagnostic, render
 }
 
 // RR-65: hb-subset from the pinned harfbuzzjs package (MIT), compiled once per process. The module has no imports, so it is
-// instantiated synchronously and renderSvg stays synchronous. A copy that cannot be loaded leaves the handle without `subsets`
+// instantiated synchronously and toSvg stays synchronous. A copy that cannot be loaded leaves the handle without `subsets`
 // (whole faces, as before RR-65): a byte saving never stops fonts from loading.
-let subsetterPromise;
-function nodeSubsetter() {
-  subsetterPromise ??= readFile(require.resolve("harfbuzzjs/dist/harfbuzz-subset.wasm")).then(createSubsetter, () => null).catch(() => null);
-  return subsetterPromise;
-}
-
 // RR-64 phase 2: HarfBuzz's shaper (harfbuzz.wasm of the same package) for text drawn as outlines, so the outlines are shaped as
 // a browser shapes the text. Without it outlines are shaped with fontkit.
-let shaperPromise;
-function nodeShaper() {
-  shaperPromise ??= readFile(require.resolve("harfbuzzjs/dist/harfbuzz.wasm")).then(createShaper, () => null).catch(() => null);
-  return shaperPromise;
+// render#199: a file that cannot be found (a bundled server that did not ship it) loads as null too, and `loadFonts` reports it
+// through `onDiagnostic` (`harfbuzz-unavailable`).
+const HARFBUZZ = {
+  subsets: {file: "harfbuzzjs/dist/harfbuzz-subset.wasm", create: createSubsetter, without: "standalone SVG embeds whole faces instead of subsets"},
+  shaper: {file: "harfbuzzjs/dist/harfbuzz.wasm", create: createShaper, without: "text drawn as outlines is shaped with fontkit instead of HarfBuzz"},
+};
+const harfbuzzEngines = {};
+function nodeHarfbuzz(kind) {
+  const {file, create} = HARFBUZZ[kind];
+  harfbuzzEngines[kind] ??= Promise.resolve().then(() => readFile(resolveInstalled(file))).then(create).catch(() => null);
+  return harfbuzzEngines[kind];
 }
 
 /**
  * The fonts handle: one set of verified font inputs for layout, SVG, editor, PPTX and Node raster export. Pass it as `{ fonts }` to
- * `renderSvg`, `renderSlideSvg`, `svgToPng`, `svgToPdf`, core `paginate` and `validate`, and `toPptx`.
+ * `toSvg`, `toPng`, `toPdf`, core `paginate` and `validate`, and `toPptx`.
  *
  * Bundled, openly licensed faces only: no system font discovery and no network requests. `pack`: `base` (default, Roboto),
  * `office` (the Office substitutes and the open families) or `none` (only the `faces` you supply). Everything else
@@ -285,7 +284,11 @@ export async function loadFonts({pack = "base", embedScriptFonts = false, ...opt
   // The embedded list is base64 of every face: computed on first use, and again after `ensure` added faces.
   let embeddedFonts, fontFiles = [...registry.fontFiles];
   const refresh = () => { embeddedFonts = undefined; fontFiles = [...registry.fontFiles]; };
-  const [subsetter, shaper] = await Promise.all([nodeSubsetter(), nodeShaper()]);
+  const [subsetter, shaper] = await Promise.all([nodeHarfbuzz("subsets"), nodeHarfbuzz("shaper")]);
+  for (const [kind, engine] of [["subsets", subsetter], ["shaper", shaper]]) if (!engine) {
+    const {file, without} = HARFBUZZ[kind];
+    options.onDiagnostic?.({code: "harfbuzz-unavailable", package: "harfbuzzjs", file, message: `${file} could not be loaded, so ${without}. Ship the harfbuzzjs package with the server.`});
+  }
   return {
     textMeasurement: registry.textMeasurement,
     get embeddedFonts() { return (embeddedFonts ??= selectEmbedded()); },
@@ -293,7 +296,7 @@ export async function loadFonts({pack = "base", embedScriptFonts = false, ...opt
     useBundledFonts: false,
     loadSystemFonts: false,
     registry,
-    // RR-64: the outline engine `renderSvg(deck, { fonts, textAsPaths: true })` draws text with, over this registry's faces.
+    // RR-64: the outline engine `toSvg(deck, { fonts, text: "paths" })` draws text with, over this registry's faces.
     outlines: textOutlines({ registry, shaper }),
     // RR-65: the subset engine that cuts each face an SVG embeds to the characters the slide draws.
     ...(subsetter ? { subsets: fontSubsets(registry, subsetter) } : {}),

package/dist/fonts.d.ts

@@ -34,14 +34,14 @@ export interface FontRegistryOptions {
 export declare const FONT_COMPATIBILITY: readonly Readonly<{requestedFamily:string;substitutes:readonly string[];compatibility:"metric"|"visual";weights?:readonly number[];weight?:number;source?:string;measured?:FontReplacementMeasurement;decision?:string;metricModeFallback?:true;licenseClass?:FontPolicyEntry['licenseClass'];note:string}>[];
 export declare const EXPERIMENTAL_FONT_CANDIDATES: readonly Readonly<{requestedFamily:string;substitute:string;source:string;note:string}>[];
 /**
- * What the deck-level functions read from their `fonts` option: `renderSvg`, `renderSlideSvg` and `<opf-deck>` take the measurement and
- * the faces to embed; `svgToPng` and `svgToPdf` (Node) take the font files; core `paginate`, `validate` and `resolveSlideContext` take the
+ * What the deck-level functions read from their `fonts` option: `toSvg` and `<opf-deck>` take the measurement and
+ * the faces to embed; `toPng` and `toPdf` (Node) take the font files; core `paginate`, `validate` and `resolveSlideContext` take the
  * measurement. The object `loadFonts()` returns is a `FontsHandle`, which extends this; any object with these fields works.
  */
 export interface RenderFonts {
   /** Measures text with the real faces. Without it layout uses core's portable estimate. */
   textMeasurement?: TextMeasurement;
-  /** 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). */
+  /** Faces `toSvg` 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[];
@@ -49,15 +49,22 @@ export interface RenderFonts {
   useBundledFonts?: boolean;
   /** Whether the raster conversion loads system fonts. Default false (the output never depends on the machine). */
   loadSystemFonts?: boolean;
-  /** The outline engine `textAsPaths: true` draws text with (RR-64); a `loadFonts` handle carries one over its registry's faces. */
+  /** The outline engine `text: "paths"` draws text with (RR-64); a `loadFonts` handle carries one over its registry's faces. */
   outlines?: TextOutlines;
   /** The subset engine (RR-65): each face an SVG embeds is cut to the characters the slide draws. The Node `loadFonts` handle carries one; a browser handle with `subsetWasm`. */
   subsets?: FontSubsets;
 }
 /** Cuts an embedded face to code points (RR-65), with hb-subset; a face whose license, Reserved Font Name or fsType does not allow it keeps its own data URL. */
 export interface FontSubsets { subsetDataUrl(font: EmbeddedFont, codePoints: Iterable<number>): string }
-/** Draws a slide's text as glyph outlines (RR-64). Read by `renderSvg`; hosts pass the handle and `textAsPaths: true`. */
-export interface TextOutlines { outlineSlideText(content: string[], options: object): { content: string[]; defs: string } }
+/** Draws a slide's text as glyph outlines (RR-64). Read by `toSvg`; hosts pass the handle and `text: "paths"`. */
+export interface TextOutlines {
+  outlineSlideText(content: string[], options: object): { content: string[]; defs: string };
+  /**
+   * HarfBuzz shaping of one run of a face (opf-render#188), present when the handle has the shaper (the Node handle always, a browser
+   * handle with `shapeWasm`). Read by `toPdf`, which then shapes the vector PDF's text as the browser shapes it; fontkit otherwise.
+   */
+  shape?(face: { hash: string; data: Uint8Array }, text: string, options?: { direction?: "ltr" | "rtl"; lang?: string; features?: Record<string, boolean> }): { gid: number; codePoints: number[]; advance: number; xOffset: number; yOffset: number }[];
+}
 /** What `fonts.ensure(presentation)` loaded: the script packages and vendored faces that were missing, and drawn CJK characters no face covers. */
 export interface EnsureResult { scripts: string[]; lazy: LazyFont[]; uncovered: string[] }
 /** The fonts handle `loadFonts()` returns from `/fonts-node` and `/fonts-browser`: pass it as `{ fonts }` to every deck-level function. */
@@ -66,7 +73,7 @@ export interface FontsHandle extends RenderFonts {
   readonly embeddedFonts: EmbeddedFont[];
   /** The face registry behind the handle (shaping, resolution, lazy and script loading). */
   readonly registry: FontRegistry;
-  /** The outline engine for `textAsPaths: true` (RR-64), over this registry's faces, including faces `ensure` loads later. */
+  /** The outline engine for `text: "paths"` (RR-64), over this registry's faces, including faces `ensure` loads later. */
   readonly outlines: TextOutlines;
   /** The pinned manifest of the bundled font packages. */
   readonly manifest: { readonly version: number; readonly packages: readonly object[] };

package/dist/hb-shape.js

@@ -70,8 +70,13 @@ function shaperOver(instance, state) {
     return font;
   };
   return {
-    /** Shape `text` with the face (`key` names it, `data` is its bytes); `features` is an object of OpenType feature booleans. */
-    shape(key, data, text, { direction = "ltr", language, features } = {}) {
+    /**
+     * Shape `text` with the face (`key` names it, `data` is its bytes); `features` is an object of OpenType feature booleans.
+     * `clusterLevel` is HarfBuzz's cluster level (0 by default: a mark joins its base's cluster and a reordered syllable is one
+     * cluster; 2 keeps each character with the glyph it became). It changes only which glyph carries which characters, never the
+     * glyphs or their positions.
+     */
+    shape(key, data, text, { direction = "ltr", language, features, clusterLevel } = {}) {
       const font = fontFor(key, data);
       const buffer = hb.hb_buffer_create();
       const units = text.length, textPointer = hb.malloc(units * 2 + 2);
@@ -81,6 +86,7 @@ function shaperOver(instance, state) {
       try {
         hb.hb_buffer_add_utf16(buffer, textPointer, units, 0, units);
         hb.hb_buffer_set_direction(buffer, HB_DIRECTION[direction] ?? HB_DIRECTION.ltr);
+        if (clusterLevel) hb.hb_buffer_set_cluster_level(buffer, clusterLevel);
         if (language) { const tag = string(language); allocated.push(tag.pointer); hb.hb_buffer_set_language(buffer, hb.hb_language_from_string(tag.pointer, tag.length)); }
         hb.hb_buffer_guess_segment_properties(buffer);
         const entries = Object.entries(features ?? {});
@@ -102,12 +108,16 @@ function shaperOver(instance, state) {
           const info = infos + index * INFO_SIZE, position = positions + index * POSITION_SIZE;
           glyphs.push({ gid: data32.getUint32(info, true), cluster: data32.getUint32(info + 8, true), advance: data32.getInt32(position, true), xOffset: data32.getInt32(position + 8, true), yOffset: data32.getInt32(position + 12, true) });
         }
-        // The characters of each cluster go to its first glyph in output order; later glyphs of the cluster carry none.
+        // The characters of each cluster go to one of its glyphs: the first in logical order (output order, reversed right to left)
+        // that advances the pen, else the first; its other glyphs carry none (a mark or dot the font split off a letter).
         const starts = [...new Set(glyphs.map((glyph) => glyph.cluster))].sort((a, b) => a - b);
-        const seen = new Set();
+        const carriers = new Map();
+        for (const glyph of direction === "rtl" ? [...glyphs].reverse() : glyphs) {
+          const carrier = carriers.get(glyph.cluster);
+          if (!carrier || (carrier.advance === 0 && glyph.advance !== 0)) carriers.set(glyph.cluster, glyph);
+        }
         for (const glyph of glyphs) {
-          if (seen.has(glyph.cluster)) { glyph.codePoints = []; continue; }
-          seen.add(glyph.cluster);
+          if (carriers.get(glyph.cluster) !== glyph) { glyph.codePoints = []; continue; }
           const end = starts[starts.indexOf(glyph.cluster) + 1] ?? units;
           glyph.codePoints = [...text.slice(glyph.cluster, end)].map((character) => character.codePointAt(0));
         }