satoru-render 0.0.18 → 0.0.19

package/README.md

@@ -220,17 +220,56 @@ 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",
+});
+```
+
+---
+
 ## 💻 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
 ```

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;
@@ -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/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>;

package/dist/jsdom.js

@@ -0,0 +1,99 @@
+/**
+ * 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 async function getHtml(options) {
+    let jsdomModule;
+    try {
+        jsdomModule = await import("jsdom");
+    }
+    catch (e) {
+        throw new Error("[Satoru] 'jsdom' is required to use hydrateHtml. Please run: npm install jsdom");
+    }
+    const { JSDOM, VirtualConsole } = jsdomModule.default || jsdomModule;
+    const isUrl = /^https?:\/\//.test(options.src);
+    const finalBaseUrl = options.baseUrl || (isUrl ? options.src : "http://localhost/");
+    const virtualConsole = new VirtualConsole();
+    if (options.forwardConsole) {
+        virtualConsole.forwardTo(console);
+    }
+    const jsdomOptions = {
+        runScripts: "dangerously",
+        resources: "usable",
+        pretendToBeVisual: true,
+        url: finalBaseUrl,
+        virtualConsole,
+        beforeParse: (window) => {
+            // Provide basic polyfills often needed by modern frameworks
+            if (!window.fetch) {
+                window.fetch = async (url, opts) => {
+                    const absoluteUrl = new URL(url, finalBaseUrl).href;
+                    return await globalThis.fetch(absoluteUrl, opts);
+                };
+            }
+            window.matchMedia = window.matchMedia || (() => ({
+                matches: false,
+                addListener: () => { },
+                removeListener: () => { },
+                addEventListener: () => { },
+                removeEventListener: () => { },
+                dispatchEvent: () => false,
+            }));
+            window.IntersectionObserver = window.IntersectionObserver || class {
+                observe() { }
+                unobserve() { }
+                disconnect() { }
+            };
+            window.ResizeObserver = window.ResizeObserver || class {
+                observe() { }
+                unobserve() { }
+                disconnect() { }
+            };
+            if (options.beforeParse) {
+                options.beforeParse(window);
+            }
+        },
+    };
+    let dom;
+    if (isUrl) {
+        const { url, ...fromUrlOptions } = jsdomOptions;
+        dom = await JSDOM.fromURL(options.src, fromUrlOptions);
+    }
+    else {
+        dom = new JSDOM(options.src, jsdomOptions);
+    }
+    const timeoutMs = options.timeout || 10000;
+    const startTime = Date.now();
+    const checkWaitCondition = async () => {
+        if (Date.now() - startTime >= timeoutMs) {
+            return true; // Timeout reached
+        }
+        if (typeof options.waitUntil === "number") {
+            return Date.now() - startTime >= options.waitUntil;
+        }
+        if (options.waitUntil === "networkidle") {
+            // Wait at least 2 seconds for heavy sites like Zenn
+            return Date.now() - startTime >= 2000;
+        }
+        if (typeof options.waitUntil === "function") {
+            return await options.waitUntil(dom.window);
+        }
+        // Default: wait a short tick for basic sync scripts
+        return Date.now() - startTime >= 50;
+    };
+    // Polling loop
+    while (!(await checkWaitCondition())) {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    const removeScripts = options.removeScripts ?? true;
+    if (removeScripts) {
+        const scripts = dom.window.document.querySelectorAll("script");
+        scripts.forEach((s) => s.remove());
+    }
+    const finalHtml = dom.serialize();
+    // Cleanup to prevent memory leaks
+    if (dom.window) {
+        dom.window.close();
+    }
+    return finalHtml;
+}