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

package/docs/errors/xobject-cycle.md

@@ -0,0 +1,36 @@
+---
+title: "xobject-cycle"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/xobject-cycle/"
+---
+
+# xobject-cycle
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A Form XObject draws itself, directly or through other forms; the inner `Do` was skipped.
+
+## Why
+
+A malformed or hostile file: forms that draw each other without end would never finish.
+
+## How to fix
+
+Nothing to do.
+
+## Example
+
+```text
+8 0 obj << /Subtype /Form /Resources << /XObject << /Me 8 0 R >> >> >> stream /Me Do endstream
+```
+
+The form draws itself: the inner `/Me Do` is skipped once Lamina PDF sees form 8 a second time.
+
+## Data fields
+
+- `object`: the form reached again.
+
+The `location` is `object` (the form reached again).

package/docs/errors/xref-repaired.md

@@ -0,0 +1,36 @@
+---
+title: "xref-repaired"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/xref-repaired/"
+---
+
+# xref-repaired
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+The stored cross-reference data was unusable and was rebuilt by scanning the file.
+
+## Why
+
+Edited, truncated or concatenated files often have stale offsets.
+
+## How to fix
+
+Nothing, if the result is right. Incremental saves refuse a repaired base (`repaired-base`); save in full instead.
+
+## Example
+
+```text
+startxref
+123456
+%%EOF
+```
+
+`startxref` points past the end of a file that was truncated and re-padded. Lamina PDF scans the file for `n g obj` headers, rebuilds the table, raises `xref-repaired` and opens normally. `save(SaveMode::Incremental)` is then refused with [`repaired-base`](repaired-base.md); `SaveMode::Auto` rewrites the file.
+
+## Data fields
+
+None.

package/docs/errors/xrefstm-ignored.md

@@ -0,0 +1,34 @@
+---
+title: "xrefstm-ignored"
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/reference/codes/xrefstm-ignored/"
+---
+
+# xrefstm-ignored
+
+- Type: warning
+- Kind: `input` (the input is malformed beyond what tolerance repairs)
+
+## What happened
+
+A hybrid file's `/XRefStm` could not be read and was ignored.
+
+## Why
+
+Hybrid files carry a classic xref table for old readers and an xref stream for objects in object streams. An editor that moved bytes without updating `/XRefStm`, or a damaged stream, leaves the stream unreadable.
+
+## How to fix
+
+Nothing; the classic table is used.
+
+## Example
+
+```text
+trailer << /Size 40 /Root 1 0 R /XRefStm 99999 >>
+```
+
+A hybrid-reference file (ISO 32000-2 §7.5.8.4) points `/XRefStm` at an offset with no stream. Lamina PDF ignores it and reads the classic table; objects only the stream listed may be missing.
+
+## Data fields
+
+`offset` (where `/XRefStm` points).

package/docs/llms.txt

