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

package/docs/api/variables/Matrix.md

@@ -0,0 +1,99 @@
+---
+version: "0.2.0-alpha.3"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / Matrix
+
+# Variable: Matrix
+
+> `const` **Matrix**: `object`
+
+Building transformation matrices.
+
+## Type Declaration
+
+### identity
+
+> `readonly` **identity**: [`Transform`](../type-aliases/Transform.md)
+
+The identity.
+
+### after()
+
+> `readonly` **after**(`outer`, `inner`): [`Transform`](../type-aliases/Transform.md)
+
+`outer` applied after `inner`: maps p to outer(inner(p)).
+
+#### Parameters
+
+##### outer
+
+[`Transform`](../type-aliases/Transform.md)
+
+##### inner
+
+[`Transform`](../type-aliases/Transform.md)
+
+#### Returns
+
+[`Transform`](../type-aliases/Transform.md)
+
+### rotate()
+
+> `readonly` **rotate**(`degrees`): [`Transform`](../type-aliases/Transform.md)
+
+A rotation by `degrees` about the origin, clockwise as displayed.
+
+#### Parameters
+
+##### degrees
+
+`number`
+
+#### Returns
+
+[`Transform`](../type-aliases/Transform.md)
+
+### scale()
+
+> `readonly` **scale**(`sx`, `sy`): [`Transform`](../type-aliases/Transform.md)
+
+A scaling by `sx` horizontally and `sy` vertically.
+
+#### Parameters
+
+##### sx
+
+`number`
+
+##### sy
+
+`number`
+
+#### Returns
+
+[`Transform`](../type-aliases/Transform.md)
+
+### translate()
+
+> `readonly` **translate**(`x`, `y`): [`Transform`](../type-aliases/Transform.md)
+
+A translation by (x, y) points.
+
+#### Parameters
+
+##### x
+
+`number`
+
+##### y
+
+`number`
+
+#### Returns
+
+[`Transform`](../type-aliases/Transform.md)

package/docs/api/variables/PAGE_SIZES.md

@@ -0,0 +1,15 @@
+---
+version: "0.2.0-alpha.3"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / PAGE\_SIZES
+
+# Variable: PAGE\_SIZES
+
+> `const` **PAGE\_SIZES**: `Readonly`\<`Record`\<[`PageSizeName`](../type-aliases/PageSizeName.md), readonly \[`width`: `number`, `height`: `number`\]\>\>
+
+Each named size in points, width × height.

package/docs/api/variables/TAG_NAMES.md

@@ -0,0 +1,15 @@
+---
+version: "0.2.0-alpha.3"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / TAG\_NAMES
+
+# Variable: TAG\_NAMES
+
+> `const` **TAG\_NAMES**: readonly \[`"Document"`, `"Part"`, `"Sect"`, `"H1"`, `"H2"`, `"H3"`, `"H4"`, `"H5"`, `"H6"`, `"P"`, `"L"`, `"LI"`, `"Lbl"`, `"LBody"`, `"Table"`, `"TR"`, `"TH"`, `"TD"`, `"Figure"`, `"Caption"`, `"Link"`, `"Span"`, `"Quote"`, `"Note"`, `"Code"`\]
+
+Every TagName, as the WASM module names it.

package/docs/errors/README.md

