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

package/docs/errors/sink-not-empty.md

@@ -0,0 +1,33 @@
+---
+title: "sink-not-empty"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/sink-not-empty/"
+---
+
+# sink-not-empty
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+The `WriteSink` already held bytes when the save started, so the writer refused before writing anything.
+
+## Why
+
+Output offsets (the xref table, `startxref`) count from the sink's first byte, and a sink only appends. An `AppendedOnly` incremental save also accepts a sink that holds exactly the base.
+
+## How to fix
+
+Pass an empty sink. The document is unchanged.
+
+## Example
+
+```rust
+let mut sink = b"%PDF-".to_vec();
+ops.save(&mut sink, &options)?; // sink-not-empty, data.held = 5
+```
+
+## Data fields
+
+- `held`: the bytes the sink held.

package/docs/errors/sink.md

@@ -0,0 +1,31 @@
+---
+title: "sink"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/sink/"
+---
+
+# sink
+
+- Type: error
+- Kind: `io` (the host failed to supply or take bytes)
+
+## What happened
+
+The `WriteSink` failed to take the bytes, or could not give them back. (A sink that already held bytes is [`sink-not-empty`](sink-not-empty.md).)
+
+## Why
+
+The destination failed: a full disk, a closed upload, a refused read-back.
+
+## How to fix
+
+Check the destination and retry the save. The document is unchanged; the sink may hold a prefix of the output.
+
+## Example
+
+An upload sink whose connection closed halfway through: the save fails with `sink`, the document is unchanged, and `data.kind` is the I/O error kind (`BrokenPipe`).
+
+## Data fields
+
+- `kind`: the I/O error kind, for a writer that failed.
+- `message`: the sink's or writer's own text (**untrusted**: it comes from the host and may name a path; never in the message).

package/docs/errors/source-budget-exceeded.md

