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

package/docs/pages/guides/fonts-and-text.md

@@ -1,7 +1,7 @@
 ---
 title: "Text and fonts"
 description: "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."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 url: "https://docs.laminapdf.com/guides/fonts-and-text/"
 ---
 
@@ -189,6 +189,8 @@ pub(crate) fn build(options: BuildOptions, fonts: Vec<Vec<u8>>) -> Result<Vec<u8
 }
 ````
 
+**Result:** [multilingual.pdf](https://docs.laminapdf.com/examples/pdf/multilingual.pdf)
+
 [See the output](../../pages/recipes/multilingual.md). Text extracted from it, with pdf.js, pypdf or pdftotext, equals the input strings, ligatures included.
 
 ## When a font can't draw the text

package/docs/pages/guides/images-and-vectors.md

@@ -1,7 +1,7 @@
 ---
 title: "Shapes, colour and images"
 description: "Draw lines, shapes and images on a page, in any colour, with transparency, clipping and transforms."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 url: "https://docs.laminapdf.com/guides/images-and-vectors/"
 ---
 
@@ -212,6 +212,8 @@ fn images(s: &mut Surface, photo: &Image, glow: &Image) {
 }
 ````
 
+**Result:** [images_and_vectors.pdf](https://docs.laminapdf.com/examples/pdf/images_and_vectors.pdf)
+
 [See the output](../../pages/recipes/images-and-vectors.md).
 
 > **Details:** A PNG's alpha channel, and an RGBA image's, becomes a soft mask: a second image that holds the transparency.

package/docs/pages/guides/keep-the-page-responsive.md

@@ -1,7 +1,7 @@
 ---
 title: "Keep the page responsive"
 description: "Run Lamina PDF in a Web Worker with @laminapdf/sdk/worker, so a large file never freezes the page."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 url: "https://docs.laminapdf.com/guides/keep-the-page-responsive/"
 ---
 
@@ -58,11 +58,15 @@ The Web Worker leaves out a few members, each for a reason:
 
 ## Cancel a call
 
-Pass an `AbortSignal` as `signal` to any call. An aborted call rejects with `cancelled`, and `error.cause` holds the signal's reason. What happens to the work depends on where it was:
+The Web Worker runs one call at a time, so a call waits while another runs. Pass an `AbortSignal` as `signal` to any call. An aborted call rejects with `cancelled`, and `error.cause` holds the signal's reason. What happens to the work depends on where it was:
 
 - A call that hasn't started never runs.
-- `save` stops at its next step, and the document stays usable.
-- Any other call runs to the end in the Web Worker, because it is one synchronous call. `client.terminate()` stops it at once.
+- `save` and `saveWithReport` stop at their next step, and the document stays usable.
+- Any other call runs to the end in the Web Worker, because it is one synchronous call, though the byte fetches of a file opened with `openUrl` stop. `client.terminate()` stops it at once.
+
+*Each call crosses to the Web Worker as a message; an abort skips a call not started and stops a running save.*
+
+Your page's client sends each call, such as `await doc.pageCount()`, to the Web Worker as a message. There `@laminapdf/sdk` runs one call at a time, and each answer comes back as a Promise; saved bytes and page text come back transferred rather than copied. When a call's `AbortSignal` aborts, the call rejects with `cancelled`. A call not started never runs, and a running `save` or `saveWithReport` stops at its next step. Any other call runs to the end, though the byte fetches of a file opened with `openUrl` stop.
 
 ## Move bytes instead of copying them
 

package/docs/pages/guides/links-outlines-and-metadata.md

@@ -1,7 +1,7 @@
 ---
 title: "Links, outlines and metadata"
 description: "Add links, named destinations, an outline, page labels, viewer preferences and metadata to a document."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 url: "https://docs.laminapdf.com/guides/links-outlines-and-metadata/"
 ---
 
@@ -215,6 +215,8 @@ fn navigation(b: &mut Builder) -> Result<(), Box<dyn Error>> {
 }
 ````
 
+**Result:** [links_and_outlines.pdf](https://docs.laminapdf.com/examples/pdf/links_and_outlines.pdf)
+
 [See the output](../../pages/recipes/links-and-outlines.md).
 
 > **Details:** The metadata goes into two places: an XMP packet, the XML that describes the file, and the Info dictionary, the older list of the same facts. Lamina PDF writes both from the same values, so they always agree.

package/docs/pages/guides/open-large-files.md

@@ -0,0 +1,69 @@
+---
+title: "Open large files by ranges"
+description: "Open a PDF on a web server without downloading all of it, fetching only the byte ranges each read needs."
+version: "0.2.0-alpha.5"
+url: "https://docs.laminapdf.com/guides/open-large-files/"
+---
+
+# Open large files by ranges
+
+Open a PDF on a web server without downloading all of it, fetching only the byte ranges each read needs.
+
+You'll open a PDF on a web server by fetching only the parts you read. A large report opens after a few small requests, and reading its first page fetches that page and little else. You need this when files are too large to download before the first page shows.
+
+This example opens a remote file, then reads its page count and first page:
+
+`packages/sdk/examples/open-large-file.ts`:
+
+```ts
+// Opens a PDF on a web server by range requests: only the parts it reads are downloaded, so a
+// large file opens without fetching all of it. The server must answer `Range` requests, as most
+// file hosts and CDNs do; across origins it must also allow the `Range` and `If-Range` headers.
+// Needs `init()`.
+import { Document, httpRangeSource } from "@laminapdf/sdk";
+
+/** What a first look at a remote file needs: its page count and the first page's size. */
+export interface FirstLook {
+  readonly pages: number;
+  /** The first page's displayed size, in points (1/72 inch). */
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Opens the PDF at `url` range by range and reads its page count and first page. */
+export async function firstLook(url: string): Promise<FirstLook> {
+  // The first request reads the end of the file, where a PDF keeps the index of its objects.
+  using doc = await Document.openRange(httpRangeSource(url));
+  // A read can need bytes that haven't arrived. `ensure` catches the `data-pending` error, fetches
+  // the ranges it names, and runs the read again until it has what it needs.
+  const pages = await doc.ensure(() => doc.pageCount);
+  const first = await doc.ensure(() => doc.pageInfo(0));
+  return { pages, width: first.width, height: first.height };
+}
+```
+
+## Each read fetches the bytes it needs
+
+`Document.openRange` fetches only what opening needs: the end of the file, where a PDF keeps the index of its objects, then that index and the document's catalog. Calls on the document stay synchronous, so a read that needs bytes not fetched yet can't wait for them. It throws `data-pending` instead, with the byte ranges it needs. `doc.ensure` runs your read, fetches those ranges when it throws, and runs it again until it returns:
+
+*A read that needs missing bytes fetches them and runs again.*
+
+`Document.openRange` opens a remote file from the few byte ranges the open needs. A later read, such as `doc.pageInfo(0)`, may need bytes that haven't arrived: it then throws `data-pending`, naming the ranges it needs. `doc.ensure` catches the error, fetches those ranges through the source (`httpRangeSource`), supplies them to the document and runs the read again. Once the bytes are there, the read returns its result.
+
+Wrap every read after the open in `doc.ensure`, saving included: `await doc.ensure(() => doc.save())` fetches whatever the save writes. A read fails with the last `data-pending` when its fetches bring nothing new, or when it still needs bytes after 1,024 rounds of fetches. Pass `maxRounds` to `Document.openRange` to change that number.
+
+## The server must answer `Range` requests
+
+`httpRangeSource(url)` asks for byte ranges with the `Range` header, and most file hosts and CDNs answer them. Across origins, the server must also allow the `Range` and `If-Range` request headers (`Access-Control-Allow-Headers: Range, If-Range`) and expose `Content-Range`, `Content-Length` and `ETag` (`Access-Control-Expose-Headers`). It must not compress the response, or the ranges it sends wouldn't match the file's bytes. An error status from the server fails with `fetch-failed`, its `data.status` holding the status code.
+
+A server that ignores `Range` and answers `200` sends the whole file. Lamina PDF then opens that one download, as `Document.open` would.
+
+## A file that changes on the server fails the read
+
+Every request after the first sends `If-Range` with the `ETag` the first response gave, when it's a strong one, or else that response's `Last-Modified` date. When the file changes between two reads, the read fails with `source-changed` rather than mixing two versions. Open the file again to read the new one.
+
+## Limit how much a file can make you fetch
+
+A remote file decides how much you fetch, so cap it when the file comes from someone else. Pass `budget` to `Document.openRange`: it's the most bytes the document may hold, and past it a read fails with `source-budget-exceeded`. Pass `signal` with the same options to stop the open's fetches. Later reads take their own: `doc.ensure(read, { signal: AbortSignal.timeout(10_000) })`.
+
+The [limits for files you don't trust](../../pages/guides/untrusted-files.md) apply here too: pass `limits` with the other options.

package/docs/pages/guides/password-protected-files.md

@@ -1,7 +1,7 @@
 ---
 title: "Open password-protected files"
 description: "Open PDFs that need a password, ask again when it is missing or wrong, and save them afterwards."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 url: "https://docs.laminapdf.com/guides/password-protected-files/"
 ---
 

package/docs/pages/guides/save-a-pdf.md

@@ -1,7 +1,7 @@
 ---
 title: "Save a PDF"
 description: "Save edits as a revision appended to the original bytes or as a whole new file, and see when a file refuses a save."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 url: "https://docs.laminapdf.com/guides/save-a-pdf/"
 ---
 
@@ -118,6 +118,8 @@ fn edit(bytes: Vec<u8>, edited_at: Option<PdfDate>) -> Result<Vec<u8>, Box<dyn E
 }
 ````
 
+**Result:** [generate_then_edit.pdf](https://docs.laminapdf.com/examples/pdf/generate_then_edit.pdf)
+
 ## Choose a save mode
 
 Every save either appends a revision to the bytes you opened (an incremental save) or writes the whole file again (a [full rewrite](../../pages/reference/glossary.md#full-rewrite)). You pick one with the `mode` option:
@@ -130,6 +132,10 @@ Every save either appends a revision to the bytes you opened (an incremental sav
 
 `doc.save(options)` returns the bytes, and `doc.saveWithReport(options)` also says what it wrote. `doc.saveJob()` does the same work in steps, so a page can save a large file without freezing. The same file with the same edits always saves to the same bytes.
 
+*An incremental save appends a revision; a full rewrite writes every byte again.*
+
+An incremental save (`incremental`) keeps the original bytes and appends one revision after them. A signature over those bytes stays valid for the edits it allows. A full rewrite (`fullRewrite`) writes every byte again as one new file. Signatures over the original bytes are no longer valid, so a signed file saves this way only when you pass `invalidateSignatures: true`, which removes them.
+
 ## When a file refuses a save
 
 Every save makes a plan before it writes. The plan reads the file's save constraint: what its signatures, permissions, repairs and encryption allow. Then it picks a mode or refuses:
@@ -137,7 +143,11 @@ Every save makes a plan before it writes. The plan reads the file's save constra
 - **A signed file** saves only incrementally, and only with edits its signatures allow. Anything else fails with `would-invalidate-signatures`. Pass `invalidateSignatures: true` to save anyway, which removes the broken signatures from the output.
 - **A repaired file**, one Lamina PDF had to fix as it opened, can't safely take an appended revision. It needs a full rewrite, so asking for `incremental` fails with `requires-rewrite`.
 - **An edited encrypted file** saves only as a full rewrite without its encryption, and only when you pass `removeEncryption: true`. Otherwise every mode fails with `encrypted-base`.
-- **An unchanged document** always saves incrementally, which returns its bytes unchanged.
+- **An unchanged document**, even a signed, repaired or encrypted one, saves incrementally in `auto` and `incremental` mode and returns the bytes you opened. Passing `removeEncryption: true` rewrites it instead.
+
+*What a file allows, and the options you pass, decide its save mode or the error the save fails with.*
+
+Every save plans before it writes, and an unchanged document comes first: in `auto` and `incremental` mode it saves incrementally and returns the bytes you opened, whatever else is true of it. A signed file saves incrementally, with the edits its signatures allow. Any other save fails with `would-invalidate-signatures` unless you pass `invalidateSignatures: true`, which saves anyway and removes the signatures that no longer hold. A repaired file needs a full rewrite: `auto` picks `fullRewrite`, and asking for `incremental` fails with `requires-rewrite`. An encrypted file you edited saves as `fullRewrite` without its encryption when you pass `removeEncryption: true`; otherwise every mode fails with `encrypted-base`. An edited file in two of these states meets both rules: a signed file that was repaired fails until you pass `invalidateSignatures: true`.
 
 > **Details:** The save constraint covers signature fields, the [DocMDP](../../pages/reference/glossary.md#docmdp) and [UR3](../../pages/reference/glossary.md#ur3) permissions, a signature's `/Lock` entry (the form fields it locks), document timestamps, and whether the file needed repair.
 

package/docs/pages/guides/test-generated-pdfs.md

@@ -0,0 +1,324 @@
+---
+title: "Test the PDFs you generate"
+description: "Compare the PDFs your code makes with reference PDFs you approved, byte for byte, and draw both files' pages to see what changed."
+version: "0.2.0-alpha.5"
+url: "https://docs.laminapdf.com/guides/test-generated-pdfs/"
+---
+
+# Test the PDFs you generate
+
+Compare the PDFs your code makes with reference PDFs you approved, byte for byte, and draw both files' pages to see what changed.
+
+You'll write a test that fails when a PDF your code makes changes. The test compares the PDF's bytes with a reference PDF you opened and approved. When the bytes differ, a second example draws both files' pages to show where they look different.
+
+## Why the bytes repeat
+
+Lamina PDF never reads a clock or picks a random value while it writes. With the same code, data, options and Lamina PDF version, Rust and every JavaScript runtime write the same bytes. Three values usually come from your app rather than from the content (the file ID, the producer and the creation date), so a test fixes them.
+
+Your own code can vary the bytes too, and a failing test should point there first:
+
+- a date taken from the clock, such as an invoice date or `new Date()` in a footer;
+- records read in a different order, such as rows from a database without `ORDER BY`;
+- a different font file: an update to the font changes the embedded subset.
+
+## Compare with a reference PDF
+
+The example below holds the options a test passes and a function that compares a PDF with its reference. The function answers `same`, `created` or `changed`, and your test runner checks the answer, so it works in Vitest, Jest, `node:test` or `cargo test`:
+
+**TypeScript**
+
+`packages/sdk/examples/snapshot-test.ts`:
+
+```ts
+// Checks that a PDF your code makes is byte for byte the reference PDF you approved.
+//
+// Build the document with `TEST_OPTIONS`, then let your test runner check the answer:
+//
+//   expect(compareWithReference(invoice(order, TEST_OPTIONS), "references/invoice.pdf")).toBe("same");
+//
+// The first run fails with `created` and writes the reference: open it, and commit it once it
+// looks right. When the bytes change later, the new PDF is written beside the reference for
+// review; pass `{ update: true }` to accept it.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+import type { BuilderOptions } from "@laminapdf/sdk";
+
+/**
+ * What a test passes in place of the clock and a random file ID. With these fixed, the same code
+ * and data give the same bytes on every run, machine and runtime.
+ */
+export const TEST_OPTIONS: BuilderOptions = {
+  // The file ID: any 32 hex digits, as long as they stay the same.
+  id: "00112233445566778899aabbccddeeff",
+  // The Info dictionary's /Producer: your app's name, without a version that changes.
+  producer: "my-app tests",
+  // The Info dictionary's /CreationDate, in PDF date form.
+  creationDate: "D:20260101000000Z",
+};
+
+/** `same`: the bytes match. `created`: there was no reference, so one was written. `changed`: they differ. */
+export type Outcome = "same" | "created" | "changed";
+
+export interface CompareOptions {
+  /** Replace the reference with the new bytes instead of writing them beside it. */
+  readonly update?: boolean;
+}
+
+/**
+ * Compares `bytes` with the reference PDF at `reference`. A changed PDF is written to
+ * `<name>.new.pdf` next to the reference, or replaces it when `update` is set.
+ */
+export function compareWithReference(bytes: Uint8Array, reference: string, options: CompareOptions = {}): Outcome {
+  const pending = join(dirname(reference), `${basename(reference, extname(reference))}.new.pdf`);
+  if (!existsSync(reference)) {
+    mkdirSync(dirname(reference), { recursive: true });
+    writeFileSync(reference, bytes);
+    return "created";
+  }
+  if (sameBytes(readFileSync(reference), bytes)) {
+    rmSync(pending, { force: true });
+    return "same";
+  }
+  if (options.update) {
+    writeFileSync(reference, bytes);
+    rmSync(pending, { force: true });
+  } else {
+    writeFileSync(pending, bytes);
+  }
+  return "changed";
+}
+
+function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+  return a.length === b.length && a.every((byte, i) => byte === b[i]);
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/snapshot_test.rs`:
+
+````rust
+//! Checks that a PDF your code makes is byte for byte the reference PDF you approved.
+//!
+//! Build the document with `test_options()`, then assert on the answer in a test:
+//!
+//! ```ignore
+//! let bytes = invoice(&order, test_options()?)?;
+//! assert_eq!(compare_with_reference(&bytes, Path::new("references/invoice.pdf"), false)?, Outcome::Same);
+//! ```
+//!
+//! The first run fails with `Created` and writes the reference: open it, and commit it once it
+//! looks right. When the bytes change later, the new PDF is written beside the reference for
+//! review; pass `update: true` to accept it. Run on its own, the example compares two files:
+//!
+//! ```sh
+//! cargo run -p laminapdf --example snapshot_test -- new.pdf reference.pdf
+//! ```
+
+use std::error::Error;
+use std::path::{Path, PathBuf};
+
+use laminapdf::BuildOptions;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args = std::env::args().skip(1);
+    let (Some(new), Some(reference)) = (args.next(), args.next()) else {
+        return Err("usage: snapshot_test <new.pdf> <reference.pdf>".into());
+    };
+    let outcome = compare_with_reference(&std::fs::read(new)?, Path::new(&reference), false)?;
+    println!("{outcome:?}");
+    Ok(())
+}
+
+/// What a test passes in place of the clock and a random file ID. With these fixed, the same code
+/// and data give the same bytes on every run, machine and runtime.
+#[cfg_attr(
+    not(test),
+    expect(dead_code, reason = "your tests call it; `main` only compares two files")
+)]
+pub(crate) fn test_options() -> Result<BuildOptions, Box<dyn Error>> {
+    /// The file ID: any 16 bytes, as long as they stay the same.
+    const FILE_ID: [u8; 16] = [
+        0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff,
+    ];
+    /// The Info dictionary's `/Producer`: your app's name, without a version that changes.
+    const PRODUCER: &str = "my-app tests";
+    /// The Info dictionary's `/CreationDate`, in PDF date form.
+    const CREATED: &str = "D:20260101000000Z";
+    Ok(BuildOptions::new()
+        .with_id(FILE_ID)
+        .with_producer(PRODUCER)
+        .with_creation_date(CREATED.parse()?))
+}
+
+/// `Same`: the bytes match. `Created`: there was no reference, so one was written. `Changed`:
+/// they differ.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Outcome {
+    Same,
+    Created,
+    Changed,
+}
+
+/// Compares `bytes` with the reference PDF at `reference`. A changed PDF is written to
+/// `<name>.new.pdf` next to the reference, or replaces it when `update` is set.
+pub(crate) fn compare_with_reference(bytes: &[u8], reference: &Path, update: bool) -> std::io::Result<Outcome> {
+    let pending = pending_path(reference);
+    if !reference.exists() {
+        if let Some(folder) = reference.parent() {
+            std::fs::create_dir_all(folder)?;
+        }
+        std::fs::write(reference, bytes)?;
+        return Ok(Outcome::Created);
+    }
+    if std::fs::read(reference)? == bytes {
+        remove_if_present(&pending)?;
+        return Ok(Outcome::Same);
+    }
+    if update {
+        std::fs::write(reference, bytes)?;
+        remove_if_present(&pending)?;
+    } else {
+        std::fs::write(&pending, bytes)?;
+    }
+    Ok(Outcome::Changed)
+}
+
+/// `invoice.pdf` → `invoice.new.pdf`, in the same folder.
+fn pending_path(reference: &Path) -> PathBuf {
+    let stem = reference.file_stem().unwrap_or_default().to_string_lossy();
+    reference.with_file_name(format!("{stem}.new.pdf"))
+}
+
+fn remove_if_present(path: &Path) -> std::io::Result<()> {
+    match std::fs::remove_file(path) {
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        result => result,
+    }
+}
+````
+
+On the first run there is no reference yet, so the function writes one, answers `created`, and the test fails. Open that PDF before you commit it: the test only proves that later runs match it, so it has to be right. After that, every run answers `same` until the output changes. A reference you forget to commit fails the test on every other machine too, since a fresh checkout has none.
+
+When the bytes change, the reference stays as it was and the new PDF goes beside it as `<name>.new.pdf`. Open both, and if the change is the one you meant, run the tests again with `update` set, for example from an environment variable such as `UPDATE_REFERENCES=1`. Commit the new reference with the change that caused it.
+
+## See where a changed PDF looks different
+
+Different bytes don't always mean different pages: a reordered dictionary or a new producer changes the file but not how it looks. This example draws each page of both files and counts the pixels that differ:
+
+`packages/sdk/examples/compare-pages.ts`:
+
+```ts
+// Draws each page of two PDFs and counts the pixels that differ, to show where a changed PDF looks different.
+//
+// Both files are drawn by the same renderer, so its own quirks cancel out. In Node, load it with
+// the module's bytes:
+//
+//   const wasm = fileURLToPath(import.meta.resolve("@laminapdf/wasm/lamina_pdf_render_hayro.wasm"));
+//   const renderer = await loadRenderer(readFileSync(wasm));
+import {
+  bytesSource,
+  DEFAULT_LIMITS,
+  type RenderBackend,
+  type RenderDocument,
+  type RenderedTile,
+} from "@laminapdf/render";
+import { initHayro } from "@laminapdf/render-hayro";
+
+/** Pixels per point: 2 draws at 144 dpi, enough to see a glyph that moved. Pages too large for the renderer's limits at this scale are drawn smaller. */
+const SCALE = 2;
+/** How far a colour channel (0–255) may move before the pixel counts as changed: absorbs smoothing noise. */
+const TOLERANCE = 8;
+
+/** A rectangle in page points, from the page's top-left corner. */
+export interface Box {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** One page: how many pixels differ, and the box around them (`null` when none do). */
+export interface PageDifference {
+  readonly page: number;
+  readonly pixels: number;
+  readonly box: Box | null;
+}
+
+export interface Comparison {
+  /** The page counts of the first and second file; only the pages both have are compared. */
+  readonly pageCounts: readonly [number, number];
+  readonly pages: readonly PageDifference[];
+}
+
+/** Loads the renderer from the module's bytes, a URL, or (in a browser) the file next to its code. */
+export function loadRenderer(wasm?: Uint8Array | URL): Promise<RenderBackend> {
+  return initHayro(wasm);
+}
+
+/** Compares every page the two PDFs share. */
+export function comparePages(renderer: RenderBackend, before: Uint8Array, after: Uint8Array): Comparison {
+  using a = renderer.open(bytesSource(before));
+  using b = renderer.open(bytesSource(after));
+  const shared = Math.min(a.pageCount, b.pageCount);
+  const pages = Array.from({ length: shared }, (_, page) => comparePage(a, b, page));
+  return { pageCounts: [a.pageCount, b.pageCount], pages };
+}
+
+function comparePage(a: RenderDocument, b: RenderDocument, page: number): PageDifference {
+  const scale = Math.min(fittingScale(a, page), fittingScale(b, page));
+  const first = a.render({ page, scale });
+  const second = b.render({ page, scale });
+  const width = Math.max(first.width, second.width);
+  const height = Math.max(first.height, second.height);
+  let pixels = 0;
+  let [left, top, right, bottom] = [width, height, -1, -1];
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      if (!differs(first, second, x, y)) continue;
+      pixels++;
+      [left, top] = [Math.min(left, x), Math.min(top, y)];
+      [right, bottom] = [Math.max(right, x), Math.max(bottom, y)];
+    }
+  }
+  const box =
+    pixels === 0
+      ? null
+      : { x: left / scale, y: top / scale, width: (right - left + 1) / scale, height: (bottom - top + 1) / scale };
+  return { page, pixels, box };
+}
+
+/** `SCALE`, or less when the page would pass the renderer's pixel or side limit at it. */
+function fittingScale(doc: RenderDocument, page: number): number {
+  const { width, height } = doc.page(page);
+  const byArea = Math.sqrt(DEFAULT_LIMITS.maxRenderPixels / (width * height));
+  const bySide = DEFAULT_LIMITS.maxRenderSide / Math.max(width, height);
+  return Math.min(SCALE, byArea, bySide);
+}
+
+/** Whether the pixel at (x, y) differs; a pixel only one page has always does. */
+function differs(first: RenderedTile, second: RenderedTile, x: number, y: number): boolean {
+  if (x >= first.width || y >= first.height || x >= second.width || y >= second.height) return true;
+  const i = (y * first.width + x) * 4;
+  const j = (y * second.width + x) * 4;
+  for (let channel = 0; channel < 4; channel++) {
+    const delta = Math.abs((first.pixels[i + channel] ?? 0) - (second.pixels[j + channel] ?? 0));
+    if (delta > TOLERANCE) return true;
+  }
+  return false;
+}
+```
+
+Each page gets one of two outcomes. With no differing pixels, the file's structure changed but its pages look the same. With some, the box shows where on the page, in points from the top-left corner. The same renderer draws both files, so its own small differences from other viewers cancel out.
+
+To read the change itself, build with `compress: false` (`with_compress(false)` in Rust). The content streams then stay readable text, and a diff tool shows what moved. In Rust, the `laminapdf-render` crate's `hayro` feature draws pages the same way.
+
+## Upgrade Lamina PDF
+
+Pin the exact Lamina PDF version, so an upgrade happens only when you choose it. A release that changes the bytes written for the same input lists that change first in its changelog. Upgrade in a change of its own, regenerate the references with `update` set, and look at the page comparison before you commit them.
+
+## Keep fonts and edits repeatable
+
+Fonts need the same care. The embedded subset depends on the font file's exact bytes, so keep the font your test uses in your own repository rather than loading it from the system. Edited files repeat too: opening a PDF, applying the same edits and saving writes the same bytes each time.
+
+The [stability policy](../../pages/reference/stability.md) states the promise these tests rely on: the same input gives the same bytes everywhere.

package/docs/pages/guides/untrusted-files.md

@@ -1,7 +1,7 @@
 ---
 title: "Open files you don't trust"
 description: "Cap how much work an uploaded PDF can make Lamina PDF do, and refuse damaged files with strict mode."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 url: "https://docs.laminapdf.com/guides/untrusted-files/"
 ---
 
@@ -77,4 +77,6 @@ These are the TypeScript names. In Rust they're builder methods, such as `Limits
 
 Lamina PDF repairs damaged files as it opens them and reports each repair as a warning. Pass `strict: true` to refuse any file that needs repair instead. It then fails with `strict`.
 
+A file on someone else's server can also decide how much you download. [Open it by ranges](../../pages/guides/open-large-files.md) and cap the bytes it may fetch with `budget`.
+
 Next: [keep the page responsive](../../pages/guides/keep-the-page-responsive.md).

package/docs/pages/index.md

@@ -1,7 +1,7 @@
 ---
 title: "Lamina PDF"
 description: "Create, read, edit and save PDFs from Rust and TypeScript, with one Rust core that runs natively and as WebAssembly."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 url: "https://docs.laminapdf.com/"
 ---
 
@@ -14,7 +14,7 @@ Lamina PDF creates, reads, edits and saves PDFs. One Rust core does the work, an
 - **[`laminapdf`](https://crates.io/crates/laminapdf)** on crates.io is the Rust crate. Its [API reference](../pages/reference/rust.md) is on docs.rs.
 - **[`@laminapdf/sdk`](https://www.npmjs.com/package/@laminapdf/sdk)** on npm is the TypeScript API over the WebAssembly build. After one `await init()`, every call is synchronous, and the API is the same in every runtime. Its [API reference](../api/README.md) is on this site.
 
-> **Alpha releases:** Both packages are alpha releases, so name the version when you install them: `npm install @laminapdf/sdk@0.2.0-alpha.3` and `cargo add laminapdf@=0.2.0-alpha.3`. [Install](../pages/install.md) lists every published package.
+> **Alpha releases:** Both packages are alpha releases, so name the version when you install them: `npm install @laminapdf/sdk@0.2.0-alpha.5` and `cargo add laminapdf@=0.2.0-alpha.5`. [Install](../pages/install.md) lists every published package.
 
 ## What works today
 

package/docs/pages/install.md

@@ -1,7 +1,7 @@
 ---
 title: "Install"
 description: "Install Lamina PDF from npm or crates.io, and find every published package."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 url: "https://docs.laminapdf.com/install/"
 ---
 
@@ -16,10 +16,10 @@ Lamina PDF is published to npm as [`@laminapdf/sdk`](https://www.npmjs.com/packa
 Install the version these docs describe:
 
 ```sh
-npm install @laminapdf/sdk@0.2.0-alpha.3
+npm install @laminapdf/sdk@0.2.0-alpha.5
 ```
 
-`npm install @laminapdf/sdk@alpha` installs the newest alpha, whichever version that is. pnpm, Yarn and Bun take the same name (`pnpm add @laminapdf/sdk@0.2.0-alpha.3`), and Deno takes `npm:@laminapdf/sdk@0.2.0-alpha.3`. The package brings [`@laminapdf/wasm`](https://www.npmjs.com/package/@laminapdf/wasm), its WebAssembly modules, as a dependency.
+`npm install @laminapdf/sdk@alpha` installs the newest alpha, whichever version that is. pnpm, Yarn and Bun take the same name (`pnpm add @laminapdf/sdk@0.2.0-alpha.5`), and Deno takes `npm:@laminapdf/sdk@0.2.0-alpha.5`. The package brings [`@laminapdf/wasm`](https://www.npmjs.com/package/@laminapdf/wasm), its WebAssembly modules, as a dependency.
 
 The package is ESM only. It has one entry per runtime (the `workerd`, `deno`, `browser`, `node` and `default` export conditions), and each entry loads the `.wasm` its own way. The [quick starts](../pages/quick-start/browser.md) show each one.
 
@@ -28,10 +28,10 @@ The package is ESM only. It has one entry per runtime (the `workerd`, `deno`, `b
 Add the crate at the version these docs describe:
 
 ```sh
-cargo add laminapdf@=0.2.0-alpha.3
+cargo add laminapdf@=0.2.0-alpha.5
 ```
 
-The command writes `laminapdf = "=0.2.0-alpha.3"` to `Cargo.toml`, which keeps your project on this release until you change it: alphas promise nothing to each other (see the [stability policy](../pages/reference/stability.md)). The default features are `text` (fonts and text, which includes the builder and text extraction) and `saslprep` (passwords for AES-256 files). For reading and editing only, add `--no-default-features`.
+The command writes `laminapdf = "=0.2.0-alpha.5"` to `Cargo.toml`, which keeps your project on this release until you change it: alphas promise nothing to each other (see the [stability policy](../pages/reference/stability.md)). The default features are `text` (fonts and text, which includes the builder and text extraction) and `saslprep` (passwords for AES-256 files). For reading and editing only, add `--no-default-features`.
 
 ## Every published package
 
@@ -58,6 +58,10 @@ Most projects need only the two above. The table links every published package t
 | `laminapdf-render` | [crates.io](https://crates.io/crates/laminapdf-render) | The Rust interface that page renderers implement |
 | `laminapdf-render-pdfium` | [crates.io](https://crates.io/crates/laminapdf-render-pdfium) | The native PDFium renderer |
 
+*Each JavaScript package and what it depends on, beside the Rust API.*
+
+In JavaScript, `@laminapdf/sdk` is the TypeScript API, and it depends on `@laminapdf/wasm`, whose WebAssembly the SDK loads as three modules: base, extract and text. `@laminapdf/viewer`, a web PDF viewer, depends on `@laminapdf/sdk`, on `@laminapdf/render`, the interface that renderers implement, and on both renderers. Those renderers are `@laminapdf/render-pdfium`, the default, and `@laminapdf/render-hayro`, which also uses `@laminapdf/wasm`. In Rust, the API is one crate, `laminapdf`, with features instead of modules.
+
 ## Try a change before it's released
 
 An unreleased change is only in the repository, so build the packages from a checkout. You need Rust (the toolchain in `rust-toolchain.toml` installs itself), Node 22 or newer and pnpm:

package/docs/pages/quick-start/browser.md

@@ -1,7 +1,7 @@
 ---
 title: "Browser and bundlers"
 description: "Load @laminapdf/sdk in a web page through Vite or another bundler."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 url: "https://docs.laminapdf.com/quick-start/browser/"
 ---
 
@@ -13,6 +13,8 @@ In a browser, `@laminapdf/sdk` finds its `.wasm` files with `new URL("…", impo
 
 This app builds one A4 page that says "Hello, world!" and offers it to your user as `hello.pdf`:
 
+**TypeScript**
+
 `packages/sdk/examples/quick-start/browser.ts`:
 
 ```ts
@@ -56,6 +58,8 @@ export async function hello(
 }
 ```
 
+**Result:** [hello.pdf](https://docs.laminapdf.com/examples/pdf/hello.pdf)
+
 Import `hello` from your page's script and call it when your user asks for the file, for example from a button: `button.addEventListener("click", () => hello())`. Then start the page with your bundler, such as `npx vite`.
 
 Lamina PDF's tests bundle this app with Vite, run it in Chromium, Firefox and WebKit, and check that it builds the reference PDF byte for byte.