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

package/docs/errors/source.md

@@ -1,6 +1,6 @@
 ---
 title: "source"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/source/"
 ---
 

package/docs/errors/stale-generation.md

@@ -1,6 +1,6 @@
 ---
 title: "stale-generation"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/stale-generation/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "stream-length-recovered"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/stream-length-recovered/"
 ---
 

package/docs/errors/strict.md

@@ -1,6 +1,6 @@
 ---
 title: "strict"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/strict/"
 ---
 

package/docs/errors/subset-failed.md

@@ -1,6 +1,6 @@
 ---
 title: "subset-failed"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/subset-failed/"
 ---
 

package/docs/errors/syntax.md

@@ -1,6 +1,6 @@
 ---
 title: "syntax"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/syntax/"
 ---
 

package/docs/errors/tag-element-not-open.md

@@ -0,0 +1,41 @@
+---
+title: "tag-element-not-open"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/tag-element-not-open/"
+---
+
+# tag-element-not-open
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Surface::resume` or `Builder::close_element` was given a structure element that isn't open. When `resume` names one, the page's `PageBuilder::finish` fails.
+
+## Why
+
+An element that continues across pages is open from `Surface::open_element` until `Builder::close_element` writes it, and only then. The element named was one of these:
+
+- closed already;
+- opened by another builder;
+- opened inside an artifact, so it is part of the artifact (ISO 32000-2 §14.8.2.2);
+- opened on a page added to an existing document, which is never tagged;
+- opened on a page whose `PageBuilder::finish` failed, so it was never written.
+
+## How to fix
+
+Open the element on a page of the same builder, outside every artifact, and close it once, after its last page is finished.
+
+## Example
+
+```rust
+let paragraph = page.surface().open_element(TagKind::P);
+page.finish()?;
+builder.close_element(paragraph)?;
+builder.close_element(paragraph)?; // tag-element-not-open: closed already
+```
+
+## Data fields
+
+None.

package/docs/errors/tag-element-unclosed.md

@@ -0,0 +1,34 @@
+---
+title: "tag-element-unclosed"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/tag-element-unclosed/"
+---
+
+# tag-element-unclosed
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Builder::finish` was called while structure elements opened with `Surface::open_element` were still open.
+
+## Why
+
+An element that continues across pages is written when `Builder::close_element` closes it, since only then is its content complete. An element never closed would leave the structure tree with a reference to an element that doesn't exist (ISO 32000-2 §14.7.2), so the build stops instead.
+
+## How to fix
+
+Close every element from `Surface::open_element` with `Builder::close_element` once its last page is finished, before `Builder::finish`.
+
+## Example
+
+```rust
+let paragraph = page.surface().open_element(TagKind::P);
+page.finish()?;
+builder.finish()?; // tag-element-unclosed: the paragraph is still open
+```
+
+## Data fields
+
+- `count`: how many elements are still open.

package/docs/errors/text-in-earlier-revision.md

@@ -0,0 +1,36 @@
+---
+title: "text-in-earlier-revision"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/text-in-earlier-revision/"
+---
+
+# text-in-earlier-revision
+
+- Type: warning
+- Kind: `security` (encryption, permissions or signatures block the call, or look tampered with)
+
+## What happened
+
+The file was saved with incremental updates, and an earlier revision holds words that the latest revision has nowhere. Anyone can cut the file back to that revision and read them.
+
+## Why
+
+An incremental save appends the changes to the end of the file and keeps everything before them (ISO 32000-2 §7.5.6). Deleting a paragraph and saving that way leaves the paragraph in the bytes of the earlier revision. Signing, filling a form and some editors' plain "Save" all save incrementally.
+
+Not every removed word is a leak: fixing a typo removes the misspelt word too. The warning states that the earlier text is still in the file; whether that matters depends on what was removed.
+
+## How to fix
+
+Save the file as a full rewrite, which keeps only the latest revision. A signed file loses its signatures that way, so sign it again afterwards.
+
+## Example
+
+`fixtures/corpus/hello-incremental.pdf` first draws "Hello, World", and its update replaces that with "Hello, Update". `laminapdf check` reports `text-in-earlier-revision` with `revision` 0, `words` 1 and `pages` `[0]`.
+
+## Data fields
+
+- `revision`: the earlier revision's index, 0 for the original file.
+- `words`: how many words that revision has more often than the latest one (only words of two or more letters or digits count).
+- `pages`: the indices of that revision's pages where those words are.
+
+The warning has no `location`, and it never holds the words themselves.

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