@@ -0,0 +1,156 @@
+---
+title: "Error and warning codes"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/"
+---
+
+# Error and warning codes
+
+- [`aes-padding-invalid`](aes-padding-invalid.md)
+- [`already-initialized`](already-initialized.md)
+- [`binary-output-to-terminal`](binary-output-to-terminal.md)
+- [`builder-finished`](builder-finished.md)
+- [`cancelled`](cancelled.md)
+- [`cmap-invalid`](cmap-invalid.md)
+- [`collection-index`](collection-index.md)
+- [`color-components`](color-components.md)
+- [`content-bad-operands`](content-bad-operands.md)
+- [`content-path-unpainted`](content-path-unpainted.md)
+- [`content-resource-missing`](content-resource-missing.md)
+- [`content-syntax`](content-syntax.md)
+- [`content-unbalanced-bt`](content-unbalanced-bt.md)
+- [`content-unbalanced-marked`](content-unbalanced-marked.md)
+- [`content-unbalanced-q`](content-unbalanced-q.md)
+- [`content-unknown-operator`](content-unknown-operator.md)
+- [`data-pending`](data-pending.md)
+- [`decompress`](decompress.md)
+- [`device-color-without-output-intent`](device-color-without-output-intent.md)
+- [`direct-page`](direct-page.md)
+- [`disposed`](disposed.md)
+- [`document-changed`](document-changed.md)
+- [`embedded-file-forbidden`](embedded-file-forbidden.md)
+- [`embedded-file-without-mime-type`](embedded-file-without-mime-type.md)
+- [`encoding-full`](encoding-full.md)
+- [`encrypted-base`](encrypted-base.md)
+- [`extract-limit-blocks`](extract-limit-blocks.md)
+- [`extract-module-not-loaded`](extract-module-not-loaded.md)
+- [`extract-reading-order-ambiguous`](extract-reading-order-ambiguous.md)
+- [`extract-struct-tree-ignored`](extract-struct-tree-ignored.md)
+- [`extract-table-ambiguous`](extract-table-ambiguous.md)
+- [`extract-table-limit`](extract-table-limit.md)
+- [`extract-untagged-content`](extract-untagged-content.md)
+- [`fetch-failed`](fetch-failed.md)
+- [`flate-truncated`](flate-truncated.md)
+- [`font-invalid`](font-invalid.md)
+- [`font-mismatch`](font-mismatch.md)
+- [`font-not-embeddable`](font-not-embeddable.md)
+- [`font-not-embedded`](font-not-embedded.md)
+- [`font-not-shapable`](font-not-shapable.md)
+- [`glyph-out-of-range`](glyph-out-of-range.md)
+- [`glyph-without-unicode`](glyph-without-unicode.md)
+- [`heading-level-skipped`](heading-level-skipped.md)
+- [`image-data-length`](image-data-length.md)
+- [`image-too-large`](image-too-large.md)
+- [`inline-image-unterminated`](inline-image-unterminated.md)
+- [`input-unreadable`](input-unreadable.md)
+- [`instance-reset`](instance-reset.md)
+- [`invalid-argument`](invalid-argument.md)
+- [`invalid-axis-value`](invalid-axis-value.md)
+- [`invalid-box`](invalid-box.md)
+- [`invalid-color`](invalid-color.md)
+- [`invalid-command-line`](invalid-command-line.md)
+- [`invalid-date`](invalid-date.md)
+- [`invalid-entry`](invalid-entry.md)
+- [`invalid-feature`](invalid-feature.md)
+- [`invalid-font`](invalid-font.md)
+- [`invalid-geometry`](invalid-geometry.md)
+- [`invalid-icc-profile`](invalid-icc-profile.md)
+- [`invalid-image`](invalid-image.md)
+- [`invalid-op-log`](invalid-op-log.md)
+- [`invalid-page-label`](invalid-page-label.md)
+- [`invalid-page-labels`](invalid-page-labels.md)
+- [`invalid-page-range`](invalid-page-range.md)
+- [`invalid-rotate`](invalid-rotate.md)
+- [`invalid-structure-nesting`](invalid-structure-nesting.md)
+- [`invalid-structure`](invalid-structure.md)
+- [`invalid-text-range`](invalid-text-range.md)
+- [`job-finished`](job-finished.md)
+- [`limit-exceeded`](limit-exceeded.md)
+- [`link-without-contents`](link-without-contents.md)
+- [`link-without-structure`](link-without-structure.md)
+- [`missing-alt-text`](missing-alt-text.md)
+- [`missing-glyph`](missing-glyph.md)
+- [`missing-header`](missing-header.md)
+- [`missing-lang`](missing-lang.md)
+- [`missing-root`](missing-root.md)
+- [`missing-title`](missing-title.md)
+- [`name-tree-node-skipped`](name-tree-node-skipped.md)
+- [`nested-transaction`](nested-transaction.md)
+- [`no-pending-save`](no-pending-save.md)
+- [`no-transaction`](no-transaction.md)
+- [`not-initialized`](not-initialized.md)
+- [`not-pdf`](not-pdf.md)
+- [`not-rebased`](not-rebased.md)
+- [`object-number-out-of-range`](object-number-out-of-range.md)
+- [`objstm-index-mismatch`](objstm-index-mismatch.md)
+- [`out-of-memory`](out-of-memory.md)
+- [`outline-cycle`](outline-cycle.md)
+- [`outline-item-skipped`](outline-item-skipped.md)
+- [`output-unwritable`](output-unwritable.md)
+- [`overwrite-refused`](overwrite-refused.md)
+- [`page-count-mismatch`](page-count-mismatch.md)
+- [`page-index-out-of-range`](page-index-out-of-range.md)
+- [`page-tree-node-skipped`](page-tree-node-skipped.md)
+- [`password-required`](password-required.md)
+- [`path-outside-roots`](path-outside-roots.md)
+- [`perms-mismatch`](perms-mismatch.md)
+- [`profile-version-conflict`](profile-version-conflict.md)
+- [`reference-cycle`](reference-cycle.md)
+- [`render-backend-unavailable`](render-backend-unavailable.md)
+- [`render-failed`](render-failed.md)
+- [`render-too-large`](render-too-large.md)
+- [`repaired-base`](repaired-base.md)
+- [`requires-rewrite`](requires-rewrite.md)
+- [`saved-not-rebased`](saved-not-rebased.md)
+- [`sink-not-empty`](sink-not-empty.md)
+- [`sink`](sink.md)
+- [`source-budget-exceeded`](source-budget-exceeded.md)
+- [`source-changed`](source-changed.md)
+- [`source`](source.md)
+- [`stale-generation`](stale-generation.md)
+- [`stream-length-recovered`](stream-length-recovered.md)
+- [`strict`](strict.md)
+- [`subset-failed`](subset-failed.md)
+- [`syntax`](syntax.md)
+- [`text-module-not-loaded`](text-module-not-loaded.md)
+- [`text-overflow`](text-overflow.md)
+- [`tounicode-conflict`](tounicode-conflict.md)
+- [`type`](type.md)
+- [`unexpected-eof`](unexpected-eof.md)
+- [`unknown-axis`](unknown-axis.md)
+- [`unknown-code`](unknown-code.md)
+- [`unknown-destination`](unknown-destination.md)
+- [`unknown-font`](unknown-font.md)
+- [`unknown-option`](unknown-option.md)
+- [`unknown-page`](unknown-page.md)
+- [`unmapped-glyph`](unmapped-glyph.md)
+- [`unnumbered-heading-misused`](unnumbered-heading-misused.md)
+- [`unset-object`](unset-object.md)
+- [`unsupported-filter`](unsupported-filter.md)
+- [`unsupported-image`](unsupported-image.md)
+- [`unsupported-layout-option`](unsupported-layout-option.md)
+- [`unsupported-security-handler`](unsupported-security-handler.md)
+- [`unsupported-version`](unsupported-version.md)
+- [`untagged-content`](untagged-content.md)
+- [`warnings-truncated`](warnings-truncated.md)
+- [`wasm-trap`](wasm-trap.md)
+- [`whole-font-rebuilt`](whole-font-rebuilt.md)
+- [`worker-crashed`](worker-crashed.md)
+- [`worker-failed`](worker-failed.md)
+- [`worker-version-mismatch`](worker-version-mismatch.md)
+- [`would-invalidate-signatures`](would-invalidate-signatures.md)
+- [`wrong-document`](wrong-document.md)
+- [`wrong-password`](wrong-password.md)
+- [`xobject-cycle`](xobject-cycle.md)
+- [`xref-repaired`](xref-repaired.md)
+- [`xrefstm-ignored`](xrefstm-ignored.md)

