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

package/docs/pages/recipes/invoice.md

@@ -0,0 +1,226 @@
+---
+title: "An invoice"
+description: "A tagged one-page invoice with an embedded font, a table of line items with right-aligned amounts and a total, in TypeScript and Rust."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/invoice/"
+---
+
+# An invoice
+
+A tagged one-page invoice with an embedded font, a table of line items with right-aligned amounts and a total, in TypeScript and Rust.
+
+You'll make a one-page invoice: a heading, an address, a table of line items with right-aligned amounts, and a total. It's tagged, so a screen reader reads it in order. Start from it for any document built around a table, such as a quote or a receipt.
+
+The function takes a font file, draws the invoice and returns the PDF's bytes. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+<TabItem label="TypeScript">`packages/sdk/examples/invoice.ts`:
+
+```ts
+// An invoice that screen readers can follow, with an embedded font and a table of line items.
+// The heading, the address, the table of items and the total are tagged, so a screen reader
+// reads them in order.
+import { Builder, type BuilderOptions, Font, PAGE_SIZES, type Rect, type Surface } from "@laminapdf/sdk";
+
+const ITEMS: readonly (readonly [item: string, qty: number, price: number])[] = [
+  ["Widgets, blue (W-100)", 3, 12.0],
+  ["Gadget with fine-tuned dials", 1, 79.9],
+  ["Café-grade sprockets", 12, 1.25],
+  ["Delivery", 1, 4.5],
+];
+const ADDRESS = "Acme Widgets Ltd · 1 Example Street · London";
+const PAGE = "A4";
+const [PAGE_WIDTH] = PAGE_SIZES[PAGE];
+const MARGIN = 56;
+const RIGHT_EDGE = PAGE_WIDTH - MARGIN;
+const TITLE_AT = [MARGIN, 80] as const;
+const ADDRESS_AT = [MARGIN, 100] as const;
+const TITLE = 24;
+const BODY = 11;
+const FIRST_ROW = 160;
+const ROW_HEIGHT = 24;
+/** The quantity's and the amount's columns, each a width ending this far left of the right edge. */
+const COLUMNS = [
+  [40, 169],
+  [100, 0],
+] as const;
+/** A cell's box starts this far above its row's baseline and is this tall. */
+const CELL_RISE = 12;
+const CELL_HEIGHT = 16;
+
+/**
+ * The document's bytes, in `fontBytes` (a TrueType or OpenType file). Needs `init({ text: true })`.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function invoice(fontBytes: Uint8Array, options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder({ ...options, tagged: true });
+  const font = Font.fromBytes(fontBytes);
+  const bold = Font.standard("Helvetica-Bold");
+  // Registered up front, in this order, so the embedded font is the document's first.
+  b.font(font);
+  b.font(bold);
+  const page = b.page(PAGE);
+  const s = page.surface();
+  s.text("Invoice 42", { font: bold, size: TITLE, at: TITLE_AT, tag: "H1" });
+  s.text(ADDRESS, { font, size: BODY, at: ADDRESS_AT, tag: "P" });
+  items(s, font);
+  const total = ITEMS.reduce((sum, [, qty, price]) => sum + qty * price, 0);
+  const box = cell(COLUMNS[1], rowBaseline(ITEMS.length));
+  s.textBox(`Total € ${total.toFixed(2)}`, { font, size: BODY, box, align: "end", tag: "P" });
+  page.finish();
+  b.metadata({ title: "Invoice 42", author: "Acme Widgets Ltd" }).lang("en-GB");
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** The table of line items: what, how many, and the amount, right-aligned. */
+function items(s: Surface, font: Font): void {
+  s.tag("Table", (s) => {
+    ITEMS.forEach(([item, qty, price], row) => {
+      const y = rowBaseline(row);
+      const cells = [
+        [String(qty), COLUMNS[0]],
+        [`€ ${(qty * price).toFixed(2)}`, COLUMNS[1]],
+      ] as const;
+      s.tag("TR", (s) => {
+        s.text(item, { font, size: BODY, at: [MARGIN, y], tag: "TD" });
+        for (const [text, column] of cells) {
+          s.textBox(text, { font, size: BODY, box: cell(column, y), align: "end", tag: "TD" });
+        }
+      });
+    });
+  });
+}
+
+/** The baseline of row `row` of the table. */
+function rowBaseline(row: number): number {
+  return FIRST_ROW + ROW_HEIGHT * row;
+}
+
+/** The box of a cell in `column` (width, distance from the right edge) on the row at `baseline`. */
+function cell([width, inset]: readonly [number, number], baseline: number): Rect {
+  return [RIGHT_EDGE - inset - width, baseline - CELL_RISE, width, CELL_HEIGHT];
+}
+```</TabItem>
+<TabItem label="Rust">`crates/laminapdf/examples/invoice.rs`:
+
+```rust
+//! An invoice that screen readers can follow, with an embedded font and a table of line items.
+//!
+//! The heading, the address, the table of items and the total are tagged, so a screen reader
+//! reads them in order. Run it with `cargo run -p laminapdf --example invoice -- <font.ttf> [out-dir]`.
+
+use laminapdf::{
+    Alignment, BuildError, BuildOptions, Builder, FontHandle, Metadata, PageSize, PointPt, Pt, RectPt, SaveOptions,
+    Standard14, Surface, TagKind, TextBoxOptions,
+};
+
+const ITEMS: [(&str, u32, f64); 4] = [
+    ("Widgets, blue (W-100)", 3, 12.00),
+    ("Gadget with fine-tuned dials", 1, 79.90),
+    ("Café-grade sprockets", 12, 1.25),
+    ("Delivery", 1, 4.50),
+];
+const ADDRESS: &str = "Acme Widgets Ltd · 1 Example Street · London";
+const PAGE: PageSize = PageSize::A4;
+const MARGIN: f64 = 56.0;
+const RIGHT_EDGE: f64 = PAGE.width.get() - MARGIN;
+const TITLE_AT: PointPt = PointPt::from_points(MARGIN, 80.0);
+const ADDRESS_AT: PointPt = PointPt::from_points(MARGIN, 100.0);
+const TITLE: Pt = Pt::new(24.0);
+const BODY: Pt = Pt::new(11.0);
+const FIRST_ROW: f64 = 160.0;
+const ROW_HEIGHT: f64 = 24.0;
+/// The quantity's and the amount's columns, each a width ending this far left of the right edge.
+const COLUMNS: [(f64, f64); 2] = [(40.0, 169.0), (100.0, 0.0)];
+/// A cell's box starts this far above its row's baseline and is this tall.
+const CELL_RISE: f64 = 12.0;
+const CELL_HEIGHT: f64 = 16.0;
+
+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("usage: invoice <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)?;
+    let pdf = build(BuildOptions::new(), font)?;
+    Ok(std::fs::write(out.join("invoice.pdf"), pdf)?)
+}
+
+/// The bytes, in `font` (TrueType or OpenType); `options` can fix the file ID, producer and date.
+pub(crate) fn build(options: BuildOptions, font: Vec<u8>) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
+    let mut b = Builder::new(options.with_tagged(true));
+    draw(&mut b, font)?;
+    Ok(b.finish()?.save(&SaveOptions::new())?.bytes)
+}
+
+/// Draws the invoice's one page into `b` and sets its title, author and language.
+pub(crate) fn draw(b: &mut Builder, font: Vec<u8>) -> Result<(), Box<dyn std::error::Error>> {
+    let (font, bold) = (b.font_bytes(font)?, b.standard_font(Standard14::HelveticaBold)?);
+    let mut page = b.page(PAGE);
+    let s = page.surface();
+    s.text("Invoice 42", &bold, TITLE, TITLE_AT)?.tag(TagKind::H1);
+    s.text(ADDRESS, &font, BODY, ADDRESS_AT)?.tag(TagKind::P);
+    items(s, &font)?;
+    let total: f64 = ITEMS.iter().map(|(_, qty, price)| f64::from(*qty) * price).sum();
+    let (total, below_items) = (format!("Total € {total:.2}"), u32::try_from(ITEMS.len())?);
+    let area = cell(COLUMNS[1], row_baseline(below_items));
+    s.tag(TagKind::P, |s| right_aligned(s, &font, &total, area))?;
+    page.finish()?;
+    let metadata = Metadata::default().with_title("Invoice 42");
+    b.metadata(metadata.with_author("Acme Widgets Ltd")).lang("en-GB");
+    Ok(())
+}
+
+/// The table of line items: what, how many, and the amount, right-aligned.
+fn items(s: &mut Surface, font: &FontHandle) -> Result<(), BuildError> {
+    s.tag(TagKind::Table, |s| {
+        for (row, (item, qty, price)) in (0_u32..).zip(ITEMS) {
+            let y = row_baseline(row);
+            s.tag(TagKind::TR, |s| {
+                s.text(item, font, BODY, PointPt::from_points(MARGIN, y))?
+                    .tag(TagKind::TD);
+                let amount = format!("€ {:.2}", f64::from(qty) * price);
+                for (text, column) in [qty.to_string(), amount].iter().zip(COLUMNS) {
+                    s.tag(TagKind::TD, |s| right_aligned(s, font, text, cell(column, y)))?;
+                }
+                Ok(())
+            })?;
+        }
+        Ok(())
+    })
+}
+
+/// The baseline of row `row` of the table.
+fn row_baseline(row: u32) -> f64 {
+    FIRST_ROW + ROW_HEIGHT * f64::from(row)
+}
+
+/// The box of a cell in `column` (width, distance from the right edge) on the row at `baseline`.
+fn cell((width, inset): (f64, f64), baseline: f64) -> RectPt {
+    RectPt::from_points(RIGHT_EDGE - inset - width, baseline - CELL_RISE, width, CELL_HEIGHT)
+}
+
+/// `text` in `area`, in the body size, aligned to its right edge.
+fn right_aligned(s: &mut Surface, font: &FontHandle, text: &str, area: RectPt) -> Result<(), BuildError> {
+    let right = TextBoxOptions::new().with_align(Alignment::End);
+    s.text_box(text, font, BODY, area, &right).map(|_| ())
+}
+```</TabItem>
+
+The result is one A4 page with its body set in Noto Sans: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/invoice.pdf).
+
+## How it works
+
+- The body uses your font file, and Lamina PDF embeds only the glyphs the invoice draws. The heading uses Helvetica Bold, one of the [standard 14 fonts](../../pages/reference/glossary.md#standard-14-fonts), so it embeds nothing.
+- Each quantity and amount is a text box aligned to its `end`, so the numbers line up on the right. `cell` works out each box from its column's width and its distance from the right margin.
+- `tagged: true` (`with_tagged(true)` in Rust) gives the document a structure for screen readers. The `tag` option and `s.tag(…)` make the heading an `H1`, the address and the total each a paragraph (`P`), and the items a `Table` of rows (`TR`) and cells (`TD`).
+- `metadata` sets the title and author, and `lang("en-GB")` tells a screen reader which language to speak.
+
+## What to change
+
+- **The line items:** edit `ITEMS`. Each row sits `ROW_HEIGHT` points below the one before, and the total follows the last row.
+- **The columns:** each pair in `COLUMNS` is a column's width and its distance from the right margin, in points.
+- **The currency:** change the `€` in the amount and total strings. Your font needs a glyph for the new symbol, or drawing fails with `missing-glyph`. See [Text and fonts](../../pages/guides/fonts-and-text.md).
+- **A PDF/UA-1 invoice:** add `profiles: ["PDF/UA-1"]` (`with_profile(Profile::PdfUa1)` in Rust) to check the rules for accessible PDFs. PDF/UA-1 needs every font embedded, so load a bold font file for the heading. See [Accessible PDFs](../../pages/guides/accessible-pdfs.md).
+
+Next: [multilingual text](../../pages/recipes/multilingual.md), with five scripts, each in its own embedded font.

package/docs/pages/recipes/links-and-outlines.md

@@ -0,0 +1,215 @@
+---
+title: "Links and outlines"
+description: "Four A5 pages joined by web, page and named links, with a nested outline, page labels that read i, ii, 1, 2 and the outline shown on open."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/links-and-outlines/"
+---
+
+# Links and outlines
+
+Four A5 pages joined by web, page and named links, with a nested outline, page labels that read i, ii, 1, 2 and the outline shown on open.
+
+You'll make four A5 pages joined by links to a website and between pages, an outline (the bookmarks panel) and page numbers that read i, ii, 1, 2. Start from it for a manual, a report or any document longer than a page or two.
+
+The function draws the four pages, links them and returns the PDF's bytes. It draws text, so in TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+<TabItem label="TypeScript">`packages/sdk/examples/links-and-outlines.ts`:
+
+```ts
+// Links and outlines: four A5 pages joined by links, bookmarks and page labels. The title page
+// links to a website, to a page and through a named destination; every other page has a linked
+// text run back to it. The outline is nested and shown when the file opens.
+import { Builder, type BuilderOptions, Font, type LinkTarget, type Surface } from "@laminapdf/sdk";
+
+const TITLES = ["Title page", "Contents", "Chapter 1", "Chapter 2"] as const;
+const MARGIN = 36;
+const TITLE_BASELINE = 60;
+const TITLE_SIZE = 18;
+const LINK_SIZE = 12;
+/** The baselines of the title page's three links. */
+const LINK_BASELINES = [100, 125, 150] as const;
+/** A link's clickable box: this wide, this tall, starting this far above the baseline. */
+const LINK_WIDTH = 220;
+const LINK_HEIGHT = 20;
+const LINK_RISE = 15;
+
+/**
+ * The document's bytes. Needs `init({ text: true })`.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function linksAndOutlines(options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const font = Font.standard("Helvetica");
+  b.font(font);
+  b.destination("chapter-2", 3);
+  TITLES.forEach((title, index) => {
+    const page = b.page("A5");
+    const s = page.surface();
+    s.text(title, { font, size: TITLE_SIZE, at: [MARGIN, TITLE_BASELINE] });
+    if (index === 0) titlePageLinks(s, font);
+    else {
+      const link = { target: { type: "page", index: 0 }, contents: "Title page" } as const;
+      s.text("Back to the title page", { font, size: LINK_SIZE, at: [MARGIN, 100], fill: [0, 0.2, 0.8], link });
+    }
+    page.finish();
+  });
+  navigation(b);
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** The title page's links: to a website, to a page, and to a named destination. */
+function titlePageLinks(s: Surface, font: Font): void {
+  const links: readonly (readonly [label: string, target: LinkTarget, contents?: string])[] = [
+    ["Visit example.com", { type: "uri", uri: "https://example.com/" }, "Example"],
+    ["Go to chapter 1", { type: "page", index: 2 }],
+    ["Go to chapter 2 (named)", { type: "named", name: "chapter-2" }],
+  ];
+  links.forEach(([label, target, contents], i) => {
+    const baseline = LINK_BASELINES[i] ?? 0;
+    s.text(label, { font, size: LINK_SIZE, at: [MARGIN, baseline] });
+    s.link([MARGIN, baseline - LINK_RISE, LINK_WIDTH, LINK_HEIGHT], target, contents);
+  });
+}
+
+/** The outline (bookmarks), the page labels, and the viewer opening with the outline shown. */
+function navigation(b: Builder): void {
+  b.outline([
+    { title: "Title page", target: { type: "page", index: 0 } },
+    { title: "Contents", target: { type: "page", index: 1 }, color: [0, 0, 0.6] },
+    {
+      title: "Chapters",
+      open: true,
+      bold: true,
+      children: [
+        { title: "Chapter 1", target: { type: "page", index: 2 } },
+        { title: "Chapter 2", target: { type: "named", name: "chapter-2" }, italic: true },
+      ],
+    },
+  ]);
+  b.pageLabels([
+    { start: 0, style: "lowerRoman" },
+    { start: 2, style: "decimal" },
+  ]).viewerPreferences({ pageMode: "outlines" });
+}
+```</TabItem>
+<TabItem label="Rust">`crates/laminapdf/examples/links_and_outlines.rs`:
+
+````rust
+//! Links and outlines: four A5 pages joined by links, bookmarks and page labels.
+//!
+//! The title page has a URI link, a link to a page and one through a named destination; every
+//! other page has a linked text run back to it. The outline (bookmarks) is nested and open in
+//! the viewer, and the pages are labelled i, ii, 1, 2.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example links_and_outlines -- [out-dir]   # writes <out-dir>/links_and_outlines.pdf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    BuildOptions, Builder, Color, Fit, FontHandle, LabelStyle, LinkTarget, OutlineEntry, PageLabel, PageMode, PageSize,
+    PointPt, Pt, RectPt, SaveOptions, Standard14, Surface, ViewerPreferences,
+};
+
+const TITLES: [&str; 4] = ["Title page", "Contents", "Chapter 1", "Chapter 2"];
+const MARGIN: f64 = 36.0;
+const TITLE_AT: PointPt = PointPt::from_points(MARGIN, 60.0);
+const BACK_AT: PointPt = PointPt::from_points(MARGIN, 100.0);
+const TITLE_SIZE: Pt = Pt::new(18.0);
+const LINK_SIZE: Pt = Pt::new(12.0);
+/// The baselines of the title page's three links.
+const LINK_BASELINES: [f64; 3] = [100.0, 125.0, 150.0];
+/// A link's clickable box: this wide, this tall, starting this far above the baseline.
+const LINK_WIDTH: f64 = 220.0;
+const LINK_HEIGHT: f64 = 20.0;
+const LINK_RISE: f64 = 15.0;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let out = PathBuf::from(std::env::args().nth(1).unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    std::fs::write(out.join("links_and_outlines.pdf"), build(BuildOptions::new())?)?;
+    Ok(())
+}
+
+/// The document's bytes. `options` can fix the file ID, the producer and the creation date.
+pub(crate) fn build(options: BuildOptions) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let helvetica = b.standard_font(Standard14::Helvetica)?;
+    b.destination("chapter-2", 3, Fit::Page);
+    for (index, title) in (0_u32..).zip(TITLES) {
+        let mut page = b.page(PageSize::A5);
+        let s = page.surface();
+        s.text(title, &helvetica, TITLE_SIZE, TITLE_AT)?;
+        if index == 0 {
+            title_page_links(s, &helvetica)?;
+        } else {
+            s.text("Back to the title page", &helvetica, LINK_SIZE, BACK_AT)?
+                .fill(Color::rgb(0.0, 0.2, 0.8))
+                .link(LinkTarget::page(0), Some("Title page".into()));
+        }
+        page.finish()?;
+    }
+    navigation(&mut b)?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+
+/// The title page's links: to a website, to a page, and to a named destination.
+fn title_page_links(s: &mut Surface, font: &FontHandle) -> Result<(), Box<dyn Error>> {
+    let site = LinkTarget::Uri("https://example.com/".into());
+    let links = [
+        ("Visit example.com", site, Some("Example")),
+        ("Go to chapter 1", LinkTarget::page(2), None),
+        ("Go to chapter 2 (named)", LinkTarget::Named("chapter-2".into()), None),
+    ];
+    for ((label, target, contents), baseline) in links.into_iter().zip(LINK_BASELINES) {
+        s.text(label, font, LINK_SIZE, PointPt::from_points(MARGIN, baseline))?;
+        let area = RectPt::from_points(MARGIN, baseline - LINK_RISE, LINK_WIDTH, LINK_HEIGHT);
+        s.link(area, target, contents.map(String::from));
+    }
+    Ok(())
+}
+
+/// The outline (bookmarks), the page labels, and the viewer opening with the outline shown.
+fn navigation(b: &mut Builder) -> Result<(), Box<dyn Error>> {
+    b.outline(vec![
+        OutlineEntry::new("Title page", LinkTarget::page(0)),
+        OutlineEntry::new("Contents", LinkTarget::page(1)).with_color(0.0, 0.0, 0.6),
+        OutlineEntry::heading("Chapters")
+            .open(true)
+            .bold()
+            .with_child(OutlineEntry::new("Chapter 1", LinkTarget::page(2)))
+            .with_child(OutlineEntry::new("Chapter 2", LinkTarget::Named("chapter-2".into())).italic()),
+    ])?;
+    b.page_labels(vec![
+        PageLabel::new(0, Some(LabelStyle::LowerRoman)),
+        PageLabel::new(2, Some(LabelStyle::Decimal)),
+    ])
+    .viewer_preferences(ViewerPreferences::default().with_page_mode(PageMode::Outlines));
+    Ok(())
+}
+````</TabItem>
+
+The result is four A5 pages with an outline and page labels: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/links_and_outlines.pdf).
+
+## How it works
+
+- `s.link(rect, target, contents)` puts a clickable box over each label on the title page. A target is a web address (`uri`), a page by its index from 0, or a named destination. See [Pages and coordinates](../../pages/concepts/pages-and-coordinates.md#pages-count-from-0).
+- `destination("chapter-2", 3)` names the fourth page, so a link or an outline entry can go there by name. When the builder finishes, a missing page fails with `page-index-out-of-range` and a missing name with `unknown-destination`.
+- On the other pages, the `link` option of `text` (`.link(…)` on the run in Rust) makes the blue run itself the link, with no box to work out.
+- `contents` describes a link in words, for viewers and screen readers. Accessible PDFs need one on every link.
+- `outline` builds the bookmarks. "Chapters" has no target, so it's a heading, shown open and in bold with both chapters inside it.
+- `pageLabels` numbers the pages i and ii, then 1 and 2 from the third page. `pageMode: "outlines"` asks the viewer to open the file with the outline showing.
+
+## What to change
+
+- **Where a page link lands:** add a `fit` to the target, such as `fit: { type: "width" }` (`Fit::Width` in Rust) to fill the window with the page's width. `destination` takes one too.
+- **The page numbers:** a label also takes a `prefix` and a `first` number, so `{ start: 2, style: "decimal", prefix: "A-" }` numbers the chapters A-1 and A-2.
+- **The panel on open:** `pageMode` also takes `"thumbnails"`, `"attachments"` or `"none"`.
+- **A title and an author:** add `metadata({ title, author })`, and `displayDocTitle: true` in the viewer preferences so viewers show the title instead of the file name. See [Links, outlines and metadata](../../pages/guides/links-outlines-and-metadata.md).
+
+Next: [generate, then edit](../../pages/recipes/generate-then-edit.md), which opens a PDF you made and changes its metadata.

package/docs/pages/recipes/multilingual.md

@@ -0,0 +1,189 @@
+---
+title: "Multilingual text"
+description: "Latin, Arabic, Devanagari, Hebrew and Chinese on one page, each in its own embedded font, as a shaped line and a wrapped paragraph."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/recipes/multilingual/"
+---
+
+# Multilingual text
+
+Latin, Arabic, Devanagari, Hebrew and Chinese on one page, each in its own embedded font, as a shaped line and a wrapped paragraph.
+
+You'll put five scripts on one page: Latin, Arabic, Devanagari, Hebrew and Chinese, each as a single line and as a paragraph wrapped in a box. Start from it whenever your text goes beyond Latin, or mixes left-to-right and right-to-left writing.
+
+The function takes one font file per script, draws each script's line and paragraph, and returns the PDF's bytes. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+<TabItem label="TypeScript">`packages/sdk/examples/multilingual.ts`:
+
+```ts
+// Five scripts on one page, each as a single line and as a wrapped paragraph. The scripts are
+// Latin, Arabic and Hebrew (right to left), Devanagari and simplified Chinese; each is shaped and
+// bidi-resolved, and each paragraph wraps in a text box. Each script needs a font that covers it,
+// such as the Noto fonts (OFL).
+import { Builder, type BuilderOptions, type Direction, Font } from "@laminapdf/sdk";
+
+/** Each script's line, its paragraph and the paragraph's direction, in the order of the fonts. */
+export const SCRIPTS: readonly (readonly [line: string, paragraph: string, direction: Direction])[] = [
+  [
+    "Latin: the office staff fill the affine waffle flask",
+    "A paragraph breaks at spaces and fits the width of its box, line by line.",
+    "ltr",
+  ],
+  ["مرحبا بالعالم السلام عليكم", "مرحبا بالعالم السلام عليكم مرحبا بالعالم السلام عليكم", "rtl"],
+  ["नमस्ते दुनिया। हिन्दी पाठ का परीक्षण", "नमस्ते दुनिया। हिन्दी पाठ का परीक्षण नमस्ते दुनिया।", "ltr"],
+  ["שלום עולם וברוכים הבאים", "שלום עולם וברוכים הבאים שלום עולם וברוכים הבאים", "rtl"],
+  ["你好世界，这是中文字体子集测试。", "你好世界，这是中文字体子集测试。你好世界，这是中文。", "ltr"],
+];
+const MARGIN = 56;
+const FIRST_BASELINE = 80;
+/** The distance from one script's line to the next one's. */
+const SCRIPT_HEIGHT = 140;
+/** The paragraph's box: this far below the line, this wide and this tall. */
+const PARAGRAPH_DROP = 14;
+const PARAGRAPH_WIDTH = 220;
+const PARAGRAPH_HEIGHT = 100;
+
+/**
+ * The document's bytes. Needs `init({ text: true })`.
+ *
+ * @param fonts - one font file per script, in the order of {@link SCRIPTS}.
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function multilingual(fonts: readonly Uint8Array[], options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  if (fonts.length !== SCRIPTS.length) throw new Error(`${SCRIPTS.length} fonts, one per script, are needed`);
+  using b = new Builder(options);
+  const loaded = fonts.map((bytes) => Font.fromBytes(bytes));
+  for (const font of loaded) b.font(font);
+  const page = b.page("A4");
+  const s = page.surface();
+  SCRIPTS.forEach(([line, paragraph, direction], row) => {
+    const font = loaded[row];
+    if (font === undefined) return;
+    const y = FIRST_BASELINE + SCRIPT_HEIGHT * row;
+    s.text(line, { font, size: 16, at: [MARGIN, y] });
+    // A narrow box breaks the paragraph into lines; right-to-left paragraphs start at the right.
+    const box = [MARGIN, y + PARAGRAPH_DROP, PARAGRAPH_WIDTH, PARAGRAPH_HEIGHT] as const;
+    s.textBox(paragraph, { font, size: 12, box, direction, align: "start" });
+  });
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+```</TabItem>
+<TabItem label="Rust">`crates/laminapdf/examples/multilingual.rs`:
+
+````rust
+//! Five scripts on one page, each as a single line and as a wrapped paragraph.
+//!
+//! The scripts are Latin, Arabic and Hebrew (right to left), Devanagari and simplified Chinese;
+//! each is shaped and bidi-resolved, and each paragraph wraps in a text box. Each script needs a
+//! font that covers it, such as the Noto fonts (OFL).
+//!
+//! ```sh
+//! cargo run -p laminapdf --example multilingual -- latin.ttf arabic.ttf devanagari.ttf hebrew.ttf chinese.otf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    Alignment, BuildOptions, Builder, Direction, PageSize, PointPt, Pt, RectPt, SaveOptions, TextBoxOptions,
+};
+
+/// Each script's line, its paragraph and the paragraph's direction, in the order of the fonts.
+const SCRIPTS: [(&str, &str, Direction); 5] = [
+    (
+        "Latin: the office staff fill the affine waffle flask",
+        "A paragraph breaks at spaces and fits the width of its box, line by line.",
+        Direction::LeftToRight,
+    ),
+    (
+        "مرحبا بالعالم السلام عليكم",
+        "مرحبا بالعالم السلام عليكم مرحبا بالعالم السلام عليكم",
+        Direction::RightToLeft,
+    ),
+    (
+        "नमस्ते दुनिया। हिन्दी पाठ का परीक्षण",
+        "नमस्ते दुनिया। हिन्दी पाठ का परीक्षण नमस्ते दुनिया।",
+        Direction::LeftToRight,
+    ),
+    (
+        "שלום עולם וברוכים הבאים",
+        "שלום עולם וברוכים הבאים שלום עולם וברוכים הבאים",
+        Direction::RightToLeft,
+    ),
+    (
+        "你好世界，这是中文字体子集测试。",
+        "你好世界，这是中文字体子集测试。你好世界，这是中文。",
+        Direction::LeftToRight,
+    ),
+];
+const MARGIN: f64 = 56.0;
+const FIRST_BASELINE: f64 = 80.0;
+/// The distance from one script's line to the next one's.
+const SCRIPT_HEIGHT: f64 = 140.0;
+/// The paragraph's box: this far below the line, this wide and this tall.
+const PARAGRAPH_DROP: f64 = 14.0;
+const PARAGRAPH_WIDTH: f64 = 220.0;
+const PARAGRAPH_HEIGHT: f64 = 100.0;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args: Vec<String> = std::env::args().skip(1).collect();
+    let out = PathBuf::from(if args.len() > SCRIPTS.len() {
+        args.remove(SCRIPTS.len())
+    } else {
+        "target/examples-out".into()
+    });
+    let fonts = args.iter().map(std::fs::read).collect::<Result<Vec<_>, _>>()?;
+    std::fs::create_dir_all(&out)?;
+    std::fs::write(out.join("multilingual.pdf"), build(BuildOptions::new(), fonts)?)?;
+    Ok(())
+}
+
+/// The document's bytes, with one font per script in `fonts` (in the order of [`SCRIPTS`]).
+/// `options` can fix the file ID, the producer and the creation date.
+pub(crate) fn build(options: BuildOptions, fonts: Vec<Vec<u8>>) -> Result<Vec<u8>, Box<dyn Error>> {
+    if fonts.len() != SCRIPTS.len() {
+        return Err(format!("{} fonts, one per script, are needed", SCRIPTS.len()).into());
+    }
+    let mut b = Builder::new(options);
+    let fonts = fonts
+        .into_iter()
+        .map(|bytes| b.font_bytes(bytes))
+        .collect::<Result<Vec<_>, _>>()?;
+    let mut page = b.page(PageSize::A4);
+    let s = page.surface();
+    for (row, ((line, paragraph, direction), font)) in (0_u32..).zip(SCRIPTS.iter().zip(&fonts)) {
+        let y = FIRST_BASELINE + SCRIPT_HEIGHT * f64::from(row);
+        s.text(line, font, Pt::new(16.0), PointPt::from_points(MARGIN, y))?;
+        // A narrow box breaks the paragraph into lines; right-to-left paragraphs start at the right.
+        let options = TextBoxOptions::new()
+            .with_direction(*direction)
+            .with_align(Alignment::Start);
+        let area = RectPt::from_points(MARGIN, y + PARAGRAPH_DROP, PARAGRAPH_WIDTH, PARAGRAPH_HEIGHT);
+        s.text_box(paragraph, font, Pt::new(12.0), area, &options)?;
+    }
+    page.finish()?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+````</TabItem>
+
+The result is one A4 page, with each script set in its own Noto font: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/multilingual.pdf).
+
+## How it works
+
+- `Font.fromBytes` (`font_bytes` in Rust) loads each font, which must cover its script. The builder embeds only the glyphs the page draws.
+- Lamina PDF shapes the text with each font, so Arabic letters join, Devanagari letters combine into clusters and the Latin line forms ligatures.
+- `textBox` breaks each paragraph into lines that fit its 220-point-wide box. It breaks where Unicode's line-breaking rules allow: between words, and between Chinese characters.
+- `direction: "rtl"` (`Direction::RightToLeft`) makes the Arabic and Hebrew paragraphs right to left, so `align: "start"` starts their lines at the box's right edge.
+- Each font is embedded with its [ToUnicode](../../pages/reference/glossary.md#tounicode) mapping, so text copied or extracted from the PDF equals the strings you passed in, ligatures included.
+
+## What to change
+
+- **Your own scripts:** change `SCRIPTS` and pass one font per row, in the same order. A character the font lacks fails with `missing-glyph`.
+- **The paragraph's box:** `PARAGRAPH_WIDTH` and `PARAGRAPH_HEIGHT` set its size. Lines that don't fit are left out, unless you pass `overflow: "error"` (`Overflow::Error`) to fail with `text-overflow` instead.
+- **Alignment and spacing:** `align` also takes `"end"`, `"left"`, `"right"` or `"center"`, and `lineHeight` (`with_line_height`) sets the distance between baselines, 1.2 times the size by default.
+- **Ligatures and other OpenType features:** `features: ["liga=0"]` on `text` or `textBox` turns the ligatures off. In Rust, call `features` on the run or `with_feature` on the text box's options. See [Text and fonts](../../pages/guides/fonts-and-text.md).
+
+Next: [images and vectors](../../pages/recipes/images-and-vectors.md), with shapes, colour, transparency and two images.