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

package/docs/errors/content-syntax.md

@@ -0,0 +1,36 @@
+---
+title: "content-syntax"
+version: "0.2.0-alpha.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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/data-pending.md

@@ -0,0 +1,34 @@
+---
+title: "data-pending"
+version: "0.2.0-alpha.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.

package/docs/errors/extract-limit-blocks.md

@@ -0,0 +1,35 @@
+---
+title: "extract-limit-blocks"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/extract-limit-blocks/"
+---
+
+# extract-limit-blocks
+
+- Type: warning
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+A page had more runs of text than `ExtractLimits::max_blocks_per_page` allows. Since each run can be a block of its own, extraction kept the first runs the page draws and left out the rest. It cuts them before grouping runs into blocks, so the work stays bounded.
+
+## Why
+
+A page of many tiny separate pieces of text, such as a dense table, a map with hundreds of labels, or a file built to slow extraction down.
+
+## How to fix
+
+Raise `max_blocks_per_page` if the page really holds that many blocks.
+
+## Example
+
+```rust
+let mut options = laminapdf_extract::ExtractOptions::default();
+options.limits.max_blocks_per_page = 50_000;
+```
+
+## Data fields
+
+- `limit`: the limit that was reached.
+
+The `location` has the page's `pageIndex`.

package/docs/errors/extract-module-not-loaded.md

@@ -0,0 +1,37 @@
+---
+title: "extract-module-not-loaded"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/extract-module-not-loaded/"
+---
+
+# extract-module-not-loaded
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+`page.text()` of `@laminapdf/sdk` was called on a page of a document opened in the base module, which has no text extraction.
+
+## Why
+
+`@laminapdf/sdk` ships three WebAssembly modules: base (open, read, edit, save), extract (base plus text extraction) and text (base plus fonts, shaping and extraction). A document lives in the module it was opened in, and opening uses the richest one loaded at that moment: text, then extract, then base. A document opened before the extract or text module was loaded stays in the base module.
+
+## How to fix
+
+Load the extract module (about half the size of the text module) before opening the document: `await init({ extract: true })` or `await loadExtract()`. A document already open in the base module can be moved by saving it and opening the bytes again.
+
+## Example
+
+```js
+await init();
+const doc = Document.open(bytes);
+doc.page(0).text(); // throws { code: "extract-module-not-loaded", … }
+
+await loadExtract();
+Document.open(bytes).page(0).text().text(); // works
+```
+
+## Data fields
+
+None.

package/docs/errors/extract-reading-order-ambiguous.md

@@ -0,0 +1,32 @@
+---
+title: "extract-reading-order-ambiguous"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/extract-reading-order-ambiguous/"
+---
+
+# extract-reading-order-ambiguous
+
+- Type: warning
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+A page mixes horizontal and vertical writing. Extraction put its blocks in an order, but no layout rule tells which comes first, so the order is a guess.
+
+## Why
+
+Japanese and Chinese pages often set the body vertically and captions, headings or page numbers horizontally. Without a structure tree, nothing in the file says how the two relate.
+
+## How to fix
+
+Nothing to do in Lamina PDF; the file is valid. Like every warning, it fails the call in strict mode. Check the order of that page's blocks, or ask for the order the content stream draws (`ReadingOrder::ContentStream`). A tagged file avoids the guess.
+
+## Example
+
+A page whose body text is drawn with a vertical font (`Identity-V`) and whose page number is drawn with a horizontal one.
+
+## Data fields
+
+None.
+
+The `location` has the page's `pageIndex`.

package/docs/errors/extract-struct-tree-ignored.md

@@ -0,0 +1,32 @@
+---
+title: "extract-struct-tree-ignored"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/extract-struct-tree-ignored/"
+---
+
+# extract-struct-tree-ignored
+
+- Type: warning
+- Kind: `input` (a problem with the PDF file)
+
+## What happened
+
+The page is tagged, but its structure tree didn't pass the checks that decide whether to trust it, so extraction read the page in layout order instead.
+
+## Why
+
+A structure tree gives a page's reading order, but trees are often incomplete or wrong. Extraction uses a page's tree only when its elements cover at least 80% of the page's visible text, not counting headers, page numbers and other text the file marks as page furniture. Its order must also jump back up into an earlier column at most once in ten moves from block to block. A tree written by a tool that tags only some of the text, or that tags it in drawing order, fails one of the checks.
+
+## How to fix
+
+Nothing to do: the page reads in layout order, as an untagged page would. To use the tree anyway, extract with `ReadingOrder::Tagged` (`readingOrder: "tagged"`). Like every warning, it fails the call in strict mode.
+
+## Example
+
+A report whose tool tagged only its headings: the tree covers a tenth of the text, so the reason is `coverage`.
+
+## Data fields
+
+- `reason`: `coverage` or `order`, the check that failed.
+
+The `location` has the page's `pageIndex`.