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

package/docs/errors/invalid-icc-profile.md

@@ -0,0 +1,32 @@
+---
+title: "invalid-icc-profile"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-icc-profile/"
+---
+
+# invalid-icc-profile
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+`IccProfile::new` (`laminapdf-build`) rejected the bytes.
+
+## Why
+
+An ICC profile (ICC.1:2010) starts with a 128-byte header holding its size, the `acsp` signature, its class and its data colour space. PDF's `ICCBased` colour spaces (ISO 32000-2 §8.6.5.5) take Gray, RGB, CMYK and Lab profiles. The builder takes Gray, RGB and CMYK: Lab components fall outside `[0, 1]` and need a `/Range`, which it doesn't support yet. Device-link, abstract and named-colour profiles can't be used.
+
+## How to fix
+
+Pass the complete bytes of an input, display, output or colour-space profile with a Gray, RGB or CMYK data colour space.
+
+## Example
+
+```rust
+let profile = IccProfile::new(b"not a profile".to_vec())?; // invalid-icc-profile
+```
+
+## Data fields
+
+- `reason`: what was wrong (fixed text).

package/docs/errors/invalid-image.md

@@ -0,0 +1,33 @@
+---
+title: "invalid-image"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-image/"
+---
+
+# invalid-image
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+`Image::jpeg`, `Image::png` or `Image::png_with` (`laminapdf-build`) could not read the bytes as an image of that format.
+
+## Why
+
+A JPEG must start with a start-of-image marker and have a frame header (SOF) before its first scan, with every marker segment inside the data; a PNG must decode without errors (signature, chunk CRCs, zlib data, sizes).
+
+## How to fix
+
+Pass the complete file. Check that the bytes are the format you called (a PNG passed to `Image::jpeg` fails here).
+
+## Example
+
+```rust
+let img = Image::jpeg(std::fs::read("photo.png")?)?; // invalid-image: PNG bytes given as JPEG
+```
+
+## Data fields
+
+- `format`: `Jpeg`, `Png` or `Rgba`.
+- `reason`: what was wrong (fixed text).

package/docs/errors/invalid-op-log.md

@@ -0,0 +1,33 @@
+---
+title: "invalid-op-log"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-op-log/"
+---
+
+# invalid-op-log
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An op log does not parse: an unknown op or field, a bad value, or not JSON.
+
+## Why
+
+Hand-written or corrupted op logs.
+
+## How to fix
+
+Validate the log against the op schema; the samples in `fixtures/ops/v1/` show the format.
+
+## Example
+
+```rust
+doc.apply_log(r#"{ "v": 1, "ops": [{ "op": "rotate" }] }"#)?;
+// invalid-op-log: "rotate" is not an op (it is "rotatePage"); data.detail has serde's message
+```
+
+## Data fields
+
+`detail` (**untrusted**: may quote the log; the message never includes it).

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

@@ -0,0 +1,34 @@
+---
+title: "invalid-page-label"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-page-label/"
+---
+
+# invalid-page-label
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A `/PageLabels` entry is malformed; that part is dropped.
+
+## Why
+
+A writer bug: a range that is not a dictionary, an unknown `/S` style, a non-string `/P` prefix or an `/St` below 1.
+
+## How to fix
+
+Nothing; affected pages fall back to decimal labels.
+
+## Example
+
+```text
+/PageLabels << /Nums [0 << /S /Fancy >> 4 << /S /r >>] >>
+```
+
+`/Fancy` is not a numbering style, so pages 0–3 get decimal labels; the range starting at 4 is kept. `data` is `{ "start": 0 }`.
+
+## Data fields
+
+`start`.

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

