@pdfluent/sdk-wasm 1.0.0-beta.10

package/LICENSE

@@ -0,0 +1,242 @@
+PDFluent Commercial License
+Version 1.0
+Effective: 2026-05-02
+
+Copyright (c) 2026 Innovation Trigger BV (operating as PDFluent).
+All rights reserved.
+
+IMPORTANT — READ CAREFULLY. This is a legal agreement between you ("Licensee")
+and Innovation Trigger BV, a private limited company organized under the laws
+of the Netherlands and operating under the trade name "PDFluent" ("PDFluent",
+"we", "us"). By installing, copying, downloading, or otherwise using the
+Software, you agree to be bound by the terms of this License. If you do not
+agree, do not install or use the Software.
+
+This License governs the use of all Rust crates published by PDFluent that
+reference this LICENSE file in their Cargo manifest. PDFluent also publishes
+separate crates under permissive open-source licenses (MIT or Apache-2.0);
+those crates are NOT governed by this License and may be used under their
+respective open-source terms. See the NOTICE file for the list of crates
+covered by each license.
+
+----------------------------------------------------------------------------
+
+1. DEFINITIONS
+
+   "Software" means the source code, compiled object code, binary artefacts,
+   and accompanying documentation of the PDFluent crates that reference this
+   LICENSE file.
+
+   "Production Use" means any use of the Software in connection with the
+   operation of a business or for the benefit of a third party, including
+   without limitation: (a) processing data of customers, clients, or other
+   third parties; (b) integration into a commercial product, service, or
+   internal business application; (c) deployment in a production environment.
+
+   "Evaluation Use" means use of the Software solely for the purpose of
+   evaluating its suitability for Production Use, including in development,
+   testing, demonstration, and non-public staging environments. Evaluation
+   Use does not include any form of Production Use.
+
+   "Valid License" means a current and active license entitlement issued by
+   PDFluent or an authorized reseller, identified by an Ed25519-signed
+   license key file or by other written commercial terms agreed with
+   PDFluent.
+
+   "Authorized Use" means the scope of Production Use granted under a Valid
+   License, including the number of developers, locations, products, and
+   deployment configurations described in the commercial terms applicable to
+   that Valid License.
+
+----------------------------------------------------------------------------
+
+2. EVALUATION GRANT
+
+   Subject to compliance with this License, PDFluent grants Licensee a
+   non-exclusive, non-transferable, worldwide, royalty-free license to:
+
+   (a) install and use the Software for Evaluation Use; and
+
+   (b) make a reasonable number of internal copies of the Software for the
+       sole purpose of supporting Evaluation Use.
+
+   The Software, when used without a Valid License, may produce output that
+   contains identifying markers indicating that the output was generated by
+   an unlicensed copy of the Software (including but not limited to a
+   "Producer" string in PDF metadata and a one-time warning emitted to
+   standard error). Licensee shall not remove, modify, suppress, or
+   circumvent these markers, nor any license-enforcement mechanism within
+   the Software.
+
+----------------------------------------------------------------------------
+
+3. PRODUCTION GRANT
+
+   Production Use of the Software is permitted ONLY when Licensee holds a
+   Valid License covering the intended use. The scope of Production Use
+   permitted is determined by the Valid License and by the commercial terms
+   referenced therein. The current commercial terms, including pricing,
+   tiers, add-ons, and definitions of permitted use, are published at:
+
+       https://pdfluent.com/terms
+       https://pdfluent.com/pricing
+
+   Production Use exceeding the Authorized Use of the applicable Valid
+   License is a material breach of this License.
+
+----------------------------------------------------------------------------
+
+4. RESTRICTIONS
+
+   Except as expressly permitted by this License or by a separately
+   negotiated written agreement with PDFluent, Licensee shall not:
+
+   (a) use the Software in Production Use without a Valid License;
+
+   (b) remove, disable, alter, or circumvent any license-enforcement,
+       watermarking, telemetry, or attribution mechanism contained in the
+       Software;
+
+   (c) redistribute, publish, sell, sublicense, lease, rent, or otherwise
+       make the Software available to any third party, except under a
+       separately purchased OEM Redistribution add-on as described in the
+       commercial terms;
+
+   (d) reverse engineer, decompile, or disassemble the Software, except to
+       the limited extent that such activity is expressly permitted by
+       applicable law notwithstanding this restriction;
+
+   (e) modify the Software with the intent of, or in a manner that has the
+       effect of, evading any restriction in this License;
+
+   (f) remove, obscure, or alter any copyright, trademark, attribution, or
+       other proprietary notices contained in the Software or its
+       documentation; or
+
+   (g) redistribute, sublicense, expose, or offer the Software as a
+       standalone SDK, library, API, platform, service, or substantially
+       similar substitute for PDFluent, except as expressly permitted under
+       an OEM Redistribution add-on.
+
+   For clarity, restriction (g) is intended to prevent re-packaging or
+   re-offering the Software (in whole or in substantial part) as a competing
+   PDF SDK or service. It does not restrict Licensee from using the Software
+   inside its own application, product, or service that delivers
+   functionality beyond what the Software itself provides.
+
+----------------------------------------------------------------------------
+
+5. RESERVATION OF RIGHTS
+
+   The Software is licensed, not sold. Title, ownership, and all
+   intellectual property rights in and to the Software remain at all times
+   with PDFluent and its licensors. All rights not expressly granted under
+   this License are reserved by PDFluent.
+
+   Feedback, suggestions, or improvements that Licensee voluntarily provides
+   to PDFluent regarding the Software may be used by PDFluent without
+   restriction, without obligation of confidentiality, and without
+   compensation to Licensee.
+
+----------------------------------------------------------------------------
+
+6. THIRD-PARTY COMPONENTS
+
+   The Software may include or depend upon third-party components,
+   including upstream open-source crates from which certain PDFluent crates
+   are derived. Such components remain subject to their respective licenses,
+   which are reproduced in the THIRD_PARTY_LICENSES.txt file accompanying
+   the Software. Nothing in this License is intended to limit or override
+   any rights granted under those third-party licenses with respect to those
+   third-party components.
+
+----------------------------------------------------------------------------
+
+7. NO WARRANTY
+
+   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, TITLE, AND
+   NON-INFRINGEMENT. PDFLUENT DOES NOT WARRANT THAT THE SOFTWARE WILL MEET
+   LICENSEE'S REQUIREMENTS, OPERATE WITHOUT INTERRUPTION, OR BE FREE OF
+   ERRORS OR DEFECTS.
+
+----------------------------------------------------------------------------
+
+8. LIMITATION OF LIABILITY
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
+   PDFLUENT OR ITS CONTRIBUTORS BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING BUT NOT LIMITED
+   TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF USE, DATA, OR
+   PROFITS, OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE
+   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+   PDFLUENT'S TOTAL CUMULATIVE LIABILITY UNDER OR IN CONNECTION WITH THIS
+   LICENSE SHALL NOT EXCEED THE GREATER OF (i) THE FEES PAID BY LICENSEE TO
+   PDFLUENT UNDER THE APPLICABLE VALID LICENSE IN THE TWELVE (12) MONTHS
+   IMMEDIATELY PRECEDING THE EVENT GIVING RISE TO LIABILITY, OR (ii) ONE
+   HUNDRED EUROS (€100).
+
+----------------------------------------------------------------------------
+
+9. TERMINATION
+
+   This License is effective until terminated. This License terminates
+   automatically and without notice if Licensee fails to comply with any
+   term of this License. Upon termination, Licensee shall cease all use of
+   the Software, destroy all copies in its possession or control, and, on
+   request, certify such destruction in writing to PDFluent.
+
+   Sections 4 (Restrictions), 5 (Reservation of Rights), 7 (No Warranty),
+   8 (Limitation of Liability), 10 (Governing Law), and 11 (Entire
+   Agreement) survive any termination of this License.
+
+----------------------------------------------------------------------------
+
+10. GOVERNING LAW AND JURISDICTION
+
+    This License shall be governed by and construed in accordance with the
+    laws of the Netherlands, excluding its conflict-of-laws provisions and
+    the United Nations Convention on Contracts for the International Sale
+    of Goods. The courts of Amsterdam, the Netherlands, shall have
+    exclusive jurisdiction over any dispute arising from or in connection
+    with this License, except that PDFluent may seek injunctive relief in
+    any court of competent jurisdiction to protect its intellectual
+    property rights.
+
+----------------------------------------------------------------------------
+
+11. ENTIRE AGREEMENT
+
+    This License, together with any Valid License terms and any commercial
+    terms expressly incorporated by reference, constitutes the entire
+    agreement between Licensee and PDFluent with respect to the Software
+    and supersedes all prior or contemporaneous communications,
+    representations, or agreements, whether oral or written. No
+    modification or amendment of this License shall be effective unless in
+    writing and signed by an authorized representative of PDFluent.
+
+----------------------------------------------------------------------------
+
+CONTACT
+
+    Innovation Trigger BV
+    Operating as PDFluent
+    Email: hello@pdfluent.com
+    Web:   https://pdfluent.com
+
+For commercial terms, pricing, evaluation policies, trial keys, and OEM
+licensing options, visit https://pdfluent.com/pricing.
+
+----------------------------------------------------------------------------
+
+NOTE ON HISTORICAL VERSIONS
+
+Versions of PDFluent crates published to crates.io prior to 2026-05-02
+under the MIT license remain available under the MIT license. This License
+applies to versions published on or after that date that reference this
+LICENSE file in their Cargo manifest. See CHANGELOG.md for the version
+boundary.

