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

package/docs/errors/font-not-shapable.md

@@ -0,0 +1,33 @@
+---
+title: "font-not-shapable"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/font-not-shapable/"
+---
+
+# font-not-shapable
+
+- Type: error
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+A standard 14 font (`Font::standard`) was given to the shaper, `itemize`, `break_lines` or `pdf_run`.
+
+## Why
+
+The standard 14 fonts are referred to by name and never embedded. Lamina PDF has their metrics (Adobe's AFM files) but no font program, so there is nothing for HarfRust to shape with and no `cmap` for itemizing. Nor are there CIDs for a shaped run: a standard 14 font is written as a simple font with one-byte codes.
+
+## How to fix
+
+Draw standard 14 text with `FontRegistry::encode` (one glyph per character, kerning not applied), or load a real font with `Font::from_bytes` and shape with it.
+
+## Example
+
+```rust
+let helvetica = Font::standard(Standard14::Helvetica);
+shaper.shape(&helvetica, "Hello", &options)?; // font-not-shapable
+```
+
+## Data fields
+
+- `font`: the standard font's PostScript name (fixed text: one of the fourteen).

package/docs/errors/glyph-out-of-range.md

@@ -0,0 +1,34 @@
+---
+title: "glyph-out-of-range"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/glyph-out-of-range/"
+---
+
+# glyph-out-of-range
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`FontRegistry::use_glyph` was given a glyph ID at or past the font's glyph count.
+
+## Why
+
+Glyph IDs must come from the same font (its `cmap` or a shaper run on it).
+
+## How to fix
+
+Pass glyph IDs from the font you registered.
+
+## Example
+
+```rust
+registry.use_glyph(key, GlyphId::new(60_000), "x")?; // the font has 1,200 glyphs
+```
+
+## Data fields
+
+- `gid`: the glyph ID.
+- `count`: the font's glyph count.
+- `font`: the font's PostScript name (**untrusted**: read from the font).

package/docs/errors/glyph-without-unicode.md

@@ -0,0 +1,37 @@
+---
+title: "glyph-without-unicode"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/glyph-without-unicode/"
+---
+
+# glyph-without-unicode
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/A-2u or PDF/UA-1, a glyph was drawn with no Unicode value, or with one that holds U+0000, U+FEFF or U+FFFE.
+
+A glyph that maps to the empty value doesn't fail. Shaping can draw one character with several glyphs: Noto Sans Arabic draws a beh as a dotless body and a dot. The body then carries the letter and the dot maps to the empty value, so the letter is read once.
+
+## Why
+
+Software can search, copy or read text aloud only when every glyph maps to a usable Unicode value. The PDF/A-2u archival standard (ISO 19005-2 §6.2.11.7.2) and the PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.21.7) both need that mapping. These are conditions 31-027 to 31-029 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Remove the NUL characters (U+0000) from the text, and check what it was decoded from: a NUL usually means a UTF-16 string read as UTF-8, or the end of a C string. An archive that needs no accessibility can use PDF/A-2b instead, which doesn't need Unicode for every glyph. PDF/UA-1 has no such relaxed variant.
+
+## Example
+
+```rust
+surface.text("\u{0}Report", &font, Pt::new(12.0), at)?;
+builder.finish()?; // glyph-without-unicode under Profile::PdfA2u
+```
+
+## Data fields
+
+- `profile`: the profile, `PDF/A-2u` or `PDF/UA-1`.
+- `font`: the font's PostScript name (untrusted: read from the font file).
+- `gid`: the glyph's ID in the font.

package/docs/errors/heading-level-skipped.md

@@ -0,0 +1,36 @@
+---
+title: "heading-level-skipped"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/heading-level-skipped/"
+---
+
+# heading-level-skipped
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/UA-1, the document's headings skip a level. Numbered headings are `H1`, `H2` and so on, as opposed to the unnumbered `H`. Either the first numbered heading is not `H1`, or a heading is more than one level below the heading before it (an `H3` straight after an `H1`).
+
+## Why
+
+Screen-reader users move through a document by its headings, and a skipped level suggests a missing section. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.4.2) requires numbered headings to start at `H1` and to go down one level at a time. These are conditions 14-002 and 14-003 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures. Going back up any number of levels is fine.
+
+## How to fix
+
+Use the next level down for a subsection (`H2` under `H1`, `H3` under `H2`). If a heading should only look smaller, change its font size, not its level.
+
+## Example
+
+```rust
+s.text("Results", &font, Pt::new(18.0), at)?.tag(TagKind::H1);
+s.text("Method", &font, Pt::new(12.0), at2)?.tag(TagKind::H3);
+builder.finish()?; // heading-level-skipped: the second heading should be an H2
+```
+
+## Data fields
+
+- `page`: the page's index (0-based).
+- `level`: the heading's level.
+- `previous`: the level of the heading before it (0 when there is none).

package/docs/errors/image-data-length.md

