satoru-render 1.0.11 → 1.0.13

package/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## v1.0.13 - 2026-05-19
+
+- **Diagnostics & Tooling**:
+  - [Feature] Stabilize `RenderDiagnostics` schema (version 1) for reliable automated analysis.
+  - [Feature] Add Inspection Workspace to Playground with Resources, Fonts, Timings, and Logs tabs.
+  - [Improvement] Make CLI `--json-report` output deterministic by sorting resources and fonts.
+  - [Improvement] Add regression tests for diagnostics and resource resolution.
+
+## v1.0.12 - 2026-05-18
+
+- **Performance**:
+  - [Optimization] Add performance optimizations for rendering speed.
+
+## v1.0.11 - 2026-05-17
+
+- **Rendering Engine & Text Layout**:
+  - [Feature] Implement text layout measurement engine with vertical writing mode and profiling support.
+  - [Feature] Implement core interfaces and font resolution logic, including Google Fonts resolution.
+- **Core API & Infrastructure**:
+  - [Feature] Implement core Satoru module interface, resource resolution, and C++ API bindings.
+  - [Improvement] Initialize and adjust `satoru-render` package configuration and exports.
+
+## v1.0.10 - 2026-04-26
+
+- **Rendering Capabilities**:
+  - [Feature] Implement PNG, PDF, and SVG rendering engines with Skia-based text and layout management.
+- **Configuration & Build**:
+  - [Improvement] Initialize `package.json` with multi-environment exports.
+
+## v1.0.9 - 2026-04-25
+
+- **Rendering Engine**:
+  - [Feature] Add `backdrop-filter` support via Skia.
+
+## v1.0.7 - 2026-04-24
+
+- **Rendering Engine**:
+  - [Feature] Implement `backdrop-filter` in Skia container.
+  - [Feature] Add initial font rendering infrastructure.
+  - [Feature] Implement PDF and PNG rendering engines using Skia and litehtml integration.
+
+## v1.0.5 - 2026-04-23
+
+- **Core Capabilities**:
+  - [Feature] Implement multi-format rendering supporting PNG, WebP, PDF, and SVG engines.
+
+## v1.0.4 - 2026-04-22
+
+- **Configuration & Build**:
+  - [Improvement] Initialize `package.json` for `satoru-render`.
+
+## v1.0.3 - 2026-04-22
+
+- **Rendering Engine**:
+  - [Feature] Implement core rendering engine including litehtml integration and showcase page scaffolding.
+
+## v1.0.2 - 2026-04-21
+
+- **Rendering Engine**:
+  - [Feature] Implement C++ rendering engine with bridge support and add initial assets.
+  - [Feature] Add WebP renderer support and expand core TypeScript interfaces.
+
+## v0.0.7 - 2026-03-03
+
+- **CSS Support & Rendering**:
+  - [Feature] Add support for CSS gradients in the `border-image` property.
+  - [Feature] Implement full SVG mask rendering, including images and gradients.
+
+## v0.0.6 - 2026-03-03
+
+- **CSS Support**:
+  - [Feature] Implement `object-fit` CSS property for images (reflected in rendering and visual tests).
+
+## v0.0.5 - 2026-03-03
+
+- **General**:
+  - [Improvement] Version bump and cleanup of image rendering debug output.
+
+## v0.0.4 - 2026-02-27
+
+- **Asset Management**:
+  - [Feature] Allow direct asset linking via URL parameters.
+  - [Optimization] Improve asset loading logic.
+
+## v0.0.3 - 2026-02-26
+
+- **Code Quality**:
+  - [Refactor] Format text layout and rendering code for improved readability.
+
+## v0.0.2 - 2026-02-25
+
+- **Performance & Build**:
+  - [Optimization] Optimize WASM builds using Thin LTO and `-O3`.
+  - [Improvement] Improve height handling in core API.
+
+## v0.0.1 - 2026-02-23
+
+- **Architecture & Ecosystem**:
+  - [Feature] Major structural changes including entry point setup for multiple environments (Node, Workers, Deno, etc.).
+  - [Feature] Add Cloudflare OGP generator package and Deno OGP service.
+  - [Feature] Implement automatic font resolution with configurable font map and Google Fonts integration.
+  - [Improvement] Rename package from `satoru` to `satoru-render`.
+
+## v1.0.0 - 2026-02-06
+
+- **Initial Setup & Monorepo**:
+  - [Refactor] Refactor to pnpm monorepo structure.
+  - [Feature] Create initial `@satoru/core` WASM package and add Cloudflare Workers (workerd) support.
+  - [Feature] Add visual regression testing suite and comprehensive HTML/CSS test assets.

