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

package/docs/errors/extract-column-order-uncertain.md

@@ -0,0 +1,38 @@
+---
+title: "extract-column-order-uncertain"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/extract-column-order-uncertain/"
+---
+
+# extract-column-order-uncertain
+
+- Type: warning
+- Kind: `unsupported` (something Lamina PDF can't do yet)
+
+## What happened
+
+Extraction read the page's columns in an order its layout rules had to guess, so the page's blocks may be in the wrong order. The blocks the guess concerns have a `confidence` of 0.5 instead of 0.75; the order itself is the rules' best one.
+
+## Why
+
+A PDF stores where each piece of text is drawn, not the order to read it in, so extraction works the order out from the layout: columns first, top to bottom. Three layouts leave that order in doubt, and the warning's `reason` names which one it found:
+
+- `narrow-gutter`: two columns sit closer together than a font size, so lines may have been read straight across both columns.
+- `columns-revisited`: a block across the gutter, such as a pull quote with the text wrapped round it, cut the columns into rows, so the order leaves a column and comes back to it.
+- `near-grid`: blocks that look like an unruled table, with one cell wrapped onto a second line, were read column by column; read by rows, the order would differ.
+
+A page that mixes horizontal and vertical writing raises [`extract-reading-order-ambiguous`](extract-reading-order-ambiguous.md) instead.
+
+## How to fix
+
+Check the page's text, or send the page to a layout model, which reads columns from the page's image. A tagged file read in its structure tree's order never raises this warning. Like every warning, it fails the call in strict mode.
+
+## Example
+
+A newsletter page with two columns set 7 pt apart: each line of the extracted text runs across both columns, and the page is warned with `narrow-gutter`.
+
+## Data fields
+
+- `reason`: `narrow-gutter`, `columns-revisited` or `near-grid`, the first check that doubted the order.
+
+The `location` has the page's `pageIndex`.

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

@@ -0,0 +1,35 @@
+---
+title: "extract-limit-blocks"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/extract-limit-blocks/"
+---
+
+# extract-limit-blocks
+
+- Type: warning
+- Kind: `limit` (a `Limits` value or another resource bound was hit)
+
+## What happened
+
+A page had more runs of text than `ExtractLimits::max_blocks_per_page` allows. Since each run can be a block of its own, extraction kept the first runs the page draws and left out the rest. It cuts them before grouping runs into blocks, so the work stays bounded.
+
+## Why
+
+A page of many tiny separate pieces of text, such as a dense table, a map with hundreds of labels, or a file built to slow extraction down.
+
+## How to fix
+
+Raise `max_blocks_per_page` if the page really holds that many blocks.
+
+## Example
+
+```rust
+let mut options = laminapdf_extract::ExtractOptions::default();
+options.limits.max_blocks_per_page = 50_000;
+```
+
+## Data fields
+
+- `limit`: the limit that was reached.
+
+The `location` has the page's `pageIndex`.

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

@@ -0,0 +1,37 @@
+---
+title: "extract-module-not-loaded"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/extract-module-not-loaded/"
+---
+
+# extract-module-not-loaded
+
+- Type: error
+- Kind: `state` (the call isn't valid in the object's current state)
+
+## What happened
+
+`page.text()` of `@laminapdf/sdk` was called on a page of a document opened in the base module, which has no text extraction.
+
+## Why
+
+`@laminapdf/sdk` ships three WebAssembly modules: base (open, read, edit, save), extract (base plus text extraction) and text (base plus fonts, shaping and extraction). A document lives in the module it was opened in, and opening uses the richest one loaded at that moment: text, then extract, then base. A document opened before the extract or text module was loaded stays in the base module.
+
+## How to fix
+
+Load the extract module (about half the size of the text module) before opening the document: `await init({ extract: true })` or `await loadExtract()`. A document already open in the base module can be moved by saving it and opening the bytes again.
+
+## Example
+
+```js
+await init();
+const doc = Document.open(bytes);
+doc.page(0).text(); // throws { code: "extract-module-not-loaded", … }
+
+await loadExtract();
+Document.open(bytes).page(0).text().text(); // works
+```
+
+## Data fields
+
+None.

package/docs/errors/extract-needs-ocr.md

@@ -0,0 +1,37 @@
+---
+title: "extract-needs-ocr"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/extract-needs-ocr/"
+---
+
+# extract-needs-ocr
+
+- Type: warning
+- Kind: `unsupported` (something Lamina PDF can't do yet)
+
+## What happened
+
+The page has no text that extraction can use, so the page's Markdown, text and blocks are empty or close to it. Each page's `textLayer` in the extraction says why, and this warning names the pages whose status is `needs-ocr` or `ocr-layer`.
+
+## Why
+
+A page's text comes from its fonts. Some pages draw their words in other ways:
+
+- a scanned page is one image, with no text at all;
+- a page made searchable by OCR has an image under invisible text, which extraction leaves out of the blocks because a reader can't see it;
+- outlined text is drawn as shapes, not glyphs;
+- a font without a Unicode mapping draws glyphs that extraction can't turn into characters.
+
+## How to fix
+
+Send the pages this warning names to OCR or a vision model. On an `ocr-layer` page you can instead keep the existing OCR layer: extraction lists its text under `dropped` as `invisible` when you set `drop: { keepSpans: true }` (`DropOptions::keep_spans` in Rust). Like every warning, it fails the call in strict mode.
+
+## Example
+
+A scanned contract: every page is `needs-ocr`, and the extraction's Markdown is empty.
+
+## Data fields
+
+- `status`: the page's text-layer status, `needs-ocr` or `ocr-layer`.
+
+The `location` has the page's `pageIndex`.

package/docs/errors/extract-reading-order-ambiguous.md

@@ -0,0 +1,32 @@
+---
+title: "extract-reading-order-ambiguous"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/extract-reading-order-ambiguous/"
+---
+
+# extract-reading-order-ambiguous
+
+- Type: warning
+- Kind: `unsupported` (valid input that Lamina PDF doesn't implement)
+
+## What happened
+
+A page mixes horizontal and vertical writing. Extraction put its blocks in an order, but no layout rule tells which comes first, so the order is a guess.
+
+## Why
+
+Japanese and Chinese pages often set the body vertically and captions, headings or page numbers horizontally. Without a structure tree, nothing in the file says how the two relate.
+
+## How to fix
+
+Nothing to do in Lamina PDF; the file is valid. Like every warning, it fails the call in strict mode. Check the order of that page's blocks, or ask for the order the content stream draws (`ReadingOrder::ContentStream`). A tagged file avoids the guess.
+
+## Example
+
+A page whose body text is drawn with a vertical font (`Identity-V`) and whose page number is drawn with a horizontal one.
+
+## Data fields
+
+None.
+
+The `location` has the page's `pageIndex`.

package/docs/errors/extract-struct-tree-ignored.md

@@ -0,0 +1,32 @@
+---
+title: "extract-struct-tree-ignored"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/extract-struct-tree-ignored/"
+---
+
+# extract-struct-tree-ignored
+
+- Type: warning
+- Kind: `input` (a problem with the PDF file)
+
+## What happened
+
+The page is tagged, but its structure tree didn't pass the checks that decide whether to trust it, so extraction read the page in layout order instead.
+
+## Why
+
+A structure tree gives a page's reading order, but trees are often incomplete or wrong. Extraction uses a page's tree only when its elements cover at least 80% of the page's visible text, not counting headers, page numbers and other text the file marks as page furniture. Its order must also jump back up into an earlier column at most once in ten moves from block to block. A tree written by a tool that tags only some of the text, or that tags it in drawing order, fails one of the checks.
+
+## How to fix
+
+Nothing to do: the page reads in layout order, as an untagged page would. To use the tree anyway, extract with `ReadingOrder::Tagged` (`readingOrder: "tagged"`). Like every warning, it fails the call in strict mode.
+
+## Example
+
+A report whose tool tagged only its headings: the tree covers a tenth of the text, so the reason is `coverage`.
+
+## Data fields
+
+- `reason`: `coverage` or `order`, the check that failed.
+
+The `location` has the page's `pageIndex`.

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

@@ -0,0 +1,32 @@
+---
+title: "extract-table-ambiguous"
+version: "0.2.0-alpha.4"
+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.4"
+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.4"
+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.4"
+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 must not compress the response (`Content-Encoding` breaks byte ranges). Across origins, it must also allow the `If-Range` header that every request after the first carries, and expose `Content-Range`, `Content-Length` and `ETag` through CORS. 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, If-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.4"
+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/flow-content-too-large.md

@@ -0,0 +1,34 @@
+---
+title: "flow-content-too-large"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/flow-content-too-large/"
+---
+
+# flow-content-too-large
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Builder::flow` found a figure, a single line of text or a table row taller than the body of a page: the space between the top and bottom margins. No page can hold it, so the flow stopped and added no pages. A line or row counts together with the footnotes it cites, since its notes go at the foot of its page.
+
+## Why
+
+A flow moves a figure to the next page when it doesn't fit, and splits a paragraph only between lines. A figure or a line taller than a whole page would fit on no page at all, and cutting it would hide part of it.
+
+## How to fix
+
+Make the figure narrower with `Figure::with_width`, so its height shrinks with it. For a line, use a smaller text size or a smaller line height. For a footnote, shorten the note or split it into two. Or give the page more room with a taller page size or smaller top and bottom margins.
+
+## Example
+
+```rust
+let tall = Image::rgba(1, 10, &[0; 40])?; // ten times as tall as it is wide
+let flow = Flow::new(PageTemplate::new(PageSize::A6)).block(FlowBlock::Figure(Figure::new(tall, "A bar")));
+builder.flow(&flow)?; // flow-content-too-large
+```
+
+## Data fields
+
+- `what`: what is too tall: `line`, `figure`, `table row`, or `footnote` when a line or table row and its footnotes fit on no page together.

package/docs/errors/flow-keep-broken.md

@@ -0,0 +1,34 @@
+---
+title: "flow-keep-broken"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/flow-keep-broken/"
+---
+
+# flow-keep-broken
+
+- Type: warning
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Builder::flow` met blocks it was asked to keep on one page, and together they are taller than a page. The flow split them across pages anyway. Blocks are kept together by a `FlowBlock::Keep` group, or by a heading or a paragraph set to keep with the block after it.
+
+## Why
+
+Blocks that can't fit on one page can't be kept on one page. No layout can keep them together, so the flow doesn't look for one. It lays them out as it would without the rule, and every page still ends on a whole line.
+
+## How to fix
+
+Keep fewer blocks together: split a long `Keep` group into smaller ones, or turn off `keep_with_next` on a paragraph in a long chain. Or make the page taller, or its margins smaller, so the group fits.
+
+## Example
+
+```rust
+let group = FlowBlock::Keep(vec![long_intro, long_paragraph]); // taller than a page
+let report = builder.flow(&Flow::new(template).block(group))?;
+assert_eq!(report.warnings[0].code(), "flow-keep-broken");
+```
+
+## Data fields
+
+- `page`: the page the blocks start on, counted from 0 within the flow.

package/docs/errors/flow-layout-unstable.md

@@ -0,0 +1,38 @@
+---
+title: "flow-layout-unstable"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/flow-layout-unstable/"
+---
+
+# flow-layout-unstable
+
+- Type: error
+- Kind: `internal` (a bug in Lamina PDF or a broken invariant)
+
+## What happened
+
+`Builder::flow` laid out a flow with a contents page four times, and the page numbers on the contents page still changed. The flow stopped and added no pages.
+
+## Why
+
+A contents page lists each heading with the page it starts on, but those pages aren't known until the flow is laid out. So the flow lays everything out, writes the numbers it found into the contents page, and lays out again to check them. Each entry keeps the same room for its number however wide the number is, so the contents page's length never depends on the numbers, and the second layout finds the same pages.
+
+The flow still checks up to four layouts. This error means the numbers kept changing anyway, which points to a fault in Lamina PDF's layout rather than in your document.
+
+## How to fix
+
+Report the flow that fails, with the blocks and page template that produce it. Until it is fixed, a page break after the contents block may avoid the error, since the headings after it then start on pages of their own.
+
+## Example
+
+```rust
+let flow = Flow::new(template)
+    .block(FlowBlock::Contents(Contents::new(&style)))
+    .block(FlowBlock::PageBreak) // the headings start on their own pages
+    .block(FlowBlock::Heading(1, Paragraph::plain("Introduction", &heading)));
+builder.flow(&flow)?;
+```
+
+## Data fields
+
+None.

package/docs/errors/font-invalid.md

@@ -0,0 +1,36 @@
+---
+title: "font-invalid"
+version: "0.2.0-alpha.4"
+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.4"
+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.4"
+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.4"
+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`.