wasm-html-to-image 1.0.2 → 1.0.3

package/dist/loader.d.ts

@@ -85,7 +85,19 @@ export interface HtmlToImageModule {
      * Returns false on failure. Probed at runtime; PNG path is the fallback.
      */
     satoru_render_to_converter?: (...args: unknown[]) => boolean;
-    /** Image encode wrapper (positional: instance, format, quality, speed, animation). */
+    /**
+     * Animated (opacity / transform / color) HTML render into a converter's
+     * frames, additive: `(satoruInst, converterInst, htmls, width, height,
+     * options, durationMs, fps)`. Frames come from `@keyframes` + `animation` in
+     * the document (loop infinite); returns the number of frames appended
+     * (0 on failure).
+     */
+    satoru_render_animation_to_converter?: (...args: unknown[]) => number;
+    /**
+     * Image encode wrapper (positional: instance, format, quality, speed,
+     * animation, animationLoop). `animationLoop` is the animated WebP loop
+     * count (0 = infinite, the default).
+     */
     converter_encode?: (...args: unknown[]) => unknown;
     /**
      * Unified Bitmap-direct call (`render_bitmap_to_encoded` exposed to JS,
@@ -115,6 +127,13 @@ export interface LoadOptions {
     /** Bypass the process-wide cache (tests). */
     noCache?: boolean;
 }
+/**
+ * A failure that is likely to disappear on a second attempt (the `.wasm`
+ * was read while it was still being written).
+ */
+export declare class TransientWasmError extends Error {
+    constructor(message: string);
+}
 /** Default glue URL: `./html-to-image.js` next to the compiled loader. */
 export declare function defaultGlueUrl(): URL;
 /**
@@ -134,6 +153,10 @@ export declare function importNode<T = unknown>(name: string): Promise<T>;
  * 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).
+ *
+ * Parallel calls with the same key share one instantiation (see
+ * {@link pendingLoads}); a failed load is not cached, so a later call
+ * retries.
  */
 export declare function loadHtmlToImageModule(options?: LoadOptions): Promise<HtmlToImageModule>;
 /** Drop all cached instances (tests / HMR). */
@@ -143,8 +166,13 @@ export declare function dropCachedModule(): void;
  * Shared adapter for workerd / edge-light entry points (behavior unchanged:
  * `WebAssembly.instantiate` + success-callback override, empty object return
  * for emscripten). The `label` only selects the console-error prefix.
+ *
+ * `onFailure` (optional) is notified when the instantiation fails. The
+ * emscripten glue only offers a success callback, so without it a failed
+ * instantiation leaves the module promise pending forever; the caller uses
+ * this hook to turn the failure into a rejected promise.
  */
-export declare function precompiledModuleArg(wasm: WebAssembly.Module, label: string): EmscriptenModuleArg;
+export declare function precompiledModuleArg(wasm: WebAssembly.Module, label: string, onFailure?: (e: unknown) => void): EmscriptenModuleArg;
 /**
  * Load (and reuse) the unified module for a pre-compiled `WebAssembly.Module`.
  * Per-`wasm` cache with failure eviction (a second call with a different

package/dist/loader.js

@@ -19,6 +19,7 @@
  * file URL, then invoking the factory. No `node:` builtins are used so the
  * same file works in both runtimes.
  */
+import { checkWasmBinary } from "./wasm-binary.js";
 /**
  * Process-wide module cache, keyed by factory then moduleArg: different
  * factories, or different WASM payloads (e.g. workerd/edge-light calls
@@ -27,6 +28,37 @@
  * single.ts default path, `*-workers` lazy vars) are unaffected.
  */
 const moduleCache = new Map();
