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

package/docs/errors/output-unwritable.md

@@ -0,0 +1,37 @@
+---
+title: "output-unwritable"
+version: "0.2.0-alpha.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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/redaction-not-applied.md

@@ -0,0 +1,32 @@
+---
+title: "redaction-not-applied"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/redaction-not-applied/"
+---
+
+# redaction-not-applied
+
+- Type: warning
+- Kind: `security` (encryption, permissions or signatures block the call, or look tampered with)
+
+## What happened
+
+A page has redaction marks (`Redact` annotations, ISO 32000-2 §12.5.6.23) that were never applied. A mark only records what someone meant to remove; until a tool applies it, the text, images and drawings under it are all still in the file.
+
+## Why
+
+Editors such as Acrobat redact in two steps: you mark what to remove, then you apply the marks. A file saved between the two steps looks redacted in some viewers, which draw the mark's overlay, but nothing has been taken out.
+
+## How to fix
+
+Apply the redactions in a tool that removes what they cover, then save the file as a full rewrite.
+
+## Example
+
+A page with two redaction marks over a name and an account number, saved before "Apply redactions" was chosen. `laminapdf check` reports `redaction-not-applied` for that page with `annotations` 2.
+
+## Data fields
+
+- `annotations`: how many redaction marks the page has.
+
+The `location` has the page's `pageIndex`.

package/docs/errors/reference-cycle.md

@@ -0,0 +1,35 @@
+---
+title: "reference-cycle"
+version: "0.2.0-alpha.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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/revision-index-out-of-range.md

@@ -0,0 +1,34 @@
+---
+title: "revision-index-out-of-range"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/revision-index-out-of-range/"
+---
+
+# revision-index-out-of-range
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Document::open_revision` was asked for a revision the file doesn't have.
+
+## Why
+
+Revisions are numbered from 0, the original file, to one less than `Document::revision_count`, the latest revision. A file that was never updated, or one opened by repairing a broken cross-reference table, has one revision.
+
+## How to fix
+
+Ask for an index below `revision_count()`.
+
+## Example
+
+```rust
+let count = doc.revision_count()?; // 2
+doc.open_revision(count, OpenOptions::default())?; // revision-index-out-of-range
+```
+
+## Data fields
+
+- `index`: the index asked for.
+- `count`: how many revisions the file has.

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

@@ -0,0 +1,34 @@
+---
+title: "saved-not-rebased"
+version: "0.2.0-alpha.4"
+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.

package/docs/errors/sink-not-empty.md

@@ -0,0 +1,33 @@
+---
+title: "sink-not-empty"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/sink-not-empty/"
+---
+
+# sink-not-empty
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+The `WriteSink` already held bytes when the save started, so the writer refused before writing anything.
+
+## Why
+
+Output offsets (the xref table, `startxref`) count from the sink's first byte, and a sink only appends. An `AppendedOnly` incremental save also accepts a sink that holds exactly the base.
+
+## How to fix
+
+Pass an empty sink. The document is unchanged.
+
+## Example
+
+```rust
+let mut sink = b"%PDF-".to_vec();
+ops.save(&mut sink, &options)?; // sink-not-empty, data.held = 5
+```
+
+## Data fields
+
+- `held`: the bytes the sink held.