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

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

@@ -0,0 +1,38 @@
+---
+title: "would-invalidate-signatures"
+version: "0.2.0-alpha.4"
+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.4"
+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.4"
+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.

package/docs/errors/xobject-cycle.md

@@ -0,0 +1,36 @@
+---
+title: "xobject-cycle"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/xobject-cycle/"
+---
+
+# xobject-cycle
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A Form XObject draws itself, directly or through other forms; the inner `Do` was skipped.
+
+## Why
+
+A malformed or hostile file: forms that draw each other without end would never finish.
+
+## How to fix
+
+Nothing to do.
+
+## Example
+
+```text
+8 0 obj << /Subtype /Form /Resources << /XObject << /Me 8 0 R >> >> >> stream /Me Do endstream
+```
+
+The form draws itself: the inner `/Me Do` is skipped once Lamina PDF sees form 8 a second time.
+
+## Data fields
+
+- `object`: the form reached again.
+
+The `location` is `object` (the form reached again).

package/docs/errors/xref-repaired.md

@@ -0,0 +1,36 @@
+---
+title: "xref-repaired"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/xref-repaired/"
+---
+
+# xref-repaired
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+The stored cross-reference data was unusable and was rebuilt by scanning the file.
+
+## Why
+
+Edited, truncated or concatenated files often have stale offsets.
+
+## How to fix
+
+Nothing, if the result is right. Incremental saves refuse a repaired base (`repaired-base`); save in full instead.
+
+## Example
+
+```text
+startxref
+123456
+%%EOF
+```
+
+`startxref` points past the end of a file that was truncated and re-padded. Lamina PDF scans the file for `n g obj` headers, rebuilds the table, raises `xref-repaired` and opens normally. `save(SaveMode::Incremental)` is then refused with [`repaired-base`](repaired-base.md); `SaveMode::Auto` rewrites the file.
+
+## Data fields
+
+None.

package/docs/errors/xrefstm-ignored.md

@@ -0,0 +1,34 @@
+---
+title: "xrefstm-ignored"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/xrefstm-ignored/"
+---
+
+# xrefstm-ignored
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A hybrid file's `/XRefStm` could not be read and was ignored.
+
+## Why
+
+Hybrid files carry a classic xref table for old readers and an xref stream for objects in object streams. An editor that moved bytes without updating `/XRefStm`, or a damaged stream, leaves the stream unreadable.
+
+## How to fix
+
+Nothing; the classic table is used.
+
+## Example
+
+```text
+trailer << /Size 40 /Root 1 0 R /XRefStm 99999 >>
+```
+
+A hybrid-reference file (ISO 32000-2 §7.5.8.4) points `/XRefStm` at an offset with no stream. Lamina PDF ignores it and reads the classic table; objects only the stream listed may be missing.
+
+## Data fields
+
+`offset` (where `/XRefStm` points).

package/docs/llms.txt

