wasm-html-to-image 1.0.2 → 1.0.5

package/dist/input.d.ts

@@ -13,7 +13,7 @@ export declare function toBytes(data: Uint8Array | ArrayBuffer): Uint8Array;
  * Whether `value` is image input.
  *
  * - Binary (`Uint8Array` / `ArrayBuffer`): magic-byte sniffing for
- *   PNG/JPEG/WebP/GIF/AVIF/BMP. Unknown magic throws.
+ *   PNG/JPEG/WebP/GIF/AVIF/JXL/BMP. Unknown magic throws.
  * - `string`: `data:image/` prefix means image input; anything else is HTML.
  * - `string[]` (HTML vector) / `undefined`: not image input.
  */

package/dist/input.js

@@ -41,13 +41,23 @@ function sniffImageFormat(bytes) {
         return "avif";
     if (bytes.length >= 2 && bytes[0] === 0x42 && bytes[1] === 0x4d)
         return "bmp";
+    // JPEG XL: bare codestream (FF 0A) or ISO BMFF container signature box.
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0x0a)
+        return "jxl";
+    if (bytes.length >= 12 &&
+        bytes[0] === 0 &&
+        bytes[1] === 0 &&
+        bytes[2] === 0 &&
+        bytes[3] === 0x0c &&
+        ascii(bytes, 4, 8) === "JXL ")
+        return "jxl";
     return null;
 }
 /**
  * Whether `value` is image input.
  *
  * - Binary (`Uint8Array` / `ArrayBuffer`): magic-byte sniffing for
- *   PNG/JPEG/WebP/GIF/AVIF/BMP. Unknown magic throws.
+ *   PNG/JPEG/WebP/GIF/AVIF/JXL/BMP. Unknown magic throws.
  * - `string`: `data:image/` prefix means image input; anything else is HTML.
  * - `string[]` (HTML vector) / `undefined`: not image input.
  */

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/tailwind.d.ts

@@ -1 +1,38 @@
-export declare const createCSS: (html: string) => Promise<string>;
+/** Options shared by {@link createCSS}, {@link tailwind} and {@link convertTw}. */
+export interface TailwindOptions {
+    /**
+     * Extra stylesheet that may use Tailwind v4 `@theme { ... }` and `@apply`.
+     * It is converted like the `<style>` blocks of the HTML and appended to the result.
+     */
+    css?: string;
+    /** Called for problems that are skipped (unknown / unsupported `@apply` utilities). Defaults to `console.warn`. */
+    warn?: (message: string) => void;
+}
+/**
+ * Rewrite Tailwind v4 style `tw="..."` attributes into `class` (merged with an existing `class`).
+ * Comments, `<script>` and `<style>` contents are left untouched.
+ */
+export declare const convertTw: (html: string) => string;
+/**
+ * Generate the CSS for `html`: UnoCSS / Tailwind utilities for every class (and `tw`) token,
+ * plus Tailwind v4 `@theme` variables (`:root`) and `@apply` expansion for `<style>` blocks of
+ * `html` and for `options.css`.
+ *
+ * `tw="..."` attributes are not rewritten here: pass the HTML through {@link convertTw} (or use
+ * {@link tailwind}) so the elements actually carry the classes.
+ */
+export declare const createCSS: (html: string, options?: TailwindOptions) => Promise<string>;
+/**
+ * One call for Tailwind v4 style markup: `tw="..."` becomes `class`, and the returned `css` holds the
+ * utilities, `@theme` variables and `@apply` expansion. Feed both to `render()`.
+ *
+ * @example
+ * const { html, css } = await tailwind('<div tw="flex gap-2 bg-brand">…</div>', {
+ *   css: "@theme { --color-brand: #f00 }",
+ * });
+ * await render({ value: html, css, width: 600, format: "png" });
+ */
+export declare const tailwind: (html: string, options?: TailwindOptions) => Promise<{
+    html: string;
+    css: string;
+}>;

package/dist/tailwind.js

@@ -1,6 +1,190 @@
 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);