package/README.md

@@ -0,0 +1,321 @@
+# PDFluent browser SDK (WASM)
+
+WebAssembly distribution of the PDFluent PDF engine. Read, edit, annotate,
+redact, sign, and validate PDFs (including XFA) entirely in the browser —
+zero bytes go to a server.
+
+Published as `@pdfluent/xfa-wasm` on npm. (Crate name reflects historical
+XFA roots; the package now covers the full SDK surface needed for an
+in-browser PDF editor.)
+
+## Features
+
+- **XFA Forms**: Parse, calculate, import/export XFA form data
+- **PDF Analysis**: Metadata, signatures, PDF/A compliance validation
+- **Page Rendering** (feature `render`): Render pages to RGBA pixels or Canvas2D
+- **Page Manipulation**: delete, rotate, reorder, extract, split via re-extract, merge
+- **Forms write-back**: set AcroForm field values, save modified PDF bytes
+- **Annotations** (feature `annotate`): highlight, sticky note, free text
+- **Text watermark**: diagonal text watermark with configurable opacity
+- **Redaction**: by region (rectangle) or by search query (GDPR-safe permanent removal)
+- **Stream compression**: re-deflate content streams for smaller file size
+- **License activation**: process-global tier activation via key string or file
+- **`PdfDocMut`** (Wave 3): stateful editing handle — open once, mutate in
+  place, save once. 2.7× faster than the stateless `PdfDoc` chain for
+  multi-step edits, identical output bytes.
+
+## Building
+
+```bash
+# Install wasm-pack
+cargo install wasm-pack
+
+# Build the WASM package
+wasm-pack build crates/@pdfluent/wasm --target web
+
+# Without rendering (smaller bundle)
+wasm-pack build crates/@pdfluent/wasm --target web -- --no-default-features
+```
+
+## Quick Start
+
+### XFA Forms
+
+```js
+import init, { XfaEngine } from './pkg/xfa_wasm';
+
+await init();
+
+const engine = XfaEngine.fromFields(JSON.stringify([
+  { name: "Name", value: "Alice" },
+  { name: "Total", value: "", calculate: "100 + 21" },
+]));
+
+engine.runCalculations();
+console.log(engine.getFieldValue("form1.Total")); // "121"
+
+const json = engine.exportJson();
+engine.importJson('{"fields": {"form1.Name": "Bob"}}');
+```
+
+### PDF Analysis
+
+```js
+import init, { PdfDoc } from './pkg/xfa_wasm';
+
+await init();
+
+const response = await fetch('document.pdf');
+const data = new Uint8Array(await response.arrayBuffer());
+const doc = PdfDoc.open(data);
+
+console.log(`Pages: ${doc.pageCount()}`);
+
+// Metadata
+const meta = JSON.parse(doc.metadata());
+console.log(`Title: ${meta.title}`);
+
+// Signatures
+if (doc.hasSignatures()) {
+  const sigs = JSON.parse(doc.verifySignatures());
+  for (const sig of sigs) {
+    console.log(`${sig.signer}: integrity ${sig.structural_integrity}`);
+  }
+}
+
+// PDF/A validation
+const report = JSON.parse(doc.validatePdfA("pdfa2b"));
+console.log(`Compliant: ${report.compliant}`);
+```
+
+### Page Rendering
+
+```js
+const raw = doc.renderPage(0, 1.5); // scale factor
+const view = new DataView(raw.buffer);
+const w = view.getUint32(0, true);  // little-endian
+const h = view.getUint32(4, true);
+const pixels = raw.slice(8);
+const imageData = new ImageData(new Uint8ClampedArray(pixels), w, h);
+ctx.putImageData(imageData, 0, 0);
+```
+
+### Annotations
+
+```js
+// Read existing annotations
+const annots = JSON.parse(doc.getAnnotations(0));
+for (const a of annots) {
+  console.log(`${a.subtype} at (${a.rect?.x0}, ${a.rect?.y0})`);
+}
+
+// Add a highlight (returns new PDF bytes)
+const newPdf = PdfDoc.addHighlight(pdfBytes, 0,
+  100, 700, 400, 720,   // rect: x0, y0, x1, y1
+  1.0, 1.0, 0.0);       // color: yellow RGB
+
+// Add a sticky note
+const withNote = PdfDoc.addStickyNote(pdfBytes, 0,
+  50, 750, "Review this section");
+
+// Add free text
+const withText = PdfDoc.addFreeText(pdfBytes, 0,
+  100, 600, 300, 620, "Important!", 12.0);
+```
+
+## TypeScript Support
+
+Typed wrappers are provided in `ts/index.ts`:
+
+```ts
+import { XfaForms, PdfDocument, FieldDef } from './ts/index';
+
+const fields: FieldDef[] = [
+  { name: "Amount", value: "100" },
+];
+const forms = XfaForms.fromFields(fields);
+forms.runCalculations();
+const data = forms.exportJson();
+```
+
+## Features
+
+| Feature | Default | Description |
+|---------|---------|-------------|
+| `render` | Yes | Page rendering via pdf-render |
+| `annotate` | Yes | Annotation read/write via pdf-annot + lopdf |
+
+Build without optional features for a smaller WASM binary:
+
+```bash
+wasm-pack build crates/@pdfluent/wasm --target web -- --no-default-features
+```
+
+## API Reference
+
+### XfaEngine
+
+| Method | Description |
+|--------|-------------|
+| `XfaEngine.fromFields(json)` | Create from JSON field definitions |
+| `XfaEngine.fromJson(json)` | Create from exported JSON |
+| `runCalculations()` | Execute FormCalc calculate scripts |
+| `exportJson()` | Export field values as JSON |
+| `exportSchema()` | Export form schema as JSON |
+| `importJson(json)` | Import field values from JSON |
+| `getFieldValue(path)` | Get field value by SOM path |
+| `setFieldValue(path, value)` | Set field value by SOM path |
+| `nodeCount()` | Number of form nodes |
+| `version()` | Engine version string |
+
+### License Activation
+
+The WASM build runs in Trial mode by default. Output produced by the engine
+is marked via `/Producer` metadata in Trial. Activate a license to remove
+the mark and unlock paid capabilities.
+
+```js
+import init, { activateLicenseKey, licenseStatus } from '@pdfluent/xfa-wasm';
+
+await init();
+activateLicenseKey('tier:enterprise');
+
+const s = licenseStatus();
+console.log(s.tier);            // "Enterprise"
+console.log(s.source);          // "Explicit" | "EnvVar" | "Default"
+console.log(s.outputIsMarked);  // false
+```
+
+**Browser-specific caveats:**
+
+- `activateLicenseFile` is intentionally **not** exposed. Browsers and
+  Workers have no synchronous filesystem access. Fetch the key text
+  yourself (`await fetch(...).then(r => r.text())`) and pass it to
+  `activateLicenseKey`.
+- The `PDFLUENT_LICENSE_KEY` environment variable is honoured only when a
+  Node host provides it; browsers do not expose process env vars.
+- The active tier is **process-global and set-once** within a single WASM
+  instance. Activating a second time with a different tier throws; reload
+  the page or re-initialise the WASM module to switch tiers.
+
+Invalid keys throw `Error`. The key string is never logged.
+
+### PdfDoc
+
+| Method | Description |
+|--------|-------------|
+| `PdfDoc.open(data)` | Open PDF from Uint8Array |
+| `pageCount()` | Number of pages |
+| `pageWidth(index)` | Page width in points |
+| `pageHeight(index)` | Page height in points |
+| `metadata()` | Document metadata as JSON |
+| `signatures()` | Signature info as JSON array |
+| `hasSignatures()` | Whether document has signatures |
+| `verifySignatures()` | Verify signatures, returns JSON |
+| `validatePdfA(level)` | PDF/A compliance check |
+| `dssInfo()` | Document Security Store info |
+| `renderPage(index, scale)` | Render page to RGBA (feature: render) |
+| `renderThumbnail(index, maxDim)` | Render thumbnail (feature: render) |
+| `renderPageToCanvas(canvas, index, scale)` | Render page directly to a Canvas2D (feature: render) |
+| `getAnnotations(index)` | Read annotations as JSON (feature: annotate) |
+| `getTextPositions(index)` | Per-glyph text positions as JSON |
+| `merge(other)` | Append another PDF, returns merged bytes |
+| `flattenXfa()` | Flatten XFA form fields into static PDF content |
+| `convertToPdfa(level)` | Convert to PDF/A 1b/2b/3b, returns bytes |
+
+### Page manipulation (Wave 2)
+
+| Method | Description |
+|--------|-------------|
+| `deletePages(pages: Uint32Array)` | Remove the listed 0-based pages; returns new bytes |
+| `rotatePage(pageIndex, degrees)` | Rotate one page by 90/180/270 (or negative); returns new bytes |
+| `reorderPages(newOrder: Uint32Array)` | Permute pages; returns new bytes |
+| `extractPages(pages: Uint32Array)` | Extract the listed pages into a new PDF (use for split) |
+
+### Edit, annotate, redact, optimise (Wave 2)
+
+| Method | Description |
+|--------|-------------|
+| `setFormField(path, value)` | Set a single AcroForm text field; returns new bytes |
+| `setFormFields(jsonObject)` | Bulk-set form fields from a JSON `{path: value}` map |
+| `addHighlight(pageIndex, x, y, w, h, colorHex?)` | Highlight annotation (feature: annotate) |
+| `addStickyNote(pageIndex, x, y, contents)` | Sticky note annotation (feature: annotate) |
+| `addFreeText(pageIndex, x, y, w, h, contents)` | Free-text annotation (feature: annotate) |
+| `addTextWatermark(text, opacity)` | Diagonal text watermark on all pages |
+| `redactRegion(pageIndex, x, y, w, h)` | Permanently remove content in a rectangle (GDPR-safe) |
+| `redactSearch(query)` | Find all literal matches of `query` and redact each |
+| `compress()` | Re-deflate content streams; returns optimised bytes |
+
+### PdfDocMut (Wave 3) — **recommended for editor workflows**
+
+`PdfDocMut` is a stateful editing handle. Open once, mutate in place,
+save once. The `PdfDoc` class above is great for inspection and
+single-shot transformations, but for an editor that applies multiple
+operations to the same document, **`PdfDocMut` is dramatically faster**:
+9-step sessions go from ~16 parse passes to **1 parse + 1 serialise**
+(measured 2.7× wall-clock speedup; bigger on larger documents).
+
+| Method | Description |
+|--------|-------------|
+| `PdfDocMut.open(bytes)` | Open for editing |
+| `pageCount()` | Live page count after any mutations so far |
+| `save()` | Serialise current state to `Uint8Array`. Non-consuming — keep editing after |
+| `free()` | Release the WASM-side memory deterministically |
+| `deletePages(pages)` | In place |
+| `rotatePage(pageIndex, degrees)` | In place |
+| `reorderPages(newOrder)` | In place |
+| `extractPages(pages)` | Returns bytes for a NEW subdocument; current editor unchanged |
+| `setFormField(path, value)` | In place |
+| `setFormFields(jsonObject)` | In place, bulk |
+| `addHighlight(pageIndex, x, y, w, h, colorHex?)` | In place (feature: annotate) |
+| `addStickyNote(pageIndex, x, y, contents)` | In place (feature: annotate) |
+| `addFreeText(pageIndex, x, y, w, h, contents)` | In place (feature: annotate) |
+| `addTextWatermark(text, opacity)` | In place |
+| `redactRegion(pageIndex, x, y, w, h)` | In place (GDPR-safe permanent removal) |
+| `redactSearch(query)` | In place |
+| `compress()` | In place |
+
+#### Editor flow with PdfDocMut
+
+```js
+import init, { PdfDocMut } from '@pdfluent/xfa-wasm';
+
+await init();
+const bytes  = new Uint8Array(await (await fetch('/document.pdf')).arrayBuffer());
+const editor = PdfDocMut.open(bytes);
+
+// All edits operate on the same internal lopdf::Document — no re-parse.
+editor.reorderPages(new Uint32Array([1, 0, 2]));
+editor.addTextWatermark('CONCEPT', 0.3);
+editor.addHighlight(0, 100, 700, 200, 20, '#ffeb3b');
+editor.redactSearch('John Doe');
+editor.compress();
+
+// Save once at the end.
+const out = editor.save();
+editor.free();
+const blob = new Blob([out], { type: 'application/pdf' });
+```
+
+#### One-shot helpers on PdfDoc (kept for compatibility)
+
+For a workflow with a single mutation, the stateless `PdfDoc` methods
+are equally fine. They are kept for backward compatibility but the
+recommended path for any multi-step edit is `PdfDocMut`.
+
+```js
+import init, { PdfDoc } from '@pdfluent/xfa-wasm';
+await init();
+const doc = PdfDoc.open(bytes);
+const merged = doc.merge(otherBytes);   // single op, one-shot
+```
+
+## Bundle size
+
+| Build | Tarball | Unpacked |
+|-------|---------|----------|
+| 1.0.0-beta.8 (pre-Wave 2) | 3.6 MB | 10.2 MB |
+| **1.0.0-beta.9 (Wave 2)** | **3.8 MB** | **~11 MB** |
+
+Wave 2 added 13 new methods for ~0.2 MB of binary growth. Well under the
+15 MB hard limit and well under the 5 MB gzipped soft target.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@pdfluent/sdk-wasm",
+  "type": "module",
+  "description": "PDFluent browser SDK — read, edit, annotate, redact, sign, and validate PDFs (including XFA) entirely client-side via WASM.",
+  "version": "1.0.0-beta.10",
+  "license": "SEE LICENSE IN LICENSE",
+  "files": [
+    "xfa_wasm_bg.wasm",
+    "xfa_wasm.js",
+    "xfa_wasm.d.ts"
+  ],
+  "main": "xfa_wasm.js",
+  "types": "xfa_wasm.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ],
+  "keywords": [
+    "pdf",
+    "wasm",
+    "pdfluent",
+    "browser",
+    "sdk",
+    "xfa",
+    "forms",
+    "annotate",
+    "redact"
+  ],
+  "homepage": "https://pdfluent.com",
+  "author": "Innovation Trigger BV <team@pdfluent.com>"
+}