satoru-render 0.0.18 → 0.0.20

package/README.md

@@ -103,9 +103,9 @@ const png = await render({
 
 ## 🛠️ Advanced Usage
 
-### 1. Dynamic Resource Resolution
+### 1. Dynamic Resource Resolution & Caching
 
-Satoru can automatically fetch missing fonts, images, or external CSS via a `resolveResource` callback.
+Satoru can automatically fetch missing fonts, images, or external CSS via a `resolveResource` callback. You can also implement high-performance caching using the browser's `CacheStorage` API.
 
 ```typescript
 const pdf = await render({
@@ -114,12 +114,23 @@ const pdf = await render({
   format: "pdf",
   baseUrl: "https://example.com/assets/",
   resolveResource: async (resource, defaultResolver) => {
-    // Custom intercept logic
-    if (resource.url.startsWith("my-app://")) {
-      return myAssetBuffer;
+    // 1. Open Cache storage
+    const cache = await caches.open("satoru-resource-cache");
+    const cachedResponse = await cache.match(resource.url);
+
+    // 2. Return cached data if available
+    if (cachedResponse) {
+      const buf = await cachedResponse.arrayBuffer();
+      return new Uint8Array(buf);
     }
-    // Fallback to default fetch/filesystem resolver
-    return defaultResolver(resource);
+
+    // 3. Fetch using default resolver and save to cache
+    const data = await defaultResolver(resource);
+    if (data?.length) {
+      await cache.put(resource.url, new Response(data));
+    }
+
+    return data;
   },
 });
 ```
@@ -220,17 +231,81 @@ const png = await render({
 
 ---
 
+### 6. JSDOM Hydration (For Next.js / SPAs)
+
+For complex client-side applications (like Next.js) that require full Javascript evaluation and DOM hydration before rendering, Satoru provides an optional `jsdom` helper.
+
+_Note: `jsdom` must be installed separately in your project (`npm install jsdom`)._
+
+```typescript
+import { render } from "satoru-render";
+import { getHtml } from "satoru-render/jsdom";
+
+// 1. Let JSDOM fetch the URL, execute scripts, and wait for network/hydration
+const hydratedHtml = await getHtml({
+  src: "https://example.com/",
+  waitUntil: "networkidle", // Wait until Next.js finishes loading chunks
+  beforeParse: (window) => {
+    // Provide polyfills if the target site requires them
+    window.matchMedia = () => ({ matches: false, addListener: () => {} });
+    window.IntersectionObserver = class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    };
+  },
+});
+
+// 2. Render the fully constructed DOM in Satoru (at native speed)
+const pngBytes = await render({
+  value: hydratedHtml,
+  baseUrl: "https://example.com/",
+  width: 1200,
+  format: "png",
+});
+```
+
+### 7. DOM Capture (html2canvas alternative)
+
+Satoru can capture live DOM elements directly in the browser, preserving computed styles, pseudo-elements (`::before`/`::after`), canvas contents, and form states.
+
+```typescript
+import { Satoru } from "satoru-render";
+import createSatoruModule from "satoru-render/satoru.js";
+
+const satoru = await Satoru.create(createSatoruModule);
+const element = document.getElementById("target-element");
+
+// 1. Capture to HTMLCanvasElement (Direct html2canvas replacement)
+const canvas = await satoru.capture(element, {
+  format: "png",
+});
+document.body.appendChild(canvas);
+
+// 2. Or render directly to binary (Uint8Array)
+const png = await satoru.render({
+  value: element, // Accepts HTMLElement directly
+  width: 800,
+  format: "png",
+});
+```
+
+---
+
 ## 💻 CLI Tool
 
 Convert files or URLs directly from your terminal.
 
 ```bash
-# Local HTML to PNG
+# Local HTML to PNG (JSDOM hydration enabled by default)
 npx satoru-render input.html -o output.png
 
 # URL to PDF with specific width
 npx satoru-render https://example.com -o site.pdf -w 1280
 
+# Convert without JSDOM hydration
+npx satoru-render https://example.com --no-jsdom -o example.pdf
+
 # WebP conversion with verbose logs
 npx satoru-render input.html -f webp --verbose
 ```
@@ -241,9 +316,9 @@ npx satoru-render input.html -f webp --verbose
 
 ### Render Options
 
-| Option            | Type                                | Description                                             |
-| :---------------- | :---------------------------------- | :------------------------------------------------------ |
-| `value`           | `string \| string[]`                | HTML string or array of strings (for multi-page PDF).   |
+| Option            | Type                                     | Description                                             |
+| :---------------- | :--------------------------------------- | :------------------------------------------------------ |
+| `value`           | `string \| string[] \| HTMLElement \| ...` | HTML string, array of strings, or DOM element(s).       |
 | `url`             | `string`                            | URL to fetch HTML from.                                 |
 | `width`           | `number`                            | **Required.** Output width in pixels.                   |
 | `height`          | `number`                            | Output height. Default: `0` (auto-calculate).           |

package/dist/bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bench.js

@@ -0,0 +1,70 @@
+import { Bench } from "tinybench";
+import { Satoru } from "./node.js";
+// @ts-ignore
+import createSatoruModule from "../dist/satoru-single.js";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const assetsDir = path.join(__dirname, "../../../assets");
+async function runBenchmark() {
+    const satoru = await Satoru.create(createSatoruModule);
+    const bench = new Bench({ time: 1000 });
+    const files = [
+        "06-flexbox.html",
+        "09-grid.html",
+        "11-complex-text.html",
+        "15-showcase.html",
+    ];
+    for (const file of files) {
+        const filePath = path.join(assetsDir, file);
+        if (!fs.existsSync(filePath)) {
+            console.warn(`File not found: ${filePath}`);
+            continue;
+        }
+        const html = fs.readFileSync(filePath, "utf-8");
+        // Full render
+        bench.add(`Full Render: ${file}`, async () => {
+            await satoru.render({
+                value: html,
+                width: 1200,
+                format: "svg",
+                baseUrl: `file://${assetsDir}/`,
+            });
+        });
+        // Core layout and render (no resource discovery if we assume resources are loaded)
+        // To make it fair, we'll initialize once and layout/render multiple times
+        // However, tinybench runs the function multiple times, so we need to be careful about state.
+        // For core, we'll do init inside to avoid state pollution, but the focus is on layout/render.
+        bench.add(`Core Layout+Render (SVG): ${file}`, async () => {
+            const inst = await satoru.initDocument({
+                html,
+                width: 1200,
+                baseUrl: `file://${assetsDir}/`,
+            });
+            await satoru.layoutDocument(inst, 1200);
+            await satoru.renderFromState(inst, {
+                width: 1200,
+                format: "svg",
+            });
+            await satoru.destroyInstance(inst);
+        });
+        bench.add(`Core Layout+Render (PNG): ${file}`, async () => {
+            const inst = await satoru.initDocument({
+                html,
+                width: 1200,
+                baseUrl: `file://${assetsDir}/`,
+            });
+            await satoru.layoutDocument(inst, 1200);
+            await satoru.renderFromState(inst, {
+                width: 1200,
+                format: "png",
+            });
+            await satoru.destroyInstance(inst);
+        });
+    }
+    console.log("Running benchmarks...");
+    await bench.run();
+    console.table(bench.table());
+}
+runBenchmark().catch(console.error);

package/dist/cli.js

@@ -7,6 +7,7 @@ async function main() {
     const options = {
         width: 800,
         format: "png",
+        jsdom: true, // Default to true
     };
     let input;
     for (let i = 0; i < args.length; i++) {
@@ -23,6 +24,9 @@ async function main() {
         else if (arg === "-o" || arg === "--output") {
             options.output = args[++i];
         }
+        else if (arg === "--no-jsdom") {
+            options.jsdom = false;
+        }
         else if (arg === "--verbose") {
             options.verbose = true;
         }
@@ -70,16 +74,63 @@ async function main() {
             console.error(`[Satoru] ${LogLevel[level]}: ${message}`);
         };
     }
+    let finalHtml;
+    let baseUrl;
     if (isUrl) {
-        renderOptions.url = input;
+        baseUrl = input;
+        if (options.jsdom) {
+            try {
+                const { getHtml } = await import("./jsdom.js");
+                if (options.verbose)
+                    console.error(`[Satoru] Hydrating URL via JSDOM: ${input}`);
+                finalHtml = await getHtml({
+                    src: input,
+                    waitUntil: "networkidle",
+                    forwardConsole: options.verbose,
+                });
+            }
+            catch (err) {
+                if (options.verbose)
+                    console.error(`[Satoru] JSDOM hydration failed or not available, falling back to direct URL fetch:`, err);
+                renderOptions.url = input;
+            }
+        }
+        else {
+            renderOptions.url = input;
+        }
     }
     else {
         if (!fs.existsSync(input)) {
             console.error(`Error: File not found: ${input}`);
             process.exit(1);
         }
-        renderOptions.value = fs.readFileSync(input, "utf-8");
-        renderOptions.baseUrl = path.dirname(path.resolve(input));
+        const rawContent = fs.readFileSync(input, "utf-8");
+        baseUrl = path.dirname(path.resolve(input));
+        if (options.jsdom) {
+            try {
+                const { getHtml } = await import("./jsdom.js");
+                if (options.verbose)
+                    console.error(`[Satoru] Hydrating file via JSDOM: ${input}`);
+                finalHtml = await getHtml({
+                    src: rawContent,
+                    baseUrl: `file://${baseUrl}/`,
+                    waitUntil: "networkidle",
+                    forwardConsole: options.verbose,
+                });
+            }
+            catch (err) {
+                if (options.verbose)
+                    console.error(`[Satoru] JSDOM hydration failed or not available, falling back to raw file content:`, err);
+                finalHtml = rawContent;
+            }
+        }
+        else {
+            finalHtml = rawContent;
+        }
+    }
+    if (finalHtml !== undefined) {
+        renderOptions.value = finalHtml;
+        renderOptions.baseUrl = baseUrl;
     }
     try {
         const result = await satoru.render(renderOptions);
@@ -100,6 +151,7 @@ Options:
   -w, --width <number>   Viewport width (default: 800)
   -h, --height <number>  Viewport height (default: 0, auto-calculate)
   -f, --format <format>  Output format: svg, png, webp, pdf
+  --no-jsdom             Disable JSDOM hydration (enabled by default)
   --verbose              Enable detailed logging
   --help                 Show this help message
 `);

package/dist/core.d.ts

@@ -7,7 +7,9 @@ export interface SatoruModule {
     add_resource: (inst: any, url: string, type: number, data: Uint8Array) => void;
     scan_css: (inst: any, css: string) => void;
     load_font: (inst: any, name: string, data: Uint8Array) => void;
+    load_fallback_font: (inst: any, data: Uint8Array) => void;
     load_image: (inst: any, name: string, url: string, width: number, height: number) => void;
+    load_image_pixels: (inst: any, name: string, width: number, height: number, pixels: Uint8Array, data_url: string) => void;
     set_font_map: (inst: any, fontMap: Record<string, string>) => void;
     set_log_level: (level: number) => void;
     init_document: (inst: any, html: string, width: number, height: number) => void;
@@ -26,7 +28,7 @@ export interface RequiredResource {
 }
 export type ResourceResolver = (resource: RequiredResource, defaultResolver: (resource: RequiredResource) => Promise<Uint8Array | null>) => Promise<Uint8Array | ArrayBufferView | null>;
 export interface RenderOptions {
-    value?: string | string[];
+    value?: string | string[] | any | any[];
     url?: string;
     width: number;
     height?: number;
@@ -37,6 +39,7 @@ export interface RenderOptions {
         name: string;
         data: Uint8Array;
     }[];
+    fallbackFonts?: Uint8Array[];
     images?: {
         name: string;
         url: string;
@@ -69,6 +72,7 @@ export declare abstract class SatoruBase {
         textToPaths?: boolean;
     }): Promise<string | Uint8Array>;
     destroyInstance(inst: any): Promise<void>;
+    loadFallbackFont(data: Uint8Array): Promise<void>;
     protected abstract resolveDefaultResource(resource: RequiredResource, baseUrl?: string, userAgent?: string): Promise<Uint8Array | null>;
     protected abstract fetchHtml(url: string, userAgent?: string): Promise<string>;
     render(options: RenderOptions & {

package/dist/core.js

@@ -150,6 +150,16 @@ export class SatoruBase {
         const mod = await this.getModule();
         mod.destroy_instance(inst);
     }
+    async loadFallbackFont(data) {
+        const mod = await this.getModule();
+        const inst = mod.create_instance();
+        try {
+            mod.load_fallback_font(inst, data);
+        }
+        finally {
+            mod.destroy_instance(inst);
+        }
+    }
     async render(options) {
         const mod = await this.getModule();
         let { value, url, width, height = 0, format = "svg", fonts, images, css, baseUrl, logLevel, onLog, } = options;
@@ -181,6 +191,11 @@ export class SatoruBase {
                     mod.load_font(instancePtr, f.name, f.data);
                 }
             }
+            if (options.fallbackFonts) {
+                for (const data of options.fallbackFonts) {
+                    mod.load_fallback_font(instancePtr, data);
+                }
+            }
             if (images) {
                 for (const img of images) {
                     mod.load_image(instancePtr, img.name, img.url, img.width ?? 0, img.height ?? 0);
@@ -225,6 +240,23 @@ export class SatoruBase {
                                 const uint8 = data instanceof Uint8Array
                                     ? data
                                     : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+                                if (r.type === "image" && typeof createImageBitmap !== "undefined" && typeof OffscreenCanvas !== "undefined") {
+                                    try {
+                                        const blob = new Blob([uint8.buffer]);
+                                        const bitmap = await createImageBitmap(blob);
+                                        const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+                                        const ctx = canvas.getContext("2d");
+                                        if (ctx) {
+                                            ctx.drawImage(bitmap, 0, 0);
+                                            const imageData = ctx.getImageData(0, 0, bitmap.width, bitmap.height);
+                                            mod.load_image_pixels(instancePtr, r.url, bitmap.width, bitmap.height, new Uint8Array(imageData.data.buffer), r.url);
+                                            return;
+                                        }
+                                    }
+                                    catch (e) {
+                                        // fallback to passing raw binary if decoding fails
+                                    }
+                                }
                                 let typeInt = 1;
                                 if (r.type === "image")
                                     typeInt = 2;
@@ -247,7 +279,7 @@ export class SatoruBase {
                 });
                 resolvedUrls.forEach((url) => {
                     const escapedUrl = url.replace(/[.*+?^${}()|[\]]/g, "\\$&");
-                    const linkRegex = new RegExp(`<link[^>]*href\\s*=\\s*(["'])${escapedUrl}\\1[^>]*>`, "gi");
+                    const linkRegex = new RegExp(`<link[^>]*href\\s*=\\s*(["']?)${escapedUrl}\\1[^>]*>`, "gi");
                     processedHtml = processedHtml.replace(linkRegex, "");
                 });
                 processedHtmls.push(processedHtml);
@@ -267,7 +299,7 @@ export class SatoruBase {
             if (format === "svg") {
                 return new TextDecoder().decode(result);
             }
-            return new Uint8Array(result);
+            return new Uint8Array(result.slice());
         }
         finally {
             mod.destroy_instance(instancePtr);

package/dist/index.d.ts

@@ -1,9 +1,26 @@
-import { SatoruBase, RequiredResource } from "./core.js";
+import { SatoruBase, RequiredResource, RenderOptions } from "./core.js";
 export * from "./core.js";
 export * from "./log-level.js";
 export type { SatoruWorker } from "./child-workers.js";
 export declare class Satoru extends SatoruBase {
     static create(createSatoruModuleFunc: any): Promise<Satoru>;
+    /**
+     * Captures an HTMLElement and returns an HTMLCanvasElement.
+     * Similar to html2canvas.
+     */
+    capture(element: HTMLElement, options?: Partial<Omit<RenderOptions, "value" | "url">>): Promise<HTMLCanvasElement>;
+    private serializeElement;
+    private pngToCanvas;
+    /**
+     * Overrides render to support HTMLElement as value.
+     */
+    render(options: RenderOptions & {
+        format: "png" | "webp" | "pdf";
+    }): Promise<Uint8Array>;
+    render(options: RenderOptions & {
+        format?: "svg";
+    }): Promise<string>;
+    render(options: RenderOptions): Promise<string | Uint8Array>;
     static defaultResourceResolver(resource: RequiredResource, baseUrl?: string, userAgent?: string): Promise<Uint8Array | null>;
     protected resolveDefaultResource(resource: RequiredResource, baseUrl?: string, userAgent?: string): Promise<Uint8Array | null>;
     protected fetchHtml(url: string, userAgent?: string): Promise<string>;

package/dist/index.js

@@ -5,6 +5,169 @@ export class Satoru extends SatoruBase {
     static async create(createSatoruModuleFunc) {
         return new Satoru(createSatoruModuleFunc);
     }
+    /**
+     * Captures an HTMLElement and returns an HTMLCanvasElement.
+     * Similar to html2canvas.
+     */
+    async capture(element, options = {}) {
+        const rect = element.getBoundingClientRect();
+        const width = options.width ?? Math.ceil(rect.width);
+        const height = options.height ?? Math.ceil(rect.height);
+        // 1. Serialize DOM with computed styles
+        const serializedHtml = this.serializeElement(element);
+        // 2. Render to PNG
+        const pngData = await this.render({
+            ...options,
+            value: serializedHtml,
+            width,
+            height,
+            format: "png",
+        });
+        // 3. Convert PNG to Canvas
+        return this.pngToCanvas(pngData, width, height);
+    }
+    serializeElement(element) {
+        const clone = element.cloneNode(true);
+        const absoluteUrl = (url) => {
+            if (!url || url.startsWith("data:") || url.startsWith("blob:"))
+                return url;
+            const a = document.createElement("a");
+            a.href = url;
+            return a.href;
+        };
+        const applyStyles = (src, dest) => {
+            const computed = window.getComputedStyle(src);
+            const styleArr = [];
+            for (let i = 0; i < computed.length; i++) {
+                const prop = computed[i];
+                let value = computed.getPropertyValue(prop);
+                // Convert relative URLs in styles (e.g., background-image)
+                if (value.includes("url(")) {
+                    value = value.replace(/url\(['"]?([^'"]+)['"]?\)/g, (match, url) => {
+                        return `url("${absoluteUrl(url)}")`;
+                    });
+                }
+                styleArr.push(`${prop}:${value}`);
+            }
+            dest.setAttribute("style", styleArr.join(";"));
+            // Handle pseudo-elements
+            const handlePseudo = (pseudoType) => {
+                const style = window.getComputedStyle(src, pseudoType);
+                const content = style.getPropertyValue("content");
+                if (!content || content === "none" || content === "normal")
+                    return;
+                const pseudoEl = document.createElement("span");
+                const pseudoStyles = [];
+                for (let i = 0; i < style.length; i++) {
+                    const prop = style[i];
+                    pseudoStyles.push(`${prop}:${style.getPropertyValue(prop)}`);
+                }
+                pseudoEl.setAttribute("style", pseudoStyles.join(";"));
+                // Remove quotes from content for the innerText if it's just a string
+                if (content.startsWith('"') && content.endsWith('"')) {
+                    pseudoEl.innerText = content.slice(1, -1);
+                }
+                if (pseudoType === "::before") {
+                    dest.prepend(pseudoEl);
+                }
+                else {
+                    dest.append(pseudoEl);
+                }
+            };
+            handlePseudo("::before");
+            handlePseudo("::after");
+            // Special handling for specific elements
+            if (src instanceof HTMLCanvasElement) {
+                const img = document.createElement("img");
+                img.src = src.toDataURL();
+                img.setAttribute("style", dest.getAttribute("style") || "");
+                dest.replaceWith(img);
+            }
+            else if (src instanceof HTMLImageElement) {
+                dest.setAttribute("src", absoluteUrl(src.src));
+            }
+            else if (src instanceof HTMLInputElement) {
+                if (src.type === "checkbox" || src.type === "radio") {
+                    if (src.checked)
+                        dest.setAttribute("checked", "");
+                }
+                else {
+                    dest.setAttribute("value", src.value);
+                }
+            }
+            else if (src instanceof HTMLTextAreaElement) {
+                dest.innerText = src.value;
+            }
+            else if (src instanceof HTMLSelectElement) {
+                // Find the selected option and mark it
+                const index = src.selectedIndex;
+                const clonedSelect = dest;
+                if (clonedSelect.options[index]) {
+                    clonedSelect.options[index].setAttribute("selected", "");
+                }
+            }
+            for (let i = 0; i < src.children.length; i++) {
+                const srcChild = src.children[i];
+                const destChild = dest.children[i];
+                if (srcChild && destChild) {
+                    applyStyles(srcChild, destChild);
+                }
+            }
+        };
+        applyStyles(element, clone);
+        return `<!DOCTYPE html><html><body style="margin:0;padding:0;overflow:hidden;background:transparent;">${clone.outerHTML}</body></html>`;
+    }
+    async pngToCanvas(data, width, height) {
+        const blob = new Blob([data], { type: "image/png" });
+        const url = URL.createObjectURL(blob);
+        try {
+            const img = new Image();
+            img.crossOrigin = "anonymous";
+            await new Promise((resolve, reject) => {
+                img.onload = resolve;
+                img.onerror = reject;
+                img.src = url;
+            });
+            const canvas = document.createElement("canvas");
+            canvas.width = width;
+            canvas.height = height;
+            const ctx = canvas.getContext("2d");
+            if (ctx) {
+                ctx.drawImage(img, 0, 0);
+            }
+            return canvas;
+        }
+        finally {
+            URL.revokeObjectURL(url);
+        }
+    }
+    async render(options) {
+        if (options.value) {
+            const values = Array.isArray(options.value)
+                ? options.value
+                : [options.value];
+            const processedValues = [];
+            let hasElement = false;
+            for (const val of values) {
+                if (val instanceof HTMLElement) {
+                    processedValues.push(this.serializeElement(val));
+                    hasElement = true;
+                }
+                else {
+                    processedValues.push(val);
+                }
+            }
+            if (hasElement) {
+                options = {
+                    ...options,
+                    value: Array.isArray(options.value)
+                        ? processedValues
+                        : processedValues[0],
+                };
+            }
+        }
+        return super.render(options);
+    }
     static async defaultResourceResolver(resource, baseUrl, userAgent) {
         try {
             if (resource.url.startsWith("provider:google-fonts")) {

package/dist/jsdom.d.ts

@@ -0,0 +1,41 @@
+export interface HydrateOptions {
+    /**
+     * Target URL or raw HTML string to render.
+     */
+    src: string;
+    /**
+     * Base URL for resolving relative paths and fetching resources.
+     * Recommended when passing raw HTML.
+     */
+    baseUrl?: string;
+    /**
+     * Wait condition for hydration to complete.
+     * - number: Wait for specified milliseconds
+     * - function: Polling function that receives the window object and returns true when done
+     * - "networkidle": Waits until network requests settle (basic implementation)
+     */
+    waitUntil?: number | ((window: any) => boolean | Promise<boolean>) | "networkidle";
+    /**
+     * Maximum time to wait in milliseconds. Default: 10000ms.
+     */
+    timeout?: number;
+    /**
+     * Callback to mock or inject missing browser APIs (e.g. matchMedia, IntersectionObserver)
+     * before the HTML is parsed and scripts are executed.
+     */
+    beforeParse?: (window: any) => void | Promise<void>;
+    /**
+     * If true, forwards console.log/error from JSDOM to the Node.js console.
+     */
+    forwardConsole?: boolean;
+    /**
+     * If true, removes all <script> tags from the final HTML before returning.
+     * Default: true.
+     */
+    removeScripts?: boolean;
+}
+/**
+ * Hydrates an HTML string or URL using JSDOM and returns the final rendered HTML.
+ * Note: Requires 'jsdom' to be installed as a peer dependency.
+ */
+export declare function getHtml(options: HydrateOptions): Promise<string>;