@@ -1,6 +1,6 @@
 ---
 title: "text-module-not-loaded"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/text-module-not-loaded/"
 ---
 

package/docs/errors/text-overflow.md

@@ -1,6 +1,6 @@
 ---
 title: "text-overflow"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/text-overflow/"
 ---
 

package/docs/errors/tounicode-conflict.md

@@ -1,6 +1,6 @@
 ---
 title: "tounicode-conflict"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/tounicode-conflict/"
 ---
 

package/docs/errors/type.md

@@ -1,6 +1,6 @@
 ---
 title: "type"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/type/"
 ---
 

package/docs/errors/unexpected-eof.md

@@ -1,6 +1,6 @@
 ---
 title: "unexpected-eof"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unexpected-eof/"
 ---
 

package/docs/errors/unknown-axis.md

@@ -1,6 +1,6 @@
 ---
 title: "unknown-axis"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unknown-axis/"
 ---
 

package/docs/errors/unknown-code.md

@@ -1,6 +1,6 @@
 ---
 title: "unknown-code"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unknown-code/"
 ---
 

package/docs/errors/unknown-destination.md

@@ -1,6 +1,6 @@
 ---
 title: "unknown-destination"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unknown-destination/"
 ---
 

package/docs/errors/unknown-font.md

@@ -1,6 +1,6 @@
 ---
 title: "unknown-font"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unknown-font/"
 ---
 

package/docs/errors/unknown-option.md

@@ -1,6 +1,6 @@
 ---
 title: "unknown-option"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unknown-option/"
 ---
 

package/docs/errors/unknown-page.md

@@ -1,6 +1,6 @@
 ---
 title: "unknown-page"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unknown-page/"
 ---
 

package/docs/errors/unmapped-glyph.md

@@ -1,6 +1,6 @@
 ---
 title: "unmapped-glyph"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unmapped-glyph/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "unnumbered-heading-misused"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unnumbered-heading-misused/"
 ---
 

package/docs/errors/unset-object.md

@@ -1,6 +1,6 @@
 ---
 title: "unset-object"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unset-object/"
 ---
 

package/docs/errors/unsupported-filter.md

@@ -1,6 +1,6 @@
 ---
 title: "unsupported-filter"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unsupported-filter/"
 ---
 

package/docs/errors/unsupported-image.md

@@ -1,6 +1,6 @@
 ---
 title: "unsupported-image"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unsupported-image/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "unsupported-layout-option"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unsupported-layout-option/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "unsupported-security-handler"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unsupported-security-handler/"
 ---
 

package/docs/errors/unsupported-version.md

@@ -1,6 +1,6 @@
 ---
 title: "unsupported-version"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/unsupported-version/"
 ---
 

package/docs/errors/untagged-content.md

@@ -1,6 +1,6 @@
 ---
 title: "untagged-content"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/untagged-content/"
 ---
 

package/docs/errors/warnings-truncated.md

@@ -1,6 +1,6 @@
 ---
 title: "warnings-truncated"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/warnings-truncated/"
 ---
 

package/docs/errors/wasm-trap.md

@@ -1,6 +1,6 @@
 ---
 title: "wasm-trap"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/wasm-trap/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "whole-font-rebuilt"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/whole-font-rebuilt/"
 ---
 

package/docs/errors/worker-crashed.md

