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

package/docs/errors/content-path-unpainted.md

@@ -0,0 +1,36 @@
+---
+title: "content-path-unpainted"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/content-path-unpainted/"
+---
+
+# content-path-unpainted
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A content stream ended with a path that no painting operator ended; it was dropped.
+
+## Why
+
+A producer bug, or truncated content.
+
+## How to fix
+
+Nothing to do.
+
+## Example
+
+```text
+0 0 m 100 100 l
+```
+
+The content stream ends after building a path without `S`, `f` or `n`: the path is dropped, as the spec intends.
+
+## Data fields
+
+- `offset`: the byte offset of the path's first segment in the decoded content.
+
+The `location` is `object` (the page for page content, the Form XObject for a form) with `streamOffset` in its decoded content; none for content interpreted on its own or a direct page.

package/docs/errors/content-resource-missing.md

@@ -0,0 +1,37 @@
+---
+title: "content-resource-missing"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/content-resource-missing/"
+---
+
+# content-resource-missing
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An operator named a resource (font, XObject, graphics state, colour space, shading, property list) that is missing, of the wrong type or unreadable, or a Form XObject's content could not be decoded; the operator was skipped or ran without it.
+
+## Why
+
+Resources lost in editing or merging, or damaged objects.
+
+## How to fix
+
+Check the page's `/Resources`.
+
+## Example
+
+```text
+/Im7 Do      % /Resources << /XObject << /Im1 8 0 R >> >>
+```
+
+`/Im7` is not in the page's resources, so the `Do` draws nothing. `data.category` is `XObject`; the resource's name, which comes from the file, is never put in the message.
+
+## Data fields
+
+- `offset`: the operator's byte offset in the decoded content.
+- `category`: the resource category, e.g. `Font` (Lamina PDF's own vocabulary).
+
+The `location` is `object` (the page for page content, the Form XObject for a form) with `streamOffset` in its decoded content; none for content interpreted on its own or a direct page.

package/docs/errors/content-syntax.md

@@ -0,0 +1,36 @@
+---
+title: "content-syntax"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/content-syntax/"
+---
+
+# content-syntax
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A content stream held bytes that are not a token (an unbalanced `)` or `>`, a bad hex digit, an unterminated string or array) or a stray `ID`/`EI`; they were skipped with the operands read so far.
+
+## Why
+
+Damaged or truncated content.
+
+## How to fix
+
+Check the page's content around the reported offset.
+
+## Example
+
+```text
+BT (unbalanced Tj ET
+```
+
+The string never closes, so the bytes to the end of the token are skipped with the pending operands.
+
+## Data fields
+
+- `offset`: the problem's byte offset in the decoded content.
+
+The `location` is `object` (the page for page content, the Form XObject for a form) with `streamOffset` in its decoded content; none for content interpreted on its own or a direct page.

package/docs/errors/content-unbalanced-bt.md

@@ -0,0 +1,36 @@
+---
+title: "content-unbalanced-bt"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/content-unbalanced-bt/"
+---
+
+# content-unbalanced-bt
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A `BT` inside a text object, an `ET` outside one, a text operator outside one, or a content stream that ended inside one.
+
+## Why
+
+A producer bug, or damaged content.
+
+## How to fix
+
+Nothing to do; text operators were handled tolerantly.
+
+## Example
+
+```text
+BT /F1 12 Tf (one) Tj BT (two) Tj ET
+```
+
+The second `BT` opens a text object inside one; Lamina PDF treats it as a new text object and carries on.
+
+## Data fields
+
+- `offset`: the operator's byte offset, or the end of the content.
+
+The `location` is `object` (the page for page content, the Form XObject for a form) with `streamOffset` in its decoded content; none for content interpreted on its own or a direct page.

package/docs/errors/content-unbalanced-marked.md

@@ -0,0 +1,36 @@
+---
+title: "content-unbalanced-marked"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/content-unbalanced-marked/"
+---
+
+# content-unbalanced-marked
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An `EMC` had no matching `BMC`/`BDC` (it was ignored), or a content stream ended with marked-content sequences open (they were closed).
+
+## Why
+
+A producer bug, or tagging split across streams.
+
+## How to fix
+
+Check tagged-content results; the sequences were closed for you.
+
+## Example
+
+```text
+/P << /MCID 0 >> BDC (text) Tj
+```
+
+The stream ends with the marked-content sequence open; it is closed at the end, so MCID 0 covers the text that follows it.
+
+## Data fields
+
+- `offset`: the `EMC`'s byte offset, or the end of the content.
+
+The `location` is `object` (the page for page content, the Form XObject for a form) with `streamOffset` in its decoded content; none for content interpreted on its own or a direct page.

package/docs/errors/content-unbalanced-q.md

@@ -0,0 +1,36 @@
+---
+title: "content-unbalanced-q"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/content-unbalanced-q/"
+---
+
+# content-unbalanced-q
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A `Q` had no matching `q` (it was ignored), or a content stream ended with saved graphics states still open (they were restored).
+
+## Why
+
+Producers that split `q`/`Q` pairs across streams, or damaged content.
+
+## How to fix
+
+Nothing to do; each stream balances on its own.
+
+## Example
+
+```text
+q 1 0 0 1 72 72 cm 0 0 10 10 re f Q Q
+```
+
+The second `Q` has no matching `q` and is ignored.
+
+## Data fields
+
+- `offset`: the `Q`'s byte offset, or the end of the content.
+
+The `location` is `object` (the page for page content, the Form XObject for a form) with `streamOffset` in its decoded content; none for content interpreted on its own or a direct page.

package/docs/errors/content-unknown-operator.md

@@ -0,0 +1,37 @@
+---
+title: "content-unknown-operator"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/content-unknown-operator/"
+---
+
+# content-unknown-operator
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A content stream used an operator ISO 32000-2 Annex A does not define, outside a `BX`/`EX` compatibility section; it was skipped.
+
+## Why
+
+A producer wrote a private or misspelled operator.
+
+## How to fix
+
+Nothing to do; check the page's rendering if the operator mattered.
+
+## Example
+
+```text
+BT /F1 12 Tf 72 720 Td (Hi) Tj ET
+0 0 1 setcolor
+```
+
+`setcolor` is not an Annex A operator and is not inside `BX`/`EX`, so it is skipped with its operands. `data.offset` is its byte offset in the decoded content.
+
+## Data fields
+
+- `offset`: the operator's byte offset in the decoded content.
+
+The `location` is `object` (the page for page content, the Form XObject for a form) with `streamOffset` in its decoded content; none for content interpreted on its own or a direct page.

package/docs/errors/covered-text.md

@@ -0,0 +1,33 @@
+---
+title: "covered-text"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/covered-text/"
+---
+
+# covered-text
+
+- Type: warning
+- Kind: `security` (encryption, permissions or signatures block the call, or look tampered with)
+
+## What happened
+
+A page draws text and then paints something opaque over it: a filled box, an image or an annotation. A reader sees the box, but the text under it is still in the file, so copying, search and every text extractor still get it.
+
+## Why
+
+Drawing a black box over a name is the most common failed redaction. A PDF keeps every glyph its content draws, whatever is painted over it later, so the box hides the words on screen and in print without removing them. Extraction already leaves such text out of its blocks and lists it under `dropped` as `covered`; this warning says how much of it each page has.
+
+## How to fix
+
+Remove the text itself with a tool that deletes what a redaction covers, then save the file as a full rewrite, so no earlier revision keeps it either. If the box is part of the design and the text under it is meant to be there, you can ignore the warning.
+
+## Example
+
+A page draws "Pay John Smith now." and then a black rectangle over "John Smith". `laminapdf check` reports `covered-text` for page 0 with `chars` 9, and `laminapdf extract` gives `Pay now.`.
+
+## Data fields
+
+- `chars`: how many characters, spaces left out, the page has under covers.
+- `regions`: how many separate covered passages the page has: one per box over a run of words.
+
+The `location` has the page's `pageIndex`. The warning never holds the covered text.

package/docs/errors/data-pending.md

@@ -0,0 +1,34 @@
+---
+title: "data-pending"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/data-pending/"
+---
+
+# data-pending
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+The `ByteSource` hasn't fetched the listed byte ranges yet.
+
+## Why
+
+Range loading: the call needs more of the file.
+
+## How to fix
+
+Fetch the ranges and retry the call; the document stays usable.
+
+## Example
+
+```ts
+const doc = await Document.openRange(httpRangeSource(url));
+// pages() needs bytes that haven't arrived: ensure() fetches e.ranges and retries
+const pages = await doc.ensure(() => doc.pages);
+```
+
+## Data fields
+
+`ranges` (offset, length pairs).

package/docs/errors/decompress.md

@@ -0,0 +1,34 @@
+---
+title: "decompress"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/decompress/"
+---
+
+# decompress
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+Compressed data was corrupt and produced no output.
+
+## Why
+
+Damaged streams.
+
+## How to fix
+
+Use another copy of the file.
+
+## Example
+
+```text
+5 0 obj << /Filter /FlateDecode /Length 40 >> stream (40 bytes that are not zlib data) endstream
+```
+
+Inflating fails before producing any output, so the stream has no data.
+
+## Data fields
+
+None.

package/docs/errors/device-color-without-output-intent.md

@@ -0,0 +1,33 @@
+---
+title: "device-color-without-output-intent"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/device-color-without-output-intent/"
+---
+
+# device-color-without-output-intent
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under a PDF/A profile, a page draws with `DeviceCMYK` (CMYK given as plain numbers, with no profile to say which inks they mean): a `Color::cmyk` colour or a CMYK JPEG.
+
+## Why
+
+The PDF/A standard for archival PDF (ISO 19005) gives device colour a defined meaning through the document's output intent, which Lamina PDF writes as sRGB. That sRGB intent defines device RGB and gray, but not device CMYK, so ISO 19005-2 §6.2.4.3 forbids CMYK under it.
+
+## How to fix
+
+Use `Color::rgb` or `Color::gray`, convert CMYK images to RGB, or give CMYK colours an ICC profile with `Color::icc` (an ICC-based colour carries its own meaning).
+
+## Example
+
+```rust
+surface.fill_color(Color::cmyk(0.0, 0.5, 1.0, 0.0));
+builder.finish()?; // device-color-without-output-intent under Profile::PdfA2b
+```
+
+## Data fields
+
+- `page`: the index (0-based) of the first page that uses `DeviceCMYK`.

package/docs/errors/direct-page.md

@@ -0,0 +1,34 @@
+---
+title: "direct-page"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/direct-page/"
+---
+
+# direct-page
+
+- Type: error
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+The page is a direct dictionary, which ops can't edit yet.
+
+## Why
+
+Non-standard files.
+
+## How to fix
+
+Rewrite the file so every page is an indirect object (any full rewrite by another tool does), or wait for Lamina PDF's page-structure ops.
+
+## Example
+
+```text
+2 0 obj << /Type /Pages /Kids [<< /Type /Page /MediaBox [0 0 612 792] >>] /Count 1 >>
+```
+
+The page is written inline in `/Kids`. Reading works (its ID is a path ID such as `p2.0/Kids/0`), but a `rotatePage` op on it fails with `direct-page`.
+
+## Data fields
+
+None.

package/docs/errors/disposed.md

@@ -0,0 +1,34 @@
+---
+title: "disposed"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/disposed/"
+---
+
+# disposed
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+A `Document`, `Builder` or other handle of `@laminapdf/sdk` was used after `free()` released it, or after the `using` block that held it ended (`Symbol.dispose`). A page or save job is freed with its document, and a builder's page with its builder.
+
+## Why
+
+Each handle owns memory inside the WebAssembly module. Freeing it returns that memory at once, so the handle has nothing left to work on.
+
+## How to fix
+
+Free a handle only after its last use. To keep working with the document, open it again from its bytes, or create a new builder.
+
+## Example
+
+```ts
+const doc = Document.open(bytes);
+doc.free();
+doc.save(); // throws LaminaPdfError { code: "disposed", … }
+```
+
+## Data fields
+
+None.

package/docs/errors/document-changed.md

@@ -0,0 +1,34 @@
+---
+title: "document-changed"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/document-changed/"
+---
+
+# document-changed
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+A job's `step` was given a document other than the one the job was created from, or that document changed since: a committed transaction, an undo, a redo, a save or a rebase. Every step checks the document's instance and revision before any work, and the job is now finished.
+
+## Why
+
+Jobs don't borrow the document, so other calls can run between two steps. A save or a read that went on after an edit would mix two states of the document, so the job stops instead.
+
+## How to fix
+
+Pass the document the job was created from, don't change it while the job runs, and create a new job after a change. A failed save left the document as it was.
+
+## Example
+
+```rust
+let mut job = doc.save_job(&laminapdf::SaveOptions::new());
+doc.apply(vec![laminapdf::Op::from(set_info)])?; // the revision moves on
+assert_eq!(job.step(&mut doc, laminapdf::Budget::UNLIMITED).unwrap_err().code(), "document-changed");
+```
+
+## Data fields
+
+None.

package/docs/errors/embedded-file-forbidden.md

@@ -0,0 +1,35 @@
+---
+title: "embedded-file-forbidden"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/embedded-file-forbidden/"
+---
+
+# embedded-file-forbidden
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Builder::attach` added a file to a document built under PDF/A-2b or PDF/A-2u.
+
+## Why
+
+The PDF/A-2 standard for archival PDF (ISO 19005-2 §6.8) allows only attached files that are themselves PDF/A. Lamina PDF can't check what an attachment is, so it rejects every attachment under PDF/A-2 on purpose, PDF/A ones included. The PDF/A-3 standard for archival PDF (ISO 19005-3) allows files of any kind, provided they are associated with the document, which `Builder::attach` does.
+
+## How to fix
+
+Choose `Profile::PdfA3b` for documents that carry files, such as an e-invoice's XML, or leave the attachment out.
+
+## Example
+
+```rust
+let options = BuildOptions::default().with_profile(Profile::PdfA2b);
+let mut builder = Builder::new(options);
+builder.attach(Attachment::new("data.csv", csv, "text/csv"));
+builder.finish()?; // embedded-file-forbidden: use Profile::PdfA3b
+```
+
+## Data fields
+
+- `profile`: the profile, such as `PDF/A-2b`.

package/docs/errors/embedded-file-without-mime-type.md

@@ -0,0 +1,36 @@
+---
+title: "embedded-file-without-mime-type"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/embedded-file-without-mime-type/"
+---
+
+# embedded-file-without-mime-type
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under a PDF/A profile, `Builder::attach` added a file with an empty MIME type. A MIME type names the file's format, such as `text/xml`.
+
+## Why
+
+Software reading an archive years later needs to know what each attached file is. The PDF/A-3 standard for archival PDF (ISO 19005-3 §6.8) requires every embedded file to name its MIME type in the `/Subtype` of its stream, and Lamina PDF writes no `/Subtype` for an empty one.
+
+## How to fix
+
+Pass the file's MIME type to `Attachment::new`. For bytes of no particular type, use `application/octet-stream`.
+
+## Example
+
+```rust
+let options = BuildOptions::default().with_profile(Profile::PdfA3b);
+let mut builder = Builder::new(options);
+builder.attach(Attachment::new("invoice.xml", xml, ""));
+builder.finish()?; // embedded-file-without-mime-type: pass "text/xml"
+```
+
+## Data fields
+
+- `profile`: the profile, such as `PDF/A-3b`.
+- `name`: the file's name (untrusted: the caller's text).

package/docs/errors/encoding-full.md

@@ -0,0 +1,34 @@
+---
+title: "encoding-full"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/encoding-full/"
+---
+
+# encoding-full
+
+- Type: error
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+A standard 14 font had no free one-byte code left for another glyph in this document.
+
+## Why
+
+A standard 14 font is a simple font: text is written one byte per character, so one font resource addresses at most 256 glyphs (ISO 32000-2 §9.6.5). Lamina PDF writes the Latin fonts in `WinAnsiEncoding`, and gives each glyph of the standard Latin character set outside it (`Lslash`, `Scedilla`, `minus`, …) one of the 37 codes `WinAnsiEncoding` leaves undefined, through `/Differences`.
+
+A document that draws more such glyphs with one font than there are free codes runs out. Assignment is all or nothing: when one `encode` call needs more new codes than are free, none are assigned and nothing of the text is recorded.
+
+## How to fix
+
+Embed a font (`Font::from_bytes`), which addresses every glyph through a Type 0 font, or split the text across two registrations of the standard font (each is its own font resource with its own codes).
+
+## Example
+
+Drawing more than 37 different non-WinAnsi Latin glyphs (Ā, ă, Ą, …) with `Standard14::Helvetica` in one document: the 38th has no free code in the font's `/Differences`, so the call fails with `encoding-full`.
+
+## Data fields
+
+- `font`: the standard font's PostScript name (fixed text: one of the fourteen).
+- `limit`: how many codes `/Differences` can assign for this font.
+- `free`: how many of them were still free; the text needed more, so none were assigned.

package/docs/errors/encrypted-base.md

@@ -0,0 +1,33 @@
+---
+title: "encrypted-base"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/encrypted-base/"
+---
+
+# encrypted-base
+
+- Type: error
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+A save was requested for an encrypted document without `SaveOptions::with_remove_encryption(true)` (every mode: `Auto`, `Incremental` and `FullRewrite`). Nothing was written. `laminapdf_save::SaveError::EncryptedBase` and the writers' `laminapdf_cos::Error::EncryptedBase` share this code.
+
+## Why
+
+Lamina PDF can't encrypt on save yet, and it never drops or corrupts encryption silently.
+
+## How to fix
+
+Save with `SaveOptions::with_remove_encryption(true)` to write a plaintext full rewrite (every string and stream decrypted, no `/Encrypt`), or wait until Lamina PDF can encrypt on save. A signed and encrypted document also needs `with_invalidate_signatures(true)`.
+
+## Example
+
+```rust
+let err = doc.save(&SaveOptions::default()).unwrap_err(); // encrypted-base
+let saved = doc.save(&SaveOptions::default().with_remove_encryption(true))?;
+```
+
+## Data fields
+
+None.