package/docs/errors/aes-padding-invalid.md

@@ -0,0 +1,34 @@
+---
+title: "aes-padding-invalid"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/aes-padding-invalid/"
+---
+
+# aes-padding-invalid
+
+- Type: warning
+- Kind: `security` (encryption, permissions or signatures block the call, or look tampered with)
+
+## What happened
+
+AES-encrypted data was not `IV ‖ whole blocks` or had invalid padding; it was kept as stored or unstripped.
+
+## Why
+
+Damaged data, or plaintext spliced into an encrypted file (PDFex-style).
+
+## How to fix
+
+Treat the affected strings and streams as suspect: they may have been altered or spliced in. Don't use them for anything security-relevant.
+
+## Example
+
+```text
+(an AESV2 string whose last block does not end in valid PKCS#5 padding)
+```
+
+Lamina PDF keeps the data as stored (or unstripped) instead of failing, and raises the warning with the string's or stream's `object`.
+
+## Data fields
+
+None.

package/docs/errors/already-initialized.md

@@ -0,0 +1,34 @@
+---
+title: "already-initialized"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/already-initialized/"
+---
+
+# already-initialized
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+`init()` or `loadText()` of `@laminapdf/sdk` named a source (a URL, `Response`, bytes or `WebAssembly.Module`) for a module that an earlier call had already loaded, or started loading, from another source (or from the default file).
+
+## Why
+
+Each module is instantiated once per JavaScript realm: every document and builder lives in that instance. Loading a second copy from another source would leave two instances whose objects can't be mixed, so the second source is refused rather than silently ignored.
+
+## How to fix
+
+Pass the source on the first call only; later calls (from other parts of the app) can call `init()` without one, which waits for the same load. Calling again with the very same source object is allowed.
+
+## Example
+
+```js
+await init(new URL("/wasm/lamina_pdf_base.wasm", location.href));
+await init(); // fine: the module is loaded
+await init(otherBytes); // throws { code: "already-initialized", … }
+```
+
+## Data fields
+
+None.

