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

package/docs/pages/quick-start/rust.md

@@ -1,7 +1,7 @@
 ---
 title: "Rust"
 description: "Generate a PDF with the Lamina PDF crate."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/quick-start/rust/"
 ---
 
@@ -9,7 +9,9 @@ url: "https://docs.laminapdf.com/quick-start/rust/"
 
 Generate a PDF with the Lamina PDF crate.
 
-The `laminapdf` crate is the one to depend on: it wraps Lamina PDF's core crates in one API. Add it with `cargo add laminapdf@=0.2.0-alpha.3`, then build a document. [Install](../../pages/install.md#rust-laminapdf) explains the version. This is the `hello` example, which is tested on every change:
+The `laminapdf` crate is the one to depend on: it wraps Lamina PDF's core crates in one API. Add it with `cargo add laminapdf@=0.2.0-alpha.4`, then build a document. [Install](../../pages/install.md#rust-laminapdf) explains the version. This is the `hello` example, which is tested on every change:
+
+**Rust**
 
 `crates/laminapdf/examples/hello.rs`:
 
@@ -51,6 +53,8 @@ pub(crate) fn build(options: BuildOptions) -> Result<Vec<u8>, Box<dyn Error>> {
 }
 ````
 
+**Result:** [hello.pdf](https://docs.laminapdf.com/examples/pdf/hello.pdf)
+
 To run it, save it as `src/main.rs` in a project that depends on `laminapdf`, then run `cargo run`. It writes `target/examples-out/hello.pdf`, or `hello.pdf` in the folder you pass: `cargo run -- out`.
 
 - **Same input, same bytes:** `build` takes `BuildOptions`: fix the file ID, the producer and the creation date in them, and the output never changes; see [how Lamina PDF thinks about a PDF](../../pages/concepts/how-lamina-thinks.md#same-input-same-bytes).

package/docs/pages/quick-start/workers.md

@@ -1,7 +1,7 @@
 ---
 title: "Cloudflare Workers"
 description: "Generate PDFs per request in a Cloudflare Worker."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/quick-start/workers/"
 ---
 
@@ -131,7 +131,7 @@ declare module "*.otf" {
 }
 ```
 
-To run it, install `@laminapdf/sdk` and `wrangler` in the Cloudflare Worker's folder (`npm install @laminapdf/sdk@0.2.0-alpha.3 wrangler`), put a copy of [Noto Sans](https://fonts.google.com/noto/specimen/Noto+Sans) at `src/fonts/NotoSans-Regular.ttf`, and run `npx wrangler dev`.
+To run it, install `@laminapdf/sdk` and `wrangler` in the Cloudflare Worker's folder (`npm install @laminapdf/sdk@0.2.0-alpha.4 wrangler`), put a copy of [Noto Sans](https://fonts.google.com/noto/specimen/Noto+Sans) at `src/fonts/NotoSans-Regular.ttf`, and run `npx wrangler dev`.
 
 - **Errors the caller caused** become a `400` with the error's JSON: a name the font can't draw (`missing-glyph`, `encoding-full`). Anything else, such as a broken font file, stays a `500`. See [Errors and warnings](../../pages/concepts/errors-and-warnings.md).
 - **Memory:** the letter frees its builder and document as soon as the bytes are saved, because one isolate serves many requests.

package/docs/pages/recipes/cloudflare-worker.md

@@ -1,7 +1,7 @@
 ---
 title: "A Cloudflare Worker"
 description: "A Cloudflare Worker that returns a one-page letter per request, in a standard 14 font or a bundled one, and a 400 for a name the font can't draw."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/cloudflare-worker/"
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 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.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/extract-markdown/"
 ---
 
@@ -13,7 +13,9 @@ You'll turn a PDF into three outputs an LLM or a search index can use: Markdown
 
 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:
 
-<TabItem label="TypeScript">`packages/sdk/examples/extract-markdown.ts`:
+**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,
@@ -42,8 +44,11 @@ export function extractForAnLlm(bytes: Uint8Array): ForAnLlm {
   const json = doc.extract({ format: "json", pageMarkers: true, chunk: { maxTokens: 400 } });
   return { markdown, json, chunks: json.chunks ?? [] };
 }
-```</TabItem>
-<TabItem label="Rust">`crates/laminapdf/examples/extract_markdown.rs`:
+```
+
+**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
@@ -89,15 +94,45 @@ pub(crate) fn write_outputs(bytes: &[u8], out: &Path, stem: &str) -> Result<(),
     std::fs::write(out.join(format!("{stem}.json")), json)?;
     Ok(())
 }
-````</TabItem>
+````
+
+**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.
-- 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 and text too small to read. The JSON lists each such run under `dropped`, with the reason and how many characters it held.
+- 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.
@@ -109,6 +144,9 @@ Run the Rust program on any PDF: `cargo run -p laminapdf --example extract_markd
 - **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

@@ -1,7 +1,7 @@
 ---
 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.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/generate-then-edit/"
 ---
 
@@ -13,7 +13,9 @@ You'll generate a one-page draft report, then open its bytes, retitle it and sav
 
 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:
 
-<TabItem label="TypeScript">`packages/sdk/examples/generate-then-edit.ts`:
+**TypeScript**
+
+`packages/sdk/examples/generate-then-edit.ts`:
 
 ```ts
 // Generate a document, then open its bytes, edit them and save incrementally. The edit changes
@@ -48,8 +50,11 @@ function edit(bytes: Uint8Array, editedAt?: string): Uint8Array<ArrayBuffer> {
   doc.transact((tx) => tx.setInfo({ title: "Final report", author: "Ada Lovelace" }, editedAt));
   return doc.save({ mode: "incremental" });
 }
-```</TabItem>
-<TabItem label="Rust">`crates/laminapdf/examples/generate_then_edit.rs`:
+```
+
+**Rust**
+
+`crates/laminapdf/examples/generate_then_edit.rs`:
 
 ````rust
 //! Generate a document, then open its bytes, edit them and save incrementally.
@@ -111,9 +116,11 @@ fn edit(bytes: Vec<u8>, edited_at: Option<PdfDate>) -> Result<Vec<u8>, Box<dyn E
     let options = SaveOptions::new().with_mode(SaveMode::Incremental);
     Ok(doc.save(&options)?.bytes)
 }
-````</TabItem>
+````
+
+**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: [open the reference 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
 

package/docs/pages/recipes/hello.md

@@ -1,7 +1,7 @@
 ---
 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.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/hello/"
 ---
 
@@ -13,7 +13,9 @@ You'll make the smallest PDF Lamina PDF writes: one A4 page that says "Hello, wo
 
 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:
 
-<TabItem label="TypeScript">`packages/sdk/examples/hello.ts`:
+**TypeScript**
+
+`packages/sdk/examples/hello.ts`:
 
 ```ts
 // The smallest document: one A4 page with a line of text in a standard 14 font.
@@ -34,8 +36,11 @@ export function hello(options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
   using doc = b.finish();
   return doc.save();
 }
-```</TabItem>
-<TabItem label="Rust">`crates/laminapdf/examples/hello.rs`:
+```
+
+**Rust**
+
+`crates/laminapdf/examples/hello.rs`:
 
 ````rust
 //! The smallest document: one A4 page with a line of text in a standard 14 font.
@@ -73,9 +78,11 @@ pub(crate) fn build(options: BuildOptions) -> Result<Vec<u8>, Box<dyn Error>> {
     let mut doc = b.finish()?;
     Ok(doc.save(&SaveOptions::new())?.bytes)
 }
-````</TabItem>
+````
+
+**Result:** [hello.pdf](https://docs.laminapdf.com/examples/pdf/hello.pdf)
 
-The result is one page with the line near its top-left corner: [open the reference 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
 

package/docs/pages/recipes/images-and-vectors.md

@@ -1,7 +1,7 @@
 ---
 title: "Images and vectors"
 description: "Shapes, a dashed curve, gray, RGB, CMYK and hex colour, transparency, a blend mode, a clip, a rotation, a JPEG and an RGBA image on one page."
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/images-and-vectors/"
 ---
 
@@ -13,7 +13,9 @@ You'll draw shapes and images on one A4 page: a rectangle, a circle, a dashed cu
 
 The function takes a JPEG's bytes, draws the page and returns the PDF's bytes. It draws no text, so in TypeScript it needs only the base module, `init()`. Both languages write the same bytes:
 
-<TabItem label="TypeScript">`packages/sdk/examples/images-and-vectors.ts`:
+**TypeScript**
+
+`packages/sdk/examples/images-and-vectors.ts`:
 
 ```ts
 // Images and vector graphics on one A4 page. It draws shapes and a dashed Bézier curve in gray,
@@ -84,8 +86,11 @@ function images(s: Surface, photo: Image, glow: Image): void {
   s.save().transform(Matrix.after(Matrix.translate(150, 520), Matrix.rotate(30)));
   s.image(glow, [-60, -60, 120, 120]).restore();
 }
-```</TabItem>
-<TabItem label="Rust">`crates/laminapdf/examples/images_and_vectors.rs`:
+```
+
+**Rust**
+
+`crates/laminapdf/examples/images_and_vectors.rs`:
 
 ````rust
 //! Images and vector graphics on one A4 page.
@@ -185,9 +190,11 @@ fn images(s: &mut Surface, photo: &Image, glow: &Image) {
     s.save().transform(placement);
     s.image(glow, RectPt::from_points(-60.0, -60.0, 120.0, 120.0)).restore();
 }
-````</TabItem>
+````
+
+**Result:** [images_and_vectors.pdf](https://docs.laminapdf.com/examples/pdf/images_and_vectors.pdf)
 
-The result is one A4 page with every shape and both images: [open the reference PDF](https://docs.laminapdf.com/examples/pdf/images_and_vectors.pdf).
+The result is one A4 page with every shape and both images. The Result tab shows it, with a link to the PDF.
 
 ## How it works
 

package/docs/pages/recipes/invoice.md

@@ -1,7 +1,7 @@
 ---
 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"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/invoice/"
 ---
 
@@ -13,7 +13,9 @@ You'll make a one-page invoice: a heading, an address, a table of line items wit
 
 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`:
+**TypeScript**
+
+`packages/sdk/examples/invoice.ts`:
 
 ```ts
 // An invoice that screen readers can follow, with an embedded font and a table of line items.
@@ -101,8 +103,11 @@ function rowBaseline(row: number): number {
 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**
+
+`crates/laminapdf/examples/invoice.rs`:
 
 ```rust
 //! An invoice that screen readers can follow, with an embedded font and a table of line items.
@@ -205,9 +210,11 @@ fn right_aligned(s: &mut Surface, font: &FontHandle, text: &str, area: RectPt) -
     let right = TextBoxOptions::new().with_align(Alignment::End);
     s.text_box(text, font, BODY, area, &right).map(|_| ())
 }
-```</TabItem>
+```
+
+**Result:** [invoice.pdf](https://docs.laminapdf.com/examples/pdf/invoice.pdf)
 
-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).
+The result is one A4 page with its body set in Noto Sans. The Result tab shows it, with a link to the PDF.
 
 ## How it works
 

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

@@ -1,7 +1,7 @@
 ---
 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"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/recipes/links-and-outlines/"
 ---
 
@@ -13,7 +13,9 @@ You'll make four A5 pages joined by links to a website and between pages, an out
 
 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`:
+**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
@@ -93,8 +95,11 @@ function navigation(b: Builder): void {
     { start: 2, style: "decimal" },
   ]).viewerPreferences({ pageMode: "outlines" });
 }
-```</TabItem>
-<TabItem label="Rust">`crates/laminapdf/examples/links_and_outlines.rs`:
+```
+
+**Rust**
+
+`crates/laminapdf/examples/links_and_outlines.rs`:
 
 ````rust
 //! Links and outlines: four A5 pages joined by links, bookmarks and page labels.
@@ -192,9 +197,11 @@ fn navigation(b: &mut Builder) -> Result<(), Box<dyn Error>> {
     .viewer_preferences(ViewerPreferences::default().with_page_mode(PageMode::Outlines));
     Ok(())
 }
-````</TabItem>
+````
+
+**Result:** [links_and_outlines.pdf](https://docs.laminapdf.com/examples/pdf/links_and_outlines.pdf)
 
-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).
+The result is four A5 pages with an outline and page labels. The Result tab shows it, with a link to the PDF.
 
 ## How it works