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

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

@@ -0,0 +1,38 @@
+---
+title: "out-of-memory"
+version: "0.2.0-alpha.3"
+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.3"
+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.3"
+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.

package/docs/errors/output-unwritable.md

@@ -0,0 +1,37 @@
+---
+title: "output-unwritable"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/output-unwritable/"
+---
+
+# output-unwritable
+
+- Type: error
+- Kind: `io` (the host failed to supply or take bytes)
+
+## What happened
+
+The output couldn't be written: its folder is missing or read-only, the disk is full, or standard output was closed before the command finished.
+
+## Why
+
+The system refused the write, or standard output closed while the command was writing to it. The CLI writes to a temporary file beside the output and renames it into place, so a failed write leaves any old file as it was.
+
+## How to fix
+
+Check that the output's folder exists, that you can write to it and that the disk has room. When piping, make sure the reading command doesn't exit early.
+
+## Example
+
+```console
+$ laminapdf pages rotate scan.pdf +90 -o /no/such/folder/out.pdf
+error[output-unwritable]: couldn't write the output
+  = hint: check that the output's folder exists, …
+$ echo $?
+1
+```
+
+## Data fields
+
+- `output`: the file that couldn't be written, or `-` for standard output (untrusted: caller text, never in the message).
+- `reason`: the system's error kind, such as `NotFound` or `StorageFull`.

package/docs/errors/overwrite-refused.md

@@ -0,0 +1,36 @@
+---
+title: "overwrite-refused"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/overwrite-refused/"
+---
+
+# overwrite-refused
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+The output file already exists, or the command was asked to change its input in place with `--in-place`, and `--force` wasn't given.
+
+## Why
+
+The CLI never replaces a file without being told to, so a mistyped `-o` can't destroy a document. It never prompts either, because scripts and agents can't answer a prompt. Exit code 4 tells a script the command needs `--force`.
+
+## How to fix
+
+Pass `--force` to replace the file, or write to a new file with `-o`. The CLI writes to a temporary file and renames it, so a replaced file is never left half written.
+
+## Example
+
+```console
+$ laminapdf pages rotate scan.pdf 90:z --in-place
+error[overwrite-refused]: refusing to replace a file without --force
+  = hint: pass --force, or write to a new file with -o
+$ echo $?
+4
+```
+
+## Data fields
+
+- `output`: the file that would have been replaced (untrusted: caller text, never in the message).

package/docs/errors/page-count-mismatch.md

@@ -0,0 +1,34 @@
+---
+title: "page-count-mismatch"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/page-count-mismatch/"
+---
+
+# page-count-mismatch
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+The page tree's `/Count` differs from the number of pages walked; the walk wins.
+
+## Why
+
+Writers that don't update `/Count`.
+
+## How to fix
+
+Nothing; Lamina PDF uses the walked count.
+
+## Example
+
+```text
+2 0 obj << /Type /Pages /Kids [3 0 R 4 0 R] /Count 7 >>
+```
+
+The root says 7 pages but two are reachable: `page_count()` is 2, and the warning's `data` is `{ "declared": 7, "walked": 2 }`.
+
+## Data fields
+
+`declared`, `walked`.

package/docs/errors/page-index-out-of-range.md

@@ -0,0 +1,34 @@
+---
+title: "page-index-out-of-range"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/page-index-out-of-range/"
+---
+
+# page-index-out-of-range
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A link (`LinkTarget::Page`), an outline item or a named destination (`Builder::destination`) names a page index the document doesn't have when the build finishes.
+
+## Why
+
+Page targets are resolved when `Builder::finish` (or `Appender::finish`) runs, so a link can name a page added after its own; by then every index must be one of the document's pages. Indexes are 0-based.
+
+## How to fix
+
+Use an index below the document's page count, or add the page before finishing.
+
+## Example
+
+```rust
+surface.link(rect, LinkTarget::Page { index: 5, fit: Fit::Page }, None);
+builder.finish()?; // page-index-out-of-range: the document has 2 pages
+```
+
+## Data fields
+
+- `index`: the 0-based index given.
+- `count`: the number of pages.

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

