@arraypress/covers 1.0.0 → 1.1.0

package/src/platform/bytes.js

@@ -0,0 +1,103 @@
+/**
+ * Byte helpers that work the same in Node, browsers and Workers (no
+ * `Buffer`). Where Node's `Buffer` is present it's used for speed; the
+ * output is identical either way.
+ *
+ * @module bytes
+ */
+
+const B = /** @type {any} */ (globalThis).Buffer;
+
+/**
+ * Bytes as a `Uint8Array` view.
+ *
+ * @param {Uint8Array | ArrayBuffer | ArrayBufferView} v
+ * @returns {Uint8Array}
+ */
+export function u8(v) {
+  if (v instanceof Uint8Array) return v;
+  if (v instanceof ArrayBuffer) return new Uint8Array(v);
+  if (ArrayBuffer.isView(v)) return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+  throw new TypeError('Expected bytes (Uint8Array or ArrayBuffer)');
+}
+
+/** @param {unknown} v @returns {v is Uint8Array | ArrayBuffer} */
+export const isBytes = (v) => v instanceof Uint8Array || v instanceof ArrayBuffer || ArrayBuffer.isView(v);
+
+/**
+ * Base64-encode bytes.
+ *
+ * @param {Uint8Array | ArrayBuffer} bytes
+ * @returns {string}
+ */
+export function toBase64(bytes) {
+  const b = u8(bytes);
+  if (B) return B.from(b.buffer, b.byteOffset, b.byteLength).toString('base64');
+  let out = '';
+  for (let i = 0; i < b.length; i += 0x8000) out += String.fromCharCode.apply(null, /** @type {any} */ (b.subarray(i, i + 0x8000)));
+  return btoa(out);
+}
+
+/**
+ * Decode base64.
+ *
+ * @param {string} s
+ * @returns {Uint8Array}
+ */
+export function fromBase64(s) {
+  if (B) return new Uint8Array(B.from(s, 'base64'));
+  const bin = atob(s.replace(/\s+/g, ''));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/** @param {Uint8Array} b @returns {string} Each byte as one char. */
+export function latin1(b) {
+  let s = '';
+  for (let i = 0; i < b.length; i++) s += String.fromCharCode(b[i]);
+  return s;
+}
+
+/** @param {Uint8Array | ArrayBuffer} b @returns {string} */
+export const utf8 = (b) => new TextDecoder().decode(u8(b));
+
+/** @param {string} s @returns {Uint8Array} */
+export const encodeUtf8 = (s) => new TextEncoder().encode(s);
+
+/**
+ * Join byte arrays.
+ *
+ * @param {Uint8Array[]} parts
+ * @returns {Uint8Array}
+ */
+export function concat(parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) { out.set(p, o); o += p.length; }
+  return out;
+}
+
+/**
+ * Decode a `data:` URI.
+ *
+ * @param {string} uri
+ * @returns {Uint8Array | undefined} Its bytes, or undefined when it isn't one.
+ */
+export function fromDataUri(uri) {
+  const m = /^data:([^,]*?),(.*)$/s.exec(uri);
+  if (!m) return undefined;
+  return /;base64$/i.test(m[1]) ? fromBase64(m[2]) : encodeUtf8(decodeURIComponent(m[2]));
+}
+
+/**
+ * Hex digest with Web Crypto (Node 20+, browsers, Workers).
+ *
+ * @param {'SHA-1' | 'SHA-256'} algo
+ * @param {Uint8Array | string} data
+ * @returns {Promise<string>}
+ */
+export async function hexDigest(algo, data) {
+  const buf = await globalThis.crypto.subtle.digest(algo, typeof data === 'string' ? encodeUtf8(data) : u8(data));
+  return Array.from(new Uint8Array(buf), (x) => x.toString(16).padStart(2, '0')).join('');
+}

package/src/platform/compress.d.ts

@@ -0,0 +1,12 @@
+// zlib on every platform.
+
+/** zlib-deflate synchronously (Node), else undefined. */
+export function deflateSync(data: Uint8Array): Uint8Array | undefined;
+/** zlib-deflate (Node's zlib, else CompressionStream). */
+export function deflate(data: Uint8Array): Promise<Uint8Array>;
+/** zlib-inflate. */
+export function inflate(data: Uint8Array): Promise<Uint8Array>;
+/** Brotli-decompress synchronously (Node), else undefined. */
+export function unbrotliSync(data: Uint8Array): Uint8Array | undefined;
+/** Brotli-decompress (Node's zlib, else DecompressionStream('brotli') where there is one), else undefined. */
+export function unbrotli(data: Uint8Array): Promise<Uint8Array | undefined>;

