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

package/docs/errors/unknown-page.md

@@ -0,0 +1,34 @@
+---
+title: "unknown-page"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unknown-page/"
+---
+
+# unknown-page
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+An op names a page the document doesn't have.
+
+## Why
+
+The page ID is stale or from another document.
+
+## How to fix
+
+Use a `PageId` from this document.
+
+## Example
+
+```rust
+let other = Document::open_bytes(other_bytes, OpenOptions::new())?;
+let id = other.page_info(0)?.id;
+doc.apply(vec![Op::from(RotatePage::new(id, Rotation::Clockwise90))]); // unknown-page
+```
+
+## Data fields
+
+None.

package/docs/errors/unmapped-glyph.md

@@ -0,0 +1,36 @@
+---
+title: "unmapped-glyph"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unmapped-glyph/"
+---
+
+# unmapped-glyph
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A font showed glyphs that its ToUnicode CMap, its encoding's glyph names and its font program's `cmap` all leave unmapped. They extract as U+FFFD; `PageText::unmapped` counts them.
+
+## Why
+
+The file has no ToUnicode CMap for a subset or symbolic font, uses arbitrary glyph names (`g37`), or obfuscates its encoding (ISO 32000-2 §9.10.2: there is then no way to know what the glyph means).
+
+## How to fix
+
+Nothing to do in Lamina PDF. A producer that writes ToUnicode CMaps (Lamina PDF does) avoids it; OCR is the only way to recover such text.
+
+## Example
+
+```text
+<< /Subtype /Type0 /BaseFont /ABCDEF+Subset /Encoding /Identity-H >>   % no /ToUnicode
+```
+
+A subset font with Identity-H and no ToUnicode: unless its embedded `cmap` maps the glyphs, they extract as U+FFFD and the warning carries the font's `object`.
+
+## Data fields
+
+None.
+
+The `location` is `object`, the font dictionary's object; none for a direct font dictionary.

package/docs/errors/unnumbered-heading-misused.md

@@ -0,0 +1,34 @@
+---
+title: "unnumbered-heading-misused"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unnumbered-heading-misused/"
+---
+
+# unnumbered-heading-misused
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/UA-1, the document misuses the unnumbered heading `H`, a heading whose level comes from the section it sits in. Numbered headings are `H1`, `H2` and so on. Either two `H` elements share one parent, or the document uses `H` and numbered headings together.
+
+## Why
+
+A screen reader works out an `H` heading's level from the sections around it. A section therefore has one `H` at most, and a document that mixes the two kinds gives no consistent outline. The PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.4.4) requires one `H` per section and only one kind of heading per document. These are conditions 14-006 and 14-007 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Use numbered headings (`TagKind::H1` to `TagKind::H6`) throughout; most documents need nothing else. If you use `H` (`Tag::custom("H", …)`), give each section (`Sect`) its own and leave the numbered ones out.
+
+## Example
+
+```rust
+s.text("Results", &font, Pt::new(18.0), at)?.tag(TagKind::H1);
+s.text("Method", &font, Pt::new(14.0), at2)?.tag(Tag::custom("H", TagKind::H2));
+builder.finish()?; // unnumbered-heading-misused: use TagKind::H2 for the second heading
+```
+
+## Data fields
+
+- `page`: the page's index (0-based).

package/docs/errors/unset-object.md

@@ -0,0 +1,30 @@
+---
+title: "unset-object"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unset-object/"
+---
+
+# unset-object
+
+- Type: error
+- Kind: `internal` (a bug in Lamina PDF or a broken invariant)
+
+## What happened
+
+A writer object number was reserved but never given a value.
+
+## Why
+
+A bug in Lamina PDF.
+
+## How to fix
+
+Report it at https://github.com/laudebugs/laminapdf/issues with the steps (and, if you can share it, the file) that led to it.
+
+## Example
+
+Raised by a writer when an object number reserved during a save never received its object. No input should cause it.
+
+## Data fields
+
+None.

package/docs/errors/unsupported-filter.md

