@otisk/preview 1.1.0 → 1.1.2

package/README.md

@@ -1,96 +1,109 @@
-# `engine-wasm` — WASM bindings for otisk
-
-Thin `wasm-bindgen` wrapper around `otisk::Engine`. Exposes a single
-JS-callable entry point so browser (and other `wasm32-unknown-unknown`)
-hosts can drive the otisk pipeline:
-
-```rust
-// Issue 30 baseline + Issue 115 widening: an **optional** 4th argument
-// crosses a JS-side `AssetResolver` into the engine. The 3-arg call
-// `render_pdf(html, css, margin)` remains byte-identical to the
-// Issue 31 parity baseline; passing `null` / `undefined` for the 4th
-// arg is equivalent. When present, `assets` must be either a bare
-// `function(url): Uint8Array` callable or an object with a synchronous
-// `fetch(url): Uint8Array` method — every engine-side `@font-face`,
-// `<img>`, `background-image`, `@color-profile` lookup is funneled
-// through it.
-#[wasm_bindgen]
-pub fn render_pdf(
-    html: &str,
-    css: &str,
-    margin_mm: f32,
-    assets: Option<JsValue>, // bindgen-side: omittable in JS
-) -> Result<Vec<u8>, JsValue>;
+# @otisk/preview
+
+Raster **print-preview** for the [otisk](https://www.npmjs.com/org/otisk)
+typesetting engine, compiled to WebAssembly. Render HTML/CSS pages to RGBA
+bitmaps in the browser (or Bun/Node) and paint them onto an HTML5 canvas —
+the preview shares the **same layout engine** as otisk's PDF output, so what
+you see on screen matches the print geometry pixel-for-pixel; only the
+rasteriser differs (tiny-skia here, the press RIP for the PDF).
+
+This package is **preview-only**: it renders pages to bitmaps for on-screen
+display. It does not generate PDFs — produce the final PDF/X-4 on your
+backend with the otisk engine, from the same `(html, css)` you previewed.
+
+```
+npm i @otisk/preview
 ```
 
-JS call sites:
+## Quick start — paint a page to a canvas
 
 ```js