package/src/platform/compress.js

@@ -0,0 +1,81 @@
+/**
+ * zlib deflate and inflate: Node's zlib, else `CompressionStream` and
+ * `DecompressionStream` (browsers, Workers). For PNG textures and WOFF.
+ *
+ * @module platform/compress
+ */
+
+import { node } from './node.js';
+
+/**
+ * zlib-deflate synchronously, when the platform can (Node).
+ *
+ * @param {Uint8Array} data
+ * @returns {Uint8Array | undefined}
+ */
+export function deflateSync(data) {
+  const z = node('zlib');
+  return z ? z.deflateSync(data, { level: 9 }) : undefined;
+}
+
+/**
+ * zlib-deflate: Node's zlib, else `CompressionStream` (browsers, Workers).
+ * The two may differ in bytes but both are valid zlib streams.
+ *
+ * @param {Uint8Array} data
+ * @returns {Promise<Uint8Array>}
+ */
+export async function deflate(data) {
+  return deflateSync(data) ?? stream(data, new CompressionStream('deflate'));
+}
+
+/**
+ * zlib-inflate (WOFF tables).
+ *
+ * @param {Uint8Array} data
+ * @returns {Promise<Uint8Array>}
+ */
+export async function inflate(data) {
+  const z = node('zlib');
+  return z ? z.inflateSync(data) : stream(data, new DecompressionStream('deflate'));
+}
+
+/**
+ * @param {Uint8Array} data
+ * @param {TransformStream} ts
+ * @returns {Promise<Uint8Array>}
+ */
+async function stream(data, ts) {
+  const out = new Response(new Blob([/** @type {any} */ (data)]).stream().pipeThrough(ts));
+  return new Uint8Array(await out.arrayBuffer());
+}
+
+/**
+ * Brotli-decompress synchronously, when the platform can (Node's zlib).
+ *
+ * @param {Uint8Array} data
+ * @returns {Uint8Array | undefined}
+ */
+export function unbrotliSync(data) {
+  const z = node('zlib');
+  if (!z?.brotliDecompressSync) return undefined;
+  const out = z.brotliDecompressSync(data);
+  return new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
+}
+
+/**
+ * Brotli-decompress (WOFF2): Node's zlib, else `DecompressionStream('brotli')`
+ * where the runtime has it. Undefined where neither can.
+ *
+ * @param {Uint8Array} data
+ * @returns {Promise<Uint8Array | undefined>}
+ */
+export async function unbrotli(data) {
+  const sync = unbrotliSync(data);
+  if (sync) return sync;
+  try {
+    return await stream(data, new DecompressionStream(/** @type {any} */ ('brotli')));
+  } catch {
+    return undefined;
+  }
+}

package/src/platform/harfbuzz.d.ts

@@ -0,0 +1,9 @@
+// HarfBuzz, loaded once.
+
+/** The harfbuzzjs module (its own types need Emscripten's; covers uses a handful of its classes). */
+export type HarfBuzzModule = object;
+
+/** harfbuzzjs, with its wasm from `configure({ harfbuzz })` when given. */
+export function harfbuzz(): Promise<HarfBuzzModule>;
+/** harfbuzzjs where it runs (and isn't switched off), else undefined: text then uses the JavaScript outliner. */
+export function shaperModule(): Promise<HarfBuzzModule | undefined>;

package/src/platform/harfbuzz.js