package/README.md

@@ -1,16 +1,17 @@
 # Satoru Render: High-Performance HTML to Image/PDF Engine
 
 [![Playground](https://img.shields.io/badge/Demo-Playground-blueviolet)](https://sorakumo001.github.io/satoru/master)
+[![Documentation](https://img.shields.io/badge/Docs-Docusaurus-blue)](https://sorakumo001.github.io/satoru/master/docs/)
 [![npm license](https://img.shields.io/npm/l/satoru-render.svg)](https://www.npmjs.com/package/satoru-render)
 [![npm version](https://img.shields.io/npm/v/satoru-render.svg)](https://www.npmjs.com/package/satoru-render)
 [![npm download](https://img.shields.io/npm/dw/satoru-render.svg)](https://www.npmjs.com/package/satoru-render)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/SoraKumo001/satoru)
 
-**Satoru Render** is a high-fidelity HTML-to-Image/PDF conversion engine built with WebAssembly. It provides a lightweight, dependency-free solution for generating high-quality visuals and documents across **Node.js**, **Cloudflare Workers**, **Deno**, and **Web Browsers**.
+**Satoru Render** is a high-fidelity HTML-to-Image/PDF conversion engine built with WebAssembly. It generates high-quality visuals and documents across **Node.js**, **Cloudflare Workers**, **Deno**, and **Web Browsers** without requiring a headless browser or system-level rendering service.
 
 By combining the **Skia** graphics engine with a custom **litehtml** layout core, Satoru performs all layout and drawing operations entirely within WASM, eliminating the need for headless browsers or system-level dependencies.
 
-![Sample Output](./document/sample01.webp)
+![Sample Output](https://raw.githubusercontent.com/SoraKumo001/satoru/master/packages/satoru/document/sample01.webp)
 
 ## Example
 
@@ -23,7 +24,9 @@ By combining the **Skia** graphics engine with a custom **litehtml** layout core
 
 ---
 
-## 📋 Supported CSS Properties
+## 📋 Tested CSS Feature Coverage
+
+Satoru supports and tests a broad subset of modern CSS. The list below highlights the main feature areas covered by the renderer and visual test suite. For detailed status and known differences, see the [compatibility evidence](https://sorakumo001.github.io/satoru/master/docs/docs/compatibility/).
 
 <details>
 <summary>Click to expand supported properties list</summary>
@@ -177,12 +180,12 @@ const pdf = await render({
 });
 ```
 
-### 3. Edge/Cloudflare Workers
+### 4. Edge/Cloudflare Workers
 
 Use the specialized `workerd` export for serverless environments.
 
 ```typescript
-import { render } from "satoru-render";
+import { render } from "satoru-render/workerd";
 
 export default {
   async fetch(request) {
@@ -197,7 +200,7 @@ export default {
 };
 ```
 
-### 4. Multi-threaded Rendering (Worker Proxy)
+### 5. Multi-threaded Rendering (Worker Proxy)
 
 Distribute rendering tasks across multiple background workers for high-throughput applications.
 
@@ -213,7 +216,7 @@ const png = await satoru.render({
 });
 ```
 
-### 5. preact + tailwind
+### 6. preact + tailwind
 
 - install
 
@@ -261,7 +264,7 @@ const png = await render({
 
 ---
 
-### 6. JSDOM Hydration (For Next.js / SPAs)
+### 7. 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.
 
@@ -295,7 +298,7 @@ const pngBytes = await render({
 });
 ```
 
-### 7. DOM Capture (html2canvas alternative)
+### 8. 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.
 
@@ -320,6 +323,28 @@ const png = await satoru.render({
 });
 ```
 
+### 9. Rendering Diagnostics
+
+Get detailed insights into the rendering process, including resource loading status, font resolution, and performance timings.
+
+```typescript
+import { render } from "satoru-render";
+
+const png = await render({
+  value: "<h1>Hello World</h1>",
+  width: 800,
+  format: "png",
+  diagnostics: true,
+  onDiagnostics: (report) => {
+    console.log(`Version: ${report.version}`);
+    console.log(`Format: ${report.format}`);
+    console.log("Resources:", report.resources);
+    console.log("Fonts:", report.fonts);
+    console.log("Timings:", report.timings);
+  },
+});
+```
+
 ---
 
 ## 💻 CLI Tool
@@ -338,6 +363,16 @@ npx satoru-render https://example.com --no-jsdom -o example.pdf
 
 # WebP conversion with verbose logs
 npx satoru-render input.html -f webp --verbose
+
+# Write rendering diagnostics to a JSON file
+npx satoru-render input.html -o output.png --json-report report.json
+
+# Restrict network access for safer server-side usage
+npx satoru-render https://example.com -o output.png \
+  --timeout 5000 \
+  --max-resource-count 50 \
+  --max-total-resource-bytes 10000000 \
+  --allowed-protocols https:
 ```
 
 ---
@@ -356,13 +391,45 @@ npx satoru-render input.html -f webp --verbose
 | `outputWidth`     | `number`                                   | Output image width. Default: canvas/crop width.         |
 | `outputHeight`    | `number`                                   | Output image height. Default: canvas/crop height.       |
 | `fit`             | `"contain" \| "cover" \| "fill"`           | Fit strategy when canvas/crop size differs from output. |
+| `fitPosition`     | `{ x, y }`                                 | Alignment origin for `contain`/`cover`. Default: center. |
+| `backgroundColor` | `string`                                   | Background color for raster/PDF output.                 |
 | `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 }]`.         |
+| `fallbackFonts`   | `Uint8Array[]`                             | Font data used as fallback faces.                       |
+| `images`          | `Object[]`                                 | Pre-load named images for resource resolution.          |
 | `css`             | `string`                                   | Extra CSS to inject into the document.                  |
 | `baseUrl`         | `string`                                   | Base URL for relative path resolution.                  |
+| `userAgent`       | `string`                                   | User agent used by the default resource resolver.       |
+| `fontMap`         | `Record<string, string>`                   | Override font-family to remote font URL mapping.        |
 | `logLevel`        | `LogLevel`                                 | Verbosity: `None`, `Error`, `Warning`, `Info`, `Debug`. |
 | `mediaType`       | `"screen" \| "print"`                      | CSS media type for `@media` queries. Default: `"screen"`. |
+| `limits`          | `RenderLimits`                             | Timeout, resource size, protocol, and host restrictions. |
+| `profile`         | `boolean`                                  | Collect coarse render timings.                          |
+| `onProfile`       | `(profile) => void`                        | Callback that receives coarse render timings.           |
+| `diagnostics`     | `boolean`                                  | Enable detailed rendering diagnostics. |
+| `onDiagnostics`   | `(report: RenderDiagnostics) => void`      | Callback that receives the full diagnostics report. |
+| `pdfTitle` / `pdfAuthor` | `string`                            | PDF metadata fields.                                    |
+| `pdfMargin`       | `{ top, right, bottom, left }`             | PDF page margins in pixels.                             |
+| `pdfHeader` / `pdfFooter` | `string`                            | PDF header/footer HTML. Supports `{{pageNumber}}` and `{{totalPages}}`. |
+
+For the full API surface, see the [API Reference](https://sorakumo001.github.io/satoru/master/docs/docs/api-reference/).
+
+---
+
+## 📝 Changelog
+
+Please see [CHANGELOG.md](./CHANGELOG.md) for a history of changes.
+
+## 📖 Recipes
+
+- [Production OGP Generation](https://sorakumo001.github.io/satoru/master/docs/docs/recipes/ogp-production/): Caching, safety limits, and diagnostics for high-traffic services.
+
+---
+
+## 🔬 Compatibility Evidence
+
+For a detailed breakdown of CSS feature support and visual test coverage, see the [Compatibility Matrix](https://sorakumo001.github.io/satoru/master/docs/docs/compatibility/).
 
 ---
 

package/dist/cli.js

@@ -24,6 +24,9 @@ async function main() {
         else if (arg === "-o" || arg === "--output") {
             options.output = args[++i];
         }
+        else if (arg === "--json-report") {
+            options.jsonReport = args[++i];
+        }
         else if (arg === "--no-jsdom") {
             options.jsdom = false;
         }
@@ -33,6 +36,27 @@ async function main() {
         else if (arg === "--media") {
             options.mediaType = args[++i];
         }
+        else if (arg === "--timeout") {
+            options.timeout = parseInt(args[++i]);
+        }
+        else if (arg === "--max-resource-bytes") {
+            options.maxResourceBytes = parseInt(args[++i]);
+        }
+        else if (arg === "--max-total-resource-bytes") {
+            options.maxTotalResourceBytes = parseInt(args[++i]);
+        }
+        else if (arg === "--max-resource-count") {
+            options.maxResourceCount = parseInt(args[++i]);
+        }
+        else if (arg === "--allowed-protocols") {
+            options.allowedProtocols = args[++i].split(",");
+        }
+        else if (arg === "--allowed-hosts") {
+            options.allowedHosts = args[++i].split(",");
+        }
+        else if (arg === "--blocked-hosts") {
+            options.blockedHosts = args[++i].split(",");
+        }
         else if (arg === "--help") {
             printHelp();
             return;
@@ -71,8 +95,36 @@ async function main() {
         format: options.format,
         logLevel: options.verbose ? LogLevel.Debug : LogLevel.None,
         mediaType: options.mediaType,
+        limits: {
+            timeoutMs: options.timeout,
+            maxResourceBytes: options.maxResourceBytes,
+            maxTotalResourceBytes: options.maxTotalResourceBytes,
+            maxResourceCount: options.maxResourceCount,
+            allowedProtocols: options.allowedProtocols,
+            allowedHosts: options.allowedHosts,
+            blockedHosts: options.blockedHosts,
+        },
         css: "body { background-color: white; }",
     };
+    if (options.jsonReport) {
+        renderOptions.diagnostics = true;
+        renderOptions.onDiagnostics = (report) => {
+            const deterministicReport = {
+                ...report,
+                timings: { omitted: 1 },
+            };
+            if (deterministicReport.resources) {
+                deterministicReport.resources.sort((a, b) => (a.url || "").localeCompare(b.url || ""));
+            }
+            if (deterministicReport.fonts) {
+                deterministicReport.fonts.sort((a, b) => (a.family || "").localeCompare(b.family || ""));
+            }
+            fs.writeFileSync(options.jsonReport, JSON.stringify(deterministicReport, null, 2));
+            if (options.verbose) {
+                console.error(`[Satoru] Diagnostics report written to ${options.jsonReport}`);
+            }
+        };
+    }
     if (options.verbose) {
         renderOptions.onLog = (level, message) => {
             console.error(`[Satoru] ${LogLevel[level]}: ${message}`);
@@ -155,8 +207,16 @@ 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
+  --json-report <path>   Write diagnostics report to a JSON file
   --no-jsdom             Disable JSDOM hydration (enabled by default)
   --media <type>         Media type: screen, print (default: screen)
+  --timeout <ms>         Rendering timeout in milliseconds
+  --max-resource-bytes <bytes>       Max size for a single resource
+  --max-total-resource-bytes <bytes> Max total size for all resources
+  --max-resource-count <count>       Max number of resources to load
+  --allowed-protocols <list>         Comma-separated allowed protocols (e.g. http:,https:)
+  --allowed-hosts <list>             Comma-separated allowed hostnames
+  --blocked-hosts <list>             Comma-separated blocked hostnames
   --verbose              Enable detailed logging
   --help                 Show this help message
 `);

package/dist/core.d.ts

@@ -3,7 +3,10 @@ export interface SatoruModule {
     create_instance: () => any;
     destroy_instance: (inst: any) => void;
     collect_resources: (inst: any, html: string, width: number, height: number, mediaType: number) => void;
+    get_collect_profile: (inst: any) => string;
+    set_collect_profile_enabled: (inst: any, enabled: boolean) => void;
     get_pending_resources: (inst: any) => Uint8Array | null;
+    get_font_diagnostics: (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;
@@ -20,6 +23,20 @@ export interface SatoruModule {
     onLog?: (level: LogLevel, message: string) => void;
     logLevel: LogLevel;
 }
+export interface WorkerPoolStats {
+    /** Number of workers in the pool */
+    workerCount: number;
+    /** Jobs currently being executed */
+    activeJobs: number;
+    /** Jobs waiting for a free worker */
+    queuedJobs: number;
+    /** Total jobs completed successfully since start */
+    completedJobs: number;
+    /** Total jobs that failed since start */
+    failedJobs: number;
+    /** Average time per job in milliseconds */
+    avgJobTimeMs: number;
+}
 export interface RequiredResource {
     type: "font" | "css" | "image";
     url: string;
@@ -35,7 +52,66 @@ export interface ResolvedFontResult {
     }[];
 }
 export type ResourceResolver = (resource: RequiredResource, defaultResolver: (resource: RequiredResource) => Promise<Uint8Array | ResolvedFontResult | null>) => Promise<Uint8Array | ArrayBufferView | ResolvedFontResult | null>;
+export interface RenderDiagnostics {
+    version: 1;
+    format: "svg" | "png" | "webp" | "pdf";
+    width: number;
+    height?: number;
+    mediaType: "screen" | "print";
+    timings: Record<string, number>;
+    resources: ResourceDiagnostic[];
+    fonts: FontDiagnostic[];
+    warnings: DiagnosticMessage[];
+    errors: DiagnosticMessage[];
+}
+export interface ResourceDiagnostic {
+    type: "font" | "css" | "image";
+    url: string;
+    name?: string;
+    status: "pending" | "loaded" | "failed" | "skipped";
+    bytes?: number;
+    reason?: string;
+}
+export interface FontDiagnostic {
+    family: string;
+    weight?: number;
+    style?: "normal" | "italic" | "oblique";
+    status: "loaded" | "fallback" | "missing";
+    source?: string;
+    characters?: string;
+}
+export interface DiagnosticMessage {
+    code: string;
+    message: string;
+    source?: string;
+}
+export declare const DIAGNOSTIC_CODES: {
+    readonly LIMIT_TIMEOUT: "LIMIT_TIMEOUT";
+    readonly LIMIT_RESOURCE_SIZE: "LIMIT_RESOURCE_SIZE";
+    readonly LIMIT_TOTAL_SIZE: "LIMIT_TOTAL_SIZE";
+    readonly LIMIT_RESOURCE_COUNT: "LIMIT_RESOURCE_COUNT";
+    readonly LIMIT_PROTOCOL_BLOCKED: "LIMIT_PROTOCOL_BLOCKED";
+    readonly LIMIT_HOST_BLOCKED: "LIMIT_HOST_BLOCKED";
+};
+export interface RenderLimits {
+    /** Timeout for the entire render process in milliseconds */
+    timeoutMs?: number;
+    /** Maximum bytes for a single resource */
+    maxResourceBytes?: number;
+    /** Maximum total bytes for all resources */
+    maxTotalResourceBytes?: number;
+    /** Maximum number of resources to load */
+    maxResourceCount?: number;
+    /** Allowed URL protocols (e.g., ["http:", "https:"]) */
+    allowedProtocols?: string[];
+    /** Allowed hostnames (e.g., ["example.com", "fonts.googleapis.com"]) */
+    allowedHosts?: string[];
+    /** Blocked hostnames */
+    blockedHosts?: string[];
+}
 export interface RenderOptions {
+    /** Abort signal to cancel rendering */
+    signal?: AbortSignal;
     /** Input content (HTML string or state object) */
     value?: string | string[] | any | any[];
     /** Source URL */
@@ -87,10 +163,39 @@ export interface RenderOptions {
     onLog?: (level: LogLevel, message: string) => void;
     /** Media type for CSS @media queries (default: "screen") */
     mediaType?: "screen" | "print";
+    /** Rendering limits for safety and performance */
+    limits?: RenderLimits;
     /** Collect coarse render timings for diagnostics */
     profile?: boolean;
     /** Receives coarse render timings when profile is enabled */
     onProfile?: (profile: Record<string, number>) => void;
+    /** Enable full rendering diagnostics */
+    diagnostics?: boolean;
+    /** Receives the full diagnostics report if diagnostics is enabled */
+    onDiagnostics?: (report: RenderDiagnostics) => void;
+    /** PDF Title metadata */
+    pdfTitle?: string;
+    /** PDF Author metadata */
+    pdfAuthor?: string;
+    /** PDF Subject metadata */
+    pdfSubject?: string;
+    /** PDF Keywords metadata */
+    pdfKeywords?: string;
+    /** PDF Creator metadata */
+    pdfCreator?: string;
+    /** PDF Producer metadata */
+    pdfProducer?: string;
+    /** PDF page margins in pixels */
+    pdfMargin?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    /** PDF header HTML template. Supports {{pageNumber}} and {{totalPages}} */
+    pdfHeader?: string;
+    /** PDF footer HTML template. Supports {{pageNumber}} and {{totalPages}} */
+    pdfFooter?: string;
 }
 export declare const DEFAULT_FONT_MAP: Record<string, string>;
 export declare function resolveGoogleFonts(resource: RequiredResource, userAgent?: string): Promise<ResolvedFontResult | Uint8Array | null>;