@otisk/preview 1.1.0 → 1.1.1

package/README.md

@@ -1,96 +1,113 @@
-# `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).
+
+The same bundle also exposes the full `render_pdf` entry point, so you can
+generate the final PDF from the exact bytes 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";
 
-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.
+await init(); // load the wasm module (once)
 
-## Build (browser bundle)
+const html = "<h1>Náhled sazby</h1><p>Příliš žluťoučký kůň…</p>";
+const css = "@page { size: A6 } body { font-family: serif }";
 
-```sh
-wasm-pack build crates/engine-wasm --target web --out-dir ../../examples/web-ui/pkg --release
+const dpi = 96;
+const page = render_page_rgba(html, css, /*marginMm*/ 0, null, null, /*pageIndex*/ 0, dpi / 72);
+
+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`
+
+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.
 
-Artefact at `target/wasm32-unknown-unknown/release/engine_wasm.wasm`.
+### `page_count(html, css, marginMm, assets?, outputIntent?) → number`
 
-## Size budget
+How many pages the `(html, css)` pair lays out — for preview navigation.
 
-`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.
+### `render_pdf(html, css, marginMm, assets?, outputIntent?) → Uint8Array`
 
-## Host-target build
+Render the whole document to a PDF (the production print artefact). Same
+inputs as the preview, so the PDF matches what you previewed.
 
-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.
+### `RasterResult`
 
-## `parity_export` feature (Issue 31)
+| Member     | Type         | Notes                                  |
+| ---------- | ------------ | -------------------------------------- |
+| `width`    | `number`     | Device width in pixels.                |
+| `height`   | `number`     | Device height in pixels.               |
+| `rgba`     | `Uint8Array` | `4 · width · height` bytes, RGBA8.     |
 
-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`.
+### Asset resolver (`assets`)
 
-```sh
-cargo build -p engine-wasm --target wasm32-unknown-unknown \
-    --no-default-features --features parity_export --release
+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):
+
+```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/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.1",
   "license": "Apache-2.0",
   "files": [
     "engine_wasm_bg.wasm",