@@ -0,0 +1,35 @@
+---
+title: "page-tree-node-skipped"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/page-tree-node-skipped/"
+---
+
+# page-tree-node-skipped
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A page-tree node was missing, unparsable, of the wrong type or too deep, and was skipped.
+
+## Why
+
+Damaged page trees: a kid that is missing, unparsable or of the wrong type, a `/Kids` that is not an array, or a tree deeper than `max_page_tree_depth`.
+
+## How to fix
+
+Check the page count; pages under the skipped node are missing.
+
+## Example
+
+```text
+2 0 obj << /Type /Pages /Kids [3 0 R 9 0 R] /Count 2 >>
+9 0 obj (not a page) endobj
+```
+
+Kid 9 is a string, not a page or a pages node: it is skipped with this warning, so the document has one page. The `location` is the skipped node's `object` when it has one.
+
+## Data fields
+
+None.

package/docs/errors/password-required.md

@@ -0,0 +1,36 @@
+---
+title: "password-required"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/password-required/"
+---
+
+# password-required
+
+- Type: error
+- Kind: `security` (encryption, permissions or signatures block the call, or look tampered with)
+
+## What happened
+
+The document is encrypted with a non-empty user password and none was given.
+
+## Why
+
+Encrypted input.
+
+## How to fix
+
+Ask the user for the password and pass it in `OpenOptions` (`{ password }` in TS).
+
+## Example
+
+```ts
+try {
+  Document.open(bytes);
+} catch (e) {
+  if (isLaminaPdfError(e, "password-required")) Document.open(bytes, { password: await ask() });
+}
+```
+
+## Data fields
+
+None.

package/docs/errors/path-outside-roots.md

@@ -0,0 +1,32 @@
+---
+title: "path-outside-roots"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/path-outside-roots/"
+---
+
+# path-outside-roots
+
+- Type: error
+- Kind: `security` (encryption, permissions or signatures block the call)
+
+## What happened
+
+A tool of `laminapdf mcp` was given a path the server may not use: one outside every `--root` folder it was started with, one that climbs out with `..`, or a symbolic link inside a root that leads out of it. A missing file outside the roots, and a link that leads nowhere, get this answer too, so a call can't tell whether a file outside the roots exists.
+
+## Why
+
+An MCP server acts for a model that may have read instructions planted in a document or a web page. So the server touches only the folders named on its command line by the person who started it. It resolves every path, links included, before it checks the path, so a link can't lead it elsewhere.
+
+## How to fix
+
+Use a path inside one of the server's `--root` folders; a relative path is read from the first root. To work on files elsewhere, start the server with another `--root`.
+
+## Example
+
+```json
+{"schema":"laminapdf.error/1","error":{"code":"path-outside-roots","kind":"security","message":"the path is outside the server's --root folders","data":{"path":"../secret.pdf"},"exitCode":1,…}}
+```
+
+## Data fields
+
+- `path`: the path the tool was given (untrusted: caller text, never in the message).

package/docs/errors/perms-mismatch.md

@@ -0,0 +1,34 @@
+---
+title: "perms-mismatch"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/perms-mismatch/"
+---
+
+# perms-mismatch
+
+- Type: warning
+- Kind: `security` (encryption, permissions or signatures block the call, or look tampered with)
+
+## What happened
+
+An R5/R6 document's `/Perms` does not match its `/P` and `/EncryptMetadata`.
+
+## Why
+
+`/P` may have been tampered with (ISO 32000-2 Algorithm 13).
+
+## How to fix
+
+Treat the permissions as untrusted.
+
+## Example
+
+```text
+/Encrypt << /V 5 /R 6 /P -3904 /Perms <…> … >>   % /Perms decrypts to a different /P
+```
+
+The document opens, but `Document::permissions()` comes from a `/P` that the encrypted `/Perms` contradicts.
+
+## Data fields
+
+None.

package/docs/errors/profile-version-conflict.md

