wasm-html-to-image 1.0.22 → 1.0.23

package/dist/cli-options.d.ts

@@ -27,6 +27,32 @@ export interface CliFlags {
     font?: string[];
     /** `--js`: run the page's scripts (jsdom) before rendering. */
     js?: boolean;
+    /** `--markdown`: treat the input as Markdown (implied by a `.md` / `.markdown` file). */
+    markdown?: boolean;
+    /** `--markdown-theme <light|dark>`; absent means light. */
+    markdownTheme?: string;
+    /** `--template <name|file>`: a bundled template, or a .json / .css file (see `loadTemplate`). */
+    template?: string;
+    /** `--page-size <A4|A5|...|"210mm 297mm">`. */
+    pageSize?: string;
+    /** `--accent <colour>`: links, rules and the cover accent. */
+    accent?: string;
+    /** `--body-font <family>`: the body font of the page. */
+    bodyFont?: string;
+    /** `--stamp <text>`: printed in the header of every page. */
+    stamp?: string;
+    /** `--cover` / `--no-cover`. */
+    cover?: boolean;
+    /** `--no-toc` sets this to false: a PDF from Markdown gets a table of contents by default. */
+    toc?: boolean;
+    /** `--toc-depth <n>`: deepest heading level in the table of contents (default 3). */
+    tocDepth?: number;
+    /** `--no-outline` sets this to false: the PDF's bookmarks (outline) are on by default. */
+    outline?: boolean;
+    /** `--no-math` sets this to false: `$...$` / `$$...$$` are typeset when katex is installed. */
+    math?: boolean;
+    /** `--markdown-css <path>`: extra stylesheet appended after the built-in one. */
+    markdownCss?: string;
     /** `--js-wait <ms|selector>`: a number is the settle time after load, anything else a CSS selector to wait for. */
     jsWait?: string;
 }
