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

package/docs/errors/invalid-page-labels.md

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

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

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

package/docs/errors/invalid-rotate.md

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

package/docs/errors/invalid-spans.md

@@ -0,0 +1,39 @@
+---
+title: "invalid-spans"
+version: "0.2.0-alpha.5"
+url: "https://docs.laminapdf.com/reference/codes/invalid-spans/"
+---
+
+# invalid-spans
+
+- Type: error
+- Kind: `usage` (the caller passed something invalid)
+
+## What happened
+
+The styled spans passed to `break_spans` don't cover the paragraph's text exactly once, in order, or name fonts it can't use. One of these is true:
+
+- two spans leave a gap, overlap, or come out of order;
+- the last span stops before the end of the text, or runs past it;
+- a span starts or ends inside a character, or between a letter and its accent;
+- a span lists no fonts, or a font index past the end of the list.
+
+## Why
+
+Each character's font, size and language come from the span that holds it. A character in no span, or in two, would have no style or two styles, so Lamina PDF refuses the spans rather than guess. A letter and its accent are drawn as one glyph cluster, so they can't take two styles. An index past the end of the font list names no font.
+
+## How to fix
+
+List the spans in the order of the text. Start the first at byte 0, start each span where the one before it ends, and end the last at the text's length. Take span ends from `grapheme_boundaries` or `str::len`, so that they fall between clusters. List at least one font per span, each an index into the font list. An empty text needs no spans.
+
+## Example
+
+```rust
+let text = "Hello, world";
+let spans = [StyledSpan::new(0..5), StyledSpan::new(6..12)]; // byte 5 is in no span
+break_spans(&shaper, &fonts, text, &spans, &options)?; // invalid-spans
+```
+
+## Data fields
+
+- `at`: the byte offset where the spans stop covering the text, or where the span with a bad font list starts.

package/docs/errors/invalid-structure-nesting.md

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

package/docs/errors/invalid-structure.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-structure"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
+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.5"
+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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
+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.5"
+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.5"
+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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
+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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 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.5"
 url: "https://docs.laminapdf.com/reference/codes/requires-rewrite/"
 ---