package/docs/errors/binary-output-to-terminal.md

@@ -0,0 +1,35 @@
+---
+title: "binary-output-to-terminal"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/binary-output-to-terminal/"
+---
+
+# binary-output-to-terminal
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+A command that writes a PDF was told to write it to standard output (`-o -`), and standard output is a terminal.
+
+## Why
+
+A PDF's bytes would fill the terminal with noise and can leave it in a strange state. The CLI writes binary output only to a file or a pipe.
+
+## How to fix
+
+Redirect standard output to a file or a pipe, or write to a file with `-o`.
+
+## Example
+
+```console
+$ laminapdf pages rotate scan.pdf +90 -o -
+error[binary-output-to-terminal]: standard output is a terminal
+  = hint: redirect standard output to a file or a pipe, or write to a file with -o
+$ laminapdf pages rotate scan.pdf +90 -o - > rotated.pdf
+```
+
+## Data fields
+
+None.

package/docs/errors/builder-finished.md

@@ -0,0 +1,35 @@
+---
+title: "builder-finished"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/builder-finished/"
+---
+
+# builder-finished
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+A `WasmBuilder` method was called after the builder's `finish`, or a `WasmPageBuilder` was drawn on or finished again after its own `finish` (or after its builder's).
+
+## Why
+
+`finish` hands the work over: a builder's becomes a `WasmDocument`, a page's is written into its builder. Neither holds anything to draw on afterwards.
+
+## How to fix
+
+Draw everything on a page before finishing it, and finish every page before the builder. To build more, create a new page or builder.
+
+## Example
+
+```js
+const b = new WasmBuilder(undefined);
+const page = b.page(595, 842);
+page.finish();
+page.save(); // throws { code: "builder-finished", … }
+```
+
+## Data fields
+
+- `argument`: always `builder`.

package/docs/errors/cancelled.md

@@ -0,0 +1,35 @@
+---
+title: "cancelled"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/cancelled/"
+---
+
+# cancelled
+
+- Type: error
+- Kind: `cancelled` (a `CancelToken` stopped the work)
+
+## What happened
+
+The `CancelToken` passed to a job, or to a run-to-completion call such as `Document::save`, was cancelled. The call returned at its next check: the start of a step, a budget check, or the next object or page of a long loop.
+
+## Why
+
+The caller (or a host on its behalf: an `AbortSignal`, Ctrl-C, a task cancellation) asked for the work to stop.
+
+## How to fix
+
+Nothing: this is the outcome that was asked for. The job is finished, a cancelled save left the document as it was (`Dirty`, nothing written), and a cancelled read returned no partial result. Start a new job with a fresh token to try again.
+
+## Example
+
+```rust
+let cancel = laminapdf::CancelToken::new();
+cancel.cancel();
+let err = doc.save_with(&laminapdf::SaveOptions::new(), &cancel).unwrap_err();
+assert_eq!(err.code(), "cancelled");
+```
+
+## Data fields
+
+None.

package/docs/errors/cmap-invalid.md