@@ -60,6 +86,24 @@ export interface AnimationResolution {
 export declare function resolveAnimation(flags: CliFlags): AnimationResolution;
 /** Output format implied by the output file's extension, if recognised. */
 export declare function inferFormat(output: string | undefined): OutputFormat | undefined;
+/** Whether `input` names an existing file (a Markdown text or HTML string is not a path). */
+export declare function isFile(input: string): Promise<boolean>;
+/** Markdown text passed with `--markdown` instead of a file path. */
+export declare function isInlineMarkdown(input: string, flags: {
+    markdown?: boolean;
+}): Promise<boolean>;
+/** A `.md` / `.markdown` file path is Markdown input without `--markdown`. */
+export declare function isMarkdownPath(input: string): boolean;
+/** Convert Markdown text to a styled HTML document (`marked` is an optional dependency). */
+export declare function convertMarkdown(markdown: string, flags: CliFlags): Promise<{
+    html: string;
+    renderOptions: import("./markdown.js").MarkdownRenderOptions;
+}>;
+/**
+ * `--template`: a bundled name, or a file. A `.json` file is a {@link MarkdownTemplate} (`type`, `page`,
+ * `defaults`, `css`); a `.css` file is extra CSS laid over the default template.
+ */
+export declare function loadTemplate(spec: string): Promise<string | import("./markdown-template.js").MarkdownTemplate>;
 /** Inline markup passed on the command line (as opposed to a path or URL). */
 export declare function isInlineHtml(input: string): boolean;
 /** Read all of standard input as UTF-8 text. */

package/dist/cli-options.js

@@ -65,6 +65,87 @@ export function inferFormat(output) {
     const ext = path.extname(output).slice(1).toLowerCase();
     return EXTENSION_FORMATS[ext];
 }
+/** Whether `input` names an existing file (a Markdown text or HTML string is not a path). */
+export async function isFile(input) {
+    try {
+        return (await fs.stat(input)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Markdown text passed with `--markdown` instead of a file path. */
+export async function isInlineMarkdown(input, flags) {
+    return !!flags.markdown && input !== "-" && !isUrlInput(input) && !(await isFile(input));
+}
+/** A `.md` / `.markdown` file path is Markdown input without `--markdown`. */
+export function isMarkdownPath(input) {
+    return /\.(md|markdown)$/i.test(input) && !isUrlInput(input);
+}
+/** Convert Markdown text to a styled HTML document (`marked` is an optional dependency). */
+export async function convertMarkdown(markdown, flags) {
+    let mod;
+    try {
+        mod = await import("./markdown.js");
+    }
+    catch (e) {
+        if (e.code !== "ERR_MODULE_NOT_FOUND")
+            throw e;
+        throw new Error("Markdown input needs the optional dependency `marked`. Install it with `npm i marked`.");
+    }
+    const theme = flags.markdownTheme?.toLowerCase();
+    if (theme !== undefined && theme !== "light" && theme !== "dark") {
+        throw new Error(`unsupported markdown theme "${flags.markdownTheme}". Choose from: light, dark`);
+    }
+    const css = flags.markdownCss ? await fs.readFile(flags.markdownCss, "utf-8") : undefined;
+    const settings = {
+        ...(flags.pageSize !== undefined ? { page_size: flags.pageSize } : {}),
+        ...(flags.accent !== undefined ? { accent: flags.accent } : {}),
+        ...(flags.bodyFont !== undefined ? { font: flags.bodyFont } : {}),
+        ...(flags.stamp !== undefined ? { stamp: flags.stamp } : {}),
+        ...(flags.cover !== undefined ? { cover: flags.cover } : {}),
+    };
+    const template = flags.template !== undefined ? await loadTemplate(flags.template) : undefined;
+    return mod.markdownToDocument(markdown, {
+        theme,
+        css,
+        ...(template !== undefined ? { template } : {}),
+        ...(Object.keys(settings).length ? { settings } : {}),
+        paged: flags.format === "pdf",
+        // Default: a table of contents in a PDF (markdownToHtml's own default), none in an image.
+        ...(flags.toc === false ? { toc: false } : flags.tocDepth !== undefined ? { toc: { depth: flags.tocDepth } } : {}),
+        ...(flags.math === false ? {} : await loadMath()),
+    });
+}
+/**
+ * `--template`: a bundled name, or a file. A `.json` file is a {@link MarkdownTemplate} (`type`, `page`,
+ * `defaults`, `css`); a `.css` file is extra CSS laid over the default template.
+ */
+export async function loadTemplate(spec) {
+    if (!/\.(json|css)$/i.test(spec))
+        return spec; // a name: resolveTemplate reports an unknown one
+    const text = await fs.readFile(spec, "utf-8");
+    if (/\.css$/i.test(spec))
+        return { description: spec, css: text };
+    try {
+        return JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`template ${spec} is not valid JSON: ${e.message}`);
+    }
+}
+/** KaTeX maths for the Markdown, or nothing when `katex` is not installed (it is optional). */
+async function loadMath() {
+    try {
+        const { katexMath } = await import("./markdown-math.js");
+        return { math: katexMath() };
+    }
+    catch (e) {
+        if (e.code === "ERR_MODULE_NOT_FOUND")
+            return {};
+        throw e;
+    }
+}
 /** Inline markup passed on the command line (as opposed to a path or URL). */
 export function isInlineHtml(input) {
     return input.trimStart().startsWith("<");
@@ -152,13 +233,23 @@ export async function readInput(input) {
  * (`resolveHtmlSource`), while a file input falls back to its own directory.
  */
 export async function buildRenderOptions(input, flags) {
-    const source = isInlineHtml(input)
+    const markdown = flags.markdown || isMarkdownPath(input);
+    // `--markdown` takes a file path, `-` (stdin) or the Markdown text itself.
+    const inlineMarkdown = await isInlineMarkdown(input, flags);
+    let source = inlineMarkdown || isInlineHtml(input)
         ? { value: input, baseUrl: process.cwd() }
         : input === "-"
             ? { value: await readStdin(), baseUrl: process.cwd() }
             : isUrlInput(input)
                 ? { url: input }
                 : await readInput(input);
+    // A template's running header / footer and the PDF's title and author travel with the page.
+    let templateOptions = {};
+    if (markdown && "value" in source && typeof source.value === "string") {
+        const converted = await convertMarkdown(source.value, flags);
+        source = { ...source, value: converted.html };
+        templateOptions = converted.renderOptions;
+    }
     const fonts = flags.font?.length ? await loadFonts(flags.font) : [];
     const { animation, warning } = resolveAnimation(flags);
     if (warning)
@@ -169,6 +260,7 @@ export async function buildRenderOptions(input, flags) {
         format: flags.format,
         quality: flags.quality,
         ...source,
+        ...templateOptions,
         ...(flags.baseUrl !== undefined ? { baseUrl: flags.baseUrl } : {}),
         ...(flags.colorSpace !== undefined ? { colorSpace: flags.colorSpace } : {}),
         ...(flags.scale !== undefined ? { scale: flags.scale } : {}),
@@ -176,5 +268,6 @@ export async function buildRenderOptions(input, flags) {
         ...(animation ? { animation } : {}),
         ...(fonts.length ? { fonts } : {}),
         ...(flags.js ? { javascript: resolveJavaScript(flags.jsWait) } : {}),
+        ...(flags.outline === false ? { pdfOutline: false } : {}),
     };
 }

package/dist/cli.js

@@ -3,7 +3,7 @@ import { program } from "commander";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { render } from "./single.js";
-import { buildRenderOptions, inferFormat, isInlineHtml, isUrlInput, } from "./cli-options.js";
+import { buildRenderOptions, inferFormat, isInlineHtml, isInlineMarkdown, isUrlInput, } from "./cli-options.js";
 const OUTPUT_FORMATS = [
     "svg",
     "png",
@@ -26,7 +26,7 @@ program
     .name("wasm-html-to-image")
     .description("HTML to image converter on the single unified WASM module (svg/pdf direct, png/jpeg/webp/avif/jxl/raw/thumbhash via encode or html_to_image)")
     .version("0.1.0")
-    .argument("<input>", "input HTML/image file path, URL, inline HTML string (starts with <), or - for stdin")
+    .argument("[input]", "input HTML/image file path, URL, inline HTML string (starts with <), or - for stdin")
     .option("-o, --output <path>", "output file path")
     .option("-w, --width <number>", "viewport width", (v) => parseInt(v, 10), 800)
     .option("-h, --height <number>", "viewport height (omit for auto)", (v) => parseInt(v, 10))
@@ -40,10 +40,35 @@ program
     .option("--animation <duration-ms>", "sample the document's @keyframes opacity / transform / color animation into an animated WebP / APNG / GIF; one loop duration in ms (webp, apng and gif output only; the CSS animation-duration wins and this value is an upper bound)", (v) => parseInt(v, 10))
     .option("--animation-fps <n>", "animation frame rate (default 15, capped at ~75 frames total; requires --animation)", (v) => parseInt(v, 10))
     .option("--animation-loop <n>", "how many times the animated WebP / APNG / GIF repeats (0 = infinite, the default; 1 = play once; requires --animation)", (v) => parseInt(v, 10))
+    .option("--markdown", "treat the input as Markdown (implied by a .md / .markdown file; inline text and stdin need it; needs the optional dependency marked)")
+    .option("--template <name|file>", "look of a PDF from Markdown: a bundled template (see --list-templates) or a .json / .css file")
+    .option("--list-templates", "print the bundled templates and exit")
+    .option("--page-size <size>", "PDF page size for Markdown: A3, A4, A5, B4, B5, Letter, or e.g. '210mm 297mm'")
+    .option("--accent <colour>", "accent colour of a Markdown document (links, rules, cover), e.g. '#c2410c'")
+    .option("--body-font <family>", "body font family of a Markdown document (the renderer loads it; serif and sans-serif work)")
+    .option("--stamp <text>", "text printed in the header of every page of a Markdown PDF (DRAFT, Confidential, ...)")
+    .option("--cover", "a cover page with the title, subtitle, author and date (from the front matter)")
+    .option("--no-cover", "no cover page, whatever the template says")
+    .option("--no-toc", "no table of contents in a PDF made from Markdown (there is one by default)")
+    .option("--toc-depth <n>", "deepest heading level in the table of contents (default 3)", (v) => parseInt(v, 10))
+    .option("--no-outline", "leave the bookmarks (outline) out of a PDF (they are built from the headings by default)")
+    .option("--no-math", "do not typeset $...$ and $$...$$ in Markdown (done with KaTeX when it is installed)")
+    .option("--markdown-theme <light|dark>", "colour scheme of the built-in Markdown stylesheet (default light)")
+    .option("--markdown-css <path>", "extra CSS file appended after the built-in Markdown stylesheet")
     .option("--js", "run the page's scripts in jsdom before rendering (needs the optional dependency jsdom; trusted pages only)")
     .option("--js-wait <ms|selector>", "with --js: milliseconds to wait after load (default 1000), or a CSS selector to wait for")
     .action(async (input, options) => {
     try {
+        if (options.listTemplates) {
+            const { listTemplates } = await import("./markdown-template.js");
+            for (const t of listTemplates())
+                console.log(`${t.name.padEnd(10)} ${t.description}`);
+            return;
+        }
+        if (input === undefined) {
+            console.error("error: missing required argument 'input'");
+            process.exit(1);
+        }
         const format = String(options.format ?? inferFormat(options.output) ?? "png").toLowerCase();
         if (!isOutputFormat(format)) {
             console.error(`Error: unsupported format "${options.format}". Choose from: ${OUTPUT_FORMATS.join(", ")}`);
@@ -56,7 +81,7 @@ program
             process.exit(1);
         }
         const isUrl = isUrlInput(input);
-        const isVirtual = isInlineHtml(input) || input === "-";
+        const isVirtual = isInlineHtml(input) || input === "-" || (await isInlineMarkdown(input, options));
         if (isVirtual && !options.output) {
             console.error("Error: --output is required for inline HTML or stdin input");
             process.exit(1);
@@ -88,6 +113,19 @@ program
             font: options.font,
             js: options.js,
             jsWait: options.jsWait,
+            markdown: options.markdown,
+            markdownTheme: options.markdownTheme,
+            math: options.math,
+            template: options.template,
+            pageSize: options.pageSize,
+            accent: options.accent,
+            bodyFont: options.bodyFont,
+            stamp: options.stamp,
+            cover: options.cover,
+            toc: options.toc,
+            tocDepth: options.tocDepth,
+            outline: options.outline,
+            markdownCss: options.markdownCss,
         };
         const result = await render(await buildRenderOptions(input, flags));
         await fs.writeFile(outputPath, typeof result.data === "string"

package/dist/core-orchestrate.d.ts

@@ -54,6 +54,8 @@ export interface Orchestration {
         data: Uint8Array;
     }[] | undefined;
     limits: RenderLimits;
+    pdfOutline: boolean | undefined;
+    pdfBackground: string | undefined;
     pdfTitle: string | undefined;
     pdfAuthor: string | undefined;
     pdfSubject: string | undefined;

package/dist/core-orchestrate.js

@@ -14,7 +14,7 @@ import { pdfFirstPageSize, svgRootHeight } from "./output-size.js";
 import { FIT_INT, FORMAT_INT, TIFF_CMYK_INT } from "./encode-args.js";
 import { imageBytesFromUnknown, toBytes, } from "./input.js";
 import { DIAGNOSTIC_CODES, LogLevel, } from "./diagnostics.js";
-import { isNodeRuntime, now, resolveHtmlResources, } from "./core-resources.js";
+import { canSetUserAgent, now, resolveHtmlResources, } from "./core-resources.js";
 const DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
 export { DEFAULT_USER_AGENT };
 export function requireBindingError(name) {
@@ -34,7 +34,7 @@ export function defaultSpeed(format) {
 }
 /** Build per-call orchestration state (log gate, timings, diag, resolve ctx). */
 export function createOrchestration(module, options) {
-    const { format = "png", quality = 85, speed: speedOption, height, crop, fit, value, url, baseUrl, fontMap, userAgent, fallbackFonts, logLevel = LogLevel.None, onLog, diagnostics = false, onDiagnostics, onLayout, resolveResource, mediaType = "screen", textToPaths, css, fonts: preloadFonts, limits = {}, pdfTitle, pdfAuthor, pdfSubject, pdfKeywords, pdfCreator, pdfProducer, pdfMargin, pdfHeader, pdfFooter, } = options;
+    const { format = "png", quality = 85, speed: speedOption, height, crop, fit, value, url, baseUrl, fontMap, userAgent, fallbackFonts, logLevel = LogLevel.None, onLog, diagnostics = false, onDiagnostics, onLayout, resolveResource, mediaType = "screen", textToPaths, css, fonts: preloadFonts, limits = {}, pdfOutline, pdfBackground, pdfTitle, pdfAuthor, pdfSubject, pdfKeywords, pdfCreator, pdfProducer, pdfMargin, pdfHeader, pdfFooter, } = options;
     // `animation` accepts a boolean (image input: keep frames) or, for HTML
     // input, an object requesting keyframe sampling. The object form turns on
     // the boolean flag for the encode stage and enables the frame path.
@@ -179,6 +179,8 @@ export function createOrchestration(module, options) {
         css,
         preloadFonts,
         limits,
+        pdfOutline,
+        pdfBackground,
         pdfTitle,
         pdfAuthor,
         pdfSubject,
@@ -216,9 +218,9 @@ export async function resolveHtmlSource(orch) {
         return value;
     }
     if (typeof url === "string") {
-        // Same as resource fetch: User-Agent override is Node-only. In browsers
+        // Same as resource fetch: User-Agent override is Node/Workers-only. In browsers
         // it is forbidden and triggers a Firefox preflight that breaks CORS.
-        const headers = isNodeRuntime()
+        const headers = canSetUserAgent()
             ? { "User-Agent": userAgent ?? DEFAULT_USER_AGENT }
             : undefined;
         const fetchStart = now();

package/dist/core-resources.d.ts

@@ -11,6 +11,14 @@ import { LogLevel, type DiagnosticMessage, type FontDiagnostic, type RenderLimit
 /** Drop every cached resource (e.g. after the source assets changed). */
 export declare function clearResourceCache(): void;
 export declare function isNodeRuntime(): boolean;
+/**
+ * Whether `fetch` may send a `User-Agent` of our choosing: Node and Cloudflare Workers can; browsers
+ * cannot (and Firefox preflights it, which breaks Google Fonts / jsDelivr CORS). The UA decides what
+ * Google Fonts serves: a browser UA gets woff2 split by unicode-range (a few KB per page), anything
+ * else (a Worker's own UA, none) gets the whole `.ttf` per weight (about 5 MB each, embedded whole
+ * into a PDF).
+ */
+export declare function canSetUserAgent(): boolean;
 /**
  * Fetch external resource bytes. `data:` URLs resolve inline in C++
  * (`request()`), so they are skipped here. Relative URLs resolve against

package/dist/core-resources.js

@@ -61,6 +61,19 @@ export function isNodeRuntime() {
         .process;
     return typeof proc?.versions?.node === "string";
 }
+/**
+ * Whether `fetch` may send a `User-Agent` of our choosing: Node and Cloudflare Workers can; browsers
+ * cannot (and Firefox preflights it, which breaks Google Fonts / jsDelivr CORS). The UA decides what
+ * Google Fonts serves: a browser UA gets woff2 split by unicode-range (a few KB per page), anything
+ * else (a Worker's own UA, none) gets the whole `.ttf` per weight (about 5 MB each, embedded whole
+ * into a PDF).
+ */
+export function canSetUserAgent() {
+    if (isNodeRuntime())
+        return true;
+    const nav = globalThis.navigator;
+    return nav?.userAgent === "Cloudflare-Workers";
+}
 function fileUrlToFsPath(p) {
     if (!p.startsWith("file://"))
         return p;
@@ -103,9 +116,9 @@ async function isInsideDir(fs, path, root, target) {
 /** Built-in resolution behind the `resolveResource` hook (see above). */
 async function fetchResourceBytesInner(url, baseUrl, userAgent, timeoutMs, confineFiles) {
     // Browser fetch forbids overriding User-Agent (and Firefox preflights it,
-    // breaking Google Fonts/jsDelivr CORS). Spoof only in Node where we
-    // control the UA to get woff2 CSS.
-    const headers = userAgent && isNodeRuntime() ? { "User-Agent": userAgent } : undefined;
+    // breaking Google Fonts/jsDelivr CORS). Spoof only where we control the UA
+    // (Node, Workers) to get woff2 CSS.
+    const headers = userAgent && canSetUserAgent() ? { "User-Agent": userAgent } : undefined;
     // Abort hung connections so one stalled server cannot outlive `timeoutMs`.
     const signal = timeoutMs !== undefined
         ? // Node >= 24 requires an integer delay; the remaining budget is fractional.

package/dist/core.d.ts

@@ -200,6 +200,16 @@ export interface HtmlToImageOptions extends RenderOptions {
      *   gamut-mapped. Other formats ignore it.
      */
     colorSpace?: "srgb" | "cmyk";
+    /**
+     * PDF outline (bookmarks) built from the document's `h1`-`h6`. On by default; `false` leaves it out.
+     */
+    pdfOutline?: boolean;
+    /**
+     * PDF page background, painted over the whole page (margins included) before the content: `#rrggbb`
+     * or `#rrggbbaa`. Without it only the content area takes the document's `background`, so a dark page
+     * would show white margins. Other formats ignore it.
+     */
+    pdfBackground?: string;
     /** PDF Title metadata. */
     pdfTitle?: string;
     /** PDF Author metadata. */

package/dist/core.js

@@ -48,6 +48,8 @@ export async function htmlToImage(module, options) {
         mediaTypeInt: orch.mediaTypeInt,
         colorSpace: orch.colorSpace,
         scale: orch.scale,
+        pdfOutline: orch.pdfOutline,
+        pdfBackground: orch.pdfBackground,
         pdfTitle: orch.pdfTitle,
         pdfAuthor: orch.pdfAuthor,
         pdfSubject: orch.pdfSubject,

package/dist/encode-args.d.ts

@@ -18,6 +18,8 @@ export interface FullSatoruOptionsInput {
     mediaTypeInt: number;
     colorSpace?: "srgb" | "cmyk";
     scale?: number;
+    pdfOutline?: boolean;
+    pdfBackground?: string;
     pdfTitle?: string;
     pdfAuthor?: string;
     pdfSubject?: string;
@@ -38,3 +40,8 @@ export interface FullSatoruOptionsInput {
  * `core.ts` HTML パスはこの関数のみを使い、個別組み立てをしない。
  */
 export declare function buildFullSatoruOptions(input: FullSatoruOptionsInput): Record<string, unknown>;
+/**
+ * `#rgb`, `#rrggbb` or `#rrggbbaa` as the engine's ARGB integer (`0xAARRGGBB`). Anything else is an error:
+ * a mistyped colour should not silently paint nothing.
+ */
+export declare function parseCssColor(color: string): number;

package/dist/encode-args.js

@@ -39,13 +39,16 @@ export function buildSatoruOptions(crop, fit) {
  * `core.ts` HTML パスはこの関数のみを使い、個別組み立てをしない。
  */
 export function buildFullSatoruOptions(input) {
-    const { textToPaths, mediaTypeInt, pdfTitle, pdfAuthor, pdfSubject, pdfKeywords, pdfCreator, pdfProducer, pdfMargin, pdfHeader, pdfFooter, } = input;
+    const { textToPaths, mediaTypeInt, pdfOutline, pdfBackground, pdfTitle, pdfAuthor, pdfSubject, pdfKeywords, pdfCreator, pdfProducer, pdfMargin, pdfHeader, pdfFooter, } = input;
     return {
         ...buildSatoruOptions(input.crop, input.fit),
         svgTextToPaths: textToPaths ?? true,
         mediaType: mediaTypeInt,
         ...(input.colorSpace === "cmyk" ? { colorSpace: 1 } : {}),
         ...(input.scale !== undefined && input.scale !== 1 ? { scale: input.scale } : {}),
+        // The engine's default is on: only an explicit false has to be sent.
+        ...(pdfOutline === false ? { pdfOutline: false } : {}),
+        ...(pdfBackground !== undefined ? { backgroundColor: parseCssColor(pdfBackground) } : {}),
         pdfTitle: pdfTitle ?? "",
         pdfAuthor: pdfAuthor ?? "",
         pdfSubject: pdfSubject ?? "",
@@ -60,3 +63,17 @@ export function buildFullSatoruOptions(input) {
         pdfFooter: pdfFooter ?? "",
     };
 }
+/**
+ * `#rgb`, `#rrggbb` or `#rrggbbaa` as the engine's ARGB integer (`0xAARRGGBB`). Anything else is an error:
+ * a mistyped colour should not silently paint nothing.
+ */
+export function parseCssColor(color) {
+    const m = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(color.trim());
+    if (!m)
+        throw new Error(`invalid colour "${color}": use #rgb, #rrggbb or #rrggbbaa`);
+    let hex = m[1];
+    if (hex.length === 3)
+        hex = hex.split("").map((c) => c + c).join("");
+    const a = hex.length === 8 ? hex.slice(6, 8) : "ff";
+    return parseInt(a + hex.slice(0, 6), 16) >>> 0;
+}