wasm-html-to-image 0.1.0

package/dist/diagnostics.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Playground-parity diagnostics (satoru-compatible shapes).
+ *
+ * `LogLevel` mirrors `satoru/log-level.ts` verbatim (numeric levels shared
+ * with the WASM `set_log_level` binding). `RenderDiagnostics` mirrors
+ * satoru's `RenderDiagnostics` so playground-style consumers can switch
+ * imports without reshaping reports.
+ */
+/** Log severity, shared with the WASM `set_log_level` binding. */
+export declare enum LogLevel {
+    None = 0,
+    Error = 1,
+    Warning = 2,
+    Info = 3,
+    Debug = 4
+}
+/** Status of a single discovered resource. */
+export interface ResourceDiagnostic {
+    type: "font" | "css" | "image";
+    url: string;
+    name?: string;
+    status: "pending" | "loaded" | "failed" | "skipped";
+    bytes?: number;
+    reason?: string;
+}
+/**
+ * Font record (best effort, JS-side only).
+ * NOTE: per-glyph C++ diagnostics (`get_font_diagnostics`) have no binding
+ * in this build (see `src/cpp/main.cpp`), so entries describe fonts this
+ * layer loaded (option preloads, fetched font resources) rather than the
+ * renderer's matched faces.
+ */
+export interface FontDiagnostic {
+    family: string;
+    weight?: number;
+    style?: "normal" | "italic" | "oblique";
+    status: "loaded" | "fallback" | "missing";
+    source?: string;
+    characters?: string;
+}
+/** A warning/error entry in the diagnostics report. */
+export interface DiagnosticMessage {
+    code: string;
+    message: string;
+    source?: string;
+}
+/** Full render diagnostics report (satoru-compatible). */
+export interface RenderDiagnostics {
+    version: 1;
+    format: "svg" | "png" | "webp" | "pdf";
+    width: number;
+    height?: number;
+    mediaType: "screen" | "print";
+    timings: Record<string, number>;
+    resources: ResourceDiagnostic[];
+    fonts: FontDiagnostic[];
+    warnings: DiagnosticMessage[];
+    errors: DiagnosticMessage[];
+}
+/** Machine-readable diagnostic codes (satoru parity). */
+export declare const DIAGNOSTIC_CODES: {
+    readonly LIMIT_TIMEOUT: "LIMIT_TIMEOUT";
+    readonly LIMIT_RESOURCE_SIZE: "LIMIT_RESOURCE_SIZE";
+    readonly LIMIT_TOTAL_SIZE: "LIMIT_TOTAL_SIZE";
+    readonly LIMIT_RESOURCE_COUNT: "LIMIT_RESOURCE_COUNT";
+    readonly LIMIT_PROTOCOL_BLOCKED: "LIMIT_PROTOCOL_BLOCKED";
+    readonly LIMIT_HOST_BLOCKED: "LIMIT_HOST_BLOCKED";
+    /** Extension: a resource fetch (or resolveResource hook) failed. */
+    readonly RESOURCE_FETCH_FAILED: "RESOURCE_FETCH_FAILED";
+};
+/** Safety/performance limits, enforced in JS around resource resolution. */
+export interface RenderLimits {
+    /** Timeout for the whole render in milliseconds. */
+    timeoutMs?: number;
+    /** Maximum bytes for a single resource. */
+    maxResourceBytes?: number;
+    /** Maximum total bytes for all resources. */
+    maxTotalResourceBytes?: number;
+    /** Maximum number of resources to load. */
+    maxResourceCount?: number;
+    /** Allowed URL protocols (e.g. `["http:", "https:"]`). */
+    allowedProtocols?: string[];
+    /** Allowed hostnames. */
+    allowedHosts?: string[];
+    /** Blocked hostnames. */
+    blockedHosts?: string[];
+}
+/**
+ * Override hook for resource resolution. Receives the absolute (or
+ * baseUrl-relative) URL and a fallback that runs the built-in resolution;
+ * return bytes to inject, or `null` to skip the resource.
+ */
+export type ResolveResourceHook = (url: string, fallback: () => Promise<Uint8Array | null>) => Promise<Uint8Array | null>;