@@ -0,0 +1,32 @@
+---
+title: "invalid-page-labels"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-page-labels/"
+---
+
+# invalid-page-labels
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+The ranges given to `Builder::page_labels` can't be written as a `/PageLabels` number tree.
+
+## Why
+
+ISO 32000-2 §7.7.2 and §12.4.2: the tree must have an entry for page index 0, its keys are page indexes in increasing order, and a label range's first number (`/St`) is at least 1. A range starting past the document's last page would label nothing.
+
+## How to fix
+
+Give the ranges sorted by first page, the first starting at page 0, each start a page of the document, and numbers from 1 (`PageLabel::with_first`).
+
+## Example
+
+```rust
+builder.page_labels([PageLabel::new(1, Some(LabelStyle::Decimal))]); // invalid-page-labels at finish: no range starts at page 0
+```
+
+## Data fields
+
+- `what`: what is wrong (fixed text).

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

@@ -0,0 +1,37 @@
+---
+title: "invalid-page-range"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-page-range/"
+---
+
+# invalid-page-range
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A page range doesn't fit the grammar, or it names a page the document doesn't have, such as page 9 of a 5-page file.
+
+## Why
+
+Ranges count pages from 1, as people do. A range that can't be read, or that reaches past the last page, fails before anything is written, so a command never works on the wrong pages.
+
+## How to fix
+
+Write pages as `1-5`, `z` for the last page, `r2` for the second from the end, `x3` to leave page 3 out, and `:odd` or `:even` at the end for every other page of the result. `data.position` is the character where the range went wrong.
+
+## Example
+
+```console
+$ laminapdf pages rotate scan.pdf +90:1-9 -o out.pdf
+error[invalid-page-range]: the document has 5 pages
+  = hint: write pages as 1-5, z for the last page, …
+$ echo $?
+2
+```
+
+## Data fields
+
+- `range`: the range given (untrusted: caller text, never in the message).
+- `position`: the 1-based character of `range` where it went wrong.

package/docs/errors/invalid-rotate.md

@@ -0,0 +1,34 @@
+---
+title: "invalid-rotate"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-rotate/"
+---
+
+# invalid-rotate
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A page's `/Rotate` is not a multiple of 90; it reads as 0.
+
+## Why
+
+A writer bug, or a viewer setting stored as an arbitrary angle.
+
+## How to fix
+
+Nothing to do if the page displays upright. Otherwise set the rotation you want with the `rotatePage` op.
+
+## Example
+
+```text
+3 0 obj << /Type /Page /Rotate 45 … >>
+```
+
+`/Rotate` must be a multiple of 90 (ISO 32000-2 §7.7.3.3); the page reads as unrotated.
+
+## Data fields
+
+None.

package/docs/errors/invalid-spans.md

@@ -0,0 +1,39 @@
+---
+title: "invalid-spans"
+version: "0.2.0-alpha.4"
+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

@@ -0,0 +1,38 @@
+---
+title: "invalid-structure-nesting"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-structure-nesting/"
+---
+
+# invalid-structure-nesting
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/UA-1, a table or list element sits in a parent its type doesn't allow. A table (`Table`) holds rows (`TR`), each holding header cells (`TH`) and data cells (`TD`); a list (`L`) holds list items (`LI`), each holding a label (`Lbl`, its bullet or number) and a body (`LBody`). Examples of a wrong parent: a `TD` or `TH` outside a `TR`, a `TR` outside a `Table`, an `LI` outside an `L`, or a paragraph directly inside a `Table`, `TR`, `L` or `LI`.
+
+## Why
+
+ISO 32000-1 Tables 336 and 337 define how tables and lists are built, and assistive technology relies on that shape to announce rows, columns and list items. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.2) requires tables and lists to have that shape. These are conditions 09-004 and 09-005 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Nest tables as `Table` > `TR` > `TH` or `TD` (optionally with `THead`, `TBody` and `TFoot` around the rows, and a `Caption`), and lists as `L` > `LI` > `Lbl` and `LBody`. Put paragraphs and other content inside the cells and list bodies.
+
+## Example
+
+```rust
+s.tag(TagKind::Table, |s| {
+    s.text("Total", &font, Pt::new(11.0), at)?.tag(TagKind::TD); // a TD straight in the Table
+    Ok(())
+})?;
+builder.finish()?; // invalid-structure-nesting: wrap the cell in a TR
+```
+
+## Data fields
+
+- `page`: the page's index (0-based).
+- `kind`: the element's standard type, such as `TD`.
+- `parent`: its parent's standard type (`Document` at the top level).