@@ -0,0 +1,34 @@
+---
+title: "unsupported-filter"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unsupported-filter/"
+---
+
+# unsupported-filter
+
+- Type: error
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+A stream uses a filter Lamina PDF doesn't implement; only decoding that stream fails.
+
+## Why
+
+Rare or proprietary filters.
+
+## How to fix
+
+Use a tool that supports the filter.
+
+## Example
+
+```text
+5 0 obj << /Filter /JBIG2Decode /Length 2048 >> stream …
+```
+
+Decoding this stream fails; the rest of the document reads normally. `data.filter` is the filter's name as read from the file.
+
+## Data fields
+
+`filter` (**untrusted**: read from the file). The message never includes it.

package/docs/errors/unsupported-image.md

@@ -0,0 +1,33 @@
+---
+title: "unsupported-image"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unsupported-image/"
+---
+
+# unsupported-image
+
+- Type: error
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+The image is valid but uses a feature the builder can't embed.
+
+## Why
+
+PDF's `DCTDecode` filter (ISO 32000-2 §7.4.8) takes baseline and progressive JPEG with 8-bit samples; lossless, hierarchical and arithmetic-coded JPEG and 12-bit samples are refused, as are JPEGs with 2 or more than 4 components.
+
+## How to fix
+
+Re-encode the image as a baseline or progressive 8-bit JPEG, or as PNG.
+
+## Example
+
+```rust
+let img = Image::jpeg(lossless_jpeg_bytes)?; // unsupported-image: data.feature says which
+```
+
+## Data fields
+
+- `format`: the image's format.
+- `feature`: the feature that is not supported (fixed text).

package/docs/errors/unsupported-layout-option.md

@@ -0,0 +1,33 @@
+---
+title: "unsupported-layout-option"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unsupported-layout-option/"
+---
+
+# unsupported-layout-option
+
+- Type: error
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+`break_lines` was given a layout option Lamina PDF does not implement yet: `LayoutOptions::justify` set to `true`.
+
+## Why
+
+Justification (stretching inter-word gaps, kashida) is reserved for a later plan (research 03 §7.6); silently ignoring the option would lay out ragged lines the caller did not ask for.
+
+## How to fix
+
+Leave `justify` at `false` and pick an `Alignment` (start, end, left, right or centre).
+
+## Example
+
+```rust
+let options = LayoutOptions { justify: true, ..LayoutOptions::new(300.0, 12.0) };
+break_lines(&shaper, &fonts, text, &options)?; // unsupported-layout-option
+```
+
+## Data fields
+
+- `option`: the option's name (fixed text).

package/docs/errors/unsupported-security-handler.md

@@ -0,0 +1,34 @@
+---
+title: "unsupported-security-handler"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unsupported-security-handler/"
+---
+
+# unsupported-security-handler
+
+- Type: error
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+The document uses a security handler Lamina PDF can't decrypt.
+
+## Why
+
+Not `/Standard`, an unknown `/V`/`/R`, or an unknown crypt filter method.
+
+## How to fix
+
+Use a tool that supports the handler.
+
+## Example
+
+```text
+trailer << /Encrypt << /Filter /Adobe.PubSec /SubFilter /adbe.pkcs7.s5 … >> >>
+```
+
+A public-key (certificate) handler: Lamina PDF implements only `/Standard`, so `open` fails. `data.filter` holds the handler's name as read from the file.
+
+## Data fields
+
+`filter` (**untrusted**: read from the file; the message never includes it), `version`, `revision`.

package/docs/errors/unsupported-version.md

@@ -0,0 +1,32 @@
+---
+title: "unsupported-version"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/unsupported-version/"
+---
+
+# unsupported-version
+
+- Type: error
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+An op log has a schema version this reader doesn't know.
+
+## Why
+
+A newer Lamina PDF wrote it.
+
+## How to fix
+
+Upgrade Lamina PDF.
+
+## Example
+
+```rust
+doc.apply_log(r#"{ "v": 9, "ops": [] }"#)?; // unsupported-version, data.version = 9
+```
+
+## Data fields
+
+`version`.

