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

package/docs/errors/invalid-structure.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-structure"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-structure/"
 ---
 

package/docs/errors/invalid-text-range.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-text-range"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-text-range/"
 ---
 

package/docs/errors/job-finished.md

@@ -1,6 +1,6 @@
 ---
 title: "job-finished"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/job-finished/"
 ---
 

package/docs/errors/limit-exceeded.md

@@ -1,6 +1,6 @@
 ---
 title: "limit-exceeded"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/limit-exceeded/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "link-without-contents"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/link-without-contents/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "link-without-structure"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/link-without-structure/"
 ---
 

package/docs/errors/markdown-html-ignored.md

@@ -0,0 +1,33 @@
+---
+title: "markdown-html-ignored"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/markdown-html-ignored/"
+---
+
+# markdown-html-ignored
+
+- Type: warning
+- Kind: `unsupported` (valid input that Lamina PDF can't handle yet)
+
+## What happened
+
+`Builder::markdown` found raw HTML in the Markdown, such as a `<div>` block or an inline `<span>`, left it out of the PDF and laid out the rest as usual. The builder raises one warning for each HTML block and each inline HTML tag.
+
+## Why
+
+Markdown lets authors mix in HTML, and a browser would draw it. Laying out HTML needs a web page's layout rules, which a PDF builder doesn't have. Rather than print the tags as text, the builder leaves the HTML out and says where it was.
+
+## How to fix
+
+Write the content in Markdown instead: `**bold**` for `<b>`, a table for `<table>`, an image for `<img>`. If the HTML is only a comment, such as `<!-- draft -->`, remove it or ignore the warning.
+
+## Example
+
+```rust
+let report = builder.markdown("Hello <span>there</span>\n", &MarkdownBuildOptions::new())?;
+assert_eq!(report.warnings[0].code(), "markdown-html-ignored");
+```
+
+## Data fields
+
+- `offset`: where the HTML starts, as a byte offset into the Markdown.

package/docs/errors/markdown-image-missing.md

@@ -0,0 +1,34 @@
+---
+title: "markdown-image-missing"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/markdown-image-missing/"
+---
+
+# markdown-image-missing
+
+- Type: warning
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Builder::markdown` met an image, such as `![Chart](chart.png)`, whose bytes weren't passed in. It left the image out of the PDF and laid out the rest of the document as usual.
+
+## Why
+
+The builder reads no files and fetches nothing from the network, so it can only draw images the caller supplies. An image path the options don't list, or a web address, has nothing behind it.
+
+## How to fix
+
+Read the image yourself and pass it with `MarkdownBuildOptions::with_image`, under the same path the Markdown uses.
+
+## Example
+
+```rust
+let chart = Image::png(&std::fs::read("chart.png")?)?;
+let options = MarkdownBuildOptions::new().with_image("chart.png", chart);
+builder.markdown("![Chart](chart.png)\n", &options)?;
+```
+
+## Data fields
+
+- `offset`: where the image starts, as a byte offset into the Markdown.

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

@@ -1,6 +1,6 @@
 ---
 title: "missing-alt-text"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/missing-alt-text/"
 ---
 

package/docs/errors/missing-glyph.md

@@ -1,6 +1,6 @@
 ---
 title: "missing-glyph"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/missing-glyph/"
 ---
 

package/docs/errors/missing-header.md

@@ -1,6 +1,6 @@
 ---
 title: "missing-header"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/missing-header/"
 ---
 

package/docs/errors/missing-lang.md

@@ -1,6 +1,6 @@
 ---
 title: "missing-lang"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/missing-lang/"
 ---
 

package/docs/errors/missing-root.md

@@ -1,6 +1,6 @@
 ---
 title: "missing-root"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/missing-root/"
 ---
 

package/docs/errors/missing-title.md

@@ -1,6 +1,6 @@
 ---
 title: "missing-title"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/missing-title/"
 ---
 

package/docs/errors/model-failed.md

@@ -0,0 +1,33 @@
+---
+title: "model-failed"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/model-failed/"
+---
+
+# model-failed
+
+- Type: error
+- Kind: `internal` (something failed outside the caller's control)
+
+## What happened
+
+A layout model, an OCR engine or the page renderer that feeds them failed while an extraction was using it. The extraction stopped and returned no partial result.
+
+## Why
+
+Models are plug-ins: the extraction calls the model and the renderer it was given, and stops when either reports an error. The error's message is the plug-in's own, and never holds text from the document.
+
+## How to fix
+
+Check the plug-in's own logs or setup: a missing weights file, a runtime that failed to load, a page too large to render. To get a result meanwhile, extract without the model; the rules alone still give every page's blocks.
+
+## Example
+
+```rust
+let options = laminapdf::extract::ExtractOptions::new(); // no models: rules only
+let extraction = doc.extract(&options)?;
+```
+
+## Data fields
+
+None.

package/docs/errors/model-needs-host.md

@@ -0,0 +1,40 @@
+---
+title: "model-needs-host"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/model-needs-host/"
+---
+
+# model-needs-host
+
+- Type: error
+- Kind: `usage` (the call itself is wrong)
+
+## What happened
+
+An extraction in one call (`extract`) was given a model whose results only the host can give: a model named as the host's (`ModelSlot::Host`), or a plug-in model with no page renderer to draw the pages it reads.
+
+## Why
+
+A one-call extraction runs to the end without stopping, so it can only use models it can call itself, on pages its renderer draws. A host's model answers through the extraction job, which stops at each page that needs a result.
+
+## How to fix
+
+Step an extraction job and hand it each result: `request()` says which page and resolution it needs, `provide(result)` gives it back. Or give the plug-in model a page renderer, so the extraction calls it between pages.
+
+## Example
+
+```rust
+let mut job = doc.extract_job(&options)?;
+loop {
+    if let laminapdf::Step::Done(extraction) = job.step(&doc, laminapdf::Budget::UNLIMITED)? {
+        break extraction;
+    }
+    if let Some(request) = job.request().cloned() {
+        job.provide(run_my_model(&request))?;
+    }
+}
+```
+
+## Data fields
+
+None.

package/docs/errors/model-result-unexpected.md

@@ -0,0 +1,36 @@
+---
+title: "model-result-unexpected"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/model-result-unexpected/"
+---
+
+# model-result-unexpected
+
+- Type: error
+- Kind: `usage` (the call itself is wrong)
+
+## What happened
+
+A model result was handed to an extraction job (`provide`) that wasn't waiting for one, or that was waiting for the other model's result: layout regions when it asked for OCR words, or the reverse.
+
+## Why
+
+A job whose models the host runs stops at each page that needs a result and says which one (`request()`). It takes exactly that result and nothing else, so results can't land on the wrong page.
+
+## How to fix
+
+Call `provide` only while `request()` returns a request, with the result its kind asks for: layout regions for a layout request, OCR words for an OCR request.
+
+## Example
+
+```rust
+while let laminapdf::Step::Progress { .. } = job.step(&doc, laminapdf::Budget::UNLIMITED)? {
+    if let Some(request) = job.request().cloned() {
+        job.provide(run_my_model(&request))?;
+    }
+}
+```
+
+## Data fields
+
+None.

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

@@ -1,6 +1,6 @@
 ---
 title: "name-tree-node-skipped"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/name-tree-node-skipped/"
 ---
 

package/docs/errors/nested-transaction.md

@@ -1,6 +1,6 @@
 ---
 title: "nested-transaction"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/nested-transaction/"
 ---
 

package/docs/errors/no-pending-save.md

@@ -1,6 +1,6 @@
 ---
 title: "no-pending-save"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/no-pending-save/"
 ---
 

package/docs/errors/no-transaction.md

@@ -1,6 +1,6 @@
 ---
 title: "no-transaction"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/no-transaction/"
 ---
 

package/docs/errors/not-initialized.md

@@ -1,6 +1,6 @@
 ---
 title: "not-initialized"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/not-initialized/"
 ---
 

package/docs/errors/not-pdf.md

@@ -1,6 +1,6 @@
 ---
 title: "not-pdf"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/not-pdf/"
 ---
 

package/docs/errors/not-rebased.md

@@ -1,6 +1,6 @@
 ---
 title: "not-rebased"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/not-rebased/"
 ---
 

package/docs/errors/object-number-out-of-range.md

@@ -1,6 +1,6 @@
 ---
 title: "object-number-out-of-range"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/object-number-out-of-range/"
 ---
 

package/docs/errors/objstm-index-mismatch.md

@@ -1,6 +1,6 @@
 ---
 title: "objstm-index-mismatch"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/objstm-index-mismatch/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "out-of-memory"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/out-of-memory/"
 ---
 

package/docs/errors/outline-cycle.md

@@ -1,6 +1,6 @@
 ---
 title: "outline-cycle"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/outline-cycle/"
 ---
 

package/docs/errors/outline-item-skipped.md

@@ -1,6 +1,6 @@
 ---
 title: "outline-item-skipped"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/outline-item-skipped/"
 ---
 

package/docs/errors/output-unwritable.md

@@ -1,6 +1,6 @@
 ---
 title: "output-unwritable"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/output-unwritable/"
 ---
 

package/docs/errors/overwrite-refused.md

@@ -1,6 +1,6 @@
 ---
 title: "overwrite-refused"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/overwrite-refused/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "page-count-mismatch"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/page-count-mismatch/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "page-index-out-of-range"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/page-index-out-of-range/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "page-tree-node-skipped"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/page-tree-node-skipped/"
 ---
 

package/docs/errors/password-required.md

@@ -1,6 +1,6 @@
 ---
 title: "password-required"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/password-required/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "path-outside-roots"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/path-outside-roots/"
 ---
 

package/docs/errors/perms-mismatch.md

@@ -1,6 +1,6 @@
 ---
 title: "perms-mismatch"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/perms-mismatch/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "profile-version-conflict"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/profile-version-conflict/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "reference-cycle"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/reference-cycle/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "render-backend-unavailable"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/render-backend-unavailable/"
 ---
 

package/docs/errors/render-failed.md

@@ -1,6 +1,6 @@
 ---
 title: "render-failed"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/render-failed/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "render-too-large"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/render-too-large/"
 ---
 

package/docs/errors/repaired-base.md

@@ -1,6 +1,6 @@
 ---
 title: "repaired-base"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/repaired-base/"
 ---
 

package/docs/errors/requires-rewrite.md

@@ -1,6 +1,6 @@
 ---
 title: "requires-rewrite"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/requires-rewrite/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "saved-not-rebased"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/saved-not-rebased/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "sink-not-empty"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/sink-not-empty/"
 ---
 

package/docs/errors/sink.md

@@ -1,6 +1,6 @@
 ---
 title: "sink"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/sink/"
 ---
 

package/docs/errors/source-budget-exceeded.md

@@ -1,6 +1,6 @@
 ---
 title: "source-budget-exceeded"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/source-budget-exceeded/"
 ---
 

package/docs/errors/source-changed.md

@@ -1,6 +1,6 @@
 ---
 title: "source-changed"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/source-changed/"
 ---