@@ -0,0 +1,34 @@
+---
+title: "source-budget-exceeded"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/source-budget-exceeded/"
+---
+
+# source-budget-exceeded
+
+- Type: error
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+A sparse source (`WasmSparseSource` in `@laminapdf/wasm`, or a `@laminapdf/sdk` range document) was handed bytes that would make it hold more than the byte budget it was created with. The bytes were not added.
+
+## Why
+
+A range source keeps every byte it has fetched: the document may already have read them, so nothing is evicted. The budget bounds how much of a remote or lazily read file one document may hold in memory.
+
+## How to fix
+
+Create the source with a larger budget, or fetch less per round: smaller blocks and no readahead. A file that must be read whole (a full rewrite, or a repaired file with no usable xref) needs a budget of at least its size.
+
+## Example
+
+```js
+const source = new WasmSparseSource(10_000_000, 1_000_000);
+source.supply(0, new Uint8Array(2_000_000)); // throws { code: "source-budget-exceeded", … }
+```
+
+## Data fields
+
+- `argument`: `bytes`.
+- `detail`: how many bytes the source would hold and its budget (Lamina PDF's own numbers).

package/docs/errors/source-changed.md

@@ -0,0 +1,33 @@
+---
+title: "source-changed"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/source-changed/"
+---
+
+# source-changed
+
+- Type: error
+- Kind: `io` (the host failed to supply bytes; often transient)
+
+## What happened
+
+A remote file changed while `@laminapdf/sdk` was reading it range by range: a response's `ETag` or total length differs from the first one (or the server ignored `If-Range` and sent a different file).
+
+## Why
+
+A range document is assembled from many responses. If the file changed between them, the parts no longer belong to one file, and the document would read a mix of two versions. `httpRangeSource` sends `If-Range` with the first `ETag` and compares each response's `ETag` and `Content-Range` length with the first.
+
+## How to fix
+
+Open the file again (a new source, a new document). If the file changes often, download it whole with `Document.open(bytes)` instead.
+
+## Example
+
+```js
+const doc = await Document.openRange(httpRangeSource(url));
+await doc.ensure(() => doc.pages); // throws { code: "source-changed", … } if the file was replaced meanwhile
+```
+
+## Data fields
+
+None.

package/docs/errors/source.md

@@ -0,0 +1,30 @@
+---
+title: "source"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/source/"
+---
+
+# source
+
+- Type: error
+- Kind: `io` (the host failed to supply bytes; often transient)
+
+## What happened
+
+The `ByteSource` failed to read.
+
+## Why
+
+A file-system or network error in the host.
+
+## How to fix
+
+Retry, or check the source.
+
+## Example
+
+A `ByteSource` reading from a network answered with an error for bytes 4096..+65536; the call fails with `source` and the same call can be retried once the connection is back.
+
+## Data fields
+
+None.

package/docs/errors/stale-generation.md

@@ -0,0 +1,34 @@
+---
+title: "stale-generation"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/stale-generation/"
+---
+
+# stale-generation
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A reference's generation number did not match its xref entry, so it resolved to `null` (ISO 32000-2 §7.3.10).
+
+## Why
+
+An editor deleted and reused an object number (bumping its generation) but left a reference with the old generation behind.
+
+## How to fix
+
+Nothing; the reference is treated as missing.
+
+## Example
+
+```text
+/Contents 7 1 R      % but the xref entry for object 7 has generation 0
+```
+
+The reference resolves to `null` (ISO 32000-2 §7.3.10), as if object 7 were missing, and the warning carries `generation` 1.
+
+## Data fields
+
+`generation`.

package/docs/errors/stream-length-recovered.md

@@ -0,0 +1,37 @@
+---
+title: "stream-length-recovered"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/stream-length-recovered/"
+---
+
+# stream-length-recovered
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A stream's `/Length` was wrong or unresolvable; its end was found by scanning for `endstream`.
+
+## Why
+
+Writers that edit streams without updating `/Length`.
+
+## How to fix
+
+Nothing; re-saving writes the correct length.
+
+## Example
+
+```text
+4 0 obj << /Length 10 >>
+stream
+BT /F1 12 Tf 72 720 Td (Hello) Tj ET
+endstream
+```
+
+`/Length` says 10 bytes but the data is longer. Lamina PDF finds `endstream`, uses the real length and raises the warning with the stream's `object`.
+
+## Data fields
+
+None.

package/docs/errors/strict.md

@@ -0,0 +1,34 @@
+---
+title: "strict"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/strict/"
+---
+
+# strict
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+Strict mode refused something the tolerant reader would have repaired.
+
+## Why
+
+The file needs repair; see the warning code in the data.
+
+## How to fix
+
+Open without strict mode, or fix the file.
+
+## Example
+
+```rust
+let options = OpenOptions::new().with_strict(true);
+let err = Document::open_bytes(bytes_with_a_broken_xref, options).unwrap_err();
+// { "code": "strict", "data": { "warning": "xref-repaired" }, … }
+```
+
+## Data fields
+
+`warning` (the warning code).

package/docs/errors/subset-failed.md

@@ -0,0 +1,31 @@
+---
+title: "subset-failed"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/subset-failed/"
+---
+
+# subset-failed
+
+- Type: error
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+Subsetting a font at `FontRegistry::finish_fonts` failed.
+
+## Why
+
+The `subsetter` crate could not rebuild the font program: a font feature it does not support, or a table it could not parse.
+
+## How to fix
+
+Try another version or format of the font (for example TrueType instead of CFF), and report the font if it is a common one.
+
+## Example
+
+A font whose tables `subsetter` can't rebuild makes `FontRegistry::finish_fonts` (and so `Builder::finish`) fail with `subset-failed`; `data.font` is the font's PostScript name.
+
+## Data fields
+
+- `font`: the font's PostScript name (**untrusted**: read from the font).
+- `reason`: the subsetter's failure class (fixed text).

package/docs/errors/syntax.md

@@ -0,0 +1,34 @@
+---
+title: "syntax"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/syntax/"
+---
+
+# syntax
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A token or structure did not match the PDF grammar.
+
+## Why
+
+Malformed input.
+
+## How to fix
+
+Use another copy of the file.
+
+## Example
+
+```text
+1 0 obj << /Type /Catalog /Pages 2 0 R >> >> endobj
+```
+
+A stray `>>` where an object should end: parsing that object fails with `syntax` at its offset.
+
+## Data fields
+
+None. The `location` is a file `offset`, or `object` with `streamOffset` inside an object stream.

package/docs/errors/text-module-not-loaded.md

@@ -0,0 +1,36 @@
+---
+title: "text-module-not-loaded"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/text-module-not-loaded/"
+---
+
+# text-module-not-loaded
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+A font or text method (`Font` use, `surface.text`, `surface.textBox`, `builder.font`) was called on a `Builder` created while only the base WebAssembly module was loaded, or `new Builder({ text: true })` was called before the text module was loaded.
+
+## Why
+
+`@laminapdf/sdk` ships two modules: the base module (open, edit, save, vector and image pages) and the larger text module (all of the base plus fonts, shaping and text layout). A document that draws text is built entirely in the text module, and loading it is asynchronous, so it can't happen inside a synchronous drawing call. A builder created without the text module can't gain it later.
+
+## How to fix
+
+Load the text module before creating the builder that draws text: `await init({ text: true })`, or `await loadText()` after `init()`. Builders created after that use the text module.
+
+## Example
+
+```js
+await init();
+const b = new Builder();
+b.page("A4").surface().text("Hi", { font: Font.standard("Helvetica"), size: 12, at: [72, 72] });
+// throws { code: "text-module-not-loaded", … }
+await loadText(); // then create a new Builder
+```
+
+## Data fields
+
+None.

package/docs/errors/text-overflow.md

@@ -0,0 +1,34 @@
+---
+title: "text-overflow"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/text-overflow/"
+---
+
+# text-overflow
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Surface::text_box` laid its text out and not every line fit the box (its height, or a single grapheme cluster wider than the box), and its `TextBoxOptions` asked for `Overflow::Error`. Nothing was drawn.
+
+## Why
+
+A text box draws only lines that fit inside it. With `Overflow::Error` the caller asked to be told instead of having the text cut off.
+
+## How to fix
+
+Make the box taller or wider, the font smaller or the text shorter; or use `Overflow::Clip` (the default), which draws the lines that fit and reports where the rest starts in `TextLayout::overflow`.
+
+## Example
+
+```rust
+let options = TextBoxOptions::default().with_overflow(Overflow::Error);
+surface.text_box(long_text, &font, Pt::new(12.0), small_rect, &options)?; // text-overflow
+```
+
+## Data fields
+
+- `fits`: the number of lines that fit.
+- `needed`: the number of lines the text needs.

package/docs/errors/tounicode-conflict.md

@@ -0,0 +1,32 @@
+---
+title: "tounicode-conflict"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/tounicode-conflict/"
+---
+
+# tounicode-conflict
+
+- Type: warning
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+One glyph was used for two different texts; the ToUnicode CMap maps it to the first.
+
+## Why
+
+A ToUnicode CMap maps each code to one string (ISO 32000-2 §9.10.3), for example when one space glyph stands for both U+0020 and U+00A0.
+
+## How to fix
+
+Mark the second occurrence with `/ActualText` (§14.9.4) so extraction gets its text; Lamina PDF's builder does this for you.
+
+## Example
+
+A CFF font in which one space glyph is used for both U+0020 and U+00A0: the ToUnicode CMap maps it to U+0020 (the first use), and the warning names the glyph (`gid`) and the second text.
+
+## Data fields
+
+- `font`: the font's PostScript name (**untrusted**: read from the font).
+- `gid`: the glyph, in the original font's numbering.
+- `kept`, `dropped`: the two texts (**untrusted**: caller text).

package/docs/errors/type.md

@@ -0,0 +1,34 @@
+---
+title: "type"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/type/"
+---
+
+# type
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An object had a different type than the structure requires.
+
+## Why
+
+Malformed input: an object of the wrong type where the structure requires a specific one.
+
+## How to fix
+
+Use another copy of the file.
+
+## Example
+
+```text
+2 0 obj << /Type /Pages /Kids 5 >>
+```
+
+`/Kids` must be an array; reading the page tree fails with `type`, and `data` names what was expected and where (`expected`, `context`, from Lamina PDF's own vocabulary).
+
+## Data fields
+
+`expected`, `context` (from Lamina PDF's fixed list).

package/docs/errors/unexpected-eof.md

@@ -0,0 +1,34 @@
+---
+title: "unexpected-eof"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unexpected-eof/"
+---
+
+# unexpected-eof
+
+- Type: error
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+The input ended before a complete token or object was read.
+
+## Why
+
+Truncated files.
+
+## How to fix
+
+Use a complete copy of the file.
+
+## Example
+
+```text
+1 0 obj << /Type /Catalog /Pages 2 0 R
+```
+
+The file ends inside a dictionary; the `location` is the file offset where reading stopped.
+
+## Data fields
+
+None. The `location` is a file `offset`, or `object` with `streamOffset` inside an object stream.

package/docs/errors/unknown-axis.md

@@ -0,0 +1,33 @@
+---
+title: "unknown-axis"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unknown-axis/"
+---
+
+# unknown-axis
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Font::instance` was given a variation axis the font does not have.
+
+## Why
+
+A static font has no axes; a variable font has the axes listed in `FontInfo::axes` (`fvar`).
+
+## How to fix
+
+Check `font.info().axes` before choosing coordinates, or use a variable font.
+
+## Example
+
+```rust
+let bold = static_font.instance(&[(OpenTypeTag::WEIGHT, 700.0)])?; // unknown-axis: no wght axis
+```
+
+## Data fields
+
+- `font`: the font's PostScript name (**untrusted**: read from the font).
+- `tag`: the axis tag that was asked for.

package/docs/errors/unknown-code.md

@@ -0,0 +1,36 @@
+---
+title: "unknown-code"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unknown-code/"
+---
+
+# unknown-code
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`laminapdf explain` was given a code that isn't one of Lamina PDF's error or warning codes.
+
+## Why
+
+Every code Lamina PDF reports is listed once, with its own page. A code that isn't listed has no explanation to print.
+
+## How to fix
+
+Check the spelling: `didYouMean` lists the known codes closest to the one given. The tables in this folder's README list every code.
+
+## Example
+
+```console
+$ laminapdf explain xref-repaird
+error[unknown-code]: not a Lamina PDF code
+  = did you mean: xref-repaired
+$ echo $?
+2
+```
+
+## Data fields
+
+- `code`: the code given (untrusted: caller text, never in the message).

package/docs/errors/unknown-destination.md

@@ -0,0 +1,33 @@
+---
+title: "unknown-destination"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unknown-destination/"
+---
+
+# unknown-destination
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A link or outline item of a new document targets `LinkTarget::Named(name)`, but `Builder::destination` never defined that name.
+
+## Why
+
+A named destination is looked up in the document's `/Names /Dests` tree (ISO 32000-2 §12.3.2.4); a name that isn't there goes nowhere in every viewer.
+
+## How to fix
+
+Define the name with `Builder::destination(name, page_index, fit)` before `Builder::finish`, or link to the page directly with `LinkTarget::Page`.
+
+## Example
+
+```rust
+surface.link(rect, LinkTarget::Named("appendix".into()), None);
+builder.finish()?; // unknown-destination: call builder.destination("appendix", …) first
+```
+
+## Data fields
+
+- `name`: the name as given (untrusted: caller text, never in the message).

package/docs/errors/unknown-font.md

@@ -0,0 +1,33 @@
+---
+title: "unknown-font"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unknown-font/"
+---
+
+# unknown-font
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A `FontKey` was used with a `FontRegistry` that did not hand it out.
+
+## Why
+
+Keys are indices into one registry; each document has its own.
+
+## How to fix
+
+Use the key returned by this registry's `add`.
+
+## Example
+
+```rust
+let key = registry_a.add(font, EmbedPolicy::Respect)?;
+registry_b.encode(key, "Hi")?; // unknown-font: key came from registry_a
+```
+
+## Data fields
+
+- `key`: the key's index.

package/docs/errors/unknown-option.md

@@ -0,0 +1,33 @@
+---
+title: "unknown-option"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unknown-option/"
+---
+
+# unknown-option
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+An options record passed to `@laminapdf/wasm` (`OpenOptionsInit`, `SaveOptionsInit`, `BuildOptionsInit`, …) has a key Lamina PDF doesn't know.
+
+## Why
+
+Records refuse unknown keys instead of ignoring them, so a misspelt option fails loudly rather than silently doing nothing.
+
+## How to fix
+
+Remove the key or correct its spelling. `didYouMean` lists the known keys within two edits of it.
+
+## Example
+
+```js
+WasmDocument.openBytes(bytes, { pasword: "secret" }); // throws { code: "unknown-option", didYouMean: ["password"], … }
+```
+
+## Data fields
+
+- `argument`: the parameter whose record had the key (`options`, `metadata`, …).
+- `option`: the key given (untrusted: caller text, never in the message).