wasm-html-to-image 1.0.9 → 1.0.11

package/README.md

@@ -123,7 +123,7 @@ npx wasm-html-to-image loader.html -o loader.gif -f gif --animation 2000
 ### Outputs (`format`)
 `png`, `jpeg`, `webp`, `avif`, `jxl`, `apng`, `gif`, `tiff`, `svg`, `pdf`, `thumbhash`, `raw` (uncompressed RGBA).
 
-**Print colors:** `format: "tiff"` keeps RGBA; add `colorSpace: "cmyk"` (CLI: `--color-space cmyk`) to get a CMYK TIFF, or a PDF whose colors and images are DeviceCMYK. The conversion is the plain device formula (no ICC profile), so convert with your print shop's profile if you need exact press colors.
+**Print colors:** `format: "tiff"` keeps RGBA; add `colorSpace: "cmyk"` (CLI: `--color-space cmyk`) to get a CMYK TIFF, or a PDF whose colors and images are DeviceCMYK. The conversion is the plain device formula (no ICC profile), so convert with your print shop's profile if you need exact press colors. For print resolution, add `scale` (CLI: `--scale`): an 8.33in-wide page at 300 dpi is `width: 800, scale: 3.125`, and the TIFF records `96 × scale` ppi (override with `dpi`).
 
 Every call returns a `RenderResult` object:
 ```typescript

package/dist/cli-options.d.ts

@@ -10,6 +10,10 @@ export interface CliFlags {
     baseUrl?: string;
     /** `--color-space <srgb|cmyk>`; absent means the default (srgb). */
     colorSpace?: "srgb" | "cmyk";
+    /** `--scale <n>`; absent means 1. */
+    scale?: number;
+    /** `--dpi <n>`; absent means 96 x scale. */
+    dpi?: number;
     /** `--animation <duration-ms>`; absent means "no keyframe animation". */
     animation?: number;
     /** `--animation-fps <n>`; defaults to 15 when `--animation` is set. */

package/dist/cli-options.js

@@ -86,6 +86,8 @@ export async function buildRenderOptions(input, flags) {
         ...source,
         ...(flags.baseUrl !== undefined ? { baseUrl: flags.baseUrl } : {}),
         ...(flags.colorSpace !== undefined ? { colorSpace: flags.colorSpace } : {}),
+        ...(flags.scale !== undefined ? { scale: flags.scale } : {}),
+        ...(flags.dpi !== undefined ? { dpi: flags.dpi } : {}),
         ...(animation ? { animation } : {}),
     };
 }

package/dist/cli.js

@@ -34,6 +34,8 @@ program
     .option("-q, --quality <number>", "encode quality 0-100 (encode stage only)", (v) => parseFloat(v), 85)
     .option("--base-url <url>", "base URL for relative resources (URL input: defaults to the post-redirect document URL; file input: defaults to the file's directory)")
     .option("--color-space <srgb|cmyk>", "output color space of tiff and pdf (default srgb; cmyk rewrites colors for print, with no ICC profile)", (v) => v.toLowerCase())
+    .option("--scale <n>", "pixel density of raster output from HTML (default 1; 3.125 draws an 800px layout as 2500px)", (v) => parseFloat(v))
+    .option("--dpi <n>", "resolution written to tiff output, in pixels per inch (default 96 x scale)", (v) => parseInt(v, 10))
     .option("--animation <duration-ms>", "sample the document's @keyframes opacity / transform / color animation into an animated WebP / APNG / GIF; one loop duration in ms (webp, apng and gif output only; the CSS animation-duration wins and this value is an upper bound)", (v) => parseInt(v, 10))
     .option("--animation-fps <n>", "animation frame rate (default 15, capped at ~75 frames total; requires --animation)", (v) => parseInt(v, 10))
     .option("--animation-loop <n>", "how many times the animated WebP / APNG / GIF repeats (0 = infinite, the default; 1 = play once; requires --animation)", (v) => parseInt(v, 10))
@@ -70,6 +72,8 @@ program
             quality: options.quality,
             baseUrl: options.baseUrl,
             colorSpace: options.colorSpace,
+            scale: options.scale,
+            dpi: options.dpi,
             animation: options.animation,
             animationFps: options.animationFps,
             animationLoop: options.animationLoop,

package/dist/core-orchestrate.d.ts

@@ -42,6 +42,7 @@ export interface Orchestration {
     onLog: HtmlToImageOptions["onLog"];
     diagnostics: boolean;
     onDiagnostics: HtmlToImageOptions["onDiagnostics"];
+    onLayout: HtmlToImageOptions["onLayout"];
     resolveResource: ResolveResourceHook | undefined;
     mediaType: "screen" | "print";
     textToPaths: boolean | undefined;
@@ -63,6 +64,12 @@ export interface Orchestration {
     fmtInt: number;
     /** Output color space of `tiff` / `pdf`. */
     colorSpace: "srgb" | "cmyk";
+    /** Raster pixel density of HTML input (1 = CSS px). */
+    scale: number;
+    /** TIFF resolution tag in pixels per inch (image input: 96 unless set). */
+    dpi: number;
+    /** The caller's explicit `dpi` (image input has no `scale`, so it falls back to 96). */
+    dpiOption: number | undefined;
     mediaTypeInt: number;
     t0: number;
     diag: DiagState | null;

package/dist/core-orchestrate.js

@@ -34,7 +34,7 @@ export function defaultSpeed(format) {
 }
 /** Build per-call orchestration state (log gate, timings, diag, resolve ctx). */
 export function createOrchestration(module, options) {
-    const { format = "png", quality = 85, speed: speedOption, width, height, crop, fit, value, url, baseUrl, fontMap, userAgent, fallbackFonts, logLevel = LogLevel.None, onLog, diagnostics = false, onDiagnostics, resolveResource, mediaType = "screen", textToPaths, css, fonts: preloadFonts, limits = {}, pdfTitle, pdfAuthor, pdfSubject, pdfKeywords, pdfCreator, pdfProducer, pdfMargin, pdfHeader, pdfFooter, } = options;
+    const { format = "png", quality = 85, speed: speedOption, width, height, crop, fit, value, url, baseUrl, fontMap, userAgent, fallbackFonts, logLevel = LogLevel.None, onLog, diagnostics = false, onDiagnostics, onLayout, resolveResource, mediaType = "screen", textToPaths, css, fonts: preloadFonts, limits = {}, pdfTitle, pdfAuthor, pdfSubject, pdfKeywords, pdfCreator, pdfProducer, pdfMargin, pdfHeader, pdfFooter, } = options;
     // `animation` accepts a boolean (image input: keep frames) or, for HTML
     // input, an object requesting keyframe sampling. The object form turns on
     // the boolean flag for the encode stage and enables the frame path.
@@ -47,6 +47,16 @@ export function createOrchestration(module, options) {
     const animationLoop = Math.max(0, Math.trunc(animationFrames?.loop ?? 0));
     const speed = speedOption ?? defaultSpeed(format);
     const colorSpace = options.colorSpace === "cmyk" ? "cmyk" : "srgb";
+    const scale = options.scale ?? 1;
+    if (!Number.isFinite(scale) || scale <= 0 || scale > 16) {
+        throw new Error(`wasm-html-to-image: scale must be a number in (0, 16], got ${String(options.scale)}`);
+    }
+    if (options.dpi !== undefined &&
+        (!Number.isFinite(options.dpi) || options.dpi < 1 || options.dpi > 65535)) {
+        throw new Error(`wasm-html-to-image: dpi must be a number in [1, 65535], got ${String(options.dpi)}`);
+    }
+    // One CSS px is 1/96 in, so a scaled HTML render carries 96 * scale ppi by default.
+    const dpi = Math.round(options.dpi ?? 96 * scale);
     const fmtInt = format === "tiff" && colorSpace === "cmyk"
         ? TIFF_CMYK_INT
         : FORMAT_INT[format];
@@ -157,6 +167,7 @@ export function createOrchestration(module, options) {
         onLog,
         diagnostics,
         onDiagnostics,
+        onLayout,
         resolveResource,
         mediaType,
         textToPaths,
@@ -174,6 +185,9 @@ export function createOrchestration(module, options) {
         pdfFooter,
         fmtInt,
         colorSpace,
+        scale,
+        dpi,
+        dpiOption: options.dpi,
         mediaTypeInt,
         t0,
         diag,
@@ -248,7 +262,7 @@ export async function resolveHtmlSource(orch) {
  * `imageBytesFromUnknown` (`unknown` in, no `as` casts).
  */
 export async function runImageInput(module, value, orch) {
-    const { format, quality, speed, animation, animationLoop, width, height, crop, fit, fmtInt, colorSpace, t0, emitLog, logged, loggedBinding, addTime, deliverReport, } = orch;
+    const { format, quality, speed, animation, animationLoop, width, height, crop, fit, fmtInt, colorSpace, dpiOption, t0, emitLog, logged, loggedBinding, addTime, deliverReport, } = orch;
     // Narrowed here: caller selected this branch via `isImageInput(value)`.
     const loadImage = module.converter_load_image;
     if (typeof loadImage !== "function")
@@ -343,6 +357,8 @@ export async function runImageInput(module, value, orch) {
         const encodeBinding = module.converter_encode;
         if (typeof encodeBinding !== "function")
             throw loggedBinding("converter_encode");
+        if (format === "tiff")
+            module.converter_set_dpi?.(inst, Math.round(dpiOption ?? 96));
         const encodeStart = now();
         const out = (await encodeBinding(inst, fmtInt, quality, speed, animation, animationLoop));
         addTime("encode", now() - encodeStart);
@@ -376,7 +392,7 @@ export async function runImageInput(module, value, orch) {
  * pre-resolved resources, so it stays a fallback only).
  */
 export async function tryRunHtmlInstance(module, htmls, satoruOpts, defaultFontMap, orch) {
-    const { format, quality, speed, animation, animationFrames, animationLoop, width, height, baseUrl, fontMap, userAgent, fallbackFonts, fmtInt, t0, emitLog, logged, loggedBinding, addTime, deliverReport, resolveCtx, } = orch;
+    const { format, quality, speed, animation, animationFrames, animationLoop, width, height, baseUrl, fontMap, userAgent, fallbackFonts, fmtInt, dpi, t0, emitLog, logged, loggedBinding, addTime, deliverReport, resolveCtx, } = orch;
     const renderBinding = module.satoru_render;
     const encodeBinding = module.converter_encode;
     if (typeof renderBinding !== "function" ||
@@ -392,6 +408,10 @@ export async function tryRunHtmlInstance(module, htmls, satoruOpts, defaultFontM
         await resolveHtmlResources(module, sInst, htmls, width, height, baseUrl, fontMap ?? defaultFontMap, userAgent ?? DEFAULT_USER_AGENT, fallbackFonts, resolveCtx);
         addTime("resolveResources", now() - resolveStart);
         emitLog(LogLevel.Info, "resources resolved");
+        if (orch.onLayout && typeof module.satoru_layout_json === "function") {
+            const page = Array.isArray(htmls) ? htmls[0] : htmls;
+            orch.onLayout(JSON.parse(module.satoru_layout_json(sInst, page, width, height ?? 0, orch.mediaTypeInt)));
+        }
         if (format === "svg" || format === "pdf") {
             const renderStart = now();
             const out = (await renderBinding(sInst, htmls, width, height ?? 0, fmtInt, satoruOpts));
@@ -458,6 +478,8 @@ export async function tryRunHtmlInstance(module, htmls, satoruOpts, defaultFontM
             }
             const outWidth = module.converter_get_width?.(cInst) ?? width;
             const outHeight = module.converter_get_height?.(cInst) ?? height ?? 0;
+            if (format === "tiff")
+                module.converter_set_dpi?.(cInst, dpi);
             const encodeStart = now();
             const out = (await encodeBinding(cInst, fmtInt, quality, speed, animation, animationLoop));
             addTime("encode", now() - encodeStart);

package/dist/core.d.ts

@@ -60,6 +60,21 @@ export interface RenderOptions {
  * - Image input: render stage is skipped; `width`/`height`/`crop`/`fit`
  *   are applied as output resize on the encode stage.
  */
+/** One element's border box from `onLayout` (page coordinates, CSS px). */
+export interface LayoutBox {
+    /** Path of element-child indexes from the root, e.g. "0.1.3". */
+    p: string;
+    /** Lower-case tag name. */
+    t: string;
+    /** `id` attribute ("" when absent). */
+    i: string;
+    /** `class` attribute, truncated ("" when absent). */
+    c: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
 export interface HtmlToImageOptions extends RenderOptions {
     /** Encode quality 0-100 (encode stage only, default 85; ignored for svg/pdf). */
     quality?: number;
@@ -127,6 +142,13 @@ export interface HtmlToImageOptions extends RenderOptions {
     diagnostics?: boolean;
     /** Receives the diagnostics report when `diagnostics` is enabled. */
     onDiagnostics?: (report: RenderDiagnostics) => void;
+    /**
+     * Debug aid for comparing against a reference browser: receives every laid-out element's border
+     * box in page coordinates (HTML input only; `html-to-image` instance pipeline). `p` is the
+     * element's path among element children of the shadow-flattened tree ("0.1.3"), so a browser
+     * walk produces the same keys. Inline boxes are omitted except replaced ones (img, svg, ...).
+     */
+    onLayout?: (boxes: LayoutBox[]) => void;
     /**
      * Override hook for resource resolution, applied to every fetch path
      * (discovery fetches, fallback-font URLs, HTML `url` fetch). Return
@@ -146,6 +168,19 @@ export interface HtmlToImageOptions extends RenderOptions {
     }[];
     /** Safety/performance limits, enforced in JS around resource resolution. */
     limits?: RenderLimits;
+    /**
+     * Pixel density of raster output from HTML input (default `1`). The page is laid out at
+     * `width` CSS px and drawn `scale` times larger, so `scale: 3.125` turns an 800px layout
+     * into a 2500px bitmap (300 dpi for an 8.33in page) with text and shapes re-rasterized
+     * sharply. `width` / `height` / `crop` stay in CSS px; the result's `width` / `height` are
+     * the bitmap size. Range 0-16; ignored for `svg` / `pdf` and for image input.
+     */
+    scale?: number;
+    /**
+     * Resolution written to the `tiff` file, in pixels per inch (default `96 * scale`, rounded:
+     * one CSS px is 1/96 in). A print shop reads the physical size from it.
+     */
+    dpi?: number;
     /**
      * Output color space of `tiff` and `pdf` (default `"srgb"`).
      *

package/dist/core.js

@@ -47,6 +47,7 @@ export async function htmlToImage(module, options) {
         textToPaths: orch.textToPaths,
         mediaTypeInt: orch.mediaTypeInt,
         colorSpace: orch.colorSpace,
+        scale: orch.scale,
         pdfTitle: orch.pdfTitle,
         pdfAuthor: orch.pdfAuthor,
         pdfSubject: orch.pdfSubject,

package/dist/encode-args.d.ts

@@ -17,6 +17,7 @@ export interface FullSatoruOptionsInput {
     textToPaths?: boolean;
     mediaTypeInt: number;
     colorSpace?: "srgb" | "cmyk";
+    scale?: number;
     pdfTitle?: string;
     pdfAuthor?: string;
     pdfSubject?: string;

package/dist/encode-args.js

@@ -45,6 +45,7 @@ export function buildFullSatoruOptions(input) {
         svgTextToPaths: textToPaths ?? true,
         mediaType: mediaTypeInt,
         ...(input.colorSpace === "cmyk" ? { colorSpace: 1 } : {}),
+        ...(input.scale !== undefined && input.scale !== 1 ? { scale: input.scale } : {}),
         pdfTitle: pdfTitle ?? "",
         pdfAuthor: pdfAuthor ?? "",
         pdfSubject: pdfSubject ?? "",