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

package/docs/pages/recipes/multilingual.md

@@ -1,7 +1,7 @@
 ---
 title: "Multilingual text"
 description: "Latin, Arabic, Devanagari, Hebrew and Chinese on one page, each in its own embedded font, as a shaped line and a wrapped paragraph."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/multilingual/"
 ---
 
@@ -13,7 +13,9 @@ You'll put five scripts on one page: Latin, Arabic, Devanagari, Hebrew and Chine
 
 The function takes one font file per script, draws each script's line and paragraph, and returns the PDF's bytes. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
 
-<TabItem label="TypeScript">`packages/sdk/examples/multilingual.ts`:
+**TypeScript**
+
+`packages/sdk/examples/multilingual.ts`:
 
 ```ts
 // Five scripts on one page, each as a single line and as a wrapped paragraph. The scripts are
@@ -69,8 +71,11 @@ export function multilingual(fonts: readonly Uint8Array[], options: BuilderOptio
   using doc = b.finish();
   return doc.save();
 }
-```</TabItem>
-<TabItem label="Rust">`crates/laminapdf/examples/multilingual.rs`:
+```
+
+**Rust**
+
+`crates/laminapdf/examples/multilingual.rs`:
 
 ````rust
 //! Five scripts on one page, each as a single line and as a wrapped paragraph.
@@ -167,9 +172,11 @@ pub(crate) fn build(options: BuildOptions, fonts: Vec<Vec<u8>>) -> Result<Vec<u8
     let mut doc = b.finish()?;
     Ok(doc.save(&SaveOptions::new())?.bytes)
 }
-````</TabItem>
+````
+
+**Result:** [multilingual.pdf](https://docs.laminapdf.com/examples/pdf/multilingual.pdf)
 
-The result is one A4 page, with each script set in its own Noto font: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/multilingual.pdf).
+The result is one A4 page, with each script set in its own Noto font. The Result tab shows it, with a link to the PDF.
 
 ## How it works
 

package/docs/pages/recipes/open-untrusted.md

@@ -1,7 +1,7 @@
 ---
 title: "Open someone else's file"
 description: "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."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/open-untrusted/"
 ---
 

package/docs/pages/recipes/pdf-a-archive.md

@@ -1,7 +1,7 @@
 ---
 title: "A PDF/A archive"
 description: "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."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/pdf-a-archive/"
 ---
 
@@ -13,7 +13,9 @@ You'll write a letter confirming an order as a PDF/A file, which looks the same
 
 The function takes the level, `2b` or `2u`, and builds the same letter under that level's profiles. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
 
-<TabItem label="TypeScript">`packages/sdk/examples/pdf-a-archive.ts`:
+**TypeScript**
+
+`packages/sdk/examples/pdf-a-archive.ts`:
 
 ```ts
 // An archival letter, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1.
@@ -78,8 +80,11 @@ function draw(s: Surface, font: Font, photo: Image): void {
     s.text("Acme Widgets Ltd, 1 Example Street, London", { font, size: BODY, at: [MARGIN, FOOTER_BASELINE] }),
   );
 }
-```</TabItem>
-<TabItem label="Rust">`crates/laminapdf/examples/pdf_a_archive.rs`:
+```
+
+**Rust**
+
+`crates/laminapdf/examples/pdf_a_archive.rs`:
 
 ```rust
 //! An archival letter, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1.
@@ -182,9 +187,11 @@ fn draw(s: &mut Surface, font: &FontHandle, photo: &Image) -> Result<(), BuildEr
     let footer = "Acme Widgets Ltd, 1 Example Street, London";
     s.tag(TagKind::P, |s| s.text(footer, font, BODY, FOOTER_AT).map(drop))
 }
-```</TabItem>
+```
+
+**Result:** [pdf_a_archive-2b.pdf](https://docs.laminapdf.com/examples/pdf/pdf_a_archive-2b.pdf), [pdf_a_archive-2u.pdf](https://docs.laminapdf.com/examples/pdf/pdf_a_archive-2u.pdf)
 
-The result is one A4 letter under a translucent blue band, with a photo beside its text: open the [PDF/A-2b](https://docs.laminapdf.com/examples/pdf/pdf_a_archive-2b.pdf) or the [PDF/A-2u](https://docs.laminapdf.com/examples/pdf/pdf_a_archive-2u.pdf) reference PDF.
+The result is one A4 letter under a translucent blue band, with a photo beside its text: the Result tab shows both versions, PDF/A-2b and PDF/A-2u, with links to the PDFs.
 
 ## How it works
 

package/docs/pages/recipes/pdf-a3-invoice-with-xml.md

@@ -1,7 +1,7 @@
 ---
 title: "A PDF/A-3 invoice with XML"
 description: "A PDF/A-3b invoice that carries the same invoice as an attached XML file, for people to read and for software to process."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/pdf-a3-invoice-with-xml/"
 ---
 
@@ -13,7 +13,9 @@ You'll write a one-page invoice as PDF/A-3b, with the same invoice attached as X
 
 The function draws the invoice, writes the same items as XML and attaches that file before it finishes. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
 
-<TabItem label="TypeScript">`packages/sdk/examples/pdf-a3-invoice-with-xml.ts`:
+**TypeScript**
+
+`packages/sdk/examples/pdf-a3-invoice-with-xml.ts`:
 
 ```ts
 // A PDF/A-3b invoice that carries the same invoice as XML, attached for software to read.
