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

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

@@ -0,0 +1,222 @@
+---
+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"
+url: "https://docs.laminapdf.com/guides/links-outlines-and-metadata/"
+---
+
+# Links, outlines and metadata
+
+Add links, named destinations, an outline, page labels, viewer preferences and metadata to a document.
+
+You'll make a document readers can find their way around: links between pages and to the web, an outline (the bookmarks panel), page numbers that read i, ii, 1, 2, and a title. You need this for any document longer than a page or two.
+
+## Link to a page or the web
+
+`surface.link(rect, target, contents)` makes a clickable area. The target is a web address (`{ type: "uri" }`), a page (`{ type: "page", index }`) or a named destination (`{ type: "named", name }`). A text run takes a `link` option too. The builder checks every target when it finishes: a missing page fails with `page-index-out-of-range`, and a missing name with `unknown-destination`.
+
+`builder.destination(name, index)` names a page, so links can point to it by name.
+
+## Add an outline and page labels
+
+- **Outline:** `builder.outline([...])` builds the bookmarks a viewer shows beside the pages, with nested entries, colour, bold, italic and `open` (an entry shown expanded).
+- **Page labels:** `builder.pageLabels([{ start, style }])` sets the page numbers a viewer shows. The example below uses roman numerals for the front matter, then decimal from page 3.
+- **Viewer preferences:** for example, `pageMode: "outlines"` opens the file with the outline showing.
+
+## Set the metadata
+
+`builder.metadata({ title, author, … })` sets the document's title, author and the rest (see Details).
+
+This example builds four pages that link to each other and to the web, with an outline, page labels and the outline shown on open. It draws its labels as text, so it needs the text module. It sets no metadata ([Edit a PDF](../../pages/guides/edit-a-pdf.md) does). The example:
+
+**TypeScript**
+
+`packages/sdk/examples/links-and-outlines.ts`:
+
+```ts
+// Links and outlines: four A5 pages joined by links, bookmarks and page labels. The title page
+// links to a website, to a page and through a named destination; every other page has a linked
+// text run back to it. The outline is nested and shown when the file opens.
+import { Builder, type BuilderOptions, Font, type LinkTarget, type Surface } from "@laminapdf/sdk";
+
+const TITLES = ["Title page", "Contents", "Chapter 1", "Chapter 2"] as const;
+const MARGIN = 36;
+const TITLE_BASELINE = 60;
+const TITLE_SIZE = 18;
+const LINK_SIZE = 12;
+/** The baselines of the title page's three links. */
+const LINK_BASELINES = [100, 125, 150] as const;
+/** A link's clickable box: this wide, this tall, starting this far above the baseline. */
+const LINK_WIDTH = 220;
+const LINK_HEIGHT = 20;
+const LINK_RISE = 15;
+
+/**
+ * The document's bytes. Needs `init({ text: true })`.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function linksAndOutlines(options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const font = Font.standard("Helvetica");
+  b.font(font);
+  b.destination("chapter-2", 3);
+  TITLES.forEach((title, index) => {
+    const page = b.page("A5");
+    const s = page.surface();
+    s.text(title, { font, size: TITLE_SIZE, at: [MARGIN, TITLE_BASELINE] });
+    if (index === 0) titlePageLinks(s, font);
+    else {
+      const link = { target: { type: "page", index: 0 }, contents: "Title page" } as const;
+      s.text("Back to the title page", { font, size: LINK_SIZE, at: [MARGIN, 100], fill: [0, 0.2, 0.8], link });
+    }
+    page.finish();
+  });
+  navigation(b);
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** The title page's links: to a website, to a page, and to a named destination. */
+function titlePageLinks(s: Surface, font: Font): void {
+  const links: readonly (readonly [label: string, target: LinkTarget, contents?: string])[] = [
+    ["Visit example.com", { type: "uri", uri: "https://example.com/" }, "Example"],
+    ["Go to chapter 1", { type: "page", index: 2 }],
+    ["Go to chapter 2 (named)", { type: "named", name: "chapter-2" }],
+  ];
+  links.forEach(([label, target, contents], i) => {
+    const baseline = LINK_BASELINES[i] ?? 0;
+    s.text(label, { font, size: LINK_SIZE, at: [MARGIN, baseline] });
+    s.link([MARGIN, baseline - LINK_RISE, LINK_WIDTH, LINK_HEIGHT], target, contents);
+  });
+}
+
+/** The outline (bookmarks), the page labels, and the viewer opening with the outline shown. */
+function navigation(b: Builder): void {
+  b.outline([
+    { title: "Title page", target: { type: "page", index: 0 } },
+    { title: "Contents", target: { type: "page", index: 1 }, color: [0, 0, 0.6] },
+    {
+      title: "Chapters",
+      open: true,
+      bold: true,
+      children: [
+        { title: "Chapter 1", target: { type: "page", index: 2 } },
+        { title: "Chapter 2", target: { type: "named", name: "chapter-2" }, italic: true },
+      ],
+    },
+  ]);
+  b.pageLabels([
+    { start: 0, style: "lowerRoman" },
+    { start: 2, style: "decimal" },
+  ]).viewerPreferences({ pageMode: "outlines" });
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/links_and_outlines.rs`:
+
+````rust
+//! Links and outlines: four A5 pages joined by links, bookmarks and page labels.
+//!
+//! The title page has a URI link, a link to a page and one through a named destination; every
+//! other page has a linked text run back to it. The outline (bookmarks) is nested and open in
+//! the viewer, and the pages are labelled i, ii, 1, 2.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example links_and_outlines -- [out-dir]   # writes <out-dir>/links_and_outlines.pdf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    BuildOptions, Builder, Color, Fit, FontHandle, LabelStyle, LinkTarget, OutlineEntry, PageLabel, PageMode, PageSize,
+    PointPt, Pt, RectPt, SaveOptions, Standard14, Surface, ViewerPreferences,
+};
+
+const TITLES: [&str; 4] = ["Title page", "Contents", "Chapter 1", "Chapter 2"];
+const MARGIN: f64 = 36.0;
+const TITLE_AT: PointPt = PointPt::from_points(MARGIN, 60.0);
+const BACK_AT: PointPt = PointPt::from_points(MARGIN, 100.0);
+const TITLE_SIZE: Pt = Pt::new(18.0);
+const LINK_SIZE: Pt = Pt::new(12.0);
+/// The baselines of the title page's three links.
+const LINK_BASELINES: [f64; 3] = [100.0, 125.0, 150.0];
+/// A link's clickable box: this wide, this tall, starting this far above the baseline.
+const LINK_WIDTH: f64 = 220.0;
+const LINK_HEIGHT: f64 = 20.0;
+const LINK_RISE: f64 = 15.0;
+
+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)?;
+    std::fs::write(out.join("links_and_outlines.pdf"), build(BuildOptions::new())?)?;
+    Ok(())
+}
+
+/// The document's bytes. `options` can fix the file ID, the producer and the creation date.
+pub(crate) fn build(options: BuildOptions) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let helvetica = b.standard_font(Standard14::Helvetica)?;
+    b.destination("chapter-2", 3, Fit::Page);
+    for (index, title) in (0_u32..).zip(TITLES) {
+        let mut page = b.page(PageSize::A5);
+        let s = page.surface();
+        s.text(title, &helvetica, TITLE_SIZE, TITLE_AT)?;
+        if index == 0 {
+            title_page_links(s, &helvetica)?;
+        } else {
+            s.text("Back to the title page", &helvetica, LINK_SIZE, BACK_AT)?
+                .fill(Color::rgb(0.0, 0.2, 0.8))
+                .link(LinkTarget::page(0), Some("Title page".into()));
+        }
+        page.finish()?;
+    }
+    navigation(&mut b)?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+
+/// The title page's links: to a website, to a page, and to a named destination.
+fn title_page_links(s: &mut Surface, font: &FontHandle) -> Result<(), Box<dyn Error>> {
+    let site = LinkTarget::Uri("https://example.com/".into());
+    let links = [
+        ("Visit example.com", site, Some("Example")),
+        ("Go to chapter 1", LinkTarget::page(2), None),
+        ("Go to chapter 2 (named)", LinkTarget::Named("chapter-2".into()), None),
+    ];
+    for ((label, target, contents), baseline) in links.into_iter().zip(LINK_BASELINES) {
+        s.text(label, font, LINK_SIZE, PointPt::from_points(MARGIN, baseline))?;
+        let area = RectPt::from_points(MARGIN, baseline - LINK_RISE, LINK_WIDTH, LINK_HEIGHT);
+        s.link(area, target, contents.map(String::from));
+    }
+    Ok(())
+}
+
+/// The outline (bookmarks), the page labels, and the viewer opening with the outline shown.
+fn navigation(b: &mut Builder) -> Result<(), Box<dyn Error>> {
+    b.outline(vec![
+        OutlineEntry::new("Title page", LinkTarget::page(0)),
+        OutlineEntry::new("Contents", LinkTarget::page(1)).with_color(0.0, 0.0, 0.6),
+        OutlineEntry::heading("Chapters")
+            .open(true)
+            .bold()
+            .with_child(OutlineEntry::new("Chapter 1", LinkTarget::page(2)))
+            .with_child(OutlineEntry::new("Chapter 2", LinkTarget::Named("chapter-2".into())).italic()),
+    ])?;
+    b.page_labels(vec![
+        PageLabel::new(0, Some(LabelStyle::LowerRoman)),
+        PageLabel::new(2, Some(LabelStyle::Decimal)),
+    ])
+    .viewer_preferences(ViewerPreferences::default().with_page_mode(PageMode::Outlines));
+    Ok(())
+}
+````
+
+[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.
+
+Next: [accessible PDFs](../../pages/guides/accessible-pdfs.md).

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

@@ -0,0 +1,70 @@
+---
+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"
+url: "https://docs.laminapdf.com/guides/password-protected-files/"
+---
+
+# Open password-protected files
+
+Open PDFs that need a password, ask again when it is missing or wrong, and save them afterwards.
+
+You'll open a PDF that needs a password, and ask your user again when the password is missing or wrong. You need this for bank statements, contracts and other files that people protect before they share them.
+
+This example opens an upload with an optional password and returns the outcome as a value instead of throwing. Its test opens a file encrypted with AES-256 three times: with the right password, with none and with a wrong one:
+
+`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;
+  }
+}
+```
+
+## Pass the password
+
+Pass the password when you open the file: `Document.open(bytes, { password })`. The password goes only to the WebAssembly module. Lamina PDF never stores or logs it, and never puts it in an error.
+
+A PDF can have two passwords. The user password opens the file, and the owner password also lifts its restrictions, such as on printing or copying. Lamina PDF checks your password against both:
+
+- **Older files** (RC4 and AES-128) check the user password first.
+- **AES-256 files** check the owner password first, as PDF 2.0 requires. So a password that matches both counts as the owner's.
+
+## When the password is missing or wrong
+
+Opening fails with `password-required` when you pass no password, and with `wrong-password` when it matches neither. Nothing else has changed, so ask your user and open the file again.
+
+## Passwords with accents and other symbols
+
+A character such as "é" can be written in more than one way in Unicode, so the same password can arrive as different bytes. In TypeScript, Lamina PDF tries the password as you give it and, after `wrong-password`, again in its NFKC form, the Unicode form that makes such spellings match. Older files also accept a password's Latin-1 bytes. AES-256 files accept the password as given or in the normalised form that PDF 2.0 asks for (SASLprep).
+
+## Save an encrypted file
+
+Once you've edited an encrypted file, it saves only as an unencrypted [full rewrite](../../pages/reference/glossary.md#full-rewrite), with `removeEncryption: true`. Without that option, saving fails with `encrypted-base` (see [save a PDF](../../pages/guides/save-a-pdf.md#when-a-file-refuses-a-save)). Lamina PDF can't yet write encrypted files.
+
+> **Details:** Lamina PDF reads files encrypted with the standard security handler: RC4 (revisions 2–4), AES-128 (revision 4) and AES-256 (revisions 5 and 6), including crypt filters and unencrypted metadata. It decrypts strings and streams as the file loads.
+
+Next: [open files you don't trust](../../pages/guides/untrusted-files.md).

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

@@ -0,0 +1,144 @@
+---
+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"
+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)
+}
+````
+
+## 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.
+
+## 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** always saves incrementally, which returns its bytes unchanged.
+
+> **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/untrusted-files.md

