@laminapdf/sdk 0.0.0-stage → 0.2.0-alpha.3

package/docs/errors/job-finished.md

@@ -0,0 +1,34 @@
+---
+title: "job-finished"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/job-finished/"
+---
+
+# job-finished
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+`step` was called on a job that had already returned its result, failed or been cancelled.
+
+## Why
+
+A job ends with its first `Step::Done`, or with its first error: an error ends the job. A step loop that keeps going after either reaches this.
+
+## How to fix
+
+Stop stepping once a step returns `Done` or an error. To run the work again, create a new job.
+
+## Example
+
+```rust
+let mut job = doc.save_job(&laminapdf::SaveOptions::new());
+while let laminapdf::Step::Progress { .. } = job.step(&mut doc, laminapdf::Budget::UNLIMITED)? {}
+assert_eq!(job.step(&mut doc, laminapdf::Budget::UNLIMITED).unwrap_err().code(), "job-finished");
+```
+
+## Data fields
+
+None.

package/docs/errors/limit-exceeded.md

@@ -0,0 +1,38 @@
+---
+title: "limit-exceeded"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/limit-exceeded/"
+---
+
+# limit-exceeded
+
+- Type: error
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+A hard `Limits` value was exceeded.
+
+## Why
+
+Hostile or unusually large input.
+
+## How to fix
+
+Raise the named limit only if you trust the input.
+
+## Example
+
+```rust
+let options = OpenOptions::new().with_limits(Limits::new().with_max_nesting_depth(1));
+let doc = Document::open_bytes(bytes, options)?;
+let err = doc.page_count().unwrap_err();
+// { "code": "limit-exceeded", "kind": "limit", "data": { "limit": "max_nesting_depth" },
+//   "location": { "object": 9, "streamOffset": 89 }, … }
+```
+
+## Data fields
+
+`limit` (the limit's name).
+
+The `location` tells where the limit was hit. The nesting and string-length limits and the read window give `offset`, a file offset; the same limits inside an object stream give `object` with `streamOffset`. A reference chain gives `object` alone, and decoding budgets give no location.

package/docs/errors/link-without-contents.md

@@ -0,0 +1,33 @@
+---
+title: "link-without-contents"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/link-without-contents/"
+---
+
+# link-without-contents
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/UA-1, a link annotation has no description: `Surface::link` or `TextRun::link` was called with `None` (or an empty string) as its contents.
+
+## Why
+
+A screen reader announces a link by its `/Contents`, its alternate description. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.18.5) requires one on every link. This is condition 28-012 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Pass a short description of where the link goes as the link's contents.
+
+## Example
+
+```rust
+surface.link(rect, LinkTarget::Uri("https://example.com/pay".into()), None);
+builder.finish()?; // link-without-contents: pass Some("Pay the invoice online".into())
+```
+
+## Data fields
+
+- `page`: the page's index (0-based).

package/docs/errors/link-without-structure.md

@@ -0,0 +1,37 @@
+---
+title: "link-without-structure"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/link-without-structure/"
+---
+
+# link-without-structure
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/UA-1, a link annotation has no `Link` structure element. The builder gives every link one automatically, except a link drawn inside an artifact, which stays outside the structure.
+
+## Why
+
+A screen reader finds links through the structure tree, so a link inside decoration can't be reached. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.18.5) requires each link annotation to be nested in a `Link` element. This is condition 28-011 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Draw the link outside `Surface::artifact`, next to the text it belongs to; the builder then wraps it in a `Link` element.
+
+## Example
+
+```rust
+surface.artifact(ArtifactKind::Layout, |s| {
+    s.link(rect, LinkTarget::Uri("https://example.com".into()), Some("Example".into()));
+    Ok(())
+})?;
+builder.finish()?; // link-without-structure
+```
+
+## Data fields
+
+- `page`: the page's index (0-based).
+- `count`: how many links on that page lack a `Link` element.

package/docs/errors/missing-alt-text.md

@@ -0,0 +1,33 @@
+---
+title: "missing-alt-text"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/missing-alt-text/"
+---
+
+# missing-alt-text
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/UA-1, a page has a `Figure` or `Formula` element without alternate text: neither `/Alt` (`Tag::with_alt`) nor `/ActualText` (`Tag::with_actual_text`).
+
+## Why
+
+A screen reader can't describe a picture or a formula by itself. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.3) requires every `Figure` and every `Formula` to carry a text alternative. These are conditions 13-004 and 17-002 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures. Lamina PDF checks only that a description exists; whether it describes the figure well is for a person to judge.
+
+## How to fix
+
+Describe the figure with `Surface::figure(&image, rect, alt)` or `Tag::new(TagKind::Figure).with_alt(…)`. If the picture is decoration that carries no meaning, draw it inside `Surface::artifact` instead.
+
+## Example
+
+```rust
+surface.tag(TagKind::Figure, |s| { s.image(&chart, rect); Ok(()) })?;
+builder.finish()?; // missing-alt-text: use Tag::new(TagKind::Figure).with_alt("Sales by month")
+```
+
+## Data fields
+
+- `page`: the page's index (0-based).

package/docs/errors/missing-glyph.md

@@ -0,0 +1,33 @@
+---
+title: "missing-glyph"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/missing-glyph/"
+---
+
+# missing-glyph
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+Text contained a character the font has no glyph for. Lamina PDF never draws `.notdef` (an empty box) silently.
+
+## Why
+
+The font's `cmap` does not map the character (for example a CJK character with a Latin font).
+
+## How to fix
+
+Use a font that covers the character (check with `Font::glyph_for`), or split the text across fonts.
+
+## Example
+
+```rust
+registry.encode(latin_font, "東京")?; // missing-glyph: the font has no CJK glyphs
+```
+
+## Data fields
+
+- `ch`: the character (**untrusted**: caller or document text).
+- `font`: the font's PostScript name (**untrusted**: read from the font).

package/docs/errors/missing-header.md

@@ -0,0 +1,37 @@
+---
+title: "missing-header"
+version: "0.2.0-alpha.3"
+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.3"
+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.3"
+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.3"
+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/name-tree-node-skipped.md

@@ -0,0 +1,34 @@
+---
+title: "name-tree-node-skipped"
+version: "0.2.0-alpha.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.