package/docs/errors/invalid-structure.md

@@ -0,0 +1,34 @@
+---
+title: "invalid-structure"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-structure/"
+---
+
+# invalid-structure
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An object stream, xref section or filter parameter was malformed or out of range.
+
+## Why
+
+Malformed input: an object stream, xref section or filter parameter out of range.
+
+## How to fix
+
+Use another copy of the file.
+
+## Example
+
+```text
+12 0 obj << /Type /ObjStm /N 3 /First -4 >>
+```
+
+A negative `/First` makes the object stream unusable; `data.structure` says which structure was malformed.
+
+## Data fields
+
+`structure`.

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

@@ -0,0 +1,33 @@
+---
+title: "invalid-text-range"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-text-range/"
+---
+
+# invalid-text-range
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A byte range of a text given to `Shaper::shape_range`, `BidiParagraph::visual_runs` or `BidiParagraph::line_levels`, or the range of a `ShapedRun` given to `pdf_run`, is past the end of the text or does not start and end on character boundaries.
+
+## Why
+
+Ranges are byte offsets into UTF-8 text; a range that cuts a character in two (or reaches past the end) names no text.
+
+## How to fix
+
+Take ranges from Lamina PDF's own results (`line_breaks`, `itemize`, `break_lines`, `ShapedRun::text_range`), or check them with `str::get` first, and pass the same text the range was computed on.
+
+## Example
+
+```rust
+shaper.shape_range(&font, "héllo", 0..2, &options)?; // byte 2 is inside 'é'
+```
+
+## Data fields
+
+- `start`, `end`: the range (bytes).
+- `len`: the text's length (bytes).

package/docs/errors/job-finished.md

@@ -0,0 +1,34 @@
+---
+title: "job-finished"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/job-finished/"
+---
+
+# job-finished
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+`step` was called on a job that had already returned its result, failed or been cancelled.
+
+## Why
+
+A job ends with its first `Step::Done`, or with its first error: an error ends the job. A step loop that keeps going after either reaches this.
+
+## How to fix
+
+Stop stepping once a step returns `Done` or an error. To run the work again, create a new job.
+
+## Example
+
+```rust
+let mut job = doc.save_job(&laminapdf::SaveOptions::new());
+while let laminapdf::Step::Progress { .. } = job.step(&mut doc, laminapdf::Budget::UNLIMITED)? {}
+assert_eq!(job.step(&mut doc, laminapdf::Budget::UNLIMITED).unwrap_err().code(), "job-finished");
+```
+
+## Data fields
+
+None.

package/docs/errors/limit-exceeded.md

