wasm-html-to-image 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SoraKumo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the \"Software\"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,326 @@
+# wasm-html-to-image
+
+[![npm version](https://img.shields.io/npm/v/wasm-html-to-image.svg)](https://www.npmjs.com/package/wasm-html-to-image)
+[![npm downloads](https://img.shields.io/npm/dw/wasm-html-to-image.svg)](https://www.npmjs.com/package/wasm-html-to-image)
+[![license](https://img.shields.io/npm/l/wasm-html-to-image.svg)](https://github.com/SoraKumo001/wasm-html-to-image/blob/master/LICENSE)
+[![Playground](https://img.shields.io/badge/Demo-Playground-blueviolet)](https://sorakumo001.github.io/wasm-html-to-image/master)
+[![Documentation](https://img.shields.io/badge/Docs-Docusaurus-blue)](https://sorakumo001.github.io/wasm-html-to-image/)
+
+A high-performance, WebAssembly-powered HTML-to-image renderer and image optimization engine. It consolidates HTML rendering (**Satoru** / **Skia** / **litehtml**) and native image encoding (**WebP / AVIF / JPEG**) into a single, unified WASM binary.
+
+No headless browsers (Chromium, Puppeteer, or Playwright) required. Runs seamlessly across Node.js, Cloudflare Workers, Edge runtimes, browsers, and the CLI.
+
+---
+
+## ✨ Features
+
+- ⚡ **Single Unified WASM Binary**: HTML parsing, CSS layout, vector painting, and image encoding execute entirely inside WebAssembly without copying intermediate framebuffers across JS boundaries.
+- 🎨 **Versatile Inputs**: Renders HTML strings, remote Web URLs, multi-page HTML arrays, or raw image buffers (PNG, JPEG, WebP, GIF, AVIF, BMP, Data URLs).
+- 📦 **Rich Output Formats**: Direct SVG vector streams, high-quality PNG, JPEG, WebP, AVIF, uncompressed RAW pixels, ThumbHash placeholders, and multi-page vector PDFs.
+- 🚀 **Zero-Config Single Bundle**: Use `wasm-html-to-image/single` to call `render()` immediately without manual WASM loading or build setup.
+- 🌐 **Edge & Serverless Native**: Dedicated subpaths (`/workerd` for Cloudflare Workers, `/edge-light` for Vercel Edge) tailored for strict serverless constraints.
+- 🧵 **Multi-Threaded Worker Pool**: Process thousands of images in parallel using `wasm-html-to-image/workers` (Node.js worker threads / Web Workers).
+- ⚛️ **Ecosystem Ready**: First-class support for React / Preact JSX components and Tailwind CSS inlined styling.
+
+---
+
+## 📦 Installation
+
+```bash npm2yarn
+npm install wasm-html-to-image
+```
+
+---
+
+## 🚀 Quick Start
+
+### Zero-Config Rendering (`wasm-html-to-image`)
+
+The easiest way to get started. WASM is embedded and loaded automatically (in Cloudflare Workers, the workerd-optimized module is automatically selected):
+
+```typescript
+import { render } from "wasm-html-to-image";
+
+// 1. Render HTML to PNG (returns RenderResult with .data and dimensions)
+const result = await render({
+  value: `<div style="background: linear-gradient(135deg, #667eea, #764ba2); padding: 40px; color: white; border-radius: 16px; font-family: sans-serif;">
+    <h1 style="margin: 0; font-size: 32px;">Hello wasm-html-to-image</h1>
+    <p style="margin-top: 8px; opacity: 0.9;">High-performance serverless rendering</p>
+  </div>`,
+  width: 800,
+  format: "png",
+});
+
+console.log(result.data); // Uint8Array
+console.log(result.width, result.height); // 800, 600
+
+// 2. Convert and resize image with the same render() function
+const webp = await render({
+  value: result.data, // Pass raw image buffer directly
+  width: 400, // Target resized width
+  format: "webp",
+  quality: 80,
+});
+
+console.log(webp.originalWidth, webp.originalHeight); // Original image dimensions
+console.log(webp.width, webp.height); // Output image dimensions
+```
+
+---
+
+## 🖼️ Image-to-Image Conversion & Optimization
+
+`wasm-html-to-image` is not only an HTML renderer — it also serves as a high-speed, self-contained **image-to-image converter, resizer, and compressor** without requiring heavy native libraries like Sharp or ImageMagick.
+
+Simply pass raw image bytes (`Uint8Array` or `Buffer`) or a `data:image/...` URL to `render()`. It automatically identifies input magic bytes, skips the HTML layout pass, and routes straight into the native Skia image pipeline. Every call returns rich metadata (`width`, `height`, `originalWidth`, `originalHeight`, `format`, `isAnimated`) along with the output data in `.data`:
+
+```typescript
+import fs from "node:fs/promises";
+import { render } from "wasm-html-to-image/single";
+
+const imageBuffer = await fs.readFile("photo.jpg");
+
+// 1. Convert JPEG -> AVIF (highest compression)
+const avif = await render({
+  value: imageBuffer,
+  width: 800,
+  format: "avif",
+  quality: 75,
+  speed: 6, // 0 (best quality) - 10 (fastest)
+});
+await fs.writeFile("photo.avif", Buffer.from(avif.data));
+
+// 2. Crop & Resize -> PNG
+const cropped = await render({
+  value: imageBuffer,
+  crop: { x: 50, y: 50, width: 300, height: 300 },
+  width: 150,
+  height: 150,
+  format: "png",
+});
+await fs.writeFile("cropped.png", Buffer.from(cropped.data));
+
+// 3. Generate ThumbHash Blur Placeholder
+const thumbhash = await render({
+  value: imageBuffer,
+  width: 100,
+  format: "thumbhash",
+});
+console.log("ThumbHash bytes:", thumbhash.data);
+
+// 4. Convert Image -> Single-Page Vector PDF
+const pdf = await render({
+  value: imageBuffer,
+  format: "pdf",
+});
+await fs.writeFile("photo.pdf", Buffer.from(pdf.data));
+
+// 5. Convert Animated GIF -> Animated WebP
+const animatedWebp = await render({
+  value: await fs.readFile("animation.gif"),
+  format: "webp",
+  animation: true,
+});
+await fs.writeFile("animation.webp", Buffer.from(animatedWebp.data));
+```
+
+---
+
+## 📊 Format Matrix
+
+### Inputs (`value` / `url`)
+
+| Input Type                  | Detection                        | Description                                                |
+| --------------------------- | -------------------------------- | ---------------------------------------------------------- |
+| **HTML String**             | Text starting with tags / markup | Standard HTML/CSS rendering                                |
+| **HTML Array (`string[]`)** | Array of HTML strings            | Multi-page PDF generation (one page per item)              |
+| **URL (`url`)**             | `http://` or `https://`          | Automatically fetches and renders remote web pages         |
+| **Image Buffer**            | `Uint8Array` / `Buffer`          | Magic-byte recognition for PNG, JPEG, WebP, GIF, AVIF, BMP |
+| **Data URL**                | `data:image/*;base64,...`        | Inlined image data URL, routed straight to image pipeline  |
+
+### Outputs (`format`)
+
+All formats return a `RenderResult<T>` object containing `.data` (`Uint8Array` or `string` for SVG) and metadata (`width`, `height`, `originalWidth`, `originalHeight`, `format`, `isAnimated`):
+
+| Format      | `result.data` Type | HTML Input                                     | Image Input                                   |
+| ----------- | ------------------ | ---------------------------------------------- | --------------------------------------------- |
+| `png`       | `Uint8Array`       | Skia render → PNG encode                       | Decodes and converts to PNG                   |
+| `jpeg`      | `Uint8Array`       | Skia render → JPEG encode (`quality`)          | Decodes and compresses JPEG                   |
+| `webp`      | `Uint8Array`       | Skia render → WebP encode (`quality`)          | Decodes and compresses WebP                   |
+| `avif`      | `Uint8Array`       | Skia render → AVIF encode (`quality`, `speed`) | Decodes and compresses AVIF                   |
+| `raw`       | `Uint8Array`       | Uncompressed RGBA pixel bytes                  | Uncompressed RGBA pixel bytes                 |
+| `thumbhash` | `Uint8Array`       | Computes ThumbHash from render                 | Computes ThumbHash from image                 |
+| `svg`       | `string`           | Skia vector drawing stream                     | Single `<image>` wrapper SVG                  |
+| `pdf`       | `Uint8Array`       | SkPDFDocument vector PDF                       | Single-page centered PDF                      |
+| `none`      | `Uint8Array`       | N/A (throws error)                             | Passthrough original bytes + extract metadata |
+
+---
+
+## 🧩 Subpaths & Usage
+
+Choose the optimal entry point for your application and environment:
+
+| Subpath                         | Target Environment                       | Highlights                                                             |
+| ------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------- |
+| `wasm-html-to-image`            | Universal (Node, Edge, Cloudflare, Deno) | Zero-config default: auto routes to single/workerd, instant `render()` |
+| `wasm-html-to-image/single`     | Node.js, Bundlers                        | Single bundled WASM entry point                                        |
+| `wasm-html-to-image/index`      | High-throughput servers                  | Explicit `loadHtmlToImageModule()` & manual instance reuse             |
+| `wasm-html-to-image/workerd`    | Cloudflare Workers                       | WebAssembly.Module compilation compatible                              |
+| `wasm-html-to-image/edge-light` | Vercel Edge Runtime                      | Optimized for Edge Runtime constraints                                 |
+| `wasm-html-to-image/workers`    | Node.js, Browsers                        | Multi-threaded worker pool for high concurrency                        |
+| `wasm-html-to-image/react`      | React integration                        | Directly render React JSX element trees                                |
+| `wasm-html-to-image/preact`     | Preact integration                       | Directly render Preact JSX element trees                               |
+| `wasm-html-to-image/tailwind`   | Utility styling                          | Inlines UnoCSS / Tailwind classes                                      |
+
+---
+
+## 💡 Practical Examples
+
+### 1. High-Throughput Node.js Server (Instance Reuse)
+
+Reuse the WASM module across incoming HTTP requests for maximum performance:
+
+```typescript
+import { loadHtmlToImageModule, htmlToImage } from "wasm-html-to-image";
+import express from "express";
+
+const app = express();
+const mod = await loadHtmlToImageModule(); // Load once at startup
+
+app.get("/ogp", async (req, res) => {
+  const result = await htmlToImage(mod, {
+    value: `<h1>${req.query.title}</h1>`,
+    width: 1200,
+    height: 630,
+    format: "webp",
+    quality: 85,
+  });
+
+  res.type("image/webp").send(Buffer.from(result.data));
+});
+
+app.listen(3000);
+```
+
+### 2. Cloudflare Workers (`workerd`)
+
+Generate dynamic social preview images at the edge:
+
+```typescript
+// wrangler.jsonc:
+// { "rules": [{ "type": "CompiledWasm", "globs": ["**/*.wasm"], "fallthrough": false }] }
+
+import { render } from "wasm-html-to-image/workerd";
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const result = await render({
+      value: `<div style="padding: 40px; font-family: sans-serif; background: #0f172a; color: white;">
+        <h1>Edge OGP Generator</h1>
+      </div>`,
+      width: 1200,
+      height: 630,
+      format: "png",
+    });
+
+    return new Response(result.data, {
+      headers: {
+        "Content-Type": "image/png",
+        "Cache-Control": "public, max-age=86400",
+      },
+    });
+  },
+};
+```
+
+### 3. Multi-Threaded Batch Generation (`workers`)
+
+Leverage multi-core CPUs to process large batches of images in parallel:
+
+```typescript
+import { render } from "wasm-html-to-image/workers";
+
+const tasks = items.map((item) =>
+  render({
+    value: `<h1>${item.title}</h1>`,
+    width: 600,
+    height: 400,
+    format: "webp",
+  }),
+);
+
+const images = await Promise.all(tasks);
+```
+
+### 4. Command Line Interface (CLI)
+
+Render directly from your shell without writing code:
+
+```bash
+# Render HTML to WebP
+npx wasm-html-to-image template.html -o banner.webp -w 1200 -h 630 -f webp -q 90
+
+# Capture screenshot from URL
+npx wasm-html-to-image https://example.com -o site.png -w 1280 -h 720
+
+# Convert and resize an image
+npx wasm-html-to-image photo.jpg -o photo.avif -w 800 -f avif -q 80
+```
+
+---
+
+## 📖 Documentation
+
+For full guides, architecture deep-dives, font management, and advanced recipes:
+
+👉 **[Read the Official Documentation](https://sorakumo001.github.io/wasm-html-to-image/)**
+
+- [Overview & Getting Started](https://sorakumo001.github.io/wasm-html-to-image/docs/overview)
+- [Architecture & Pipelines](https://sorakumo001.github.io/wasm-html-to-image/docs/architecture)
+- [API Reference](https://sorakumo001.github.io/wasm-html-to-image/docs/api-reference)
+- [Runtime Guide (Node / Workers / Edge / Browser)](https://sorakumo001.github.io/wasm-html-to-image/docs/api-reference/runtime-guide)
+- [Production Recipes](https://sorakumo001.github.io/wasm-html-to-image/docs/recipes)
+
+---
+
+## 🛠️ Development
+
+<details>
+<summary>Click to view repository build and test instructions</summary>
+
+### Prerequisites
+
+- Node.js >= 20, pnpm >= 9
+- Emscripten SDK (emsdk), CMake, Ninja, vcpkg (for C++ WASM builds)
+
+### Building
+
+```bash
+# Install workspace dependencies
+pnpm install
+
+# Build TypeScript packages
+pnpm --filter wasm-html-to-image build
+pnpm build:js
+
+# Build Documentation
+pnpm docs:build
+```
+
+### Testing
+
+```bash
+# Unit tests (Vitest)
+pnpm --filter wasm-html-to-image test
+
+# Visual regression tests
+pnpm --filter visual-test test
+```
+
+</details>
+
+---
+
+## 📄 License
+
+MIT © [SoraKumo](https://github.com/SoraKumo001)

package/dist/browser-workers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Browser worker-side implementation (pre-bundled `dist/web-workers.js`).
+ * Mirrors `./child-workers.js`, but the WASM is the compressed payload
+ * (`dist/html-to-image-wasm.js`, restored via `DecompressionStream`) handed
+ * to the regular glue as `wasmBinary`, so no `.wasm` fetch/`locateFile`
+ * is needed.
+ */
+declare const map: {
+    render(options: import("./core.js").HtmlToImageOptions): Promise<import("./core.js").RenderResult<Uint8Array | string>>;
+};
+export type HtmlToImageWorker = typeof map;
+export {};

package/dist/browser-workers.js

@@ -0,0 +1,26 @@
+import { loadWorkerLib } from "./worker-lib-loader.js";
+import { loadHtmlToImageModule, } from "./loader.js";
+import { loadCompressedWasmBinary } from "./wasm-payload.js";
+import { createRenderActions } from "./worker-actions.js";
+// @ts-expect-error — dist/html-to-image.js is generated at build time
+import createHtmlToImageModule from "../dist/html-to-image.js";
+const { initWorker } = await loadWorkerLib();
+let mod;
+/** Lazily load (and reuse) the module inside this worker. */
+const getModule = async () => {
+    if (!mod) {
+        mod = await loadHtmlToImageModule({
+            factory: createHtmlToImageModule,
+            moduleArg: { wasmBinary: await loadCompressedWasmBinary() },
+        });
+    }
+    return mod;
+};
+/**
+ * Browser worker-side implementation (pre-bundled `dist/web-workers.js`).
+ * Mirrors `./child-workers.js`, but the WASM is the compressed payload
+ * (`dist/html-to-image-wasm.js`, restored via `DecompressionStream`) handed
+ * to the regular glue as `wasmBinary`, so no `.wasm` fetch/`locateFile`
+ * is needed.
+ */
+const map = initWorker(createRenderActions(getModule));

package/dist/child-workers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Worker-side implementation.
+ * Exposes the unified render (HTML and image inputs) via worker-lib.
+ * Each worker thread loads its own module instance (modules cannot cross
+ * thread boundaries, so nothing is shared with the parent).
+ */
+declare const map: {
+    render(options: import("./core.js").HtmlToImageOptions): Promise<import("./core.js").RenderResult<Uint8Array | string>>;
+};
+export type HtmlToImageWorker = typeof map;
+export {};

package/dist/child-workers.js

@@ -0,0 +1,19 @@
+import { loadWorkerLib } from "./worker-lib-loader.js";
+import { getDefaultModule } from "./single.js";
+import { createRenderActions } from "./worker-actions.js";
+const { initWorker } = await loadWorkerLib();
+let mod;
+/** Lazily load (and reuse) the single module inside this worker. */
+const getModule = async () => {
+    if (!mod) {
+        mod = await getDefaultModule();
+    }
+    return mod;
+};
+/**
+ * Worker-side implementation.
+ * Exposes the unified render (HTML and image inputs) via worker-lib.
+ * Each worker thread loads its own module instance (modules cannot cross
+ * thread boundaries, so nothing is shared with the parent).
+ */
+const map = initWorker(createRenderActions(getModule));

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { render, } from "./single.js";
+import { isImageInput } from "./core.js";
+const OUTPUT_FORMATS = [
+    "svg",
+    "png",
+    "pdf",
+    "jpeg",
+    "webp",
+    "avif",
+    "raw",
+    "thumbhash",
+    "none",
+];
+function isOutputFormat(value) {
+    return OUTPUT_FORMATS.includes(value);
+}
+/**
+ * Read a local input file as binary; image files (magic-byte sniffed) are
+ * passed through as bytes, everything else as UTF-8 text (HTML).
+ */
+async function readInput(input) {
+    const data = await fs.readFile(input);
+    let value = data.toString("utf-8");
+    try {
+        if (isImageInput(data))
+            value = data;
+    }
+    catch {
+        // Unknown binary magic -> treat as text and let rendering decide.
+    }
+    return { value, baseUrl: path.dirname(path.resolve(input)) };
+}
+program
+    .name("wasm-html-to-image")
+    .description("HTML to image converter on the single unified WASM module (svg/pdf direct, png/jpeg/webp/avif/raw/thumbhash via encode or html_to_image)")
+    .version("0.1.0")
+    .argument("<input>", "input HTML/image file path or URL")
+    .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))
+    .option("-f, --format <format>", `output format (${OUTPUT_FORMATS.join(", ")})`, "png")
+    .option("-q, --quality <number>", "encode quality 0-100 (encode stage only)", (v) => parseFloat(v), 85)
+    .action(async (input, options) => {
+    try {
+        const format = String(options.format).toLowerCase();
+        if (!isOutputFormat(format)) {
+            console.error(`Error: unsupported format "${options.format}". Choose from: ${OUTPUT_FORMATS.join(", ")}`);
+            process.exit(1);
+        }
+        const isWindowsPath = /^[a-zA-Z]:[\\/]/.test(input);
+        const isUrl = !isWindowsPath &&
+            /^[a-z][a-z0-9+.-]*:/i.test(input) &&
+            !input.startsWith("data:");
+        let outputPath = options.output;
+        if (!outputPath) {
+            const ext = format;
+            outputPath = isUrl
+                ? `output.${ext}`
+                : path.format({
+                    dir: path.dirname(input),
+                    name: path.basename(input, path.extname(input)),
+                    ext: `.${ext}`,
+                });
+        }
+        const renderOptions = {
+            width: options.width,
+            height: options.height,
+            format,
+            quality: options.quality,
+            ...(isUrl ? { url: input, baseUrl: input } : await readInput(input)),
+        };
+        const result = await render(renderOptions);
+        await fs.writeFile(outputPath, typeof result.data === "string"
+            ? result.data
+            : Buffer.from(result.data));
+        console.log(`Successfully rendered to ${outputPath}`);
+    }
+    catch (err) {
+        console.error("Error during rendering:", err);
+        process.exit(1);
+    }
+});
+program.parseAsync(process.argv);

package/dist/core.d.ts

@@ -0,0 +1,168 @@
+import type { HtmlToImageModule } from "./loader.js";
+import { isImageInput } from "./input.js";
+import { DIAGNOSTIC_CODES, LogLevel, type RenderDiagnostics, type RenderLimits, type ResolveResourceHook } from "./diagnostics.js";
+export { isImageInput };
+export { DIAGNOSTIC_CODES, LogLevel };
+export type { DiagnosticMessage, FontDiagnostic, RenderDiagnostics, RenderLimits, ResolveResourceHook, ResourceDiagnostic, } from "./diagnostics.js";
+/**
+ * Final output formats. Single-WASM internal routing:
+ * - HTML input: resources are resolved on the instance first
+ *   (`satoru_collect_resources` -> fetch -> `satoru_add_resource`), then
+ *   `satoru_render` direct (svg/pdf) or `satoru_render` PNG intermediate ->
+ *   `converter_encode`. The unified `html_to_image` binding is only a legacy
+ *   fallback for builds without instance render bindings.
+ * - Image input: render stage skipped, straight to `converter_*`
+ *   (`converter_load_image` -> optional crop/resize -> `converter_encode`,
+ *   or `converter_encode_svg` / `converter_encode_pdf`).
+ */
+export type OutputFormat = "svg" | "png" | "pdf" | "jpeg" | "webp" | "avif" | "raw" | "thumbhash" | "none";
+/** Result of rendering an HTML document or converting an image. */
+export interface RenderResult<T = Uint8Array | string> {
+    /** Output binary or text (string for svg, Uint8Array for all others). */
+    data: T;
+    /** Result image width in pixels. */
+    width: number;
+    /** Result image height in pixels. */
+    height: number;
+    /** Output format. */
+    format: OutputFormat;
+    /** Original input image width (image inputs only). */
+    originalWidth?: number;
+    /** Original input image height (image inputs only). */
+    originalHeight?: number;
+    /** Original input image format (image inputs only). */
+    originalFormat?: string;
+    /** Whether the original input image is animated (image inputs only). */
+    originalAnimation?: boolean;
+    /** Whether the output is animated. */
+    animation?: boolean;
+}
+/**
+ * Render input (self-defined; no `satoru-render` dependency).
+ * `value` accepts HTML (`string` / `string[]`), a `data:image/` URL string,
+ * or raw image bytes (`Uint8Array` / `ArrayBuffer`).
+ * Extra keys are passed through to the WASM binding options object.
+ */
+export interface RenderOptions {
+    value?: string | string[] | Uint8Array | ArrayBuffer;
+    url?: string;
+    baseUrl?: string;
+    width: number;
+    height?: number;
+    format?: OutputFormat;
+}
+/**
+ * Unified options for HTML and image inputs.
+ *
+ * - HTML input: `width`/`height` are the layout viewport; `crop`/`fit`
+ *   are forwarded to the satoru render options.
+ * - Image input: render stage is skipped; `width`/`height`/`crop`/`fit`
+ *   are applied as output resize on the encode stage.
+ */
+export interface HtmlToImageOptions extends RenderOptions {
+    /** Encode quality 0-100 (encode stage only, default 85; ignored for svg/pdf). */
+    quality?: number;
+    /** Encode speed 0-10, mainly for AVIF (encode stage only, default 6). */
+    speed?: number;
+    /** Keep animation frames where supported (encode stage only). */
+    animation?: boolean;
+    /** Crop rectangle (encode stage for image input, render options for HTML). */
+    crop?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Resize strategy (encode stage for image input, render options for HTML). */
+    fit?: "contain" | "cover" | "fill";
+    /**
+     * Generic family -> font URL map (upstream `DEFAULT_FONT_MAP` strategy).
+     * Applied via `satoru_set_font_map` before resource discovery, so
+     * `@font-face`-less text (sans-serif/serif/...) resolves through Google
+     * Fonts instead of rendering blank. Defaults to `DEFAULT_FONT_MAP`.
+     */
+    fontMap?: Record<string, string>;
+    /** User-Agent for resource fetches (default: Chrome, for woff2 CSS). */
+    userAgent?: string;
+    /**
+     * User-supplied fallback font(s), applied to the instance before resource
+     * discovery (upstream `fallbackFonts` idiom). Entries may be raw bytes
+     * (`Uint8Array` / `ArrayBuffer`), a `data:` URL, or a fetchable URL
+     * (http(s) or baseUrl-relative file on Node).
+     */
+    fallbackFonts?: (Uint8Array | ArrayBuffer | string)[];
+    /**
+     * Log severity gate for `onLog` (satoru `LogLevel` parity; default
+     * `None` silences all JS-side log calls). Also forwarded to the WASM
+     * `satoru_set_log_level` binding when set.
+     */
+    logLevel?: LogLevel;
+    /** JS-side log hook, called at stage boundaries, warnings, and errors. */
+    onLog?: (level: LogLevel, message: string) => void;
+    /** Collect a full `RenderDiagnostics` report (delivered to `onDiagnostics`). */
+    diagnostics?: boolean;
+    /** Receives the diagnostics report when `diagnostics` is enabled. */
+    onDiagnostics?: (report: RenderDiagnostics) => void;
+    /**
+     * Override hook for resource resolution, applied to every fetch path
+     * (discovery fetches, fallback-font URLs, HTML `url` fetch). Return
+     * bytes to inject, or `null` to skip the resource.
+     */
+    resolveResource?: ResolveResourceHook;
+    /** Media type for CSS `@media` queries (default `"screen"`). */
+    mediaType?: "screen" | "print";
+    /** Render SVG text as paths (default `true`, satoru parity). */
+    textToPaths?: boolean;
+    /** Extra CSS pre-scanned on the instance before discovery. */
+    css?: string;
+    /** Named fonts pre-loaded on the instance before discovery. */
+    fonts?: {
+        name: string;
+        data: Uint8Array;
+    }[];
+    /** Safety/performance limits, enforced in JS around resource resolution. */
+    limits?: RenderLimits;
+    /** PDF Title metadata. */
+    pdfTitle?: string;
+    /** PDF Author metadata. */
+    pdfAuthor?: string;
+    /** PDF Subject metadata. */
+    pdfSubject?: string;
+    /** PDF Keywords metadata. */
+    pdfKeywords?: string;
+    /** PDF Creator metadata. */
+    pdfCreator?: string;
+    /** PDF Producer metadata. */
+    pdfProducer?: string;
+    /** PDF page margins in pixels. */
+    pdfMargin?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    /** PDF header HTML template. */
+    pdfHeader?: string;
+    /** PDF footer HTML template. */
+    pdfFooter?: string;
+    /** Extra keys are forwarded to the WASM render options object. */
+    [key: string]: unknown;
+}
+/**
+ * Upstream default font strategy (verbatim from satoru `DEFAULT_FONT_MAP`):
+ * generic families resolve to Google Fonts css2 URLs (fetched with a browser
+ * UA so woff2 is served); fetched at render time, nothing bundled.
+ */
+export declare const DEFAULT_FONT_MAP: Record<string, string>;
+/** Binding names reported by {@link requireBindingError}. */
+export type WasmBindingName = "satoru_render" | "converter_encode" | "converter_encode_svg" | "converter_encode_pdf" | "converter_load_image" | "html_to_image";
+/**
+ * Render HTML — or convert an image — through the single unified WASM
+ * module. Image input skips the render stage and goes straight to
+ * `converter_encode`. Returns bytes (`Uint8Array`); only `svg` resolves
+ * to `string`.
+ */
+export declare function htmlToImage(module: HtmlToImageModule, options: HtmlToImageOptions & {
+    format: "svg";
+}): Promise<RenderResult<string>>;
+export declare function htmlToImage(module: HtmlToImageModule, options: HtmlToImageOptions): Promise<RenderResult<Uint8Array | string>>;