@@ -0,0 +1,80 @@
+/**
+ * HarfBuzz, loaded once and lazily, with its WebAssembly from wherever
+ * `configure({ harfbuzz })` says. `#harfbuzz` is harfbuzzjs, except under
+ * the `workerd` / `worker` conditions, where it's a stub that fails, and
+ * text falls back to the JavaScript outliner.
+ *
+ * @module platform/harfbuzz
+ */
+
+import { isBytes } from './bytes.js';
+import { settings } from './settings.js';
+import { loadBytes, asBytes } from './load.js';
+
+/** @type {Promise<any> | undefined} */
+let hbPromise;
+
+/**
+ * Load harfbuzzjs. With `configure({ harfbuzz })` its WebAssembly comes from
+ * there (a URL, bytes, a compiled Module or a Response) instead of the file
+ * next to harfbuzzjs, which a bundler may not have copied.
+ *
+ * harfbuzzjs creates small wasm trampolines at runtime (Emscripten's
+ * `addFunction`), which Cloudflare Workers forbid; there text falls back to
+ * the built-in JavaScript outliner (`fonts/sfnt.js`).
+ *
+ * @returns {Promise<any>} The harfbuzzjs module.
+ */
+export function harfbuzz() {
+  hbPromise ??= (async () => {
+    const src = await settings.harfbuzz;
+    if (src == null) return import('#harfbuzz');
+    const W = /** @type {any} */ (WebAssembly);
+    const { instantiate, instantiateStreaming } = W;
+    /** @param {any} imports */
+    const ours = async (imports) => {
+      if (src instanceof WebAssembly.Module) return { module: src, instance: await instantiate(src, imports) };
+      const bytes = isBytes(src) || typeof src?.arrayBuffer === 'function' ? await asBytes(src) : await loadBytes(src, 'file');
+      return instantiate(bytes, imports);
+    };
+    let used = false;
+    // harfbuzzjs instantiates once, on import: hand it our module then.
+    W.instantiateStreaming = (/** @type {any} */ response, /** @type {any} */ imports) => {
+      if (used) return instantiateStreaming(response, imports);
+      used = true;
+      Promise.resolve(response).catch(() => {});
+      return ours(imports);
+    };
+    W.instantiate = (/** @type {any} */ source, /** @type {any} */ imports) => {
+      if (used || !(source instanceof Uint8Array || source instanceof ArrayBuffer)) return instantiate(source, imports);
+      used = true;
+      return ours(imports);
+    };
+    try {
+      return await import('#harfbuzz');
+    } finally {
+      W.instantiate = instantiate;
+      W.instantiateStreaming = instantiateStreaming;
+    }
+  })();
+  return hbPromise;
+}
+
+/**
+ * Whether outlines come from HarfBuzz: `shaper: 'harfbuzz'`, or `'auto'`
+ * where HarfBuzz loads (everywhere but Workers).
+ *
+ * @returns {Promise<any>} harfbuzzjs, or undefined for the JS outliner.
+ */
+export async function shaperModule() {
+  if (settings.shaper === 'js') return undefined;
+  try {
+    return await harfbuzz();
+  } catch (err) {
+    if (settings.shaper === 'harfbuzz') throw err;
+    hbPromise = Promise.reject(err);
+    hbPromise.catch(() => {});
+    return undefined;
+  }
+}
+

package/src/platform/index.d.ts

@@ -0,0 +1,8 @@
+// The platform adapter.
+export { node, installNode, isNode, FROM_DISK, readTextSync, packageFileSync } from './node.js';
+export type { NodeModules } from './node.js';
+export { settings, configure, registry } from './settings.js';
+export type { Settings } from './settings.js';
+export { loadBytes } from './load.js';
+export { deflateSync, deflate, inflate, unbrotli, unbrotliSync } from './compress.js';
+export { harfbuzz, shaperModule } from './harfbuzz.js';

package/src/platform/index.js

@@ -0,0 +1,13 @@
+/**
+ * The platform: everything that differs between Node, a browser and a
+ * Cloudflare Worker, behind one small adapter. Nothing here imports a
+ * `node:` module.
+ *
+ * @module platform
+ */
+
+export { node, installNode, isNode, FROM_DISK, readTextSync, packageFileSync } from './node.js';
+export { settings, configure, registry } from './settings.js';
+export { loadBytes } from './load.js';
+export { deflateSync, deflate, inflate, unbrotli, unbrotliSync } from './compress.js';
+export { harfbuzz, shaperModule } from './harfbuzz.js';

package/src/platform/load.d.ts

@@ -0,0 +1,6 @@
+// Loading bytes from anything.
+
+/** Load an image, font, audio file or icon set. */
+export function loadBytes(src: unknown, kind?: 'image' | 'font' | 'audio' | 'icons' | 'file'): Promise<Uint8Array>;
+/** Bytes from what a loader returned (bytes, a Blob or a Response). */
+export function asBytes(v: unknown): Promise<Uint8Array>;

