@laminapdf/sdk 0.2.0-alpha.2 → 0.2.0-alpha.4

package/docs/errors/missing-header.md

@@ -0,0 +1,37 @@
+---
+title: "missing-header"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/missing-header/"
+---
+
+# missing-header
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+No `%PDF-x.y` header was found in the first 1,024 bytes; parsing went ahead.
+
+## Why
+
+Files are often truncated at the front or prefixed with other data.
+
+## How to fix
+
+Nothing, if the document reads correctly. Open in strict mode to refuse such files, or strip whatever precedes `%PDF` before opening.
+
+## Example
+
+```text
+offset 0      From: mailer@example.org
+              …(1,200 bytes of mail headers and a MIME boundary)…
+offset 1,212  %PDF-1.7
+              1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj
+```
+
+Lamina PDF looks for `%PDF-` in the first 1,024 bytes only. Here it starts at byte 1,212, so `Document::open_bytes` warns `missing-header` and reads the objects anyway. With `OpenOptions::new().with_strict(true)` the same open fails with [`strict`](strict.md).
+
+## Data fields
+
+None.

package/docs/errors/missing-lang.md

@@ -0,0 +1,32 @@
+---
+title: "missing-lang"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/missing-lang/"
+---
+
+# missing-lang
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A PDF/UA-1 document (`Profile::PdfUa1`) reached `Builder::finish` without a natural language: `Builder::lang` was never called, or was given a blank tag.
+
+## Why
+
+A screen reader picks its voice and pronunciation from the document's language (`/Lang` in the catalog, ISO 32000-2 §14.9.2). The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.2) requires that the language of all text can be determined. These are conditions 11-001 and 11-006 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Set the document's language with a BCP 47 tag, the standard language code of the web, such as `en-GB` or `fr`. Text in another language can carry its own tag with `Tag::with_lang`.
+
+## Example
+
+```rust
+builder.lang("en-GB");
+```
+
+## Data fields
+
+None.

package/docs/errors/missing-root.md

@@ -0,0 +1,34 @@
+---
+title: "missing-root"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/missing-root/"
+---
+
+# missing-root
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+No document catalog (`/Root`) was found, even after repair.
+
+## Why
+
+The file is damaged beyond repair.
+
+## How to fix
+
+Use another copy of the file.
+
+## Example
+
+```text
+trailer << /Size 3 >>      % no /Root, and no object with /Type /Catalog in the file
+```
+
+Repair found no catalog to use, so `open` fails.
+
+## Data fields
+
+None.

package/docs/errors/missing-title.md

@@ -0,0 +1,32 @@
+---
+title: "missing-title"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/missing-title/"
+---
+
+# missing-title
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A PDF/UA-1 document (`Profile::PdfUa1`) reached `Builder::finish` without a title: `Builder::metadata` was never called, or its `Metadata` has no title, or the title is blank.
+
+## Why
+
+A screen reader announces the title first, so a document without one is hard to tell apart from others. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.1) requires a title in the document's metadata. The title is `dc:title` in the XMP packet, the XML metadata stream that the builder writes from `Metadata`. The standard also asks viewers to show the title in the title bar instead of the file name (`/DisplayDocTitle`, which the builder writes for you). This is condition 06-003 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Give the document a title that says what it is.
+
+## Example
+
+```rust
+builder.metadata(Metadata::default().with_title("Quarterly report, Q3 2026"));
+```
+
+## Data fields
+
+None.

package/docs/errors/model-failed.md