@@ -0,0 +1,88 @@
+# Lamina PDF
+
+> Lamina PDF creates, reads, edits and saves PDF files from TypeScript and Rust: one Rust core, run as WebAssembly in browsers, Node, Deno, Bun and Cloudflare Workers (`@laminapdf/sdk`), or natively from the `laminapdf` crate. Positions are top-left points of the displayed page and page indexes start at 0; every error has a stable code with its own page.
+
+These docs describe version 0.2.0-alpha.3, the version of this package. The same docs are online at https://docs.laminapdf.com/llms.txt.
+
+- [Using Lamina PDF with coding agents](AGENTS.md)
+- [What old names became](renames.json)
+
+## Start here
+
+- [Lamina PDF](pages/index.md): Create, read, edit and save PDFs from Rust and TypeScript, with one Rust core that runs natively and as WebAssembly.
+- [Install](pages/install.md): Install Lamina PDF from npm or crates.io, and find every published package.
+- [Your first PDF](pages/start/first-pdf.md): Write hello.pdf from Node in five minutes.
+- [Use Lamina PDF with coding agents](pages/start/coding-agents.md): Point a coding agent at the docs inside the installed package, so its answers match the version you use.
+
+## Your runtime
+
+- [Browser and bundlers](pages/quick-start/browser.md): Load @laminapdf/sdk in a web page through Vite or another bundler.
+- [Node](pages/quick-start/node.md): Generate a PDF from Node with @laminapdf/sdk.
+- [Deno](pages/quick-start/deno.md): Use @laminapdf/sdk in Deno.
+- [Bun](pages/quick-start/bun.md): Use @laminapdf/sdk in Bun.
+- [Cloudflare Workers](pages/quick-start/workers.md): Generate PDFs per request in a Cloudflare Worker.
+- [Rust](pages/quick-start/rust.md): Generate a PDF with the Lamina PDF crate.
+
+## Concepts
+
+- [How Lamina PDF thinks about a PDF](pages/concepts/how-lamina-thinks.md): Bytes in and out, the same bytes every time, edits kept apart from the opened file, two ways to save, memory you free, three JavaScript modules.
+- [Pages and coordinates](pages/concepts/pages-and-coordinates.md): Points from the top-left corner of the page as it's displayed, y going down, and pages numbered from 0.
+- [Errors and warnings](pages/concepts/errors-and-warnings.md): One coded error shape on every surface, and warnings for what Lamina PDF repaired.
+- [What Lamina PDF writes and what it borrows](pages/concepts/dependencies.md): Lamina PDF writes the parts that decide a PDF's bytes, borrows the rest from permissive projects, and pins and checks everything it borrows.
+
+## Create PDFs
+
+- [Text and fonts](pages/guides/fonts-and-text.md): Draw text in any script with your own fonts or the standard 14, one line at a time or as a paragraph that wraps in a box.
+- [Shapes, colour and images](pages/guides/images-and-vectors.md): Draw lines, shapes and images on a page, in any colour, with transparency, clipping and transforms.
+- [Links, outlines and metadata](pages/guides/links-outlines-and-metadata.md): Add links, named destinations, an outline, page labels, viewer preferences and metadata to a document.
+- [Accessible PDFs](pages/guides/accessible-pdfs.md): Build PDF/UA-1 documents that screen readers can follow, with every machine-checkable rule checked when the builder finishes.
+- [Archival PDFs](pages/guides/archival-pdfs.md): Build PDF/A-2b, PDF/A-2u and PDF/A-3b documents that look the same in years to come, and attach files such as an e-invoice's XML.
+
+## Read and edit PDFs
+
+- [Edit a PDF](pages/guides/edit-a-pdf.md): Change an existing PDF in transactions you can undo, and replay edits stored as JSON.
+- [Save a PDF](pages/guides/save-a-pdf.md): Save edits as a revision appended to the original bytes or as a whole new file, and see when a file refuses a save.
+- [Open password-protected files](pages/guides/password-protected-files.md): Open PDFs that need a password, ask again when it is missing or wrong, and save them afterwards.
+- [Open files you don't trust](pages/guides/untrusted-files.md): Cap how much work an uploaded PDF can make Lamina PDF do, and refuse damaged files with strict mode.
+
+## Production
+
+- [Keep the page responsive](pages/guides/keep-the-page-responsive.md): Run Lamina PDF in a Web Worker with @laminapdf/sdk/worker, so a large file never freezes the page.
+
+## Recipes
+
+- [Recipes](pages/recipes.md): Complete Lamina PDF programs, from one page of text to an archived invoice, each with its code and the PDF it writes.
+- [Hello, world](pages/recipes/hello.md): One A4 page with a line of text in a standard 14 font, the smallest PDF Lamina PDF writes, in TypeScript and Rust.
+- [An invoice](pages/recipes/invoice.md): 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.
+- [Multilingual text](pages/recipes/multilingual.md): Latin, Arabic, Devanagari, Hebrew and Chinese on one page, each in its own embedded font, as a shaped line and a wrapped paragraph.
+- [Images and vectors](pages/recipes/images-and-vectors.md): 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.
+- [Links and outlines](pages/recipes/links-and-outlines.md): 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.
+- [Generate, then edit](pages/recipes/generate-then-edit.md): Build a one-page draft, open its bytes, retitle it in one transaction and save the edit as a revision after the original bytes.
+- [Extract text for an LLM](pages/recipes/extract-markdown.md): Turn a PDF into Markdown in reading order, JSON with a box for every block, and chunks sized for retrieval, in TypeScript and Rust.
+- [A PDF/UA report](pages/recipes/pdf-ua-report.md): A one-page sales report a screen reader can follow, with headings, a table, a described chart and a link, checked against PDF/UA-1 as it's built.
+- [A PDF/A archive](pages/recipes/pdf-a-archive.md): An order confirmation for long-term archiving, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1, with an embedded font and a photo.
+- [A PDF/A-3 invoice with XML](pages/recipes/pdf-a3-invoice-with-xml.md): A PDF/A-3b invoice that carries the same invoice as an attached XML file, for people to read and for software to process.
+- [A 100-page report](pages/recipes/report.md): A 100-page A4 report with two embedded fonts and a table on every page, the document Lamina PDF times in each JavaScript runtime.
+- [Open someone else's file](pages/recipes/open-untrusted.md): Open an uploaded PDF with an optional password and tighter limits, and get its page count and warnings, or the error, back as a value.
+- [Save in a Web Worker](pages/recipes/web-worker-client.md): Open and save a PDF in a Web Worker, so a large file never freezes the page, with progress as it saves and a signal that stops the work.
+- [A Cloudflare Worker](pages/recipes/cloudflare-worker.md): 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.
+
+## Troubleshooting
+
+- [Troubleshooting](pages/troubleshooting.md): The problems people hit with Lamina PDF, from a missing init() to a signed file that won't save, with the cause and the fix of each.
+
+## Reference
+
+- [Rust API (rustdoc)](pages/reference/rust.md): Where to read the API documentation of the Lamina PDF crates.
+- [Error and warning codes](pages/reference/codes.md): Every code Lamina PDF raises, generated from fixtures/codes.json when the site is built.
+- [Stability policy](pages/reference/stability.md): What a Lamina PDF version number promises, and what stays the same in every version.
+- [Changelog](pages/reference/changelog.md): What changed in each Lamina PDF release, newest first.
+- [Glossary](pages/reference/glossary.md): The PDF and Lamina PDF terms the docs use, each in a sentence or two.
+
+## API reference
+
+- [@laminapdf/sdk](api/README.md)
+
+## Optional
+
+- [Error and warning codes](errors/README.md)

package/docs/pages/concepts/dependencies.md

@@ -0,0 +1,44 @@
+---
+title: "What Lamina PDF writes and what it borrows"
+description: "Lamina PDF writes the parts that decide a PDF's bytes, borrows the rest from permissive projects, and pins and checks everything it borrows."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/concepts/dependencies/"
+---
+
+# What Lamina PDF writes and what it borrows
+
+Lamina PDF writes the parts that decide a PDF's bytes, borrows the rest from permissive projects, and pins and checks everything it borrows.
+
+Add `@laminapdf/viewer` to your app, and it downloads about 2 MB of WebAssembly from a project called EmbedPDF. That WebAssembly is PDFium, the C++ engine behind Chrome's PDF viewer. You may wonder why a Rust library ships someone else's C++, and what else comes along with it. Lamina PDF follows one rule: it writes the parts that decide what your PDF contains. It borrows the rest only from permissively licensed projects that do the job better, and it pins and checks every borrowed piece.
+
+## Lamina PDF writes the parts that decide your bytes
+
+Lamina PDF's own Rust code reads, edits and saves your PDFs. Those parts take files from strangers, and they decide every byte of the file you save. A bug there corrupts documents or breaks signatures, so Lamina PDF owns them. Rust also keeps that code memory-safe while it reads damaged or hostile files. And because Lamina PDF wrote it, the same input gives the same bytes in a browser, on a server and inside a Cloudflare Worker.
+
+## It borrows the work others already do well
+
+Fonts and text shaping are deep problems with good open-source answers, so Lamina PDF reuses them. `skrifa` reads font files, `subsetter` cuts them down to the glyphs you use, and HarfRust shapes Arabic, Hindi and other scripts. ICU4X finds line breaks, and `pdf-writer` writes PDF syntax. Each one is permissively licensed Rust that compiles to WebAssembly. Lamina PDF measured krilla, a complete PDF generator built on the same crates. But krilla can't add content to a file you opened, so Lamina PDF builds on the crates beneath it.
+
+## Drawing pages is the one job it hands to PDFium
+
+Lamina PDF hands one big job to another project: turning pages into pixels. Real-world PDFs often break the specification, and PDFium draws them for everyone who opens a PDF in Chrome. Lamina PDF measured the alternative, hayro, a renderer written in Rust. It drew 91% of 2,196 test pages the same as PDFium or close to it, and most of the rest went wrong on fonts and annotations. A viewer that becomes an editor needs that fidelity from the start, so PDFium draws the pages. `@embedpdf/pdfium` is PDFium compiled to WebAssembly.
+
+## PDFium only draws, and only in a Web Worker
+
+PDFium is C++ reading files you didn't write, so Lamina PDF keeps it at arm's length. The viewer runs it inside a Web Worker, away from your page. PDFium never changes the document either: every edit goes through Lamina PDF, which also writes the saved file. Text, selection and links come from Lamina PDF's own reading of the file, never from the renderer. Lamina PDF also checks that the two agree: its tests compare each page's size and every character's position with PDFium's.
+
+## You pay for PDFium only when you show pages
+
+`@laminapdf/sdk`, the package that creates, reads and edits PDFs, depends only on `@laminapdf/wasm`, Lamina PDF's own WebAssembly. PDFium comes only with `@laminapdf/render-pdfium` and the viewer built on it. For pages as pixels on a server or in a Cloudflare Worker, `@laminapdf/render-hayro` is the lighter choice: pure Rust, with no C++, and a smaller download than PDFium. Every night, Lamina PDF's tests draw thousands of pages with both renderers, so hayro can take over once it matches PDFium.
+
+## Every dependency is permissively licensed
+
+Lamina PDF is `MIT OR Apache-2.0`, so you can use it in a closed product or a paid service. That promise only holds if every dependency allows the same. So Lamina PDF accepts no GPL, AGPL or LGPL code in anything it ships, and a licence check enforces the rule on every change. MuPDF is a fine PDF engine, but it is AGPL, so Lamina PDF never uses it, in any form. Copyleft tools such as veraPDF run as separate programs in Lamina PDF's tests and are never shipped.
+
+## Everything borrowed is pinned and checked
+
+A dependency can change under you, so Lamina PDF's lockfiles pin every one to an exact version. For PDFium, Lamina PDF goes further: the build checks the SHA-256 of `pdfium.wasm`, and any other file fails the build. `@embedpdf/pdfium` ships no notices for the libraries compiled into it, such as libpng, zlib and FreeType. So `@laminapdf/render-pdfium` includes a third-party notices file, and an app that bundles it ships that file too. An update to PDFium arrives as its own reviewed change, and the next release picks up its security fixes.
+
+## What this means for your app
+
+You can build Lamina PDF into closed software, and `@laminapdf/sdk` brings no third-party engine with it. Add the viewer when you need to show pages, and ship PDFium's notices file with it. Next, see [how Lamina PDF thinks about a PDF](../../pages/concepts/how-lamina-thinks.md), or start with [your first PDF](../../pages/start/first-pdf.md).

package/docs/pages/concepts/errors-and-warnings.md

@@ -0,0 +1,64 @@
+---
+title: "Errors and warnings"
+description: "One coded error shape on every surface, and warnings for what Lamina PDF repaired."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/concepts/errors-and-warnings/"
+---
+
+# Errors and warnings
+
+One coded error shape on every surface, and warnings for what Lamina PDF repaired.
+
+Real PDFs are often damaged, so Lamina PDF separates a call that failed from one that worked around a problem. An error stops the call. A warning lets it finish and tells you what was repaired, dropped or approximated. Both carry a stable code your program can branch on.
+
+## Errors stop the call
+
+In TypeScript an error is a `LaminaPdfError`, and in Rust it's a `laminapdf::Error`. Branch on its `code`, never on its `message`: `isLaminaPdfError(e, "wrong-password")` checks the code and narrows the type in one step.
+
+## Warnings say what was repaired
+
+A warning means the call went ahead, but Lamina PDF had to repair, drop or approximate something in the file. Read them with `doc.warnings` in TypeScript or `doc.warnings()` in Rust. Show them to the user when the difference matters, such as a page that may not look the way its author intended.
+
+## Every surface has the same fields
+
+Errors and warnings have the same fields in TypeScript and Rust: `code`, `kind`, `message`, `hint`, `location`, `data` and `docsUrl`. `toJSON()` in TypeScript gives the same object as `serde` does in Rust, so a server and a browser can pass them to each other unchanged.
+
+- **`kind` sorts errors by who can fix them**, such as `input`, `limit`, `usage`, `state` or `io`. For example, a server returns a 4xx status for `input` and `limit` and a 5xx for the rest, as the [Cloudflare Workers quick start](../../pages/quick-start/workers.md) does.
+- **Text from the document is untrusted**, so it never appears in `message` or `hint`. It goes only in `data`, where you can escape it before you show it.
+
+This example opens someone else's file and returns the error's code and hint as a value, instead of letting the error escape:
+
+`packages/sdk/examples/open-untrusted.ts`:
+
+```ts
+// Open bytes from someone else: an optional password, tighter limits than the defaults, and the
+// outcome as a value rather than an exception. The example writes nothing: it returns what it found.
+import { Document, isLaminaPdfError } from "@laminapdf/sdk";
+
+const MiB = 1024 * 1024;
+/** Limits for an upload endpoint: each decoded stream, and all of them together. */
+const LIMITS = { maxStreamDecoded: 16 * MiB, maxDecodedTotal: 64 * MiB } as const;
+
+/** What opening a file gave: its page count and warning codes, or why it didn't open. */
+export type Opened =
+  | { readonly ok: true; readonly pages: number; readonly warnings: readonly string[] }
+  | { readonly ok: false; readonly code: string; readonly hint: string | undefined };
+
+/** Opens `bytes`, with `password` if the file needs one, under {@link LIMITS}. Needs `init()`. */
+export function openUntrusted(bytes: Uint8Array, password?: string): Opened {
+  try {
+    using doc = Document.open(bytes, { ...(password === undefined ? {} : { password }), limits: LIMITS });
+    // Repairs and dropped values are warnings: the file opened, but not exactly as written.
+    return { ok: true, pages: doc.pageCount, warnings: doc.warnings.map((w) => w.code) };
+  } catch (e) {
+    // `password-required`, `wrong-password`, `not-pdf`, `limit-exceeded`, …: a coded error whose
+    // message and hint never contain text from the file. Anything else is a bug: let it throw.
+    if (isLaminaPdfError(e)) return { ok: false, code: e.code, hint: e.hint };
+    throw e;
+  }
+}
+```
+
+The [error and warning codes](../../errors/README.md) list every code with its kind, a summary and a hint.
+
+Next: make a PDF with [text and fonts](../../pages/guides/fonts-and-text.md).

package/docs/pages/concepts/how-lamina-thinks.md

@@ -0,0 +1,86 @@
+---
+title: "How Lamina PDF thinks about a PDF"
+description: "Bytes in and out, the same bytes every time, edits kept apart from the opened file, two ways to save, memory you free, three JavaScript modules."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/concepts/how-lamina-thinks/"
+---
+
+# How Lamina PDF thinks about a PDF
+
+Bytes in and out, the same bytes every time, edits kept apart from the opened file, two ways to save, memory you free, three JavaScript modules.
+
+The rest of the docs build on six ideas. The first two follow from one choice: Lamina PDF treats a PDF as bytes, which you give it and it gives back.
+
+## Bytes in, bytes out
+
+Lamina PDF's core never touches the file system or the network, and it never reads the clock. Your app reads the file, hands Lamina PDF the bytes and stores whatever comes back. The only fetches are the ones you ask for, such as opening a remote file by range requests. That's why the same code runs in a browser, on a server and inside a Cloudflare Worker.
+
+## Same input, same bytes
+
+Because Lamina PDF reads no clock, you pass in dates and file IDs yourself. It then writes the same bytes for the same input, on every run and every platform, so you can test, cache and compare its output byte for byte.
+
+## The file you opened never changes
+
+When you open a document, Lamina PDF keeps its bytes exactly as they were. Every edit goes into an [overlay](../../pages/reference/glossary.md#overlay) on top of them. Reading the document reads the overlay first, so you see your edits; undo and redo move through them.
+
+## Two ways to save
+
+A save writes the overlay out in one of two ways:
+
+- **[Incremental save](../../pages/reference/glossary.md#incremental-save):** the original bytes, unchanged, followed by a new revision that holds your edits. Signatures over the original stay valid.
+- **[Full rewrite](../../pages/reference/glossary.md#full-rewrite):** the whole file written again, smaller and tidier, but no longer the original bytes.
+
+The default, `auto`, saves incrementally when it can. A signed file saves only incrementally, and a save fails if your edits break its signatures, unless you pass `invalidateSignatures: true`. [Save a PDF](../../pages/guides/save-a-pdf.md) has the details.
+
+This example builds a document, opens its bytes, changes the title and saves incrementally. The saved file starts with the original bytes:
+
+`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" });
+}
+```
+
+## You free what you create
+
+In JavaScript, documents and builders live in WebAssembly memory. The garbage collector frees them eventually, but late, so free each one when you're done: `using doc = …` frees it at the end of the block, and `doc.free()` frees it at once. A short script can skip this, but a long-running server shouldn't.
+
+## Three modules in JavaScript
+
+In JavaScript, Lamina PDF is WebAssembly, split into three modules so a page downloads only what it uses:
+
+- **Base:** open, read, edit and save; vector and image pages.
+- **Extract:** everything in base, plus text extraction.
+- **Text:** everything in base, plus fonts, shaped text and extraction.
+
+`init()` loads the base module, and `init({ text: true })` or `init({ extract: true })` loads one of the others. Call `loadText()` or `loadExtract()` to add a module later, when a page first needs it. Rust has one crate, with features instead.

package/docs/pages/concepts/pages-and-coordinates.md

@@ -0,0 +1,67 @@
+---
+title: "Pages and coordinates"
+description: "Points from the top-left corner of the page as it's displayed, y going down, and pages numbered from 0."
+version: "0.2.0-alpha.3"
+url: "https://docs.laminapdf.com/concepts/pages-and-coordinates/"
+---
+
+# Pages and coordinates
+
+Points from the top-left corner of the page as it's displayed, y going down, and pages numbered from 0.
+
+Every position you pass Lamina PDF is in [page space](../../pages/reference/glossary.md#page-space): points measured from the top-left corner of the page, with y going down. It's the way a screen or a sheet of paper reads, so a number means the same thing in every part of the API.
+
+## Points
+
+A point is 1/72 of an inch. An A4 page is about 595 × 842 points, and a US Letter page is 612 × 792. Some pages set a [user unit](../../pages/reference/glossary.md#user-unit), which scales the file's own units; Lamina PDF applies it, so a point is always 1/72 inch.
+
+## The top-left corner of the page you see
+
+The origin is the top-left corner of the page as a viewer displays it: its visible area (its [crop box](../../pages/reference/glossary.md#crop-box)), turned the way the page is rotated. So `[72, 96]` is one inch from the left edge and 96 points from the top, whichever way the page is rotated in the file.
+
+For text, the second number is the baseline, the line the letters sit on. Letters reach up from it, and descenders such as "g" and "p" hang below it.
+
+This app places "Hello, world!" one inch from the top-left corner, with its baseline one text size lower:
+
+`packages/sdk/examples/quick-start/node.ts`:
+
+```ts
+// Builds a one-page PDF that says "Hello, world!" and writes it to hello.pdf, in Node.
+import { writeFile } from "node:fs/promises";
+import { Builder, type BuilderOptions, Font, init } from "@laminapdf/sdk";
+
+/** The space between the page's edge and the text, in points (72 points = 1 inch). */
+const MARGIN = 72;
+/** The text's size in points; its baseline sits this far below the margin. */
+const FONT_SIZE = 24;
+
+/** Builds the page and hands its bytes to `save`, which writes hello.pdf unless you pass another `save` function. */
+export async function hello(
+  save: (pdf: Uint8Array) => void | Promise<void> = (pdf) => writeFile("hello.pdf", pdf),
+  options: BuilderOptions = {},
+): Promise<void> {
+  await init({ text: true });
+  using builder = new Builder(options);
+  const page = builder.page("A4");
+  // Points from the page's top-left corner, y down; the text's baseline sits FONT_SIZE points below the margin.
+  page.surface().text("Hello, world!", {
+    font: Font.standard("Helvetica"),
+    size: FONT_SIZE,
+    at: [MARGIN, MARGIN + FONT_SIZE],
+  });
+  page.finish();
+  using doc = builder.finish();
+  await save(doc.save());
+}
+
+// `node hello.ts` runs it (Node 24.2 or newer); imported, it only exports `hello`.
+if (import.meta.main) await hello();
+```
+
+## Pages count from 0
+
+The first page is page 0 everywhere: `doc.page(0)`, a link's target, a page label's start.
+
+## PDF's own coordinates
+
+Inside the file, PDF measures from the bottom-left corner with y going up, before rotation. That's [user space](../../pages/reference/glossary.md#user-space). Lamina PDF converts for you, so you only meet it in Rust, in names that contain `UserSpace` or `user_space`.