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

package/docs/pages/recipes/pdf-a3-invoice-with-xml.md

@@ -0,0 +1,229 @@
+---
+title: "A PDF/A-3 invoice with XML"
+description: "A PDF/A-3b invoice that carries the same invoice as an attached XML file, for people to read and for software to process."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/pdf-a3-invoice-with-xml/"
+---
+
+# A PDF/A-3 invoice with XML
+
+A PDF/A-3b invoice that carries the same invoice as an attached XML file, for people to read and for software to process.
+
+You'll write a one-page invoice as PDF/A-3b, with the same invoice attached as XML. You need this for e-invoices such as Factur-X and ZUGFeRD, where a person reads the PDF and the buyer's software reads the XML.
+
+The function draws the invoice, writes the same items as XML and attaches that file before it finishes. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+**TypeScript**
+
+`packages/sdk/examples/pdf-a3-invoice-with-xml.ts`:
+
+```ts
+// A PDF/A-3b invoice that carries the same invoice as XML, attached for software to read.
+import { Builder, Font, PAGE_SIZES, type Surface } from "@laminapdf/sdk";
+
+const MARGIN = 56;
+/** The page's right edge, less the margin: where the rule under the items ends. */
+const RIGHT = PAGE_SIZES.A4[0] - MARGIN;
+const AMOUNTS = 460;
+const ROW = 22;
+const TITLE_BASELINE = 80;
+const FIRST_ROW = 130;
+/**
+ * How far above the next row's baseline the rule sits, and how far below it the total and
+ * the note are.
+ */
+const RULE_RISE = 7;
+const TOTAL_DROP = 18;
+const NOTE_DROP = 68;
+/** How far left of the amounts column the total starts, to fit its "Total" label. */
+const TOTAL_INDENT = 40;
+const TITLE = 24;
+const TOTAL = 14;
+const BODY = 11;
+const ITEMS = [
+  ["Sprockets", 12, 1.25],
+  ["Gadget", 1, 79.9],
+  ["Delivery", 1, 4.5],
+] as const;
+
+/** The invoice's total. */
+function total(): number {
+  return ITEMS.reduce((sum, [, qty, price]) => sum + qty * price, 0);
+}
+
+/** The invoice as XML, in a made-up schema (a real e-invoice follows EN 16931, as Factur-X does). */
+function invoiceXml(): string {
+  const lines = ITEMS.map(
+    ([item, qty, price]) => `  <line item="${item}" quantity="${qty}" price="${price.toFixed(2)}"/>\n`,
+  );
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<invoice number="42" currency="EUR">\n${lines.join("")}  <total>${total().toFixed(2)}</total>\n</invoice>\n`;
+}
+
+/**
+ * The invoice's bytes. Needs `init({ text: true })`.
+ *
+ * @param notoSans - the bytes of the Noto Sans font file.
+ */
+export function pdfA3InvoiceWithXml(notoSans: Uint8Array): Uint8Array<ArrayBuffer> {
+  using b = new Builder({ profiles: ["PDF/A-3b"] });
+  b.metadata({ title: "Invoice 42", author: "Acme Widgets Ltd" });
+  const font = Font.fromBytes(notoSans);
+  b.font(font);
+  const page = b.page("A4");
+  draw(page.surface(), font);
+  page.finish();
+  b.attach("invoice-42.xml", new TextEncoder().encode(invoiceXml()), "text/xml", {
+    relationship: "alternative",
+    description: "Invoice 42 as XML",
+  });
+  using doc = b.finish();
+  return doc.save();
+}
+
+function draw(s: Surface, font: Font): void {
+  s.text("Invoice 42", { font, size: TITLE, at: [MARGIN, TITLE_BASELINE] });
+  let y = FIRST_ROW;
+  for (const [item, qty, price] of ITEMS) {
+    s.text(`${qty} × ${item}`, { font, size: BODY, at: [MARGIN, y] });
+    s.text(`€ ${(qty * price).toFixed(2)}`, { font, size: BODY, at: [AMOUNTS, y] });
+    y += ROW;
+  }
+  const rule = y - RULE_RISE;
+  s.strokeColor([0.5])
+    .path((p) => p.moveTo(MARGIN, rule).lineTo(RIGHT, rule))
+    .stroke();
+  s.text(`Total € ${total().toFixed(2)}`, { font, size: TOTAL, at: [AMOUNTS - TOTAL_INDENT, y + TOTAL_DROP] });
+  s.text("The invoice is attached as invoice-42.xml.", {
+    font,
+    size: BODY,
+    at: [MARGIN, y + NOTE_DROP],
+    link: { target: { type: "uri", uri: "https://example.com/invoices/42" }, contents: "Invoice 42 online" },
+  });
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/pdf_a3_invoice_with_xml.rs`:
+
+```rust
+//! A PDF/A-3b invoice that carries the same invoice as XML, attached for software to read.
+//!
+//! Run it with `cargo run -p laminapdf --example pdf_a3_invoice_with_xml -- <font.ttf> [out-dir]`.
+
+use std::error::Error;
+use std::fmt::Write as _;
+use std::path::PathBuf;
+
+use laminapdf::{
+    AfRelationship, Attachment, BuildError, BuildOptions, Builder, Color, FontHandle, LinkTarget, Metadata, PageSize,
+    PointPt, Profile, Pt, SaveOptions, StrokeStyle, Surface,
+};
+
+const MARGIN: f64 = 56.0;
+/// The page's right edge, less the margin: where the rule under the items ends.
+const RIGHT: f64 = PageSize::A4.width.get() - MARGIN;
+const AMOUNTS: f64 = 460.0;
+const ROW: f64 = 22.0;
+const TITLE_BASELINE: f64 = 80.0;
+const FIRST_ROW: f64 = 130.0;
+/// How far above the next row's baseline the rule sits, and how far below it the total and
+/// the note are.
+const RULE_RISE: f64 = 7.0;
+const TOTAL_DROP: f64 = 18.0;
+const NOTE_DROP: f64 = 68.0;
+/// How far left of the amounts column the total starts, to fit its "Total" label.
+const TOTAL_INDENT: f64 = 40.0;
+const TITLE: Pt = Pt::new(24.0);
+const TOTAL: Pt = Pt::new(14.0);
+const BODY: Pt = Pt::new(11.0);
+const ITEMS: [(&str, u32, f64); 3] = [("Sprockets", 12, 1.25), ("Gadget", 1, 79.90), ("Delivery", 1, 4.50)];
+
+fn main() -> Result<(), Box<dyn 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 = PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    Ok(std::fs::write(out.join("pdf_a3_invoice_with_xml.pdf"), build(font)?)?)
+}
+
+/// The invoice's total.
+fn total() -> f64 {
+    ITEMS.iter().map(|(_, qty, price)| f64::from(*qty) * price).sum()
+}
+
+/// The invoice as XML, in a made-up schema (a real e-invoice follows EN 16931, as Factur-X does).
+fn invoice_xml() -> Result<String, std::fmt::Error> {
+    let mut xml =
+        String::from("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<invoice number=\"42\" currency=\"EUR\">\n");
+    for (item, qty, price) in ITEMS {
+        writeln!(xml, "  <line item=\"{item}\" quantity=\"{qty}\" price=\"{price:.2}\"/>")?;
+    }
+    writeln!(xml, "  <total>{:.2}</total>\n</invoice>", total())?;
+    Ok(xml)
+}
+
+/// The invoice's bytes, in `font` (a TrueType or OpenType file).
+pub(crate) fn build(font: Vec<u8>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(BuildOptions::new().with_profile(Profile::PdfA3b));
+    b.metadata(
+        Metadata::default()
+            .with_title("Invoice 42")
+            .with_author("Acme Widgets Ltd"),
+    );
+    let font = b.font_bytes(font)?;
+    let mut page = b.page(PageSize::A4);
+    draw(page.surface(), &font)?;
+    page.finish()?;
+    let xml = Attachment::new("invoice-42.xml", invoice_xml()?.into_bytes(), "text/xml")
+        .with_relationship(AfRelationship::Alternative)
+        .with_description("Invoice 42 as XML");
+    b.attach(xml);
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+
+fn draw(s: &mut Surface, font: &FontHandle) -> Result<(), BuildError> {
+    let at = PointPt::from_points;
+    s.text("Invoice 42", font, TITLE, at(MARGIN, TITLE_BASELINE))?;
+    let mut y = FIRST_ROW;
+    for (item, qty, price) in ITEMS {
+        s.text(&format!("{qty} × {item}"), font, BODY, at(MARGIN, y))?;
+        let amount = f64::from(qty) * price;
+        s.text(&format!("€ {amount:.2}"), font, BODY, at(AMOUNTS, y))?;
+        y += ROW;
+    }
+    let rule = y - RULE_RISE;
+    s.stroke_color(Color::gray(0.5))
+        .path(|p| _ = p.move_to(at(MARGIN, rule)).line_to(at(RIGHT, rule)))
+        .stroke(&StrokeStyle::default());
+    let total_at = at(AMOUNTS - TOTAL_INDENT, y + TOTAL_DROP);
+    s.text(&format!("Total € {:.2}", total()), font, TOTAL, total_at)?;
+    let note = "The invoice is attached as invoice-42.xml.";
+    let note = s.text(note, font, BODY, at(MARGIN, y + NOTE_DROP))?;
+    let online = LinkTarget::Uri("https://example.com/invoices/42".into());
+    note.link(online, Some("Invoice 42 online".into()));
+    Ok(())
+}
+```
+
+**Result:** [pdf_a3_invoice_with_xml.pdf](https://docs.laminapdf.com/examples/pdf/pdf_a3_invoice_with_xml.pdf)
+
+The result is one A4 page with three line items and a total of € 99.40, carrying `invoice-42.xml`. The Result tab shows it, with a link to the PDF. Viewers that show attachments list it there.
+
+## How it works
+
+- `profiles: ["PDF/A-3b"]` (`Profile::PdfA3b` in Rust) asks for PDF/A-2b's rules and allows attached files of any kind. `finish()` fails with a coded error for the first rule the invoice breaks; see [Archival PDFs](../../pages/guides/archival-pdfs.md).
+- PDF/A needs every font embedded, so the invoice uses Noto Sans rather than one of the [standard 14 fonts](../../pages/reference/glossary.md#standard-14-fonts).
+- `invoiceXml` writes the line items and the total from the same `ITEMS` the page draws, so the PDF and the XML always agree. Its schema is made up for the recipe.
+- `attach` adds the file with its name, its bytes and its MIME type, `text/xml`. PDF/A needs a MIME type on every attachment, or `finish()` fails with `embedded-file-without-mime-type`.
+- `relationship: "alternative"` (`AfRelationship::Alternative`) says the XML is another form of the same content, and the builder associates it with the document. `description` is the text a viewer shows beside the file.
+
+## What to change
+
+- **The items:** change `ITEMS`. The page, the total and the XML all follow.
+- **A real e-invoice:** replace `invoiceXml` with XML that follows EN 16931, the European e-invoicing standard, as Factur-X and ZUGFeRD do. Those formats also need XMP entries of their own, which the builder can't add yet.
+- **Other attachments:** attach the file the invoice was made from with `relationship: "source"`, or the data behind it with `"data"` (`AfRelationship::Source`, `AfRelationship::Data`). Each needs its own name and MIME type.
+- **Accessible too:** add `"PDF/UA-1"` to `profiles`, set `lang` and tag the content, as the [PDF/UA report](../../pages/recipes/pdf-ua-report.md) does.
+
+Next: [a 100-page report](../../pages/recipes/report.md), the case Lamina PDF times in every runtime.

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

@@ -0,0 +1,244 @@
+---
+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.4"
+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:
+
+**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();
+    });
+  });
+}
+```
+
+**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(())
+    })
+}
+```
+
+**Result:** [pdf_ua_report.pdf](https://docs.laminapdf.com/examples/pdf/pdf_ua_report.pdf)
+
+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. The Result tab shows it, with a link to the 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.4"
+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. [Benchmarks](../../pages/reference/benchmarks.md) has the timings.
+
+## 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.4"
+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.