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

package/docs/pages/recipes/open-untrusted.md

@@ -0,0 +1,65 @@
+---
+title: "Open someone else's file"
+description: "Open an uploaded PDF with an optional password and tighter limits, and get its page count and warnings, or the error, back as a value."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/open-untrusted/"
+---
+
+# Open someone else's file
+
+Open an uploaded PDF with an optional password and tighter limits, and get its page count and warnings, or the error, back as a value.
+
+You'll open a PDF from someone else, with a password if it needs one and tighter limits than the defaults, and get the outcome as a value. You need this wherever you accept uploads: a stranger's file can be damaged, locked or built to use up memory.
+
+The function opens the bytes under its limits and returns the page count and warning codes, or the error's code and hint:
+
+`packages/sdk/examples/open-untrusted.ts`:
+
+```ts
+// Open bytes from someone else: an optional password, tighter limits than the defaults, and the
+// outcome as a value rather than an exception. The example writes nothing: it returns what it found.
+import { Document, isLaminaPdfError } from "@laminapdf/sdk";
+
+const MiB = 1024 * 1024;
+/** Limits for an upload endpoint: each decoded stream, and all of them together. */
+const LIMITS = { maxStreamDecoded: 16 * MiB, maxDecodedTotal: 64 * MiB } as const;
+
+/** What opening a file gave: its page count and warning codes, or why it didn't open. */
+export type Opened =
+  | { readonly ok: true; readonly pages: number; readonly warnings: readonly string[] }
+  | { readonly ok: false; readonly code: string; readonly hint: string | undefined };
+
+/** Opens `bytes`, with `password` if the file needs one, under {@link LIMITS}. Needs `init()`. */
+export function openUntrusted(bytes: Uint8Array, password?: string): Opened {
+  try {
+    using doc = Document.open(bytes, { ...(password === undefined ? {} : { password }), limits: LIMITS });
+    // Repairs and dropped values are warnings: the file opened, but not exactly as written.
+    return { ok: true, pages: doc.pageCount, warnings: doc.warnings.map((w) => w.code) };
+  } catch (e) {
+    // `password-required`, `wrong-password`, `not-pdf`, `limit-exceeded`, …: a coded error whose
+    // message and hint never contain text from the file. Anything else is a bug: let it throw.
+    if (isLaminaPdfError(e)) return { ok: false, code: e.code, hint: e.hint };
+    throw e;
+  }
+}
+```
+
+It writes no PDF. The value it returns is the result: `{ ok: true, pages, warnings }` for a file that opened, or `{ ok: false, code, hint }`, such as `password-required` for a locked file opened without its password.
+
+## How it works
+
+- It needs only `init()`: opening a file uses the base module, without fonts or text.
+- `Document.open` gets the password only when you pass one, and tries it against both of the file's passwords. See [Open password-protected files](../../pages/guides/password-protected-files.md).
+- `LIMITS` allows 16 MiB decoded from one stream and 64 MiB in all, against defaults of 64 MiB and 1 GiB. A file that needs more fails with `limit-exceeded`, and every other limit keeps its default.
+- A file can open and still carry warnings: each one names a repair or a dropped value, and the function returns their codes.
+- `isLaminaPdfError(e)` picks out Lamina PDF's coded errors, whose message and hint never contain text from the file. Any other error is a bug, so the function throws it again.
+- `using` frees the document as soon as the function returns, so the WebAssembly side keeps no copy of the file.
+
+## What to change
+
+- **Ask for the password again:** on `password-required` or `wrong-password`, ask your user and call `openUntrusted` again with their answer.
+- **Name the limit:** on `limit-exceeded`, return `e.data?.limit` too. It names the limit the file went over as Rust spells it, such as `max_stream_decoded` for `maxStreamDecoded`.
+- **Other limits:** add any limit from the table in [Open files you don't trust](../../pages/guides/untrusted-files.md#hard-and-soft-limits), such as a lower `maxNestingDepth`.
+- **Refuse damaged files:** add `strict: true` to the options, and a file that needs repair fails with `strict` instead of opening with warnings.
+
+Next: [save in a Web Worker](../../pages/recipes/web-worker-client.md), so a large file never freezes the page.

package/docs/pages/recipes/pdf-a-archive.md

@@ -0,0 +1,205 @@
+---
+title: "A PDF/A archive"
+description: "An order confirmation for long-term archiving, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1, with an embedded font and a photo."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/pdf-a-archive/"
+---
+
+# A PDF/A archive
+
+An order confirmation for long-term archiving, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1, with an embedded font and a photo.
+
+You'll write a letter confirming an order as a PDF/A file, which looks the same in any viewer for decades. You need it for documents kept for years, often by law: contracts, records, letters to customers. The recipe writes the letter twice, at two PDF/A levels.
+
+The function takes the level, `2b` or `2u`, and builds the same letter under that level's profiles. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+<TabItem label="TypeScript">`packages/sdk/examples/pdf-a-archive.ts`:
+
+```ts
+// An archival letter, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1.
+import { Builder, Font, Image, PAGE_SIZES, type Profile, type Surface } from "@laminapdf/sdk";
+
+const MARGIN = 56;
+const BAND_HEIGHT = 70;
+const TITLE_BASELINE = 110;
+/** The top of the letter's text and of the photo beside it, and the height of both. */
+const BLOCK_TOP = 130;
+const BLOCK_HEIGHT = 120;
+const LETTER_WIDTH = 300;
+const PHOTO_LEFT = 380;
+const PHOTO_WIDTH = 160;
+const FOOTER_BASELINE = 300;
+const TITLE = 22;
+const BODY = 11;
+const BAND_OPACITY = 0.35;
+const PHOTO_ALT = "A photograph of the sprockets, packed in a box";
+const LETTER =
+  "Thank you for your order of 12 sprockets. This letter confirms the delivery date and the price we agreed. " +
+  "Keep it: PDF/A files look the same in any viewer, now and in the future.";
+
+/** PDF/A-2b, or PDF/A-2u (whose text maps to Unicode) with PDF/UA-1. */
+const PROFILES: Record<"2b" | "2u", Profile[]> = {
+  "2b": ["PDF/A-2b"],
+  "2u": ["PDF/A-2u", "PDF/UA-1"],
+};
+
+/**
+ * The letter's bytes. Needs `init({ text: true })`.
+ *
+ * @param level - `2b` or `2u`.
+ * @param notoSans - the bytes of the Noto Sans font file.
+ * @param photo - the bytes of a JPEG photo.
+ */
+export function pdfAArchive(level: "2b" | "2u", notoSans: Uint8Array, photo: Uint8Array): Uint8Array<ArrayBuffer> {
+  using b = new Builder({ profiles: PROFILES[level], tagged: true });
+  b.metadata({ title: "Order confirmation 42", author: "Acme Widgets Ltd" });
+  b.lang("en-GB");
+  const font = Font.fromBytes(notoSans);
+  b.font(font);
+  const page = b.page("A4");
+  draw(page.surface(), font, Image.jpeg(photo));
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+
+function draw(s: Surface, font: Font, photo: Image): void {
+  // A translucent band across the top: decoration, and transparency, which PDF/A-2 allows.
+  const [width] = PAGE_SIZES.A4;
+  s.artifact("layout", (s) => {
+    s.save().opacity(BAND_OPACITY, 1).fillColor([0.12, 0.47, 0.78]);
+    s.path((p) => p.rect([0, 0, width, BAND_HEIGHT])).fill();
+    s.restore();
+  });
+  s.tag("H1", (s) => s.text("Order confirmation 42", { font, size: TITLE, at: [MARGIN, TITLE_BASELINE] }));
+  s.tag("P", (s) => s.textBox(LETTER, { font, size: BODY, box: [MARGIN, BLOCK_TOP, LETTER_WIDTH, BLOCK_HEIGHT] }));
+  s.image(photo, [PHOTO_LEFT, BLOCK_TOP, PHOTO_WIDTH, BLOCK_HEIGHT], PHOTO_ALT);
+  s.tag("P", (s) =>
+    s.text("Acme Widgets Ltd, 1 Example Street, London", { font, size: BODY, at: [MARGIN, FOOTER_BASELINE] }),
+  );
+}
+```</TabItem>
+<TabItem label="Rust">`crates/laminapdf/examples/pdf_a_archive.rs`:
+
+```rust
+//! An archival letter, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1.
+//!
+//! Run it with `cargo run -p laminapdf --example pdf_a_archive -- <font.ttf> <photo.jpg> [out-dir]`: it writes
+//! `pdf_a_archive-2b.pdf` and `pdf_a_archive-2u.pdf`.
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    ArtifactKind, BuildError, BuildOptions, Builder, Color, FillRule, FontHandle, Image, Metadata, PageSize, PointPt,
+    Profile, Pt, RectPt, SaveOptions, Surface, TagKind, TextBoxOptions,
+};
+
+const MARGIN: f64 = 56.0;
+const BAND_HEIGHT: f64 = 70.0;
+const TITLE_AT: PointPt = PointPt::from_points(MARGIN, 110.0);
+/// The top of the letter's text and of the photo beside it, and the height of both.
+const BLOCK_TOP: f64 = 130.0;
+const BLOCK_HEIGHT: f64 = 120.0;
+const LETTER_WIDTH: f64 = 300.0;
+const PHOTO_LEFT: f64 = 380.0;
+const PHOTO_WIDTH: f64 = 160.0;
+const FOOTER_AT: PointPt = PointPt::from_points(MARGIN, 300.0);
+const TITLE: Pt = Pt::new(22.0);
+const BODY: Pt = Pt::new(11.0);
+const BAND_OPACITY: f64 = 0.35;
+const PHOTO_ALT: &str = "A photograph of the sprockets, packed in a box";
+const LETTER: &str = "Thank you for your order of 12 sprockets. This letter confirms the delivery date and the \
+                      price we agreed. Keep it: PDF/A files look the same in any viewer, now and in the future.";
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args = std::env::args().skip(1);
+    let usage = "arguments: <font.ttf> <photo.jpg> [out-dir]";
+    let font = std::fs::read(args.next().ok_or(usage)?)?;
+    let photo = std::fs::read(args.next().ok_or(usage)?)?;
+    let out = PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    let a2b = build(Level::A2b, font.clone(), photo.clone())?;
+    std::fs::write(out.join("pdf_a_archive-2b.pdf"), a2b)?;
+    let a2u = build(Level::A2u, font, photo)?;
+    Ok(std::fs::write(out.join("pdf_a_archive-2u.pdf"), a2u)?)
+}
+
+/// Which archive to write.
+#[derive(Debug, Clone, Copy)]
+pub(crate) enum Level {
+    /// PDF/A-2b: the letter looks the same everywhere.
+    A2b,
+    /// PDF/A-2u, whose text maps to Unicode, and PDF/UA-1.
+    A2u,
+}
+
+/// The letter's bytes, in `font` (a TrueType or OpenType file) with `photo` (a JPEG).
+pub(crate) fn build(level: Level, font: Vec<u8>, photo: Vec<u8>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let options = match level {
+        Level::A2b => BuildOptions::new().with_profile(Profile::PdfA2b),
+        Level::A2u => BuildOptions::new()
+            .with_profile(Profile::PdfA2u)
+            .with_profile(Profile::PdfUa1),
+    };
+    let mut b = Builder::new(options.with_tagged(true));
+    b.metadata(
+        Metadata::default()
+            .with_title("Order confirmation 42")
+            .with_author("Acme Widgets Ltd"),
+    );
+    b.lang("en-GB");
+    let font = b.font_bytes(font)?;
+    let photo = Image::jpeg(photo)?;
+    let mut page = b.page(PageSize::A4);
+    draw(page.surface(), &font, &photo)?;
+    page.finish()?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+
+fn draw(s: &mut Surface, font: &FontHandle, photo: &Image) -> Result<(), BuildError> {
+    // A translucent band across the top: decoration, and transparency, which PDF/A-2 allows.
+    let width = PageSize::A4.width.get();
+    s.artifact(ArtifactKind::Layout, |s| {
+        s.save()
+            .opacity(BAND_OPACITY, 1.0)
+            .fill_color(Color::rgb(0.12, 0.47, 0.78));
+        s.path(|p| _ = p.rect(RectPt::from_points(0.0, 0.0, width, BAND_HEIGHT)))
+            .fill(FillRule::NonZero);
+        s.restore();
+        Ok(())
+    })?;
+    s.tag(TagKind::H1, |s| {
+        s.text("Order confirmation 42", font, TITLE, TITLE_AT).map(drop)
+    })?;
+    let body = RectPt::from_points(MARGIN, BLOCK_TOP, LETTER_WIDTH, BLOCK_HEIGHT);
+    s.tag(TagKind::P, |s| {
+        s.text_box(LETTER, font, BODY, body, &TextBoxOptions::new()).map(drop)
+    })?;
+    let beside = RectPt::from_points(PHOTO_LEFT, BLOCK_TOP, PHOTO_WIDTH, BLOCK_HEIGHT);
+    s.figure(photo, beside, Some(PHOTO_ALT));
+    let footer = "Acme Widgets Ltd, 1 Example Street, London";
+    s.tag(TagKind::P, |s| s.text(footer, font, BODY, FOOTER_AT).map(drop))
+}
+```</TabItem>
+
+The result is one A4 letter under a translucent blue band, with a photo beside its text: open the [PDF/A-2b](https://docs.laminapdf.com/examples/pdf/pdf_a_archive-2b.pdf) or the [PDF/A-2u](https://docs.laminapdf.com/examples/pdf/pdf_a_archive-2u.pdf) reference PDF.
+
+## How it works
+
+- PDF/A-2b makes the letter look the same everywhere. PDF/A-2u also maps every glyph to Unicode, so the text can be searched and copied. That copy is PDF/UA-1 too, so a screen reader can follow it.
+- PDF/A needs every font embedded, so the letter uses Noto Sans rather than one of the [standard 14 fonts](../../pages/reference/glossary.md#standard-14-fonts). `finish()` checks rules like this one and fails with a coded error for the first one the letter breaks.
+- The builder writes what PDF/A asks for: the PDF/A identification in the file's XMP metadata, and an sRGB output intent that says what its RGB colours mean. See [What PDF/A asks for](../../pages/guides/archival-pdfs.md#what-pdfa-asks-for).
+- Both copies draw the same tagged content: an `H1` title, `P` paragraphs and the photo as a figure with alternate text. PDF/A-2b doesn't ask for tags, but PDF/UA-1 does.
+- The blue band is drawn at 35% opacity, as a layout artifact that screen readers skip. PDF/A-2 allows transparency.
+- `textBox` breaks the letter into lines inside its box, beside the photo. The JPEG goes into the file as it is.
+
+## What to change
+
+- **The letter:** change `LETTER`. `textBox` leaves out lines that don't fit, so make `BLOCK_HEIGHT` larger for a longer letter, or pass `overflow: "error"` to fail with `text-overflow` instead.
+- **The photo:** pass any RGB or gray JPEG, or `Image.png(bytes)` for a PNG (`Image::png` in Rust). A CMYK JPEG fails `finish()` with `device-color-without-output-intent`, because the output intent is sRGB.
+- **Other profiles:** pass the ones you need, such as `["PDF/A-2u"]` alone or `["PDF/A-2b", "PDF/UA-1"]`. A document can claim PDF/UA-1 and at most one PDF/A profile.
+- **An attached file:** PDF/A-2 refuses attachments, so switch to PDF/A-3b, as the [PDF/A-3 invoice](../../pages/recipes/pdf-a3-invoice-with-xml.md) does.
+
+Next: [a PDF/A-3 invoice with XML](../../pages/recipes/pdf-a3-invoice-with-xml.md), with its data attached for software to read.

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

@@ -0,0 +1,222 @@
+---
+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.3"
+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:
+
+<TabItem label="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" },
+  });
+}
+```</TabItem>
+<TabItem label="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(())
+}
+```</TabItem>
+
+The result is one A4 page with three line items and a total of € 99.40, carrying `invoice-42.xml`: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/pdf_a3_invoice_with_xml.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.