@laminapdf/sdk 0.0.0-stage → 0.2.0-alpha.3

package/docs/errors/extract-table-ambiguous.md

@@ -0,0 +1,32 @@
+---
+title: "extract-table-ambiguous"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/extract-table-ambiguous/"
+---
+
+# extract-table-ambiguous
+
+- Type: warning
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+Extraction found a table drawn with lines, but the cells its missing lines would join don't make a rectangle. Extraction kept the table and gave it one cell per square of its grid, so a merged cell's text sits in the first of the squares it covers.
+
+## Why
+
+A table's lines tell where cells are merged: a missing line between two squares joins them. Joined squares that form an L or a T shape don't describe a cell, usually because a line is drawn slightly short, drawn twice in different places, or covered by a white rectangle.
+
+## How to fix
+
+Nothing to do in Lamina PDF; the file is valid. Like every warning, it fails the call in strict mode. Check that table's cells: the text of a merged cell may be split across its neighbours.
+
+## Example
+
+A table whose header spans two columns over the first row only, but whose line under that header stops halfway.
+
+## Data fields
+
+None.
+
+The `location` has the page's `pageIndex`.

package/docs/errors/extract-table-limit.md

@@ -0,0 +1,35 @@
+---
+title: "extract-table-limit"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/extract-table-limit/"
+---
+
+# extract-table-limit
+
+- Type: warning
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+A page's ruling lines would have made a table with more cells than `ExtractLimits::max_table_cells` allows, or the page drew so many lines that matching them all would cost too much. Extraction made no table from those lines; their text is still in the page's paragraphs.
+
+## Why
+
+A page drawn with thousands of lines, such as a large grid, a chart's gridlines or a file built to slow extraction down. To find a table, extraction compares every horizontal line with every vertical one, so the work grows with the square of the line count.
+
+## How to fix
+
+Raise `max_table_cells` if the page really holds a table that big.
+
+## Example
+
+```rust
+let mut options = laminapdf_extract::ExtractOptions::default();
+options.limits.max_table_cells = 50_000;
+```
+
+## Data fields
+
+- `limit`: the limit that was reached.
+
+The `location` has the page's `pageIndex`.

package/docs/errors/extract-untagged-content.md

@@ -0,0 +1,32 @@
+---
+title: "extract-untagged-content"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/extract-untagged-content/"
+---
+
+# extract-untagged-content
+
+- Type: warning
+- Kind: `input` (a problem with the PDF file)
+
+## What happened
+
+The page was read in its structure tree's order, but some of its visible text isn't in the tree and isn't marked as an artifact. Extraction kept that text and put it after the tree's blocks, in layout order.
+
+## Why
+
+In a tagged file, every piece of visible content should belong to a structure element or be marked as an artifact (ISO 32000-2 §14.8.2.2). Text that is neither has no place in the tree's order. A tool that adds text after tagging a document, such as a stamp or a page number, often leaves text like this.
+
+## How to fix
+
+Nothing to do in Lamina PDF. To give that text its place in the reading order, tag it in the file, or mark it as an artifact if it isn't content. Like every warning, it fails the call in strict mode.
+
+## Example
+
+A tagged contract with a "DRAFT" stamp drawn after tagging: the stamp's text comes after the contract's blocks.
+
+## Data fields
+
+- `chars`: how many characters (spaces left out) lie outside the tree.
+
+The `location` has the page's `pageIndex`.

package/docs/errors/fetch-failed.md