@@ -0,0 +1,80 @@
+---
+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"
+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`.
+
+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.3"
+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.3` and `cargo add laminapdf@=0.2.0-alpha.3`. [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).

package/docs/pages/install.md

@@ -0,0 +1,75 @@
+---
+title: "Install"
+description: "Install Lamina PDF from npm or crates.io, and find every published package."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/install/"
+---
+
+# Install
+
+Install Lamina PDF from npm or crates.io, and find every published package.
+
+Lamina PDF is published to npm as [`@laminapdf/sdk`](https://www.npmjs.com/package/@laminapdf/sdk) and to crates.io as [`laminapdf`](https://crates.io/crates/laminapdf). Both are alpha releases, so name the version when you install them. A plain `npm install` or `cargo add` picks a `0.0.0` placeholder that only reserves the name.
+
+## TypeScript: `@laminapdf/sdk`
+
+Install the version these docs describe:
+
+```sh
+npm install @laminapdf/sdk@0.2.0-alpha.3
+```
+
+`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.
+
+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.
+
+## Rust: `laminapdf`
+
+Add the crate at the version these docs describe:
+
+```sh
+cargo add laminapdf@=0.2.0-alpha.3
+```
+
+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`.
+
+## Every published package
+
+Most projects need only the two above. The table links every published package to its registry page:
+
+| Package | Registry | What it holds |
+| --- | --- | --- |
+| `@laminapdf/sdk` | [npm](https://www.npmjs.com/package/@laminapdf/sdk) | The TypeScript API, for every JavaScript runtime |
+| `@laminapdf/wasm` | [npm](https://www.npmjs.com/package/@laminapdf/wasm) | The WebAssembly modules under `@laminapdf/sdk` |
+| `@laminapdf/render` | [npm](https://www.npmjs.com/package/@laminapdf/render) | The interface that page renderers implement |
+| `@laminapdf/render-pdfium` | [npm](https://www.npmjs.com/package/@laminapdf/render-pdfium) | The default web renderer, built on PDFium |
+| `@laminapdf/render-hayro` | [npm](https://www.npmjs.com/package/@laminapdf/render-hayro) | A second web renderer, built on hayro |
+| `@laminapdf/viewer` | [npm](https://www.npmjs.com/package/@laminapdf/viewer) | The core of a web PDF viewer, one worker per document |
+| `laminapdf` | [crates.io](https://crates.io/crates/laminapdf) | The Rust API: open, read, edit, save and build PDFs |
+| `laminapdf-syntax` | [crates.io](https://crates.io/crates/laminapdf-syntax) | Objects, the lexer, the parser and stream filters |
+| `laminapdf-cos` | [crates.io](https://crates.io/crates/laminapdf-cos) | File structure: the tolerant reader and the writer |
+| `laminapdf-model` | [crates.io](https://crates.io/crates/laminapdf-model) | Typed views of pages, outlines, metadata and labels |
+| `laminapdf-ops` | [crates.io](https://crates.io/crates/laminapdf-ops) | Editing ops, transactions, undo and redo |
+| `laminapdf-save` | [crates.io](https://crates.io/crates/laminapdf-save) | Incremental and full saves |
+| `laminapdf-content` | [crates.io](https://crates.io/crates/laminapdf-content) | The content-stream interpreter |
+| `laminapdf-text` | [crates.io](https://crates.io/crates/laminapdf-text) | Fonts, shaping and line breaking |
+| `laminapdf-build` | [crates.io](https://crates.io/crates/laminapdf-build) | The builder that generates PDFs |
+| `laminapdf-source` | [crates.io](https://crates.io/crates/laminapdf-source) | Byte sources filled range by range, for remote files |
+| `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 |
+
+## 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:
+
+```sh
+pnpm install
+cargo xtask wasm      # builds packages/wasm/dist/ and packages/sdk/dist/, then tests them
+```
+
+Then run `pnpm pack` in `packages/wasm` and in `packages/sdk`, and install both `.tgz` files in one command: `@laminapdf/sdk` depends on `@laminapdf/wasm` at the same version, which the registry may not have yet. In Rust, use a path dependency: `laminapdf = { path = "../laminapdf/crates/laminapdf" }`.
+
+## API docs
+
+- TypeScript: the [`@laminapdf/sdk` reference](../api/README.md), generated from the package's TSDoc comments.
+- Rust: the [Rust API](../pages/reference/rust.md) page, which links each crate's docs on docs.rs.