+/**
+ * In-flight loads, keyed like {@link moduleCache} (factory then moduleArg).
+ *
+ * The resolved-module cache only helps *after* the first load finished, so
+ * N parallel calls (a worker pool starting up, a burst of requests) each
+ * instantiated their own copy of the module — a 12 MB binary plus its
+ * linear memory, N times over. Sharing the pending promise makes parallel
+ * initialization instantiate exactly once.
+ */
+const pendingLoads = new Map();
+/**
+ * How many times a load is attempted before the error is reported.
+ *
+ * A truncated `.wasm` (read while a concurrent build was still writing it)
+ * is transient: re-reading the file a moment later usually yields the
+ * complete binary. Two attempts are enough to cover that window without
+ * hiding a real failure.
+ */
+const LOAD_ATTEMPTS = 2;
+/** Delay before the retry of a transient (truncated binary) failure. */
+const LOAD_RETRY_DELAY_MS = 150;
+/**
+ * A failure that is likely to disappear on a second attempt (the `.wasm`
+ * was read while it was still being written).
+ */
+export class TransientWasmError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TransientWasmError";
+    }
+}
 /** 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);
@@ -129,6 +161,10 @@ async function readWasmBinaryNode(glueDir) {
  * 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).
+ *
+ * Parallel calls with the same key share one instantiation (see
+ * {@link pendingLoads}); a failed load is not cached, so a later call
+ * retries.
  */
 export async function loadHtmlToImageModule(options = {}) {
     const cacheKeyFactory = options.factory ?? undefined;
@@ -137,7 +173,80 @@ export async function loadHtmlToImageModule(options = {}) {
         const hit = moduleCache.get(cacheKeyFactory)?.get(cacheKeyModuleArg);
         if (hit)
             return hit;
+        // A load is already running for this key: share it instead of
+        // instantiating a second copy of the module.
+        const pending = pendingLoads.get(cacheKeyFactory)?.get(cacheKeyModuleArg);
+        if (pending)
+            return pending;
     }
+    const promise = loadHtmlToImageModuleOnce(options, cacheKeyFactory, cacheKeyModuleArg);
+    if (!options.noCache) {
+        let inner = pendingLoads.get(cacheKeyFactory);
+        if (!inner) {
+            inner = new Map();
+            pendingLoads.set(cacheKeyFactory, inner);
+        }
+        inner.set(cacheKeyModuleArg, promise);
+        // A rejected load must not poison the cache: drop it so a later call
+        // retries (a truncated `.wasm` may be complete by then).
+        promise.catch(() => {
+            if (inner?.get(cacheKeyModuleArg) === promise) {
+                inner.delete(cacheKeyModuleArg);
+            }
+        });
+    }
+    return promise;
+}
+/**
+ * Load the module, retrying once when the failure is transient (the
+ * `.wasm` was read while it was still being written).
+ */
+async function loadHtmlToImageModuleOnce(options, cacheKeyFactory, cacheKeyModuleArg) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await loadHtmlToImageModuleUncached(options, cacheKeyFactory, cacheKeyModuleArg);
+        }
+        catch (e) {
+            if (attempt >= LOAD_ATTEMPTS || !isTransientWasmFailure(e)) {
+                throw e;
+            }
+            await new Promise((r) => setTimeout(r, LOAD_RETRY_DELAY_MS));
+        }
+    }
+}
+/**
+ * True when the failure looks like a corrupt/truncated binary (retryable).
+ *
+ * The engine reports a truncated module as `CompileError`; the emscripten
+ * glue wraps it into `RuntimeError("Aborted(CompileError: ...)")`, so the
+ * message is inspected as well.
+ */
+function isTransientWasmFailure(e) {
+    if (e instanceof TransientWasmError)
+        return true;
+    if (typeof WebAssembly !== "undefined" && e instanceof WebAssembly.CompileError)
+        return true;
+    const message = e instanceof Error ? e.message : String(e);
+    return /CompileError/.test(message);
+}
+/**
+ * Explain a load failure in terms of the artifact that is actually broken:
+ * a truncated `.wasm` (read while a build was writing it) or a
+ * glue/binary mismatch (the two come from different builds).
+ */
+function explainWasmLoadFailure(e, glueLabel) {
+    const message = e instanceof Error ? e.message : String(e);
+    if (/Import #\d+/.test(message)) {
+        return new Error(`wasm-html-to-image: the WebAssembly binary and the JavaScript ` +
+            `glue do not match (${message}). The artifacts in ${glueLabel} ` +
+            `are probably from different builds - rebuild the glue and the ` +
+            `.wasm together.`, { cause: e });
+    }
+    if (e instanceof Error)
+        return e;
+    return new Error(message);
+}
+async function loadHtmlToImageModuleUncached(options, cacheKeyFactory, cacheKeyModuleArg) {
     let factory = options.factory;
     let glueLabel = "(pre-bundled factory)";
     let glueDir = "";
@@ -173,16 +282,51 @@ export async function loadHtmlToImageModule(options = {}) {
     // workerd with `instantiateWasm`, is left untouched).
     let moduleArg = options.moduleArg;
     if (!options.factory && glueDir && moduleArg?.wasmBinary === undefined) {
+        const wasmPath = glueDirToFsPath(glueDir) + "html-to-image.wasm";
         const wasmBinary = await readWasmBinaryNode(glueDir);
-        if (wasmBinary)
+        if (wasmBinary) {
+            // A file that is still being written yields a truncated binary and
+            // a cryptic `section Data extends past end` deep inside the engine.
+            const check = checkWasmBinary(wasmBinary);
+            if (!check.ok) {
+                throw new TransientWasmError(`wasm-html-to-image: invalid WebAssembly binary at ${wasmPath}: ` +
+                    `${check.reason} - the file was probably read while it was ` +
+                    `still being written (concurrent build); retry once the ` +
+                    `build finished.`);
+            }
             moduleArg = { ...moduleArg, wasmBinary };
+        }
+        else if (isNodeRuntime()) {
+            throw new TransientWasmError(`wasm-html-to-image: cannot read the WebAssembly binary at ` +
+                `${wasmPath}`);
+        }
+    }
+    const provided = moduleArg?.wasmBinary;
+    const providedBytes = provided instanceof Uint8Array
+        ? provided
+        : provided instanceof ArrayBuffer
+            ? new Uint8Array(provided)
+            : undefined;
+    if (providedBytes) {
+        // Caller-supplied bytes (browser worker payload, edge runtimes) get
+        // the same structural check.
+        const check = checkWasmBinary(providedBytes);
+        if (!check.ok) {
+            throw new TransientWasmError(`wasm-html-to-image: invalid WebAssembly binary: ${check.reason}`);
+        }
+    }
+    let module;
+    try {
+        module = await factory({
+            ...moduleArg,
+            locateFile: options.locateFile ??
+                moduleArg?.locateFile ??
+                ((path) => glueDir + path),
+        });
+    }
+    catch (e) {
+        throw explainWasmLoadFailure(e, glueLabel);
     }
-    const module = await factory({
-        ...moduleArg,
-        locateFile: options.locateFile ??
-            moduleArg?.locateFile ??
-            ((path) => glueDir + path),
-    });
     if (!options.noCache) {
         let inner = moduleCache.get(cacheKeyFactory);
         if (!inner) {
@@ -196,14 +340,20 @@ export async function loadHtmlToImageModule(options = {}) {
 /** Drop all cached instances (tests / HMR). */
 export function dropCachedModule() {
     moduleCache.clear();
+    pendingLoads.clear();
 }
 /**
  * Build Emscripten module args for a pre-compiled `WebAssembly.Module`.
  * Shared adapter for workerd / edge-light entry points (behavior unchanged:
  * `WebAssembly.instantiate` + success-callback override, empty object return
  * for emscripten). The `label` only selects the console-error prefix.
+ *
+ * `onFailure` (optional) is notified when the instantiation fails. The
+ * emscripten glue only offers a success callback, so without it a failed
+ * instantiation leaves the module promise pending forever; the caller uses
+ * this hook to turn the failure into a rejected promise.
  */
-export function precompiledModuleArg(wasm, label) {
+export function precompiledModuleArg(wasm, label, onFailure) {
     return {
         instantiateWasm: (imports, successCallback) => {
             WebAssembly.instantiate(wasm, imports)
@@ -212,6 +362,7 @@ export function precompiledModuleArg(wasm, label) {
             })
                 .catch((e) => {
                 console.error(`wasm-html-to-image [${label}]: Wasm instantiation failed:`, e);
+                onFailure?.(e);
             });
             return {}; // Return empty object as emscripten expects
         },
@@ -227,10 +378,20 @@ export function precompiledModuleArg(wasm, label) {
 export async function loadPrecompiledModule(factory, wasm, cache, label) {
     let pending = cache.get(wasm);
     if (!pending) {
-        pending = loadHtmlToImageModule({
-            factory,
-            moduleArg: precompiledModuleArg(wasm, label),
+        // The glue only reports instantiation failures through the console,
+        // so the failure is mirrored into a rejected promise: otherwise the
+        // module promise never settles and the caller waits forever.
+        let reportFailure = () => { };
+        const failure = new Promise((_resolve, reject) => {
+            reportFailure = reject;
         });
+        pending = Promise.race([
+            loadHtmlToImageModule({
+                factory,
+                moduleArg: precompiledModuleArg(wasm, label, reportFailure),
+            }),
+            failure,
+        ]);
         cache.set(wasm, pending);
         pending.catch(() => {
             if (cache.get(wasm) === pending)

package/dist/wasm-binary.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal WASM binary sanity check.
+ *
+ * The loader hands the `.wasm` bytes straight to the engine, so a file
+ * that is still being written (concurrent build) or that belongs to a
+ * different build than the JavaScript glue fails deep inside V8 with
+ * messages that do not point at the real cause:
+ *
+ * - `CompileError: section Data extends past end` — the file was read
+ *   while it was still being written (truncated binary).
+ * - `Import #0 "env" is not an object` — the binary and the glue come
+ *   from different builds (the import namespace does not match).
+ *
+ * {@link checkWasmBinary} detects the truncated case before the engine
+ * sees it and reports the import namespaces, so the loader can explain
+ * a mismatch instead of surfacing a cryptic engine error.
+ */
+/** Result of {@link checkWasmBinary}. */
+export interface WasmBinaryCheck {
+    /** True when the bytes are a structurally complete WASM binary. */
+    ok: boolean;
+    /** Why the check failed (only set when `ok` is false). */
+    reason?: string;
+    /** Import namespaces (module names) the binary requires. */
+    namespaces: string[];
+}
+/**
+ * Check that `bytes` is a structurally complete WASM binary.
+ *
+ * Walks the section table: a truncated file (the classic symptom of
+ * reading a file that is still being written) shows up as a section
+ * whose declared length runs past the end of the buffer.
+ */
+export declare function checkWasmBinary(bytes: Uint8Array): WasmBinaryCheck;

package/dist/wasm-binary.js

@@ -0,0 +1,210 @@
+/**
+ * Minimal WASM binary sanity check.
+ *
+ * The loader hands the `.wasm` bytes straight to the engine, so a file
+ * that is still being written (concurrent build) or that belongs to a
+ * different build than the JavaScript glue fails deep inside V8 with
+ * messages that do not point at the real cause:
+ *
+ * - `CompileError: section Data extends past end` — the file was read
+ *   while it was still being written (truncated binary).
+ * - `Import #0 "env" is not an object` — the binary and the glue come
+ *   from different builds (the import namespace does not match).
+ *
+ * {@link checkWasmBinary} detects the truncated case before the engine
+ * sees it and reports the import namespaces, so the loader can explain
+ * a mismatch instead of surfacing a cryptic engine error.
+ */
+/** WASM magic header (`\0asm`). */
+const WASM_MAGIC = [0x00, 0x61, 0x73, 0x6d];
+/** Section id of the import section. */
+const SECTION_IMPORT = 2;
+/** Human-readable section names (for the failure reason). */
+const SECTION_NAMES = {
+    0: "Custom",
+    1: "Type",
+    2: "Import",
+    3: "Function",
+    4: "Table",
+    5: "Memory",
+    6: "Global",
+    7: "Export",
+    8: "Start",
+    9: "Element",
+    10: "Code",
+    11: "Data",
+    12: "DataCount",
+    13: "Tag",
+};
+/** Read an unsigned LEB128 value; returns `null` when malformed. */
+function readU32Leb(bytes, offset) {
+    let result = 0;
+    let shift = 0;
+    let pos = offset;
+    for (;;) {
+        if (pos >= bytes.length)
+            return null;
+        const byte = bytes[pos++];
+        result += (byte & 0x7f) * 2 ** shift;
+        if ((byte & 0x80) === 0)
+            break;
+        shift += 7;
+        if (shift > 35)
+            return null; // malformed / truncated
+    }
+    return { value: result, next: pos };
+}
+/** Read a length-prefixed name; returns `null` when malformed. */
+function readName(bytes, offset) {
+    const len = readU32Leb(bytes, offset);
+    if (!len)
+        return null;
+    const start = len.next;
+    const end = start + len.value;
+    if (end > bytes.length)
+        return null;
+    let name = "";
+    for (let i = start; i < end; i++)
+        name += String.fromCharCode(bytes[i]);
+    return { value: name, next: end };
+}
+/**
+ * Collect the import namespaces (module names) of an import section.
+ * Malformed input simply yields no namespaces (the caller reports the
+ * structural problem separately).
+ */
+function collectImportNamespaces(section, namespaces) {
+    const count = readU32Leb(section, 0);
+    if (!count)
+        return;
+    let off = count.next;
+    for (let i = 0; i < count.value; i++) {
+        const mod = readName(section, off);
+        if (!mod)
+            return;
+        const field = readName(section, mod.next);
+        if (!field)
+            return;
+        off = field.next;
+        const kind = section[off++];
+        if (kind === undefined)
+            return;
+        // Skip the kind-specific descriptor.
+        if (kind === 0) {
+            const typeIdx = readU32Leb(section, off);
+            if (!typeIdx)
+                return;
+            off = typeIdx.next;
+        }
+        else if (kind === 1) {
+            off += 1; // element type
+            const flags = section[off++];
+            if (flags === undefined)
+                return;
+            const min = readU32Leb(section, off);
+            if (!min)
+                return;
+            off = min.next;
+            if (flags & 0x01) {
+                const max = readU32Leb(section, off);
+                if (!max)
+                    return;
+                off = max.next;
+            }
+        }
+        else if (kind === 2) {
+            const flags = section[off++];
+            if (flags === undefined)
+                return;
+            const min = readU32Leb(section, off);
+            if (!min)
+                return;
+            off = min.next;
+            if (flags & 0x01) {
+                const max = readU32Leb(section, off);
+                if (!max)
+                    return;
+                off = max.next;
+            }
+        }
+        else if (kind === 3) {
+            off += 2; // value type + mutability
+        }
+        else if (kind === 4) {
+            const attr = section[off++];
+            if (attr === undefined)
+                return;
+            const typeIdx = readU32Leb(section, off);
+            if (!typeIdx)
+                return;
+            off = typeIdx.next;
+        }
+        else {
+            return; // unknown kind: stop parsing
+        }
+        if (!namespaces.includes(mod.value))
+            namespaces.push(mod.value);
+    }
+}
+/**
+ * Check that `bytes` is a structurally complete WASM binary.
+ *
+ * Walks the section table: a truncated file (the classic symptom of
+ * reading a file that is still being written) shows up as a section
+ * whose declared length runs past the end of the buffer.
+ */
+export function checkWasmBinary(bytes) {
+    const namespaces = [];
+    if (bytes.length < 8) {
+        return {
+            ok: false,
+            reason: `too short to be a WebAssembly binary (${bytes.length} bytes)`,
+            namespaces,
+        };
+    }
+    for (let i = 0; i < WASM_MAGIC.length; i++) {
+        if (bytes[i] !== WASM_MAGIC[i]) {
+            return {
+                ok: false,
+                reason: "not a WebAssembly binary (bad magic header)",
+                namespaces,
+            };
+        }
+    }
+    const version = bytes[4] | (bytes[5] << 8) | (bytes[6] << 16) | (bytes[7] << 24);
+    if (version !== 1) {
+        return {
+            ok: false,
+            reason: `unsupported WebAssembly version ${version >>> 0}`,
+            namespaces,
+        };
+    }
+    let off = 8;
+    while (off < bytes.length) {
+        const id = bytes[off++];
+        const size = readU32Leb(bytes, off);
+        if (!size) {
+            return {
+                ok: false,
+                reason: "malformed section header (truncated binary)",
+                namespaces,
+            };
+        }
+        off = size.next;
+        const end = off + size.value;
+        if (end > bytes.length) {
+            const name = SECTION_NAMES[id] ?? `#${id}`;
+            return {
+                ok: false,
+                reason: `section ${name} extends past end of the module ` +
+                    `(length ${size.value}, remaining bytes ${bytes.length - off})`,
+                namespaces,
+            };
+        }
+        if (id === SECTION_IMPORT) {
+            collectImportNamespaces(bytes.subarray(off, end), namespaces);
+        }
+        off = end;
+    }
+    return { ok: true, namespaces };
+}

package/dist/wasm-payload.js

@@ -9,6 +9,7 @@
  */
 // @ts-expect-error — dist/html-to-image-wasm.js is generated at build time
 import { wasmBase64, wasmEncoding } from "../dist/html-to-image-wasm.js";
+import { checkWasmBinary } from "./wasm-binary.js";
 /** Decompress the embedded WASM payload and return the raw bytes. */
 export async function loadCompressedWasmBinary() {
     const encoding = wasmEncoding;
@@ -29,6 +30,13 @@ export async function loadCompressedWasmBinary() {
         if (bytes.length === 0) {
             throw new Error("decompressed to 0 bytes");
         }
+        // A payload captured from a half-written `.wasm` decompresses fine but
+        // is not a complete module: reject it here instead of letting the
+        // engine fail with `section Data extends past end`.
+        const check = checkWasmBinary(bytes);
+        if (!check.ok) {
+            throw new Error(`restored payload is not a complete module: ${check.reason}`);
+        }
         return bytes;
     }
     catch (e) {