@@ -98,8 +100,11 @@ function draw(s: Surface, font: Font): void {
     link: { target: { type: "uri", uri: "https://example.com/invoices/42" }, contents: "Invoice 42 online" },
   });
 }
-```</TabItem>
-<TabItem label="Rust">`crates/laminapdf/examples/pdf_a3_invoice_with_xml.rs`:
+```
+
+**Rust**
+
+`crates/laminapdf/examples/pdf_a3_invoice_with_xml.rs`:
 
 ```rust
 //! A PDF/A-3b invoice that carries the same invoice as XML, attached for software to read.
@@ -200,9 +205,11 @@ fn draw(s: &mut Surface, font: &FontHandle) -> Result<(), BuildError> {
     note.link(online, Some("Invoice 42 online".into()));
     Ok(())
 }
-```</TabItem>
+```
+
+**Result:** [pdf_a3_invoice_with_xml.pdf](https://docs.laminapdf.com/examples/pdf/pdf_a3_invoice_with_xml.pdf)
 
-The result is one A4 page with three line items and a total of € 99.40, carrying `invoice-42.xml`: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/pdf_a3_invoice_with_xml.pdf). Viewers that show attachments list it there.
+The result is one A4 page with three line items and a total of € 99.40, carrying `invoice-42.xml`. The Result tab shows it, with a link to the PDF. Viewers that show attachments list it there.
 
 ## How it works
 

package/docs/pages/recipes/pdf-ua-report.md

@@ -1,7 +1,7 @@
 ---
 title: "A PDF/UA report"
 description: "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."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/pdf-ua-report/"
 ---
 
@@ -13,7 +13,9 @@ You'll build a one-page sales report that a screen reader can follow: headings,
 
 The function turns on the PDF/UA-1 profile, then draws each part of the report inside a tag that says what it is: a heading, a table cell, a figure. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
 
-<TabItem label="TypeScript">`packages/sdk/examples/pdf-ua-report.ts`:
+**TypeScript**
+
+`packages/sdk/examples/pdf-ua-report.ts`:
 
 ```ts
 // An accessible report that screen readers can follow, checked against PDF/UA-1 when it is built.
@@ -110,8 +112,11 @@ function chart(s: Surface): void {
     });
   });
 }
-```</TabItem>
-<TabItem label="Rust">`crates/laminapdf/examples/pdf_ua_report.rs`:
+```
+
+**Rust**
+
+`crates/laminapdf/examples/pdf_ua_report.rs`:
 
 ```rust
 //! An accessible report that screen readers can follow, checked against PDF/UA-1 when it is built.
@@ -214,9 +219,11 @@ fn chart(s: &mut Surface) -> Result<(), BuildError> {
         Ok(())
     })
 }
-```</TabItem>
+```
+
+**Result:** [pdf_ua_report.pdf](https://docs.laminapdf.com/examples/pdf/pdf_ua_report.pdf)
 
-The result is one A4 page that reads, in order, as a title, a summary, a table of four quarters, a bar chart and a link: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/pdf_ua_report.pdf).
+The result is one A4 page that reads, in order, as a title, a summary, a table of four quarters, a bar chart and a link. The Result tab shows it, with a link to the PDF.
 
 ## How it works
 

package/docs/pages/recipes/report.md

@@ -1,7 +1,7 @@
 ---
 title: "A 100-page report"
 description: "A 100-page A4 report with two embedded fonts and a table on every page, the document Lamina PDF times in each JavaScript runtime."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/report/"
 ---
 
@@ -104,7 +104,7 @@ function cell([left, width]: readonly [number, number], baseline: number): Rect
 }
 ```
 
-The result is 100 A4 pages, one per region. It has no reference PDF to open. Instead, Lamina PDF's tests build and time the report in every JavaScript runtime and check its SHA-256 there, as does the Rust benchmark that builds the same bytes.
+The result is 100 A4 pages, one per region. It has no reference PDF to open. Instead, Lamina PDF's tests build and time the report in every JavaScript runtime and check its SHA-256 there, as does the Rust benchmark that builds the same bytes. [Benchmarks](../../pages/reference/benchmarks.md) has the timings.
 
 ## How it works
 

package/docs/pages/recipes/web-worker-client.md

@@ -1,7 +1,7 @@
 ---
 title: "Save in a Web Worker"
 description: "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."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/web-worker-client/"
 ---
 

package/docs/pages/recipes.md

@@ -1,7 +1,7 @@
 ---
 title: "Recipes"
 description: "Complete Lamina PDF programs, from one page of text to an archived invoice, each with its code and the PDF it writes."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/"
 ---
 
@@ -11,7 +11,7 @@ Complete Lamina PDF programs, from one page of text to an archived invoice, each
 
 Each recipe is a complete program to copy: what it makes, the code, how it works and what to change. Pick the one closest to the document you need, and change it from there.
 
-Most recipes exist twice, in Rust and in TypeScript, and both write exactly the same bytes. Lamina PDF's tests check that on every change, in Rust and in every JavaScript runtime: Node, Chromium, Firefox, WebKit, Deno, Bun and workerd. Each recipe shows the tested code, and its reference PDF is the file that code writes.
+Most recipes exist twice, in Rust and in TypeScript, and both write exactly the same bytes. Lamina PDF's tests check that on every change, in Rust and in every JavaScript runtime: Node, Chromium, Firefox, WebKit, Deno, Bun and workerd. Each recipe shows the tested code, and its reference PDF is the file that code writes. To test your own PDFs the same way, see [Test the PDFs you generate](../pages/guides/test-generated-pdfs.md).
 
 To run a Rust recipe from a checkout of Lamina PDF, use `cargo run -p laminapdf --example <name>`. Its header comment lists the arguments it takes, such as the font or image files it reads.
 
