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

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

@@ -0,0 +1,202 @@
+---
+title: "Text and fonts"
+description: "Draw text in any script with your own fonts or the standard 14, one line at a time or as a paragraph that wraps in a box."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/guides/fonts-and-text/"
+---
+
+# Text and fonts
+
+Draw text in any script with your own fonts or the standard 14, one line at a time or as a paragraph that wraps in a box.
+
+You'll draw text on a page: single lines, and paragraphs that wrap to fit a box, in any script and direction. You need this whenever a PDF holds words, from a one-line label to a report in five languages.
+
+Text needs the text module: `init({ text: true })` or `loadText()` in TypeScript, and the default `text` feature in Rust.
+
+## Pick a font
+
+Lamina PDF draws with two kinds of font:
+
+- **The [standard 14 fonts](../../pages/reference/glossary.md#standard-14-fonts)** (`Font.standard("Helvetica")`, `Standard14::Helvetica` in Rust) need no font file and aren't embedded, because every PDF reader has them. They cover Latin text only, without shaping.
+- **Your own fonts** (`Font.fromBytes(bytes)`: TrueType, OpenType or a font collection) handle any script. Lamina PDF shapes their text, so letters join and ligatures form, and embeds only the glyphs you draw.
+
+A font is embedded once per document, however many `Font` objects name it.
+
+## Draw a line or a paragraph
+
+`surface.text(str, { font, size, at })` draws one line, with `at[1]` its baseline. `surface.textBox(str, { font, size, box, direction, align })` wraps a paragraph to fit its box and lays out each line's words in display order, so right-to-left text reads correctly. When the text doesn't fit, it reports `overflow`.
+
+This example draws five scripts (Latin with ligatures, Arabic, Devanagari, Hebrew and Chinese), each in its own embedded font:
+
+**TypeScript**
+
+`packages/sdk/examples/multilingual.ts`:
+
+```ts
+// Five scripts on one page, each as a single line and as a wrapped paragraph. The scripts are
+// Latin, Arabic and Hebrew (right to left), Devanagari and simplified Chinese; each is shaped and
+// bidi-resolved, and each paragraph wraps in a text box. Each script needs a font that covers it,
+// such as the Noto fonts (OFL).
+import { Builder, type BuilderOptions, type Direction, Font } from "@laminapdf/sdk";
+
+/** Each script's line, its paragraph and the paragraph's direction, in the order of the fonts. */
+export const SCRIPTS: readonly (readonly [line: string, paragraph: string, direction: Direction])[] = [
+  [
+    "Latin: the office staff fill the affine waffle flask",
+    "A paragraph breaks at spaces and fits the width of its box, line by line.",
+    "ltr",
+  ],
+  ["مرحبا بالعالم السلام عليكم", "مرحبا بالعالم السلام عليكم مرحبا بالعالم السلام عليكم", "rtl"],
+  ["नमस्ते दुनिया। हिन्दी पाठ का परीक्षण", "नमस्ते दुनिया। हिन्दी पाठ का परीक्षण नमस्ते दुनिया।", "ltr"],
+  ["שלום עולם וברוכים הבאים", "שלום עולם וברוכים הבאים שלום עולם וברוכים הבאים", "rtl"],
+  ["你好世界，这是中文字体子集测试。", "你好世界，这是中文字体子集测试。你好世界，这是中文。", "ltr"],
+];
+const MARGIN = 56;
+const FIRST_BASELINE = 80;
+/** The distance from one script's line to the next one's. */
+const SCRIPT_HEIGHT = 140;
+/** The paragraph's box: this far below the line, this wide and this tall. */
+const PARAGRAPH_DROP = 14;
+const PARAGRAPH_WIDTH = 220;
+const PARAGRAPH_HEIGHT = 100;
+
+/**
+ * The document's bytes. Needs `init({ text: true })`.
+ *
+ * @param fonts - one font file per script, in the order of {@link SCRIPTS}.
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function multilingual(fonts: readonly Uint8Array[], options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  if (fonts.length !== SCRIPTS.length) throw new Error(`${SCRIPTS.length} fonts, one per script, are needed`);
+  using b = new Builder(options);
+  const loaded = fonts.map((bytes) => Font.fromBytes(bytes));
+  for (const font of loaded) b.font(font);
+  const page = b.page("A4");
+  const s = page.surface();
+  SCRIPTS.forEach(([line, paragraph, direction], row) => {
+    const font = loaded[row];
+    if (font === undefined) return;
+    const y = FIRST_BASELINE + SCRIPT_HEIGHT * row;
+    s.text(line, { font, size: 16, at: [MARGIN, y] });
+    // A narrow box breaks the paragraph into lines; right-to-left paragraphs start at the right.
+    const box = [MARGIN, y + PARAGRAPH_DROP, PARAGRAPH_WIDTH, PARAGRAPH_HEIGHT] as const;
+    s.textBox(paragraph, { font, size: 12, box, direction, align: "start" });
+  });
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/multilingual.rs`:
+
+````rust
+//! Five scripts on one page, each as a single line and as a wrapped paragraph.
+//!
+//! The scripts are Latin, Arabic and Hebrew (right to left), Devanagari and simplified Chinese;
+//! each is shaped and bidi-resolved, and each paragraph wraps in a text box. Each script needs a
+//! font that covers it, such as the Noto fonts (OFL).
+//!
+//! ```sh
+//! cargo run -p laminapdf --example multilingual -- latin.ttf arabic.ttf devanagari.ttf hebrew.ttf chinese.otf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    Alignment, BuildOptions, Builder, Direction, PageSize, PointPt, Pt, RectPt, SaveOptions, TextBoxOptions,
+};
+
+/// Each script's line, its paragraph and the paragraph's direction, in the order of the fonts.
+const SCRIPTS: [(&str, &str, Direction); 5] = [
+    (
+        "Latin: the office staff fill the affine waffle flask",
+        "A paragraph breaks at spaces and fits the width of its box, line by line.",
+        Direction::LeftToRight,
+    ),
+    (
+        "مرحبا بالعالم السلام عليكم",
+        "مرحبا بالعالم السلام عليكم مرحبا بالعالم السلام عليكم",
+        Direction::RightToLeft,
+    ),
+    (
+        "नमस्ते दुनिया। हिन्दी पाठ का परीक्षण",
+        "नमस्ते दुनिया। हिन्दी पाठ का परीक्षण नमस्ते दुनिया।",
+        Direction::LeftToRight,
+    ),
+    (
+        "שלום עולם וברוכים הבאים",
+        "שלום עולם וברוכים הבאים שלום עולם וברוכים הבאים",
+        Direction::RightToLeft,
+    ),
+    (
+        "你好世界，这是中文字体子集测试。",
+        "你好世界，这是中文字体子集测试。你好世界，这是中文。",
+        Direction::LeftToRight,
+    ),
+];
+const MARGIN: f64 = 56.0;
+const FIRST_BASELINE: f64 = 80.0;
+/// The distance from one script's line to the next one's.
+const SCRIPT_HEIGHT: f64 = 140.0;
+/// The paragraph's box: this far below the line, this wide and this tall.
+const PARAGRAPH_DROP: f64 = 14.0;
+const PARAGRAPH_WIDTH: f64 = 220.0;
+const PARAGRAPH_HEIGHT: f64 = 100.0;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args: Vec<String> = std::env::args().skip(1).collect();
+    let out = PathBuf::from(if args.len() > SCRIPTS.len() {
+        args.remove(SCRIPTS.len())
+    } else {
+        "target/examples-out".into()
+    });
+    let fonts = args.iter().map(std::fs::read).collect::<Result<Vec<_>, _>>()?;
+    std::fs::create_dir_all(&out)?;
+    std::fs::write(out.join("multilingual.pdf"), build(BuildOptions::new(), fonts)?)?;
+    Ok(())
+}
+
+/// The document's bytes, with one font per script in `fonts` (in the order of [`SCRIPTS`]).
+/// `options` can fix the file ID, the producer and the creation date.
+pub(crate) fn build(options: BuildOptions, fonts: Vec<Vec<u8>>) -> Result<Vec<u8>, Box<dyn Error>> {
+    if fonts.len() != SCRIPTS.len() {
+        return Err(format!("{} fonts, one per script, are needed", SCRIPTS.len()).into());
+    }
+    let mut b = Builder::new(options);
+    let fonts = fonts
+        .into_iter()
+        .map(|bytes| b.font_bytes(bytes))
+        .collect::<Result<Vec<_>, _>>()?;
+    let mut page = b.page(PageSize::A4);
+    let s = page.surface();
+    for (row, ((line, paragraph, direction), font)) in (0_u32..).zip(SCRIPTS.iter().zip(&fonts)) {
+        let y = FIRST_BASELINE + SCRIPT_HEIGHT * f64::from(row);
+        s.text(line, font, Pt::new(16.0), PointPt::from_points(MARGIN, y))?;
+        // A narrow box breaks the paragraph into lines; right-to-left paragraphs start at the right.
+        let options = TextBoxOptions::new()
+            .with_direction(*direction)
+            .with_align(Alignment::Start);
+        let area = RectPt::from_points(MARGIN, y + PARAGRAPH_DROP, PARAGRAPH_WIDTH, PARAGRAPH_HEIGHT);
+        s.text_box(paragraph, font, Pt::new(12.0), area, &options)?;
+    }
+    page.finish()?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+````
+
+[See the output](../../pages/recipes/multilingual.md). Text extracted from it, with pdf.js, pypdf or pdftotext, equals the input strings, ligatures included.
+
+## When a font can't draw the text
+
+- **A missing character:** text a font can't encode fails with `missing-glyph`, never with a blank box.
+- **Too many letters for a standard 14 font:** a standard 14 font holds at most 37 distinct letters beyond its Western European set (WinAnsi); one more fails with `encoding-full`. Use your own font instead.
+- **A font that may not be embedded:** a font whose licence bits forbid embedding (restricted, or bitmap only) fails with `font-not-embeddable`. In Rust, `EmbedPolicy::Override` embeds it anyway, if you hold the rights. A font marked "no subsetting" is embedded whole.
+
+> **Details:** Lamina PDF shapes your own fonts' text with HarfRust, a Rust port of the HarfBuzz shaper, and subsets each font to the glyphs you draw. It embeds them as [Type 0](../../pages/reference/glossary.md#type-0) fonts with `/W` widths and a [ToUnicode](../../pages/reference/glossary.md#tounicode) [CMap](../../pages/reference/glossary.md#cmap), which is what lets the text be extracted again. Line breaking follows [UAX #14](https://www.unicode.org/reports/tr14/), and the order of mixed-direction text follows [UAX #9](https://www.unicode.org/reports/tr9/) (bidi). The licence bits are the font's `fsType`.
+
+Next: [shapes, colour and images](../../pages/guides/images-and-vectors.md).

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

@@ -0,0 +1,219 @@
+---
+title: "Shapes, colour and images"
+description: "Draw lines, shapes and images on a page, in any colour, with transparency, clipping and transforms."
+version: "0.2.0-alpha.3"
+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();
+}
+````
+
+[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,81 @@
+---
+title: "Keep the page responsive"
+description: "Run Lamina PDF in a Web Worker with @laminapdf/sdk/worker, so a large file never freezes the page."
+version: "0.2.0-alpha.3"
+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
+
+Pass an `AbortSignal` as `signal` to any call. An aborted call rejects with `cancelled`, and `error.cause` holds the signal's reason. What happens to the work depends on where it was:
+
+- A call that hasn't started never runs.
+- `save` stops at its next step, and the document stays usable.
+- Any other call runs to the end in the Web Worker, because it is one synchronous call. `client.terminate()` stops it at once.
+
+## 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.