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

package/docs/pages/recipes/element-flow.md

@@ -0,0 +1,248 @@
+---
+title: "Element flow"
+description: "A report whose title, paragraphs and photo each start below wherever the one before ended, with a body that continues on a new page."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/element-flow/"
+---
+
+# Element flow
+
+A report whose title, paragraphs and photo each start below wherever the one before ended, with a body that continues on a new page.
+
+You'll lay out a report where each part starts below wherever the part before it ended: a title, a summary, optional notes, a photo and a body that runs onto a second page. Use it when the length of your text changes from one document to the next.
+
+The function takes a JPEG's bytes and the report's text, and returns the PDF's bytes. In TypeScript it draws text, so it needs `init({ text: true })`. Both languages write the same bytes:
+
+**TypeScript**
+
+`packages/sdk/examples/element-flow.ts`:
+
+```ts
+// A report whose title, paragraphs and photo each start below wherever the one before ended. Each
+// text box reports its `bottom`, and the next element starts a gap below it, so a summary that
+// wraps moves everything after it and empty notes take no space. The body continues on new pages
+// from the top margin. Needs `init({ text: true })`.
+import { Builder, type BuilderOptions, Font, Image, PAGE_SIZES, type Surface, type TextLayout } from "@laminapdf/sdk";
+
+const [PAGE_WIDTH, PAGE_HEIGHT] = PAGE_SIZES.A5;
+const MARGIN = 48;
+const WIDTH = PAGE_WIDTH - 2 * MARGIN;
+const BOTTOM = PAGE_HEIGHT - MARGIN;
+const TITLE = 18;
+const BODY = 11;
+const GAP = 10;
+/** The photo's height, for a 3:2 photo across the text column. */
+const PHOTO_HEIGHT = WIDTH / 1.5;
+
+/** What the report says. Empty `notes` take no space; blank lines separate the body's paragraphs. */
+export interface Report {
+  readonly title: string;
+  readonly summary: string;
+  readonly notes: string;
+  readonly body: string;
+}
+
+/**
+ * The report's bytes, with `photo` (a JPEG) below its notes.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function elementFlow(photo: Uint8Array, report: Report, options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const fonts = { bold: Font.standard("Helvetica-Bold"), regular: Font.standard("Helvetica") };
+  const jpeg = Image.jpeg(photo);
+  let page = b.page("A5");
+  let y = header(page.surface(), fonts, jpeg, report);
+  let [rest, newPage] = [report.body.trimEnd(), false];
+  for (;;) {
+    const layout = page.surface().textBox(rest, { font: fonts.regular, size: BODY, box: area(y) });
+    // A clipped box still drew its first lines: the rest goes on a new page, from its top.
+    const cut = layout.overflow;
+    if (cut === undefined) break;
+    if (cut === 0 && newPage) throw new Error("a line of the body is taller than the page");
+    [rest, y, newPage] = [rest.slice(cut).trimStart(), MARGIN, true];
+    page.finish();
+    page = b.page("A5");
+  }
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+
+/**
+ * The title with a rule under it, the summary, the notes and the photo, each below the one before;
+ * returns where the body starts. Text that doesn't fit throws `text-overflow`.
+ */
+function header(s: Surface, fonts: { bold: Font; regular: Font }, photo: Image, report: Report): number {
+  const fit = (text: string, font: Font, size: number, top: number) =>
+    below(s.textBox(text, { font, size, box: area(top), overflow: "error" }), top);
+  let y = fit(report.title, fonts.bold, TITLE, MARGIN);
+  // A decoration half a gap above the summary. It's stroked: a fill colour would colour the text too.
+  s.strokeColor([0.6])
+    .path((p) => p.rect([MARGIN, y - GAP / 2, WIDTH, 0]))
+    .stroke();
+  for (const text of [report.summary, report.notes]) y = fit(text, fonts.regular, BODY, y);
+  if (y + PHOTO_HEIGHT > BOTTOM) throw new Error("the photo doesn't fit below the notes");
+  s.image(photo, [MARGIN, y, WIDTH, PHOTO_HEIGHT]);
+  return y + PHOTO_HEIGHT + GAP;
+}
+
+/** Where the next element starts: a gap below `layout`'s last drawn line, or `y` if it drew none. */
+function below(layout: TextLayout, y: number): number {
+  return layout.bottom === undefined ? y : layout.bottom + GAP;
+}
+
+/** The rest of the page's text column, from `y` down to the bottom margin. */
+function area(y: number): [number, number, number, number] {
+  return [MARGIN, y, WIDTH, Math.max(BOTTOM - y, 0)];
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/element_flow.rs`:
+
+```rust
+//! A report whose title, paragraphs and photo each start below wherever the one before ended.
+//!
+//! Each text box reports its `bottom`, and the next element starts a gap below it, so a summary
+//! that wraps moves everything after it and empty notes take no space. The body continues on new
+//! pages from the top margin. Run it with `cargo run -p laminapdf --example element_flow -- photo.jpg`.
+
+use std::error::Error;
+
+use laminapdf::{
+    BuildOptions, Builder, Color, FontHandle, Image, Overflow, PageSize, Pt, RectPt, SaveOptions,
+    Standard14::{Helvetica, HelveticaBold},
+    StrokeStyle, Surface, TextBoxOptions, TextLayout,
+};
+
+const PAGE: PageSize = PageSize::A5;
+const MARGIN: f64 = 48.0;
+const WIDTH: f64 = PAGE.width.get() - 2.0 * MARGIN;
+const BOTTOM: f64 = PAGE.height.get() - MARGIN;
+const TITLE: Pt = Pt::new(18.0);
+const BODY: Pt = Pt::new(11.0);
+const GAP: f64 = 10.0;
+const PHOTO_HEIGHT: f64 = WIDTH / 1.5; // a 3:2 photo across the text column
+
+/// What the report says. Empty `notes` take no space; blank lines separate the body's paragraphs.
+pub(crate) struct Report<'a> {
+    pub(crate) title: &'a str,
+    pub(crate) summary: &'a str,
+    pub(crate) notes: &'a str,
+    pub(crate) body: &'a str,
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args = std::env::args().skip(1);
+    let photo = std::fs::read(args.next().ok_or("usage: element_flow <photo.jpg> [out-dir]")?)?;
+    let out = std::path::PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    let report = Report {
+        title: "Third-quarter report",
+        summary: "Revenue rose twelve per cent over the quarter, led by the new reader and its offline mode.",
+        notes: "Figures are unaudited.",
+        body: "Pages now appear as soon as they are read, and support requests about slow files fell by a third.",
+    };
+    let pdf = build(BuildOptions::new(), photo, &report)?;
+    std::fs::create_dir_all(&out)?;
+    Ok(std::fs::write(out.join("element_flow.pdf"), pdf)?)
+}
+
+/// The report's bytes, with `photo` (a JPEG) below its notes. `options` can fix the file ID, the
+/// producer and the creation date.
+pub(crate) fn build(options: BuildOptions, photo: Vec<u8>, report: &Report) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let fonts = [b.standard_font(HelveticaBold)?, b.standard_font(Helvetica)?];
+    let photo = Image::jpeg(photo)?;
+    let mut page = b.page(PAGE);
+    let mut y = header(page.surface(), &fonts, &photo, report)?;
+    let (mut rest, mut new_page) = (report.body.trim_end(), false);
+    loop {
+        let s = page.surface();
+        let layout = s.text_box(rest, &fonts[1], BODY, area(y), &TextBoxOptions::new())?;
+        // A clipped box still drew its first lines: the rest goes on a new page, from its top.
+        let Some(cut) = layout.overflow else { break };
+        if cut == 0 && new_page {
+            return Err("a line of the body is taller than the page".into());
+        }
+        (rest, y, new_page) = (rest[cut..].trim_start(), MARGIN, true);
+        page.finish()?;
+        page = b.page(PAGE);
+    }
+    page.finish()?;
+    Ok(b.finish()?.save(&SaveOptions::new())?.bytes)
+}
+
+/// The title with a rule under it, the summary, the notes and the photo, each below the one
+/// before; returns where the body starts. Text that doesn't fit fails `text-overflow`.
+fn header(s: &mut Surface, fonts: &[FontHandle; 2], photo: &Image, report: &Report) -> Result<f64, Box<dyn Error>> {
+    let [bold, regular] = fonts;
+    let must_fit = TextBoxOptions::new().with_overflow(Overflow::Error);
+    let mut y = below(&s.text_box(report.title, bold, TITLE, area(MARGIN), &must_fit)?, MARGIN);
+    // A decoration half a gap above the summary. It's stroked: a fill colour would colour the text too.
+    let (rule, gray) = (RectPt::from_points(MARGIN, y - GAP / 2.0, WIDTH, 0.0), Color::gray(0.6));
+    let line = StrokeStyle::default();
+    s.stroke_color(gray).path(|p| _ = p.rect(rule)).stroke(&line);
+    for text in [report.summary, report.notes] {
+        y = below(&s.text_box(text, regular, BODY, area(y), &must_fit)?, y);
+    }
+    if y + PHOTO_HEIGHT > BOTTOM {
+        return Err("the photo doesn't fit below the notes".into());
+    }
+    s.image(photo, RectPt::from_points(MARGIN, y, WIDTH, PHOTO_HEIGHT));
+    Ok(y + PHOTO_HEIGHT + GAP)
+}
+
+/// Where the next element starts: a gap below `layout`'s last drawn line, or `y` if it drew none.
+fn below(layout: &TextLayout, y: f64) -> f64 {
+    layout.bottom().map_or(y, |bottom| bottom.get() + GAP)
+}
+
+/// The rest of the page's text column, from `y` down to the bottom margin.
+fn area(y: f64) -> RectPt {
+    RectPt::from_points(MARGIN, y, WIDTH, (BOTTOM - y).max(0.0))
+}
+```
+
+**Result:** [element_flow.pdf](https://docs.laminapdf.com/examples/pdf/element_flow.pdf)
+
+The result is two A5 pages. The body fills the first page below the photo and finishes at the top of the second. The Result tab shows it, with a link to the PDF.
+
+## How it works
+
+Every text box tells you where its text ended, so you never type a position for anything after the first element.
+
+- **`bottom` is where the next element can start.** `textBox` returns it with the lines it drew: the bottom of the last line that draws something. Rust has `TextLayout::bottom()`, and `TextRun::bottom()` for a single run of text.
+- **Empty text has no `bottom`.** The notes here are optional. When they're empty, `bottom` is `undefined` (`None` in Rust), `below` keeps `y` where it was, and the photo moves up with no gap left behind.
+- **A longer summary moves everything after it.** When the summary wraps onto one more line, the notes, the photo and the body each move down by one line height, and none of the code changes.
+- **The photo is placed by your own rectangle.** An image reports nothing back, so the code adds the photo's height and the gap to `y` itself.
+- **The rule under the title is a decoration.** It's drawn half a gap above the summary and leaves `y` alone. It's stroked rather than filled: a fill colour stays set and would colour the text drawn after it.
+
+## Text that doesn't fit
+
+The report treats overflow two ways, and you choose which for each element.
+
+The title, summary and notes must fit on the first page. They're drawn with `overflow: "error"` (`Overflow::Error` in Rust), so text that doesn't fit throws `text-overflow` instead of disappearing. The photo must fit too: when it would cross the bottom margin, the code stops with an error of its own.
+
+The body may run on. Its box reaches the bottom margin and clips what doesn't fit. Then `overflow` holds the offset of the first character it didn't draw: a UTF-16 offset in TypeScript, a byte offset in Rust. The loop starts a new page and draws the rest from the top margin. Test `overflow` with `!== undefined`, because `0` means not even one line fitted. If no line fits even on a fresh page, a line is taller than the page, so the loop stops with an error instead of adding pages for ever.
+
+## What `bottom` measures
+
+`bottom` is a typographic measurement in points: the descent of the last drawn line's font, below its baseline. A glyph that reaches lower, or a thick stroke around the text, can paint past it.
+
+Like every position, `bottom` is in [page space](../../pages/reference/glossary.md#page-space), measured from the top of the page. It's measured before the surface's transform, so inside `transform` it stays in the coordinates you drew in.
+
+In TypeScript you pass a box as a tuple, `[x, y, width, height]`. The lines a text box returns describe their `rect` as an object with `x`, `y`, `width` and `height`.
+
+## What stays your job
+
+Page breaks stay your decision: the code here makes each one from `overflow`. The builder's surface doesn't paginate, float an image beside text, or lay out tables. In Rust, [Pages that flow](../../pages/guides/flowing-pages.md) paginates for you: headings kept with their text, running headers and "Page X of Y" footers.
+
+## What to change
+
+- **Paragraphs a gap apart:** draw each paragraph in its own text box and start the next one at `bottom` plus the gap, as the summary and notes do.
+- **A line height for the body:** pass `lineHeight` (`with_line_height` in Rust); `bottom` follows it.
+- **Two columns:** keep a `y` for each column, and when the left column fills, carry on at the top margin of the right one.
+
+Next: [the PDF/UA report](../../pages/recipes/pdf-ua-report.md), a report that screen readers can follow.

package/docs/pages/recipes/extract-markdown.md

@@ -0,0 +1,152 @@
+---
+title: "Extract text for an LLM"
+description: "Turn a PDF into Markdown in reading order, JSON with a box for every block, and chunks sized for retrieval, in TypeScript and Rust."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/extract-markdown/"
+---
+
+# Extract text for an LLM
+
+Turn a PDF into Markdown in reading order, JSON with a box for every block, and chunks sized for retrieval, in TypeScript and Rust.
+
+You'll turn a PDF into three outputs an LLM or a search index can use: Markdown in reading order, JSON giving every paragraph and table its page and box, and 400-token chunks.
+
+In TypeScript the function returns the three outputs and needs the extract module, `init({ extract: true })`. In Rust, the program instead extracts once and writes the three files. Both give the same JSON:
+
+**TypeScript**
+
+`packages/sdk/examples/extract-markdown.ts`:
+
+```ts
+// Extract a PDF's text for an LLM: Markdown in reading order, JSON with a box for every block,
+// and chunks sized for retrieval.
+//
+// Tables drawn with lines come out as Markdown tables, and text a reader can't see (white,
+// invisible or off the page) is left out of all three.
+import { type Chunk, Document, type Extraction } from "@laminapdf/sdk";
+
+/** What a PDF gives an LLM or a search index. */
+export interface ForAnLlm {
+  /** The text in reading order, with a `<!-- page N -->` comment before each page. */
+  readonly markdown: string;
+  /** Every block with its page and box, the text left out, the file's warnings and the chunks. */
+  readonly json: Extraction;
+  /** About 400 tokens each, a new one at each heading. */
+  readonly chunks: readonly Chunk[];
+}
+
+/** The Markdown, the JSON and the chunks of `bytes`. Needs `init({ extract: true })`. */
+export function extractForAnLlm(bytes: Uint8Array): ForAnLlm {
+  using doc = Document.open(bytes);
+  // Page markers let a reader cite the page a passage came from.
+  const markdown = doc.extract({ format: "markdown", pageMarkers: true });
+  // The JSON carries the same chunks, and each block's place in the Markdown.
+  const json = doc.extract({ format: "json", pageMarkers: true, chunk: { maxTokens: 400 } });
+  return { markdown, json, chunks: json.chunks ?? [] };
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/extract_markdown.rs`:
+
+````rust
+//! Extract a PDF's text for an LLM: Markdown in reading order, JSON with a box for every
+//! block, and chunks sized for retrieval.
+//!
+//! Tables drawn with lines come out as Markdown tables, and text a reader can't see (white,
+//! invisible or off the page) is left out of all three.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example extract_markdown -- <file.pdf> [out-dir]
+//! # writes <out-dir>/<file>.md, <file>.json and <file>.chunks.jsonl
+//! ```
+
+use std::error::Error;
+use std::path::{Path, PathBuf};
+
+use laminapdf::extract::{ChunkOptions, ExtractOptions, MarkdownOptions, chunks_jsonl};
+use laminapdf::{Document, OpenOptions};
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args = std::env::args().skip(1);
+    let input = PathBuf::from(args.next().ok_or("usage: extract_markdown <file.pdf> [out-dir]")?);
+    let out = PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    let stem = input.file_stem().and_then(|s| s.to_str()).unwrap_or("document");
+    write_outputs(&std::fs::read(&input)?, &out, stem)
+}
+
+/// Writes the Markdown, the JSON and the chunks of `bytes` into `out`.
+pub(crate) fn write_outputs(bytes: &[u8], out: &Path, stem: &str) -> Result<(), Box<dyn Error>> {
+    let doc = Document::open_bytes(bytes.to_vec(), OpenOptions::new())?;
+    let extraction = doc.extract(&ExtractOptions::new())?;
+
+    // Page markers let a reader cite the page a passage came from.
+    let markdown = extraction.to_markdown(&MarkdownOptions::new().with_page_markers(true));
+    std::fs::write(out.join(format!("{stem}.md")), &markdown.text)?;
+
+    // About 400 tokens a chunk, starting a new one at each heading.
+    let chunks = extraction.chunks(&markdown, &ChunkOptions::new().with_max_tokens(400));
+    std::fs::write(out.join(format!("{stem}.chunks.jsonl")), chunks_jsonl(&chunks))?;
+
+    let json = doc.extract_json(&extraction, &markdown, Some(chunks));
+    std::fs::write(out.join(format!("{stem}.json")), json)?;
+    Ok(())
+}
+````
+
+**Output**
+
+`fixtures/extract/examples/invoice.md`:
+
+```md
+<!-- page 1 -->
+
+# Invoice 42
+
+Acme Widgets Ltd · 1 Example Street · London
+
+| Widgets, blue (W-100) | 3 | € 36.00 |
+| --- | --- | --- |
+| Gadget with fine-tuned dials | 1 | € 79.90 |
+| Café-grade sprockets | 12 | € 15.00 |
+| Delivery | 1 | € 4.50 |
+
+Total € 135.40
+```
+
+Run the Rust program on any PDF: `cargo run -p laminapdf --example extract_markdown -- report.pdf out`.
+
+## How it works
+
+*Extraction joins a page's text runs into lines and blocks, orders them, then writes Markdown, JSON and chunks.*
+
+Extraction starts from each page's text runs. It sets aside runs a reader can't see, and runs the file marks as artifacts, into `dropped` with their reason: `invisible`, `off-page`, `tiny`, `clipped`, `low-contrast`, `covered` or `artifact`. The other runs are joined into lines, and the lines into blocks: paragraphs, headings and tables. Once every page is read, it also sets aside headers, footers and page numbers that repeat across pages, as `running-header`, `running-footer` or `page-number`. Reading order then puts the blocks in sequence: from the file's structure tree when it is tagged and the tree covers the page's text, else by cutting the page into columns. The ordered blocks become the three outputs: Markdown, the `laminapdf.extract/1` JSON and chunks.
+
+*On a two-column page, a title across both columns comes first, then the left column, then the right.*
+
+A page has a title across both columns and three blocks in each column. Extraction numbers the title 1, the left column's blocks 2 to 4 from top to bottom, and the right column's blocks 5 to 7.
+
+- `extract` (`doc.extract` in TypeScript) reads every page's text, joins it into lines and paragraphs, and puts the paragraphs in reading order. A two-column page reads down the left column, then the right; a title across both columns comes first.
+- Each block has a `confidence` from 0 to 1. When the page's columns could be read in more than one order, the page raises the `extract-column-order-uncertain` warning and the blocks in doubt get a confidence of 0.5. A pipeline can check those pages or send them to a layout model.
+- Tables drawn with lines become table blocks with their cells, and Markdown writes them as tables. A cell that spans columns or rows makes the table HTML, since Markdown tables can't span.
+- A table that goes on over a page break comes out as one table in the Markdown, the text and the chunks, with its header once. The JSON keeps one block per page, linked by `continuedBy` and `continues`, so each block's box stays on its own page.
+- Text a reader can't see never reaches the outputs: invisible text (such as the hidden layer of a scanned page), text off the page or too small to read, and text cut away by a clipping path. Nor does near-white text with nothing behind it, or text painted over by a later shape, image or comment. Headers, footers and page numbers that repeat across pages, and text the file marks as an artifact, are left out too. The JSON lists each such run under `dropped`, with the reason and how many characters it held.
+- `to_markdown` (`format: "markdown"` in TypeScript) writes headings, paragraphs and tables, with a `<!-- page N -->` comment before each page, so a passage can be traced to its page.
+- `chunks` (`format: "chunks"`, or the `chunk` option with the JSON) groups whole paragraphs and tables up to the budget, starting a new chunk at each heading. Each chunk records the blocks, pages and boxes it came from, and where its text sits in the Markdown.
+- `extract_json` (`format: "json"`) writes the `laminapdf.extract/1` document: the pages, every block with its box in points from the top-left corner, the dropped text, the file's warnings and the chunks.
+
+## What to change
+
+- **Only some pages:** `pages: [0, 1]` in TypeScript, `ExtractOptions::new().with_pages(vec![0, 1])` in Rust (page indexes start at 0).
+- **Tables without lines:** `tables: "lattice-and-stream"` (`.with_tables(TableMode::LatticeAndStream)`) also looks for text lined up in columns. It finds more tables, and now and then a pair of columns that isn't one.
+- **Bigger or smaller chunks:** change `maxTokens` (`with_max_tokens`). A token here is about four characters, a rough count that runs low for code, numbers and scripts other than Latin, so leave room.
+- **Overlap between chunks:** `overlap: 80` (`.with_overlap(80)`) repeats up to about 80 tokens of whole paragraphs from the end of the previous chunk.
+- **One output (TypeScript):** set `format` to `"markdown"`, `"text"`, `"json"` or `"chunks"`.
+- **Pages that need OCR:** a scanned page has no text to extract, so its Markdown is empty. Each page in the JSON has a `textLayer` whose `status` says so: `pages.filter(p => p.textLayer.status === "needs-ocr")` in TypeScript, `extraction.pages.iter().filter(|p| p.text_layer.status == TextLayerStatus::NeedsOcr)` in Rust. Send those pages to OCR or a vision model. A page made searchable by OCR is `ocr-layer`, since extraction leaves its invisible text out; the file's warnings name both kinds.
+- **A long file in steps (Rust):** `doc.extract_job(&options)` and `step` do a page per unit of work, so a long file can report progress or stop between steps.
+
+[Benchmarks](../../pages/reference/benchmarks.md) has extraction's scores on a public benchmark and how many pages a second it reads.
+
+Next: [all recipes](../../pages/recipes.md).

package/docs/pages/recipes/generate-then-edit.md

@@ -0,0 +1,142 @@
+---
+title: "Generate, then edit"
+description: "Build a one-page draft, open its bytes, retitle it in one transaction and save the edit as a revision after the original bytes."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/generate-then-edit/"
+---
+
+# Generate, then edit
+
+Build a one-page draft, open its bytes, retitle it in one transaction and save the edit as a revision after the original bytes.
+
+You'll generate a one-page draft report, then open its bytes, retitle it and save the edit as a revision after them. You need this whenever your app changes a PDF it already has, such as a file a user uploads or one it wrote earlier.
+
+One function builds and saves the draft. Another opens those bytes, changes the title and author, and saves again. In TypeScript the draft needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+**TypeScript**
+
+`packages/sdk/examples/generate-then-edit.ts`:
+
+```ts
+// Generate a document, then open its bytes, edit them and save incrementally. The edit changes
+// the Info dictionary in one transaction, and the incremental save keeps the generated bytes as
+// they are, with one revision appended.
+import { Builder, type BuilderOptions, Document, Font } from "@laminapdf/sdk";
+
+/**
+ * The generated file followed by the edit's revision. Needs `init({ text: true })`.
+ *
+ * @param options - can fix the file ID, the producer and the creation date.
+ * @param editedAt - the modification date to record, as a PDF date string.
+ */
+export function generateThenEdit(options: BuilderOptions = {}, editedAt?: string): Uint8Array<ArrayBuffer> {
+  return edit(generate(options), editedAt);
+}
+
+/** A one-page draft, saved (a new document is always saved as a full rewrite). */
+export function generate(options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const page = b.page("A4");
+  page.surface().text("Draft report", { font: Font.standard("Helvetica"), size: 20, at: [72, 96] });
+  page.finish();
+  b.metadata({ title: "Draft report" });
+  using doc = b.finish();
+  return doc.save();
+}
+
+/** Opens `bytes`, edits the Info dictionary in one transaction (which `undo` could revert) and saves incrementally. */
+function edit(bytes: Uint8Array, editedAt?: string): Uint8Array<ArrayBuffer> {
+  using doc = Document.open(bytes);
+  doc.transact((tx) => tx.setInfo({ title: "Final report", author: "Ada Lovelace" }, editedAt));
+  return doc.save({ mode: "incremental" });
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/generate_then_edit.rs`:
+
+````rust
+//! Generate a document, then open its bytes, edit them and save incrementally.
+//!
+//! The edit changes the Info dictionary with an op (undoable and serialisable), and the
+//! incremental save keeps the generated bytes as they are, with one revision appended.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example generate_then_edit -- [out-dir]   # writes <out-dir>/generate_then_edit.pdf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    BuildOptions, Builder, Document, InfoPatch, Metadata, Op, OpenOptions, PageSize, PdfDate, PointPt, Pt, SaveMode,
+    SaveOptions, SetInfo, Standard14,
+};
+
+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)?;
+    let bytes = build(BuildOptions::new(), None)?;
+    std::fs::write(out.join("generate_then_edit.pdf"), bytes)?;
+    Ok(())
+}
+
+/// The generated file followed by the edit's revision. `edited_at` is recorded as the
+/// modification date; `options` can fix the file ID, the producer and the creation date.
+pub(crate) fn build(options: BuildOptions, edited_at: Option<PdfDate>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let generated = generate(options)?;
+    edit(generated, edited_at)
+}
+
+/// A one-page draft, saved (a new document is always saved as a full rewrite).
+pub(crate) fn generate(options: BuildOptions) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut b = Builder::new(options);
+    let helvetica = b.standard_font(Standard14::Helvetica)?;
+    let mut page = b.page(PageSize::A4);
+    page.surface().text(
+        "Draft report",
+        &helvetica,
+        Pt::new(20.0),
+        PointPt::from_points(72.0, 96.0),
+    )?;
+    page.finish()?;
+    b.metadata(Metadata::default().with_title("Draft report"));
+    Ok(b.finish()?.save(&SaveOptions::new())?.bytes)
+}
+
+/// Opens `bytes`, edits the Info dictionary in one transaction (which `undo` could revert) and
+/// saves incrementally: `bytes` unchanged, then the appended revision.
+fn edit(bytes: Vec<u8>, edited_at: Option<PdfDate>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let mut doc = Document::open_bytes(bytes, OpenOptions::new())?;
+    let patch = InfoPatch::new()
+        .title(Some("Final report"))
+        .author(Some("Ada Lovelace"));
+    doc.apply(vec![Op::from(SetInfo::new(patch, edited_at))])?;
+    let options = SaveOptions::new().with_mode(SaveMode::Incremental);
+    Ok(doc.save(&options)?.bytes)
+}
+````
+
+**Result:** [generate_then_edit.pdf](https://docs.laminapdf.com/examples/pdf/generate_then_edit.pdf)
+
+The result is the draft's bytes, unchanged, followed by one revision that retitles it "Final report" and names Ada Lovelace as its author. The Result tab shows it, with a link to the PDF.
+
+## How it works
+
+- A new document has no original bytes to append to, so the draft's save is a [full rewrite](../../pages/reference/glossary.md#full-rewrite).
+- `Document.open` (`Document::open_bytes` in Rust) reads the draft. Your edits sit beside its bytes and never change them; see [How Lamina PDF thinks about a PDF](../../pages/concepts/how-lamina-thinks.md).
+- `setInfo` changes the Info dictionary: the title, author and other facts a viewer shows in a file's properties. `transact` applies it as one transaction, which `undo` reverts as a whole. In Rust, `apply` takes the list of ops as one transaction.
+- `mode: "incremental"` (`SaveMode::Incremental`) asks for an [incremental save](../../pages/reference/glossary.md#incremental-save): the draft's bytes first, then one revision with the edit.
+- `editedAt` is the modification date to record, a PDF date such as `D:20261030120000Z`. Leave it out and no date is written, because Lamina PDF never reads the clock.
+- The builder also wrote the draft's title into its XMP metadata, an XML copy of the same facts. `setInfo` leaves that copy alone, so it still says "Draft report".
+
+## What to change
+
+- **More edits in the same revision:** add them inside the callback, such as `tx.rotatePage(doc.page(0).id, 90)` (`RotatePage` in Rust). See [Edit a PDF](../../pages/guides/edit-a-pdf.md).
+- **Removing an entry:** pass `null` for it, as in `{ author: null }` (`.author(None)` in Rust).
+- **Your own file:** open its bytes in place of the draft's. A signed, repaired or encrypted file limits how it saves; [Save a PDF](../../pages/guides/save-a-pdf.md#when-a-file-refuses-a-save) lists the cases.
+- **A whole new file:** pass `mode: "fullRewrite"` (`SaveMode::FullRewrite`), or leave `mode` out and let the save choose. See [Choose a save mode](../../pages/guides/save-a-pdf.md#choose-a-save-mode).
+- **Edits stored as JSON:** replay a saved log with `doc.applyLog({ v: 1, ops })` (`apply_log` in Rust), as [Edit a PDF](../../pages/guides/edit-a-pdf.md#replay-edits-stored-as-json) shows.
+
+Next: [a PDF/UA report](../../pages/recipes/pdf-ua-report.md), an accessible report checked as it's built.

package/docs/pages/recipes/hello.md

@@ -0,0 +1,101 @@
+---
+title: "Hello, world"
+description: "One A4 page with a line of text in a standard 14 font, the smallest PDF Lamina PDF writes, in TypeScript and Rust."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/hello/"
+---
+
+# Hello, world
+
+One A4 page with a line of text in a standard 14 font, the smallest PDF Lamina PDF writes, in TypeScript and Rust.
+
+You'll make the smallest PDF Lamina PDF writes: one A4 page that says "Hello, world!" in Helvetica. Start from it to check that a new setup works, or as the skeleton of a document of your own.
+
+The function builds the page and returns the PDF's bytes. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+**TypeScript**
+
+`packages/sdk/examples/hello.ts`:
+
+```ts
+// The smallest document: one A4 page with a line of text in a standard 14 font.
+import { Builder, type BuilderOptions, Font } from "@laminapdf/sdk";
+
+/**
+ * The document's bytes. Needs `init({ text: true })`.
+ *
+ * @param options - can fix the file ID, the producer and the creation date, so that the same
+ *   input gives the same bytes on every run.
+ */
+export function hello(options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  using b = new Builder(options);
+  const page = b.page("A4");
+  // Page space: points from the top-left corner, y down; `at[1]` is the text's baseline.
+  page.surface().text("Hello, world!", { font: Font.standard("Helvetica"), size: 24, at: [72, 96] });
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/hello.rs`:
+
+````rust
+//! The smallest document: one A4 page with a line of text in a standard 14 font.
+//!
+//! ```sh
+//! cargo run -p laminapdf --example hello -- [out-dir]   # writes <out-dir>/hello.pdf (default target/examples-out)
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{BuildOptions, Builder, PageSize, PointPt, Pt, SaveOptions, Standard14};
+
+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("hello.pdf"), build(BuildOptions::new())?)?;
+    Ok(())
+}
+
+/// The document's bytes. `options` can fix the file ID, the producer and the creation date, so
+/// that the same input gives the same bytes on every run.
+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)?;
+    let mut page = b.page(PageSize::A4);
+    // Page space: points from the top-left corner, y down; `y` is the text's baseline.
+    page.surface().text(
+        "Hello, world!",
+        &helvetica,
+        Pt::new(24.0),
+        PointPt::from_points(72.0, 96.0),
+    )?;
+    page.finish()?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+````
+
+**Result:** [hello.pdf](https://docs.laminapdf.com/examples/pdf/hello.pdf)
+
+The result is one page with the line near its top-left corner. The Result tab shows it, with a link to the PDF.
+
+## How it works
+
+- The builder makes an A4 page, and the page's surface is what you draw on.
+- `at` is in points from the top-left corner of the page, with y going down. Its second number is the text's baseline. See [Pages and coordinates](../../pages/concepts/pages-and-coordinates.md).
+- Helvetica is one of the [standard 14 fonts](../../pages/reference/glossary.md#standard-14-fonts), which every PDF viewer has, so the PDF embeds no font.
+- Finishing the builder gives a document, and saving the document gives its bytes. `using` in TypeScript frees both as soon as the function ends.
+
+## What to change
+
+- **The text and where it goes:** change the string, the size and `at`.
+- **The page size:** name another size, such as `"Letter"`, or pass `[width, height]` in points.
+- **The font:** for characters outside the standard 14 fonts' Latin set, embed a font. See [Text and fonts](../../pages/guides/fonts-and-text.md).
+- **A file ID or a date of your own:** pass them in the builder's options. Without them, the file ID is a hash of the content and the PDF has no creation date, so the same code writes the same bytes on every run.
+
+Next: [an invoice](../../pages/recipes/invoice.md), with an embedded font and a table of line items.