@@ -1,6 +1,6 @@
 ---
 title: "worker-crashed"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/worker-crashed/"
 ---
 

package/docs/errors/worker-failed.md

@@ -1,6 +1,6 @@
 ---
 title: "worker-failed"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/worker-failed/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "worker-version-mismatch"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/worker-version-mismatch/"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "would-invalidate-signatures"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/would-invalidate-signatures/"
 ---
 

package/docs/errors/wrong-document.md

@@ -1,6 +1,6 @@
 ---
 title: "wrong-document"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/wrong-document/"
 ---
 

package/docs/errors/wrong-password.md

@@ -1,6 +1,6 @@
 ---
 title: "wrong-password"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/wrong-password/"
 ---
 

package/docs/errors/xobject-cycle.md

@@ -1,6 +1,6 @@
 ---
 title: "xobject-cycle"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/xobject-cycle/"
 ---
 

package/docs/errors/xref-repaired.md

@@ -1,6 +1,6 @@
 ---
 title: "xref-repaired"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/xref-repaired/"
 ---
 

package/docs/errors/xrefstm-ignored.md

@@ -1,6 +1,6 @@
 ---
 title: "xrefstm-ignored"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/xrefstm-ignored/"
 ---
 

package/docs/llms.txt

@@ -2,7 +2,7 @@
 
 > Lamina PDF creates, reads, edits and saves PDF files from TypeScript and Rust: one Rust core, run as WebAssembly in browsers, Node, Deno, Bun and Cloudflare Workers (`@laminapdf/sdk`), or natively from the `laminapdf` crate. Positions are top-left points of the displayed page and page indexes start at 0; every error has a stable code with its own page.
 
-These docs describe version 0.2.0-alpha.3, the version of this package. The same docs are online at https://docs.laminapdf.com/llms.txt.
+These docs describe version 0.2.0-alpha.4, the version of this package. The same docs are online at https://docs.laminapdf.com/llms.txt.
 
 - [Using Lamina PDF with coding agents](AGENTS.md)
 - [What old names became](renames.json)
@@ -29,12 +29,14 @@ These docs describe version 0.2.0-alpha.3, the version of this package. The same
 - [Pages and coordinates](pages/concepts/pages-and-coordinates.md): Points from the top-left corner of the page as it's displayed, y going down, and pages numbered from 0.
 - [Errors and warnings](pages/concepts/errors-and-warnings.md): One coded error shape on every surface, and warnings for what Lamina PDF repaired.
 - [What Lamina PDF writes and what it borrows](pages/concepts/dependencies.md): Lamina PDF writes the parts that decide a PDF's bytes, borrows the rest from permissive projects, and pins and checks everything it borrows.
+- [How a page is drawn](pages/concepts/drawing-pages.md): A renderer turns a page into pixels; Lamina PDF reads the page's text, links and selection itself, from the same bytes.
 
 ## Create PDFs
 
 - [Text and fonts](pages/guides/fonts-and-text.md): Draw text in any script with your own fonts or the standard 14, one line at a time or as a paragraph that wraps in a box.
 - [Shapes, colour and images](pages/guides/images-and-vectors.md): Draw lines, shapes and images on a page, in any colour, with transparency, clipping and transforms.
 - [Links, outlines and metadata](pages/guides/links-outlines-and-metadata.md): Add links, named destinations, an outline, page labels, viewer preferences and metadata to a document.
+- [Pages that flow](pages/guides/flowing-pages.md): Pour headings, paragraphs, tables and images, or a Markdown file, into as many pages as they need, with footnotes, a contents page and "Page X of Y" footers.
 - [Accessible PDFs](pages/guides/accessible-pdfs.md): Build PDF/UA-1 documents that screen readers can follow, with every machine-checkable rule checked when the builder finishes.
 - [Archival PDFs](pages/guides/archival-pdfs.md): Build PDF/A-2b, PDF/A-2u and PDF/A-3b documents that look the same in years to come, and attach files such as an e-invoice's XML.
 
