wasm-html-to-image 1.0.2 → 1.0.3

package/README.md

@@ -273,6 +273,12 @@ npx wasm-html-to-image https://example.com/news -o news.png --base-url https://e
 
 # 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

@@ -8,7 +8,39 @@ export interface CliFlags {
     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.

package/dist/cli-options.js

@@ -7,6 +7,37 @@
 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.
@@ -44,6 +75,9 @@ 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,
@@ -51,5 +85,6 @@ export async function buildRenderOptions(input, flags) {
         quality: flags.quality,
         ...source,
         ...(flags.baseUrl !== undefined ? { baseUrl: flags.baseUrl } : {}),
+        ...(animation ? { animation } : {}),
     };
 }

package/dist/cli.js

@@ -30,6 +30,9 @@ program
     .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();
@@ -56,6 +59,9 @@ program
             format,
             quality: options.quality,
             baseUrl: options.baseUrl,
+            animation: options.animation,
+            animationFps: options.animationFps,
+            animationLoop: options.animationLoop,
         };
         const result = await render(await buildRenderOptions(input, flags));
         await fs.writeFile(outputPath, typeof result.data === "string"

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,
@@ -228,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")
@@ -323,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");
@@ -355,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" ||
@@ -402,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);
@@ -423,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;