@laminapdf/sdk 0.0.0-stage → 0.2.0-alpha.3

package/docs/pages/recipes/pdf-ua-report.md

@@ -0,0 +1,237 @@
+---
+title: "A PDF/UA report"
+description: "A one-page sales report a screen reader can follow, with headings, a table, a described chart and a link, checked against PDF/UA-1 as it's built."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/pdf-ua-report/"
+---
+
+# A PDF/UA report
+
+A one-page sales report a screen reader can follow, with headings, a table, a described chart and a link, checked against PDF/UA-1 as it's built.
+
+You'll build a one-page sales report that a screen reader can follow: headings, a table, a chart described in words and a link. You need this when a document has to meet accessibility law or a client's accessibility policy.
+
+The function turns on the PDF/UA-1 profile, then draws each part of the report inside a tag that says what it is: a heading, a table cell, a figure. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+<TabItem label="TypeScript">`packages/sdk/examples/pdf-ua-report.ts`:
+
+```ts
+// An accessible report that screen readers can follow, checked against PDF/UA-1 when it is built.
+import { Builder, Font, type Surface, type Tag, type TagName } from "@laminapdf/sdk";
+
+const MARGIN = 56;
+const ROW = 18;
+const COLUMN = 144;
+const HEADER_BASELINE = 40;
+const TITLE_BASELINE = 90;
+const TABLE_TOP = 150;
+const LINK_BASELINE = 400;
+const CHART_LEFT = 320;
+const CHART_BASE = 360;
+const BAR_WIDTH = 36;
+const BAR_PITCH = 50;
+const BODY = 11;
+/** The font sizes of the title and the headings; other text is `BODY`. */
+const SIZES: Partial<Record<TagName, number>> = { H1: 22, H2: 15 };
+const BLUE = [0.12, 0.47, 0.78] as const;
+const QUARTERS = [
+  ["Q1", 120],
+  ["Q2", 135],
+  ["Q3", 160],
+  ["Q4", 150],
+] as const;
+const CHART_ALT = "Bar chart of sales by quarter: 120, 135, 160 and 150 thousand euros.";
+
+/**
+ * The report's bytes. Needs `init({ text: true })`.
+ *
+ * @param notoSans - the bytes of the Noto Sans font file.
+ */
+export function pdfUaReport(notoSans: Uint8Array): Uint8Array<ArrayBuffer> {
+  using b = new Builder({ profiles: ["PDF/UA-1"] });
+  b.metadata({ title: "Annual sales report 2026" });
+  b.lang("en-GB");
+  const font = Font.fromBytes(notoSans);
+  b.font(font);
+  const page = b.page("A4");
+  draw(page.surface(), font);
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** One line of text with its baseline at `y`, as the structure element `tag`, sized by it. */
+function line(s: Surface, font: Font, tag: Tag, text: string, x: number, y: number): void {
+  const size = (typeof tag === "string" ? SIZES[tag] : undefined) ?? BODY;
+  s.tag(tag, (s) => s.text(text, { font, size, at: [x, y] }));
+}
+
+function draw(s: Surface, font: Font): void {
+  // The running header is decoration: an artifact, which screen readers skip.
+  s.artifact("pagination", (s) => s.text("Acme Widgets", { font, size: BODY, at: [MARGIN, HEADER_BASELINE] }));
+  line(s, font, "H1", "Annual sales report 2026", MARGIN, TITLE_BASELINE);
+  line(s, font, "P", "Sales grew in three quarters of four.", MARGIN, TITLE_BASELINE + 2 * ROW);
+  table(s, font);
+  chart(s);
+  const link = {
+    target: { type: "uri", uri: "https://example.com/accounts" },
+    contents: "The full 2026 accounts",
+  } as const;
+  s.tag("P", (s) =>
+    s.text("The full accounts", { font, size: BODY, at: [MARGIN, LINK_BASELINE], fill: [...BLUE], link }),
+  );
+}
+
+/** A heading and a table of the quarters, whose first row holds the columns' header cells. */
+function table(s: Surface, font: Font): void {
+  line(s, font, "H2", "Sales by quarter", MARGIN, TABLE_TOP);
+  const header: Tag = { type: "TH", scope: "column" };
+  s.tag("Table", (s) => {
+    s.tag("TR", (s) => {
+      line(s, font, header, "Quarter", MARGIN, TABLE_TOP + ROW);
+      line(s, font, header, "Sales (k€)", MARGIN + COLUMN, TABLE_TOP + ROW);
+    });
+    QUARTERS.forEach(([quarter, sales], i) => {
+      const y = TABLE_TOP + ROW * (i + 2);
+      s.tag("TR", (s) => {
+        line(s, font, "TD", quarter, MARGIN, y);
+        line(s, font, "TD", sales.toFixed(0), MARGIN + COLUMN, y);
+      });
+    });
+  });
+}
+
+/** The quarters as bars standing on the chart's base: one figure with alternate text. */
+function chart(s: Surface): void {
+  s.tag({ type: "Figure", alt: CHART_ALT }, (s) => {
+    s.fillColor([...BLUE]);
+    QUARTERS.forEach(([, sales], i) => {
+      s.path((p) => p.rect([CHART_LEFT + BAR_PITCH * i, CHART_BASE - sales, BAR_WIDTH, sales])).fill();
+    });
+  });
+}
+```</TabItem>
+<TabItem label="Rust">`crates/laminapdf/examples/pdf_ua_report.rs`:
+
+```rust
+//! An accessible report that screen readers can follow, checked against PDF/UA-1 when it is built.
+
+use laminapdf::{
+    ArtifactKind, BuildError, BuildOptions, Builder, Color, FillRule, FontHandle, LinkTarget, Metadata, PageSize,
+    PointPt, Profile, Pt, RectPt, SaveOptions, Surface, TableScope, Tag, TagKind,
+};
+
+const MARGIN: f64 = 56.0;
+const ROW: f64 = 18.0;
+const COLUMN: f64 = 144.0;
+const HEADER_AT: PointPt = PointPt::from_points(MARGIN, 40.0);
+const TITLE_BASELINE: f64 = 90.0;
+const TABLE_TOP: f64 = 150.0;
+const LINK_AT: PointPt = PointPt::from_points(MARGIN, 400.0);
+const CHART_LEFT: f64 = 320.0;
+const CHART_BASE: f64 = 360.0;
+const BAR_WIDTH: Pt = Pt::new(36.0);
+const BAR_PITCH: f64 = 50.0;
+const BODY: Pt = Pt::new(11.0);
+/// The font sizes of the title and the headings; other text is `BODY`.
+const SIZES: [(TagKind, Pt); 2] = [(TagKind::H1, Pt::new(22.0)), (TagKind::H2, Pt::new(15.0))];
+const BLUE: Color = Color::Rgb(0.12, 0.47, 0.78);
+const QUARTERS: [(&str, f64); 4] = [("Q1", 120.0), ("Q2", 135.0), ("Q3", 160.0), ("Q4", 150.0)];
+const CHART_ALT: &str = "Bar chart of sales by quarter: 120, 135, 160 and 150 thousand euros.";
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut args = std::env::args().skip(1);
+    let font = std::fs::read(args.next().ok_or("arguments: <font.ttf> [out-dir]")?)?;
+    let out = std::path::PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    Ok(std::fs::write(out.join("pdf_ua_report.pdf"), build(font)?)?)
+}
+
+pub(crate) fn build(font: Vec<u8>) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
+    let mut b = Builder::new(BuildOptions::new().with_profile(Profile::PdfUa1));
+    b.metadata(Metadata::default().with_title("Annual sales report 2026"));
+    b.lang("en-GB");
+    let font = b.font_bytes(font)?;
+    let mut page = b.page(PageSize::A4);
+    draw(page.surface(), &font)?;
+    page.finish()?;
+    Ok(b.finish()?.save(&SaveOptions::new())?.bytes)
+}
+
+/// One line of text with its baseline at `y`, as the structure element `tag`, sized by it.
+fn line(s: &mut Surface, font: &FontHandle, tag: impl Into<Tag>, text: &str, x: f64, y: f64) -> Result<(), BuildError> {
+    let tag = tag.into();
+    let size = SIZES.iter().find(|e| e.0 == tag.kind()).map_or(BODY, |e| e.1);
+    s.tag(tag, |s| s.text(text, font, size, PointPt::from_points(x, y)).map(drop))
+}
+
+fn draw(s: &mut Surface, font: &FontHandle) -> Result<(), BuildError> {
+    // The running header is decoration: an artifact, which screen readers skip.
+    let header = |s: &mut Surface| s.text("Acme Widgets", font, BODY, HEADER_AT).map(drop);
+    s.artifact(ArtifactKind::Pagination, header)?;
+    line(s, font, TagKind::H1, "Annual sales report 2026", MARGIN, TITLE_BASELINE)?;
+    let summary = "Sales grew in three quarters of four.";
+    line(s, font, TagKind::P, summary, MARGIN, TITLE_BASELINE + 2.0 * ROW)?;
+    table(s, font)?;
+    chart(s)?;
+    let link = LinkTarget::Uri("https://example.com/accounts".into());
+    s.tag(TagKind::P, |s| {
+        let text = s.text("The full accounts", font, BODY, LINK_AT)?;
+        text.fill(BLUE).link(link, Some("The full 2026 accounts".into()));
+        Ok(())
+    })
+}
+
+/// A heading and a table of the quarters, whose first row holds the columns' header cells.
+fn table(s: &mut Surface, font: &FontHandle) -> Result<(), BuildError> {
+    line(s, font, TagKind::H2, "Sales by quarter", MARGIN, TABLE_TOP)?;
+    let header = Tag::new(TagKind::TH).with_scope(TableScope::Column);
+    s.tag(TagKind::Table, |s| {
+        s.tag(TagKind::TR, |s| {
+            line(s, font, header.clone(), "Quarter", MARGIN, TABLE_TOP + ROW)?;
+            line(s, font, header.clone(), "Sales (k€)", MARGIN + COLUMN, TABLE_TOP + ROW)
+        })?;
+        for (row, (quarter, sales)) in (2_u8..).zip(QUARTERS) {
+            let y = TABLE_TOP + ROW * f64::from(row);
+            s.tag(TagKind::TR, |s| {
+                line(s, font, TagKind::TD, quarter, MARGIN, y)?;
+                line(s, font, TagKind::TD, &format!("{sales:.0}"), MARGIN + COLUMN, y)
+            })?;
+        }
+        Ok(())
+    })
+}
+
+/// The quarters as bars standing on the chart's base: one figure with alternate text.
+fn chart(s: &mut Surface) -> Result<(), BuildError> {
+    s.tag(Tag::new(TagKind::Figure).with_alt(CHART_ALT), |s| {
+        s.fill_color(BLUE);
+        for (i, (_, sales)) in (0_u8..).zip(QUARTERS) {
+            let x = CHART_LEFT + BAR_PITCH * f64::from(i);
+            let bar = RectPt::from_xywh(Pt::new(x), Pt::new(CHART_BASE - sales), BAR_WIDTH, Pt::new(sales));
+            s.path(|p| _ = p.rect(bar)).fill(FillRule::NonZero);
+        }
+        Ok(())
+    })
+}
+```</TabItem>
+
+The result is one A4 page that reads, in order, as a title, a summary, a table of four quarters, a bar chart and a link: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/pdf_ua_report.pdf).
+
+## How it works
+
+- `profiles: ["PDF/UA-1"]` (`Profile::PdfUa1` in Rust) tags the document and makes `finish()` check the rules a program can check. It fails with a coded error for the first rule the report breaks; [Accessible PDFs](../../pages/guides/accessible-pdfs.md#what-pdfua-asks-for) lists them.
+- `metadata` gives the report its title and `lang` its language, which PDF/UA-1 asks for. The font is an embedded Noto Sans, because PDF/UA-1 refuses the [standard 14 fonts](../../pages/reference/glossary.md#standard-14-fonts).
+- `tag` puts what its callback draws inside a structure element, such as `H1`, `P` or `TD`, in reading order. The `line` helper tags one line of text and sizes it by its tag: 22 points for `H1`, 15 for `H2`, 11 for the rest.
+- The table's first row holds `TH` header cells with a column scope, so a screen reader can name each cell's column.
+- The four bars are one `Figure` with alternate text, the sentence a screen reader reads in place of the drawing. The running header is an artifact, which screen readers skip.
+- The link's `contents`, "The full 2026 accounts", is its description. The builder makes the link a `Link` element inside its paragraph.
+
+## What to change
+
+- **The numbers:** change `QUARTERS`, then change `CHART_ALT` to match. The builder checks that the chart has alternate text, not that the text is right; see [What a program can't check](../../pages/guides/accessible-pdfs.md#what-a-program-cant-check).
+- **A list:** nest an `"L"`, an `"LI"` for each item, and inside each a `"Lbl"` for the bullet and an `"LBody"` for the text. An `L` holds `LI` items or a nested `L`, and an `LI` holds a `Lbl` and an `LBody`: anything else inside them fails `finish()` with `invalid-structure-nesting`.
+- **A passage in another language:** tag it with its own, as in `{ type: "P", lang: "fr-FR" }` (`Tag::new(TagKind::P).with_lang("fr-FR")` in Rust).
+- **Accessible and archival at once:** add a PDF/A profile beside it, as in `profiles: ["PDF/A-2u", "PDF/UA-1"]`. The [PDF/A archive](../../pages/recipes/pdf-a-archive.md) does this.
+
+Next: [a PDF/A archive](../../pages/recipes/pdf-a-archive.md), a letter written for long-term keeping.

package/docs/pages/recipes/report.md

@@ -0,0 +1,125 @@
+---
+title: "A 100-page report"
+description: "A 100-page A4 report with two embedded fonts and a table on every page, the document Lamina PDF times in each JavaScript runtime."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/report/"
+---
+
+# A 100-page report
+
+A 100-page A4 report with two embedded fonts and a table on every page, the document Lamina PDF times in each JavaScript runtime.
+
+You'll make a 100-page report with two embedded fonts: on every page, a heading, a paragraph, a line of Chinese and a table of 20 products. Start from it for any long document you generate from data, such as monthly statements or a catalogue.
+
+The function draws one region's page at a time in a loop, then returns the PDF's bytes:
+
+`packages/sdk/examples/report.ts`:
+
+```ts
+// A 100-page report with two embedded fonts. Each page has a heading, a paragraph broken into a
+// box, a line of Chinese, a table of products with rules between the rows, and a page number.
+import { Builder, type BuilderOptions, Font, PAGE_SIZES, type Rect, type Surface } from "@laminapdf/sdk";
+
+/** The number of pages. */
+const REPORT_PAGES = 100;
+const PRODUCTS = 20;
+const PRICE = 12.5;
+const [PAGE_WIDTH] = PAGE_SIZES.A4;
+const MARGIN = 56;
+const RIGHT_EDGE = PAGE_WIDTH - MARGIN;
+const HEADING_AT = [MARGIN, 72] as const;
+const PARAGRAPH_BOX = [MARGIN, 88, RIGHT_EDGE - MARGIN, 60] as const;
+const CHINESE_AT = [MARGIN, 166] as const;
+const FOOTER_AT = [MARGIN, 800] as const;
+const FIRST_ROW = 200;
+const ROW_HEIGHT = 24;
+/** The units' and the revenue's columns (left edge, width), both right-aligned. */
+const UNITS_COLUMN = [300, 60] as const;
+const REVENUE_COLUMN = [400, RIGHT_EDGE - 400] as const;
+/** A cell's box starts this far above its row's baseline and is this tall; the rule is this far below. */
+const CELL_RISE = 11;
+const CELL_HEIGHT = 14;
+const RULE_DROP = 7;
+/** Font sizes: the heading, the paragraph and the Chinese line, the table, the page number. */
+const SIZES = { heading: 20, body: 11, table: 10, footer: 9 } as const;
+const PARAGRAPH =
+  "Quarterly figures for every region follow. Each table lists the units shipped, the revenue " +
+  "and the change against the previous quarter; totals are at the end of the report.";
+
+/**
+ * The document's bytes. Needs `init({ text: true })`.
+ *
+ * @param latinFont - a font for the text, such as Noto Sans.
+ * @param chineseFont - a font with Chinese glyphs, such as Noto Sans SC.
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function report(
+  latinFont: Uint8Array,
+  chineseFont: Uint8Array,
+  options: BuilderOptions = {},
+): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const font = Font.fromBytes(latinFont);
+  const chinese = Font.fromBytes(chineseFont);
+  b.font(font);
+  b.font(chinese);
+  for (let region = 1; region <= REPORT_PAGES; region++) {
+    const page = b.page("A4");
+    const s = page.surface();
+    s.text(`Region ${region}: quarterly report`, { font, size: SIZES.heading, at: HEADING_AT });
+    s.textBox(PARAGRAPH, { font, size: SIZES.body, box: PARAGRAPH_BOX });
+    s.text("你好世界，这是中文字体子集测试。", { font: chinese, size: SIZES.body, at: CHINESE_AT });
+    products(s, font, region);
+    s.text(`Page ${region} of ${REPORT_PAGES}`, { font, size: SIZES.footer, at: FOOTER_AT });
+    page.finish();
+  }
+  b.metadata({ title: "Quarterly report", author: "lamina examples" }).lang("en-GB");
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** Made-up sales figures: the units of `product` that `region` shipped, from 0 to 499. */
+function unitsShipped(region: number, product: number): number {
+  return (region * 37 + product * 11) % 500;
+}
+
+/** A region's table: one row per product, with its units and revenue right-aligned. */
+function products(s: Surface, font: Font, region: number): void {
+  for (let product = 0; product < PRODUCTS; product++) {
+    const y = FIRST_ROW + ROW_HEIGHT * product;
+    const units = unitsShipped(region, product);
+    const size = SIZES.table;
+    s.text(`Product ${product + 1}`, { font, size, at: [MARGIN, y] });
+    s.textBox(String(units), { font, size, box: cell(UNITS_COLUMN, y), align: "end" });
+    s.textBox(`€ ${(units * PRICE).toFixed(2)}`, { font, size, box: cell(REVENUE_COLUMN, y), align: "end" });
+    s.strokeColor([0.8])
+      .path((p) => p.moveTo(MARGIN, y + RULE_DROP).lineTo(RIGHT_EDGE, y + RULE_DROP))
+      .stroke({ width: 0.5 });
+  }
+}
+
+/** The box of a cell in `column` (left edge, width) on the row at `baseline`. */
+function cell([left, width]: readonly [number, number], baseline: number): Rect {
+  return [left, baseline - CELL_RISE, width, CELL_HEIGHT];
+}
+```
+
+The result is 100 A4 pages, one per region. It has no reference PDF to open. Instead, Lamina PDF's tests build and time the report in every JavaScript runtime and check its SHA-256 there, as does the Rust benchmark that builds the same bytes.
+
+## How it works
+
+- It needs the text module, `init({ text: true })`, because it draws with embedded fonts.
+- `Font.fromBytes` reads each font file, and `b.font` registers both before the first page. Each font is embedded once for the whole report, with only the glyphs its 100 pages draw.
+- `s.text` draws one line, with `at[1]` as its baseline, and `s.textBox` breaks the paragraph into lines that fit `PARAGRAPH_BOX`.
+- In the table, the units and the revenue are text boxes as wide as their columns, with `align: "end"` to right-align them. `cell` works out each box from its column and the row's baseline.
+- `strokeColor([0.8])` sets a light gray, and each rule is a path from the left margin to the right edge, stroked 0.5 points wide.
+- `metadata` and `lang("en-GB")` set the title, author and language once for the document, and `using` frees the builder and the document when the function returns.
+
+## What to change
+
+- **Your data:** replace `unitsShipped` with your own figures, and set `REPORT_PAGES` and `PRODUCTS` to your counts.
+- **A longer table:** 20 rows end at 656 points, above the page number at 800. For more rows, lower `ROW_HEIGHT` or carry the rest over to the next page.
+- **Another script:** load a font that covers it and draw its text in that font, as the Chinese line does. See [Text and fonts](../../pages/guides/fonts-and-text.md).
+- **The file's details:** pass `producer` and `creationDate` in `options`, such as `creationDate: "D:20261104120000Z"`. The builder never reads the clock, so a report without a date has none.
+
+Next: [open someone else's file](../../pages/recipes/open-untrusted.md), with a password and tighter limits.

package/docs/pages/recipes/web-worker-client.md

@@ -0,0 +1,64 @@
+---
+title: "Save in a Web Worker"
+description: "Open and save a PDF in a Web Worker, so a large file never freezes the page, with progress as it saves and a signal that stops the work."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/web-worker-client/"
+---
+
+# Save in a Web Worker
+
+Open and save a PDF in a Web Worker, so a large file never freezes the page, with progress as it saves and a signal that stops the work.
+
+You'll save a PDF in a Web Worker, reporting progress as it goes and stopping when the user presses Cancel. You need this in a browser app once files get large, because a save on the main thread freezes the page until it ends.
+
+`saveInWorker` starts a Web Worker, opens the bytes there and saves them as a [full rewrite](../../pages/reference/glossary.md#full-rewrite), handing your `onProgress` and `signal` to each call:
+
+`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();
+  }
+}
+```
+
+The promise resolves to the saved file, or rejects with `cancelled` once the signal aborts. Lamina PDF's tests run it in Chromium, Firefox and WebKit.
+
+## How it works
+
+- `connect` starts the Web Worker file that ships with `@laminapdf/sdk` and checks that it comes from the same build as your page.
+- `client.open` copies the bytes into the Web Worker and returns a remote document, whose methods return promises. `await using` closes it there when the block ends.
+- The Web Worker saves in steps of 20,000 units of work, about one per object in a full rewrite. Between steps it calls `onProgress` with `done`, `total` and `phase`, at most every 50 ms, so a small file saves in one step and reports none.
+- Aborting the signal rejects the call at once with `cancelled`, and `error.cause` holds the signal's reason. A save stops at its next step.
+- `client.terminate()` in `finally` stops the Web Worker however the save ended, which also stops an open that was still running.
+
+## What to change
+
+- **A progress bar:** in `onProgress`, set a `<progress>` element's `value` to `done` and, when the save knows it, its `max` to `total`.
+- **Large files:** pass `transfer: true` to `client.open` to move the buffer instead of copying it, which leaves your copy empty. See [Keep the page responsive](../../pages/guides/keep-the-page-responsive.md#move-bytes-instead-of-copying-them).
+- **Several files:** call `connect` once, reuse the client for each file, and terminate it when the page no longer needs it.
+- **Edits before the save:** apply them with `await doc.apply(ops)`, then save in the default `auto` mode. It appends them as an [incremental save](../../pages/reference/glossary.md#incremental-save) when the file allows one. See [Save a PDF](../../pages/guides/save-a-pdf.md#choose-a-save-mode).
+
+Next: [a Cloudflare Worker](../../pages/recipes/cloudflare-worker.md) that generates a PDF per request.

package/docs/pages/recipes.md

@@ -0,0 +1,47 @@
+---
+title: "Recipes"
+description: "Complete Lamina PDF programs, from one page of text to an archived invoice, each with its code and the PDF it writes."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/"
+---
+
+# Recipes
+
+Complete Lamina PDF programs, from one page of text to an archived invoice, each with its code and the PDF it writes.
+
+Each recipe is a complete program to copy: what it makes, the code, how it works and what to change. Pick the one closest to the document you need, and change it from there.
+
+Most recipes exist twice, in Rust and in TypeScript, and both write exactly the same bytes. Lamina PDF's tests check that on every change, in Rust and in every JavaScript runtime: Node, Chromium, Firefox, WebKit, Deno, Bun and workerd. Each recipe shows the tested code, and its reference PDF is the file that code writes.
+
+To run a Rust recipe from a checkout of Lamina PDF, use `cargo run -p laminapdf --example <name>`. Its header comment lists the arguments it takes, such as the font or image files it reads.
+
+## Create a PDF
+
+- [Hello, world](../pages/recipes/hello.md): one page of text in a standard 14 font.
+- [An invoice](../pages/recipes/invoice.md): an embedded font, a table of line items, and tags for screen readers.
+- [Multilingual text](../pages/recipes/multilingual.md): five scripts, each in its own embedded font.
+- [Images and vectors](../pages/recipes/images-and-vectors.md): paths, colour, transparency, a clip and two images.
+- [Links and outlines](../pages/recipes/links-and-outlines.md): links, an outline and page labels.
+
+## Edit a PDF
+
+- [Generate, then edit](../pages/recipes/generate-then-edit.md): open a file's bytes, change its metadata and save incrementally.
+
+## Read a PDF
+
+- [Extract text for an LLM](../pages/recipes/extract-markdown.md): Markdown, JSON with boxes, and chunks for retrieval, in TypeScript and Rust.
+
+## Meet a standard
+
+- [A PDF/UA report](../pages/recipes/pdf-ua-report.md): an accessible report a screen reader can follow.
+- [A PDF/A archive](../pages/recipes/pdf-a-archive.md): a letter for long-term archiving.
+- [A PDF/A-3 invoice with XML](../pages/recipes/pdf-a3-invoice-with-xml.md): an invoice with its data attached.
+
+## Run it in production (TypeScript)
+
+- [A 100-page report](../pages/recipes/report.md): the case Lamina PDF times in every runtime.
+- [Open someone else's file](../pages/recipes/open-untrusted.md): a password and tighter limits, with the outcome as a value.
+- [Save in a Web Worker](../pages/recipes/web-worker-client.md): progress and cancelling, off the main thread.
+- [A Cloudflare Worker](../pages/recipes/cloudflare-worker.md): a PDF per request.
+
+Next: [Hello, world](../pages/recipes/hello.md), the smallest PDF Lamina PDF writes.

package/docs/pages/reference/changelog.md

@@ -0,0 +1,86 @@
+---
+title: "Changelog"
+description: "What changed in each Lamina PDF release, newest first."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/changelog/"
+---
+
+# Changelog
+
+What changed in each Lamina PDF release, newest first.
+
+Every Lamina PDF package shares one version, so each entry covers all of them, from the Rust crates to `@laminapdf/sdk` and the viewer. Breaking changes come first, under **Minor Changes**, as the [stability policy](../../pages/reference/stability.md) explains. Versions from `0.2.0-alpha.2` on are on npm and crates.io; earlier ones were never published.
+
+## 0.2.0-alpha.3
+
+### Minor Changes
+
+- The package now carries its docs as Markdown in `docs/`, matched to its version: every page of the docs site, the API reference, a page per error code, `renames.json` (what renamed items are called now) and `AGENTS.md`, a snippet for your project's agent instructions. The `laminapdf` crate ships the same folder without the API reference. The docs site serves a Markdown copy of every page, `llms.txt` and `llms-full.txt`.
+- Every handle on WebAssembly memory frees with `free()` or `using`: `Document`, `PageRef`, `SaveJob`, `Builder`, `Page` and `Image`. A second `free()` does nothing, and any other call afterwards throws `disposed` instead of a glue error. A page or save job is freed with its document, and freeing a document now frees its memory at once, even while pages of it are still held. Pages of a freed builder throw `disposed` too (`builder-finished` once it finishes), and a freed `Image` throws `disposed` instead of decoding again.
+  
+Each module's memory may grow to 2 GiB. Past that, the module traps and the call throws `out-of-memory`; any other trap throws `wasm-trap`. The next call runs in a fresh instance, and handles of the old one throw `instance-reset`. The new `reset()` gives grown memory back by starting every module afresh, and the new `onLeak(hook)` reports handles the garbage collector reclaims without a `free()`.
+- `doc.extract({ format })` gives a document's text for an LLM or a search index: Markdown or plain text in reading order, the `laminapdf.extract/1` JSON with a box for every block (the same bytes as Rust's `extract_json`), or chunks sized for retrieval. Tables drawn with lines come out as tables, and hidden text is left out. It needs the extract or text module.
+- Two new warning codes, `extract-table-ambiguous` and `extract-table-limit`, join the generated `WarningCode` union. In Rust, `laminapdf-extract` is now published, and the `laminapdf` crate exposes it. `Document::extract`, `extract_job` and `extract_json` return blocks in reading order, with tables and their cells. An `Extraction` renders as Markdown, plain text, retrieval chunks or `laminapdf.extract/1` JSON, whose JSON Schema is in `laminapdf-extract`'s `schemas/`.
+- Breaking (Rust, while alpha): `laminapdf::Error` no longer exposes the errors of the crates below it. The `Cos`, `Ops`, `Save`, `Text` and `Build` variants are one opaque `Error::Core`, and `CosError`, `OpsError`, `SaveError` and `SinkError` are no longer re-exported (`BuildError` and `TextError` stay: the builder's and `Font`'s own methods return them). Match on `error_code()` instead; a `data-pending` error's ranges come from the new `Error::pending_ranges()`, which replaces `laminapdf_source::pending_ranges`. The JavaScript API and every error's code, message and JSON are unchanged.
+- Breaking (Rust, while alpha): every public type now has a name of its own, and each item one public path.
+  
+- An extracted run is `PageTextRun` (`laminapdf::extract::PageTextRun`, `laminapdf_text::PageTextRun`), the name `@laminapdf/sdk` already gives it. `TextRun` now means only drawn text.
+- `laminapdf-build`'s font handle is `FontHandle`, the name the façade already gave it, so the builder's signatures read `&FontHandle` beside `laminapdf::Font`.
+- `laminapdf-text`'s OpenType tag is `OpenTypeTag`, and the façade exports it for `Font::instance(&[(OpenTypeTag::WEIGHT, 700.0)])`.
+- `laminapdf-text`'s `extract` and `agl` modules are private. Their items are at the crate root (`laminapdf_text::TextExtractor`, `PageText` and the rest), and `agl::to_unicode` is now `glyph_name_to_unicode`, beside `zapf_dingbats_to_unicode`. `CMap` and `MAX_USECMAP_DEPTH` are now private to the crate.
+- `laminapdf::Document::ops` and `into_ops` are hidden from the docs. They stay for Lamina PDF's own crates, and may change without notice.
+  
+In JavaScript, the extracted run's class is itself named `PageTextRun` now, so `run.constructor.name` reads `PageTextRun`. The rest of the JavaScript API and every output are unchanged.
+- New: the `laminapdf` command-line tool (`crates/laminapdf-cli`, not published to crates.io yet), with `info`, `check`, `pages rotate`, `extract` and `explain`, versioned JSON reports with JSON Schemas, and exit codes 0–5 (ADR 0031). Its own error codes (`invalid-command-line`, `invalid-page-range`, `binary-output-to-terminal`, `unknown-code`, `overwrite-refused`, `input-unreadable`, `output-unwritable`) join every code table, so the TypeScript `ErrorCode` union lists them too. The Rust façade gains `Document::version`, `is_encrypted`, `is_tagged` and `read_every_object`, and `laminapdf::did_you_mean`.
+- Two new warning codes, `extract-limit-blocks` and `extract-reading-order-ambiguous`, join the generated `WarningCode` union. In Rust, `Budget`, `Step` and `Phase` now come from `laminapdf-syntax` (the façade re-exports them at the same paths), `laminapdf_model::Document::is_tagged` and `RectPt::union` are new, and `laminapdf_text::is_right_to_left` is public. A new crate, `laminapdf-extract`, extracts blocks in reading order (ADR 0030); it is published with L3b.
+- New: `laminapdf mcp`, an MCP server on standard input and output that serves the CLI's commands as tools, in builds with the `laminapdf-cli` crate's `mcp` feature (ADR 0031 §9). It touches only files under its `--root` folders, is read-only unless started with `--allow-write`, and keeps document text out of everything but report fields. A path outside the roots is the new error code `path-outside-roots`, so the TypeScript `ErrorCode` union lists it too. The Rust façade exposes the error schema as `laminapdf::ERROR_SCHEMA`.
+- Breaking (Rust, while alpha): `Matrix`, `FillRule` and `Dash` are now defined once, in `laminapdf-model`. `laminapdf`, `laminapdf-build` and `laminapdf-content` re-export them under their old paths. Their API changes as follows:
+  
+- `Matrix::translate` takes two `f64`s instead of two `Pt`s.
+- `Dash` lengths are `f64`s in the drawing's own units, so the builder takes points: `Dash::new(vec![18.0, 6.0], 0.0)`.
+- The content reader's `Matrix::new` takes an array, `multiply` is `then` (the receiver applies first, with `after` for the other order), and `transform_point` is `apply`.
+- `PageFrame::to_user_space_matrix` and `TilePlan::page_to_tile` return a `Matrix` instead of a `[f64; 6]`. Read its fields, or call `to_array()` for the six numbers. `laminapdf-render` re-exports `Matrix`.
+- `Dash` is `#[non_exhaustive]`: build one with `Dash::new`. The content reader's `Matrix::from_object` is removed.
+- The content reader's current colour, `laminapdf_content::Color`, is now `CurrentColor`, so `Color` means only the builder's colour.
+  
+The JavaScript API and every output are unchanged.
+
+### Patch Changes
+
+- `didYouMean` now suggests the same names as errors from the WASM module. Names equally close to a mistyped one come in name order, and a typo with characters outside ASCII counts one edit per character.
+- Text extraction now avoids a quadratic scan for right-to-left runs whose glyphs have zero advance, preventing long stalls on PDFs with missing font widths. The extracted text stays the same.
+- The `@laminapdf/sdk/worker` worker now frees the document of an `open()` or `openUrl()` you abort just as it finishes. Before, the call rejected with `cancelled`, but the document stayed in the worker's memory until the worker stopped. An `open()` aborted while it ran always leaked its document, since the worker reads the cancel only after the synchronous open has answered.
+
+## 0.2.0-alpha.2
+
+### Minor Changes
+
+- `Document::save` no longer takes a `CancelToken`. To stop a save from another thread, call `save_with(&options, &cancel)` instead. In TypeScript, `save()`, `saveWithReport()` and `SaveJob.step()` now return `Uint8Array<ArrayBuffer>`, which `Response` and `Blob` accept without a cast. Smaller additions: `RectPt::from_points(x, y, width, height)`, `SetInfo::patch(patch)` for an edit that records no `/ModDate`, and `new()` on `BuildOptions`, `OpenOptions`, `PngOptions`, `RetryOptions` and `TextBoxOptions`. You can now ignore the run that `Surface::text` returns: the text is drawn either way.
+- The WASM module's `beginTag` and `beginArtifact` now take a structure type, table scope and artifact kind by name instead of by index, which breaks code that calls the module directly; `@laminapdf/sdk` already calls them that way. `@laminapdf/sdk` also exports the `LineCap`, `LineJoin` and `TableScope` types that `StrokeStyle` and `TagSpec` use, and `laminapdf-build`'s `FillRule`, `LineCap`, `LineJoin`, `BlendMode`, `ArtifactKind` and `TableScope` gain an `ALL` list of their variants.
+
+### Patch Changes
+
+- Text copied from a standard 14 font no longer loses half of its last character when that text runs past 256 UTF-16 units and ends with a character outside the BMP, such as an emoji. Symbol and ZapfDingbats now write a `/CapHeight`, as every other font does, and `laminapdf-syntax` adds `Object::number` and `Object::rounded`.
+
+## 0.2.0-alpha.1
+
+### Minor Changes
+
+- The library is called Lamina PDF, and its public names follow. `@laminapdf/sdk`'s error class is `LaminaPdfError`, checked with `isLaminaPdfError`, and its warnings are `LaminaPdfWarning`. The error object's JSON Schema is `laminapdf.error/1`. `@laminapdf/wasm`'s modules are `lamina_pdf_base`, `lamina_pdf_text`, `lamina_pdf_extract` and `lamina_pdf_render_hayro` (`.js`, `.d.ts` and `.wasm`).
+- `@laminapdf/viewer` exports only its documented API: `ViewerClient`, `createViewer` and `Viewer`, the types of their options, events and state, the protocol types `client.call` takes, and `MIN_ZOOM`/`MAX_ZOOM`. Its internal helpers (layout, canvas pool, bitmap cache, tiles, zoom maths), its byte-source functions and its protocol constants are no longer exported. Its worker no longer keeps a log of every render, which grew without bound, and no longer serves test-only methods. `@laminapdf/sdk/worker/server`'s `serve()` takes a `saveBudget` (work units per save step), and `workerStats()` reports the handles and calls a worker holds. `@laminapdf/sdk/worker` exports the `Emitter` its client uses.
+- A render `data-pending` thrown inside `@laminapdf/sdk`'s worker now reaches the page with its byte ranges: `LaminaPdfError.ranges` lists them. Before, they arrived empty. `RenderError` has a new `toDiagnostic()`, which returns the plain error object every Lamina PDF surface uses, and the worker posts that object for any error that has the method. `RenderError`'s `toJSON()`, `reviveRenderError` and `SerializedRenderError` are gone, and `ByteRange` and `RenderErrorKind` name its types. The viewer's worker now throws `RenderError`s for `cancelled` and `disposed` instead of plain objects, so they reach the page with a `docsUrl`.
+- `@laminapdf/render` has one `WasmSource` type for where an engine's `.wasm` comes from (a URL, a `Response` or a promise of one, the bytes or a compiled module). `CloneableWasmSource` is the subset a Web Worker can be sent. `initPdfium` and `initHayro` both take it: `@laminapdf/render-pdfium`'s own `PdfiumWasm` type is gone, and `initHayro` no longer takes a `Request`, a promise of anything but a `Response`, or a view of a `SharedArrayBuffer`. `RenderBackend` declares `memory()`, which both backends already had; a backend written outside this repository has to add it. The adapters share the page-index check, the read handling and the pending-range merging, so hayro now reports adjacent missing reads as one range, as PDFium did.
+- The `rotatePage` op now reads a `/Rotate` stored as an integral real, such as `90.0`, as the rotation the page displays; before, it read 0. `PageBuilder.rotate` now refuses angles other than 0, 90, 180 and 270, as its type says. In the Rust crates, `Rotation` from `laminapdf-syntax` replaces `laminapdf-render`'s `ViewRotation` and the degrees in `RenderPage::rotate`, and `laminapdf_cos::Page` drops `media_box`, `crop_box` and `rotate`: read them, and their strict-mode errors, from `laminapdf-model`'s page view.
+
+## 0.2.0-alpha.0
+
+### Minor Changes
+
+- Accessible and archival PDFs. A `profiles` option on the builder (`PDF/UA-1`, `PDF/A-2b`, `PDF/A-2u`, `PDF/A-3b`; `BuildOptions::with_profile` in Rust) checks each machine-checkable rule the document breaks when it finishes, with a coded error per rule: `missing-title`, `missing-lang`, `untagged-content`, `missing-alt-text`, `heading-level-skipped`, `unnumbered-heading-misused`, `invalid-structure-nesting`, `link-without-structure`, `link-without-contents`, `font-not-embedded`, `glyph-without-unicode`, `device-color-without-output-intent`, `embedded-file-forbidden`, `embedded-file-without-mime-type` and `profile-version-conflict`. The builder writes the XMP identification, `/DisplayDocTitle` for PDF/UA-1 and, for PDF/A, an sRGB output intent with a 480-byte embedded ICC profile. `attach(name, bytes, mime, { relationship })` adds associated files for PDF/A-3b, such as an e-invoice's XML. Every example that claims a profile is validated by veraPDF each night.
+- `@laminapdf/sdk/worker` can be extended: `@laminapdf/sdk/worker/server`'s `serve({ methods })` adds methods to the same worker, called with `client.request(method, params, { priority, key })`. The worker runs higher priorities first and coalesces calls with the same key. `emit()` sends events to `client.on("event")`, and `connect({ onDiscard })` sees late answers (by default it closes their ImageBitmaps). The worker protocol is now version 2.
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- First alpha, `0.1.0-alpha.0`, versioned and tagged but not published (ADR 0017). The `lamina` façade and its core crates at the same version: open, read, edit and save PDFs (incremental and full rewrites, the save planner, undo/redo), generate them (pages, vectors, colour, images, standard 14 and embedded fonts with shaping, bidi and line breaking, links, outlines, metadata, tagged PDF), and extract page text; `@laminapdf/sdk` over the base, text and extract WebAssembly modules in browsers, Node, Deno, Bun and Cloudflare Workers.

package/docs/pages/reference/codes.md

@@ -0,0 +1,14 @@
+---
+title: "Error and warning codes"
+description: "Every code Lamina PDF raises, generated from fixtures/codes.json when the site is built."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/"
+---
+
+# Error and warning codes
+
+Every code Lamina PDF raises, generated from fixtures/codes.json when the site is built.
+
+Every error and warning Lamina PDF raises, in Rust, in WebAssembly and in `@laminapdf/sdk`, has one of these codes. The tables below are read from `fixtures/codes.json` when this site is built: the same file `cargo xtask gen codes` generates the Rust enums and the TypeScript unions from. Each code links to its page on this site, which explains when it happens, why, how to fix it and what its `data` holds. See [Errors and warnings](../../pages/concepts/errors-and-warnings.md) for how to handle them.
+
+See the [error and warning codes](../../errors/README.md).