-// 3-arg legacy form — unchanged, empty resolver.
-const pdf = render_pdf(html, css, 10);
-
-// 4-arg widened form — supply a resolver. `null` / `undefined` are
-// equivalent to omitting the arg.
-const pdf = render_pdf(html, css, 10, {
-    fetch(url) { /* return Uint8Array */ }
-});
-```
+import init, { render_page_rgba } from "@otisk/preview";
+
+await init(); // load the wasm module (once)
 
-See `src/lib.rs` and the issue specs at
-`.plans/pdfx4-engine/issues/30-wasm-bindings-crate.md` (baseline) and
-`.plans/pdfx4-engine/issues/115-wasm-asset-resolver-crossing.md`
-(resolver crossing) for the full rationale.
+const html = "<h1>Náhled sazby</h1><p>Příliš žluťoučký kůň…</p>";
+const css = "@page { size: A6 } body { font-family: serif }";
 
-## Build (browser bundle)
+const dpi = 96;
+const page = render_page_rgba(html, css, /*marginMm*/ 0, null, null, /*pageIndex*/ 0, dpi / 72);
 
-```sh
-wasm-pack build crates/engine-wasm --target web --out-dir ../../examples/web-ui/pkg --release
+const canvas = document.querySelector("canvas");
+canvas.width = page.width;
+canvas.height = page.height;
+canvas
+  .getContext("2d")
+  .putImageData(new ImageData(new Uint8ClampedArray(page.rgba), page.width, page.height), 0, 0);
 ```
 
-This produces `examples/web-ui/pkg/engine_wasm_bg.wasm` plus the
-`engine_wasm.js` glue module. Serve the demo UI with any static server:
+`rgba` is straight (non-premultiplied) RGBA8, row-major, top-down — exactly
+the layout `ImageData` / `createImageBitmap` expect, so there's no per-pixel
+rework.
 
-```sh
-python3 -m http.server 4173 --directory examples/web-ui
-```
+## Recommended — render off the main thread
 
-The `pkg/` output directory is git-ignored.
+Rasterising a page will jank the UI thread. For a live preview (re-rendering
+on every edit), run the wasm in a **Web Worker** that owns an
+`OffscreenCanvas`, so pixels never cross back to the main thread. A complete,
+copy-paste consumer — worker + a `PreviewClient` with latest-wins coalescing —
+lives in the repo at
+[`examples/preview-canvas/`](https://github.com/otisk-engine/otisk/tree/main/examples/preview-canvas).
 
-## Build (raw `.wasm`, no JS glue)
+## API
 
-For CI gate parity with the issue spec — no `wasm-pack` required:
+The default export is the wasm initialiser — `await init()` (or
+`init(customWasmUrl)`) once before calling anything else.
 
-```sh
-cargo build -p engine-wasm --target wasm32-unknown-unknown --locked --release
-```
+### `render_page_rgba(html, css, marginMm, assets?, outputIntent?, pageIndex, scale) → RasterResult`
 
-Artefact at `target/wasm32-unknown-unknown/release/engine_wasm.wasm`.
+Render one page to an RGBA bitmap. `scale` is pixels-per-point (`dpi / 72`);
+`pageIndex` is 0-based. Throws a string error on a layout failure, an
+out-of-range page, or degenerate dimensions.
 
-## Size budget
+### `page_count(html, css, marginMm, assets?, outputIntent?) → number`
 
-`SPECIFICATION.md` §4.2: **5 MB compressed** for the full engine. Phase 2
-ships the raw bundle without `wasm-opt`; binary-size optimization lands in
-Issue 31 / Phase 6. The commit that introduces this crate records the
-current unoptimized `.wasm` size as a baseline.
+How many pages the `(html, css)` pair lays out — for preview navigation.
 
-## Host-target build
+### `RasterResult`
 
-The crate is also exposed as an `rlib` so `cargo build -p engine-wasm`
-on the host triple works (useful for `cargo doc`, future host-side
-integration tests, and IDE indexing). The `cdylib` artefact only matters
-for the `wasm32-unknown-unknown` target.
+| Member     | Type         | Notes                                  |
+| ---------- | ------------ | -------------------------------------- |
+| `width`    | `number`     | Device width in pixels.                |
+| `height`   | `number`     | Device height in pixels.               |
+| `rgba`     | `Uint8Array` | `4 · width · height` bytes, RGBA8.     |
 
-## `parity_export` feature (Issue 31)
+### Asset resolver (`assets`)
 
-The crate ships a second WASM entry point — a raw C-ABI
-`render_pdf_raw` — gated behind the `parity_export` feature. The Phase 2
-parity harness (`crates/otisk/tests/wasm_parity.rs`) builds the artefact
-with `--no-default-features --features parity_export` and drives it
-through `wasmtime` without the `wasm-bindgen` JS glue. This surface is
-**internal** — the wire format is not a stability contract, and browser
-hosts should always use the default `render_pdf`.
+Fonts, images, and color profiles referenced by the CSS/HTML
+(`@font-face`, `<img>`, `background-image`, `@color-profile`) are pulled
+through an optional **synchronous** resolver. Pass `null`/`undefined` to
+disable it, or an object with a `fetch` method (or a bare function):
 
-```sh
-cargo build -p engine-wasm --target wasm32-unknown-unknown \
-    --no-default-features --features parity_export --release
+```js
+const assets = {
+  fetch(url) {
+    return fontBytes.get(url); // must return a Uint8Array, synchronously
+  },
+};
+render_page_rgba(html, css, 0, assets, null, 0, dpi / 72);
 ```