@@ -0,0 +1,34 @@
+---
+title: "fetch-failed"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/fetch-failed/"
+---
+
+# fetch-failed
+
+- Type: error
+- Kind: `io` (the host failed to supply bytes; often transient)
+
+## What happened
+
+A range source of `@laminapdf/sdk` (`httpRangeSource`) couldn't get bytes it asked for. The request failed (a network error, a CORS refusal, DNS), or the server answered with a status other than `200` or `206`, or with a `206` whose `Content-Range` (or length) doesn't match the range asked for. A `Content-Range` that the browser hides, because CORS doesn't expose it, looks the same. It is also raised when a `callbackSource`'s read returns a different number of bytes than it was asked for.
+
+## Why
+
+Opening a remote file range by range depends on the server: it must allow the `Range` request (and, across origins, expose `Content-Range`, `Content-Length` and `ETag` through CORS), and must not compress the response (`Content-Encoding` breaks byte ranges). Lamina PDF never retries on its own; the error says the bytes are not available.
+
+## How to fix
+
+Check that the URL is reachable from where the code runs and that the server sends `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers: Range` and `Access-Control-Expose-Headers: Content-Range, Content-Length, ETag`. Serve PDFs without `Content-Encoding`. Retry the call yourself if the failure was transient.
+
+## Example
+
+```js
+const doc = await Document.openRange(httpRangeSource(url)); // throws { code: "fetch-failed", data: { status: 403 } }
+```
+
+## Data fields
+
+- `reason`: `network`, `status`, `content-range` or `length` (Lamina PDF's own words). The URL is never included.
+- `status`: the HTTP status, when there was a response.
+- `expected`, `got`: for `length`, the bytes asked for and the bytes returned.

package/docs/errors/flate-truncated.md

@@ -0,0 +1,34 @@
+---
+title: "flate-truncated"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/flate-truncated/"
+---
+
+# flate-truncated
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+Flate data was truncated or had a bad checksum; the partial output was kept.
+
+## Why
+
+Truncated downloads or damaged streams.
+
+## How to fix
+
+Nothing, if the content looks right; part of the stream may be missing.
+
+## Example
+
+```text
+5 0 obj << /Filter /FlateDecode /Length 900 >> stream …(the zlib data stops early)… endstream
+```
+
+Lamina PDF keeps what inflated before the data ended or the Adler-32 checksum failed; the content may be cut short. The warning carries the stream's `object`.
+
+## Data fields
+
+None.

package/docs/errors/font-invalid.md

@@ -0,0 +1,36 @@
+---
+title: "font-invalid"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/font-invalid/"
+---
+
+# font-invalid
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A font dictionary read for text extraction has a missing, unreadable or malformed entry (the descendant font, `/Encoding` or its `/Differences`, `/Widths`, `/W`, `/W2`, the font descriptor or its font program). Its text was decoded with defaults: the standard encoding, the standard 14 font's widths or `/MissingWidth`, `/DW`.
+
+## Why
+
+A producer bug, a damaged file, or a font dictionary that relies on what a viewer guesses.
+
+## How to fix
+
+Nothing to do. Text or positions extracted for that font may be off; regenerating the file with a current producer fixes it.
+
+## Example
+
+```text
+<< /Type /Font /Subtype /Type0 /BaseFont /Foo /Encoding /Identity-H /DescendantFonts 99 0 R >>
+```
+
+The descendant font is missing, so text in this font is decoded with defaults: two-byte codes, default widths. The `location` is the font dictionary's `object`.
+
+## Data fields
+
+None.
+
+The `location` is `object`, the font dictionary's object; none for a direct font dictionary.

package/docs/errors/font-mismatch.md

@@ -0,0 +1,34 @@
+---
+title: "font-mismatch"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/font-mismatch/"
+---
+
+# font-mismatch
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`pdf_run` was given a shaped run and the key of a font other than the one the run was shaped with. Nothing was recorded in the registry.
+
+## Why
+
+Glyph IDs, advances and units per em only mean something in the font that produced them; drawing them with another font would show the wrong glyphs and wrong text.
+
+## How to fix
+
+Register every font of a layout and pass the key of the run's own font: each `LineRun::font` is an index into the font list given to `break_lines`.
+
+## Example
+
+```rust
+let run = shaper.shape(&noto, text, &options)?;
+pdf_run(&run, text, &mut registry, roboto_key)?; // font-mismatch: shaped with Noto
+```
+
+## Data fields
+
+- `font`: the registered font's PostScript name (**untrusted**: read from the font).
+- `shaped_with`: the PostScript name of the font the run was shaped with (**untrusted**: read from the font).

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

@@ -0,0 +1,34 @@
+---
+title: "font-not-embeddable"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/font-not-embeddable/"
+---
+
+# font-not-embeddable
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`FontRegistry::add` refused a font whose `OS/2.fsType` forbids embedding (restricted licence, or bitmap embedding only).
+
+## Why
+
+Font vendors mark fonts whose licence does not allow embedding in documents (OpenType `OS/2` table; research 03 §6.3). `fsType` is advisory; the licence is what counts.
+
+## How to fix
+
+Use another font, or, if your licence allows embedding, register it with `EmbedPolicy::Override`.
+
+## Example
+
+```rust
+registry.add(restricted_font, EmbedPolicy::Respect)?;  // font-not-embeddable
+registry.add(restricted_font, EmbedPolicy::Override)?; // only if your licence allows embedding
+```
+
+## Data fields
+
+- `font`: the font's PostScript name (**untrusted**: read from the font).
+- `fs_type`: the `fsType` bits.

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

@@ -0,0 +1,35 @@
+---
+title: "font-not-embedded"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/font-not-embedded/"
+---
+
+# font-not-embedded
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Text was drawn with one of the standard 14 fonts (`Builder::standard_font`) under PDF/UA-1 or a PDF/A profile. The standard 14 fonts are never embedded: viewers substitute their own.
+
+## Why
+
+The PDF/A standard for archival PDF (ISO 19005-2 §6.2.11.4.1) needs every font embedded, so the document looks the same everywhere in the future. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.21.4.1) needs it too, so viewers can render the text and map it to characters reliably. This is condition 31-009 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Load a font file with `Builder::font` (or `Builder::font_bytes` in the façade): Lamina PDF embeds the subset of glyphs you draw.
+
+## Example
+
+```rust
+let bold = builder.standard_font(Standard14::HelveticaBold)?;
+surface.text("Invoice", &bold, Pt::new(24.0), at)?;
+builder.finish()?; // font-not-embedded under Profile::PdfA2b
+```
+
+## Data fields
+
+- `profile`: the profile, such as `PDF/A-2b`.
+- `font`: the font's PostScript name, such as `Helvetica-Bold`.

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

@@ -0,0 +1,33 @@
+---
+title: "font-not-shapable"
+version: "0.2.0-alpha.3"
+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.3"
+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,35 @@
+---
+title: "glyph-without-unicode"
+version: "0.2.0-alpha.3"
+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 that stands for no text of its own, or whose text is U+0000, U+FEFF or U+FFFE. Shaping can draw one cluster (a group of characters that display as one unit) with several glyphs. The text then belongs to the first glyph, and the others stand for none.
+
+## 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. Lamina PDF maps a glyph that stands for no text to an empty value, which these profiles reject.
+
+## How to fix
+
+Check the text for control characters and byte-order marks. If shaping draws several glyphs for one cluster, choose a font that draws each cluster as one glyph. 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, so a PDF/UA-1 document needs the font change.
+
+## Example
+
+```rust
+surface.text("\u{FEFF}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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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.3"
+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).