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

package/docs/errors/invalid-axis-value.md

@@ -0,0 +1,32 @@
+---
+title: "invalid-axis-value"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/invalid-axis-value/"
+---
+
+# invalid-axis-value
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Font::instance` was given a NaN or infinite axis value.
+
+## Why
+
+Variation coordinates are user-space numbers such as `wght` 700; NaN and infinities have no position on an axis.
+
+## How to fix
+
+Pass finite values; values outside the axis range are clamped, so there is no need for infinities.
+
+## Example
+
+```rust
+font.instance(&[(OpenTypeTag::WEIGHT, f32::NAN)])?; // invalid-axis-value
+```
+
+## Data fields
+
+- `tag`: the axis.

package/docs/errors/invalid-box.md

@@ -0,0 +1,34 @@
+---
+title: "invalid-box"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/invalid-box/"
+---
+
+# invalid-box
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A page boundary box is not four numbers; it reads as absent.
+
+## Why
+
+A writer bug: a box that is not an array of four numbers (too few, or names or strings in it).
+
+## How to fix
+
+Nothing; the page uses the next box in the chain.
+
+## Example
+
+```text
+3 0 obj << /Type /Page /MediaBox [0 0 612 792] /CropBox [0 0 612] >>
+```
+
+The CropBox has three numbers, so it reads as absent and the page uses its MediaBox. `data` is `{ "key": "CropBox" }`.
+
+## Data fields
+
+`key` (which box, from Lamina PDF's fixed list).

package/docs/errors/invalid-color.md

@@ -0,0 +1,32 @@
+---
+title: "invalid-color"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/invalid-color/"
+---
+
+# invalid-color
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Color::hex` was given a string that is not `#rgb` or `#rrggbb`.
+
+## Why
+
+Hex colours are a `#` followed by three or six hexadecimal digits, in either case.
+
+## How to fix
+
+Write the colour as `#3366cc` or `#36c`, or use `Color::rgb`.
+
+## Example
+
+```rust
+let c = Color::hex("#12345")?; // invalid-color: 5 digits
+```
+
+## Data fields
+
+- `text`: the string as given (untrusted: caller text, never in the message).

package/docs/errors/invalid-command-line.md

@@ -0,0 +1,44 @@
+---
+title: "invalid-command-line"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/invalid-command-line/"
+---
+
+# invalid-command-line
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+The command line didn't parse: a command or flag `laminapdf` doesn't have, a missing argument, a value of the wrong form, or `-` (standard input) named as more than one input.
+
+## Why
+
+The CLI checks its whole command line before it reads any file, so a typo never runs half a command. Exit code 2 tells a script that the call itself was wrong, not the document.
+
+## How to fix
+
+Run the command with `--help` to see its arguments, and `laminapdf --help` for the commands. Read standard input at most once per command.
+
+## Example
+
+```console
+$ laminapdf info --pages 1 report.pdf
+error[invalid-command-line]: unexpected argument '--pages' found
+
+Usage: laminapdf info [OPTIONS] <INPUT>
+
+For more information, try '--help'.
+$ echo $?
+2
+```
+
+With `--json`, the line on standard error has the message "the command line doesn't parse" and the parser's finding in `data.detail`.
+
+## Data fields
+
+Which field is there depends on what was wrong:
+
+- `detail`: when the parser refused the line, the kind of problem it found, such as `UnknownArgument` or `MissingRequiredArgument`.
+- `argument`: when a value parsed but means nothing, the value given: the angle of `pages rotate`, a `help` topic or a `--fields` key (untrusted: caller text, never in the message).

package/docs/errors/invalid-date.md

@@ -0,0 +1,34 @@
+---
+title: "invalid-date"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/invalid-date/"
+---
+
+# invalid-date
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An Info date is not a valid PDF date (ISO 32000-2 §7.9.4); the raw string is kept.
+
+## Why
+
+Writers that write free-form dates.
+
+## How to fix
+
+The `Info` view keeps the raw string; read it there if you need it.
+
+## Example
+
+```text
+<< /CreationDate (last Tuesday) >>
+```
+
+The Info view's `creation_date` is `None` and its raw string is kept; `data` is `{ "key": "CreationDate" }`.
+
+## Data fields
+
+`key` (which entry).

package/docs/errors/invalid-entry.md

