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

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

@@ -0,0 +1,154 @@
+---
+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.4"
+url: "https://docs.laminapdf.com/guides/save-a-pdf/"
+---
+
+# Save a PDF
+
+Save edits as a revision appended to the original bytes or as a whole new file, and see when a file refuses a save.
+
+You'll save an edited PDF, either by appending your changes to the original bytes or by writing the whole file again. The choice matters when a file is signed, was damaged, or is password-protected, because each one limits how it can be saved.
+
+This example, from [Edit a PDF](../../pages/guides/edit-a-pdf.md), asks for an [incremental save](../../pages/reference/glossary.md#incremental-save), which keeps the original bytes at the start of the result, unchanged:
+
+**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" });
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/generate_then_edit.rs`:
+
+````rust
+//! Generate a document, then open its bytes, edit them and save incrementally.
+//!
+//! The edit changes the Info dictionary with an op (undoable and serialisable), and the
+//! incremental save keeps the generated bytes as they are, with one revision appended.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example generate_then_edit -- [out-dir]   # writes <out-dir>/generate_then_edit.pdf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    BuildOptions, Builder, Document, InfoPatch, Metadata, Op, OpenOptions, PageSize, PdfDate, PointPt, Pt, SaveMode,
+    SaveOptions, SetInfo, Standard14,
+};
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let out = PathBuf::from(std::env::args().nth(1).unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    let bytes = build(BuildOptions::new(), None)?;
+    std::fs::write(out.join("generate_then_edit.pdf"), bytes)?;
+    Ok(())
+}
+
+/// The generated file followed by the edit's revision. `edited_at` is recorded as the
+/// modification date; `options` can fix the file ID, the producer and the creation date.
+pub(crate) fn build(options: BuildOptions, edited_at: Option<PdfDate>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let generated = generate(options)?;
+    edit(generated, edited_at)
+}
+
+/// A one-page draft, saved (a new document is always saved as a full rewrite).
+pub(crate) fn generate(options: BuildOptions) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let helvetica = b.standard_font(Standard14::Helvetica)?;
+    let mut page = b.page(PageSize::A4);
+    page.surface().text(
+        "Draft report",
+        &helvetica,
+        Pt::new(20.0),
+        PointPt::from_points(72.0, 96.0),
+    )?;
+    page.finish()?;
+    b.metadata(Metadata::default().with_title("Draft report"));
+    Ok(b.finish()?.save(&SaveOptions::new())?.bytes)
+}
+
+/// Opens `bytes`, edits the Info dictionary in one transaction (which `undo` could revert) and
+/// saves incrementally: `bytes` unchanged, then the appended revision.
+fn edit(bytes: Vec<u8>, edited_at: Option<PdfDate>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut doc = Document::open_bytes(bytes, OpenOptions::new())?;
+    let patch = InfoPatch::new()
+        .title(Some("Final report"))
+        .author(Some("Ada Lovelace"));
+    doc.apply(vec![Op::from(SetInfo::new(patch, edited_at))])?;
+    let options = SaveOptions::new().with_mode(SaveMode::Incremental);
+    Ok(doc.save(&options)?.bytes)
+}
+````
+
+**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:
+
+| `mode` | What it writes |
+| --- | --- |
+| `auto` (the default) | Incremental when that's allowed, otherwise a full rewrite |
+| `incremental` | The original bytes unchanged, then one appended revision |
+| `fullRewrite` | The whole file again |
+
+`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:
+
+- **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**, 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.
+
+Next: [open password-protected files](../../pages/guides/password-protected-files.md).

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.4"
+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

@@ -0,0 +1,82 @@
+---
+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.4"
+url: "https://docs.laminapdf.com/guides/untrusted-files/"
+---
+
+# Open files you don't trust
+
+Cap how much work an uploaded PDF can make Lamina PDF do, and refuse damaged files with strict mode.
+
+You'll open uploads with caps on how much an untrusted file can make Lamina PDF decode, read or draw. You need this on any server or page that opens PDFs from strangers, because a small file can ask for gigabytes of work.
+
+This example opens uploads with tighter limits than the defaults: at most 16 MiB decoded from one stream and 64 MiB in all:
+
+`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;
+  }
+}
+```
+
+## Set only the limits you need
+
+That work takes many forms: a stream that inflates to gigabytes, a page tree thousands of levels deep, drawings nested inside drawings. Lamina PDF keeps every file within the `limits` you pass when you open it. Every limit has a safe default, so you set only the ones you want to change.
+
+## Hard and soft limits
+
+- **Hard limits** stop the call with `limit-exceeded`. Its `data.limit` names the limit, so you can tell the user which one.
+- **Soft limits** drop the excess with a warning and carry on.
+
+| Limit | Kind | Default | What it caps |
+| --- | --- | --- | --- |
+| `maxNestingDepth` | hard | 256 | arrays and dictionaries inside each other; saved graphics states (`q`) |
+| `maxStreamDecoded` | hard | 64 MiB | bytes one stream decodes to, per filter stage |
+| `maxDecodedTotal` | hard | 1 GiB | bytes one call (`open`, one page's content, one read) decodes, across all streams |
+| `maxFilterChain` | hard | 8 | filters on one stream |
+| `maxResolveDepth` | hard | 32 | indirect objects in flight while following a chain of references |
+| `maxPageTreeDepth` | hard | 256 | `/Kids` levels below the page-tree root (a deeper subtree is skipped with a warning) |
+| `maxTreeDepth` | hard | 64 | name and number tree levels, outline depth |
+| `maxStringLength` | hard | 16 MiB | bytes in one string or name |
+| `maxXrefSections` | soft | 4,096 | `/Prev` hops in the [cross-reference table](../../pages/reference/glossary.md#cross-reference-table) chain (past it, Lamina PDF rebuilds the table by scanning) |
+| `maxObjectNumber` | soft | 8,388,607 | the highest object number kept |
+| `maxWarnings` | soft | 1,000 | warnings kept per document (then one `warnings-truncated`) |
+| `maxContentOperators` | hard | 10,000,000 | drawing operators run in one content call, counting a form's each time it is drawn |
+| `maxXobjectDepth` | hard | 32 | forms drawn inside forms |
+| `maxImagePixels` | hard (reserved) | 2²⁸ | pixels of one image |
+| `maxReadWindow` | hard | 256 MiB | one read from a range source (`Document.openRange`) |
+
+These are the TypeScript names. In Rust they're builder methods, such as `Limits::new().with_max_stream_decoded(…)`.
+
+## Refuse damaged files
+
+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

@@ -0,0 +1,33 @@
+---
+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.4"
+url: "https://docs.laminapdf.com/"
+---
+
+# Lamina PDF
+
+Create, read, edit and save PDFs from Rust and TypeScript, with one Rust core that runs natively and as WebAssembly.
+
+Lamina PDF creates, reads, edits and saves PDFs. One Rust core does the work, and it runs natively and as WebAssembly in browsers, Node, Deno, Bun and Cloudflare Workers. It's for apps that make documents, such as invoices, reports and tickets, and for apps that open documents other people send.
+
+- **[`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.4` and `cargo add laminapdf@=0.2.0-alpha.4`. [Install](../pages/install.md) lists every published package.
+
+## What works today
+
+| Area | What you get | Guide |
+| --- | --- | --- |
+| Generate | Pages, text with shaping, bidi and line breaking, embedded and subset fonts, the standard 14, vectors, colour, images, tagged PDF | [Fonts and text](../pages/guides/fonts-and-text.md), [Images and vectors](../pages/guides/images-and-vectors.md) |
+| Navigate | Links, named destinations, outlines, page labels, Info and XMP metadata | [Links, outlines and metadata](../pages/guides/links-outlines-and-metadata.md) |
+| Edit | Ops in transactions, undo and redo, incremental or full saves that respect signatures | [Edit a PDF](../pages/guides/edit-a-pdf.md), [Save a PDF](../pages/guides/save-a-pdf.md) |
+| Read safely | Repair of damaged files as warnings, resource limits, strict mode, passwords | [Open password-protected files](../pages/guides/password-protected-files.md), [Open files you don't trust](../pages/guides/untrusted-files.md) |
+| Errors | One coded error and warning shape on every surface | [Errors and warnings](../pages/concepts/errors-and-warnings.md) |
+
+Every code block on this site is a tested example file, so the code you see is the code that runs. Each example writes the same bytes in Rust and in every JavaScript runtime.
+
+## Where to go next
+
+Start with [your first PDF](../pages/start/first-pdf.md), then read [how Lamina PDF thinks about a PDF](../pages/concepts/how-lamina-thinks.md). When you're ready for your own setup, pick [your runtime](../pages/quick-start/browser.md).