package/dist/diagnostics.js

@@ -0,0 +1,28 @@
+/**
+ * Playground-parity diagnostics (satoru-compatible shapes).
+ *
+ * `LogLevel` mirrors `satoru/log-level.ts` verbatim (numeric levels shared
+ * with the WASM `set_log_level` binding). `RenderDiagnostics` mirrors
+ * satoru's `RenderDiagnostics` so playground-style consumers can switch
+ * imports without reshaping reports.
+ */
+/** Log severity, shared with the WASM `set_log_level` binding. */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["None"] = 0] = "None";
+    LogLevel[LogLevel["Error"] = 1] = "Error";
+    LogLevel[LogLevel["Warning"] = 2] = "Warning";
+    LogLevel[LogLevel["Info"] = 3] = "Info";
+    LogLevel[LogLevel["Debug"] = 4] = "Debug";
+})(LogLevel || (LogLevel = {}));
+/** Machine-readable diagnostic codes (satoru parity). */
+export const DIAGNOSTIC_CODES = {
+    LIMIT_TIMEOUT: "LIMIT_TIMEOUT",
+    LIMIT_RESOURCE_SIZE: "LIMIT_RESOURCE_SIZE",
+    LIMIT_TOTAL_SIZE: "LIMIT_TOTAL_SIZE",
+    LIMIT_RESOURCE_COUNT: "LIMIT_RESOURCE_COUNT",
+    LIMIT_PROTOCOL_BLOCKED: "LIMIT_PROTOCOL_BLOCKED",
+    LIMIT_HOST_BLOCKED: "LIMIT_HOST_BLOCKED",
+    /** Extension: a resource fetch (or resolveResource hook) failed. */
+    RESOURCE_FETCH_FAILED: "RESOURCE_FETCH_FAILED",
+};

package/dist/edge-light.d.ts

@@ -0,0 +1,18 @@
+import { type HtmlToImageModule } from "./loader.js";
+import { type HtmlToImageOptions, type RenderResult } from "./core.js";
+export type { OutputFormat, RenderOptions, HtmlToImageOptions, RenderResult, DiagnosticMessage, FontDiagnostic, RenderDiagnostics, RenderLimits, ResolveResourceHook, ResourceDiagnostic, } from "./core.js";
+export { DIAGNOSTIC_CODES, LogLevel } from "./core.js";
+export type { HtmlToImageModule, EmscriptenModuleArg, LoadOptions, WasmInstancePtr, CreateHtmlToImageModule, } from "./loader.js";
+/**
+ * Load (and reuse) the unified module for a pre-compiled `WebAssembly.Module`.
+ * @param wasm The compiled WASM module (always required — no bundled default)
+ */
+export declare function getDefaultModule(wasm: WebAssembly.Module): Promise<HtmlToImageModule>;
+/**
+ * Render HTML — or convert an image — on an edge runtime.
+ * Returns RenderResult containing data and metadata.
+ */
+export declare function render(options: HtmlToImageOptions & {
+    format: "svg";
+}, wasm: WebAssembly.Module): Promise<RenderResult<string>>;
+export declare function render(options: HtmlToImageOptions, wasm: WebAssembly.Module): Promise<RenderResult<Uint8Array | string>>;

package/dist/edge-light.js