@@ -0,0 +1,34 @@
+---
+title: "invalid-entry"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/invalid-entry/"
+---
+
+# invalid-entry
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An entry a view reads is unreadable or of the wrong type; it reads as absent or its default.
+
+## Why
+
+A writer bug: an entry of the wrong type, or a reference that does not resolve.
+
+## How to fix
+
+Nothing to do; the view uses the entry's default.
+
+## Example
+
+```text
+1 0 obj << /Type /Catalog /Pages 2 0 R /Outlines (none) >>
+```
+
+`/Outlines` should be a dictionary; the outline reads as empty and `data` is `{ "key": "Outlines" }`.
+
+## Data fields
+
+`key` (from Lamina PDF's fixed list).

package/docs/errors/invalid-feature.md

@@ -0,0 +1,32 @@
+---
+title: "invalid-feature"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/invalid-feature/"
+---
+
+# invalid-feature
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+An OpenType feature setting given to the shaper (`"liga=0".parse::<Feature>()`) did not parse.
+
+## Why
+
+Feature settings use HarfBuzz's syntax without ranges: `tag` or `+tag` (on), `-tag` (off), `tag=N`, `tag=on` or `tag=off`, where the tag is one to four printable ASCII characters. A sign together with a value (`+liga=1`), an empty or longer tag, or a value that is not a non-negative integer is refused.
+
+## How to fix
+
+Write the setting as `liga=0`, `-liga`, `smcp` or `aalt=2`, or build it with `Feature::new(OpenTypeTag::new(b"liga"), 0)`.
+
+## Example
+
+```rust
+let f: Feature = "liga[3:5]=0".parse()?; // invalid-feature: ranges are not supported
+```
+
+## Data fields
+
+- `feature`: the setting as given (**untrusted**: caller text).

package/docs/errors/invalid-font.md

@@ -0,0 +1,32 @@
+---
+title: "invalid-font"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/invalid-font/"
+---
+
+# invalid-font
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+Font bytes passed to `Font::from_bytes` or `Font::from_collection` (`laminapdf-text`) could not be read as a font.
+
+## Why
+
+The bytes are not an OpenType/TrueType font or collection (WOFF/WOFF2 must be decompressed first), or a table every font needs (`head`, `hhea`, `hmtx`, `maxp`) is missing or malformed.
+
+## How to fix
+
+Pass the bytes of a `.ttf`, `.otf`, `.ttc` or `.otc` file; check that the file is complete.
+
+## Example
+
+```rust
+let err = laminapdf::Font::from_bytes(std::fs::read("font.woff2")?).unwrap_err(); // invalid-font
+```
+
+## Data fields
+
+- `index`: the collection member that was asked for (0 for a single font).

package/docs/errors/invalid-geometry.md

@@ -0,0 +1,32 @@
+---
+title: "invalid-geometry"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/invalid-geometry/"
+---
+
+# invalid-geometry
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A page size, page box, `/UserUnit`, drawing value or image size given to the builder is not usable. Drawing values are checked as the `Surface` receives them and the first bad one is reported by `PageBuilder::finish`.
+
+## Why
+
+Page sizes and `/UserUnit` must be finite and positive, and page boxes, path coordinates, matrices and image rectangles finite. Line widths and dash lengths must be finite and not negative, and a dash pattern not all zeros (ISO 32000-2 §8.4.3.6). Miter limits must be at least 1, images at least one pixel wide and tall, font sizes and line heights positive, text boxes wider than 0, and destination coordinates finite.
+
+## How to fix
+
+Check the values passed to `Builder::page`, `PageBuilder::user_unit`, the box setters, the `Surface` (paths, `transform`, `StrokeStyle`, `image`, `text` and `text_box` sizes, positions, boxes and line heights, `link` rectangles), destinations (`Fit` coordinates) and `Image::rgba`.
+
+## Example
+
+```rust
+let page = builder.page(PageSize::new(Pt::new(0.0), Pt::new(842.0))); // invalid-geometry at finish
+```
+
+## Data fields
+
+- `what`: which value was invalid (fixed text).

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

@@ -0,0 +1,32 @@
+---
+title: "invalid-icc-profile"
+version: "0.2.0-alpha.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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-structure-nesting.md

@@ -0,0 +1,38 @@
+---
+title: "invalid-structure-nesting"
+version: "0.2.0-alpha.3"
+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.3"
+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.3"
+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).