djvu-rs 0.28.0

package/djvu_rs.d.ts

@@ -0,0 +1,321 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * A parsed DjVu document.
+ *
+ * Created from raw bytes via [`WasmDocument::from_bytes`].
+ */
+export class WasmDocument {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Parse a DjVu document from a byte buffer.
+     *
+     * The buffer is moved into a shared backing store and bundled pages
+     * materialize lazily on first access (#609) — the same owned-bytes path
+     * as the native `Document::from_bytes` (LAZY_PAGE_CONSTRUCT), instead of
+     * the eager parser that copied every page at open time. The JS-visible
+     * signature is unchanged (pass a `Uint8Array`); the JS→wasm transfer is
+     * the single unavoidable copy.
+     *
+     * Throws a JavaScript `Error` if the bytes are not a valid DjVu file.
+     */
+    static from_bytes(data: Uint8Array): WasmDocument;
+    /**
+     * Return a handle to page `index` (0-based).
+     *
+     * Throws if `index >= page_count()`.
+     */
+    page(index: number): WasmPage;
+    /**
+     * Total number of pages in the document.
+     */
+    page_count(): number;
+    /**
+     * Render a contiguous batch of pages at `target_dpi`, returning one
+     * [`WasmPixmap`] per page in input order (#610).
+     *
+     * With the opt-in `wasm-threads` build (rayon Web-Worker pool via
+     * `initThreadPool`), pages render concurrently as coarse one-page tasks —
+     * the threading shape WASM_THREADS measured as viable (fine-grained
+     * compositor parallelism regressed ~9× and stays disabled). Without the
+     * pool the batch renders sequentially with identical results.
+     *
+     * Memory is bounded by the caller-chosen batch size: `count` full-size
+     * pixmaps are alive at once. Failed pages yield an error for the whole
+     * batch (all-or-nothing keeps the ordering contract simple).
+     */
+    render_pages_batch(target_dpi: number, start: number, count: number): WasmPixmap[];
+}
+
+/**
+ * A single page within a [`WasmDocument`].
+ */
+export class WasmPage {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Number of BG44 background chunks on this page.
+     *
+     * Determines how many refinement steps are available via
+     * [`render_progressive`]. Returns `0` for bilevel-only pages.
+     */
+    bg44_chunk_count(): number;
+    /**
+     * Native DPI stored in the INFO chunk.
+     */
+    dpi(): number;
+    /**
+     * Output height in pixels when rendered at `target_dpi`.
+     */
+    height_at(target_dpi: number): number;
+    /**
+     * Render the page at `target_dpi` and return raw RGBA pixels
+     * (`Uint8ClampedArray`, suitable for `new ImageData(pixels, w, h)`).
+     *
+     * Throws on decode error.
+     */
+    render(target_dpi: number): Uint8ClampedArray;
+    /**
+     * Fast coarse render — decodes only the first BG44 chunk (~5 ms for a
+     * typical color page).
+     *
+     * Returns `undefined` for bilevel-only pages (no BG44 data); use
+     * [`render`] for those.  For color pages the result is a blurry but
+     * instantly visible preview; call [`render_progressive`] or [`render`]
+     * on a Web Worker to produce the final image.
+     *
+     * Throws on decode error.
+     */
+    render_coarse(target_dpi: number): Uint8ClampedArray | undefined;
+    /**
+     * Render into a caller-owned [`WasmPixmap`], reusing its Rust-side
+     * allocation (#611). No JS-side allocation, no wasm→JS copy — consume
+     * the pixels via [`WasmPixmap::view`].
+     */
+    render_into_pixmap(target_dpi: number, out: WasmPixmap): void;
+    /**
+     * Progressive render — decodes BG44 chunks 0..=`chunk_n` plus all
+     * foreground layers (JB2 mask, text).
+     *
+     * `chunk_n = 0` is equivalent to [`render_coarse`] but also composites
+     * the mask. Each subsequent call with `chunk_n += 1` adds one more
+     * wavelet refinement pass. After the last chunk the result is identical
+     * to [`render`].
+     *
+     * Use [`bg44_chunk_count`] to find the maximum valid `chunk_n`
+     * (`bg44_chunk_count() - 1`).
+     *
+     * Throws on decode error or if `chunk_n` is out of range.
+     */
+    render_progressive(target_dpi: number, chunk_n: number): Uint8ClampedArray;
+    /**
+     * Progressive render into a caller-owned [`WasmPixmap`] (#611): the same
+     * refinement semantics as [`render_progressive`](Self::render_progressive),
+     * but an N-pass progressive session reuses one buffer instead of
+     * allocating and copying N full frames.
+     */
+    render_progressive_into_pixmap(target_dpi: number, chunk_n: number, out: WasmPixmap): void;
+    /**
+     * Render one full-quality tile, returning a [`WasmPixmap`] whose
+     * `width()`/`height()` give the (possibly clipped) tile dimensions.
+     *
+     * Byte-identical to the matching rectangle of [`render`](Self::render);
+     * assembled from the page's composited-tile cache (cache state never
+     * changes bytes, only latency).
+     *
+     * Throws on decode error or a grid violation.
+     */
+    render_tile(target_dpi: number, tile_size: number, col: number, row: number): WasmPixmap;
+    /**
+     * Render one full-quality tile into a caller-owned [`WasmPixmap`]
+     * (#611 pattern): a pan/zoom session reuses one Rust-side allocation
+     * per on-screen tile slot instead of allocating per frame.
+     */
+    render_tile_into_pixmap(target_dpi: number, tile_size: number, col: number, row: number, out: WasmPixmap): void;
+    /**
+     * Render one tile at progressive quality step `chunk_n` (BG44 chunks
+     * `0..=chunk_n` only), byte-identical to the tile's rectangle of
+     * [`render_progressive`](Self::render_progressive) with the same
+     * `chunk_n`. Partial-quality tiles are never cached.
+     *
+     * On bilevel pages (no BG44 data) `chunk_n = 0` is the full render.
+     * Throws on decode error, a grid violation, or `chunk_n` out of range.
+     */
+    render_tile_progressive(target_dpi: number, tile_size: number, col: number, row: number, chunk_n: number): WasmPixmap;
+    /**
+     * Extract the plain text content of this page from the TXTz/TXTa layer.
+     *
+     * Returns `undefined` (JS `None`) if the page has no text layer.
+     * Throws a JavaScript `Error` on decode failure.
+     */
+    text(): string | undefined;
+    /**
+     * Return text zone data for this page, scaled to match a render at `target_dpi`.
+     *
+     * Returns a JSON string — array of `{"t":"…","x":N,"y":N,"w":N,"h":N}` objects,
+     * one per leaf text zone, with pixel coordinates identical to the canvas produced
+     * by `render(target_dpi)`.  Leaf zones are the finest granularity stored in the
+     * text layer (word-level for richly OCR'd files, line-level otherwise).
+     *
+     * Returns `null` if the page has no text layer.
+     * Throws a JavaScript `Error` on decode failure.
+     */
+    text_zones_json(target_dpi: number): string | undefined;
+    /**
+     * Number of tile columns at `target_dpi` for `tile_size`-pixel tiles.
+     *
+     * Tiles live in display space: tile `(col, row)` starts at canvas pixel
+     * `(col * tile_size, row * tile_size)`; edge tiles are clipped, never
+     * padded, so blitting every tile covers the canvas exactly once.
+     */
+    tile_cols(target_dpi: number, tile_size: number): number;
+    /**
+     * Number of tile rows at `target_dpi` for `tile_size`-pixel tiles.
+     */
+    tile_rows(target_dpi: number, tile_size: number): number;
+    /**
+     * Output width in pixels when rendered at `target_dpi`.
+     */
+    width_at(target_dpi: number): number;
+}
+
+/**
+ * A Rust-owned RGBA pixel buffer that stays alive as long as JS holds the
+ * handle, so pixels can be consumed **without** the per-frame
+ * `Uint8ClampedArray` allocation + full-buffer copy the plain `render*`
+ * methods pay.
+ *
+ * Two usage modes:
+ * - **Zero-copy view**: [`view`](WasmPixmap::view) returns a typed-array view
+ *   directly into wasm linear memory. Consume it immediately (e.g.
+ *   `ctx.putImageData(new ImageData(pm.view(), pm.width(), pm.height()), 0, 0)`
+ *   — `ImageData` copies). The view is invalidated by wasm memory growth and
+ *   by dropping/re-rendering the pixmap; never store it.
+ * - **Buffer reuse**: pass the same `WasmPixmap` back to
+ *   [`render_into_pixmap`](WasmPage::render_into_pixmap) /
+ *   [`render_progressive_into_pixmap`](WasmPage::render_progressive_into_pixmap)
+ *   — the Rust-side allocation is reused across frames (a progressive
+ *   session allocates once instead of once per refinement pass).
+ *
+ * The existing copying `render*` methods are unchanged for callers that need
+ * independently owned JS bytes.
+ */
+export class WasmPixmap {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * RGBA byte length (`width * height * 4`).
+     */
+    byte_length(): number;
+    /**
+     * Pixel height of the last render written into this pixmap.
+     */
+    height(): number;
+    /**
+     * An empty pixmap for use with the `*_into_pixmap` methods.
+     */
+    constructor();
+    /**
+     * Copy the pixels into a fresh, independently owned
+     * `Uint8ClampedArray` (same guarantee as the plain `render` API).
+     */
+    to_bytes(): Uint8ClampedArray;
+    /**
+     * Zero-copy `Uint8ClampedArray` view into wasm memory.
+     *
+     * Valid only until the next wasm memory growth, the next render into
+     * this pixmap, or the pixmap being freed — consume it immediately and
+     * never store it. `new ImageData(view, w, h)` copies, so canvas
+     * consumption is safe.
+     */
+    view(): Uint8ClampedArray;
+    /**
+     * Pixel width of the last render written into this pixmap.
+     */
+    width(): number;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_wasmdocument_free: (a: number, b: number) => void;
+    readonly __wbg_wasmpage_free: (a: number, b: number) => void;
+    readonly __wbg_wasmpixmap_free: (a: number, b: number) => void;
+    readonly djvu_doc_free: (a: number) => void;
+    readonly djvu_doc_open: (a: number, b: number, c: number) => number;
+    readonly djvu_doc_page_count: (a: number) => number;
+    readonly djvu_error_free: (a: number) => void;
+    readonly djvu_page_dpi: (a: number, b: number, c: number) => number;
+    readonly djvu_page_height: (a: number, b: number, c: number) => number;
+    readonly djvu_page_render: (a: number, b: number, c: number, d: number) => number;
+    readonly djvu_page_text: (a: number, b: number, c: number) => number;
+    readonly djvu_page_width: (a: number, b: number, c: number) => number;
+    readonly djvu_pixmap_data: (a: number) => number;
+    readonly djvu_pixmap_data_len: (a: number) => number;
+    readonly djvu_pixmap_free: (a: number) => void;
+    readonly djvu_pixmap_height: (a: number) => number;
+    readonly djvu_pixmap_width: (a: number) => number;
+    readonly djvu_text_free: (a: number) => void;
+    readonly wasmdocument_from_bytes: (a: number, b: number) => [number, number, number];
+    readonly wasmdocument_page: (a: number, b: number) => [number, number, number];
+    readonly wasmdocument_page_count: (a: number) => number;
+    readonly wasmdocument_render_pages_batch: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly wasmpage_bg44_chunk_count: (a: number) => number;
+    readonly wasmpage_dpi: (a: number) => number;
+    readonly wasmpage_height_at: (a: number, b: number) => number;
+    readonly wasmpage_render: (a: number, b: number) => [number, number, number];
+    readonly wasmpage_render_coarse: (a: number, b: number) => [number, number, number];
+    readonly wasmpage_render_into_pixmap: (a: number, b: number, c: number) => [number, number];
+    readonly wasmpage_render_progressive: (a: number, b: number, c: number) => [number, number, number];
+    readonly wasmpage_render_progressive_into_pixmap: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly wasmpage_render_tile: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly wasmpage_render_tile_into_pixmap: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+    readonly wasmpage_render_tile_progressive: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly wasmpage_text: (a: number) => [number, number, number, number];
+    readonly wasmpage_text_zones_json: (a: number, b: number) => [number, number, number, number];
+    readonly wasmpage_tile_cols: (a: number, b: number, c: number) => [number, number, number];
+    readonly wasmpage_tile_rows: (a: number, b: number, c: number) => [number, number, number];
+    readonly wasmpage_width_at: (a: number, b: number) => number;
+    readonly wasmpixmap_byte_length: (a: number) => number;
+    readonly wasmpixmap_height: (a: number) => number;
+    readonly wasmpixmap_new: () => number;
+    readonly wasmpixmap_to_bytes: (a: number) => any;
+    readonly wasmpixmap_view: (a: number) => any;
+    readonly wasmpixmap_width: (a: number) => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __externref_drop_slice: (a: number, b: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;
+
+export function wasmSimd128Supported(): boolean;
+export function selectedWasmVariant(): "scalar" | "simd128" | undefined;

package/djvu_rs.js

@@ -0,0 +1,56 @@
+import * as scalarModule from "./scalar/djvu_rs.js";
+import * as simd128Module from "./simd128/djvu_rs.js";
+
+const SIMD128_PROBE = new Uint8Array([
+  0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
+  0x01, 0x05, 0x01, 0x60, 0x00, 0x01, 0x7b,
+  0x03, 0x02, 0x01, 0x00,
+  0x0a, 0x16, 0x01, 0x14, 0x00, 0xfd, 0x0c,
+  0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00,
+  0x0b,
+]);
+
+let selectedModule;
+let selectedVariant;
+
+export let WasmDocument;
+export let WasmPage;
+export let WasmPixmap;
+export let WasmLazyDocument;
+export let initThreadPool;
+
+export function wasmSimd128Supported() {
+  return typeof WebAssembly === "object" && WebAssembly.validate(SIMD128_PROBE);
+}
+
+export function selectedWasmVariant() {
+  return selectedVariant;
+}
+
+export default async function init(input) {
+  if (selectedModule !== undefined) {
+    return selectedModule;
+  }
+
+  const useSimd128 = wasmSimd128Supported();
+  selectedVariant = useSimd128 ? "simd128" : "scalar";
+  selectedModule = useSimd128 ? simd128Module : scalarModule;
+
+  const wasmInput = input ?? new URL(`./${selectedVariant}/djvu_rs_bg.wasm`, import.meta.url);
+  await selectedModule.default({ module_or_path: wasmInput });
+
+  WasmDocument = selectedModule.WasmDocument;
+  WasmPage = selectedModule.WasmPage;
+  WasmPixmap = selectedModule.WasmPixmap;
+  WasmLazyDocument = selectedModule.WasmLazyDocument;
+  initThreadPool = selectedModule.initThreadPool;
+
+  return selectedModule;
+}
+
+export function initSync() {
+  throw new Error("The dual wasm loader requires async init() for runtime variant selection.");
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "djvu-rs",
+  "type": "module",
+  "description": "Read, render, convert, and create DjVu files. Pure-Rust DjVu decoder/encoder with CLI, WebAssembly, and Python bindings. DjVu to PDF, EPUB, TIFF, PNG, and text. MIT licensed, no GPL dependencies.",
+  "version": "0.28.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/matyushkin/djvu-rs"
+  },
+  "files": [
+    "djvu_rs.js",
+    "djvu_rs.d.ts",
+    "README.md",
+    "LICENSE",
+    "scalar/djvu_rs.js",
+    "scalar/djvu_rs.d.ts",
+    "scalar/djvu_rs_bg.wasm",
+    "scalar/djvu_rs_bg.wasm.d.ts",
+    "simd128/djvu_rs.js",
+    "simd128/djvu_rs.d.ts",
+    "simd128/djvu_rs_bg.wasm",
+    "simd128/djvu_rs_bg.wasm.d.ts"
+  ],
+  "main": "djvu_rs.js",
+  "types": "djvu_rs.d.ts",
+  "sideEffects": false,
+  "keywords": [
+    "djvu",
+    "decoder",
+    "encoder",
+    "pdf",
+    "converter"
+  ],
+  "module": "djvu_rs.js",
+  "exports": {
+    ".": {
+      "types": "./djvu_rs.d.ts",
+      "import": "./djvu_rs.js",
+      "default": "./djvu_rs.js"
+    }
+  }
+}
+

package/scalar/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lev Matyushkin
+
+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.