package/src/platform/load.js

@@ -0,0 +1,72 @@
+/**
+ * Loading bytes from anything: bytes, Blobs and Responses, `data:` URIs,
+ * paths (Node), URLs (fetched where allowed), or a `configure({ load })`
+ * hook.
+ *
+ * @module platform/load
+ */
+
+import { isBytes, u8, fromDataUri } from './bytes.js';
+import { node, isNode } from './node.js';
+import { settings } from './settings.js';
+
+/** @returns {boolean} */
+const networkAllowed = () => settings.network ?? !isNode();
+
+/** @returns {typeof fetch} */
+function fetcher() {
+  const f = settings.fetch ?? globalThis.fetch;
+  if (!f) throw new Error('No fetch available to load a URL: pass bytes, or configure({ fetch })');
+  return f;
+}
+
+/**
+ * Whatever a loader handed back, as bytes.
+ *
+ * @param {any} v
+ * @returns {Promise<Uint8Array>}
+ */
+async function asBytes(v) {
+  if (isBytes(v)) return u8(v);
+  if (typeof v?.arrayBuffer === 'function') {
+    if (typeof v.ok === 'boolean' && !v.ok) throw new Error(`Couldn't load ${v.url}: HTTP ${v.status}`);
+    return new Uint8Array(await v.arrayBuffer());
+  }
+  throw new TypeError('A loader must return bytes, an ArrayBuffer, a Blob or a Response');
+}
+
+/**
+ * Load bytes: an image, font, audio file or icon set.
+ *
+ * @param {any} src - Bytes, a Blob, a Response, a `data:` URI, a URL, or a path (Node).
+ * @param {'image' | 'font' | 'audio' | 'icons' | 'file'} [kind='file'] - What it is (for errors and the loader).
+ * @returns {Promise<Uint8Array>} The bytes (a Node Buffer when read from disk).
+ */
+export async function loadBytes(src, kind = 'file') {
+  if (isBytes(src)) return u8(src);
+  if (src && typeof src === 'object' && !(src instanceof URL)) return asBytes(src);
+  if (settings.load) {
+    const r = await settings.load(src, { kind });
+    if (r != null) return asBytes(r);
+  }
+  const s = String(src instanceof URL ? src.href : src);
+  const data = fromDataUri(s);
+  if (data) return data;
+  if (/^https?:/i.test(s)) {
+    if (!networkAllowed()) {
+      throw new TypeError(kind === 'image'
+        ? 'Image src must be a local file or bytes: covers never fetch from the network (allow it with configure({ network: true }))'
+        : `${kind} "${s}" is a URL, and covers doesn't fetch from the network in Node unless asked: configure({ network: true }) or pass bytes`);
+    }
+    return asBytes(await fetcher()(s));
+  }
+  const fsp = node('fs/promises');
+  const isFileUrl = s.startsWith('file:');
+  if (fsp && (isFileUrl || !/^[a-z][\w+.-]*:/i.test(s))) return fsp.readFile(isFileUrl ? new URL(s) : s);
+  // A browser: a relative or absolute URL, against the page.
+  const base = /** @type {any} */ (globalThis).document?.baseURI ?? /** @type {any} */ (globalThis).location?.href;
+  if (base || /^[a-z][\w+.-]*:/i.test(s)) return asBytes(await fetcher()(new URL(s, base).href));
+  throw new Error(`Can't load ${kind} "${s}" here: pass bytes, or give covers a loader with configure({ load })`);
+}
+
+export { asBytes };

package/src/platform/no-harfbuzz.d.ts

@@ -0,0 +1,2 @@
+// What #harfbuzz resolves to in Workers: importing it fails.
+export {};

package/src/platform/no-harfbuzz.js

@@ -0,0 +1,11 @@
+/**
+ * What `#harfbuzz` resolves to in Cloudflare Workers (the `workerd` and
+ * `worker` export conditions): harfbuzzjs needs to compile WebAssembly
+ * trampolines at runtime, which Workers forbid, and its loader imports
+ * `node:module`. Importing this fails, so text falls back to the built-in
+ * JavaScript outliner (`sfnt.js`).
+ *
+ * @module no-harfbuzz
+ */
+
+throw new Error('HarfBuzz is not available in Cloudflare Workers; covers draws text with its JavaScript outliner there');

