wasm-html-to-image 0.1.0

package/dist/loader.js

@@ -0,0 +1,199 @@
+/**
+ * Single-WASM loader for the unified `html-to-image` Emscripten module.
+ *
+ * Build assumptions (see `src/cpp/main.cpp`, C++ lane owns them):
+ * - Emscripten `MODULARIZE` + `EXPORT_ES6` → `dist/html-to-image.js`
+ *   with `export default createHtmlToImageModule`.
+ * - Single `EMSCRIPTEN_BINDINGS(html_to_image)` with `satoru_*` /
+ *   `converter_*` prefixed JS names (no bare `create_instance` etc.).
+ *
+ * Registered bindings: instance lifecycle + log level, render/encode
+ * (`satoru_render`, `converter_encode`, ...), resource discovery/injection
+ * (`satoru_collect_resources`, `satoru_get_pending_resources`,
+ * `satoru_add_resource`, `satoru_load_font`, `satoru_load_fallback_font`,
+ * `satoru_set_font_map`, ...), and the unified `html_to_image` call.
+ * Bindings added over time stay optional in the type below; callers must
+ * feature-check at runtime (see `./core.ts`).
+ *
+ * Node and browser share this minimal shape: dynamic `import()` of the glue
+ * file URL, then invoking the factory. No `node:` builtins are used so the
+ * same file works in both runtimes.
+ */
+/**
+ * Process-wide module cache, keyed by factory then moduleArg: different
+ * factories, or different WASM payloads (e.g. workerd/edge-light calls
+ * with distinct `WebAssembly.Module`s), must not share an instance.
+ * Callers with their own scoping (workerd/edge-light per-wasm maps,
+ * single.ts default path, `*-workers` lazy vars) are unaffected.
+ */
+const moduleCache = new Map();
+/** Default glue URL: `./html-to-image.js` next to the compiled loader. */
+export function defaultGlueUrl() {
+    return new URL("./html-to-image.js", import.meta.url);
+}
+function isModuleNotFound(e) {
+    const code = e?.code;
+    if (code === "ERR_MODULE_NOT_FOUND")
+        return true;
+    const msg = e instanceof Error ? e.message : String(e);
+    return /Cannot find (module|package)/.test(msg);
+}
+/**
+ * Import glue by URL, tolerating bundlers that hijack dynamic `import()`.
+ * Webpack rewrites even variable `import(url)` into chunk loading, which
+ * cannot resolve runtime URLs ("Cannot find module"). The native attempt
+ * runs first (unchanged behavior everywhere it already works, including
+ * strict-CSP pages); only on failure is an indirect import (invisible to
+ * bundlers' static analysis) retried. The original error is rethrown when
+ * both attempts fail, preserving existing error semantics (e.g. the
+ * src→dist dev fallback branching below).
+ */
+async function importGlueModule(glue) {
+    // `webpackIgnore` keeps Turbopack (Next.js 16 default builder) from trying
+    // to resolve the runtime URL at build time; webpack/vite honor it too.
+    try {
+        return (await import(
+        /* @vite-ignore, webpackIgnore: true */ glue));
+    }
+    catch (first) {
+        try {
+            const indirect = new Function("u", "return import(u)");
+            return await indirect(glue);
+        }
+        catch {
+            throw first;
+        }
+    }
+}
+/** `file://` directory URL to a plain fs path (browser URLs pass through). */
+function glueDirToFsPath(glueDir) {
+    if (!glueDir.startsWith("file://"))
+        return glueDir;
+    let p = decodeURIComponent(glueDir.slice("file://".length));
+    if (/^\/[A-Za-z]:\//.test(p))
+        p = p.slice(1); // Windows drive letter
+    return p;
+}
+function isNodeRuntime() {
+    const proc = globalThis
+        .process;
+    return typeof proc?.versions?.node === "string";
+}
+/**
+ * Runtime-only load of a `node:` builtin (e.g. `importNode("fs/promises")`).
+ * Uses `process.getBuiltinModule` (Node 22.3+/20.16+) so there is NO `import`
+ * syntax at all: bundlers with static analysis (webpack/vite/rollup, and
+ * Turbopack — the Next.js 16 default builder, which rejects both dynamic
+ * `` `node:${name}` `` requests and literal `import("node:*")` inside Edge
+ * graphs) have nothing to resolve or rewrite. Only the builtins actually
+ * used by this package are supported. All call sites are guarded to run on
+ * Node only; other runtimes never evaluate these branches. A `new Function`
+ * indirect-import fallback keeps older Node working without adding any
+ * statically analyzable import.
+ */
+export function importNode(name) {
+    if (name !== "fs/promises" && name !== "path" && name !== "module") {
+        throw new Error(`wasm-html-to-image: unsupported node builtin "${name}"`);
+    }
+    const proc = globalThis.process;
+    try {
+        const mod = proc?.getBuiltinModule?.(`node:${name}`);
+        if (mod)
+            return Promise.resolve(mod);
+    }
+    catch {
+        // fall through to the indirect dynamic import below
+    }
+    const indirect = new Function("s", "return import(s)");
+    return indirect(`node:${name}`);
+}
+/**
+ * Node-only: pre-read the sibling `.wasm` bytes. The web/worker-oriented
+ * glue has no `fs` reader, so `file://` fetching fails under Node; handing
+ * over `wasmBinary` bypasses fetching entirely. Browsers skip this (fetch
+ * works there). No static `node:` import keeps browser bundles clean.
+ */
+async function readWasmBinaryNode(glueDir) {
+    if (!isNodeRuntime())
+        return undefined;
+    try {
+        const fs = await importNode("fs/promises");
+        const data = await fs.readFile(glueDirToFsPath(glueDir) + "html-to-image.wasm");
+        return new Uint8Array(data);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Load and instantiate the unified module (cached per process, keyed by
+ * factory then moduleArg — see `moduleCache`).
+ * Works in Node (file URL import) and browsers (served URL import).
+ */
+export async function loadHtmlToImageModule(options = {}) {
+    const cacheKeyFactory = options.factory ?? undefined;
+    const cacheKeyModuleArg = options.moduleArg ?? undefined;
+    if (!options.noCache) {
+        const hit = moduleCache.get(cacheKeyFactory)?.get(cacheKeyModuleArg);
+        if (hit)
+            return hit;
+    }
+    let factory = options.factory;
+    let glueLabel = "(pre-bundled factory)";
+    let glueDir = "";
+    if (!factory) {
+        let glue = String(options.glueUrl ?? defaultGlueUrl());
+        let ns;
+        try {
+            ns = await importGlueModule(glue);
+        }
+        catch (e) {
+            if (options.glueUrl || !isModuleNotFound(e))
+                throw e;
+            // Dev-layout fallback: running from `src/` (tsx) while the glue
+            // lives in `../dist/` next to the compiled loader.
+            const fallback = String(new URL("../dist/html-to-image.js", import.meta.url));
+            try {
+                ns = await importGlueModule(fallback);
+            }
+            catch {
+                throw e; // report the original error
+            }
+            glue = fallback;
+        }
+        glueLabel = glue;
+        glueDir = glue.slice(0, glue.lastIndexOf("/") + 1);
+        factory = ns.default ?? ns.createHtmlToImageModule;
+    }
+    if (typeof factory !== "function") {
+        throw new Error(`wasm-html-to-image: no MODULARIZE factory in ${glueLabel} ` +
+            `(expected default export createHtmlToImageModule)`);
+    }
+    // Node-only: hand over pre-read `.wasm` bytes (factory path, e.g.
+    // workerd with `instantiateWasm`, is left untouched).
+    let moduleArg = options.moduleArg;
+    if (!options.factory && glueDir && moduleArg?.wasmBinary === undefined) {
+        const wasmBinary = await readWasmBinaryNode(glueDir);
+        if (wasmBinary)
+            moduleArg = { ...moduleArg, wasmBinary };
+    }
+    const module = await factory({
+        ...moduleArg,
+        locateFile: options.locateFile ??
+            moduleArg?.locateFile ??
+            ((path) => glueDir + path),
+    });
+    if (!options.noCache) {
+        let inner = moduleCache.get(cacheKeyFactory);
+        if (!inner) {
+            inner = new Map();
+            moduleCache.set(cacheKeyFactory, inner);
+        }
+        inner.set(cacheKeyModuleArg, module);
+    }
+    return module;
+}
+/** Drop all cached instances (tests / HMR). */
+export function dropCachedModule() {
+    moduleCache.clear();
+}

package/dist/preact.d.ts

@@ -0,0 +1,10 @@
+import { h, type VNode } from "preact";
+export { h };
+/**
+ * Converts a React element to a static HTML string.
+ * This is a thin wrapper around react-dom/server's renderToStaticMarkup.
+ *
+ * @param element - The React element to convert.
+ * @returns The resulting HTML string.
+ */
+export declare function toHtml(element: VNode): string;

package/dist/preact.js

@@ -0,0 +1,13 @@
+import { h } from "preact";
+import render from "preact-render-to-string";
+export { h };
+/**
+ * Converts a React element to a static HTML string.
+ * This is a thin wrapper around react-dom/server's renderToStaticMarkup.
+ *
+ * @param element - The React element to convert.
+ * @returns The resulting HTML string.
+ */
+export function toHtml(element) {
+    return render(element);
+}

package/dist/react.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from "react";
+/**
+ * Converts a React element to a static HTML string.
+ * This is a thin wrapper around react-dom/server's renderToStaticMarkup.
+ *
+ * @param element - The React element to convert.
+ * @returns The resulting HTML string.
+ */
+export declare function toHtml(element: ReactNode): string;

package/dist/react.js

@@ -0,0 +1,11 @@
+import { renderToStaticMarkup } from "react-dom/server";
+/**
+ * Converts a React element to a static HTML string.
+ * This is a thin wrapper around react-dom/server's renderToStaticMarkup.
+ *
+ * @param element - The React element to convert.
+ * @returns The resulting HTML string.
+ */
+export function toHtml(element) {
+    return renderToStaticMarkup(element);
+}

package/dist/single.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Single-WASM entry point.
+ *
+ * Loads the unified `html-to-image` module once (local `./loader.js`)
+ * and reuses the single connection for all calls.
+ * `render()` accepts HTML (`string` / `string[]` / URL) or image input
+ * (`Uint8Array` / `ArrayBuffer` / `data:image/` URL); image input skips
+ * rendering and goes straight to `converter_encode`.
+ */
+import { type HtmlToImageModule } from "./loader.js";
+import { type HtmlToImageOptions, type RenderResult } from "./core.js";
+import { isImageInput } from "./input.js";
+export type { OutputFormat, RenderOptions, HtmlToImageOptions, RenderResult, DiagnosticMessage, FontDiagnostic, RenderDiagnostics, RenderLimits, ResolveResourceHook, ResourceDiagnostic, } from "./core.js";
+export { DIAGNOSTIC_CODES, LogLevel, htmlToImage } from "./core.js";
+export { isImageInput };
+export type { HtmlToImageModule } from "./loader.js";
+export { dropCachedModule, loadHtmlToImageModule } from "./loader.js";
+/** Default connection: thin delegation to the loader-owned cache. */
+export declare function getDefaultModule(): Promise<HtmlToImageModule>;
+/**
+ * Render HTML — or convert an image — with the default single-WASM
+ * connection. Returns RenderResult containing data and metadata.
+ */
+export declare function render(options: HtmlToImageOptions & {
+    format: "svg";
+}): Promise<RenderResult<string>>;
+export declare function render(options: HtmlToImageOptions): Promise<RenderResult<Uint8Array | string>>;

package/dist/single.js

@@ -0,0 +1,22 @@
+/**
+ * Single-WASM entry point.
+ *
+ * Loads the unified `html-to-image` module once (local `./loader.js`)
+ * and reuses the single connection for all calls.
+ * `render()` accepts HTML (`string` / `string[]` / URL) or image input
+ * (`Uint8Array` / `ArrayBuffer` / `data:image/` URL); image input skips
+ * rendering and goes straight to `converter_encode`.
+ */
+import { loadHtmlToImageModule } from "./loader.js";
+import { htmlToImage, } from "./core.js";
+import { isImageInput } from "./input.js";
+export { DIAGNOSTIC_CODES, LogLevel, htmlToImage } from "./core.js";
+export { isImageInput };
+export { dropCachedModule, loadHtmlToImageModule } from "./loader.js";
+/** Default connection: thin delegation to the loader-owned cache. */
+export function getDefaultModule() {
+    return loadHtmlToImageModule();
+}
+export async function render(options) {
+    return htmlToImage(await getDefaultModule(), options);
+}

package/dist/tailwind.d.ts

@@ -0,0 +1 @@
+export declare const createCSS: (html: string) => Promise<string>;

package/dist/tailwind.js

@@ -0,0 +1,6 @@
+import { createGenerator } from "@unocss/core";
+import presetUno from "@unocss/preset-wind4";
+export const createCSS = async (html) => {
+    const uno = await createGenerator({ presets: [presetUno()] });
+    return uno.generate(html).then((v) => v.css);
+};

package/dist/wasm-payload.d.ts

@@ -0,0 +1,2 @@
+/** Decompress the embedded WASM payload and return the raw bytes. */
+export declare function loadCompressedWasmBinary(): Promise<Uint8Array>;

package/dist/wasm-payload.js

@@ -0,0 +1,39 @@
+/**
+ * Compressed embedded WASM payload.
+ *
+ * `scripts/compress-wasm.mjs` compresses `dist/html-to-image.wasm`
+ * (gzip vs brotli, smaller wins) and writes the base64 payload to
+ * `dist/html-to-image-wasm.js`. This loader restores the raw bytes at
+ * runtime via `DecompressionStream`, so the browser worker bundle embeds
+ * ~4MB instead of the 12MB SINGLE_FILE glue.
+ */
+// @ts-expect-error — dist/html-to-image-wasm.js is generated at build time
+import { wasmBase64, wasmEncoding } from "../dist/html-to-image-wasm.js";
+/** Decompress the embedded WASM payload and return the raw bytes. */
+export async function loadCompressedWasmBinary() {
+    const encoding = wasmEncoding;
+    try {
+        // gzip only: the W3C Compression Standard (DecompressionStream) has no
+        // "br" — see scripts/compress-wasm.mjs.
+        if (encoding !== "gzip") {
+            throw new Error(`unsupported wasmEncoding ${JSON.stringify(encoding)}`);
+        }
+        const bin = atob(wasmBase64);
+        const compressed = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            compressed[i] = bin.charCodeAt(i);
+        const stream = new Blob([compressed])
+            .stream()
+            .pipeThrough(new DecompressionStream(encoding));
+        const bytes = new Uint8Array(await new Response(stream).arrayBuffer());
+        if (bytes.length === 0) {
+            throw new Error("decompressed to 0 bytes");
+        }
+        return bytes;
+    }
+    catch (e) {
+        throw new Error(`wasm-html-to-image: failed to restore embedded WASM ` +
+            `(encoding=${JSON.stringify(encoding)}): ` +
+            (e instanceof Error ? e.message : String(e)));
+    }
+}