@@ -0,0 +1,33 @@
+---
+title: "model-failed"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/model-failed/"
+---
+
+# model-failed
+
+- Type: error
+- Kind: `internal` (something failed outside the caller's control)
+
+## What happened
+
+A layout model, an OCR engine or the page renderer that feeds them failed while an extraction was using it. The extraction stopped and returned no partial result.
+
+## Why
+
+Models are plug-ins: the extraction calls the model and the renderer it was given, and stops when either reports an error. The error's message is the plug-in's own, and never holds text from the document.
+
+## How to fix
+
+Check the plug-in's own logs or setup: a missing weights file, a runtime that failed to load, a page too large to render. To get a result meanwhile, extract without the model; the rules alone still give every page's blocks.
+
+## Example
+
+```rust
+let options = laminapdf::extract::ExtractOptions::new(); // no models: rules only
+let extraction = doc.extract(&options)?;
+```
+
+## Data fields
+
+None.

package/docs/errors/model-needs-host.md

@@ -0,0 +1,40 @@
+---
+title: "model-needs-host"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/model-needs-host/"
+---
+
+# model-needs-host
+
+- Type: error
+- Kind: `usage` (the call itself is wrong)
+
+## What happened
+
+An extraction in one call (`extract`) was given a model whose results only the host can give: a model named as the host's (`ModelSlot::Host`), or a plug-in model with no page renderer to draw the pages it reads.
+
+## Why
+
+A one-call extraction runs to the end without stopping, so it can only use models it can call itself, on pages its renderer draws. A host's model answers through the extraction job, which stops at each page that needs a result.
+
+## How to fix
+
+Step an extraction job and hand it each result: `request()` says which page and resolution it needs, `provide(result)` gives it back. Or give the plug-in model a page renderer, so the extraction calls it between pages.
+
+## Example
+
+```rust
+let mut job = doc.extract_job(&options)?;
+loop {
+    if let laminapdf::Step::Done(extraction) = job.step(&doc, laminapdf::Budget::UNLIMITED)? {
+        break extraction;
+    }
+    if let Some(request) = job.request().cloned() {
+        job.provide(run_my_model(&request))?;
+    }
+}
+```
+
+## Data fields
+
+None.

package/docs/errors/model-result-unexpected.md

@@ -0,0 +1,36 @@
+---
+title: "model-result-unexpected"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/model-result-unexpected/"
+---
+
+# model-result-unexpected
+
+- Type: error
+- Kind: `usage` (the call itself is wrong)
+
+## What happened
+
+A model result was handed to an extraction job (`provide`) that wasn't waiting for one, or that was waiting for the other model's result: layout regions when it asked for OCR words, or the reverse.
+
+## Why
+
+A job whose models the host runs stops at each page that needs a result and says which one (`request()`). It takes exactly that result and nothing else, so results can't land on the wrong page.
+
+## How to fix
+
+Call `provide` only while `request()` returns a request, with the result its kind asks for: layout regions for a layout request, OCR words for an OCR request.
+
+## Example
+
+```rust
+while let laminapdf::Step::Progress { .. } = job.step(&doc, laminapdf::Budget::UNLIMITED)? {
+    if let Some(request) = job.request().cloned() {
+        job.provide(run_my_model(&request))?;
+    }
+}
+```
+
+## Data fields
+
+None.

package/docs/errors/name-tree-node-skipped.md

@@ -0,0 +1,34 @@
+---
+title: "name-tree-node-skipped"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/name-tree-node-skipped/"
+---
+
+# name-tree-node-skipped
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A name- or number-tree node was malformed, reached twice or too deep, and was skipped.
+
+## Why
+
+Damaged trees: a node that is not a dictionary, a kid reached twice (a cycle), or a tree deeper than `max_tree_depth`.
+
+## How to fix
+
+Nothing to do; the entries under the skipped node are missing from the tree.
+
+## Example
+
+```text
+<< /Kids [20 0 R 21 0 R] >>   % 21 0 obj is (oops), not a dictionary
+```
+
+The walk of the `/Dests` name tree skips node 21 and keeps the entries under node 20.
+
+## Data fields
+
+None.

package/docs/errors/nested-transaction.md

@@ -0,0 +1,34 @@
+---
+title: "nested-transaction"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/nested-transaction/"
+---
+
+# nested-transaction
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+A transaction was started, or undo/redo called, while one is open.
+
+## Why
+
+Calling code opened a second transaction.
+
+## How to fix
+
+Commit or roll back first, or use a savepoint.
+
+## Example
+
+```ts
+doc.transact((tx) => {
+  doc.undo(); // nested-transaction: finish the transaction first
+});
+```
+
+## Data fields
+
+None.

package/docs/errors/no-pending-save.md

@@ -0,0 +1,32 @@
+---
+title: "no-pending-save"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/no-pending-save/"
+---
+
+# no-pending-save
+
+- Type: error
+- Kind: `state` (the call isn't valid in the current state; it may succeed after a state change)
+
+## What happened
+
+`rebase` was called, but no save is waiting for it.
+
+## Why
+
+Rebasing onto other bytes would not match the undo history, and unsaved changes would be lost.
+
+## How to fix
+
+Call `rebase` only after a save that left the document `SavedNotRebased`.
+
+## Example
+
+```rust
+doc.rebase(bytes)?; // no-pending-save: no save is waiting
+```
+
+## Data fields
+
+None.

package/docs/errors/no-transaction.md

@@ -0,0 +1,33 @@
+---
+title: "no-transaction"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/no-transaction/"
+---
+
+# no-transaction
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+`apply`, `commit` or `rollback` was called without an open transaction.
+
+## Why
+
+Calling code skipped `begin`.
+
+## How to fix
+
+Call `begin` first, or use `transact`.
+
+## Example
+
+```rust
+// laminapdf_ops::Document, without begin():
+ops.commit()?; // no-transaction
+```
+
+## Data fields
+
+None.

package/docs/errors/not-initialized.md

@@ -0,0 +1,35 @@
+---
+title: "not-initialized"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/not-initialized/"
+---
+
+# not-initialized
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+A function or class of `@laminapdf/sdk` (`Document.open`, `new Builder`, …) was called before `init()` had finished loading and instantiating the WebAssembly module.
+
+## Why
+
+`@laminapdf/sdk` is synchronous after `init()`, but fetching and compiling the `.wasm` file is asynchronous, so it happens once, up front, in `init()`. Until that promise resolves there is no module to call.
+
+## How to fix
+
+Await `init()` once, before the first call; calling it again is cheap (it is idempotent). In a Cloudflare Worker, pass the imported module: `await init({ module: wasm })`.
+
+## Example
+
+```js
+import { Document, init } from "@laminapdf/sdk";
+Document.open(bytes); // throws { code: "not-initialized", … }
+await init();
+Document.open(bytes); // works
+```
+
+## Data fields
+
+None.

package/docs/errors/not-pdf.md

@@ -0,0 +1,33 @@
+---
+title: "not-pdf"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/not-pdf/"
+---
+
+# not-pdf
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+The input does not look like a PDF at all.
+
+## Why
+
+The bytes are empty, or no `n g obj` header appears anywhere in them: an HTML error page saved as `.pdf`, a different format, or the wrong buffer.
+
+## How to fix
+
+Check that you passed the right bytes.
+
+## Example
+
+```rust
+let err = laminapdf::Document::open_bytes(b"<html>…</html>".to_vec(), Default::default()).unwrap_err();
+assert_eq!(err.code(), "not-pdf");
+```
+
+## Data fields
+
+None.

package/docs/errors/not-rebased.md

@@ -0,0 +1,35 @@
+---
+title: "not-rebased"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/not-rebased/"
+---
+
+# not-rebased
+
+- Type: error
+- Kind: `state` (the call isn't valid in the current state; it may succeed after a state change)
+
+## What happened
+
+The save wrote its complete output, but rebasing the document onto it failed. The document is `SavedNotRebased`.
+
+## Why
+
+Reading the output back failed (for example a limit, or a source that can't deliver the bytes yet).
+
+## How to fix
+
+Retry `rebase` with the output the error carries (`saved.source()`; in the `laminapdf` façade, `Error::saved_output()` and `Document::rebase`).
+
+## Example
+
+```rust
+match doc.save_with(&options, &cancel) {
+    Err(e) if e.code() == "not-rebased" => doc.rebase(e.saved_output().unwrap())?,
+    other => { other?; }
+}
+```
+
+## Data fields
+
+- `error`: the rebase's own error (its code, kind and location).

package/docs/errors/object-number-out-of-range.md

@@ -0,0 +1,38 @@
+---
+title: "object-number-out-of-range"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/object-number-out-of-range/"
+---
+
+# object-number-out-of-range
+
+- Type: warning
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+An xref entry above `Limits::max_object_number` was dropped.
+
+## Why
+
+Corrupt or hostile xref data.
+
+## How to fix
+
+Raise `max_object_number` only for trusted input.
+
+## Example
+
+```text
+xref
+0 1
+0000000000 65535 f
+9999999 1
+0000000015 00000 n
+```
+
+Object 9,999,999 is above `Limits::max_object_number`; its entry is dropped so a hostile xref can't make Lamina PDF allocate for it. References to it resolve to `null`.
+
+## Data fields
+
+None.

package/docs/errors/objstm-index-mismatch.md

@@ -0,0 +1,36 @@
+---
+title: "objstm-index-mismatch"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/objstm-index-mismatch/"
+---
+
+# objstm-index-mismatch
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An object stream's index was stale; the object was found by searching.
+
+## Why
+
+Object streams rewritten by a tool that did not update the index at their start.
+
+## How to fix
+
+Nothing.
+
+## Example
+
+```text
+12 0 obj << /Type /ObjStm /N 3 /First 18 >> stream
+20 0 21 14 22 31
+…
+```
+
+The index says object 21 starts at offset 14 of the stream, but it starts elsewhere. Lamina PDF searches the stream for it, uses what it finds and raises the warning.
+
+## Data fields
+
+None.

package/docs/errors/out-of-memory.md

@@ -0,0 +1,38 @@
+---
+title: "out-of-memory"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/out-of-memory/"
+---
+
+# out-of-memory
+
+- Type: error
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+The WebAssembly module needed more memory than it could get, so it stopped in the middle of the call. Each module may grow to at most 2 GiB, and a browser tab or server can run out before that. `@laminapdf/sdk` discarded the module's instance, so the next call runs in a fresh one. Every document, page and builder from the old instance now throws `instance-reset`.
+
+## Why
+
+A module's memory grows as the module needs more and never shrinks. Many open documents, a huge image, or a file built to exhaust memory can each push it to its limit. The open limits stop most hostile files before memory runs out, and the maximum catches the rest.
+
+## How to fix
+
+Open the document again, then keep less in memory at once. Free each document and builder as soon as you're done with it, or use `using`. For files from people you don't trust, lower the open limits, such as `maxStreamDecoded` and `maxImagePixels`, so they fail with `limit-exceeded` first. An app can also open each document in its own Web Worker, with `@laminapdf/sdk/worker`, and end the Web Worker afterwards: that returns all of its memory.
+
+## Example
+
+```ts
+try {
+  doc = Document.open(bytes, { limits: { maxStreamDecoded: 64_000_000 } });
+} catch (e) {
+  if (isLaminaPdfError(e, "out-of-memory")) showError("This file is too large to open here.");
+  else throw e;
+}
+```
+
+## Data fields
+
+- `module`: the module that ran out: `base`, `text` or `extract`.
+- `memoryBytes`: the size of its memory when it stopped.

package/docs/errors/outline-cycle.md

@@ -0,0 +1,34 @@
+---
+title: "outline-cycle"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/outline-cycle/"
+---
+
+# outline-cycle
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An outline item was reached twice; that branch stopped.
+
+## Why
+
+Damaged or hostile outlines.
+
+## How to fix
+
+Nothing; the outline is shown without the loop.
+
+## Example
+
+```text
+11 0 obj << /Title (Chapter 1) /Parent 10 0 R /Next 11 0 R >>
+```
+
+Item 11 is its own `/Next`; the outline walk stops that branch the second time it reaches it.
+
+## Data fields
+
+None.

package/docs/errors/outline-item-skipped.md

@@ -0,0 +1,34 @@
+---
+title: "outline-item-skipped"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/outline-item-skipped/"
+---
+
+# outline-item-skipped
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An outline item was missing, not a dictionary or too deep; it and its subtree were skipped.
+
+## Why
+
+Damaged outlines.
+
+## How to fix
+
+Nothing to do; the skipped item and its children are missing from the outline.
+
+## Example
+
+```text
+10 0 obj << /Type /Outlines /First 11 0 R >>   % object 11 is missing
+```
+
+The first item can't be read, so it and everything under it are left out of `outline()`.
+
+## Data fields
+
+None.