package/docs/errors/untagged-content.md

@@ -0,0 +1,35 @@
+---
+title: "untagged-content"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/untagged-content/"
+---
+
+# untagged-content
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+Under PDF/UA-1, something was drawn outside every structure element and artifact: a path, an image or text that is neither part of the document's structure nor marked as decoration.
+
+## Why
+
+Assistive technology reads a tagged document through its structure tree, and skips content outside it or reads it out of order. For this reason, the PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.1) requires every piece of content to be tagged or marked as an artifact. This is condition 01-005 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
+
+## How to fix
+
+Draw real content inside `Surface::tag` (or give a text run `TextRun::tag`) and decoration, such as rules, backgrounds and page numbers, inside `Surface::artifact`. `Builder::tagging_diagnostics` lists what is still untagged on each page.
+
+## Example
+
+```rust
+surface.path(|p| { p.rect(rule); }).fill(FillRule::NonZero);
+builder.finish()?; // untagged-content: wrap it in surface.artifact(ArtifactKind::Layout, …)
+```
+
+## Data fields
+
+- `page`: the page's index (0-based).
+- `content`: what was drawn: `path`, `image` or `text`.
+- `count`: how many drawings of that kind.

package/docs/errors/warnings-truncated.md

@@ -0,0 +1,35 @@
+---
+title: "warnings-truncated"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/warnings-truncated/"
+---
+
+# warnings-truncated
+
+- Type: warning
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+More than `Limits::max_warnings` warnings were raised; the rest were dropped.
+
+## Why
+
+A badly damaged or hostile file.
+
+## How to fix
+
+Raise `max_warnings` if you need the full list.
+
+## Example
+
+A damaged file raising 50,000 repairs with the default `max_warnings`: the first warnings are kept, then one `warnings-truncated`, and the rest are dropped.
+
+```rust
+let limits = laminapdf::Limits::default().with_max_warnings(100_000);
+let doc = laminapdf::Document::open_bytes(bytes, laminapdf::OpenOptions::new().with_limits(limits))?;
+```
+
+## Data fields
+
+None.

package/docs/errors/wasm-trap.md

@@ -0,0 +1,37 @@
+---
+title: "wasm-trap"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/wasm-trap/"
+---
+
+# wasm-trap
+
+- Type: error
+- Kind: `internal` (a bug in Lamina PDF or a broken invariant)
+
+## What happened
+
+The WebAssembly module trapped during the call: Lamina PDF hit a bug and stopped. `@laminapdf/sdk` discarded the module's instance, so the next call runs in a fresh one. Every document, page and builder from the old instance now throws `instance-reset`.
+
+## Why
+
+A trap stops the module in the middle of its work, so its memory may hold half-written state. Nothing in that instance can be trusted afterwards. A fresh instance keeps one failed call from breaking every call after it.
+
+## How to fix
+
+Open the document again from its bytes and retry. If the same call on the same file traps again, report it with the file: a trap is always a bug in Lamina PDF.
+
+## Example
+
+```ts
+try {
+  lines = doc.page(0).text().lines;
+} catch (e) {
+  if (!isLaminaPdfError(e, "wasm-trap")) throw e;
+  doc = Document.open(bytes); // the old document throws instance-reset from now on
+}
+```
+
+## Data fields
+
+- `module`: the module that trapped: `base`, `text` or `extract`.

package/docs/errors/whole-font-rebuilt.md

@@ -0,0 +1,30 @@
+---
+title: "whole-font-rebuilt"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/whole-font-rebuilt/"
+---
+
+# whole-font-rebuilt
+
+- Type: warning
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A font whose `OS/2.fsType` forbids subsetting was embedded with every glyph, but rebuilt rather than byte for byte.
+
+## Why
+
+It is a variable-font instance or has CFF2 outlines; PDF can embed neither as it is, so `subsetter` instanced it (or converted CFF2 to TrueType outlines) while keeping every glyph. Its `cmap` and layout tables are dropped.
+
+## How to fix
+
+Check the font's licence allows this, or use a static TrueType/CFF version of the font.
+
+## Example
+
+Registering a variable font instance (`font.instance(&[(OpenTypeTag::WEIGHT, 700.0)])`) whose `fsType` forbids subsetting: the font is embedded with every glyph, but instanced, so not byte for byte.
+
+## Data fields
+
+- `font`: the font's PostScript name (**untrusted**: read from the font).