@@ -0,0 +1,33 @@
+---
+title: "image-data-length"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/image-data-length/"
+---
+
+# image-data-length
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Image::rgba(width, height, bytes)` was given a number of bytes other than `width × height × 4`.
+
+## Why
+
+Raw RGBA samples are 4 bytes per pixel, row by row from the top, with no padding.
+
+## How to fix
+
+Pass exactly 4 bytes per pixel.
+
+## Example
+
+```rust
+let img = Image::rgba(2, 2, &[0; 12])?; // image-data-length: 16 bytes expected
+```
+
+## Data fields
+
+- `expected`: the length the dimensions call for.
+- `actual`: the length given.

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

@@ -0,0 +1,32 @@
+---
+title: "image-too-large"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/image-too-large/"
+---
+
+# image-too-large
+
+- Type: error
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+Decoding a PNG would need more than `MAX_DECODED_IMAGE_BYTES` (256 MiB), or the dimensions given to `Image::rgba` describe more bytes than fit in memory's address space.
+
+## Why
+
+The builder decodes PNGs to split colour and alpha; a bound on the decoded size keeps a small file with huge dimensions from exhausting memory.
+
+## How to fix
+
+Scale the image down before adding it, or use a JPEG, which is embedded without decoding.
+
+## Example
+
+```rust
+let img = Image::png(&png_of_30000_by_30000_pixels)?; // image-too-large: over 256 MiB decoded
+```
+
+## Data fields
+
+- `limit`: the limit in decoded bytes.

package/docs/errors/inline-image-unterminated.md

@@ -0,0 +1,36 @@
+---
+title: "inline-image-unterminated"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/inline-image-unterminated/"
+---
+
+# inline-image-unterminated
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+No `EI` ends an inline image (neither at its declared or computed length nor by searching for it); the rest of the content was skipped.
+
+## Why
+
+Damaged or truncated content.
+
+## How to fix
+
+Check the page: everything after the inline image is missing.
+
+## Example
+
+```text
+BI /W 10 /H 10 /CS /G /BPC 8 ID …(100 bytes, then the stream ends)…
+```
+
+No `EI` follows the image data, so the rest of the stream is skipped.
+
+## Data fields
+
+- `offset`: the `BI`'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/input-unreadable.md

@@ -0,0 +1,37 @@
+---
+title: "input-unreadable"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/input-unreadable/"
+---
+
+# input-unreadable
+
+- Type: error
+- Kind: `io` (the host failed to supply or take bytes)
+
+## What happened
+
+An input couldn't be read: the PDF named on the command line, standard input, or the file given to `--password-file`.
+
+## Why
+
+The file may not exist, may be a folder, or may not be readable by the user running the command.
+
+## How to fix
+
+Check that the file exists and that you can read it. `data.input` names the file, and `data.reason` says what the system reported.
+
+## Example
+
+```console
+$ laminapdf info missing.pdf
+error[input-unreadable]: couldn't read an input
+  = hint: check that the file exists and that you can read it; data.input names it
+$ echo $?
+1
+```
+
+## Data fields
+
+- `input`: the file that couldn't be read, or `-` for standard input (untrusted: caller text, never in the message).
+- `reason`: the system's error kind, such as `NotFound` or `PermissionDenied`.

package/docs/errors/instance-reset.md

@@ -0,0 +1,34 @@
+---
+title: "instance-reset"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/instance-reset/"
+---
+
+# instance-reset
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+A document, page, builder or save job was used after its WebAssembly instance was replaced. `reset()` replaces every loaded module's instance, and a trap (`wasm-trap` or `out-of-memory`) replaces the instance that trapped. The handle belonged to the old instance, so it has nothing left to work on.
+
+## Why
+
+Each handle lives in one instance's memory, and a fresh instance starts empty. Lamina PDF can't move a document across, so every handle from the old instance stops working at once.
+
+## How to fix
+
+Open the document again from its bytes, or create a new builder. Unsaved edits are lost with the old instance, so save often in an app that calls `reset()` or may run out of memory.
+
+## Example
+
+```ts
+const doc = Document.open(bytes);
+reset();
+doc.pageCount; // throws LaminaPdfError { code: "instance-reset", … }
+```
+
+## Data fields
+
+None.

package/docs/errors/invalid-argument.md

@@ -0,0 +1,33 @@
+---
+title: "invalid-argument"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-argument/"
+---
+
+# invalid-argument
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A value passed from JavaScript to `@laminapdf/wasm` is not of the type its declaration describes. It might be a record with a field of the wrong type, or a string that names no known value (a blend mode, a fill rule, a standard 14 font, an op). It might also be a flat-encoded path cut short, a colour with the wrong number of components, or an ID that isn't 32 hex digits.
+
+## Why
+
+The `.d.ts` types describe each argument, but JavaScript (and code written without the types) can pass anything. The binding checks each value as it converts it.
+
+## How to fix
+
+Pass what the declaration says. When the value names an unknown string, `didYouMean` lists the closest allowed ones; `data.detail` says what the conversion found.
+
+## Example
+
+```js
+page.blendMode("multiplly"); // throws { code: "invalid-argument", didYouMean: ["multiply"], … }
+```
+
+## Data fields
+
+- `argument`: the parameter that was wrong (`options`, `path`, `mode`, …).
+- `detail`: what the conversion said (untrusted: it may quote the value passed).

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

@@ -0,0 +1,32 @@
+---
+title: "invalid-axis-value"
+version: "0.2.0-alpha.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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.4"
+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).