@@ -0,0 +1,94 @@
+# Lamina PDF
+
+> 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.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)
+
+## Start here
+
+- [Lamina PDF](pages/index.md): Create, read, edit and save PDFs from Rust and TypeScript, with one Rust core that runs natively and as WebAssembly.
+- [Install](pages/install.md): Install Lamina PDF from npm or crates.io, and find every published package.
+- [Your first PDF](pages/start/first-pdf.md): Write hello.pdf from Node in five minutes.
+- [Use Lamina PDF with coding agents](pages/start/coding-agents.md): Point a coding agent at the docs inside the installed package, so its answers match the version you use.
+
+## Your runtime
+
+- [Browser and bundlers](pages/quick-start/browser.md): Load @laminapdf/sdk in a web page through Vite or another bundler.
+- [Node](pages/quick-start/node.md): Generate a PDF from Node with @laminapdf/sdk.
+- [Deno](pages/quick-start/deno.md): Use @laminapdf/sdk in Deno.
+- [Bun](pages/quick-start/bun.md): Use @laminapdf/sdk in Bun.
+- [Cloudflare Workers](pages/quick-start/workers.md): Generate PDFs per request in a Cloudflare Worker.
+- [Rust](pages/quick-start/rust.md): Generate a PDF with the Lamina PDF crate.
+
+## Concepts
+
+- [How Lamina PDF thinks about a PDF](pages/concepts/how-lamina-thinks.md): Bytes in and out, the same bytes every time, edits kept apart from the opened file, two ways to save, memory you free, three JavaScript modules.
+- [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.
+
+## Read and edit PDFs
+
+- [Edit a PDF](pages/guides/edit-a-pdf.md): Change an existing PDF in transactions you can undo, and replay edits stored as JSON.
+- [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
+
+- [Recipes](pages/recipes.md): Complete Lamina PDF programs, from one page of text to an archived invoice, each with its code and the PDF it writes.
+- [Hello, world](pages/recipes/hello.md): One A4 page with a line of text in a standard 14 font, the smallest PDF Lamina PDF writes, in TypeScript and Rust.
+- [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.
+- [A PDF/UA report](pages/recipes/pdf-ua-report.md): A one-page sales report a screen reader can follow, with headings, a table, a described chart and a link, checked against PDF/UA-1 as it's built.
+- [A PDF/A archive](pages/recipes/pdf-a-archive.md): An order confirmation for long-term archiving, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1, with an embedded font and a photo.
+- [A PDF/A-3 invoice with XML](pages/recipes/pdf-a3-invoice-with-xml.md): A PDF/A-3b invoice that carries the same invoice as an attached XML file, for people to read and for software to process.
+- [A 100-page report](pages/recipes/report.md): A 100-page A4 report with two embedded fonts and a table on every page, the document Lamina PDF times in each JavaScript runtime.
+- [Open someone else's file](pages/recipes/open-untrusted.md): Open an uploaded PDF with an optional password and tighter limits, and get its page count and warnings, or the error, back as a value.
+- [Save in a Web Worker](pages/recipes/web-worker-client.md): Open and save a PDF in a Web Worker, so a large file never freezes the page, with progress as it saves and a signal that stops the work.
+- [A Cloudflare Worker](pages/recipes/cloudflare-worker.md): A Cloudflare Worker that returns a one-page letter per request, in a standard 14 font or a bundled one, and a 400 for a name the font can't draw.
+
+## Troubleshooting
+
+- [Troubleshooting](pages/troubleshooting.md): The problems people hit with Lamina PDF, from a missing init() to a signed file that won't save, with the cause and the fix of each.
+
+## Reference
+
+- [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.
+
+## API reference
+
+- [@laminapdf/sdk](api/README.md)
+
+## Optional
+
+- [Error and warning codes](errors/README.md)

package/docs/pages/concepts/dependencies.md

@@ -0,0 +1,44 @@
+---
+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.4"
+url: "https://docs.laminapdf.com/concepts/dependencies/"
+---
+
+# What Lamina PDF writes and what it borrows
+
+Lamina PDF writes the parts that decide a PDF's bytes, borrows the rest from permissive projects, and pins and checks everything it borrows.
+
+Add `@laminapdf/viewer` to your app, and it downloads about 2 MB of WebAssembly from a project called EmbedPDF. That WebAssembly is PDFium, the C++ engine behind Chrome's PDF viewer. You may wonder why a Rust library ships someone else's C++, and what else comes along with it. Lamina PDF follows one rule: it writes the parts that decide what your PDF contains. It borrows the rest only from permissively licensed projects that do the job better, and it pins and checks every borrowed piece.
+
+## Lamina PDF writes the parts that decide your bytes
+
+Lamina PDF's own Rust code reads, edits and saves your PDFs. Those parts take files from strangers, and they decide every byte of the file you save. A bug there corrupts documents or breaks signatures, so Lamina PDF owns them. Rust also keeps that code memory-safe while it reads damaged or hostile files. And because Lamina PDF wrote it, the same input gives the same bytes in a browser, on a server and inside a Cloudflare Worker.
+
+## It borrows the work others already do well
+
+Fonts and text shaping are deep problems with good open-source answers, so Lamina PDF reuses them. `skrifa` reads font files, `subsetter` cuts them down to the glyphs you use, and HarfRust shapes Arabic, Hindi and other scripts. ICU4X finds line breaks, and `pdf-writer` writes PDF syntax. Each one is permissively licensed Rust that compiles to WebAssembly. Lamina PDF measured krilla, a complete PDF generator built on the same crates. But krilla can't add content to a file you opened, so Lamina PDF builds on the crates beneath it.
+
+## Drawing pages is the one job it hands to PDFium
+
+Lamina PDF hands one big job to another project: turning pages into pixels. Real-world PDFs often break the specification, and PDFium draws them for everyone who opens a PDF in Chrome. Lamina PDF measured the alternative, hayro, a renderer written in Rust. It drew 91% of 2,196 test pages the same as PDFium or close to it, and most of the rest went wrong on fonts and annotations. A viewer that becomes an editor needs that fidelity from the start, so PDFium draws the pages. `@embedpdf/pdfium` is PDFium compiled to WebAssembly.
+
+## 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 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
+
+`@laminapdf/sdk`, the package that creates, reads and edits PDFs, depends only on `@laminapdf/wasm`, Lamina PDF's own WebAssembly. PDFium comes only with `@laminapdf/render-pdfium` and the viewer built on it. For pages as pixels on a server or in a Cloudflare Worker, `@laminapdf/render-hayro` is the lighter choice: pure Rust, with no C++, and a smaller download than PDFium. Every night, Lamina PDF's tests draw thousands of pages with both renderers, so hayro can take over once it matches PDFium.
+
+## Every dependency is permissively licensed
+
+Lamina PDF is `MIT OR Apache-2.0`, so you can use it in a closed product or a paid service. That promise only holds if every dependency allows the same. So Lamina PDF accepts no GPL, AGPL or LGPL code in anything it ships, and a licence check enforces the rule on every change. MuPDF is a fine PDF engine, but it is AGPL, so Lamina PDF never uses it, in any form. Copyleft tools such as veraPDF run as separate programs in Lamina PDF's tests and are never shipped.
+
+## Everything borrowed is pinned and checked
+
+A dependency can change under you, so Lamina PDF's lockfiles pin every one to an exact version. For PDFium, Lamina PDF goes further: the build checks the SHA-256 of `pdfium.wasm`, and any other file fails the build. `@embedpdf/pdfium` ships no notices for the libraries compiled into it, such as libpng, zlib and FreeType. So `@laminapdf/render-pdfium` includes a third-party notices file, and an app that bundles it ships that file too. An update to PDFium arrives as its own reviewed change, and the next release picks up its security fixes.
+
+## What this means for your app
+
+You can build Lamina PDF into closed software, and `@laminapdf/sdk` brings no third-party engine with it. Add the viewer when you need to show pages, and ship PDFium's notices file with it. Next, see [how Lamina PDF thinks about a PDF](../../pages/concepts/how-lamina-thinks.md), or start with [your first PDF](../../pages/start/first-pdf.md).

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

@@ -0,0 +1,68 @@
+---
+title: "Errors and warnings"
+description: "One coded error shape on every surface, and warnings for what Lamina PDF repaired."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/concepts/errors-and-warnings/"
+---
+
+# Errors and warnings
+
+One coded error shape on every surface, and warnings for what Lamina PDF repaired.
+
+Real PDFs are often damaged, so Lamina PDF separates a call that failed from one that worked around a problem. An error stops the call. A warning lets it finish and tells you what was repaired, dropped or approximated. Both carry a stable code your program can branch on.
+
+## Errors stop the call
+
+In TypeScript an error is a `LaminaPdfError`, and in Rust it's a `laminapdf::Error`. Branch on its `code`, never on its `message`: `isLaminaPdfError(e, "wrong-password")` checks the code and narrows the type in one step.
+
+## Warnings say what was repaired
+
+A warning means the call went ahead, but Lamina PDF had to repair, drop or approximate something in the file. Read them with `doc.warnings` in TypeScript or `doc.warnings()` in Rust. Show them to the user when the difference matters, such as a page that may not look the way its author intended.
+
+## 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`. 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.
+
+This example opens someone else's file and returns the error's code and hint as a value, instead of letting the error escape:
+
+`packages/sdk/examples/open-untrusted.ts`:
+
+```ts
+// Open bytes from someone else: an optional password, tighter limits than the defaults, and the
+// outcome as a value rather than an exception. The example writes nothing: it returns what it found.
+import { Document, isLaminaPdfError } from "@laminapdf/sdk";
+
+const MiB = 1024 * 1024;
+/** Limits for an upload endpoint: each decoded stream, and all of them together. */
+const LIMITS = { maxStreamDecoded: 16 * MiB, maxDecodedTotal: 64 * MiB } as const;
+
+/** What opening a file gave: its page count and warning codes, or why it didn't open. */
+export type Opened =
+  | { readonly ok: true; readonly pages: number; readonly warnings: readonly string[] }
+  | { readonly ok: false; readonly code: string; readonly hint: string | undefined };
+
+/** Opens `bytes`, with `password` if the file needs one, under {@link LIMITS}. Needs `init()`. */
+export function openUntrusted(bytes: Uint8Array, password?: string): Opened {
+  try {
+    using doc = Document.open(bytes, { ...(password === undefined ? {} : { password }), limits: LIMITS });
+    // Repairs and dropped values are warnings: the file opened, but not exactly as written.
+    return { ok: true, pages: doc.pageCount, warnings: doc.warnings.map((w) => w.code) };
+  } catch (e) {
+    // `password-required`, `wrong-password`, `not-pdf`, `limit-exceeded`, …: a coded error whose
+    // message and hint never contain text from the file. Anything else is a bug: let it throw.
+    if (isLaminaPdfError(e)) return { ok: false, code: e.code, hint: e.hint };
+    throw e;
+  }
+}
+```
+
+The [error and warning codes](../../errors/README.md) list every code with its kind, a summary and a hint.
+
+Next: make a PDF with [text and fonts](../../pages/guides/fonts-and-text.md).

package/docs/pages/concepts/how-lamina-thinks.md

@@ -0,0 +1,98 @@
+---
+title: "How Lamina PDF thinks about a PDF"
+description: "Bytes in and out, the same bytes every time, edits kept apart from the opened file, two ways to save, memory you free, three JavaScript modules."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/concepts/how-lamina-thinks/"
+---
+
+# How Lamina PDF thinks about a PDF
+
+Bytes in and out, the same bytes every time, edits kept apart from the opened file, two ways to save, memory you free, three JavaScript modules.
+
+The rest of the docs build on six ideas. The first two follow from one choice: Lamina PDF treats a PDF as bytes, which you give it and it gives back.
+
+## Bytes in, bytes out
+
+Lamina PDF's core never touches the file system or the network, and it never reads the clock. Your app reads the file, hands Lamina PDF the bytes and stores whatever comes back. The only fetches are the ones you ask for, such as opening a remote file by range requests. That's why the same code runs in a browser, on a server and inside a Cloudflare Worker.
+
+## Same input, same bytes
+
+Because Lamina PDF reads no clock, you pass in dates and file IDs yourself. It then writes the same bytes for the same input, on every run and every platform, so you can test, cache and compare its output byte for byte.
+
+## The file you opened never changes
+
+When you open a document, Lamina PDF keeps its bytes exactly as they were. Every edit goes into an [overlay](../../pages/reference/glossary.md#overlay) on top of them. Reading the document reads the overlay first, so you see your edits; undo and redo move through them.
+
+*Edits go into an overlay; saving appends them or writes a new file.*
+
+Opening a PDF gives you a document that holds the file's original bytes, which never change, and an overlay for your edits. `doc.transact`, `undo` and `redo` write only to the overlay, and reading the document reads the overlay first. A save then either appends the edits after the original bytes (`incremental`) or writes every byte of a new file (`fullRewrite`). An incremental save leaves the original bytes untouched, so signatures over them stay valid.
+
+## Two ways to save
+
+A save writes the overlay out in one of two ways:
+
+- **[Incremental save](../../pages/reference/glossary.md#incremental-save):** the original bytes, unchanged, followed by a new revision that holds your edits. Signatures over the original stay valid.
+- **[Full rewrite](../../pages/reference/glossary.md#full-rewrite):** the whole file written again, smaller and tidier, but no longer the original bytes.
+
+The default, `auto`, saves incrementally when it can. A signed file saves only incrementally, and a save fails if your edits break its signatures, unless you pass `invalidateSignatures: true`. [Save a PDF](../../pages/guides/save-a-pdf.md) has the details.
+
+This example builds a document, opens its bytes, changes the title and saves incrementally. The saved file starts with the original bytes:
+
+**TypeScript**
+
+`packages/sdk/examples/generate-then-edit.ts`:
+
+```ts
+// Generate a document, then open its bytes, edit them and save incrementally. The edit changes
+// the Info dictionary in one transaction, and the incremental save keeps the generated bytes as
+// they are, with one revision appended.
+import { Builder, type BuilderOptions, Document, Font } from "@laminapdf/sdk";
+
+/**
+ * The generated file followed by the edit's revision. Needs `init({ text: true })`.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ * @param editedAt - the modification date to record, as a PDF date string.
+ */
+export function generateThenEdit(options: BuilderOptions = {}, editedAt?: string): Uint8Array<ArrayBuffer> {
+  return edit(generate(options), editedAt);
+}
+
+/** A one-page draft, saved (a new document is always saved as a full rewrite). */
+export function generate(options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const page = b.page("A4");
+  page.surface().text("Draft report", { font: Font.standard("Helvetica"), size: 20, at: [72, 96] });
+  page.finish();
+  b.metadata({ title: "Draft report" });
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** Opens `bytes`, edits the Info dictionary in one transaction (which `undo` could revert) and saves incrementally. */
+function edit(bytes: Uint8Array, editedAt?: string): Uint8Array<ArrayBuffer> {
+  using doc = Document.open(bytes);
+  doc.transact((tx) => tx.setInfo({ title: "Final report", author: "Ada Lovelace" }, editedAt));
+  return doc.save({ mode: "incremental" });
+}
+```
+
+**Result:** [generate_then_edit.pdf](https://docs.laminapdf.com/examples/pdf/generate_then_edit.pdf)
+
+## You free what you create
+
+In JavaScript, documents and builders live in WebAssembly memory. The garbage collector frees them eventually, but late, so free each one when you're done: `using doc = …` frees it at the end of the block, and `doc.free()` frees it at once. A short script can skip this, but a long-running server shouldn't.
+
+## Three modules in JavaScript
+
+In JavaScript, Lamina PDF is WebAssembly, split into three modules so a page downloads only what it uses:
+
+- **Base:** open, read, edit and save; vector and image pages.
+- **Extract:** everything in base, plus text extraction.
+- **Text:** everything in base, plus fonts, shaped text and extraction.
+
+`init()` loads the base module, and `init({ text: true })` or `init({ extract: true })` loads one of the others. Call `loadText()` or `loadExtract()` to add a module later, when a page first needs it. Rust has one crate, with features instead.
+
+*The three modules come in @laminapdf/wasm, under @laminapdf/sdk.*
+
+`@laminapdf/sdk` depends on `@laminapdf/wasm`, whose WebAssembly the SDK loads as three modules: base, extract and text. `@laminapdf/viewer` depends on `@laminapdf/sdk`, on `@laminapdf/render` and on both renderers that implement it, `@laminapdf/render-pdfium` and `@laminapdf/render-hayro`. In Rust, the API is one crate, `laminapdf`, with features instead of modules.