package/docs/errors/worker-crashed.md

@@ -0,0 +1,33 @@
+---
+title: "worker-crashed"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/worker-crashed/"
+---
+
+# worker-crashed
+
+- Type: error
+- Kind: `internal` (a bug or an environment failure, not the caller's input)
+
+## What happened
+
+The Web Worker running `@laminapdf/sdk` (from `@laminapdf/sdk/worker`) stopped: an uncaught error, a WebAssembly trap or the browser killing it (out of memory). Every call still in flight was rejected with this code, and the client emitted a `crashed` event.
+
+## Why
+
+A long synchronous call can keep the Web Worker busy without answering, so Lamina PDF has no heartbeat and never treats silence as a crash. Only the Web Worker's `error` or `messageerror` event, or a trap it reports, counts as a crash.
+
+## How to fix
+
+Call `client.restart()`, then open the document again: handles from the old Web Worker are gone. An encrypted document needs its password again. If one file keeps crashing the Web Worker, report it.
+
+## Example
+
+```ts
+client.on("crashed", () => client.restart());
+await doc.save(); // rejects with LaminaPdfError { code: "worker-crashed", … } if the Web Worker died
+```
+
+## Data fields
+
+- `reason`: what ended the Web Worker: `error`, `messageerror` or `trap` (a crash, which emits `crashed`), or `terminated` (`client.terminate()`, `restart()`, or a call made when no Web Worker runs).

package/docs/errors/worker-failed.md

@@ -0,0 +1,32 @@
+---
+title: "worker-failed"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/worker-failed/"
+---
+
+# worker-failed
+
+- Type: error
+- Kind: `internal` (a bug or an environment failure, not the caller's input)
+
+## What happened
+
+A call through `@laminapdf/sdk/worker` failed inside the Web Worker with an error that isn't a `LaminaPdfError`. The call was rejected with this code and the error's message; the Web Worker and its documents keep working.
+
+## Why
+
+The Web Worker passes Lamina PDF's own errors through unchanged and rejects caller mistakes it can detect (an unknown method, a parameter it can't receive) with `invalid-argument`. Anything else is a failure of Lamina PDF's client code, such as a result it couldn't send back or a bug in its code.
+
+## How to fix
+
+Report it, with the call you made and the message. The same call through the sync API on the main thread is a workaround while it is fixed.
+
+## Example
+
+```ts
+await doc.pageCount(); // rejects with LaminaPdfError { code: "worker-failed", kind: "internal", … } on a bug in Lamina PDF's client
+```
+
+## Data fields
+
+None.

package/docs/errors/worker-version-mismatch.md

@@ -0,0 +1,34 @@
+---
+title: "worker-version-mismatch"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/worker-version-mismatch/"
+---
+
+# worker-version-mismatch
+
+- Type: error
+- Kind: `usage` (the caller did something the API doesn't allow)
+
+## What happened
+
+`connect()` from `@laminapdf/sdk/worker` started a Web Worker, and its handshake named a different protocol or package version than the client. The client rejected `connect()` and sent nothing else.
+
+## Why
+
+The client and the Web Worker exchange messages whose shape belongs to one build. A Web Worker from another version (an older deploy, a CDN copy, a separately bundled copy) could misread them, so the handshake fails loudly instead. PDF.js learned the same lesson.
+
+## How to fix
+
+Let the bundler serve the Web Worker from the same `@laminapdf/sdk` package as the page: `connect()` contains the literal `new Worker(new URL(…, import.meta.url))` that Vite and webpack follow. If you pass `{ worker }` yourself, build it from the same package version.
+
+## Example
+
+```ts
+const client = await connect({ worker: new Worker("/old/lamina-worker.js", { type: "module" }) });
+// rejects: LaminaPdfError { code: "worker-version-mismatch", … }
+```
+
+## Data fields
+
+- `expected`: the client's `{ protocol, version }`.
+- `actual`: what the Web Worker answered.

package/docs/errors/would-invalidate-signatures.md

@@ -0,0 +1,38 @@
+---
+title: "would-invalidate-signatures"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/would-invalidate-signatures/"
+---
+
+# would-invalidate-signatures
+
+- Type: error (`laminapdf_save::SaveError::WouldInvalidateSignatures`)
+- Kind: `security` (signatures block the call)
+
+## What happened
+
+The save planner refused a save because it would break one or more signatures. Either it was a full rewrite of a signed document, or its pending changes or rewrite reasons conflict with the document's signatures: a DocMDP, FieldMDP or usage-rights restriction, or a repaired or encrypted base. Nothing was written.
+
+## Why
+
+A signature covers the bytes of the file as it was signed (ISO 32000-2 §12.8). A full rewrite moves those bytes, and a change a certification forbids invalidates it even when appended. Lamina PDF never breaks a signature without an explicit override.
+
+## How to fix
+
+Save with `SaveMode::Auto` or `SaveMode::Incremental` when the constraint allows it. Otherwise ask the user, naming the signatures in the error, and save again with `SaveOptions::with_invalidate_signatures(true)`: the invalidated signatures' values and `/Perms` entries are removed and `SaveReport::invalidated` lists them.
+
+## Example
+
+```rust
+let err = doc.save(&mut out, &SaveOptions::new().with_mode(SaveMode::FullRewrite)).unwrap_err();
+assert_eq!(err.code(), "would-invalidate-signatures");
+```
+
+## Data fields
+
+- `signatures`: every signature, as `{ field, kind, value, revision, covers }` (field ID, kind, signature dictionary as `num gen`, revision, covered length).
+- `rewrite_reasons`: why only a full rewrite is safe, if anything says so.
+- `violations`: pending changes a signature's restriction forbids, as `{ class, restriction, signature }`.
+- `signatures_unknown`: part of the form couldn't be followed, so there may be signatures beyond `signatures`.
+
+None of them hold document text.

package/docs/errors/wrong-document.md

@@ -0,0 +1,33 @@
+---
+title: "wrong-document"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/wrong-document/"
+---
+
+# wrong-document
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`FontRegistry::finish_fonts` was given a document in which a font's reserved object is not a free number reserved in that document.
+
+## Why
+
+A `FontRegistry` belongs to one document: `reference` reserves numbers in the document it is given, and `finish_fonts` fills those numbers. Finishing into another document would overwrite its objects, so nothing is written.
+
+## How to fix
+
+Use one `FontRegistry` per document, and pass `finish_fonts` the document its `reference` calls used.
+
+## Example
+
+```rust
+let id = registry.reference(key, &doc_a)?;
+registry.finish_fonts(&mut doc_b.edit())?; // wrong-document: the fonts were reserved in doc_a
+```
+
+## Data fields
+
+- `object`: the reserved object number.

package/docs/errors/wrong-password.md

@@ -0,0 +1,34 @@
+---
+title: "wrong-password"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/wrong-password/"
+---
+
+# wrong-password
+
+- Type: error
+- Kind: `security` (encryption, permissions or signatures block the call, or look tampered with)
+
+## What happened
+
+The given password is neither the user nor the owner password.
+
+## Why
+
+The password is neither the user nor the owner password. Lamina PDF tries it as both (owner first for R5/R6), and in TS also its NFKC form.
+
+## How to fix
+
+Ask for the password again. Passwords are case-sensitive.
+
+## Example
+
+```ts
+Document.open(bytes, { password: "nope" });
+// LaminaPdfError { code: "wrong-password", kind: "security",
+//   hint: "ask for the password again and retry with the correct one", … }
+```
+
+## Data fields
+
+None.