package/src/platform/node.d.ts

@@ -0,0 +1,26 @@
+// Node's built-ins, without importing node:.
+
+/** Node modules covers uses. */
+export interface NodeModules {
+  fs?: typeof import('node:fs');
+  fsp?: typeof import('node:fs/promises');
+  zlib?: typeof import('node:zlib');
+  path?: typeof import('node:path');
+  module?: typeof import('node:module');
+  url?: typeof import('node:url');
+}
+
+/** The global `process`, where there is one. */
+export const proc: NodeJS.Process | undefined;
+/** This module was loaded from disk. */
+export const FROM_DISK: boolean;
+/** A Node built-in, when there is one. */
+export function node<K extends 'fs' | 'fs/promises' | 'zlib' | 'path' | 'module' | 'url'>(name: K): K extends 'fs' ? typeof import('node:fs') : K extends 'fs/promises' ? typeof import('node:fs/promises') : K extends 'zlib' ? typeof import('node:zlib') : K extends 'path' ? typeof import('node:path') : K extends 'module' ? typeof import('node:module') : typeof import('node:url') | undefined;
+/** Install Node's modules (what `@arraypress/covers/node` does). */
+export function installNode(mods: NodeModules): void;
+/** Whether this is Node with a file system. */
+export function isNode(): boolean;
+/** Read a text file synchronously (Node). */
+export function readTextSync(path: string | URL): string;
+/** A file shipped with the package, from disk (Node), or undefined. */
+export function packageFileSync(rel: string): Uint8Array | undefined;

package/src/platform/node.js

