wasm-html-to-image 1.0.1 → 1.0.3

package/README.md

@@ -267,8 +267,18 @@ 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
 
+# Pin the base for relative resources (default: URL input follows redirects,
+# file input uses the file's own directory)
+npx wasm-html-to-image https://example.com/news -o news.png --base-url https://example.com/
+
 # Convert and resize an image
 npx wasm-html-to-image photo.jpg -o photo.avif -w 800 -f avif -q 80
+
+# Sample an opacity / transform / color @keyframes animation into an animated WebP
+npx wasm-html-to-image loader.html -o loader.webp -f webp --animation 2000 --animation-fps 20
+
+# Play the animated WebP once instead of looping forever
+npx wasm-html-to-image loader.html -o loader.webp -f webp --animation 2000 --animation-loop 1
 ```
 
 ---

package/dist/browser-workers.js

@@ -5,16 +5,29 @@ 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. */
+let modPromise;
+/**
+ * Lazily load (and reuse) the module inside this worker.
+ *
+ * The pending promise is shared: parallel jobs arriving while the module
+ * is still loading wait for that single load instead of starting a second
+ * instantiation (a 12 MB binary plus its linear memory, each). A failed
+ * load clears the promise so the next job retries.
+ */
 const getModule = async () => {
-    if (!mod) {
-        mod = await loadHtmlToImageModule({
-            factory: createHtmlToImageModule,
-            moduleArg: { wasmBinary: await loadCompressedWasmBinary() },
+    if (!modPromise) {
+        modPromise = (async () => {
+            const wasmBinary = await loadCompressedWasmBinary();
+            return loadHtmlToImageModule({
+                factory: createHtmlToImageModule,
+                moduleArg: { wasmBinary },
+            });
+        })().catch((e) => {
+            modPromise = undefined;
+            throw e;
         });
     }
-    return mod;
+    return modPromise;
 };
 /**
  * Browser worker-side implementation (pre-bundled `dist/web-workers.js`).

package/dist/cli-options.d.ts

@@ -0,0 +1,64 @@
+import type { HtmlToImageOptions, OutputFormat } from "./core.js";
+/** Flags as parsed by commander (see `./cli.ts`). */
+export interface CliFlags {
+    output?: string;
+    width: number;
+    height?: number;
+    format: OutputFormat;
+    quality: number;
+    /** Explicit `--base-url`; absent means "let the source decide". */
+    baseUrl?: string;
+    /** `--animation <duration-ms>`; absent means "no keyframe animation". */
+    animation?: number;
+    /** `--animation-fps <n>`; defaults to 15 when `--animation` is set. */
+    animationFps?: number;
+    /**
+     * `--animation-loop <n>`; how many times the animated WebP repeats.
+     * Absent means infinite (libwebp loop_count 0 = the historical default).
+     */
+    animationLoop?: number;
+}
+/** Default frame rate for `--animation` when `--animation-fps` is omitted. */
+export declare const DEFAULT_ANIMATION_FPS = 15;
+/**
+ * Animation flags resolved against the output format.
+ *
+ * Animated WebP is the only animated output the pipeline supports, so
+ * `--animation` is ignored (with a warning) for every other format. The
+ * boolean `animation: true` image-input path is intentionally not reachable
+ * from the CLI: there the object form requests `@keyframes` sampling, which
+ * is what `--animation` means.
+ */
+export interface AnimationResolution {
+    /** Resolved `render()` animation option, or absent when disabled/ignored. */
+    animation?: {
+        duration: number;
+        fps: number;
+        loop?: number;
+    };
+    /** Human-readable reason the flag was dropped; callers warn on stderr. */
+    warning?: string;
+}
+/** Map `--animation` / `--animation-fps` / `--animation-loop` to the `render()` animation option. */
+export declare function resolveAnimation(flags: CliFlags): AnimationResolution;
+/**
+ * URL inputs are fetched, not read from disk. `data:` URLs stay values so
+ * image inputs keep flowing through the converter pipeline.
+ */
+export declare function isUrlInput(input: string): boolean;
+/**
+ * Read a local input file as binary; image files (magic-byte sniffed) are
+ * passed through as bytes, everything else as UTF-8 text (HTML).
+ */
+export declare function readInput(input: string): Promise<{
+    value: string | Uint8Array;
+    baseUrl: string;
+}>;
+/**
+ * Map CLI flags to `render()` options.
+ *
+ * `--base-url` is the only way to pin the base: without it a URL input leaves
+ * `baseUrl` unset so relative resources follow the post-redirect final URL
+ * (`resolveHtmlSource`), while a file input falls back to its own directory.
+ */
+export declare function buildRenderOptions(input: string, flags: CliFlags): Promise<HtmlToImageOptions>;

package/dist/cli-options.js

@@ -0,0 +1,90 @@
+/**
+ * CLI flag plumbing split from `./cli.ts` (behavior unchanged): input-type
+ * detection, local file reading, and the flag -> `render()` option mapping.
+ * Kept separate from the executable entry point so the mapping is
+ * unit-testable without running the CLI.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isImageInput } from "./input.js";
+/** Default frame rate for `--animation` when `--animation-fps` is omitted. */
+export const DEFAULT_ANIMATION_FPS = 15;
+/** Map `--animation` / `--animation-fps` / `--animation-loop` to the `render()` animation option. */
+export function resolveAnimation(flags) {
+    if (flags.animation === undefined) {
+        if (flags.animationFps !== undefined) {
+            return { warning: "--animation-fps requires --animation; ignoring." };
+        }
+        if (flags.animationLoop !== undefined) {
+            return { warning: "--animation-loop requires --animation; ignoring." };
+        }
+        return {};
+    }
+    if (flags.format !== "webp") {
+        return {
+            warning: `--animation is only supported for webp output; ignoring (format=${flags.format}).`,
+        };
+    }
+    // `loop` stays absent unless requested: the render() default (0) is the
+    // historical infinite loop, so the option object keeps its old shape.
+    const loop = flags.animationLoop === undefined
+        ? undefined
+        : Math.max(0, Math.trunc(flags.animationLoop));
+    return {
+        animation: {
+            duration: flags.animation,
+            fps: flags.animationFps ?? DEFAULT_ANIMATION_FPS,
+            ...(loop === undefined ? {} : { loop }),
+        },
+    };
+}
+/**
+ * URL inputs are fetched, not read from disk. `data:` URLs stay values so
+ * image inputs keep flowing through the converter pipeline.
+ */
+export function isUrlInput(input) {
+    const isWindowsPath = /^[a-zA-Z]:[\\/]/.test(input);
+    return (!isWindowsPath &&
+        /^[a-z][a-z0-9+.-]*:/i.test(input) &&
+        !input.startsWith("data:"));
+}
+/**
+ * Read a local input file as binary; image files (magic-byte sniffed) are
+ * passed through as bytes, everything else as UTF-8 text (HTML).
+ */
+export 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)) };
+}
+/**
+ * Map CLI flags to `render()` options.
+ *
+ * `--base-url` is the only way to pin the base: without it a URL input leaves
+ * `baseUrl` unset so relative resources follow the post-redirect final URL
+ * (`resolveHtmlSource`), while a file input falls back to its own directory.
+ */
+export async function buildRenderOptions(input, flags) {
+    const source = isUrlInput(input)
+        ? { url: input }
+        : await readInput(input);
+    const { animation, warning } = resolveAnimation(flags);
+    if (warning)
+        console.warn(`wasm-html-to-image: ${warning}`);
+    return {
+        width: flags.width,
+        height: flags.height,
+        format: flags.format,
+        quality: flags.quality,
+        ...source,
+        ...(flags.baseUrl !== undefined ? { baseUrl: flags.baseUrl } : {}),
+        ...(animation ? { animation } : {}),
+    };
+}

package/dist/cli.js

@@ -2,8 +2,8 @@
 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";
+import { render } from "./single.js";
+import { buildRenderOptions, isUrlInput } from "./cli-options.js";
 const OUTPUT_FORMATS = [
     "svg",
     "png",
@@ -19,22 +19,6 @@ const OUTPUT_FORMATS = [
 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/jxl/raw/thumbhash via encode or html_to_image)")
@@ -45,6 +29,10 @@ program
     .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)
+    .option("--base-url <url>", "base URL for relative resources (URL input: defaults to the post-redirect document URL; file input: defaults to the file's directory)")
+    .option("--animation <duration-ms>", "sample the document's @keyframes opacity / transform / color animation into an animated WebP; one loop duration in ms (webp output only; the CSS animation-duration wins and this value is an upper bound)", (v) => parseInt(v, 10))
+    .option("--animation-fps <n>", "animation frame rate (default 15, capped at ~75 frames total; requires --animation)", (v) => parseInt(v, 10))
+    .option("--animation-loop <n>", "how many times the animated WebP repeats (0 = infinite, the default; 1 = play once; requires --animation)", (v) => parseInt(v, 10))
     .action(async (input, options) => {
     try {
         const format = String(options.format).toLowerCase();
@@ -52,10 +40,7 @@ program
             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:");
+        const isUrl = isUrlInput(input);
         let outputPath = options.output;
         if (!outputPath) {
             const ext = format;
@@ -67,14 +52,18 @@ program
                     ext: `.${ext}`,
                 });
         }
-        const renderOptions = {
+        const flags = {
+            output: options.output,
             width: options.width,
             height: options.height,
             format,
             quality: options.quality,
-            ...(isUrl ? { url: input, baseUrl: input } : await readInput(input)),
+            baseUrl: options.baseUrl,
+            animation: options.animation,
+            animationFps: options.animationFps,
+            animationLoop: options.animationLoop,
         };
-        const result = await render(renderOptions);
+        const result = await render(await buildRenderOptions(input, flags));
         await fs.writeFile(outputPath, typeof result.data === "string"
             ? result.data
             : Buffer.from(result.data));

package/dist/core-orchestrate.d.ts

@@ -13,6 +13,21 @@ export interface Orchestration {
     quality: number;
     speed: number;
     animation: boolean;
+    /**
+     * HTML animated-output request (`animation: { duration, fps, loop }`). When
+     * set, the HTML pipeline samples the document's `@keyframes` animation
+     * (opacity / transform / color) into converter frames before encoding.
+     */
+    animationFrames: {
+        duration: number;
+        fps?: number;
+        loop?: number;
+    } | undefined;
+    /**
+     * Animated WebP loop count handed to the encode stage (libwebp
+     * `anim_params.loop_count`). `0` = infinite (the historical default).
+     */
+    animationLoop: number;
     width: number;
     height: number | undefined;
     crop: HtmlToImageOptions["crop"];

package/dist/core-orchestrate.js

@@ -34,7 +34,17 @@ export function defaultSpeed(format) {
 }
 /** Build per-call orchestration state (log gate, timings, diag, resolve ctx). */
 export function createOrchestration(module, options) {
-    const { format = "png", quality = 85, speed: speedOption, animation = false, width, height, crop, fit, value, url, baseUrl, fontMap, userAgent, fallbackFonts, logLevel = LogLevel.None, onLog, diagnostics = false, onDiagnostics, resolveResource, mediaType = "screen", textToPaths, css, fonts: preloadFonts, limits = {}, pdfTitle, pdfAuthor, pdfSubject, pdfKeywords, pdfCreator, pdfProducer, pdfMargin, pdfHeader, pdfFooter, } = options;
+    const { format = "png", quality = 85, speed: speedOption, width, height, crop, fit, value, url, baseUrl, fontMap, userAgent, fallbackFonts, logLevel = LogLevel.None, onLog, diagnostics = false, onDiagnostics, resolveResource, mediaType = "screen", textToPaths, css, fonts: preloadFonts, limits = {}, pdfTitle, pdfAuthor, pdfSubject, pdfKeywords, pdfCreator, pdfProducer, pdfMargin, pdfHeader, pdfFooter, } = options;
+    // `animation` accepts a boolean (image input: keep frames) or, for HTML
+    // input, an object requesting keyframe sampling. The object form turns on
+    // the boolean flag for the encode stage and enables the frame path.
+    const rawAnimation = options.animation;
+    const animationFrames = rawAnimation !== null && typeof rawAnimation === "object"
+        ? rawAnimation
+        : undefined;
+    const animation = animationFrames ? true : rawAnimation === true;
+    // Loop count of the produced animated WebP (0 = infinite = legacy default).
+    const animationLoop = Math.max(0, Math.trunc(animationFrames?.loop ?? 0));
     const speed = speedOption ?? defaultSpeed(format);
     const fmtInt = FORMAT_INT[format];
     const mediaTypeInt = mediaType === "print" ? 1 : 0;
@@ -128,6 +138,8 @@ export function createOrchestration(module, options) {
         quality,
         speed,
         animation,
+        animationFrames,
+        animationLoop,
         width,
         height,
         crop,
@@ -183,12 +195,18 @@ export async function resolveHtmlSource(orch) {
     if (typeof url === "string") {
         const headers = { "User-Agent": userAgent ?? DEFAULT_USER_AGENT };
         const fetchStart = now();
+        // Post-redirect document URL (`Response.url`). Relative resources must
+        // resolve against the final URL, not the stale request URL: a 301 to a new
+        // host otherwise leaves every stylesheet/font/image on the old host.
+        let finalUrl;
         let htmls;
         if (resolveResource) {
             const fallbackFetch = async () => {
                 const res = await fetch(url, { headers });
                 if (!res.ok)
                     return null;
+                if (res.url)
+                    finalUrl = res.url;
                 return toBytes(await res.arrayBuffer());
             };
             const raw = await resolveResource(url, fallbackFetch);
@@ -202,8 +220,15 @@ export async function resolveHtmlSource(orch) {
             if (!res.ok) {
                 throw logged(`wasm-html-to-image: failed to fetch HTML from URL: ${url} (${res.status})`);
             }
+            if (res.url)
+                finalUrl = res.url;
             htmls = await res.text();
         }
+        // An explicit `baseUrl` always wins; otherwise adopt the document URL so
+        // relative resource resolution follows redirects.
+        if (orch.baseUrl === undefined && finalUrl !== undefined) {
+            orch.baseUrl = finalUrl;
+        }
         addTime("fetchHtml", now() - fetchStart);
         return htmls;
     }
@@ -215,7 +240,7 @@ export async function resolveHtmlSource(orch) {
  * `imageBytesFromUnknown` (`unknown` in, no `as` casts).
  */
 export async function runImageInput(module, value, orch) {
-    const { format, quality, speed, animation, width, height, crop, fit, fmtInt, t0, emitLog, logged, loggedBinding, addTime, deliverReport, } = orch;
+    const { format, quality, speed, animation, animationLoop, width, height, crop, fit, fmtInt, t0, emitLog, logged, loggedBinding, addTime, deliverReport, } = orch;
     // Narrowed here: caller selected this branch via `isImageInput(value)`.
     const loadImage = module.converter_load_image;
     if (typeof loadImage !== "function")
@@ -310,7 +335,7 @@ export async function runImageInput(module, value, orch) {
         if (typeof encodeBinding !== "function")
             throw loggedBinding("converter_encode");
         const encodeStart = now();
-        const out = (await encodeBinding(inst, fmtInt, quality, speed, animation));
+        const out = (await encodeBinding(inst, fmtInt, quality, speed, animation, animationLoop));
         addTime("encode", now() - encodeStart);
         if (out == null) {
             throw logged("wasm-html-to-image: failed to encode image");
@@ -342,7 +367,7 @@ export async function runImageInput(module, value, orch) {
  * pre-resolved resources, so it stays a fallback only).
  */
 export async function tryRunHtmlInstance(module, htmls, satoruOpts, defaultFontMap, orch) {
-    const { format, quality, speed, animation, width, height, baseUrl, fontMap, userAgent, fallbackFonts, fmtInt, t0, emitLog, logged, loggedBinding, addTime, deliverReport, resolveCtx, } = orch;
+    const { format, quality, speed, animation, animationFrames, animationLoop, width, height, baseUrl, fontMap, userAgent, fallbackFonts, fmtInt, t0, emitLog, logged, loggedBinding, addTime, deliverReport, resolveCtx, } = orch;
     const renderBinding = module.satoru_render;
     const encodeBinding = module.converter_encode;
     if (typeof renderBinding !== "function" ||
@@ -389,8 +414,22 @@ export async function tryRunHtmlInstance(module, htmls, satoruOpts, defaultFontM
         const renderStart = now();
         const cInst = module.converter_create_instance();
         try {
+            // Animated HTML: sample the document's @keyframes animation (opacity /
+            // transform / color) straight into the converter's frames (additive).
+            // Falls back to the single-frame path when no frames were produced.
+            let renderedFrames = false;
+            const renderAnimationToConverter = module.satoru_render_animation_to_converter;
+            if (animationFrames &&
+                typeof renderAnimationToConverter === "function") {
+                const frames = (await renderAnimationToConverter(sInst, cInst, htmls, width, height ?? 0, satoruOpts, animationFrames.duration, animationFrames.fps ?? 15));
+                addTime("render", now() - renderStart);
+                renderedFrames = frames > 0;
+            }
             const renderToConverter = module.satoru_render_to_converter;
-            if (typeof renderToConverter === "function") {
+            if (renderedFrames) {
+                // converter already holds the sampled frames.
+            }
+            else if (typeof renderToConverter === "function") {
                 // Bitmap goes straight into the converter: no PNG encode/decode.
                 const ok = await renderToConverter(sInst, cInst, htmls, width, height ?? 0, satoruOpts);
                 addTime("render", now() - renderStart);
@@ -410,14 +449,16 @@ export async function tryRunHtmlInstance(module, htmls, satoruOpts, defaultFontM
             }
             const outWidth = module.converter_get_width?.(cInst) ?? width;
             const outHeight = module.converter_get_height?.(cInst) ?? height ?? 0;
-            const outAnimation = module.converter_is_animation?.(cInst) ?? animation;
-            const outFormat = module.converter_get_format?.(cInst) || format;
             const encodeStart = now();
-            const out = (await encodeBinding(cInst, fmtInt, quality, speed, animation));
+            const out = (await encodeBinding(cInst, fmtInt, quality, speed, animation, animationLoop));
             addTime("encode", now() - encodeStart);
             if (out == null) {
                 throw logged("wasm-html-to-image: failed to encode image");
             }
+            // Read the post-encode metadata: `is_animation`/`get_format` are only
+            // meaningful after `converter_encode` has run.
+            const outAnimation = module.converter_is_animation?.(cInst) ?? animation;
+            const outFormat = module.converter_get_format?.(cInst) || format;
             addTime("total", now() - t0);
             emitLog(LogLevel.Info, `render done: format=${format}`);
             deliverReport();

package/dist/core.d.ts

@@ -65,8 +65,31 @@ export interface HtmlToImageOptions extends RenderOptions {
     quality?: number;
     /** Encode speed 0-10, mainly for AVIF (encode stage only; default 8 for AVIF, 6 otherwise). */
     speed?: number;
-    /** Keep animation frames where supported (encode stage only). */
-    animation?: boolean;
+    /**
+     * Animation handling.
+     * - `true`: keep animation frames where supported (image input / encode stage).
+     * - `{ duration, fps, loop }` (HTML input only): sample the document's
+     *   `@keyframes` animation into frames. `duration` is one loop length in ms
+     *   (clamped to 5000), `fps` defaults to 15 (frame count capped at ~75).
+     *   The CSS `animation-duration` (including the `animation` shorthand)
+     *   is the length of one iteration; `animation-delay` /
+     *   `animation-iteration-count` define the sampled timeline, capped by
+     *   `duration`; `fps` is the upper frame rate. `loop` is how many times the
+     *   animated WebP repeats: `0` (the default) means infinite, `1` means play
+     *   once. `opacity`, `transform` (`translate` / `rotate` / `scale` only) and
+     *   `color` / `background-color` keyframes are animated; their values may
+     *   use `var()` (resolved against the element's custom properties).
+     *   `animation-timing-function` (per keyframe or element-level:
+     *   `linear` / `ease*` / `cubic-bezier()` / `steps()` / `step-*`),
+     *   `animation-direction` and `animation-fill-mode` are honoured.
+     *   Several animations on one element (`animation-name: a, b`) are out of
+     *   scope.
+     */
+    animation?: boolean | {
+        duration: number;
+        fps?: number;
+        loop?: number;
+    };
     /** Crop rectangle (encode stage for image input, render options for HTML). */
     crop?: {
         x: number;