@@ -0,0 +1,70 @@
+/**
+ * Edge-light entry point (Next.js Edge runtime, Vercel edge-light).
+ *
+ * Same engine as `./workerd.js`, but with NO static `.wasm` import:
+ * bundlers outside workerd (notably Next.js edge-server compilation) cannot
+ * resolve a bare `import wasm from "../dist/html-to-image.wasm"`, so that
+ * line would force consumers to add a dedicated `asset/resource` rule.
+ * Here the caller always supplies a pre-compiled `WebAssembly.Module`
+ * (e.g. compiled from bytes served over HTTP), and instantiation is
+ * overridden via `instantiateWasm` exactly like `./workerd.js`.
+ *
+ * Runtime separation is done in `package.json` `exports` conditions:
+ * - `workerd` (Cloudflare) -> `./workerd.js` (static `.wasm` import)
+ * - `edge-light` (Next.js Edge) -> `./edge-light.js` (this file)
+ * The two conditions never overlap (verified against Next.js 15
+ * `edgeConditionNames` and wrangler/miniflare build conditions), and
+ * `edge-light` is listed before any `browser` key so Edge resolution wins.
+ *
+ * ```ts
+ * import { render } from "wasm-html-to-image/workerd"; // edge-light resolves here on Edge
+ * const wasm = await WebAssembly.compile(await (await fetch(wasmUrl)).arrayBuffer());
+ * const png = await render({ value: "<h1>hi</h1>", width: 800, format: "png" }, wasm);
+ * ```
+ */
+// @ts-expect-error — dist/html-to-image.js is generated at build time
+import createHtmlToImageModule from "./html-to-image.js";
+import { loadHtmlToImageModule, } from "./loader.js";
+import { htmlToImage, } from "./core.js";
+export { DIAGNOSTIC_CODES, LogLevel } from "./core.js";
+/** Build the Emscripten module args overriding WASM instantiation. */
+function edgeModuleArg(wasm) {
+    return {
+        instantiateWasm: (imports, successCallback) => {
+            WebAssembly.instantiate(wasm, imports)
+                .then((instance) => {
+                successCallback(instance, wasm);
+            })
+                .catch((e) => {
+                console.error("wasm-html-to-image [edge-light]: Wasm instantiation failed:", e);
+            });
+            return {}; // Return empty object as emscripten expects
+        },
+    };
+}
+/** Module instances keyed by WASM binary: a second call with a different
+ * `wasm` must not silently reuse the first one. Failed loads are evicted
+ * so a later call can retry. */
+const moduleByWasm = new Map();
+/**
+ * Load (and reuse) the unified module for a pre-compiled `WebAssembly.Module`.
+ * @param wasm The compiled WASM module (always required — no bundled default)
+ */
+export function getDefaultModule(wasm) {
+    let pending = moduleByWasm.get(wasm);
+    if (!pending) {
+        pending = loadHtmlToImageModule({
+            factory: createHtmlToImageModule,
+            moduleArg: edgeModuleArg(wasm),
+        });
+        moduleByWasm.set(wasm, pending);
+        pending.catch(() => {
+            if (moduleByWasm.get(wasm) === pending)
+                moduleByWasm.delete(wasm);
+        });
+    }
+    return pending;
+}
+export async function render(options, wasm) {
+    return htmlToImage(await getDefaultModule(wasm), options);
+}

package/dist/encode-args.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encode-argument conversion (moved verbatim from `./core.ts`; behavior
+ * unchanged): WASM int enums and render-option object construction.
+ */
+import type { HtmlToImageOptions, OutputFormat } from "./core.js";
+/** `RenderFormat` enum values (mirrors `bridge_types.h`). */
+export declare const FORMAT_INT: Record<OutputFormat, number>;
+export declare const FIT_INT: Record<NonNullable<HtmlToImageOptions["fit"]>, number>;
+/** Map `crop`/`fit` to satoru render-option fields (`parse_satoru_options`). */
+export declare function buildSatoruOptions(crop: HtmlToImageOptions["crop"], fit: HtmlToImageOptions["fit"]): Record<string, unknown>;

package/dist/encode-args.js

@@ -0,0 +1,30 @@
+/** `RenderFormat` enum values (mirrors `bridge_types.h`). */
+export const FORMAT_INT = {
+    svg: 0,
+    png: 1,
+    webp: 2,
+    pdf: 3,
+    jpeg: 4,
+    avif: 5,
+    raw: 6,
+    thumbhash: 7,
+    none: -1,
+};
+export const FIT_INT = {
+    contain: 0,
+    cover: 1,
+    fill: 2,
+};
+/** Map `crop`/`fit` to satoru render-option fields (`parse_satoru_options`). */
+export function buildSatoruOptions(crop, fit) {
+    const o = {};
+    if (crop) {
+        o.cropX = crop.x;
+        o.cropY = crop.y;
+        o.cropWidth = crop.width;
+        o.cropHeight = crop.height;
+    }
+    if (fit)
+        o.fitType = FIT_INT[fit];
+    return o;
+}