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

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

@@ -0,0 +1,221 @@
+---
+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.4"
+url: "https://docs.laminapdf.com/guides/images-and-vectors/"
+---
+
+# Shapes, colour and images
+
+Draw lines, shapes and images on a page, in any colour, with transparency, clipping and transforms.
+
+You'll draw lines, shapes and images on a page, in colour and with transparency. You need this for anything visual in a PDF: a logo, a chart, the rules of a table or a photo.
+
+Shapes and images need only the base module (`init()`).
+
+## Draw a shape
+
+`surface.path(p => …)` returns the shape unpainted. Paint it with `fill`, `stroke` or `fillStroke`, or call `clip` to limit what comes after to its inside. A value that makes no shape, such as NaN or a negative line width, fails `page.finish()` with `invalid-geometry`.
+
+## Colour it
+
+A colour is gray `[g]`, RGB `[r, g, b]`, CMYK `[c, m, y, k]` or hex. Opacity and blend modes set how a drawing mixes with what's already on the page: in the example, `multiply` darkens where a shape overlaps what's below it.
+
+## Place an image
+
+- `Image.jpeg(bytes)` embeds a JPEG as it is, without decoding it.
+- `Image.png(bytes)` keeps the PNG's transparency.
+- `Image.rgba(width, height, pixels)` takes raw pixels.
+
+## Move, turn and scale
+
+A `Matrix` rotates, scales or moves what you draw. It works in [page space](../../pages/reference/glossary.md#page-space), like every other position.
+
+This example draws rectangles, circles, curves and dashed strokes in several colours, with transparency, a clip and a rotation, and places a JPEG and a transparent image:
+
+**TypeScript**
+
+`packages/sdk/examples/images-and-vectors.ts`:
+
+```ts
+// Images and vector graphics on one A4 page. It draws shapes and a dashed Bézier curve in gray,
+// RGB, CMYK and hex colour, overlaps two translucent discs with a blend mode, clips a JPEG to an
+// ellipse and rotates an RGBA image with a soft mask. Needs only the base module.
+import { Builder, type BuilderOptions, Image, Matrix, type Surface } from "@laminapdf/sdk";
+
+/** The RGBA gradient's side, in pixels. */
+const GLOW_SIDE = 16;
+
+/**
+ * The document's bytes, with `photo` (a JPEG) on the page.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function imagesAndVectors(photo: Uint8Array, options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const jpeg = Image.jpeg(photo);
+  const glow = Image.rgba(GLOW_SIDE, GLOW_SIDE, gradient());
+  const page = b.page("A4");
+  const s = page.surface();
+  shapes(s);
+  overlappingDiscs(s);
+  images(s, jpeg, glow);
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** A square gradient whose alpha falls off towards the right. */
+function gradient(): Uint8Array {
+  const out = new Uint8Array(GLOW_SIDE * GLOW_SIDE * 4);
+  for (let y = 0; y < GLOW_SIDE; y++) {
+    for (let x = 0; x < GLOW_SIDE; x++) out.set([x * 16, y * 16, 200, 255 - x * 15], (y * GLOW_SIDE + x) * 4);
+  }
+  return out;
+}
+
+/** A rectangle, a circle and a dashed, round-capped Bézier curve. */
+function shapes(s: Surface): void {
+  s.fillColor([0.9, 0.3, 0.2])
+    .path((p) => p.rect([56, 56, 160, 100]))
+    .fill();
+  s.fillColor([0.8, 0.1, 0, 0])
+    .path((p) => p.circle([330, 106], 50))
+    .fill();
+  s.strokeColor("#2a9d8f")
+    .path((p) => p.moveTo(56, 220).cubicTo(180, 140, 300, 300, 539, 200))
+    .stroke({ width: 3, cap: "round", dash: [12, 8] });
+}
+
+/** Two translucent discs, the second multiplied onto the first. */
+function overlappingDiscs(s: Surface): void {
+  s.save().opacity(0.6, 1).fillColor([0.3]);
+  s.path((p) => p.circle([120, 330], 60)).fill();
+  s.blendMode("multiply").fillColor([1, 0.8, 0]);
+  s.path((p) => p.circle([190, 330], 60))
+    .fill()
+    .restore();
+}
+
+/** The photo clipped to an ellipse, and the gradient rotated by 30 degrees. */
+function images(s: Surface, photo: Image, glow: Image): void {
+  s.save()
+    .path((p) => p.ellipse([300, 270, 239, 120]))
+    .clip();
+  s.image(photo, [300, 250, 239, 160]).restore();
+  s.save().transform(Matrix.after(Matrix.translate(150, 520), Matrix.rotate(30)));
+  s.image(glow, [-60, -60, 120, 120]).restore();
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/images_and_vectors.rs`:
+
+````rust
+//! Images and vector graphics on one A4 page.
+//!
+//! It draws shapes and a dashed Bézier curve in gray, RGB, CMYK and hex colour, overlaps two
+//! translucent discs with a blend mode, clips a JPEG to an ellipse and rotates an RGBA image
+//! with a soft mask.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example images_and_vectors -- photo.jpg [out-dir]   # writes images_and_vectors.pdf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    BlendMode, BuildOptions, Builder, Color, Dash, FillRule, Image, LineCap, Matrix, PageSize, PathBuilder, PointPt,
+    Pt, RectPt, SaveOptions, StrokeStyle, Surface,
+};
+
+/// The RGBA gradient's side, in pixels.
+const GLOW_SIDE: u8 = 16;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args = std::env::args().skip(1);
+    let photo = std::fs::read(args.next().ok_or("usage: images_and_vectors <photo.jpg> [out-dir]")?)?;
+    let out = PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    std::fs::write(out.join("images_and_vectors.pdf"), build(BuildOptions::new(), photo)?)?;
+    Ok(())
+}
+
+/// The document's bytes, with `photo` (a JPEG) on the page. `options` can fix the file ID, the
+/// producer and the creation date.
+pub(crate) fn build(options: BuildOptions, photo: Vec<u8>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let photo = Image::jpeg(photo)?;
+    let glow = Image::rgba(u32::from(GLOW_SIDE), u32::from(GLOW_SIDE), &gradient())?;
+    let mut page = b.page(PageSize::A4);
+    let s = page.surface();
+    shapes(s)?;
+    overlapping_discs(s);
+    images(s, &photo, &glow);
+    page.finish()?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+
+/// A square gradient whose alpha falls off towards the right.
+fn gradient() -> Vec<u8> {
+    (0..GLOW_SIDE)
+        .flat_map(|y| (0..GLOW_SIDE).flat_map(move |x| [x * 16, y * 16, 200, 255 - x * 15]))
+        .collect()
+}
+
+/// A rectangle, a circle and a dashed, round-capped Bézier curve.
+fn shapes(s: &mut Surface) -> Result<(), Box<dyn Error>> {
+    let at = PointPt::from_points;
+    s.fill_color(Color::rgb(0.9, 0.3, 0.2))
+        .path(|p| _ = p.rect(RectPt::from_points(56.0, 56.0, 160.0, 100.0)))
+        .fill(FillRule::NonZero);
+    s.fill_color(Color::cmyk(0.8, 0.1, 0.0, 0.0))
+        .path(|p| _ = p.circle(at(330.0, 106.0), Pt::new(50.0)))
+        .fill(FillRule::NonZero);
+    let dashed = StrokeStyle {
+        width: Pt::new(3.0),
+        cap: LineCap::Round,
+        dash: Some(Dash::new(vec![12.0, 8.0], 0.0)),
+        ..StrokeStyle::default()
+    };
+    s.stroke_color(Color::hex("#2a9d8f")?)
+        .path(|p| {
+            p.move_to(at(56.0, 220.0))
+                .cubic_to(at(180.0, 140.0), at(300.0, 300.0), at(539.0, 200.0));
+        })
+        .stroke(&dashed);
+    Ok(())
+}
+
+/// Two translucent discs, the second multiplied onto the first.
+fn overlapping_discs(s: &mut Surface) {
+    let disc = |x: f64| move |p: &mut PathBuilder| _ = p.circle(PointPt::from_points(x, 330.0), Pt::new(60.0));
+    s.save().opacity(0.6, 1.0).fill_color(Color::gray(0.3));
+    s.path(disc(120.0)).fill(FillRule::NonZero);
+    s.blend_mode(BlendMode::Multiply).fill_color(Color::rgb(1.0, 0.8, 0.0));
+    s.path(disc(190.0)).fill(FillRule::NonZero).restore();
+}
+
+/// The photo clipped to an ellipse, and the gradient rotated by 30 degrees.
+fn images(s: &mut Surface, photo: &Image, glow: &Image) {
+    s.save()
+        .path(|p| _ = p.ellipse(RectPt::from_points(300.0, 270.0, 239.0, 120.0)))
+        .clip(FillRule::NonZero);
+    s.image(photo, RectPt::from_points(300.0, 250.0, 239.0, 160.0))
+        .restore();
+    let placement = Matrix::translate(150.0, 520.0).after(&Matrix::rotate(30.0));
+    s.save().transform(placement);
+    s.image(glow, RectPt::from_points(-60.0, -60.0, 120.0, 120.0)).restore();
+}
+````
+
+**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.
+
+Next: [links, outlines and metadata](../../pages/guides/links-outlines-and-metadata.md).

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

@@ -0,0 +1,85 @@
+---
+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.4"
+url: "https://docs.laminapdf.com/guides/keep-the-page-responsive/"
+---
+
+# Keep the page responsive
+
+Run Lamina PDF in a Web Worker with @laminapdf/sdk/worker, so a large file never freezes the page.
+
+You'll run Lamina PDF in a Web Worker, so opening or saving a large file never freezes your page. You need this in a browser app once files get big: on the main thread, a [full rewrite](../../pages/reference/glossary.md#full-rewrite) of a 50 MB file blocks the page for about 200 ms.
+
+`@laminapdf/sdk` is synchronous after `init()`. `@laminapdf/sdk/worker` runs the same API in a Web Worker, where you call the same methods and each returns a `Promise`. This example opens a file in a Web Worker and saves it there. The save reports its progress, and aborting the signal stops the work, for example when the user presses Cancel:
+
+`packages/sdk/examples/worker-client.ts`:
+
+```ts
+// Saving a PDF in a Web Worker, so a large file never blocks the page: `@laminapdf/sdk/worker`
+// runs the same API there, and each method returns a Promise. The save reports its progress step
+// by step, and aborting the signal (a Cancel button, say) stops the work.
+import { type CallOptions, connect } from "@laminapdf/sdk/worker";
+
+/** What the save reports to and listens to. */
+export type SaveInWorkerOptions = Pick<CallOptions, "onProgress" | "signal">;
+
+/**
+ * Opens `bytes` in a Web Worker and saves them there as a full rewrite.
+ *
+ * @param bytes - any PDF; it is copied to the worker (`transfer: true` would move it).
+ * @param options - `onProgress` is called after each step of the save. Aborting `signal` stops
+ *   the work wherever it is (starting the Web Worker, opening, or at the save's next step), and
+ *   the promise rejects with a `cancelled` error.
+ * @returns the saved file.
+ */
+export async function saveInWorker(bytes: Uint8Array, options: SaveInWorkerOptions = {}): Promise<Uint8Array> {
+  const client = await connect(options);
+  try {
+    await using doc = await client.open(bytes, options);
+    return await doc.save({ mode: "fullRewrite" }, options);
+  } finally {
+    client.terminate();
+  }
+}
+```
+
+## Call the same methods, awaited
+
+Getters become methods: `await doc.pageCount()`. `doc.page(i)` returns a remote page, and `page.text()` returns a `PageText`, once you've called `client.loadExtract()`.
+
+The Web Worker leaves out a few members, each for a reason:
+
+- **`transact`:** its callback can't cross to the Web Worker, so pass the edits to `apply(ops)` instead.
+- **`saveJob`:** the Web Worker's `save` already works in steps.
+- **`ensure`:** the Web Worker fetches the byte ranges a call needs by itself.
+- **`free`:** call `doc.close()`, or use `await using`, instead.
+- **`Builder`:** build on the main thread, or in a Web Worker of your own.
+
+## Cancel a call
+
+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` 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
+
+Saved bytes and page text come back transferred, not copied. Your input is copied unless you pass `transfer: true`, which moves it and leaves your buffer empty.
+
+## Recover from a crash
+
+If the Web Worker dies, pending calls reject with `worker-crashed`, and `client.on("crashed", …)` fires. `client.restart()` starts a fresh Web Worker, and you open your documents again.
+
+`connect()` also checks that the Web Worker comes from the same `@laminapdf/sdk` build as your page. It rejects with `worker-version-mismatch` otherwise.
+
+## Bundlers and a content security policy
+
+Vite and webpack bundle the Web Worker with no setup. In Vite, exclude `@laminapdf/sdk` from `optimizeDeps`, as for the main entry. To host the Web Worker's file yourself, for example under a strict content security policy, pass `connect({ worker: () => new Worker(url, { type: "module" }) })`.
+
+Next: browse the [recipes](../../pages/recipes.md), with the PDF each one makes, or the [troubleshooting](../../pages/troubleshooting.md) page when something goes wrong.

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

@@ -0,0 +1,224 @@
+---
+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.4"
+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(())
+}
+````
+
+**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.
+
+Next: [accessible PDFs](../../pages/guides/accessible-pdfs.md).

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

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