@@ -0,0 +1,42 @@
+---
+title: "cmap-invalid"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/cmap-invalid/"
+---
+
+# cmap-invalid
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A font's CMap (its Type 0 `/Encoding`) or ToUnicode CMap couldn't be fully used, for one of three reasons:
+
+- entries that can't be read, which are skipped;
+- a predefined CMap Lamina PDF has no table for, read as Identity (Lamina PDF knows only `Identity-H`/`-V` and the `Uni…-UCS2-…`/`Uni…-UTF16-…` ones);
+- a `/UseCMap` chain deeper than 8 levels, cut there.
+
+## Why
+
+A producer bug (bad ranges, a missing `end…` keyword), or a CJK file using one of Adobe's character-collection CMaps without embedding it.
+
+## How to fix
+
+Nothing to do. The rest of the CMap is used; affected glyphs may extract as other text or U+FFFD.
+
+## Example
+
+```text
+1 beginbfchar
+<0003> <0020
+endbfchar
+```
+
+The destination string is not closed; the entry is skipped, and the rest of the ToUnicode CMap is used.
+
+## Data fields
+
+None.
+
+The `location` is `object`, the font dictionary's object; none for a direct font dictionary.

package/docs/errors/collection-index.md

@@ -0,0 +1,33 @@
+---
+title: "collection-index"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/collection-index/"
+---
+
+# collection-index
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Font::from_collection` was asked for a member past the end of the font collection.
+
+## Why
+
+Members are numbered from 0; a single font counts as a collection of one.
+
+## How to fix
+
+Use an index below `Font::collection_len(bytes)`.
+
+## Example
+
+```rust
+let font = Font::from_collection(ttc_bytes, 4)?; // the collection has 4 members (0..=3): collection-index
+```
+
+## Data fields
+
+- `index`: the member that was asked for.
+- `count`: how many members the collection has.

package/docs/errors/color-components.md

@@ -0,0 +1,33 @@
+---
+title: "color-components"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/color-components/"
+---
+
+# color-components
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Color::icc` was given a number of components that differs from the profile's channel count.
+
+## Why
+
+An `ICCBased` colour has one component per channel of its profile (`/N`: Gray 1, RGB and Lab 3, CMYK 4).
+
+## How to fix
+
+Give `IccProfile::components()` values.
+
+## Example
+
+```rust
+let c = Color::icc(&cmyk_profile, &[0.1, 0.2, 0.3])?; // color-components: 4 expected
+```
+
+## Data fields
+
+- `expected`: the colour space's number of components.
+- `actual`: how many were given.

package/docs/errors/content-bad-operands.md

@@ -0,0 +1,36 @@
+---
+title: "content-bad-operands"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/content-bad-operands/"
+---
+
+# content-bad-operands
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An operator had too few operands or operands of the wrong type (it was skipped), or extra operands (the last ones were used).
+
+## Why
+
+A producer bug, or damaged content.
+
+## How to fix
+
+Nothing to do.
+
+## Example
+
+```text
+72 Td
+```
+
+`Td` takes two numbers; with one, the operator is skipped.
+
+## Data fields
+
+- `offset`: the operator'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/content-path-unpainted.md

@@ -0,0 +1,36 @@
+---
+title: "content-path-unpainted"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/content-path-unpainted/"
+---
+
+# content-path-unpainted
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A content stream ended with a path that no painting operator ended; it was dropped.
+
+## Why
+
+A producer bug, or truncated content.
+
+## How to fix
+
+Nothing to do.
+
+## Example
+
+```text
+0 0 m 100 100 l
+```
+
+The content stream ends after building a path without `S`, `f` or `n`: the path is dropped, as the spec intends.
+
+## Data fields
+
+- `offset`: the byte offset of the path's first segment 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/content-resource-missing.md

@@ -0,0 +1,37 @@
+---
+title: "content-resource-missing"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/content-resource-missing/"
+---
+
+# content-resource-missing
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+An operator named a resource (font, XObject, graphics state, colour space, shading, property list) that is missing, of the wrong type or unreadable, or a Form XObject's content could not be decoded; the operator was skipped or ran without it.
+
+## Why
+
+Resources lost in editing or merging, or damaged objects.
+
+## How to fix
+
+Check the page's `/Resources`.
+
+## Example
+
+```text
+/Im7 Do      % /Resources << /XObject << /Im1 8 0 R >> >>
+```
+
+`/Im7` is not in the page's resources, so the `Do` draws nothing. `data.category` is `XObject`; the resource's name, which comes from the file, is never put in the message.
+
+## Data fields
+
+- `offset`: the operator's byte offset in the decoded content.
+- `category`: the resource category, e.g. `Font` (Lamina PDF's own vocabulary).
+
+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.