Merge pull request #167 from artiz/claude/wasm-npm-package

artiz · web-flow · commit 24163e2d9968 · 2026-07-28T09:49:02.000+02:00
wasm: publish docling.rs-wasm to npm; document the Tauri paths
diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml
@@ -366,3 +366,89 @@ jobs:
         run: cd cuda/pkg && npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  # docling.rs-wasm: the browser/WebAssembly package (no native matrix — one
+  # Linux runner compiles wasm32-unknown-unknown and publishes). Same
+  # ref-selection and idempotency as the main package: builds the checked-out
+  # workspace version, skips cleanly when that version is already on npm.
+  publish-wasm:
+    name: publish docling.rs-wasm
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: .
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      - name: Install Rust (stable + wasm32 target)
+        run: |
+          rustup toolchain install stable --profile minimal
+          rustup default stable
+          rustup target add wasm32-unknown-unknown
+
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            ~/.cargo/bin
+            target
+          key: ${{ runner.os }}-cargo-v2-wasm-npm-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-v2-wasm-npm-
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install wasm-bindgen-cli (pinned to Cargo.lock)
+        run: |
+          # A CLI/crate version mismatch produces glue the module rejects at
+          # load time — pin to the workspace's wasm-bindgen (same as pages.yml).
+          version=$(cargo metadata --format-version 1 --locked \
+            | python3 -c 'import json,sys; print(next(p["version"] for p in json.load(sys.stdin)["packages"] if p["name"]=="wasm-bindgen"))')
+          echo "wasm-bindgen $version"
+          command -v wasm-bindgen >/dev/null && [ "$(wasm-bindgen --version)" = "wasm-bindgen $version" ] \
+            || cargo install wasm-bindgen-cli --version "$version" --locked
+
+      - name: Build the package
+        run: bash scripts/ci/build_wasm_pkg.sh target/npm-wasm
+
+      # Skip cleanly if this version is already on npm (idempotent re-runs).
+      - name: Check if already published
+        id: wcheck
+        run: |
+          v="$(grep -m1 '^version = ' Cargo.toml | sed -E 's/.*"([^"]+)".*/\1/')"
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+          if npm view "docling.rs-wasm@$v" version >/dev/null 2>&1; then
+            echo "published=true" >> "$GITHUB_OUTPUT"
+            echo "docling.rs-wasm@$v is already on npm — skipping."
+          else
+            echo "published=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Load the module in Node off the packed tarball (exactly what npm will
+      # serve) and convert a real file before publishing anything.
+      - name: Validate the packed package
+        if: steps.wcheck.outputs.published == 'false'
+        run: |
+          (cd target/npm-wasm && npm pack >/dev/null)
+          mkdir -p /tmp/wasm-check && tar -xzf target/npm-wasm/*.tgz -C /tmp/wasm-check --strip-components=1
+          node --input-type=module -e '
+            import { readFileSync } from "node:fs";
+            const m = await import("/tmp/wasm-check/web/docling_wasm.js");
+            await m.default({ module_or_path: readFileSync("/tmp/wasm-check/web/docling_wasm_bg.wasm") });
+            const html = new TextEncoder().encode("<html><body><h1>T</h1><p>ok</p></body></html>");
+            const md = m.convert(html, "t.html", "md");
+            if (!md.includes("# T")) throw new Error("bad output: " + md);
+            console.log("docling.rs-wasm@" + m.version() + " converts: " + JSON.stringify(md));
+          '
+
+      - name: Publish
+        if: steps.wcheck.outputs.published == 'false'
+        run: cd target/npm-wasm && npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/README.md b/README.md
@@ -152,8 +152,18 @@ pipelines) compile to `wasm32-unknown-unknown`:
 [`crates/docling-wasm`](./crates/docling-wasm) exposes
 `convert(bytes, filename, to)` → Markdown / docling JSON / DocLang via
 `wasm-bindgen`, so DOCX/HTML/XLSX/PPTX/EPUB/… convert **fully client-side** —
-no server, ~1.9 MB gzipped module, no models to download — something Python
-docling has no equivalent for. Digital PDFs convert too: the opt-in
+no server, ~3.4 MB gzipped module, no models to download — something Python
+docling has no equivalent for. Ready to use from npm:
+
+```bash
+npm i docling.rs-wasm
+```
+
+```js
+import { convert } from "docling.rs-wasm";          // bundlers
+// import init, { convert } from "docling.rs-wasm/web"; await init();  // no bundler
+const markdown = convert(bytes, file.name, "md");
+``` Digital PDFs convert too: the opt-in
 `pdf-text` feature runs docling-pdf's pure-Rust text-layer parser (the same
 extraction as `--no-ocr`: flat paragraphs, no headings/tables/pictures),
 while scanned PDFs get a clear "needs OCR" error instead of an empty
@@ -1007,7 +1017,7 @@ on a 1913-page document — see [`docs/PDF_CONFORMANCE.md`](./docs/PDF_CONFORMAN
 | `docling-serve` | HTTP conversion API over a warm pipeline | `docling-serve` |
 | `docling-node` | Node.js / Bun N-API bindings | https://www.npmjs.com/package/docling.rs |
 | `docling-py` | Python bindings | https://pypi.org/project/docling-rs |
-| `docling-wasm` | WebAssembly bindings (declarative converters + PDF text layer in the browser) | — |
+| `docling-wasm` | WebAssembly bindings (declarative converters + PDF text layer in the browser) | https://www.npmjs.com/package/docling.rs-wasm |
 | `docling-rag` | RAG layer: chunking, embeddings, vector search, REST API | — |
 
 ## License
diff --git a/crates/docling-wasm/README.md b/crates/docling-wasm/README.md
@@ -18,10 +18,33 @@ images/audio/METS are rejected with a "rebuild with …" message. Remote
 `<img src>` images stay placeholders (no network in the module); embedded
 images work normally.
 
-**Size: ~5.6 MB raw, ~1.9 MB gzipped** (measured on this crate at 0.41.x,
-`--release` with the workspace's `lto = "thin"`; no `wasm-opt` pass — one
-typically shaves another 10–15%). No models are involved: the declarative
-converters and the PDF text parser are pure Rust.
+**Size: ~11 MB raw, ~3.4 MB gzipped** (measured at 0.49.x — the module now
+also carries the browser ML pipeline's pre/post-processing: layout decode, OCR
+prep, TableFormer core; `--release` with the workspace's `lto = "thin"`, no
+`wasm-opt` pass — one typically shaves another 10–15%). No models are involved
+for the declarative converters and the PDF text parser: pure Rust.
+
+## Install from npm
+
+```bash
+npm i docling.rs-wasm
+```
+
+```js
+// Bundlers (Vite, webpack 5 with experiments.asyncWebAssembly):
+import { convert } from "docling.rs-wasm";
+
+// No bundler (plain <script type="module">): the /web target + explicit init.
+import init, { convert } from "docling.rs-wasm/web";
+await init();
+```
+
+The package ships both wasm-bindgen targets — `bundler` (the default export)
+and `web` (self-initializing, fetches `docling_wasm_bg.wasm` next to the JS).
+It is assembled by `scripts/ci/build_wasm_pkg.sh` and published by the
+`npm publish` workflow alongside [`docling.rs`](https://www.npmjs.com/package/docling.rs)
+(the native Node bindings — prefer those on servers: full ML pipeline, no wasm
+limits).
 
 ## API
 
@@ -260,6 +283,64 @@ Resolution order for every model is **device file → local `./models/` →
 `MODEL_BASE` (Hugging Face)**. Tables need no upload beyond the model files;
 the image never leaves the page.
 
+## Tauri and other desktop shells
+
+Two ways to put docling.rs in a desktop app, and they are not equivalent:
+
+**Native backend (recommended for Tauri).** A Tauri app's backend *is* Rust,
+so skip wasm entirely and depend on the real crates — the webview only renders
+the result. This gets the full native pipeline: pdfium rendering, the complete
+ML stack (RT-DETR + TableFormer + OCR + enrichment), GPU execution providers,
+multi-threading, memory-mapped models — none of which fit the wasm build.
+
+```toml
+# src-tauri/Cargo.toml
+[dependencies]
+docling = { version = "0.49" }        # full default features (ml pipeline)
+```
+
+```rust
+// src-tauri/src/lib.rs
+use docling::{DocumentConverter, SourceDocument};
+
+#[tauri::command]
+async fn convert_document(path: String) -> Result<String, String> {
+    // The ML pipeline is CPU-heavy — keep it off the event loop.
+    tauri::async_runtime::spawn_blocking(move || {
+        let source = SourceDocument::from_file(&path).map_err(|e| e.to_string())?;
+        let result = DocumentConverter::new()
+            .convert(source)
+            .map_err(|e| e.to_string())?;
+        Ok(result.document.export_to_markdown())
+    })
+    .await
+    .map_err(|e| e.to_string())?
+}
+```
+
+Ship the `models/` directory as a Tauri resource (or fetch on first run with
+`scripts/install/download_dependencies.sh`'s URLs) and point the resolver at
+it — model paths resolve CWD-relative with env overrides
+(`PDFIUM_DYNAMIC_LIB_PATH`, `DOCLING_LAYOUT_ONNX`, …), so set the resource dir
+as the working directory or export the variables before the first conversion.
+
+**Wasm in the webview.** `docling.rs-wasm` runs unchanged inside Tauri's (or
+Electron's) webview — worth it only when the same SPA must also ship as a
+plain web page and you want one code path. The wasm limits apply (declarative
+formats + PDF text layer; browser ML needs ONNX Runtime Web + models). One
+Tauri-specific note: multi-threaded ONNX Runtime Web needs COOP/COEP headers —
+on GitHub Pages the demo fakes them with a service worker (`www/coi.js`), but
+in Tauri you control the protocol, so serve the app with
+`Cross-Origin-Opener-Policy: same-origin` and
+`Cross-Origin-Embedder-Policy: require-corp` directly (e.g. via the
+`app.security.headers` config or a custom protocol handler) and drop the
+service-worker shim.
+
+**Electron.** Same fork: prefer the native
+[`docling.rs`](https://www.npmjs.com/package/docling.rs) N-API package in the
+main process (`ipcMain.handle("convert", …)`), keep `docling.rs-wasm` for
+renderer-only/sandboxed setups.
+
 ## Performance & threading
 
 - **Threads.** ONNX Runtime Web runs single-threaded unless the page is
diff --git a/crates/docling-wasm/npm/README.md b/crates/docling-wasm/npm/README.md
@@ -0,0 +1,77 @@
+# docling.rs-wasm
+
+[docling.rs](https://github.com/docling-project/docling.rs) compiled to
+WebAssembly: convert **DOCX, HTML, XLSX, PPTX, CSV, AsciiDoc, EPUB, ODF,
+Markdown, WebVTT, Email, MHTML, JATS, USPTO, XBRL, LaTeX, JSON, DocLang — and
+the embedded text layer of PDFs** — to Markdown / docling JSON / DocLang XML
+**entirely in the browser**. No server; the file never leaves the page.
+
+~1.9 MB gzipped, no models needed for any of the above. Scanned PDFs and
+images additionally work through the in-browser ML pipeline (RT-DETR layout +
+PP-OCRv3 + TableFormer via [ONNX Runtime Web](https://www.npmjs.com/package/onnxruntime-web))
+once you provide the models — see the
+[full docs](https://github.com/docling-project/docling.rs/tree/master/crates/docling-wasm#readme)
+and the [live demo](https://docling-project.github.io/docling.rs/).
+
+## Bundlers (Vite, webpack, …)
+
+```js
+import { convert, supported_extensions } from "docling.rs-wasm";
+
+const file = input.files[0];
+const bytes = new Uint8Array(await file.arrayBuffer());
+const markdown = convert(bytes, file.name, "md");
+const json     = convert(bytes, file.name, "json");
+const withPics = convert(bytes, file.name, "md", "embedded"); // data: URIs
+```
+
+(The bundler target loads the wasm as a module import — Vite needs no config;
+webpack 5 needs `experiments.asyncWebAssembly = true`.)
+
+## No bundler (plain `<script type="module">`)
+
+```js
+import init, { convert } from "docling.rs-wasm/web";
+await init(); // fetches docling_wasm_bg.wasm next to the JS
+
+const markdown = convert(bytes, file.name, "md");
+```
+
+## API
+
+```ts
+convert(
+  bytes: Uint8Array,
+  filename: string,                        // extension drives format detection
+  to?: "md" | "json" | "doclang",          // default "md"
+  images?: "placeholder" | "embedded",     // default "placeholder", Markdown only
+  max_pages?: number,                      // convert only the first N PDF pages
+): string
+supported_extensions(): string             // JSON array, e.g. for <input accept=…>
+version(): string
+```
+
+Structured digital-PDF conversion (`DigitalConverter`: headings, lists,
+tables, pictures via the layout model), scanned-document OCR
+(`ScannedConverter`) and TableFormer table structure are exported too — they
+need ONNX Runtime Web sessions on the JS side; the
+[crate README](https://github.com/docling-project/docling.rs/tree/master/crates/docling-wasm#readme)
+has the complete wiring, and the
+[demo page source](https://github.com/docling-project/docling.rs/tree/master/crates/docling-wasm/www)
+is a working reference.
+
+## Tauri / Electron
+
+The package runs in any webview as-is — but in a Tauri app you usually want
+the **native** pipeline in the Rust backend instead (full OCR, TableFormer,
+GPU, no wasm limits). See
+[“Tauri and other desktop shells”](https://github.com/docling-project/docling.rs/tree/master/crates/docling-wasm#tauri-and-other-desktop-shells)
+in the crate README.
+
+## Related packages
+
+- [`docling.rs`](https://www.npmjs.com/package/docling.rs) — native Node.js /
+  Bun bindings with the full ML pipeline (use this on servers).
+- [`docling.rs-cuda`](https://www.npmjs.com/package/docling.rs-cuda) — the
+  same with CUDA execution providers.
+- [`docling-rs`](https://pypi.org/project/docling-rs/) — Python wheel.
diff --git a/crates/docling-wasm/npm/package.json b/crates/docling-wasm/npm/package.json
@@ -0,0 +1,50 @@
+{
+  "name": "docling.rs-wasm",
+  "version": "0.0.0",
+  "description": "In-browser document conversion: DOCX, HTML, XLSX, PPTX, EPUB, Markdown, … and the text layer of PDFs → Markdown / docling JSON / DocLang, fully client-side (docling.rs compiled to WebAssembly)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/docling-project/docling.rs.git",
+    "directory": "crates/docling-wasm"
+  },
+  "homepage": "https://github.com/docling-project/docling.rs/tree/master/crates/docling-wasm#readme",
+  "keywords": [
+    "docling",
+    "document",
+    "conversion",
+    "markdown",
+    "pdf",
+    "docx",
+    "xlsx",
+    "pptx",
+    "wasm",
+    "webassembly",
+    "browser",
+    "ocr"
+  ],
+  "type": "module",
+  "main": "bundler/docling_wasm.js",
+  "types": "bundler/docling_wasm.d.ts",
+  "exports": {
+    ".": {
+      "types": "./bundler/docling_wasm.d.ts",
+      "default": "./bundler/docling_wasm.js"
+    },
+    "./web": {
+      "types": "./web/docling_wasm.d.ts",
+      "default": "./web/docling_wasm.js"
+    },
+    "./web/docling_wasm_bg.wasm": "./web/docling_wasm_bg.wasm",
+    "./bundler/docling_wasm_bg.wasm": "./bundler/docling_wasm_bg.wasm"
+  },
+  "sideEffects": [
+    "./bundler/docling_wasm.js"
+  ],
+  "files": [
+    "bundler",
+    "web",
+    "README.md",
+    "LICENSE"
+  ]
+}
diff --git a/scripts/ci/build_wasm_pkg.sh b/scripts/ci/build_wasm_pkg.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# Assemble the `docling.rs-wasm` npm package: compile docling-wasm for
+# wasm32-unknown-unknown, run wasm-bindgen for the `bundler` (import from
+# "docling.rs-wasm") and `web` (import from "docling.rs-wasm/web" + init())
+# targets, and lay the results out next to the package skeleton from
+# crates/docling-wasm/npm/, versioned from the workspace Cargo.toml.
+#
+# The wasm-bindgen CLI must match the wasm-bindgen crate version in Cargo.lock
+# (the generated glue is version-locked); npm-publish.yml installs the pinned
+# version the same way pages.yml does.
+#
+# Usage: scripts/ci/build_wasm_pkg.sh [outdir]   (default target/npm-wasm)
+set -euo pipefail
+cd "$(dirname "$0")/../.."
+
+out="${1:-target/npm-wasm}"
+
+cargo build -p docling-wasm --target wasm32-unknown-unknown --release --locked
+wasm="target/wasm32-unknown-unknown/release/docling_wasm.wasm"
+
+rm -rf "$out"
+mkdir -p "$out"
+for tgt in bundler web; do
+  wasm-bindgen --target "$tgt" --out-dir "$out/$tgt" "$wasm"
+done
+
+cp crates/docling-wasm/npm/package.json crates/docling-wasm/npm/README.md "$out/"
+cp LICENSE "$out/"
+
+version="$(grep -m1 '^version = ' Cargo.toml | sed -E 's/.*"([^"]+)".*/\1/')"
+(cd "$out" && npm version "$version" --no-git-tag-version --allow-same-version >/dev/null)
+
+echo ">> $out ready: docling.rs-wasm@$version"
+du -sh "$out"/bundler/docling_wasm_bg.wasm
