satoru-render 0.0.25 → 1.0.0

package/README.md

@@ -352,6 +352,10 @@ npx satoru-render input.html -f webp --verbose
 | `url`             | `string`                                   | URL to fetch HTML from.                                 |
 | `width`           | `number`                                   | **Required.** Output width in pixels.                   |
 | `height`          | `number`                                   | Output height. Default: `0` (auto-calculate).           |
+| `crop`            | `{ x, y, width, height }`                  | Crop parameters to extract a specific region.           |
+| `outputWidth`     | `number`                                   | Target output width when scaling the image.             |
+| `outputHeight`    | `number`                                   | Target output height when scaling the image.            |
+| `fit`             | `"contain" \| "cover" \| "fill"`           | Resizing behavior when output scale differs.            |
 | `format`          | `"svg" \| "png" \| "webp" \| "pdf"`        | Output format. Default: `"svg"`.                        |
 | `resolveResource` | `ResourceResolver`                         | Async callback to fetch assets (fonts, images, CSS).    |
 | `fonts`           | `Object[]`                                 | Pre-load fonts: `[{ name, data: Uint8Array }]`.         |

package/dist/core.d.ts

@@ -14,8 +14,8 @@ export interface SatoruModule {
     set_log_level: (level: number) => void;
     init_document: (inst: any, html: string, width: number, height: number) => void;
     layout_document: (inst: any, width: number) => void;
-    render_from_state: (inst: any, width: number, height: number, format: number, svgTextToPaths: boolean) => Uint8Array | null;
-    render: (inst: any, htmls: string | string[], width: number, height: number, format: number, svgTextToPaths: boolean) => Uint8Array | null;
+    render_from_state: (inst: any, width: number, height: number, format: number, options: any) => Uint8Array | null;
+    render: (inst: any, htmls: string | string[], width: number, height: number, format: number, options: any) => Uint8Array | null;
     merge_pdfs: (inst: any, pdfs: Uint8Array[]) => Uint8Array | null;
     onLog?: (level: LogLevel, message: string) => void;
     logLevel: LogLevel;
@@ -27,12 +27,28 @@ export interface RequiredResource {
     characters?: string;
     redraw_on_ready?: boolean;
 }
-export type ResourceResolver = (resource: RequiredResource, defaultResolver: (resource: RequiredResource) => Promise<Uint8Array | null>) => Promise<Uint8Array | ArrayBufferView | null>;
+export interface ResolvedFontResult {
+    css: Uint8Array;
+    fonts: {
+        url: string;
+        data: Uint8Array;
+    }[];
+}
+export type ResourceResolver = (resource: RequiredResource, defaultResolver: (resource: RequiredResource) => Promise<Uint8Array | ResolvedFontResult | null>) => Promise<Uint8Array | ArrayBufferView | ResolvedFontResult | null>;
 export interface RenderOptions {
     value?: string | string[] | any | any[];
     url?: string;
     width: number;
     height?: number;
+    crop?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    outputWidth?: number;
+    outputHeight?: number;
+    fit?: "contain" | "cover" | "fill";
     format?: "svg" | "png" | "webp" | "pdf";
     textToPaths?: boolean;
     resolveResource?: ResourceResolver;
@@ -55,11 +71,12 @@ export interface RenderOptions {
     onLog?: (level: LogLevel, message: string) => void;
 }
 export declare const DEFAULT_FONT_MAP: Record<string, string>;
-export declare function resolveGoogleFonts(resource: RequiredResource, userAgent?: string): Promise<Uint8Array | null>;
+export declare function resolveGoogleFonts(resource: RequiredResource, userAgent?: string): Promise<ResolvedFontResult | Uint8Array | null>;
 export declare abstract class SatoruBase {
     private factory;
     private modPromise?;
     protected currentFontMap: Record<string, string>;
+    private resourceCache;
     protected constructor(factory: any);
     private getModule;
     initDocument(options: Omit<RenderOptions, "value"> & {
@@ -69,12 +86,21 @@ export declare abstract class SatoruBase {
     renderFromState(inst: any, options: {
         width: number;
         height?: number;
+        crop?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        outputWidth?: number;
+        outputHeight?: number;
+        fit?: "contain" | "cover" | "fill";
         format?: "svg" | "png" | "webp" | "pdf";
         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 resolveDefaultResource(resource: RequiredResource, baseUrl?: string, userAgent?: string): Promise<Uint8Array | ResolvedFontResult | null>;
     protected abstract fetchHtml(url: string, userAgent?: string): Promise<string>;
     render(options: RenderOptions & {
         format: "png" | "webp" | "pdf";

package/dist/core.js

@@ -8,6 +8,66 @@ export const DEFAULT_FONT_MAP = {
     emoji: "https://cdn.jsdelivr.net/npm/@fontsource/noto-color-emoji/files/noto-color-emoji-emoji-400-normal.woff2",
     "Noto Color Emoji": "https://cdn.jsdelivr.net/npm/@fontsource/noto-color-emoji/files/noto-color-emoji-emoji-400-normal.woff2",
 };
+/**
+ * Parse unicode-range string into an array of [start, end] codepoint ranges.
+ * e.g. "U+0000-00FF, U+0131" → [[0x0000, 0x00FF], [0x0131, 0x0131]]
+ */
+function parseUnicodeRanges(rangeStr) {
+    const ranges = [];
+    for (const part of rangeStr.split(",")) {
+        const m = part.trim().match(/U\+([0-9A-Fa-f?]+)(?:-([0-9A-Fa-f]+))?/);
+        if (!m)
+            continue;
+        if (m[1].includes("?")) {
+            // Wildcard range: U+4?? means U+400-U+4FF
+            const lo = parseInt(m[1].replace(/\?/g, "0"), 16);
+            const hi = parseInt(m[1].replace(/\?/g, "F"), 16);
+            ranges.push([lo, hi]);
+        }
+        else {
+            const start = parseInt(m[1], 16);
+            const end = m[2] ? parseInt(m[2], 16) : start;
+            ranges.push([start, end]);
+        }
+    }
+    return ranges;
+}
+/**
+ * Check if any character's codepoint falls within the given unicode ranges.
+ */
+function hasMatchingCodepoint(ranges, characters) {
+    for (let i = 0; i < characters.length; i++) {
+        const cp = characters.codePointAt(i);
+        if (cp > 0xffff)
+            i++; // skip surrogate pair
+        for (const [start, end] of ranges) {
+            if (cp >= start && cp <= end)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parse @font-face blocks from CSS text, extracting src url and unicode-range.
+ */
+function parseFontFaceBlocks(cssText) {
+    const blocks = [];
+    const blockRegex = /@font-face\s*\{([^}]+)\}/g;
+    let blockMatch;
+    while ((blockMatch = blockRegex.exec(cssText)) !== null) {
+        const body = blockMatch[1];
+        const srcMatch = body.match(/src:\s*url\(([^)]+)\)/);
+        const rangeMatch = body.match(/unicode-range:\s*([^;]+)/);
+        if (srcMatch) {
+            const url = srcMatch[1].replace(/['"]/g, "").trim();
+            blocks.push({
+                url,
+                unicodeRange: rangeMatch ? rangeMatch[1].trim() : null,
+            });
+        }
+    }
+    return blocks;
+}
 export async function resolveGoogleFonts(resource, userAgent) {
     if (!resource.url.startsWith("provider:google-fonts"))
         return null;
@@ -40,8 +100,46 @@ export async function resolveGoogleFonts(resource, userAgent) {
         const resp = await fetch(googleFontUrl, { headers });
         if (!resp.ok)
             return null;
-        const buf = await resp.arrayBuffer();
-        return new Uint8Array(buf);
+        const cssText = await resp.text();
+        const cssBuf = new TextEncoder().encode(cssText);
+        // Parse @font-face blocks with their unicode-range
+        const blocks = parseFontFaceBlocks(cssText);
+        if (blocks.length === 0) {
+            return cssBuf;
+        }
+        // Filter blocks by unicode-range if characters are available
+        let filteredBlocks = blocks;
+        if (text && text.length > 0) {
+            filteredBlocks = blocks.filter((block) => {
+                if (!block.unicodeRange)
+                    return true; // no range = always include
+                const ranges = parseUnicodeRanges(block.unicodeRange);
+                return hasMatchingCodepoint(ranges, text);
+            });
+        }
+        if (filteredBlocks.length === 0) {
+            // No matching subsets - still return CSS for C++ to parse
+            return cssBuf;
+        }
+        // Prefetch only the matching font binaries in parallel
+        const fontResults = await Promise.all(filteredBlocks.map(async (block) => {
+            try {
+                const fontResp = await fetch(block.url, { headers });
+                if (!fontResp.ok)
+                    return null;
+                const buf = await fontResp.arrayBuffer();
+                return { url: block.url, data: new Uint8Array(buf) };
+            }
+            catch {
+                return null;
+            }
+        }));
+        const fonts = [];
+        for (const f of fontResults) {
+            if (f !== null)
+                fonts.push(f);
+        }
+        return { css: cssBuf, fonts };
     }
     catch {
         return null;
@@ -51,6 +149,7 @@ export class SatoruBase {
     factory;
     modPromise;
     currentFontMap = DEFAULT_FONT_MAP;
+    resourceCache = new Map();
     constructor(factory) {
         this.factory = factory;
     }
@@ -129,7 +228,16 @@ export class SatoruBase {
             pdf: 3,
         };
         const format = formatMap[options.format ?? "svg"] ?? 0;
-        const result = mod.render_from_state(inst, options.width, options.height ?? 0, format, options.textToPaths ?? true);
+        const result = mod.render_from_state(inst, options.width, options.height ?? 0, format, {
+            svgTextToPaths: options.textToPaths ?? true,
+            outputWidth: options.outputWidth ?? 0,
+            outputHeight: options.outputHeight ?? 0,
+            fitType: options.fit === "cover" ? 1 : options.fit === "fill" ? 2 : 0,
+            cropX: options.crop?.x ?? 0,
+            cropY: options.crop?.y ?? 0,
+            cropWidth: options.crop?.width ?? 0,
+            cropHeight: options.crop?.height ?? 0,
+        });
         if (!result) {
             if (options.format === "svg")
                 return "";
@@ -229,6 +337,58 @@ export class SatoruBase {
                     return await options.resolveResource(r, defaultResolver);
                 }
                 : defaultResolver;
+            const cachedResolver = async (r) => {
+                const cacheKey = `${r.type}:${r.url}:${r.characters ?? ""}`;
+                const cached = this.resourceCache.get(cacheKey);
+                if (cached)
+                    return cached;
+                const result = await resolver(r);
+                if (result) {
+                    if (result instanceof Uint8Array) {
+                        this.resourceCache.set(cacheKey, result);
+                    }
+                    else if ("css" in result &&
+                        "fonts" in result) {
+                        this.resourceCache.set(cacheKey, result);
+                    }
+                }
+                return result;
+            };
+            const loadResourceData = (r, uint8) => {
+                if (r.type === "image" &&
+                    typeof createImageBitmap !== "undefined" &&
+                    typeof OffscreenCanvas !== "undefined") {
+                    return (async () => {
+                        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) {
+                            // fall through
+                        }
+                        let typeInt = 1;
+                        if (r.type === "image")
+                            typeInt = 2;
+                        if (r.type === "css")
+                            typeInt = 3;
+                        mod.add_resource(instancePtr, r.url, typeInt, uint8);
+                    })();
+                }
+                let typeInt = 1;
+                if (r.type === "image")
+                    typeInt = 2;
+                if (r.type === "css")
+                    typeInt = 3;
+                mod.add_resource(instancePtr, r.url, typeInt, uint8);
+            };
             const inputHtmls = Array.isArray(value) ? value : [value];
             const processedHtmls = [];
             const resolvedResources = new Set();
@@ -253,36 +413,33 @@ export class SatoruBase {
                             }
                             const key = `${r.type}:${r.url}:${r.characters ?? ""}`;
                             resolvedResources.add(key);
-                            const data = await resolver({ ...r });
-                            if (data &&
-                                (data instanceof Uint8Array || ArrayBuffer.isView(data))) {
+                            const data = await cachedResolver({ ...r });
+                            if (!data)
+                                return;
+                            // Handle ResolvedFontResult (CSS + prefetched font binaries)
+                            if (typeof data === "object" &&
+                                "css" in data &&
+                                "fonts" in data) {
+                                const fontResult = data;
+                                // Load the CSS first so C++ can parse @font-face
+                                mod.add_resource(instancePtr, r.url, 1, // Font type
+                                fontResult.css);
+                                // Then load all prefetched font binaries directly
+                                for (const font of fontResult.fonts) {
+                                    const fontKey = `font:${font.url}:`;
+                                    resolvedResources.add(fontKey);
+                                    mod.add_resource(instancePtr, font.url, 1, // Font type
+                                    font.data);
+                                }
+                                return;
+                            }
+                            // Handle regular Uint8Array / ArrayBufferView
+                            if (data instanceof Uint8Array ||
+                                ArrayBuffer.isView(data)) {
                                 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) {
-                                    }
-                                }
-                                let typeInt = 1;
-                                if (r.type === "image")
-                                    typeInt = 2;
-                                if (r.type === "css")
-                                    typeInt = 3;
-                                mod.add_resource(instancePtr, r.url, typeInt, uint8);
+                                await loadResourceData(r, uint8);
                             }
                         }
                         catch (e) {
@@ -310,7 +467,16 @@ export class SatoruBase {
                 webp: 2,
                 pdf: 3,
             };
-            const result = mod.render(instancePtr, processedHtmls, width, height, formatMap[format] ?? 0, options.textToPaths ?? true);
+            const result = mod.render(instancePtr, processedHtmls, width, height, formatMap[format] ?? 0, {
+                svgTextToPaths: options.textToPaths ?? true,
+                outputWidth: options.outputWidth ?? 0,
+                outputHeight: options.outputHeight ?? 0,
+                fitType: options.fit === "cover" ? 1 : options.fit === "fill" ? 2 : 0,
+                cropX: options.crop?.x ?? 0,
+                cropY: options.crop?.y ?? 0,
+                cropWidth: options.crop?.width ?? 0,
+                cropHeight: options.crop?.height ?? 0,
+            });
             if (!result) {
                 if (format === "svg")
                     return "";

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SatoruBase, RequiredResource, RenderOptions } from "./core.js";
+import { SatoruBase, RequiredResource, ResolvedFontResult, RenderOptions } from "./core.js";
 export * from "./core.js";
 export * from "./log-level.js";
 export type { SatoruWorker } from "./child-workers.js";
@@ -21,7 +21,7 @@ export declare class Satoru extends SatoruBase {
         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>;
+    static defaultResourceResolver(resource: RequiredResource, baseUrl?: string, userAgent?: string): Promise<Uint8Array | ResolvedFontResult | null>;
+    protected resolveDefaultResource(resource: RequiredResource, baseUrl?: string, userAgent?: string): Promise<Uint8Array | ResolvedFontResult | null>;
     protected fetchHtml(url: string, userAgent?: string): Promise<string>;
 }

package/dist/node.d.ts

@@ -1,10 +1,10 @@
-import { SatoruBase, RequiredResource } from "./core.js";
+import { SatoruBase, RequiredResource, ResolvedFontResult } 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>;
-    static defaultResourceResolver(resource: RequiredResource, baseUrl?: string, userAgent?: string): Promise<Uint8Array | null>;
-    protected resolveDefaultResource(resource: RequiredResource, baseUrl?: string, userAgent?: string): Promise<Uint8Array | null>;
+    static defaultResourceResolver(resource: RequiredResource, baseUrl?: string, userAgent?: string): Promise<Uint8Array | ResolvedFontResult | null>;
+    protected resolveDefaultResource(resource: RequiredResource, baseUrl?: string, userAgent?: string): Promise<Uint8Array | ResolvedFontResult | null>;
     protected fetchHtml(url: string, userAgent?: string): Promise<string>;
 }