@@ -0,0 +1,35 @@
+---
+title: "profile-version-conflict"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/profile-version-conflict/"
+---
+
+# profile-version-conflict
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`BuildOptions::with_version(PdfVersion::V2_0)` was combined with a conformance profile (`BuildOptions::with_profile`) that is built on PDF 1.7. `Builder::finish` wrote nothing.
+
+## Why
+
+The PDF/UA-1 standard for accessible PDF (ISO 14289-1) and the PDF/A-2 and PDF/A-3 archival standards (ISO 19005-2 and -3) build their rules on ISO 32000-1, which is PDF 1.7. A file that says it is PDF 2.0 can't conform to them. Validators such as veraPDF, the open-source PDF/A and PDF/UA validator, check the header first.
+
+## How to fix
+
+Leave the version at its default, 1.7 (or choose a lower one: the builder raises it to what the content needs). PDF 2.0 has its own profiles, PDF/A-4 and PDF/UA-2, which Lamina PDF doesn't write yet.
+
+## Example
+
+```rust
+let options = BuildOptions::default()
+    .with_version(PdfVersion::V2_0)
+    .with_profile(Profile::PdfA2b);
+Builder::new(options).finish()?; // profile-version-conflict
+```
+
+## Data fields
+
+- `profile`: the profile, such as `PDF/A-2b`.

package/docs/errors/reference-cycle.md

@@ -0,0 +1,35 @@
+---
+title: "reference-cycle"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/reference-cycle/"
+---
+
+# reference-cycle
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A reference chain or the page tree loops back on itself.
+
+## Why
+
+Damaged or hostile files.
+
+## How to fix
+
+Use another copy of the file.
+
+## Example
+
+```text
+5 0 obj 6 0 R endobj
+6 0 obj 5 0 R endobj
+```
+
+Resolving object 5 leads back to itself; the call fails instead of looping. A page tree whose `/Kids` lead back to an ancestor fails the same way.
+
+## Data fields
+
+None.

package/docs/errors/render-backend-unavailable.md

@@ -0,0 +1,32 @@
+---
+title: "render-backend-unavailable"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/render-backend-unavailable/"
+---
+
+# render-backend-unavailable
+
+- Type: error
+- Kind: `io` (reading or writing outside Lamina PDF failed)
+
+## What happened
+
+The PDFium backend (`laminapdf-render-pdfium`) could not load the PDFium library, so nothing can be rendered with it.
+
+## Why
+
+PDFium is bound at runtime, never linked at build time: the library has to be present on the machine. Lamina PDF looks for it only in the folder you name.
+
+## How to fix
+
+Ship the PDFium library (`libpdfium.dylib`, `libpdfium.so` or `pdfium.dll`) with your app and pass its folder to `PdfiumBackend::bind(dir)`, or set `LAMINA_PDF_PDFIUM_DIR` to that folder for `PdfiumBackend::from_env()`.
+
+## Example
+
+```rust
+let backend = PdfiumBackend::from_env()?; // render-backend-unavailable when the library isn't there
+```
+
+## Data fields
+
+- `backend`: `pdfium`.

package/docs/errors/render-failed.md

@@ -0,0 +1,33 @@
+---
+title: "render-failed"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/render-failed/"
+---
+
+# render-failed
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+The render engine (PDFium or hayro, `laminapdf-render`) could not open the document, or could not draw the page it was asked for.
+
+## Why
+
+The engines have their own parsers. A file that Lamina PDF repairs may still be too damaged for an engine, or use a feature it can't draw. An engine failure (for example a panic inside hayro) is reported this way too, never as a crash.
+
+## How to fix
+
+Check the document's warnings: a damaged file is usually reported there too. Try the other backend from the debug menu. If neither can draw the page, report the file with the backend name and version.
+
+## Example
+
+```rust
+let doc = HayroBackend::new().open(Arc::new(bytes), &RenderOpenOptions::new())?; // render-failed for a file hayro can't parse
+```
+
+## Data fields
+
+- `backend`: `pdfium` or `hayro`.
+- `stage`: `open` or `render`.

package/docs/errors/render-too-large.md