@@ -0,0 +1,86 @@
+/**
+ * Node's built-ins, found without importing `node:` (so bundles for
+ * browsers and Workers never see them): `process.getBuiltinModule` on Node
+ * 20.16+, or the modules `@arraypress/covers/node` installs.
+ *
+ * @module platform/node
+ */
+
+/**
+ * @typedef {object} NodeModules
+ * @property {any} [fs] - `node:fs`.
+ * @property {any} [fsp] - `node:fs/promises`.
+ * @property {any} [zlib] - `node:zlib`.
+ * @property {any} [path] - `node:path`.
+ * @property {any} [module] - `node:module`.
+ * @property {any} [url] - `node:url`.
+ */
+
+/** @type {NodeModules} */
+let nodeModules = {};
+
+/** The global `process`, where there is one. */
+export const proc = /** @type {any} */ (globalThis).process;
+/** Built-in lookup without a static import (Node 20.16+, Deno, Bun). */
+const builtin = typeof proc?.getBuiltinModule === 'function' && proc.versions?.node ? proc.getBuiltinModule.bind(proc) : undefined;
+/** This module was loaded from disk (Node, Deno, Bun), not a bundle or a page. */
+export const FROM_DISK = String(import.meta.url).startsWith('file:');
+
+/**
+ * A Node built-in, when there is one.
+ *
+ * @param {'fs' | 'fs/promises' | 'zlib' | 'path' | 'module' | 'url'} name
+ * @returns {any}
+ */
+export function node(name) {
+  const key = name === 'fs/promises' ? 'fsp' : name;
+  const have = /** @type {any} */ (nodeModules)[key];
+  if (have) return have;
+  if (!builtin) return undefined;
+  try {
+    return (/** @type {any} */ (nodeModules)[key] = builtin(`node:${name}`));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Install Node's modules (what `@arraypress/covers/node` does).
+ *
+ * @param {NodeModules} mods
+ * @returns {void}
+ */
+export function installNode(mods) {
+  nodeModules = { ...nodeModules, ...mods };
+}
+
+/** Whether this looks like Node with a file system we can read. */
+export const isNode = () => Boolean(node('fs')) && Boolean(proc?.versions?.node);
+
+/**
+ * Read a text file synchronously (Node only; `loadRecipe`).
+ *
+ * @param {string | URL} path
+ * @returns {string}
+ */
+export function readTextSync(path) {
+  const fs = node('fs');
+  if (!fs) throw new Error('Reading a file synchronously needs Node. In a browser or Worker, fetch the JSON and pass it to defineRecipe().');
+  return fs.readFileSync(path, 'utf8');
+}
+
+/**
+ * Read a file that ships with this package (Node, from disk), or undefined.
+ *
+ * @param {string} rel - Relative to the package root (`'fonts/inter-latin-400.woff'`).
+ * @returns {Uint8Array | undefined}
+ */
+export function packageFileSync(rel) {
+  const fs = node('fs');
+  if (!fs || !FROM_DISK) return undefined;
+  try {
+    return fs.readFileSync(new URL(`../../${rel}`, import.meta.url));
+  } catch {
+    return undefined;
+  }
+}

package/src/platform/settings.d.ts

@@ -0,0 +1,28 @@
+// Global settings.
+import type { FontSource } from '../index.js';
+
+/** Global settings: how files load, where HarfBuzz comes from, how text is drawn. */
+export interface Settings {
+  /** Load a file (an image, font, audio or icon set): return bytes, an ArrayBuffer, a Blob or a Response, or undefined to fall through. */
+  load?: (src: unknown, info: { kind: string }) => unknown;
+  /** Allow fetching http(s) URLs (default: yes in browsers and Workers, no in Node). */
+  network?: boolean;
+  fetch?: typeof fetch;
+  /** HarfBuzz's wasm: a URL, bytes, a compiled `WebAssembly.Module`, a `Response`, or a promise of one. */
+  harfbuzz?: unknown;
+  /** `'auto'` (HarfBuzz where it runs, else the JavaScript outliner), `'harfbuzz'`, `'js'`. */
+  shaper?: 'auto' | 'harfbuzz' | 'js';
+  text?: 'outline' | 'live';
+  /** Where icon sets load from outside Node: a URL template with `{prefix}`, or a function. */
+  icons?: string | ((prefix: string) => string);
+  /** Fonts for every cover. */
+  fonts?: FontSource[];
+}
+
+
+/** The current settings. */
+export const settings: Settings;
+/** Fonts registered for every cover. */
+export const registry: FontSource[];
+/** Configure loading, HarfBuzz and text rendering (merges with what's set). */
+export function configure(options: Settings): void;

package/src/platform/settings.js

@@ -0,0 +1,51 @@
+/**
+ * Global settings: how files load, where HarfBuzz comes from, how text is
+ * drawn. Set with {@link configure}.
+ *
+ * @module platform/settings
+ */
+
+/**
+ * @typedef {object} Settings
+ * @property {((src: any, info: { kind: string }) => any) | undefined} load - A loader hook; return bytes (or a Response, Blob, ArrayBuffer), or undefined to fall through.
+ * @property {boolean | undefined} network - Allow fetching http(s) URLs.
+ * @property {typeof fetch | undefined} fetch - The fetch to use.
+ * @property {any} harfbuzz - HarfBuzz's wasm: a URL, bytes, a WebAssembly.Module, a Response, or a promise of one.
+ * @property {'auto' | 'harfbuzz' | 'js'} shaper - How text is shaped and outlined.
+ * @property {'outline' | 'live'} text - The default text rendering.
+ * @property {((prefix: string) => string) | string | undefined} icons - Where icon sets load from outside Node: a URL template with `{prefix}`, or a function.
+ */
+
+/** @type {Settings} */
+export const settings = {
+  load: undefined,
+  network: undefined,
+  fetch: undefined,
+  harfbuzz: undefined,
+  shaper: 'auto',
+  text: 'outline',
+  icons: undefined,
+};
+
+/**
+ * Configure how covers loads files, fetches, shapes text and finds
+ * HarfBuzz. Settings are global and merge with what's set already.
+ *
+ * @param {Partial<Settings> & { fonts?: import('../index.js').FontSource[] }} options
+ * @returns {void}
+ *
+ * @example
+ * // A browser app serving the wasm itself:
+ * configure({ harfbuzz: '/wasm/harfbuzz.wasm' });
+ * // A Worker: no wasm compilation at runtime, so text uses the JS outliner.
+ * configure({ shaper: 'js' });
+ */
+export function configure(options = {}) {
+  for (const k of /** @type {(keyof Settings)[]} */ (Object.keys(settings))) {
+    if (Object.hasOwn(options, k)) /** @type {any} */ (settings)[k] = /** @type {any} */ (options)[k];
+  }
+  if (options.fonts) for (const f of options.fonts) registry.push(f);
+}
+
+/** Fonts registered globally (`configure({ fonts })`, `registerFont()`). @type {import('../index.js').FontSource[]} */
+export const registry = [];