@@ -44,10 +46,12 @@ These docs describe version 0.2.0-alpha.3, the version of this package. The same
 - [Save a PDF](pages/guides/save-a-pdf.md): Save edits as a revision appended to the original bytes or as a whole new file, and see when a file refuses a save.
 - [Open password-protected files](pages/guides/password-protected-files.md): Open PDFs that need a password, ask again when it is missing or wrong, and save them afterwards.
 - [Open files you don't trust](pages/guides/untrusted-files.md): Cap how much work an uploaded PDF can make Lamina PDF do, and refuse damaged files with strict mode.
+- [Open large files by ranges](pages/guides/open-large-files.md): Open a PDF on a web server without downloading all of it, fetching only the byte ranges each read needs.
 
 ## Production
 
 - [Keep the page responsive](pages/guides/keep-the-page-responsive.md): Run Lamina PDF in a Web Worker with @laminapdf/sdk/worker, so a large file never freezes the page.
+- [Test the PDFs you generate](pages/guides/test-generated-pdfs.md): Compare the PDFs your code makes with reference PDFs you approved, byte for byte, and draw both files' pages to see what changed.
 
 ## Recipes
 
@@ -56,6 +60,7 @@ These docs describe version 0.2.0-alpha.3, the version of this package. The same
 - [An invoice](pages/recipes/invoice.md): A tagged one-page invoice with an embedded font, a table of line items with right-aligned amounts and a total, in TypeScript and Rust.
 - [Multilingual text](pages/recipes/multilingual.md): Latin, Arabic, Devanagari, Hebrew and Chinese on one page, each in its own embedded font, as a shaped line and a wrapped paragraph.
 - [Images and vectors](pages/recipes/images-and-vectors.md): Shapes, a dashed curve, gray, RGB, CMYK and hex colour, transparency, a blend mode, a clip, a rotation, a JPEG and an RGBA image on one page.
+- [Element flow](pages/recipes/element-flow.md): A report whose title, paragraphs and photo each start below wherever the one before ended, with a body that continues on a new page.
 - [Links and outlines](pages/recipes/links-and-outlines.md): Four A5 pages joined by web, page and named links, with a nested outline, page labels that read i, ii, 1, 2 and the outline shown on open.
 - [Generate, then edit](pages/recipes/generate-then-edit.md): Build a one-page draft, open its bytes, retitle it in one transaction and save the edit as a revision after the original bytes.
 - [Extract text for an LLM](pages/recipes/extract-markdown.md): Turn a PDF into Markdown in reading order, JSON with a box for every block, and chunks sized for retrieval, in TypeScript and Rust.
@@ -76,6 +81,7 @@ These docs describe version 0.2.0-alpha.3, the version of this package. The same
 - [Rust API (rustdoc)](pages/reference/rust.md): Where to read the API documentation of the Lamina PDF crates.
 - [Error and warning codes](pages/reference/codes.md): Every code Lamina PDF raises, generated from fixtures/codes.json when the site is built.
 - [Stability policy](pages/reference/stability.md): What a Lamina PDF version number promises, and what stays the same in every version.
+- [Benchmarks](pages/reference/benchmarks.md): How fast Lamina PDF makes PDFs in each runtime, how large its WebAssembly files are, and how well it extracts text on a public benchmark.
 - [Changelog](pages/reference/changelog.md): What changed in each Lamina PDF release, newest first.
 - [Glossary](pages/reference/glossary.md): The PDF and Lamina PDF terms the docs use, each in a sentence or two.
 

package/docs/pages/concepts/dependencies.md

@@ -1,7 +1,7 @@
 ---
 title: "What Lamina PDF writes and what it borrows"
 description: "Lamina PDF writes the parts that decide a PDF's bytes, borrows the rest from permissive projects, and pins and checks everything it borrows."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/concepts/dependencies/"
 ---
 
@@ -25,7 +25,7 @@ Lamina PDF hands one big job to another project: turning pages into pixels. Real
 
 ## PDFium only draws, and only in a Web Worker
 
-PDFium is C++ reading files you didn't write, so Lamina PDF keeps it at arm's length. The viewer runs it inside a Web Worker, away from your page. PDFium never changes the document either: every edit goes through Lamina PDF, which also writes the saved file. Text, selection and links come from Lamina PDF's own reading of the file, never from the renderer. Lamina PDF also checks that the two agree: its tests compare each page's size and every character's position with PDFium's.
+PDFium is C++ reading files you didn't write, so Lamina PDF keeps it at arm's length. The viewer runs it inside a Web Worker, away from your page. PDFium never changes the document either: every edit goes through Lamina PDF, which also writes the saved file. Text, selection and links come from Lamina PDF's own model of the file, never from the renderer. Lamina PDF also checks that the two agree: its tests compare each page's size and every character's position with PDFium's. [How a page is drawn](../../pages/concepts/drawing-pages.md) shows the two side by side.
 
 ## You pay for PDFium only when you show pages
 

package/docs/pages/concepts/drawing-pages.md

@@ -0,0 +1,76 @@
+---
+title: "How a page is drawn"
+description: "A renderer turns a page into pixels; Lamina PDF reads the page's text, links and selection itself, from the same bytes."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/concepts/drawing-pages/"
+---
+
+# How a page is drawn
+
+A renderer turns a page into pixels; Lamina PDF reads the page's text, links and selection itself, from the same bytes.
+
+Two readers go through every page you show. A renderer, PDFium or hayro, turns the page into pixels. Lamina PDF's own model of the file gives you everything you can select, search or click: the text, the links and the selection boxes. Both read the same bytes.
+
+*A renderer draws the pixels; Lamina PDF reads the text from the same bytes.*
+
+Two readers use your PDF's bytes. To draw, a render request names the page, the scale, the tile to draw (its clip) and a rotation. The request becomes a tile plan, which fixes the size in pixels, and a renderer, PDFium or hayro, draws the tile as RGBA pixels. Text, links and selection never come from the renderer. Lamina PDF reads them from its own model of the same bytes, the model that also edits and saves the file.
+
+## You ask for a tile, and get RGBA pixels back
+
+A render request names the page, the scale in pixels per point, and optionally a clip and a rotation. The clip is the part of the page you want, as a rectangle in pixels: a viewer asks for tiles of a large page rather than the whole page at once, so it only draws what's on screen. A scale of 2 draws 144 pixels per inch, sharp on most screens.
+
+Before it draws, the renderer turns the request into a tile plan: the whole page's size in pixels after the rotation, and the tile inside it. The renderer checks the tile against its limits first: by default, a tile wider or taller than 16,384 pixels, or larger than about 16.7 million pixels, fails with `render-too-large` instead of filling your memory. The renderer then draws the tile as straight RGBA, four bytes a pixel, row by row from the top-left corner.
+
+This example draws a page with hayro and reads the same page's text:
+
+`packages/sdk/examples/draw-page.ts`:
+
+```ts
+// Draws one page to pixels and reads the same page's text, to show who does which job: a renderer
+// turns the page into RGBA pixels, and Lamina PDF reads the text from its own model of the file.
+// Both read the same bytes. In Node, load the hayro renderer with the module's bytes:
+//
+//   const wasm = fileURLToPath(import.meta.resolve("@laminapdf/wasm/lamina_pdf_render_hayro.wasm"));
+//   const renderer = await initHayro(readFileSync(wasm));
+//
+// Text needs Lamina PDF's text or extract module: `await init({ text: true })`.
+
+import { bytesSource, type RenderBackend } from "@laminapdf/render";
+import { Document } from "@laminapdf/sdk";
+
+/** Pixels per point: 2 draws at 144 dpi, sharp on most screens. */
+const SCALE = 2;
+
+/** One page as pixels, with its text beside them. */
+export interface DrawnPage {
+  readonly width: number;
+  readonly height: number;
+  /** Straight RGBA, four bytes a pixel, row by row from the top-left corner. */
+  readonly pixels: Uint8ClampedArray;
+  readonly text: string;
+}
+
+/** Draws page `index` of `bytes` with `renderer` and reads its text with Lamina PDF. */
+export function drawPage(renderer: RenderBackend, bytes: Uint8Array, index: number): DrawnPage {
+  // The renderer draws the page and nothing else: it never supplies text, links or selection.
+  using drawing = renderer.open(bytesSource(bytes));
+  const { width, height, pixels } = drawing.render({ page: index, scale: SCALE });
+  // The text comes from Lamina PDF, which also edits and saves the file, so what you select is what
+  // an edit changes.
+  using doc = Document.open(bytes);
+  const text = doc.page(index).text().text();
+  return { width, height, pixels, text };
+}
+```
+
+## The text never comes from the renderer
+
+A renderer draws glyphs, but its idea of the text can differ from the file's: it may guess the order of letters or lose the characters behind a ligature. So Lamina PDF reads text, links and selection from its own model of the file, the same model that edits and saves it. What you select is what `page.text()` returns and what an edit changes.
+
+The two readers can still disagree on where a glyph sits, since each reads the fonts its own way. Lamina PDF's tests compare each page's size and every character's position with PDFium's, and a difference becomes a bug to fix.
+
+## PDFium in the browser, hayro on servers
+
+PDFium, the engine behind Chrome's PDF viewer, draws the pages in the viewer. It runs in a Web Worker, away from your page, and only draws: it never changes the document. hayro is a renderer written in Rust. It's the lighter choice on a server or in a Cloudflare Worker, and it draws in the tests that compare pages. [What Lamina PDF writes and what it borrows](../../pages/concepts/dependencies.md) explains why each one is there.
+
+Next, see [how to compare pages in tests](../../pages/guides/test-generated-pdfs.md), which draws two PDFs and counts the pixels that differ.

package/docs/pages/concepts/errors-and-warnings.md

@@ -1,7 +1,7 @@
 ---
 title: "Errors and warnings"
 description: "One coded error shape on every surface, and warnings for what Lamina PDF repaired."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/concepts/errors-and-warnings/"
 ---
 
@@ -21,7 +21,11 @@ A warning means the call went ahead, but Lamina PDF had to repair, drop or appro
 
 ## Every surface has the same fields
 
-Errors and warnings have the same fields in TypeScript and Rust: `code`, `kind`, `message`, `hint`, `location`, `data` and `docsUrl`. `toJSON()` in TypeScript gives the same object as `serde` does in Rust, so a server and a browser can pass them to each other unchanged.
+Errors and warnings have the same fields in TypeScript and Rust: `code`, `kind`, `message`, `hint`, `location`, `data` and `docsUrl`. A usage error can also carry `didYouMean`, the closest names to one Lamina PDF didn't recognise. `toJSON()` in TypeScript gives the same object as `serde` does in Rust, so a server and a browser can pass them to each other unchanged.
+
+*A call stops with an error or completes with warnings, and both carry the same core fields.*
+
+A call either stops with a `LaminaPdfError` or completes, with any warnings on `doc.warnings`. Errors and warnings carry the same fields: `code`, `kind`, `message`, `hint`, `location`, `data` and `docsUrl`; an error can also carry `didYouMean`. Text from the document goes only in `data`, never in `message` or `hint`.
 
 - **`kind` sorts errors by who can fix them**, such as `input`, `limit`, `usage`, `state` or `io`. For example, a server returns a 4xx status for `input` and `limit` and a 5xx for the rest, as the [Cloudflare Workers quick start](../../pages/quick-start/workers.md) does.
 - **Text from the document is untrusted**, so it never appears in `message` or `hint`. It goes only in `data`, where you can escape it before you show it.