@@ -0,0 +1,38 @@
+---
+title: "limit-exceeded"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/limit-exceeded/"
+---
+
+# limit-exceeded
+
+- Type: error
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+A hard `Limits` value was exceeded.
+
+## Why
+
+Hostile or unusually large input.
+
+## How to fix
+
+Raise the named limit only if you trust the input.
+
+## Example
+
+```rust
+let options = OpenOptions::new().with_limits(Limits::new().with_max_nesting_depth(1));
+let doc = Document::open_bytes(bytes, options)?;
+let err = doc.page_count().unwrap_err();
+// { "code": "limit-exceeded", "kind": "limit", "data": { "limit": "max_nesting_depth" },
+//   "location": { "object": 9, "streamOffset": 89 }, … }
+```
+
+## Data fields
+
+`limit` (the limit's name).
+
+The `location` tells where the limit was hit. The nesting and string-length limits and the read window give `offset`, a file offset; the same limits inside an object stream give `object` with `streamOffset`. A reference chain gives `object` alone, and decoding budgets give no location.

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

@@ -0,0 +1,33 @@
+---
+title: "link-without-contents"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/link-without-contents/"
+---
+
+# link-without-contents
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/UA-1, a link annotation has no description: `Surface::link` or `TextRun::link` was called with `None` (or an empty string) as its contents.
+
+## Why
+
+A screen reader announces a link by its `/Contents`, its alternate description. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.18.5) requires one on every link. This is condition 28-012 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Pass a short description of where the link goes as the link's contents.
+
+## Example
+
+```rust
+surface.link(rect, LinkTarget::Uri("https://example.com/pay".into()), None);
+builder.finish()?; // link-without-contents: pass Some("Pay the invoice online".into())
+```
+
+## Data fields
+
+- `page`: the page's index (0-based).

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

@@ -0,0 +1,37 @@
+---
+title: "link-without-structure"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/link-without-structure/"
+---
+
+# link-without-structure
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/UA-1, a link annotation has no `Link` structure element. The builder gives every link one automatically, except a link drawn inside an artifact, which stays outside the structure.
+
+## Why
+
+A screen reader finds links through the structure tree, so a link inside decoration can't be reached. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.18.5) requires each link annotation to be nested in a `Link` element. This is condition 28-011 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Draw the link outside `Surface::artifact`, next to the text it belongs to; the builder then wraps it in a `Link` element.
+
+## Example
+
+```rust
+surface.artifact(ArtifactKind::Layout, |s| {
+    s.link(rect, LinkTarget::Uri("https://example.com".into()), Some("Example".into()));
+    Ok(())
+})?;
+builder.finish()?; // link-without-structure
+```
+
+## Data fields
+
+- `page`: the page's index (0-based).
+- `count`: how many links on that page lack a `Link` element.

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

@@ -0,0 +1,33 @@
+---
+title: "missing-alt-text"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/missing-alt-text/"
+---
+
+# missing-alt-text
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/UA-1, a page has a `Figure` or `Formula` element without alternate text: neither `/Alt` (`Tag::with_alt`) nor `/ActualText` (`Tag::with_actual_text`).
+
+## Why
+
+A screen reader can't describe a picture or a formula by itself. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.3) requires every `Figure` and every `Formula` to carry a text alternative. These are conditions 13-004 and 17-002 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures. Lamina PDF checks only that a description exists; whether it describes the figure well is for a person to judge.
+
+## How to fix
+
+Describe the figure with `Surface::figure(&image, rect, alt)` or `Tag::new(TagKind::Figure).with_alt(…)`. If the picture is decoration that carries no meaning, draw it inside `Surface::artifact` instead.
+
+## Example
+
+```rust
+surface.tag(TagKind::Figure, |s| { s.image(&chart, rect); Ok(()) })?;
+builder.finish()?; // missing-alt-text: use Tag::new(TagKind::Figure).with_alt("Sales by month")
+```
+
+## Data fields
+
+- `page`: the page's index (0-based).

package/docs/errors/missing-glyph.md

@@ -0,0 +1,33 @@
+---
+title: "missing-glyph"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/missing-glyph/"
+---
+
+# missing-glyph
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+Text contained a character the font has no glyph for. Lamina PDF never draws `.notdef` (an empty box) silently.
+
+## Why
+
+The font's `cmap` does not map the character (for example a CJK character with a Latin font).
+
+## How to fix
+
+Use a font that covers the character (check with `Font::glyph_for`), or split the text across fonts.
+
+## Example
+
+```rust
+registry.encode(latin_font, "東京")?; // missing-glyph: the font has no CJK glyphs
+```
+
+## Data fields
+
+- `ch`: the character (**untrusted**: caller or document text).
+- `font`: the font's PostScript name (**untrusted**: read from the font).