+const warnDefault = (message) => console.warn(message);
+// --- tw prop -> class ------------------------------------------------------
+const PROTECTED_BLOCKS = /<!--[\s\S]*?-->|<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi;
+const OPEN_TAG = /<([a-zA-Z][\w:-]*)((?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'<>=`]+))?)*)\s*(\/?)>/g;
+const ATTR = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'<>=`]+)))?/g;
+const escapeAttr = (value) => value.replace(/"/g, "&quot;");
+/**
+ * Rewrite Tailwind v4 style `tw="..."` attributes into `class` (merged with an existing `class`).
+ * Comments, `<script>` and `<style>` contents are left untouched.
+ */
+export const convertTw = (html) => {
+    const protectedParts = [];
+    const masked = html.replace(PROTECTED_BLOCKS, (block) => {
+        protectedParts.push(block);
+        return `\u0000${protectedParts.length - 1}\u0000`;
+    });
+    const converted = masked.replace(OPEN_TAG, (whole, name, attrs, selfClose) => {
+        if (!/\stw\b/i.test(attrs))
+            return whole;
+        let twValue = "";
+        let classValue;
+        const kept = [];
+        for (const m of attrs.matchAll(ATTR)) {
+            const attrName = m[1];
+            const value = m[2] ?? m[3] ?? m[4] ?? "";
+            const lower = attrName.toLowerCase();
+            if (lower === "tw") {
+                twValue = `${twValue} ${value}`.trim();
+            }
+            else if (lower === "class") {
+                classValue = `${classValue ?? ""} ${value}`.trim();
+            }
+            else {
+                kept.push(m[0]);
+            }
+        }
+        if (!twValue)
+            return whole;
+        const merged = `${classValue ?? ""} ${twValue}`.trim();
+        const rest = kept.length ? ` ${kept.join(" ")}` : "";
+        return `<${name}${rest} class="${escapeAttr(merged)}"${selfClose ? " /" : ""}>`;
+    });
+    return converted.replace(/\u0000(\d+)\u0000/g, (_, i) => protectedParts[Number(i)]);
+};
+// --- @theme / @apply -------------------------------------------------------
+/** Index of the `}` matching the `{` at `open`, or -1. */
+const matchBrace = (css, open) => {
+    let depth = 0;
+    for (let i = open; i < css.length; i++) {
+        const ch = css[i];
+        if (ch === "{")
+            depth++;
+        else if (ch === "}" && --depth === 0)
+            return i;
+    }
+    return -1;
+};
+/** Replace every `@theme { --x: v }` block by a `:root` rule carrying the same variables. */
+const extractTheme = (css) => {
+    const variables = {};
+    let out = "";
+    let pos = 0;
+    const re = /@theme\b[^{;]*\{/g;
+    for (let m = re.exec(css); m; m = re.exec(css)) {
+        const open = m.index + m[0].length - 1;
+        const close = matchBrace(css, open);
+        if (close < 0)
+            break;
+        const body = css.slice(open + 1, close);
+        const decls = [];
+        for (const d of body.matchAll(/(--[\w-]+)\s*:\s*([^;]+);?/g)) {
+            variables[d[1]] = d[2].trim();
+            decls.push(`${d[1]}:${d[2].trim()}`);
+        }
+        out += css.slice(pos, m.index);
+        out += decls.length ? `:root{${decls.join(";")}}` : "";
+        pos = close + 1;
+        re.lastIndex = pos;
+    }
+    return { css: out + css.slice(pos), variables };
+};
+/** `--color-brand-500` style theme variables as a UnoCSS `theme.colors` tree. */
+const themeColors = (variables) => {
+    const colors = {};
+    for (const [key, value] of Object.entries(variables)) {
+        const m = /^--color-([\w-]+)$/.exec(key);
+        if (!m)
+            continue;
+        const parts = m[1].split("-");
+        let node = colors;
+        for (const [i, part] of parts.entries()) {
+            const existing = node[part];
+            if (i === parts.length - 1) {
+                // `--color-brand` and `--color-brand-500` coexist as brand.DEFAULT + brand[500].
+                if (existing && typeof existing === "object")
+                    existing.DEFAULT = value;
+                else
+                    node[part] = value;
+            }
+            else if (existing && typeof existing === "object") {
+                node = existing;
+            }
+            else {
+                const next = typeof existing === "string" ? { DEFAULT: existing } : {};
+                node[part] = next;
+                node = next;
+            }
+        }
+    }
+    return colors;
+};
+const APPLY = /@apply\s+([^;}]+?)\s*(;|(?=}))/g;
+const applyTokens = (css) => {
+    const tokens = [];
+    for (const m of css.matchAll(APPLY))
+        tokens.push(...m[1].split(/\s+/));
+    return tokens.filter(Boolean);
+};
+const expandApply = async (css, uno, warn) => {
+    const cache = new Map();
+    for (const token of new Set(applyTokens(css))) {
+        const parsed = await uno.parseToken(token);
+        // Only plain utilities (`.token { ... }`) can be inlined into another rule.
+        const plain = parsed?.filter((u) => !u[3] && u[1] && u[1].replace(/\\/g, "") === `.${token}`);
+        if (!plain || plain.length === 0) {
+            warn(`@apply: cannot resolve utility "${token}"; ignored.`);
+            continue;
+        }
+        cache.set(token, plain.map((u) => u[2].trim().replace(/;+$/, "")).join(";"));
+    }
+    return css.replace(APPLY, (_, list, end) => {
+        const body = list
+            .split(/\s+/)
+            .filter(Boolean)
+            .map((token) => cache.get(token))
+            .filter(Boolean)
+            .join(";");
+        return body ? `${body}${end === ";" ? ";" : ""}` : "";
+    });
+};
+const STYLE_BLOCK = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi;
+const needsTailwindCss = (css) => /@theme\b|@apply\b/.test(css);
+/**
+ * Generate the CSS for `html`: UnoCSS / Tailwind utilities for every class (and `tw`) token,
+ * plus Tailwind v4 `@theme` variables (`:root`) and `@apply` expansion for `<style>` blocks of
+ * `html` and for `options.css`.
+ *
+ * `tw="..."` attributes are not rewritten here: pass the HTML through {@link convertTw} (or use
+ * {@link tailwind}) so the elements actually carry the classes.
+ */
+export const createCSS = async (html, options = {}) => {
+    const warn = options.warn ?? warnDefault;
+    const userBlocks = [];
+    for (const m of html.matchAll(STYLE_BLOCK)) {
+        if (needsTailwindCss(m[1]))
+            userBlocks.push(m[1]);
+    }
+    if (options.css)
+        userBlocks.push(options.css);
+    // Theme tokens feed UnoCSS' theme (colors) so utilities such as `bg-brand` resolve.
+    const themed = userBlocks.map((css) => extractTheme(css));
+    const variables = Object.assign({}, ...themed.map((t) => t.variables));
+    const uno = await createGenerator({
+        presets: [presetUno()],
+        theme: { colors: themeColors(variables) },
+    });
+    const extraTokens = userBlocks.flatMap(applyTokens).join(" ");
+    const utilities = (await uno.generate(`${html}\n${extraTokens}`)).css;
+    const converted = [];
+    for (const t of themed) {
+        converted.push(await expandApply(t.css, uno, warn));
+    }
+    return [utilities, ...converted.filter((css) => css.trim())].join("\n");
+};
+/**
+ * One call for Tailwind v4 style markup: `tw="..."` becomes `class`, and the returned `css` holds the
+ * utilities, `@theme` variables and `@apply` expansion. Feed both to `render()`.
+ *
+ * @example
+ * const { html, css } = await tailwind('<div tw="flex gap-2 bg-brand">…</div>', {
+ *   css: "@theme { --color-brand: #f00 }",
+ * });
+ * await render({ value: html, css, width: 600, format: "png" });
+ */
+export const tailwind = async (html, options = {}) => {
+    const converted = convertTw(html);
+    return { html: converted, css: await createCSS(converted, options) };
 };

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;