+
+### Output intent (`outputIntent`)
+
+Optional color target for the render: `"srgb"` (default), `"fogra39"`, or
+`"swop_v2"`. Pass `null` for sRGB.
+
+## Notes
+
+- **Module format.** This is the `--target web` build — native ESM that
+  runs in browsers, Bun, and bundlers (Vite/webpack). It is not a CommonJS
+  Node build.
+- **Bundle size.** ~4.8 MB gzipped — fetch it lazily / behind a route split
+  rather than in your initial bundle.
+- **No OffscreenCanvas?** On engines without `transferControlToOffscreen`
+  (older Safari), run `render_page_rgba` on the main thread and
+  `putImageData` as in the quick start.
+
+## License
+
+Apache-2.0

package/engine_wasm.d.ts

@@ -36,7 +36,7 @@ export class RasterResult {
  *
  * # Errors
  *
- * Same channel as [`render_pdf`].
+ * A stringified [`otisk::RenderError`] via `JsValue::from_str`.
  */
 export function page_count(html: string, css: string, margin_mm: number, assets?: any | null, output_intent?: any | null): number;
 
@@ -44,11 +44,10 @@ export function page_count(html: string, css: string, margin_mm: number, assets?
  * Issue 297 — render one page of an `(html, css)` pair to an RGBA8
  * bitmap for an HTML5-canvas print preview.
  *
- * Mirrors [`render_pdf`]'s argument shape (`html`, `css`, `margin_mm`,
- * optional `assets`, optional `output_intent`) and adds `page_index`
- * (0-based) + `scale` (pixels-per-point, `scale = dpi / 72`). The
- * returned [`RasterResult`] carries the device dimensions + the RGBA
- * buffer.
+ * Takes the same `(html, css, margin_mm, assets?, output_intent?)`
+ * inputs the engine's PDF path uses, plus `page_index` (0-based) +
+ * `scale` (pixels-per-point, `scale = dpi / 72`). The returned
+ * [`RasterResult`] carries the device dimensions + the RGBA buffer.
  *
  * Because the preview reuses the **same** layout the PDF path produces,
  * it is guaranteed to match print geometry; only the rasteriser differs
@@ -56,100 +55,11 @@ export function page_count(html: string, css: string, margin_mm: number, assets?
  *
  * # Errors
  *
- * Same channel as [`render_pdf`] (a stringified [`otisk::RenderError`]
- * via `JsValue::from_str`), plus an out-of-range `page_index` or
- * degenerate device dimensions.
+ * A stringified [`otisk::RenderError`] via `JsValue::from_str`, plus an
+ * out-of-range `page_index` or degenerate device dimensions.
  */
 export function render_page_rgba(html: string, css: string, margin_mm: number, assets: any | null | undefined, output_intent: any | null | undefined, page_index: number, scale: number): RasterResult;
 
-/**
- * Render an `(html, css)` pair to a PDF/X-4 byte buffer.
- *
- * Thin shim over [`otisk::Engine`]: builds an engine with `margin_mm`
- * applied uniformly to all four sides (see
- * [`otisk::EngineBuilder::with_margins_mm`]), then forwards to
- * [`otisk::Engine::render`] and returns [`otisk::RenderResult::bytes`].
- *
- * ## Optional asset resolver (Issue 115)
- *
- * The `assets` parameter is **optional**. wasm-bindgen surfaces it as
- * a fourth positional argument that the JS caller may omit (older
- * 3-arg call sites — `render_pdf(html, css, margin)` — keep working
- * unchanged) or pass as `null` / `undefined` for the same behaviour.
- * When `assets` is present it must be either:
- *
- * - a bare callable: `function(url: string): Uint8Array`, or
- * - an object with the spec'd shape: `{ fetch(url: string): Uint8Array }`.
- *
- * Every engine-side asset lookup (`@font-face`, `<img>`,
- * `background-image`, and — Phase 4 — `@color-profile`) is funneled
- * through that callable. If `assets.fetch` returns a non-`Uint8Array`
- * value, throws, or the method doesn't exist, the render fails with
- * [`otisk::FetchError`] surfaced through the usual
- * `JsValue`-stringified error channel.
- *
- * ### Why synchronous
- *
- * The native [`otisk::AssetResolver::fetch`] signature is synchronous
- * (`SPECIFICATION.md` §3.7); the engine never spins up an async
- * runtime to fetch an asset. Mirroring that on the JS side keeps the
- * byte-identity contract trivial — every fetch returns bytes
- * immediately, with the same byte-for-byte semantics on both sides.
- * A `Promise<Uint8Array>` arm would either (a) require an async
- * engine entry point — out of scope for this issue — or (b) demand
- * host-side blocking that the browser doesn't permit on the main
- * thread. The simpler synchronous arm is the load-bearing acceptance
- * criterion (byte-identical parity for `font_face_load`,
- * `image_embed`, `background_image`) and an async overload can ride
- * on top of it later.
- *
- * ## Optional output intent (Issue 116)
- *
- * The `output_intent` parameter is **optional**. wasm-bindgen surfaces it
- * as a fifth positional argument that the JS caller may omit (older
- * 3-arg / 4-arg call sites keep working unchanged) or pass as `null` /
- * `undefined` for the same default behaviour. When `output_intent` is
- * present it must be a UTF-8 string naming a known
- * [`otisk::ColorProfile`] variant — see [`parse_color_profile`] for the
- * accepted spellings (`"srgb"`, `"fogra39"`, `"swop_v2"`,
- * case-insensitive). An unknown string surfaces as the usual
- * `JsValue`-stringified error so the JS caller can react.
- *
- * ## Diagnostics
- *
- * Diagnostics from the render are intentionally dropped on this entry
- * point — the spec deliberately keeps the WASM surface minimal
- * (Issue 30 §"Out of scope"). A richer entry point returning
- * `{ bytes, diagnostics }` is deferred to a future issue once the
- * parity harness has a concrete need for it.
- *
- * # Errors
- *
- * On any failure inside the pipeline ([`otisk::RenderError`] — HTML/CSS
- * parse errors, layout failures, missing fonts, PDF emit errors, or
- * resource-limit breaches), any failure inside the JS-side
- * resolver, or an unrecognised `output_intent` string, the error is
- * stringified via its `Display` impl and returned as a
- * `JsValue::from_str`. JS sees a plain string error message; richer
- * error objects can land alongside the diagnostic surface later.
- *
- * # Parameters
- *
- * - `html`: the input HTML source as a UTF-8 string.
- * - `css`: the matching CSS source (currently the only style input — the
- *   engine has no `<style>` / `<link rel="stylesheet">` extraction yet).
- * - `margin_mm`: uniform page margin applied to all four sides.
- * - `assets` *(optional)*: a `{ fetch(url): Uint8Array }` object or a
- *   bare `(url) -> Uint8Array` callable; pass `null` / `undefined` /
- *   omit entirely for the empty-resolver baseline (byte-identical to
- *   the pre-Issue-115 3-arg call).
- * - `output_intent` *(optional)*: a UTF-8 string naming a known
- *   [`otisk::ColorProfile`] variant (`"srgb"`, `"fogra39"`,
- *   `"swop_v2"`); pass `null` / `undefined` / omit entirely to keep
- *   the engine's default profile ([`ColorProfile::default`] — sRGB).
- */
-export function render_pdf(html: string, css: string, margin_mm: number, assets?: any | null, output_intent?: any | null): Uint8Array;
-
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
@@ -160,7 +70,6 @@ export interface InitOutput {
     readonly rasterresult_rgba: (a: number) => [number, number];
     readonly rasterresult_width: (a: number) => number;
     readonly render_page_rgba: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number, number];
-    readonly render_pdf: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number, number];
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_exn_store: (a: number) => void;

package/engine_wasm.js

@@ -63,7 +63,7 @@ if (Symbol.dispose) RasterResult.prototype[Symbol.dispose] = RasterResult.protot
  *
  * # Errors
  *
- * Same channel as [`render_pdf`].
+ * A stringified [`otisk::RenderError`] via `JsValue::from_str`.
  * @param {string} html
  * @param {string} css
  * @param {number} margin_mm
@@ -87,11 +87,10 @@ export function page_count(html, css, margin_mm, assets, output_intent) {
  * Issue 297 — render one page of an `(html, css)` pair to an RGBA8
  * bitmap for an HTML5-canvas print preview.
  *
- * Mirrors [`render_pdf`]'s argument shape (`html`, `css`, `margin_mm`,
- * optional `assets`, optional `output_intent`) and adds `page_index`
- * (0-based) + `scale` (pixels-per-point, `scale = dpi / 72`). The
- * returned [`RasterResult`] carries the device dimensions + the RGBA
- * buffer.
+ * Takes the same `(html, css, margin_mm, assets?, output_intent?)`
+ * inputs the engine's PDF path uses, plus `page_index` (0-based) +
+ * `scale` (pixels-per-point, `scale = dpi / 72`). The returned
+ * [`RasterResult`] carries the device dimensions + the RGBA buffer.
  *
  * Because the preview reuses the **same** layout the PDF path produces,
  * it is guaranteed to match print geometry; only the rasteriser differs
@@ -99,9 +98,8 @@ export function page_count(html, css, margin_mm, assets, output_intent) {
  *
  * # Errors
  *
- * Same channel as [`render_pdf`] (a stringified [`otisk::RenderError`]
- * via `JsValue::from_str`), plus an out-of-range `page_index` or
- * degenerate device dimensions.
+ * A stringified [`otisk::RenderError`] via `JsValue::from_str`, plus an
+ * out-of-range `page_index` or degenerate device dimensions.
  * @param {string} html
  * @param {string} css
  * @param {number} margin_mm
@@ -122,112 +120,6 @@ export function render_page_rgba(html, css, margin_mm, assets, output_intent, pa
     }
     return RasterResult.__wrap(ret[0]);
 }
-
-/**
- * Render an `(html, css)` pair to a PDF/X-4 byte buffer.
- *
- * Thin shim over [`otisk::Engine`]: builds an engine with `margin_mm`
- * applied uniformly to all four sides (see
- * [`otisk::EngineBuilder::with_margins_mm`]), then forwards to
- * [`otisk::Engine::render`] and returns [`otisk::RenderResult::bytes`].
- *
- * ## Optional asset resolver (Issue 115)
- *
- * The `assets` parameter is **optional**. wasm-bindgen surfaces it as
- * a fourth positional argument that the JS caller may omit (older
- * 3-arg call sites — `render_pdf(html, css, margin)` — keep working
- * unchanged) or pass as `null` / `undefined` for the same behaviour.
- * When `assets` is present it must be either:
- *
- * - a bare callable: `function(url: string): Uint8Array`, or
- * - an object with the spec'd shape: `{ fetch(url: string): Uint8Array }`.
- *
- * Every engine-side asset lookup (`@font-face`, `<img>`,
- * `background-image`, and — Phase 4 — `@color-profile`) is funneled
- * through that callable. If `assets.fetch` returns a non-`Uint8Array`
- * value, throws, or the method doesn't exist, the render fails with
- * [`otisk::FetchError`] surfaced through the usual
- * `JsValue`-stringified error channel.
- *
- * ### Why synchronous
- *
- * The native [`otisk::AssetResolver::fetch`] signature is synchronous
- * (`SPECIFICATION.md` §3.7); the engine never spins up an async
- * runtime to fetch an asset. Mirroring that on the JS side keeps the
- * byte-identity contract trivial — every fetch returns bytes
- * immediately, with the same byte-for-byte semantics on both sides.
- * A `Promise<Uint8Array>` arm would either (a) require an async
- * engine entry point — out of scope for this issue — or (b) demand
- * host-side blocking that the browser doesn't permit on the main
- * thread. The simpler synchronous arm is the load-bearing acceptance
- * criterion (byte-identical parity for `font_face_load`,
- * `image_embed`, `background_image`) and an async overload can ride
- * on top of it later.
- *
- * ## Optional output intent (Issue 116)
- *
- * The `output_intent` parameter is **optional**. wasm-bindgen surfaces it
- * as a fifth positional argument that the JS caller may omit (older
- * 3-arg / 4-arg call sites keep working unchanged) or pass as `null` /
- * `undefined` for the same default behaviour. When `output_intent` is
- * present it must be a UTF-8 string naming a known
- * [`otisk::ColorProfile`] variant — see [`parse_color_profile`] for the
- * accepted spellings (`"srgb"`, `"fogra39"`, `"swop_v2"`,
- * case-insensitive). An unknown string surfaces as the usual
- * `JsValue`-stringified error so the JS caller can react.
- *
- * ## Diagnostics
- *
- * Diagnostics from the render are intentionally dropped on this entry
- * point — the spec deliberately keeps the WASM surface minimal
- * (Issue 30 §"Out of scope"). A richer entry point returning
- * `{ bytes, diagnostics }` is deferred to a future issue once the
- * parity harness has a concrete need for it.
- *
- * # Errors
- *
- * On any failure inside the pipeline ([`otisk::RenderError`] — HTML/CSS
- * parse errors, layout failures, missing fonts, PDF emit errors, or
- * resource-limit breaches), any failure inside the JS-side
- * resolver, or an unrecognised `output_intent` string, the error is
- * stringified via its `Display` impl and returned as a
- * `JsValue::from_str`. JS sees a plain string error message; richer
- * error objects can land alongside the diagnostic surface later.
- *
- * # Parameters
- *
- * - `html`: the input HTML source as a UTF-8 string.
- * - `css`: the matching CSS source (currently the only style input — the
- *   engine has no `<style>` / `<link rel="stylesheet">` extraction yet).
- * - `margin_mm`: uniform page margin applied to all four sides.
- * - `assets` *(optional)*: a `{ fetch(url): Uint8Array }` object or a
- *   bare `(url) -> Uint8Array` callable; pass `null` / `undefined` /
- *   omit entirely for the empty-resolver baseline (byte-identical to
- *   the pre-Issue-115 3-arg call).
- * - `output_intent` *(optional)*: a UTF-8 string naming a known
- *   [`otisk::ColorProfile`] variant (`"srgb"`, `"fogra39"`,
- *   `"swop_v2"`); pass `null` / `undefined` / omit entirely to keep
- *   the engine's default profile ([`ColorProfile::default`] — sRGB).
- * @param {string} html
- * @param {string} css
- * @param {number} margin_mm
- * @param {any | null} [assets]
- * @param {any | null} [output_intent]
- * @returns {Uint8Array}
- */
-export function render_pdf(html, css, margin_mm, assets, output_intent) {
-    const ptr0 = passStringToWasm0(html, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(css, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.render_pdf(ptr0, len0, ptr1, len1, margin_mm, isLikeNone(assets) ? 0 : addToExternrefTable0(assets), isLikeNone(output_intent) ? 0 : addToExternrefTable0(output_intent));
-    if (ret[3]) {
-        throw takeFromExternrefTable0(ret[2]);
-    }
-    var v3 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
-    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
-    return v3;
-}
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,

package/package.json

@@ -2,7 +2,7 @@
   "name": "@otisk/preview",
   "type": "module",
   "description": "Raster print-preview for the otisk typesetting engine: render HTML/CSS pages to RGBA bitmaps (WASM) for an HTML5-canvas preview that matches the PDF print geometry.",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "license": "Apache-2.0",
   "files": [
     "engine_wasm_bg.wasm",