@@ -21,6 +21,7 @@ To run a Rust recipe from a checkout of Lamina PDF, use `cargo run -p laminapdf
 - [An invoice](../pages/recipes/invoice.md): an embedded font, a table of line items, and tags for screen readers.
 - [Multilingual text](../pages/recipes/multilingual.md): five scripts, each in its own embedded font.
 - [Images and vectors](../pages/recipes/images-and-vectors.md): paths, colour, transparency, a clip and two images.
+- [Element flow](../pages/recipes/element-flow.md): a report whose parts each start below the one before, over two pages.
 - [Links and outlines](../pages/recipes/links-and-outlines.md): links, an outline and page labels.
 
 ## Edit a PDF

package/docs/pages/reference/benchmarks.md

@@ -0,0 +1,93 @@
+---
+title: "Benchmarks"
+description: "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."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/benchmarks/"
+---
+
+# Benchmarks
+
+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.
+
+These are Lamina PDF's measured numbers: how long it takes to make a PDF in each runtime, how much your app downloads, and how well it extracts text from a public benchmark of real pages. Each table states the version, the date and the machine it came from, so you can judge how the numbers apply to yours.
+
+## How long a PDF takes to make
+
+Each figure is the time to build a document and save it to bytes, after the WebAssembly module has loaded. Every runtime builds the same three documents and gets the same bytes:
+
+- **First PDF:** the first one-page "Hello" PDF after `init()`, before the runtime has optimised anything.
+- **Hello:** the same PDF afterwards, the median of 20 builds.
+- **One-page invoice:** the [invoice recipe](../../pages/recipes/invoice.md), a tagged A4 page with an embedded font and a table of items, the median of 20 builds.
+- **100-page report:** the [report recipe](../../pages/recipes/report.md), with two embedded fonts and a table on every page, the median of 3 builds.
+
+| Runtime | Version | First PDF | Hello | One-page invoice | 100-page report | WebAssembly memory |
+| --- | --- | ---: | ---: | ---: | ---: | ---: |
+| Node 24 | 24.19.0 | 19.8 ms | 0.8 ms | 3.5 ms | 222 ms | 4.3 MB |
+| Deno | 2.9.6 | 23.8 ms | 0.7 ms | 3.6 ms | 238 ms | 4.3 MB |
+| Bun | 1.4.4 | 14.9 ms | 1.4 ms | 3.6 ms | 151 ms | 4.3 MB |
+| Cloudflare Workers (workerd) | 4.152.0 | 25.0 ms | 2.0 ms | 5.0 ms | 226 ms | 4.3 MB |
+| Chromium | 1.64.1 | 18.3 ms | 0.7 ms | 3.7 ms | 215 ms | 4.3 MB |
+| Firefox | 1.64.1 | 2.0 ms | 1.0 ms | 5.0 ms | 313 ms | 4.3 MB |
+| WebKit (Safari's engine) | 1.64.1 | 28.0 ms | 2.5 ms | 4.0 ms | 169 ms | 4.3 MB |
+| Rust, native | 1.99.1 | – | – | 0.9 ms | 45.9 ms | – |
+
+Measured with Lamina PDF 0.2.0-alpha.3 (commit `40c4179`) on 8 November 2026, on Apple M1 Pro (8 cores, 16 GB of memory), macOS 27.0.1, with a load average of 8.2 when the run began.
+
+The browsers run in Playwright at the version shown, and Cloudflare Workers run in workerd through wrangler. WebAssembly memory is the modules' memory after the reports, in megabytes of 1,000,000 bytes. It never shrinks, so it is their peak. The JavaScript heap isn't included. The native Rust row is the same invoice and report built by the `laminapdf` crate, the median build as measured by criterion, a Rust benchmarking library.
+
+## How much your app downloads
+
+`@laminapdf/sdk` loads one WebAssembly file, chosen by what you use. `base` reads, edits and saves documents and draws shapes and images; `text` adds fonts and text; `extract` adds text extraction without the fonts. Each file has a size budget, and a change that grows a file past its budget can't be merged until the budget is raised on purpose.
+
+| File | Gzip | Brotli | Budget (gzip) |
+| --- | ---: | ---: | ---: |
+| `lamina_pdf_base.wasm` | 400.0 kB | 318.2 kB | 410.0 kB |
+| `lamina_pdf_extract.wasm` | 668.1 kB | 519.0 kB | 690.0 kB |
+| `lamina_pdf_pdfium.wasm` | 2,158.0 kB | 1,653.6 kB | 2,243.2 kB |
+| `lamina_pdf_render_hayro.wasm` | 1,781.7 kB | 1,392.4 kB | 1,855.0 kB |
+| `lamina_pdf_text.wasm` | 1,153.0 kB | 875.5 kB | 1,200.0 kB |
+| `@laminapdf/sdk` (JavaScript) | 19.2 kB | – | 20.0 kB |
+| `@laminapdf/sdk/worker` (JavaScript) | 4.7 kB | – | 5.0 kB |
+| `@laminapdf/sdk/worker/entry` (JavaScript) | 19.2 kB | – | 20.0 kB |
+
+Measured with Lamina PDF 0.2.0-alpha.3 (commit `40c4179`) on 8 November 2026, on Apple M1 Pro (8 cores, 16 GB of memory), macOS 27.0.1, with a load average of 8.2 when the run began.
+
+Sizes are in kilobytes of 1,000 bytes, as a server sends them compressed. The JavaScript rows are `@laminapdf/sdk`'s code, minified: its API with the code that loads the WebAssembly, then the Web Worker client and the file that runs in the Web Worker.
+
+## How well it extracts text
+
+[olmOCR-bench](https://huggingface.co/datasets/allenai/olmOCR-bench), by the Allen Institute for AI, checks extracted text with small tests. A test checks that one passage comes before another, that a table cell sits beside its neighbours, or that a page's running header is left out. These figures use the three subsets made of pages that store their text, not scans, and the benchmark's own tests score the Markdown that Lamina PDF writes.
+
+| Subset | What it checks | Pages | Tests | Passed | Score |
+| --- | --- | ---: | ---: | ---: | ---: |
+| `multi_column` | reading order: 884 tests that one passage comes before another, on 231 multi-column pages | 231 | 884 | 461 | 52.1 % |
+| `table_tests` | tables: 1,020 tests that a cell's neighbours (up, down, left, right, headings) are right, and 2 baseline tests, on 188 pages | 188 | 1,022 | 245 | 24.0 % |
+| `headers_footers` | running headers, footers and page numbers left out: 753 tests, and 7 baseline tests, on 266 pages | 266 | 760 | 457 | 60.1 % |
+| Baseline | the page gave text, without long repeats (one test per page) | – | 676 | 578 | 85.5 % |
+
+Overall, as the benchmark averages its groups, 55.4 %; without the baseline group, 45.4 %. 672 pages were extracted and 13 failed. On one thread that is 428 pages a second, with a median of 2.0 ms a page.
+
+Measured with Lamina PDF 0.2.0-alpha.3 (commit `40c4179`) on 8 November 2026, on Apple M1 Pro (8 cores, 16 GB of memory), macOS 27.0.1, with a load average of 8.7 when the run began.
+
+Every page in the benchmark is a file of its own, so the time per page includes opening the file. A page with no text, such as a scan, counts against the score, as it would for you. Lamina PDF reads one page at a time on one thread here, without a layout model or OCR.
+
+### Also looking for tables without ruled lines
+
+Most tables in the benchmark have no ruled lines. Extraction finds tables like these when you ask it to look for text lined up in columns too: `tables: "lattice-and-stream"` in TypeScript, `TableMode::LatticeAndStream` in Rust. It finds more tables, but it reads some multi-column pages as tables, which costs those pages their reading order.
+
+| Subset | What it checks | Pages | Tests | Passed | Score |
+| --- | --- | ---: | ---: | ---: | ---: |
+| `multi_column` | reading order: 884 tests that one passage comes before another, on 231 multi-column pages | 231 | 884 | 131 | 14.8 % |
+| `table_tests` | tables: 1,020 tests that a cell's neighbours (up, down, left, right, headings) are right, and 2 baseline tests, on 188 pages | 188 | 1,022 | 480 | 47.0 % |
+| `headers_footers` | running headers, footers and page numbers left out: 753 tests, and 7 baseline tests, on 266 pages | 266 | 760 | 456 | 60.0 % |
+| Baseline | the page gave text, without long repeats (one test per page) | – | 676 | 578 | 85.5 % |
+
+Overall, as the benchmark averages its groups, 51.8 %; without the baseline group, 40.6 %. 672 pages were extracted and 13 failed. On one thread that is 375 pages a second, with a median of 2.0 ms a page.
+
+Measured with Lamina PDF 0.2.0-alpha.3 (commit `40c4179`) on 8 November 2026, on Apple M1 Pro (8 cores, 16 GB of memory), macOS 27.0.1, with a load average of 8.4 when the run began.
+
+## Where these numbers come from
+
+One command runs every measurement on one machine and writes the file this page reads, so no figure here is typed by hand. The numbers are one machine's, taken before a release. Each version of these docs keeps the numbers measured for it. Each table gives the machine's load average as its run began: how many jobs were running or waiting for a processor. A load average well above the core count means other jobs shared the machine, so the timings are slower than its best.
+
+Next: [make your first PDF](../../pages/start/first-pdf.md) and time it on your own machine.

package/docs/pages/reference/changelog.md

@@ -1,7 +1,7 @@
 ---
 title: "Changelog"
 description: "What changed in each Lamina PDF release, newest first."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/changelog/"
 ---
 
@@ -11,6 +11,54 @@ What changed in each Lamina PDF release, newest first.
 
 Every Lamina PDF package shares one version, so each entry covers all of them, from the Rust crates to `@laminapdf/sdk` and the viewer. Breaking changes come first, under **Minor Changes**, as the [stability policy](../../pages/reference/stability.md) explains. Versions from `0.2.0-alpha.2` on are on npm and crates.io; earlier ones were never published.
 
+## 0.2.0-alpha.4
+
+### Minor Changes
+
+- Extraction now leaves out text painted over by a later shape, image or annotation, as a reader can't see it either. A black box drawn over two words of a line takes those words out and keeps the rest of the line, so `Pay [box] now.` reads `Pay now.`. Covered text is listed under `dropped` with the new reason `covered`, its box and how many characters it held, never its text; `drop: { keepSpans: true }` shows it to an auditor. Only opaque paint drawn after the text covers it. A translucent box, a highlighter, shading under the text, a box in an optional layer and a scanned page's image over its own text layer all leave the text in. For Rust callers, `Flags` gains `covered`, `DropReason` gains `Covered`, and `BlendMode` now lives in `laminapdf-model` (`laminapdf::BlendMode` is unchanged).
+- Running headers, footers and watermarks can now say what they are. `surface.artifact("footer", s => …)` marks its content as a footer attached to the bottom of the page (`/Subtype /Footer /Attached [/Bottom]`), `"header"` as a header attached to the top, and `"watermark"` as a watermark. `"pagination"` still writes the plain form. In Rust it is `Artifact::footer()`, `Artifact::header()` and `Artifact::watermark()`, with `with_attached` for other edges.
+  
+A paragraph split by a page break can now stay one paragraph for screen readers. In Rust, `surface.open_element(TagKind::P)` places it, `surface.resume(id, |s| …)` draws its content on that page or a later one, and `builder.close_element(id)` writes it.
+  
+`surface.measure_text_box(…)` (Rust) returns the layout `text_box` would draw, without drawing it.
+  
+Arabic text with diacritics now builds under PDF/UA-1 and PDF/A-2u: a letter the font draws as a body and a dot no longer fails with `glyph-without-unicode`.
+- Rust flows can now have footnotes, a contents page and bookmarks. A footnote is a raised number in the text, numbered through the flow, with its note at the foot of the same page; a line whose notes don't fit moves to the next page with them. A contents page lists the headings with dot leaders, the page each one starts on and a link to it. The flow is laid out a second time to fill in the page numbers, and the new error code `flow-layout-unstable` reports a fault if they ever fail to settle. Every heading gets a bookmark in the document's outline, nested by level, which `Flow::with_outline(false)` turns off. Tagged documents can also use the `TOC`, `TOCI` and `Reference` structure types, which `@laminapdf/sdk` now accepts as tag names.
+- Rust callers can now pour a document into as many pages as it needs. `Builder::flow` takes blocks (headings, paragraphs of styled text and links, lists, figures, spacers, page breaks and groups kept together) and a page template. The template sets the margins, a header, a footer and an optional different first page. Paragraphs split only between lines, leaving at least two lines at the foot and the head of a page. Headings stay with what follows them, and figures move whole. Headers and footers can show `{page}`, `{pages}`, `{section}` and `{title}`, so "Page 3 of 12" is right on every page. The output is tagged: each paragraph stays one element across pages, and headers and footers are marked as page furniture. New codes: `flow-content-too-large` for a line or figure taller than a page, and the warning `flow-keep-broken` for blocks kept together that can't fit on one page. The TypeScript package doesn't have flows yet.
+- Rust flows can now hold tables that run across pages. A table's header rows repeat at the top of every page it continues on, no body row is split between pages, and its footer rows, such as a total, stay on the page of the last body row. Each column takes a fixed width, a share of the free width, or its widest cell's width, and the widths are worked out once so the columns line up on every page. Cells hold paragraphs, can span columns and align their text; a table sets its cells' padding and can have a frame, rules and a shaded header. The output is tagged as one table across all its pages, and the repeated header rows are marked as page furniture, so screen readers and text extraction read the header once. Tagged documents can also use the `THead`, `TBody` and `TFoot` structure types, which `@laminapdf/sdk` now accepts as tag names.
+- Rust callers can now turn Markdown into flowing, tagged pages: `Builder::markdown(text, &MarkdownBuildOptions)` reads CommonMark with tables, footnotes, strikethrough and task lists, takes the title, language, author and subject from front matter, and lays the document out with the flow layer. Links to `#a-heading` go to that heading, and a table runs across pages with its header repeated. Images come only from the caller, through `MarkdownBuildOptions::with_image`; nothing is fetched. Raw HTML and images that weren't passed are left out with the warnings `markdown-html-ignored` and `markdown-image-missing`, which give the position in the Markdown, never its text.
+  
+If you pass no fonts, the builder sets the document in Helvetica and Courier, which flows can now use. They set Latin text only, and a PDF/UA-1 build refuses them.
+  
+Flows also gain code spans and code blocks, struck-out text, block quotes (`BlockQuote`), thematic breaks and lists that start at any number. The `laminapdf` crate's new `markdown` feature is on by default.
+- Text runs and text boxes now say where the next element can start. What `surface.text()` and `surface.textBox()` return has a `bottom`: the bottom of the last line that draws something, where the next text box's top can go. In Rust it is `TextRun::bottom()` and `TextLayout::bottom()`. It is left out when nothing is drawn, such as empty text, text of only white space, or a box too short for one line, so an empty section adds no gap. A clipped box gives its last drawn line; check `overflow !== undefined` before treating the text as placed.
+- Read a document's outline and named destinations, and move through it with thumbnails. `Document.outline()` gives the outline's items with their titles, whether each starts expanded, and where each goes: a page and a view in page space (points from the displayed page's top-left, y down), whichever coordinates the file used. `Document.namedDestination(name)` finds one named destination. Both need the extract or text module, like `page.text()`.
+  
+In `@laminapdf/viewer`, `ViewerClient.outline()` and `namedDestination(name)` read them in the document Web Worker, and `Viewer.goToDestination(target)` shows an item's or a destination's target, with each kind of fit. `ThumbnailStrip` is a list of the pages as small pictures. It mounts only the thumbnails near its view, renders after the main view's pages and goes to a page on a click or a key.
+- `doc.structureTree()` reads a tagged document's structure tree: its elements in reading order, down to the marked content each owns on a page. Each element gives its standard type (`H1`, `P`, `LI`, `Figure` …), alternate text, language and actual text; custom types resolve through the role map. A text run's `mcid` links it to its element, so a viewer can give assistive technology a document's headings, paragraphs, lists and tables.
+  
+`doc.isTagged` says whether the document claims to be tagged. Both need the extract or text module, as `page.text()` does. For Rust callers, `Document::structure_tree()` returns `StructureNode`s.
+- Rust callers can now lay out a paragraph whose words change font, size or language: a bold word inside a sentence, a superscript, an Arabic name in an English line. `laminapdf_text::break_spans` takes the text and a list of `StyledSpan`s, each covering a stretch of it with its own fonts, size, baseline rise, language and OpenType features. Lines still break only where the text allows, so a style change inside a word never splits it. Spans of one style are shaped together, so kerning carries across them. Each line reports its ascent and descent from its tallest run, and `pdf_line_run` draws a superscript's rise. `break_lines` is unchanged. Spans that don't cover the text once, in order, that split a letter from its accent, or that name no font or a font past the list fail with the new error code `invalid-spans`.
+- The Rust façade reads a document's outline (`Document::outline()`) and named destinations (`Document::named_destination(name)`), each target a page index and a view in page space. The extract and text modules give them to JavaScript as `WasmDocument.outline()` and `namedDestination(name)`.
+- The viewer is sharp at every zoom level. It sized each page's canvas and sharp tiles from the page's CSS width times the pixel ratio, while the renderer sizes the page in 32-bit floats, so at most zoom levels the right-hand tile came out one pixel wider than the page. The renderer refused it, and the rest of the page stayed blurry. `@laminapdf/render` now exports `pagePixels`, the page's size in pixels at a scale as its planner computes it, and the viewer sizes canvases and tiles with it.
+- The viewer keeps the page in view sharp at every zoom up to 800 %. Each page's canvas now holds at most 8 million pixels; a larger page keeps that canvas as a backdrop, and a detail canvas over the part in view takes the sharp tiles at the full pixel ratio. The detail canvas's size follows the viewport rather than the zoom, so the canvases fit the same memory as before. `createViewer` takes a `detailPool` option, and the render stats count `detailCanvases`.
+- Find now lists its results. `viewer.find.results()` gives every match found so far in document order, each with its page and a snippet of the text around it, and `goTo(ordinal)` goes to one. The web reader shows them in a Results tab in the sidebar while find is open.
+- Find text across a whole document. `viewer.find` searches from the current page forward and wraps round, so scrolling never waits. Results stream in by page, and the first match shows as soon as it's found. `next()` and `previous()` move between matches and scroll each into view, and the matches on the page are highlighted. Options cover case, whole words and diacritics. Match counts agree with pdf.js's find. `ViewerClient.find(query, options, pages)` is the call underneath.
+- The document worker now counts every network request it makes from the moment it starts: `client.networkLog()` returns them all, with the requests its Content Security Policy blocked, and the `network` and `csp-violation` events report each as it happens. `watchNetwork` does the counting and is exported for the page too: it wraps `fetch`, `XMLHttpRequest`, `WebSocket` and `sendBeacon` and reads everything else the browser loads from Resource Timing.
+- The viewer opens remote PDFs: `client.open({ url })` makes the document worker fetch the file itself with HTTP Range requests, so its bytes never pass through the page. Lamina PDF reads the file range by range, and a render fetches the bytes it needs, so page 1 of a large file appears after a small part of it has arrived. Requests send no cookies or referrer and skip the HTTP cache. A server that ignores `Range` sends the whole file, which the viewer accepts up to 256 MiB. The new `progress` event reports how much has been read.
+- Every page's text is selectable and copyable, and a tagged document reads well in a screen reader. The viewer lays one transparent span over each text run of Lamina PDF's extraction, aligned to the rendered glyphs at every zoom and rotation, in any script. A selection runs from one page into the next, and the pages it touches stay mounted while you scroll away. Copy writes the extracted text in reading order. A tagged document's structure tree becomes a hidden tree of headings, paragraphs, lists, tables and figures that owns the spans.
+  
+`createViewer`'s `text` option turns the layer off or sets `outline`, `untaggedLabel` and `onSelection`. `Viewer.keepMounted(pages)` pins pages. `ViewerClient.pageText(index)` and `structure()` give a page's runs and glyph quads and the document's structure tree. The document Web Worker loads the extract module once the render backend is ready, so the first page never waits for it.
+
+### Patch Changes
+
+- `ViewerClient.open` now returns the document's title from its metadata as `title`, when the file has one, so an app can name its window after the document.
+- A mouse drag selects a page's text again. The layer slots above the text covered the whole page and took every press; every slot but `text` now lets the pointer through. A layer added with `addLayer` gets such a slot too, so an element in it that should be clicked, such as a link, sets `pointer-events: auto` on itself.
+  
+A selection's colour no longer hides the text it selects: the text layer (`.lamina-text-layer`) now has `mix-blend-mode: multiply`, so an opaque `::selection` tint shows under the ink.
+- The page no longer flickers while zooming. Each pause in a pinch or ctrl+wheel zoom repainted the page for its new zoom with the blurry low-resolution pass, throwing away the sharp pixels it showed; the repaint now keeps those pixels, scaled, until the sharp tiles for the new zoom replace them.
+- When you zoom out far enough that more than three pages show, every page now turns sharp. Before, the first three did and the rest stayed blurry for good, because the canvas pool's rounding to whole pixels counted as a cap and every page waited for one of three detail canvases.
+
 ## 0.2.0-alpha.3
 
 ### Minor Changes

package/docs/pages/reference/codes.md

@@ -1,7 +1,7 @@
 ---
 title: "Error and warning codes"
 description: "Every code Lamina PDF raises, generated from fixtures/codes.json when the site is built."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/"
 ---
 

package/docs/pages/reference/glossary.md

@@ -1,7 +1,7 @@
 ---
 title: "Glossary"
 description: "The PDF and Lamina PDF terms the docs use, each in a sentence or two."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/glossary/"
 ---
 

package/docs/pages/reference/rust.md

@@ -1,7 +1,7 @@
 ---
 title: "Rust API (rustdoc)"
 description: "Where to read the API documentation of the Lamina PDF crates."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/rust/"
 ---
 
@@ -9,19 +9,19 @@ url: "https://docs.laminapdf.com/reference/rust/"
 
 Where to read the API documentation of the Lamina PDF crates.
 
-docs.rs builds the API documentation of every Lamina PDF crate on crates.io. Start with [`laminapdf` on docs.rs](https://docs.rs/laminapdf/0.2.0-alpha.3/laminapdf/), the crate to depend on. It wraps the core crates and holds `Document`, `Builder`, `Error`, `Warning`, jobs and `CancelToken`.
+docs.rs builds the API documentation of every Lamina PDF crate on crates.io. Start with [`laminapdf` on docs.rs](https://docs.rs/laminapdf/0.2.0-alpha.4/laminapdf/), the crate to depend on. It wraps the core crates and holds `Document`, `Builder`, `Error`, `Warning`, jobs and `CancelToken`.
 
 The other crates are documented the same way:
 
-- [`laminapdf-syntax`](https://docs.rs/laminapdf-syntax/0.2.0-alpha.3/laminapdf_syntax/)
-- [`laminapdf-cos`](https://docs.rs/laminapdf-cos/0.2.0-alpha.3/laminapdf_cos/)
-- [`laminapdf-model`](https://docs.rs/laminapdf-model/0.2.0-alpha.3/laminapdf_model/)
-- [`laminapdf-ops`](https://docs.rs/laminapdf-ops/0.2.0-alpha.3/laminapdf_ops/)
-- [`laminapdf-save`](https://docs.rs/laminapdf-save/0.2.0-alpha.3/laminapdf_save/)
-- [`laminapdf-content`](https://docs.rs/laminapdf-content/0.2.0-alpha.3/laminapdf_content/)
-- [`laminapdf-text`](https://docs.rs/laminapdf-text/0.2.0-alpha.3/laminapdf_text/)
-- [`laminapdf-build`](https://docs.rs/laminapdf-build/0.2.0-alpha.3/laminapdf_build/)
-- [`laminapdf-render-pdfium`](https://docs.rs/laminapdf-render-pdfium/0.2.0-alpha.3/laminapdf_render_pdfium/)
+- [`laminapdf-syntax`](https://docs.rs/laminapdf-syntax/0.2.0-alpha.4/laminapdf_syntax/)
+- [`laminapdf-cos`](https://docs.rs/laminapdf-cos/0.2.0-alpha.4/laminapdf_cos/)
+- [`laminapdf-model`](https://docs.rs/laminapdf-model/0.2.0-alpha.4/laminapdf_model/)
+- [`laminapdf-ops`](https://docs.rs/laminapdf-ops/0.2.0-alpha.4/laminapdf_ops/)
+- [`laminapdf-save`](https://docs.rs/laminapdf-save/0.2.0-alpha.4/laminapdf_save/)
+- [`laminapdf-content`](https://docs.rs/laminapdf-content/0.2.0-alpha.4/laminapdf_content/)
+- [`laminapdf-text`](https://docs.rs/laminapdf-text/0.2.0-alpha.4/laminapdf_text/)
+- [`laminapdf-build`](https://docs.rs/laminapdf-build/0.2.0-alpha.4/laminapdf_build/)
+- [`laminapdf-render-pdfium`](https://docs.rs/laminapdf-render-pdfium/0.2.0-alpha.4/laminapdf_render_pdfium/)
 
 docs.rs couldn't build `laminapdf-source` and `laminapdf-render` at 0.2.0-alpha.2, so their docs come with the next release; until then, build them yourself as below. [Install](../../pages/install.md#every-published-package) lists every crate, with its page on crates.io.
 

package/docs/pages/reference/stability.md

@@ -1,7 +1,7 @@
 ---
 title: "Stability policy"
 description: "What a Lamina PDF version number promises, and what stays the same in every version."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/stability/"
 ---
 
@@ -17,7 +17,7 @@ Every crate and every npm package shares one version, and they are released toge
 
 ## What a version number tells you
 
-- **Alphas promise nothing to each other.** Anything can change between `0.2.0-alpha.1` and `0.2.0-alpha.2`. While you try an alpha, pin the exact version: `npm install --save-exact @laminapdf/sdk@0.2.0-alpha.3`, and `laminapdf = "=0.2.0-alpha.3"` in `Cargo.toml`.
+- **Alphas promise nothing to each other.** Anything can change between `0.2.0-alpha.1` and `0.2.0-alpha.2`. While you try an alpha, pin the exact version: `npm install --save-exact @laminapdf/sdk@0.2.0-alpha.4`, and `laminapdf = "=0.2.0-alpha.4"` in `Cargo.toml`.
 - **The `alpha` tag names the newest alpha.** `npm install @laminapdf/sdk@alpha` gets it. A plain `npm install @laminapdf/sdk` gets a `0.0.0` placeholder that only reserves the name.
 - **After the alphas, `0.x` versions follow SemVer as Cargo reads it.** A breaking change raises the minor version (`0.2` to `0.3`), and features and fixes raise the patch (`0.2.0` to `0.2.1`). So an upgrade within one `0.x` line never needs a code change.
 
@@ -40,7 +40,7 @@ Four promises hold across every version, `0.x` and alphas included:
 - **Error and warning codes are never renamed or reused** for another meaning. A retired code stays in the [code reference](../../errors/README.md) with the version that retired it, and keeps its page. New codes can appear in any release, so handle a code you don't know.
 - **The error object only grows.** Each error names its schema, `laminapdf.error/1`. Within one schema, a field can be added, but never removed or given another type.
 - **Saved edit logs keep loading.** A log names its format version (`{ v: 1, ops }`, as [Edit a PDF](../../pages/guides/edit-a-pdf.md#replay-edits-stored-as-json) shows). A new op or optional field keeps the version. A changed or removed one raises it, and every older version still loads.
-- **The same input gives the same bytes everywhere.** With the same input, options and version, Rust and every JavaScript runtime write identical files.
+- **The same input gives the same bytes everywhere.** With the same input, options and version, Rust and every JavaScript runtime write identical files, so you can [test your PDFs against reference PDFs](../../pages/guides/test-generated-pdfs.md).
 
 ## How the promises are checked
 

package/docs/pages/start/coding-agents.md

@@ -1,7 +1,7 @@
 ---
 title: "Use Lamina PDF with coding agents"
 description: "Point a coding agent at the docs inside the installed package, so its answers match the version you use."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/start/coding-agents/"
 ---
 

package/docs/pages/start/first-pdf.md

@@ -1,7 +1,7 @@
 ---
 title: "Your first PDF"
 description: "Write hello.pdf from Node in five minutes."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/start/first-pdf/"
 ---
 
@@ -18,7 +18,7 @@ You need Node 24.2 or newer, which runs `.ts` files directly. Create a folder an
 ```sh
 mkdir hello-pdf && cd hello-pdf
 npm init -y && npm pkg set type=module
-npm install @laminapdf/sdk@0.2.0-alpha.3
+npm install @laminapdf/sdk@0.2.0-alpha.4
 ```
 
 Lamina PDF is in alpha, so the install names the version these docs describe. `@laminapdf/sdk` brings its WebAssembly modules, `@laminapdf/wasm`, with it. [Install](../../pages/install.md) covers other package managers and Rust.
@@ -27,6 +27,8 @@ Lamina PDF is in alpha, so the install names the version these docs describe. `@
 
 Save this app as `hello.ts`. It loads Lamina PDF, builds the page and writes it to `hello.pdf`:
 
+**TypeScript**
+
 `packages/sdk/examples/quick-start/node.ts`:
 
 ```ts
@@ -62,6 +64,8 @@ export async function hello(
 if (import.meta.main) await hello();
 ```
 
+**Result:** [hello.pdf](https://docs.laminapdf.com/examples/pdf/hello.pdf)
+
 ## Run it
 
 ```sh

package/docs/pages/troubleshooting.md

@@ -1,7 +1,7 @@
 ---
 title: "Troubleshooting"
 description: "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."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/troubleshooting/"
 ---
 

package/docs/schemas/error.schema.json

@@ -49,6 +49,7 @@
             "wrong-document",
             "invalid-feature",
             "invalid-text-range",
+            "invalid-spans",
             "unsupported-layout-option",
             "font-mismatch",
             "encoding-full",
@@ -65,6 +66,8 @@
             "page-index-out-of-range",
             "unknown-destination",
             "invalid-page-labels",
+            "tag-element-not-open",
+            "tag-element-unclosed",
             "profile-version-conflict",
             "missing-title",
             "missing-lang",
@@ -80,12 +83,18 @@
             "device-color-without-output-intent",
             "embedded-file-forbidden",
             "embedded-file-without-mime-type",
+            "flow-content-too-large",
+            "flow-layout-unstable",
             "render-too-large",
             "render-failed",
             "render-backend-unavailable",
+            "model-failed",
+            "model-result-unexpected",
+            "model-needs-host",
             "cancelled",
             "job-finished",
             "document-changed",
+            "revision-index-out-of-range",
             "builder-finished",
             "disposed",
             "invalid-argument",
@@ -250,8 +259,16 @@
             "extract-table-limit",
             "extract-struct-tree-ignored",
             "extract-untagged-content",
+            "extract-needs-ocr",
+            "extract-column-order-uncertain",
             "tounicode-conflict",
-            "whole-font-rebuilt"
+            "whole-font-rebuilt",
+            "flow-keep-broken",
+            "markdown-html-ignored",
+            "markdown-image-missing",
+            "covered-text",
+            "redaction-not-applied",
+            "text-in-earlier-revision"
           ]
         },
         "data": {