@pdfluent/sdk-wasm 1.1.0 → 1.3.0

package/README.md

@@ -3,11 +3,11 @@
 [Source on GitHub](https://github.com/pdfluent/pdfluent-sdk) · [Documentation](https://pdfluent.com/docs) · [Report an issue](https://github.com/pdfluent/pdfluent-sdk/issues)
 
 WebAssembly distribution of the PDFluent PDF engine. Read, edit, annotate,
-redact, sign, and validate PDFs (including XFA) entirely in the browser —
+redact, sign, and validate PDFs (including XFA) entirely in the browser -
 zero bytes go to a server.
 
 Published as `@pdfluent/sdk-wasm` on npm. (The crate directory is named
-`xfa-wasm` for historical XFA roots — the published npm package covers the
+`xfa-wasm` for historical XFA roots - the published npm package covers the
 full SDK surface needed for an in-browser PDF editor. Previously known as
 `@pdfluent/xfa-wasm`; renamed to `@pdfluent/sdk-wasm`.)
 
@@ -22,7 +22,7 @@ full SDK surface needed for an in-browser PDF editor. Previously known as
 - **Text watermark**: diagonal text watermark with configurable opacity
 - **Redaction**: by region (rectangle) or by search query (permanent removal: the content is gone, not covered)
 - **Stream compression**: re-deflate content streams for smaller file size
-- **`PdfDocMut`**: stateful editing handle — open once, mutate in place,
+- **`PdfDocMut`**: stateful editing handle - open once, mutate in place,
   save once. One parse and one serialise for a whole editing session instead
   of one per operation, with identical output bytes.
 
@@ -216,7 +216,7 @@ wasm-pack build crates/xfa-wasm --target web -- --no-default-features
 | `redactSearch(query)` | Find all literal matches of `query` and redact each |
 | `compress()` | Re-deflate content streams; returns optimised bytes |
 
-### PdfDocMut — **recommended for editor workflows**
+### PdfDocMut - **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
@@ -229,14 +229,14 @@ serialise per step.
 |--------|-------------|
 | `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 |
+| `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 — text, checkbox, radio, and choice; updates `/V`, `/AS`, and `/AP` |
-| `setFormFields(jsonObject)` | In place, bulk — same full chain for each entry |
+| `setFormField(path, value)` | In place - text, checkbox, radio, and choice; updates `/V`, `/AS`, and `/AP` |
+| `setFormFields(jsonObject)` | In place, bulk - same full chain for each entry |
 | `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) |
@@ -254,7 +254,7 @@ 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.
+// 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');
@@ -295,4 +295,4 @@ add-on). The two texts are `LICENSE` and `LICENSE-COMMERCIAL` in this package.
 - **Documentation:** <https://pdfluent.com/docs>
 - **Pricing:** <https://pdfluent.com/sdk/pricing>
 - **PDFluent editor** (source-available): <https://github.com/pdfluent/pdfluent>. The free desktop app this SDK powers.
-- Built by [Innovation Trigger BV](https://pdfluent.com)
+- Built by [Innovation Trigger B.V.](https://pdfluent.com)

package/THIRD_PARTY_LICENSES.txt

@@ -133,8 +133,27 @@ Two vendored files, both Adobe's own CMap resources, both BSD-3-Clause:
                                              form, read by the PDF/A fixups for
                                              EUC-encoded CID text
                                              Copyright 1990-2019 Adobe
+  crates/pdf-manip/resources/predefined-cmaps/pack.z
+                                             the 61 predefined CMaps of the PDF
+                                             specification as one compressed
+                                             pack, built by
+                                             scripts/pdfa/build_cmap_pack.py
+                                             from github.com/adobe-type-tools/
+                                             cmap-resources, commit f5cf3bca
+                                             (BSD-3-Clause); read by the PDF/A
+                                             conversion so it needs no
+                                             poppler-data on the host
+                                             Copyright 1990-2023 Adobe
+  crates/pdf-manip/resources/predefined-cmaps/PROVENANCE.sha256
+                                             ours: the SHA-256 of each source
+                                             file and of the pack built from
+                                             them
+  crates/pdf-manip/resources/predefined-cmaps/LICENSE-Adobe-CMap.txt
+                                             the full BSD-3-Clause text and
+                                             Adobe's notice for the pack above
 
 Upstream licence texts in the tree:
+  crates/pdf-manip/resources/predefined-cmaps/LICENSE-Adobe-CMap.txt  (BSD-3-Clause, full text)
   crates/pdf-font/assets/LICENSE.txt              (BSD-3-Clause, full text)
   crates/pdf-manip/resources/cmap/GB-EUC-H        (the notice is the file's own
                                                    header, as Adobe ships it)
@@ -321,7 +340,8 @@ unic-char-range, unic-common, unic-ucd-ident, unic-ucd-version, unicode-bidi,
 unicode-normalization, unicode-properties, unicode-segmentation, unicode-width,
 unicode-xid, url, utf-8, utf8_iter, utf8parse, uuid, vello_common, vello_cpu,
 wasm-bindgen, wasm-bindgen-futures, wasm-bindgen-macro,
-wasm-bindgen-macro-support, wasm-bindgen-shared, wasm-streams, web-sys,
+wasm-bindgen-macro-support, wasm-bindgen-shared, wasm-streams, wasmi, wasmi_collections, wasmi_core,
+wasmi_ir, web-sys,
 web-time, web_atoms, weezl, winapi, winapi-i686-pc-windows-gnu,
 winapi-x86_64-pc-windows-gnu, window-vibrancy, windows, windows-collections,
 windows-core, windows-future, windows-implement, windows-interface,
@@ -412,8 +432,7 @@ new_debug_unreachable, nom, nom_locate, noop_proc_macro, nu-ansi-term,
 number_prefix, objc2, objc2-encode, objc2-foundation, open, openssl-sys,
 os_pipe, pango, pango-sys, pdf-bench, pdf-desktop, pdf-diff, pdf-java,
 pdfluent-lopdf, phf, phf_generator, phf_macros, phf_shared, plist,
-precomputed-hash, quick-xml, redox_syscall, redox_users, rfd, rgb, rquickjs,
-rquickjs-core, rquickjs-macro, rquickjs-sys, rusqlite, schannel, schemars,
+precomputed-hash, quick-xml, redox_syscall, redox_users, rfd, rgb, rusqlite, schannel, schemars,
 schemars_derive, sharded-slab, shared_child, sigchld, simd-adler32,
 simd_helpers, slab, soup3, soup3-sys, spin, strsim, synstructure, tiff,
 tokio, tokio-macros, tokio-native-tls, tokio-util, tower, tower-http,
@@ -731,6 +750,44 @@ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+================================================================================
+QuickJS-ng — the script engine, compiled into xfa-js-sandboxed's WebAssembly module
+https://github.com/quickjs-ng/quickjs   (version 0.7.0)
+================================================================================
+
+QuickJS (MIT) is a component of crates/xfa-js-sandboxed/wasm-guest/qjs_guest.wasm:
+the module is compiled from the C sources in wasm-guest/quickjs/ (two changes,
+listed in wasm-guest/PATCHES.md) and is interpreted by the wasmi crate. No native
+C code runs. The module also contains code from wasi-libc (Apache-2.0 WITH
+LLVM-exception; MIT and BSD-2-Clause parts derived from musl) and LLVM
+compiler-rt (Apache-2.0 WITH LLVM-exception), linked in by the toolchain
+(zig 0.16.0, build tooling only, not shipped). See wasm-guest/NOTICE.
+
+The MIT License (MIT)
+ 
+Copyright (c) 2017-2021 Fabrice Bellard
+Copyright (c) 2017-2021 Charlie Gordon
+Copyright (c) 2023 Ben Noordhuis
+Copyright (c) 2023 Saúl Ibarra Corretgé
+
+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.
+
 ================================================================================
 tract — ONNX inference for the optional vision layer (#636)
 https://github.com/sonos/tract
@@ -842,3 +899,27 @@ SOFTWARE
 ================================================================================
 END OF THIRD PARTY LICENSES
 ================================================================================
+
+================================================================================
+qrcodegen 1.8.0 — QR Code generator library (MIT)
+https://www.nayuki.io/page/qr-code-generator-library
+================================================================================
+
+Copyright (c) Project Nayuki. (MIT License)
+https://www.nayuki.io/page/qr-code-generator-library
+
+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.

package/package.json

@@ -2,8 +2,12 @@
   "name": "@pdfluent/sdk-wasm",
   "type": "module",
   "description": "PDFluent browser SDK — find and replace PDF text programmatically while preserving fonts and layout, plus edit, annotate, redact, sign and validate PDFs (including XFA), entirely client-side via WASM.",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "license": "SEE LICENSE IN LICENSE-OFFER",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pdfluent/pdfluent-sdk"
+  },
   "files": [
     "xfa_wasm_bg.wasm",
     "xfa_wasm.js",
@@ -14,7 +18,8 @@
     "LICENSE-COMMERCIAL",
     "LICENSE-OFFER",
     "NOTICE",
-    "THIRD_PARTY_LICENSES.txt"
+    "THIRD_PARTY_LICENSES.txt",
+    "xfa_wasm.augment.d.ts"
   ],
   "main": "xfa_wasm.js",
   "types": "xfa_wasm.d.ts",
@@ -39,9 +44,21 @@
     "redact"
   ],
   "homepage": "https://pdfluent.com",
-  "author": "Innovation Trigger BV <team@pdfluent.com>",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/pdfluent/pdfluent-sdk"
+  "author": "Innovation Trigger B.V. <team@pdfluent.com>",
+  "bugs": {
+    "url": "https://github.com/pdfluent/pdfluent-sdk/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./xfa_wasm.d.ts",
+      "import": "./xfa_wasm.js",
+      "default": "./xfa_wasm.js"
+    },
+    "./augment": {
+      "types": "./xfa_wasm.augment.d.ts"
+    },
+    "./xfa_wasm_bg.wasm": "./xfa_wasm_bg.wasm",
+    "./package.json": "./package.json",
+    "./*": "./*"
   }
 }

package/xfa_wasm.augment.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Hand-maintained TypeScript supplement for `@pdfluent/sdk-wasm`.
+ *
+ * Augments the generated `xfa_wasm.d.ts` with:
+ * - `PdfluentError` class declaration (errors thrown by all WASM methods)
+ * - `XfaWasmError` legacy alias (kept for older consumer code that imported
+ *   the pre-1.0 type name)
+ * - `free()` lifecycle documentation for `PdfDoc` and `XfaEngine`
+ *
+ * Usage: import this file alongside the main module in projects that need
+ * strict error handling:
+ *
+ * ```ts
+ * import init, { PdfDoc } from '@pdfluent/sdk-wasm';
+ * import type { PdfluentError } from '@pdfluent/sdk-wasm/pkg-types/xfa_wasm.augment';
+ * ```
+ *
+ * Or add this file to your `tsconfig.json` `types` array for global augmentation.
+ */
+
+/* --- Typed error class ----------------------------------------------------- */
+
+/**
+ * Structured error thrown by every fallible PDFluent WASM operation.
+ *
+ * `PdfluentError` is a real `class` (extends `Error`) registered on
+ * `globalThis.__PdfluentError` the first time the WASM module loads. The
+ * thrown instance is a true subclass of `Error`, so
+ * `error instanceof PdfluentError` works in user code.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import init, { PdfDoc, PdfluentError } from '@pdfluent/sdk-wasm';
+ * await init();
+ *
+ * try {
+ *   using doc = PdfDoc.open(corruptBytes);
+ * } catch (e) {
+ *   if (e instanceof PdfluentError) {
+ *     console.error(`[${e.code}] ${e.message} (in ${e.operation})`);
+ *     if (e.code === 'E-PARSE-INVALID-PDF') {
+ *       // show "not a valid PDF" UI feedback
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Properties
+ *
+ * | Property | Type | Description |
+ * |----------|------|-------------|
+ * | `code` | `string` | Stable C8 catalogue code, format `E-<CATEGORY>-<SPECIFIC>`. |
+ * | `message` | `string` | Human-readable description. |
+ * | `operation` | `string` | API call that failed (e.g. `"PdfDoc.open"`). |
+ * | `help` | `string` | Optional actionable hint (may be empty). |
+ * | `docsUrl` | `string` | Deep-link to documentation at `https://pdfluent.com/errors/<code>`. |
+ * | `legacyCode` | `string` | Pre-1.0 SCREAMING_SNAKE_CASE identifier, preserved for backward compatibility. |
+ *
+ * ## C8 Error codes (canonical, from `docs/error_catalogue.md`)
+ *
+ * | Code | Thrown by |
+ * |------|-----------|
+ * | `E-PARSE-INVALID-PDF` | `PdfDoc.open` — bytes are not a valid PDF |
+ * | `E-IO-GENERIC` | I/O failure |
+ * | `E-PARSE-UNSUPPORTED-VERSION` | `PdfDoc.open` — PDF version too new |
+ * | `E-COMPLIANCE-PDFA-INVALID` | `convertToPdfa`, `validatePdfA` |
+ * | `E-ENV-UNSUPPORTED-ON-WASM` | Native-only operation invoked from WASM |
+ * | `E-INTERNAL` | Internal safety-net |
+ * | `E-WASM-INVALID-ARGUMENT` | Argument validation (e.g. `validatePdfA("xyz")`) |
+ * | `E-WASM-PAGE-OUT-OF-RANGE` | Page index outside `0..page_count` |
+ * | `E-WASM-RENDER-FAILED` | `renderPage`, `renderPageToCanvas` |
+ * | `E-WASM-RENDER-FALLBACK` | Vector renderer hit unsupported feature |
+ * | `E-WASM-TEXT-EXTRACT-FAILED` | `getTextPositions` |
+ * | `E-WASM-XFA-FAILED` | `flattenXfa` |
+ * | `E-WASM-MERGE-FAILED` | `merge` |
+ * | `E-WASM-SAVE-FAILED` | Internal save / serialize |
+ * | `E-WASM-INVALID-JSON` | `fromFields`, `fromJson`, `importJson`, schema export |
+ * | `E-WASM-FORMCALC-FAILED` | `runCalculations` |
+ * | `E-SECURITY-DECRYPTION-FAILED` | `decryptPdf`, `signPdf`: wrong password, or one that does not entitle the call |
+ * | `E-WASM-SIGN-FAILED` | `signPdf` |
+ *
+ * ## Backward compatibility
+ *
+ * Before 1.0 the WASM binding threw `XfaWasmError` with a SCREAMING_SNAKE_CASE
+ * `.code` property. That identifier is preserved on the new `.legacyCode`
+ * property and on the `XfaWasmError` type alias (see below) so existing
+ * consumer code keeps working. Newly-written code should use `.code` with the
+ * `E-<CATEGORY>-<SPECIFIC>` strings.
+ */
+export declare class PdfluentError extends Error {
+  /** Stable C8 catalogue code in `E-<CATEGORY>-<SPECIFIC>` format. */
+  readonly code: string;
+  /** Short identifier of the API call that failed (e.g. `"PdfDoc.open"`). */
+  readonly operation: string;
+  /** Optional actionable hint for developers. May be empty string. */
+  readonly help: string;
+  /** Deep-link into the error documentation. */
+  readonly docsUrl: string;
+  /** Pre-1.0 SCREAMING_SNAKE_CASE identifier, kept for backward compatibility. */
+  readonly legacyCode: string;
+}
+
+/**
+ * Legacy alias for `PdfluentError`. Existing code that does
+ * `import { XfaWasmError }` keeps compiling; new code should use
+ * `PdfluentError`.
+ *
+ * @deprecated Use {@link PdfluentError}.
+ */
+export type XfaWasmError = PdfluentError;
+
+/* --- Type guards ----------------------------------------------------------- */
+
+/**
+ * Type guard: returns `true` when `e` is a `PdfluentError` thrown by the WASM module.
+ *
+ * ```ts
+ * try {
+ *   doc.flattenXfa();
+ * } catch (e) {
+ *   if (isPdfluentError(e)) {
+ *     console.error(e.code, e.help);
+ *   }
+ * }
+ * ```
+ */
+export declare function isPdfluentError(e: unknown): e is PdfluentError;
+
+/**
+ * Legacy alias for {@link isPdfluentError}.
+ * @deprecated Use {@link isPdfluentError}.
+ */
+export declare function isXfaWasmError(e: unknown): e is PdfluentError;
+
+/* --- Lifecycle augmentation ----------------------------------------------- */
+
+/**
+ * Lifecycle contract for WASM objects that hold native memory.
+ *
+ * Both `PdfDoc` and `XfaEngine` allocate memory in the WASM heap. The JavaScript
+ * garbage collector does **not** free WASM heap memory — you must call `free()`
+ * explicitly, or use the `using` keyword (TypeScript 5.2+, requires `--target ES2022`
+ * or newer and `lib: ["ESNext.Disposable"]`).
+ *
+ * ### Option 1 — `using` (recommended, TypeScript 5.2+)
+ *
+ * ```ts
+ * {
+ *   using doc = PdfDoc.open(bytes);
+ *   const count = doc.pageCount();
+ * } // doc.free() called automatically here
+ * ```
+ *
+ * ### Option 2 — explicit `free()`
+ *
+ * ```ts
+ * const doc = PdfDoc.open(bytes);
+ * try {
+ *   const count = doc.pageCount();
+ * } finally {
+ *   doc.free();
+ * }
+ * ```
+ *
+ * ### After `free()`
+ *
+ * Once `free()` is called, the object's native pointer is invalidated. Any
+ * subsequent method call throws a `PdfluentError` with code `"E-INTERNAL"`.
+ */
+export interface WasmLifecycle {
+  /**
+   * Release all native WASM heap memory owned by this object.
+   *
+   * - Must be called when you are done with the object, unless you used `using`.
+   * - After calling `free()`, all methods throw.
+   * - Calling `free()` twice is safe (no-op).
+   * - Equivalent to `[Symbol.dispose]()`.
+   */
+  free(): void;
+
+  /**
+   * Alias for `free()`, called automatically by the `using` statement.
+   *
+   * See {@link WasmLifecycle.free} for full lifecycle documentation.
+   */
+  [Symbol.dispose](): void;
+}

package/xfa_wasm.d.ts

@@ -122,7 +122,7 @@ export enum ChromaSampling {
  *
  * # Errors
  *
- * All fallible methods throw a `PdfluentError` — a standard `Error` subclass with
+ * All fallible methods throw a `PdfluentError` - a standard `Error` subclass with
  * these properties:
  * - `code`: stable C8 catalogue identifier in `E-<CATEGORY>-<SPECIFIC>` format
  *   (e.g. `"E-PARSE-INVALID-PDF"`). Use this for programmatic dispatch.
@@ -330,6 +330,10 @@ export class PdfDoc {
     /**
      * Search-and-redact: every match of `query` (literal text, case-sensitive)
      * is permanently removed from every page.
+     *
+     * Throws `E-PARSE-INVALID-PDF` when a page's text could not be read:
+     * that page was not searched, so returning bytes would read as "no
+     * matches there" (#698).
      */
     redactSearch(query: string): Uint8Array;
     /**
@@ -368,7 +372,7 @@ export class PdfDoc {
      * Render a page directly to an HTML canvas element (wasm32 only).
      *
      * Calls `canvas.getContext("2d")`, sets the canvas dimensions to the
-     * rendered pixel size, and calls `putImageData` — no round-trip through
+     * rendered pixel size, and calls `putImageData` - no round-trip through
      * a JS Uint8Array.  XFA documents are auto-flattened before rendering.
      *
      * ```js
@@ -426,6 +430,16 @@ export class PdfDoc {
      * extraction fails.
      */
     text(page_index: number): string;
+    /**
+     * Every text block of the document with its page and enclosing box, as
+     * JSON (#416): `[{"text": "...", "bbox": [xMin, yMin, xMax, yMax], "page": 0}]`.
+     *
+     * `page` is 0-based like every page index in this binding; `bbox` is in PDF
+     * points with the origin at the bottom left (PDF space, not the y-down CSS
+     * space `getTextPositions` returns). An XFA form is read from its flattened
+     * form, as `text` and `getTextPositions` do.
+     */
+    textWithLayout(): string;
     /**
      * Convert this PDF to a Word `.docx` package.
      *
@@ -475,7 +489,7 @@ export class PdfDocMut {
     addFreeText(page_index: number, x: number, y: number, w: number, h: number, contents: string): void;
     /**
      * Add a highlight annotation over the given page rectangle.
-     * `color_hex` like `"#ffeb3b"` — defaults to yellow when `None`.
+     * `color_hex` like `"#ffeb3b"` - defaults to yellow when `None`.
      */
     addHighlight(page_index: number, x: number, y: number, w: number, h: number, color_hex?: string | null): void;
     /**
@@ -532,6 +546,15 @@ export class PdfDocMut {
      * `formatted = false`, `bytesChanged = 0`, no error.
      */
     formatTextSpan(page_num: number, run_index: number, font_size?: number | null, color?: string | null): string;
+    /**
+     * The images drawn on a page (0-based `pageIndex`) as JSON, in drawing
+     * order, form-nested and inline images included:
+     * `[{"formPath":[…],"opIndex":n,"kind":"xobject"|"inline","resourceName":…,
+     * "formNames":[…],"ctm":[6],"bbox":[x0,y0,x1,y1],"pixelWidth":…,
+     * "pixelHeight":…,"hasSmask":…}]`. `bbox` is in page space, origin at the
+     * bottom left. An entry is the handle the three edit methods take.
+     */
+    imagePlacements(page_index: number): string;
     /**
      * Open a PDF for editing.
      */
@@ -547,21 +570,35 @@ export class PdfDocMut {
     /**
      * Search-and-redact: every literal match of `query` is permanently
      * removed from every page.
+     *
+     * Throws `E-PARSE-INVALID-PDF` when a page's text could not be read:
+     * that page was not searched, so success would read as "no matches
+     * there" (#698). The document is then left as it was.
      */
     redactSearch(query: string): void;
+    /**
+     * Remove one placed image. The image data leaves the file when nothing
+     * else uses it.
+     */
+    removeImage(page_index: number, handle_json: string): void;
     /**
      * Re-order pages. `new_order` is a permutation of `0..page_count`.
      */
     reorderPages(new_order: Uint32Array): void;
     /**
-     * G3 — Replace a text span on a page.
+     * Swap the picture of one placed image for JPEG or PNG `data`, fitted
+     * inside the old placement and centred. Returns the new handle as JSON.
+     */
+    replaceImage(page_index: number, handle_json: string, data: Uint8Array): string;
+    /**
+     * G3 - Replace a text span on a page.
      *
      * The editor passes the **exact** text it extracted from
      * `getTextPositions()` as `original_text`, and the desired
      * replacement as `replacement_text`. The replacement is
      * re-encoded into the same font used by the matched span
      * (subset-font fallback applies when the original font cannot
-     * encode the replacement — see
+     * encode the replacement - see
      * `pdf-manip::text_replace::replace_text`).
      *
      * `page_num` is **1-based** to match the rest of the
@@ -582,11 +619,11 @@ export class PdfDocMut {
      *
      * Typed unsupported codes (all set `replaced=false`):
      *
-     * - `"NO_MATCH"` — `original_text` not found on the page.
-     * - `"ENCODING_UNSUPPORTED"` — replacement contains characters
+     * - `"NO_MATCH"` - `original_text` not found on the page.
+     * - `"ENCODING_UNSUPPORTED"` - replacement contains characters
      *   the matched font cannot encode and no fallback font is
      *   available.
-     * - `"REPLACE_FAILED"` — anything else (lopdf I/O,
+     * - `"REPLACE_FAILED"` - anything else (lopdf I/O,
      *   serialisation, FontMap construction, …). `reason` carries
      *   the lower-level error message.
      *
@@ -611,7 +648,7 @@ export class PdfDocMut {
     /**
      * Set a single AcroForm field value (text, checkbox, radio, or choice).
      *
-     * Delegates to [`pdf_forms::apply_field_value`] — the single SDK
+     * Delegates to [`pdf_forms::apply_field_value`] - the single SDK
      * writeback chain. It keeps `/V` (ASCII literal else UTF-16BE+BOM),
      * per-widget `/AS`, and regenerated `/AP` streams consistent, resolves
      * fully-qualified names through `/Kids`, and rejects read-only fields.
@@ -622,6 +659,13 @@ export class PdfDocMut {
      * `{"field.path": "value", ...}`.
      */
     setFormFields(fields_json: string): void;
+    /**
+     * Move or resize one placed image so its bounding box becomes
+     * `[x0, y0, x1, y1]` in page space. `handleJson` is an entry of
+     * `imagePlacements`. Returns the new handle as JSON. An edit inside a Form
+     * XObject copies the form for this page, so other pages keep the original.
+     */
+    setImageRect(page_index: number, handle_json: string, x0: number, y0: number, x1: number, y1: number): string;
     /**
      * Select multiple options on a multi-select list box.
      *
@@ -723,7 +767,7 @@ export class TextEditor {
  *
  * # Errors
  *
- * All fallible methods throw a `PdfluentError` — a standard `Error` subclass with
+ * All fallible methods throw a `PdfluentError` - a standard `Error` subclass with
  * these properties:
  * - `code`: stable C8 catalogue identifier in `E-<CATEGORY>-<SPECIFIC>` format
  *   (e.g. `"E-PARSE-INVALID-PDF"`). Use this for programmatic dispatch.
@@ -893,6 +937,7 @@ export interface InitOutput {
     readonly pdfdoc_setFormFields: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdoc_signatures: (a: number, b: number) => void;
     readonly pdfdoc_text: (a: number, b: number, c: number) => void;
+    readonly pdfdoc_textWithLayout: (a: number, b: number) => void;
     readonly pdfdoc_toDocx: (a: number, b: number) => void;
     readonly pdfdoc_toPptx: (a: number, b: number) => void;
     readonly pdfdoc_toXlsx: (a: number, b: number) => void;
@@ -908,16 +953,20 @@ export interface InitOutput {
     readonly pdfdocmut_deletePages: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdocmut_extractPages: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdocmut_formatTextSpan: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly pdfdocmut_imagePlacements: (a: number, b: number, c: number) => void;
     readonly pdfdocmut_open: (a: number, b: number, c: number) => void;
     readonly pdfdocmut_pageCount: (a: number) => number;
     readonly pdfdocmut_redactRegion: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly pdfdocmut_redactSearch: (a: number, b: number, c: number, d: number) => void;
+    readonly pdfdocmut_removeImage: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly pdfdocmut_reorderPages: (a: number, b: number, c: number, d: number) => void;
+    readonly pdfdocmut_replaceImage: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly pdfdocmut_replaceTextSpan: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly pdfdocmut_rotatePage: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdocmut_save: (a: number, b: number) => void;
     readonly pdfdocmut_setFormField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly pdfdocmut_setFormFields: (a: number, b: number, c: number, d: number) => void;
+    readonly pdfdocmut_setImageRect: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
     readonly pdfdocmut_setMultiSelect: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly pdfdocmut_setTextRunStyle: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
     readonly signPdf: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;

package/xfa_wasm.js

@@ -1,5 +1,5 @@
 /* @ts-self-types="./xfa_wasm.d.ts" */
-import { __pdfluent_error_ctor } from './snippets/xfa-wasm-d1985887593da269/inline0.js';
+import { __pdfluent_error_ctor } from './snippets/xfa-wasm-d23d7ce846a87fdd/inline0.js';
 
 
 /**
@@ -45,7 +45,7 @@ export const ChromaSampling = Object.freeze({
  *
  * # Errors
  *
- * All fallible methods throw a `PdfluentError` — a standard `Error` subclass with
+ * All fallible methods throw a `PdfluentError` - a standard `Error` subclass with
  * these properties:
  * - `code`: stable C8 catalogue identifier in `E-<CATEGORY>-<SPECIFIC>` format
  *   (e.g. `"E-PARSE-INVALID-PDF"`). Use this for programmatic dispatch.
@@ -725,6 +725,10 @@ export class PdfDoc {
     /**
      * Search-and-redact: every match of `query` (literal text, case-sensitive)
      * is permanently removed from every page.
+     *
+     * Throws `E-PARSE-INVALID-PDF` when a page's text could not be read:
+     * that page was not searched, so returning bytes would read as "no
+     * matches there" (#698).
      * @param {string} query
      * @returns {Uint8Array}
      */
@@ -819,7 +823,7 @@ export class PdfDoc {
      * Render a page directly to an HTML canvas element (wasm32 only).
      *
      * Calls `canvas.getContext("2d")`, sets the canvas dimensions to the
-     * rendered pixel size, and calls `putImageData` — no round-trip through
+     * rendered pixel size, and calls `putImageData` - no round-trip through
      * a JS Uint8Array.  XFA documents are auto-flattened before rendering.
      *
      * ```js
@@ -1048,6 +1052,40 @@ export class PdfDoc {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * Every text block of the document with its page and enclosing box, as
+     * JSON (#416): `[{"text": "...", "bbox": [xMin, yMin, xMax, yMax], "page": 0}]`.
+     *
+     * `page` is 0-based like every page index in this binding; `bbox` is in PDF
+     * points with the origin at the bottom left (PDF space, not the y-down CSS
+     * space `getTextPositions` returns). An XFA form is read from its flattened
+     * form, as `text` and `getTextPositions` do.
+     * @returns {string}
+     */
+    textWithLayout() {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.pdfdoc_textWithLayout(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr1 = r0;
+            var len1 = r1;
+            if (r3) {
+                ptr1 = 0; len1 = 0;
+                throw takeObject(r2);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+        }
+    }
     /**
      * Convert this PDF to a Word `.docx` package.
      *
@@ -1228,7 +1266,7 @@ export class PdfDocMut {
     }
     /**
      * Add a highlight annotation over the given page rectangle.
-     * `color_hex` like `"#ffeb3b"` — defaults to yellow when `None`.
+     * `color_hex` like `"#ffeb3b"` - defaults to yellow when `None`.
      * @param {number} page_index
      * @param {number} x
      * @param {number} y
@@ -1469,6 +1507,40 @@ export class PdfDocMut {
             wasm.__wbindgen_export4(deferred3_0, deferred3_1, 1);
         }
     }
+    /**
+     * The images drawn on a page (0-based `pageIndex`) as JSON, in drawing
+     * order, form-nested and inline images included:
+     * `[{"formPath":[…],"opIndex":n,"kind":"xobject"|"inline","resourceName":…,
+     * "formNames":[…],"ctm":[6],"bbox":[x0,y0,x1,y1],"pixelWidth":…,
+     * "pixelHeight":…,"hasSmask":…}]`. `bbox` is in page space, origin at the
+     * bottom left. An entry is the handle the three edit methods take.
+     * @param {number} page_index
+     * @returns {string}
+     */
+    imagePlacements(page_index) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.pdfdocmut_imagePlacements(retptr, this.__wbg_ptr, page_index);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr1 = r0;
+            var len1 = r1;
+            if (r3) {
+                ptr1 = 0; len1 = 0;
+                throw takeObject(r2);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+        }
+    }
     /**
      * Open a PDF for editing.
      * @param {Uint8Array} bytes
@@ -1523,6 +1595,10 @@ export class PdfDocMut {
     /**
      * Search-and-redact: every literal match of `query` is permanently
      * removed from every page.
+     *
+     * Throws `E-PARSE-INVALID-PDF` when a page's text could not be read:
+     * that page was not searched, so success would read as "no matches
+     * there" (#698). The document is then left as it was.
      * @param {string} query
      */
     redactSearch(query) {
@@ -1540,6 +1616,27 @@ export class PdfDocMut {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Remove one placed image. The image data leaves the file when nothing
+     * else uses it.
+     * @param {number} page_index
+     * @param {string} handle_json
+     */
+    removeImage(page_index, handle_json) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(handle_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.pdfdocmut_removeImage(retptr, this.__wbg_ptr, page_index, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Re-order pages. `new_order` is a permutation of `0..page_count`.
      * @param {Uint32Array} new_order
@@ -1560,14 +1657,50 @@ export class PdfDocMut {
         }
     }
     /**
-     * G3 — Replace a text span on a page.
+     * Swap the picture of one placed image for JPEG or PNG `data`, fitted
+     * inside the old placement and centred. Returns the new handle as JSON.
+     * @param {number} page_index
+     * @param {string} handle_json
+     * @param {Uint8Array} data
+     * @returns {string}
+     */
+    replaceImage(page_index, handle_json, data) {
+        let deferred4_0;
+        let deferred4_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(handle_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            const ptr1 = passArray8ToWasm0(data, wasm.__wbindgen_export);
+            const len1 = WASM_VECTOR_LEN;
+            wasm.pdfdocmut_replaceImage(retptr, this.__wbg_ptr, page_index, ptr0, len0, ptr1, len1);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr3 = r0;
+            var len3 = r1;
+            if (r3) {
+                ptr3 = 0; len3 = 0;
+                throw takeObject(r2);
+            }
+            deferred4_0 = ptr3;
+            deferred4_1 = len3;
+            return getStringFromWasm0(ptr3, len3);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred4_0, deferred4_1, 1);
+        }
+    }
+    /**
+     * G3 - Replace a text span on a page.
      *
      * The editor passes the **exact** text it extracted from
      * `getTextPositions()` as `original_text`, and the desired
      * replacement as `replacement_text`. The replacement is
      * re-encoded into the same font used by the matched span
      * (subset-font fallback applies when the original font cannot
-     * encode the replacement — see
+     * encode the replacement - see
      * `pdf-manip::text_replace::replace_text`).
      *
      * `page_num` is **1-based** to match the rest of the
@@ -1588,11 +1721,11 @@ export class PdfDocMut {
      *
      * Typed unsupported codes (all set `replaced=false`):
      *
-     * - `"NO_MATCH"` — `original_text` not found on the page.
-     * - `"ENCODING_UNSUPPORTED"` — replacement contains characters
+     * - `"NO_MATCH"` - `original_text` not found on the page.
+     * - `"ENCODING_UNSUPPORTED"` - replacement contains characters
      *   the matched font cannot encode and no fallback font is
      *   available.
-     * - `"REPLACE_FAILED"` — anything else (lopdf I/O,
+     * - `"REPLACE_FAILED"` - anything else (lopdf I/O,
      *   serialisation, FontMap construction, …). `reason` carries
      *   the lower-level error message.
      *
@@ -1680,7 +1813,7 @@ export class PdfDocMut {
     /**
      * Set a single AcroForm field value (text, checkbox, radio, or choice).
      *
-     * Delegates to [`pdf_forms::apply_field_value`] — the single SDK
+     * Delegates to [`pdf_forms::apply_field_value`] - the single SDK
      * writeback chain. It keeps `/V` (ASCII literal else UTF-16BE+BOM),
      * per-widget `/AS`, and regenerated `/AP` streams consistent, resolves
      * fully-qualified names through `/Kids`, and rejects read-only fields.
@@ -1724,6 +1857,45 @@ export class PdfDocMut {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Move or resize one placed image so its bounding box becomes
+     * `[x0, y0, x1, y1]` in page space. `handleJson` is an entry of
+     * `imagePlacements`. Returns the new handle as JSON. An edit inside a Form
+     * XObject copies the form for this page, so other pages keep the original.
+     * @param {number} page_index
+     * @param {string} handle_json
+     * @param {number} x0
+     * @param {number} y0
+     * @param {number} x1
+     * @param {number} y1
+     * @returns {string}
+     */
+    setImageRect(page_index, handle_json, x0, y0, x1, y1) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(handle_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.pdfdocmut_setImageRect(retptr, this.__wbg_ptr, page_index, ptr0, len0, x0, y0, x1, y1);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr2 = r0;
+            var len2 = r1;
+            if (r3) {
+                ptr2 = 0; len2 = 0;
+                throw takeObject(r2);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred3_0, deferred3_1, 1);
+        }
+    }
     /**
      * Select multiple options on a multi-select list box.
      *
@@ -2019,7 +2191,7 @@ if (Symbol.dispose) TextEditor.prototype[Symbol.dispose] = TextEditor.prototype.
  *
  * # Errors
  *
- * All fallible methods throw a `PdfluentError` — a standard `Error` subclass with
+ * All fallible methods throw a `PdfluentError` - a standard `Error` subclass with
  * these properties:
  * - `code`: stable C8 catalogue identifier in `E-<CATEGORY>-<SPECIFIC>` format
  *   (e.g. `"E-PARSE-INVALID-PDF"`). Use this for programmatic dispatch.
@@ -2416,7 +2588,7 @@ export function signPdf(bytes, pkcs12, password, options) {
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg___pdfluent_error_ctor_17e86bb485874967: function() {
+        __wbg___pdfluent_error_ctor_ed1ceb6e41324c5c: function() {
             const ret = __pdfluent_error_ctor();
             return addHeapObject(ret);
         },

package/xfa_wasm_bg.wasm.d.ts

@@ -44,6 +44,7 @@ export const pdfdoc_setFormField: (a: number, b: number, c: number, d: number, e
 export const pdfdoc_setFormFields: (a: number, b: number, c: number, d: number) => void;
 export const pdfdoc_signatures: (a: number, b: number) => void;
 export const pdfdoc_text: (a: number, b: number, c: number) => void;
+export const pdfdoc_textWithLayout: (a: number, b: number) => void;
 export const pdfdoc_toDocx: (a: number, b: number) => void;
 export const pdfdoc_toPptx: (a: number, b: number) => void;
 export const pdfdoc_toXlsx: (a: number, b: number) => void;
@@ -59,16 +60,20 @@ export const pdfdocmut_compress: (a: number, b: number) => void;
 export const pdfdocmut_deletePages: (a: number, b: number, c: number, d: number) => void;
 export const pdfdocmut_extractPages: (a: number, b: number, c: number, d: number) => void;
 export const pdfdocmut_formatTextSpan: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+export const pdfdocmut_imagePlacements: (a: number, b: number, c: number) => void;
 export const pdfdocmut_open: (a: number, b: number, c: number) => void;
 export const pdfdocmut_pageCount: (a: number) => number;
 export const pdfdocmut_redactRegion: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
 export const pdfdocmut_redactSearch: (a: number, b: number, c: number, d: number) => void;
+export const pdfdocmut_removeImage: (a: number, b: number, c: number, d: number, e: number) => void;
 export const pdfdocmut_reorderPages: (a: number, b: number, c: number, d: number) => void;
+export const pdfdocmut_replaceImage: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
 export const pdfdocmut_replaceTextSpan: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
 export const pdfdocmut_rotatePage: (a: number, b: number, c: number, d: number) => void;
 export const pdfdocmut_save: (a: number, b: number) => void;
 export const pdfdocmut_setFormField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const pdfdocmut_setFormFields: (a: number, b: number, c: number, d: number) => void;
+export const pdfdocmut_setImageRect: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
 export const pdfdocmut_setMultiSelect: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const pdfdocmut_setTextRunStyle: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
 export const signPdf: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;