satoru-render 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SoraKumo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the \"Software\"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# Satoru Wasm: High-Performance HTML to SVG/PNG/PDF Engine
+
+[![Playground](https://img.shields.io/badge/Demo-Playground-blueviolet)](https://sorakumo001.github.io/satoru/)
+
+**Satoru** is a portable, WebAssembly-powered HTML rendering engine. It combines the **Skia Graphics Engine** and **litehtml** to provide high-quality, pixel-perfect SVG, PNG, and PDF generation entirely within WebAssembly.
+
+## 🚀 Project Status: High-Fidelity Rendering & Edge Ready
+
+The engine supports full text layout with custom fonts, complex CSS styling, and efficient binary data transfer. It is now compatible with **Cloudflare Workers (workerd)**, allowing for serverless, edge-side image and document generation.
+
+### Key Capabilities
+
+- **Pure Wasm Pipeline**: Performs all layout and drawing operations inside Wasm. Zero dependencies on browser DOM or `<canvas>`.
+- **Edge Native**: Specialized wrapper for Cloudflare Workers ensures smooth execution in restricted environments.
+- **Triple Output Modes**:
+  - **SVG**: Generates lean, vector-based Pure SVG strings with post-processed effects (Filters, Gradients).
+  - **PNG**: Generates high-quality raster images via Skia, transferred as binary data for maximum performance.
+  - **PDF**: Generates high-fidelity vector documents via Skia's PDF backend, including native support for text, gradients, images, and **multi-page output**.
+- **High-Level TS Wrapper**: Includes a `Satoru` class that abstracts Wasm memory management and provides a clean async API.
+- **Dynamic Font Loading**: Supports loading `.ttf` / `.woff2` / `.ttc` files at runtime with automatic weight/style inference.
+- **Japanese Support**: Full support for Japanese rendering with multi-font fallback logic.
+- **Image Format Support**: Native support for **PNG**, **JPEG**, **WebP**, **AVIF**, **GIF**, **BMP**, and **ICO** image formats.
+- **Advanced CSS Support**:
+  - **Box Model**: Margin, padding, border, and accurate **Border Radius**.
+  - **Box Shadow**: High-quality **Outer** and **Inset** shadows using advanced SVG filters (SVG) or Skia blurs (PNG/PDF).
+  - **Gradients**: Linear, **Elliptical Radial**, and **Conic** (Sweep) gradient support.
+  - **Standard Tags**: Full support for `<b>`, `<strong>`, `<i>`, `<u>`, and `<h1>`-`<h6>` via integrated master CSS.
+  - **Text Decoration**: Supports `underline`, `line-through`, `overline` with `solid`, `dotted`, and `dashed` styles.
+  - **Text Shadow**: Multiple shadows with blur, offset, and color support (PNG/SVG/PDF).
+
+## 🛠️ Usage (TypeScript)
+
+### Standard Environment (Node.js / Browser)
+
+Satoru provides a high-level `render` function for converting HTML to various formats. It automatically handles WASM instantiation and resource resolution.
+
+#### Basic Rendering (Automatic Resource Resolution)
+
+The `render` function supports automated multi-pass resource resolution. It identifies missing fonts, images, and external CSS and requests them via the `resolveResource` callback.
+
+```typescript
+import { render, LogLevel } from "satoru-render";
+
+const html = `
+  <style>
+    @font-face {
+      font-family: 'Roboto';
+      src: url('https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu4mxK.woff2');
+    }
+  </style>
+  <div style="font-family: 'Roboto'; color: #2196F3; font-size: 40px;">
+    Hello Satoru!
+    <img src="logo.png" style="width: 50px;">
+  </div>
+`;
+
+// Render to PDF with automatic resource resolution from HTML string
+const pdf = await render({
+  value: html,
+  width: 600,
+  format: "pdf",
+  baseUrl: "https://example.com/assets/", // Optional: resolve relative URLs
+  logLevel: LogLevel.Info,
+  resolveResource: async (resource, defaultResolver) => {
+    if (resource.url.startsWith("custom://")) {
+      return myCustomData;
+    }
+    return defaultResolver(resource);
+  },
+});
+
+// Render from a URL directly
+const png = await render({
+  url: "https://example.com/page.html",
+  width: 1024,
+  format: "png",
+});
+```
+
+#### Render Options
+
+| Option            | Type                                | Description                                                                                                                                                                                             |
+| ----------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`           | `string \| string[]`                | HTML string or array of HTML strings. (One of `value` or `url` is required)                                                                                                                             |
+| `url`             | `string`                            | URL to fetch HTML from. (One of `value` or `url` is required)                                                                                                                                           |
+| `width`           | `number`                            | **Required.** Width of the output in pixels.                                                                                                                                                            |
+| `height`          | `number`                            | Height of the output in pixels. Default is `0` (automatic height).                                                                                                                                      |
+| `format`          | `"svg" \| "png" \| "webp" \| "pdf"` | Output format. Default is `"svg"`.                                                                                                                                                                      |
+| `textToPaths`     | `boolean`                           | Whether to convert SVG text to paths. Default is `true`.                                                                                                                                                |
+| `resolveResource` | `ResourceResolver`                  | Async callback to fetch missing fonts, images, or CSS. Returns `Uint8Array`, `ArrayBufferView` or `null`. It receives a second argument `defaultResolver` to fallback to the standard resolution logic. |
+| `fonts`           | `Object[]`                          | Array of `{ name, data: Uint8Array }` to pre-load fonts.                                                                                                                                                |
+| `images`          | `Object[]`                          | Array of `{ name, url, width?, height? }` to pre-load images.                                                                                                                                           |
+| `css`             | `string`                            | Extra CSS to inject into the rendering process.                                                                                                                                                         |
+| `baseUrl`         | `string`                            | Base URL used to resolve relative URLs in fonts, images, and links.                                                                                                                                     |
+| `userAgent`       | `string`                            | User-Agent header for fetching resources (Node.js environment).                                                                                                                                         |
+| `logLevel`        | `LogLevel`                          | Logging verbosity (`None`, `Error`, `Warning`, `Info`, `Debug`).                                                                                                                                        |
+| `onLog`           | `(level, msg) => void`              | Custom callback for receiving log messages.                                                                                                                                                             |
+
+### 💻 CLI Usage
+
+Satoru includes a command-line interface for easy conversion.
+
+```bash
+# Convert a local HTML file to PNG
+npx satoru-render input.html -o output.png
+
+# Convert a URL to PDF
+npx satoru-render https://example.com -o example.pdf -w 1280
+
+# Convert with custom options
+npx satoru-render input.html -w 1024 -f webp --verbose
+```
+
+#### CLI Options
+
+- `<input>`: Input file path or URL (**Required**)
+- `-o, --output <path>`: Output file path
+- `-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`
+- `--verbose`: Enable detailed logging
+- `--help`: Show help message
+
+### 📄 Multi-page PDF Generation
+
+You can generate a multi-page PDF by passing an array of HTML strings to the `value` property. Each string in the array will be rendered as a new page.
+
+```typescript
+const pdf = await satoru.render({
+  value: [
+    "<h1>Page 1</h1><p>First page content.</p>",
+    "<h1>Page 2</h1><p>Second page content.</p>",
+    "<h1>Page 3</h1><p>Third page content.</p>",
+  ],
+  width: 600,
+  format: "pdf",
+});
+```
+
+### ☁️ Cloudflare Workers (Edge)
+
+Satoru is optimized for Cloudflare Workers. Use the `workerd` specific export which handles the specific WASM instantiation requirements of the environment.
+
+```typescript
+import { render } from "satoru-render";
+
+export default {
+  async fetch(request) {
+    const pdf = await render({
+      value: "<h1>Edge Rendered</h1>",
+      width: 800,
+      format: "pdf",
+      baseUrl: "https://example.com/",
+    });
+
+    return new Response(pdf, {
+      headers: { "Content-Type": "application/pdf" },
+    });
+  },
+};
+```
+
+### 📦 Single-file (Embedded WASM)
+
+For environments where deploying a separate `.wasm` file is difficult, use the `single` export which includes the WASM binary embedded.
+
+```typescript
+import { render } from "satoru-render";
+
+const png = await render({
+  value: "<div>Embedded WASM!</div>",
+  width: 600,
+  format: "png",
+});
+```
+
+### 🧵 Multi-threaded Rendering (Worker Proxy)
+
+For high-throughput applications, the Worker proxy distributes rendering tasks across multiple threads. You can configure all resources in a single `render` call for stateless operation.
+
+```typescript
+import { createSatoruWorker, LogLevel } from "satoru-render/workers";
+
+// Create a worker proxy with up to 4 parallel instances
+const satoru = createSatoruWorker({ maxParallel: 4 });
+
+// Render with full configuration in one go
+const png = await satoru.render({
+  value: "<h1>Parallel Rendering</h1><img src='icon.png'>",
+  width: 800,
+  format: "png",
+  baseUrl: "https://example.com/assets/",
+  logLevel: LogLevel.Debug, // Enable debug logs for this task
+  fonts: [{ name: "CustomFont", data: fontData }], // Pre-load fonts
+  css: "h1 { color: red; }", // Inject extra CSS
+});
+```
+
+## 📜 License
+
+MIT License

package/dist/child-workers.d.ts

@@ -0,0 +1,6 @@
+import { type RenderOptions } from "./single.js";
+declare const map: {
+    render(options: RenderOptions): Promise<string | Uint8Array<ArrayBufferLike>>;
+};
+export type SatoruWorker = typeof map;
+export {};

package/dist/child-workers.js

@@ -0,0 +1,20 @@
+import { initWorker } from "worker-lib";
+import { Satoru } from "./single.js";
+let satoru;
+const getSatoru = async () => {
+    if (!satoru) {
+        satoru = await Satoru.create();
+    }
+    return satoru;
+};
+/**
+ * Worker-side implementation for Satoru.
+ * Exposes Satoru methods via worker-lib.
+ */
+const actions = {
+    async render(options) {
+        const s = await getSatoru();
+        return await s.render(options);
+    },
+};
+const map = initWorker(actions);

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { Satoru, LogLevel } from "./single.js";
+async function main() {
+    const args = process.argv.slice(2);
+    const options = {
+        width: 800,
+        format: "png",
+    };
+    let input;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "-w" || arg === "--width") {
+            options.width = parseInt(args[++i]);
+        }
+        else if (arg === "-h" || arg === "--height") {
+            options.height = parseInt(args[++i]);
+        }
+        else if (arg === "-f" || arg === "--format") {
+            options.format = args[++i];
+        }
+        else if (arg === "-o" || arg === "--output") {
+            options.output = args[++i];
+        }
+        else if (arg === "--verbose") {
+            options.verbose = true;
+        }
+        else if (arg === "--help") {
+            printHelp();
+            return;
+        }
+        else if (!arg.startsWith("-")) {
+            input = arg;
+        }
+    }
+    if (!input) {
+        console.error("Error: Input file or URL is required.");
+        printHelp();
+        process.exit(1);
+    }
+    const isUrl = /^[a-z][a-z0-9+.-]*:/i.test(input) && !input.startsWith("data:");
+    if (!options.output) {
+        const ext = `.${options.format}`;
+        if (isUrl) {
+            options.output = "output" + ext;
+        }
+        else {
+            const basename = path.basename(input, path.extname(input));
+            options.output = basename + ext;
+        }
+    }
+    // Deduce format from output extension if not explicitly set
+    if (!args.includes("-f") && !args.includes("--format")) {
+        const ext = path.extname(options.output).toLowerCase().slice(1);
+        if (["svg", "png", "webp", "pdf"].includes(ext)) {
+            options.format = ext;
+        }
+    }
+    const satoru = await Satoru.create();
+    const renderOptions = {
+        width: options.width,
+        height: options.height,
+        format: options.format,
+        logLevel: options.verbose ? LogLevel.Debug : LogLevel.None,
+        css: "body { background-color: white; }",
+    };
+    if (options.verbose) {
+        renderOptions.onLog = (level, message) => {
+            console.error(`[Satoru] ${LogLevel[level]}: ${message}`);
+        };
+    }
+    if (isUrl) {
+        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));
+    }
+    try {
+        const result = await satoru.render(renderOptions);
+        fs.writeFileSync(options.output, result);
+        console.log(`Successfully rendered to ${options.output}`);
+    }
+    catch (err) {
+        console.error("Error during rendering:", err);
+        process.exit(1);
+    }
+}
+function printHelp() {
+    console.log(`
+Usage: satoru <input-file-or-url> [options]
+
+Options:
+  -o, --output <path>    Output file path
+  -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
+  --verbose              Enable detailed logging
+  --help                 Show this help message
+`);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/core.d.ts

@@ -0,0 +1,80 @@
+import { LogLevel } from "./log-level.js";
+export interface SatoruModule {
+    create_instance: () => any;
+    destroy_instance: (inst: any) => void;
+    collect_resources: (inst: any, html: string, width: number) => void;
+    get_pending_resources: (inst: any) => string;
+    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_image: (inst: any, name: string, url: string, width: number, height: number) => 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) => 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;
+    onLog?: (level: LogLevel, message: string) => void;
+    logLevel: LogLevel;
+}
+export interface RequiredResource {
+    type: "font" | "css" | "image";
+    url: string;
+    name: string;
+    redraw_on_ready?: boolean;
+}
+export type ResourceResolver = (resource: RequiredResource, defaultResolver: (resource: RequiredResource) => Promise<Uint8Array | null>) => Promise<Uint8Array | ArrayBufferView | null>;
+export interface RenderOptions {
+    value?: string | string[];
+    url?: string;
+    width: number;
+    height?: number;
+    format?: "svg" | "png" | "webp" | "pdf";
+    textToPaths?: boolean;
+    resolveResource?: ResourceResolver;
+    fonts?: {
+        name: string;
+        data: Uint8Array;
+    }[];
+    images?: {
+        name: string;
+        url: string;
+        width?: number;
+        height?: number;
+    }[];
+    css?: string;
+    baseUrl?: string;
+    userAgent?: string;
+    fontMap?: Record<string, string>;
+    logLevel?: LogLevel;
+    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 abstract class SatoruBase {
+    private factory;
+    private modPromise?;
+    protected currentFontMap: Record<string, string>;
+    protected constructor(factory: any);
+    private getModule;
+    initDocument(options: Omit<RenderOptions, "value"> & {
+        html: string;
+    }): Promise<any>;
+    layoutDocument(inst: any, width: number): Promise<void>;
+    renderFromState(inst: any, options: {
+        width: number;
+        height?: number;
+        format?: "svg" | "png" | "webp" | "pdf";
+        textToPaths?: boolean;
+    }): Promise<string | Uint8Array>;
+    destroyInstance(inst: any): 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 & {
+        format: "png" | "webp" | "pdf";
+    }): Promise<Uint8Array>;
+    render(options: RenderOptions & {
+        format?: "svg";
+    }): Promise<string>;
+    render(options: RenderOptions): Promise<string | Uint8Array>;
+}