@@ -0,0 +1,36 @@
+---
+title: "render-too-large"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/render-too-large/"
+---
+
+# render-too-large
+
+- Type: error
+- Kind: `limit` (a configured limit was exceeded)
+
+## What happened
+
+A render backend (`laminapdf-render`) refused a request that is too large. The tile has more than `max_render_pixels` pixels or more than `max_render_side` pixels on a side (the document's `RenderLimits`), or more than 65,535 pixels on a side for hayro. Or, for hayro, which reads the whole file, the input is longer than `max_input_bytes`.
+
+## Why
+
+Page sizes and zoom levels come from files and users, so a render could otherwise ask for a bitmap of any size. The limits are checked before anything is allocated. The defaults are 16,777,216 pixels per tile (4096 × 4096, iOS Safari's per-canvas cap), 16,384 pixels per side and 1 GiB of input.
+
+## How to fix
+
+At high zoom, render the visible part of the page as tiles of 256 to 512 pixels (`RenderRequest::with_clip`) instead of the whole page. Raise the limits with `RenderOpenOptions::with_limits` only when the larger bitmap is intended.
+
+## Example
+
+```rust
+let req = RenderRequest::page(0, 1000.0); // a letter page at 1000×: 612,000 × 792,000 pixels
+doc.render(&req, &mut out, &CancelToken::new())?; // render-too-large
+```
+
+## Data fields
+
+- `width`, `height`: the tile's size (tile limits).
+- `limit`: the limit exceeded.
+- `unit`: `pixels`, `pixels per side` or `pixels per side (hayro)` (tile limits).
+- `len`: the input's length in bytes (the input limit, with `limit`).

package/docs/errors/repaired-base.md

@@ -0,0 +1,34 @@
+---
+title: "repaired-base"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/repaired-base/"
+---
+
+# repaired-base
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+An incremental update was requested for a document whose xref needed repair.
+
+## Why
+
+Appending to a repaired file would build on offsets that are wrong.
+
+## How to fix
+
+Save with a full rewrite instead.
+
+## Example
+
+```rust
+let doc = Document::open_bytes(bytes_needing_repair, OpenOptions::new())?; // warns xref-repaired
+let err = doc.save(&SaveOptions::default().with_mode(SaveMode::Incremental));
+// repaired-base; SaveMode::Auto (the default) writes a full rewrite instead
+```
+
+## Data fields
+
+None.

package/docs/errors/requires-rewrite.md

@@ -0,0 +1,38 @@
+---
+title: "requires-rewrite"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/requires-rewrite/"
+---
+
+# requires-rewrite
+
+- Type: error (`laminapdf_save::SaveError::RequiresRewrite`)
+- Kind: `state` (the call isn't valid in the document's current state)
+
+## What happened
+
+An incremental save was requested, but only a full rewrite is safe for this document. Nothing was written.
+
+## Why
+
+The save planner found one of four reasons the file must be rewritten:
+
+- a repaired base, whose cross-reference data an appended revision can't build on;
+- an encrypted base being saved without its encryption;
+- a document built from scratch, with no base bytes at all;
+- a pending op, such as a redaction, that removes content an earlier revision would keep.
+
+## How to fix
+
+Save with `SaveMode::Auto` (it resolves to a full rewrite) or `SaveMode::FullRewrite`. If the document is also signed, that needs the explicit override ([`would-invalidate-signatures`](would-invalidate-signatures.md)).
+
+## Example
+
+```rust
+let err = doc.save(&mut out, &SaveOptions::new().with_mode(SaveMode::Incremental)).unwrap_err();
+assert_eq!(err.code(), "requires-rewrite");
+```
+
+## Data fields
+
+- `reasons`: the rewrite reasons (`RepairedBase`, `EncryptedBase`, `NoBase`, `OpRequiresRewrite`).

package/docs/errors/saved-not-rebased.md

@@ -0,0 +1,34 @@
+---
+title: "saved-not-rebased"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/saved-not-rebased/"
+---
+
+# saved-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 document was saved to a sink Lamina PDF can't read back, and it waits for `rebase`: ops, undo, redo and saves are refused until then.
+
+## Why
+
+`save_full` to a write-only sink leaves the document `SavedNotRebased`: the bytes it would continue from are not available to it.
+
+## How to fix
+
+Call `rebase` with the saved bytes, then retry.
+
+## Example
+
+```rust
+ops.save(&mut write_only_sink, &options)?;  // full rewrite; the document waits for rebase
+ops.apply(op);                               // saved-not-rebased
+ops.rebase(saved_bytes)?;                    // then edits work again
+```
+
+## Data fields
+
+None.