@arraypress/covers 0.0.0-stage → 1.1.0

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 = [];

package/src/png.js

@@ -0,0 +1,126 @@
+/**
+ * A minimal PNG encoder (8-bit greyscale, RGB or RGBA; no filtering), so
+ * layers that are pixels by nature (dithers, print textures) can embed
+ * themselves in an SVG without sharp.
+ *
+ * @module png
+ */
+
+import { deflateSync, deflate } from './platform/index.js';
+import { concat, toBase64 } from './platform/bytes.js';
+
+/** CRC-32 table (PNG's polynomial). */
+const CRC = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+/** @param {Uint8Array} bytes @returns {number} */
+function crc32(bytes) {
+  let c = 0xffffffff;
+  for (const b of bytes) c = CRC[(c ^ b) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** @param {string} type @param {Uint8Array} data @returns {Uint8Array} */
+function chunk(type, data) {
+  const out = new Uint8Array(12 + data.length);
+  const v = new DataView(out.buffer);
+  v.setUint32(0, data.length);
+  for (let i = 0; i < 4; i++) out[4 + i] = type.charCodeAt(i);
+  out.set(data, 8);
+  v.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
+  return out;
+}
+
+/**
+ * The filtered scanlines and header of a PNG.
+ *
+ * @param {Uint8Array} pixels @param {number} width @param {number} height @param {1 | 3 | 4} channels
+ * @returns {{ raw: Uint8Array, ihdr: Uint8Array }}
+ */
+function scanlines(pixels, width, height, channels) {
+  const stride = width * channels;
+  const raw = new Uint8Array((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 0;
+    raw.set(pixels.subarray(y * stride, y * stride + stride), y * (stride + 1) + 1);
+  }
+  const ihdr = new Uint8Array(13);
+  const v = new DataView(ihdr.buffer);
+  v.setUint32(0, width);
+  v.setUint32(4, height);
+  ihdr[8] = 8;
+  ihdr[9] = /** @type {Record<number, number>} */ ({ 1: 0, 3: 2, 4: 6 })[channels];
+  return { raw, ihdr };
+}
+
+const SIGNATURE = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * zlib "stored" blocks: valid, uncompressed. The synchronous fallback where
+ * the platform has no synchronous deflate (browsers, Workers).
+ *
+ * @param {Uint8Array} data
+ * @returns {Uint8Array}
+ */
+function stored(data) {
+  const parts = [new Uint8Array([0x78, 0x01])];
+  for (let i = 0; i < data.length || i === 0; i += 65535) {
+    const block = data.subarray(i, i + 65535);
+    const last = i + 65535 >= data.length ? 1 : 0;
+    parts.push(new Uint8Array([last, block.length & 255, block.length >> 8, ~block.length & 255, (~block.length >> 8) & 255]), block);
+    if (last) break;
+  }
+  let a = 1;
+  let b = 0;
+  for (const x of data) { a = (a + x) % 65521; b = (b + a) % 65521; }
+  const adler = new Uint8Array(4);
+  new DataView(adler.buffer).setUint32(0, ((b << 16) | a) >>> 0);
+  parts.push(adler);
+  return concat(parts);
+}
+
+/**
+ * Encode pixels as a PNG (synchronously: zlib in Node, stored blocks where
+ * there's no synchronous deflate; {@link encodePngAsync} compresses
+ * everywhere).
+ *
+ * @param {Uint8Array} pixels - Row-major samples.
+ * @param {number} width
+ * @param {number} height
+ * @param {1 | 3 | 4} [channels=4] - Grey, RGB or RGBA.
+ * @returns {Uint8Array} PNG bytes.
+ *
+ * @example
+ * encodePng(new Uint8Array([0, 255]), 2, 1, 1); // a black and a white pixel
+ */
+export function encodePng(pixels, width, height, channels = 4) {
+  const { raw, ihdr } = scanlines(pixels, width, height, channels);
+  return concat([SIGNATURE, chunk('IHDR', ihdr), chunk('IDAT', deflateSync(raw) ?? stored(raw)), chunk('IEND', new Uint8Array(0))]);
+}
+
+/**
+ * Encode pixels as a PNG, compressed on every platform (Node's zlib, else
+ * `CompressionStream`).
+ *
+ * @param {Uint8Array} pixels @param {number} width @param {number} height @param {1 | 3 | 4} [channels=4]
+ * @returns {Promise<Uint8Array>}
+ */
+export async function encodePngAsync(pixels, width, height, channels = 4) {
+  const { raw, ihdr } = scanlines(pixels, width, height, channels);
+  return concat([SIGNATURE, chunk('IHDR', ihdr), chunk('IDAT', await deflate(raw)), chunk('IEND', new Uint8Array(0))]);
+}
+
+/**
+ * A PNG as a data URI.
+ *
+ * @param {Uint8Array} png
+ * @returns {string}
+ */
+export const pngUri = (png) => `data:image/png;base64,${toBase64(png)}`;