@lupinum/nuxt-pdf 0.4.0-beta.3 → 0.4.0-beta.5

package/dist/agent/pages/docs/guides/svg-graphics.md

@@ -0,0 +1,165 @@
+---
+title: "Draw SVG graphics"
+description: "The SVG primitive set, direct presentation props, scoped definitions, SVG text, and the supported numeric boundary."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/svg-graphics"
+route: "/docs/guides/svg-graphics"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Draw SVG graphics
+
+> The SVG primitive set, direct presentation props, scoped definitions, SVG text, and the supported numeric boundary.
+
+Nuxt PDF ships a set of SVG drawing primitives that render through the same
+layout and render engine as the document primitives. A `PdfSvg` participates in
+normal page flow as a flex leaf, measured from its `viewBox` aspect ratio.
+
+## The primitive set
+
+| Component | Role |
+| --- | --- |
+| `PdfSvg` | SVG root; a flex leaf in page flow |
+| `PdfG` | A group; presentation attributes cascade to children |
+| `PdfPath` | A path from a `d` string |
+| `PdfRect` | A rectangle (`x`, `y`, `width`, `height`, `rx`, `ry`) |
+| `PdfCircle` | A circle (`cx`, `cy`, `r`) |
+| `PdfEllipse` | An ellipse (`cx`, `cy`, `rx`, `ry`) |
+| `PdfLine` | A line (`x1`, `y1`, `x2`, `y2`) |
+| `PdfPolyline` | An open polyline from a `points` string |
+| `PdfPolygon` | A closed polygon from a `points` string |
+| `PdfDefs` | Holds referenceable defs (gradients, clip paths) |
+| `PdfClipPath` | A clip path referenced by `clipPath="url(#id)"` |
+| `PdfLinearGradient` / `PdfRadialGradient` | Gradients referenced by `fill="url(#id)"` |
+| `PdfStop` | A gradient color stop |
+| `PdfTspan` | A text span inside an SVG `PdfText` |
+
+Full prop tables are in the [primitive reference](/raw/docs/reference/primitives.md).
+
+## A basic drawing
+
+```vue
+<PdfSvg viewBox="0 0 120 120" :style="{ width: 120, height: 120 }">
+  <PdfRect x="8" y="8" width="104" height="104" rx="12" fill="#eef2ee" />
+  <PdfCircle cx="60" cy="60" r="34" fill="#315d3b" />
+  <PdfPath d="M44 62 l12 12 l22 -26" stroke="#ffffff" stroke-width="6" fill="none" />
+</PdfSvg>
+```
+
+## Presentation is direct, not a style cascade
+
+Set SVG paint and geometry with direct props. `PdfG` and the shape primitives
+do not accept a generic `style` prop, so there is no prop-versus-style
+precedence to remember. `transform` is also a direct SVG prop; page-flow
+primitives such as `PdfView` put transforms in `PdfStyle` instead.
+
+`PdfSvg` is the exception only at the page-flow boundary: its `style` sizes and
+positions the SVG root in the surrounding PDF layout. It does not become a bag
+of SVG presentation attributes. SVG `PdfText` may use `style` for text metrics
+such as `fontFamily` and `fontSize`, but its paint color is the direct `fill`
+prop.
+
+Kebab-case attributes written in Vue templates (`stroke-width`, `stop-color`)
+are coerced to the camelCase keys the renderer reads, so both forms work:
+
+```vue
+<!-- stroke-width and strokeWidth are equivalent on SVG nodes -->
+<PdfLine x1="0" y1="0" x2="100" y2="0" stroke="#333" stroke-width="2" />
+```
+
+Presentation attributes set on a `PdfG` cascade to its children:
+
+```vue
+<PdfG fill="#315d3b" transform="translate(10 10) rotate(15)">
+  <PdfRect x="0" y="0" width="20" height="20" />
+  <PdfRect x="30" y="0" width="20" height="20" />
+</PdfG>
+```
+
+## Numbers and transforms
+
+Geometry accepts finite numbers or numeric strings; percentage strings are
+accepted only by props typed as `PdfSvgLength`. `strokeWidth` does not accept a
+percentage. Widths and radii must be non-negative, opacity and gradient-stop
+values must be between `0` and `1` (or `0%` and `100%`), and a `viewBox` must
+contain four finite numbers with positive width and height.
+
+The transform surface accepts one to three space-separated
+`translate(...)` or `rotate(...)` operations with unitless numeric arguments.
+Scale, matrix, skew, angle units, and arbitrary transform strings are rejected.
+
+Explicit zeroes keep SVG meaning despite truthiness fallbacks in the pinned
+serializer:
+
+- `fillOpacity="0"` paints fully transparent;
+- `strokeWidth="0"` paints no stroke (not a PDF hairline); and
+- a zero linear-gradient `x2`, or zero radial-gradient `cx`, `cy`, `fx`, `fy`,
+  or `r`, remains zero.
+
+Nuxt PDF repairs those values after layout on the disposable resolved tree,
+immediately before serialization. This is an engine-boundary correction, not a
+second authoring format.
+
+## Gradients and clip paths
+
+Define a gradient or clip path inside a `PdfDefs` and reference it by `url(#id)`:
+
+```vue
+<PdfSvg viewBox="0 0 200 100" :style="{ width: 200, height: 100 }">
+  <PdfDefs>
+    <PdfLinearGradient id="brand" x1="0" y1="0" x2="1" y2="0">
+      <PdfStop offset="0" stop-color="#315d3b" />
+      <PdfStop offset="1" stop-color="#7bbf88" />
+    </PdfLinearGradient>
+  </PdfDefs>
+  <PdfRect x="0" y="0" width="200" height="100" fill="url(#brand)" />
+</PdfSvg>
+```
+
+<info icon="lucide:info">
+A `url(#id)` reference resolves only against a `PdfDefs` in the same `PdfSvg`
+subtree. Definition ids must be safe and unique within that SVG, and each SVG
+accepts at most one `PdfDefs`. A missing, malformed, or incompatible reference
+(for example a clip path used as a fill) fails with `PDF_TREE_INVALID`; it is
+never rendered as an accidental fallback. The same definition id may be reused
+in another `PdfSvg` because scopes are independent.
+</info>
+
+## SVG text
+
+`PdfText` has two context-specific contracts. In page flow it accepts wrapping,
+pagination, bookmark, destination, and dynamic-text props. Inside `PdfSvg`, both
+`x` and `y` are required, `fill` is the direct paint prop, and page-flow-only
+props are rejected. SVG text may hold `PdfTspan` children, which join and chain
+along the x-axis:
+
+```vue
+<PdfSvg viewBox="0 0 200 40" :style="{ width: 200, height: 40 }">
+  <PdfText :x="0" :y="24" fill="#18251d">
+    <PdfTspan>Total </PdfTspan>
+    <PdfTspan fill="#315d3b">EUR 1,250.00</PdfTspan>
+  </PdfText>
+</PdfSvg>
+```
+
+The text content is preserved in the extracted page text, so it remains
+selectable and testable. `PdfTspan` accepts only
+`x`, `y`, and `fill`; it has no generic `style`, stroke, transform, or other
+shape presentation props.
+
+## Nesting rules and what is not claimed
+
+`PdfSvg` is a valid child of `PdfPage` and `PdfView` but is rejected directly
+inside `PdfText`. Leaf shapes stay childless. Each container accepts only its
+valid children; invalid nesting fails with a targeted diagnostic.
+
+Within SVG, the following are **not** claimed in the current alpha:
+
+- `Marker` (`markerStart` / `markerMid` / `markerEnd`);
+- alternate `gradientUnits`, `gradientTransform`, gradient inheritance, and
+  `preserveAspectRatio` modes;
+- radial-gradient inner radius (`fr`), which the pinned renderer hardcodes to
+  zero; and
+- SVG image _files_ as an image source.

package/dist/agent/pages/docs/guides/testing.md

@@ -0,0 +1,119 @@
+---
+title: "Test a PDF"
+description: "Assert against your own templates with a real render using @lupinum/nuxt-pdf/test, plus a realistic Vitest example."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/testing"
+route: "/docs/guides/testing"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Test a PDF
+
+> Assert against your own templates with a real render using @lupinum/nuxt-pdf/test, plus a realistic Vitest example.
+
+The utilities Nuxt PDF is tested with ship as `@lupinum/nuxt-pdf/test`. They run
+a **real render** through the same pipeline that your server uses. This pipeline includes asset
+resolution, font registration, and single-pass or multi-pass layout. You assert against actual
+output, not a mocked tree. There is one parser, and it is the one the package's
+own suite runs on.
+
+## Setup
+
+The parser and rasterizer load `pdfjs-dist` and `@napi-rs/canvas` lazily. Install
+them as dev dependencies of the project under test:
+
+```bash [pnpm]
+pnpm add -D pdfjs-dist @napi-rs/canvas
+```
+
+The helpers are runner-agnostic: they throw a `PdfAssertionError` with an
+actionable message rather than depending on Vitest or Jest.
+
+## A realistic example
+
+```ts [test/invoice.test.ts]
+import { describe, it } from 'vitest'
+import { expectPdf, renderPdfSfc } from '@lupinum/nuxt-pdf/test'
+
+describe('invoice.vue', () => {
+  it('renders the customer, a terms link, and an outline', async () => {
+    const { parsed } = await renderPdfSfc(
+      './pdfs/invoice.vue',
+      { invoice: { customer: 'Acme Corp', number: 'INV-001', total: 'EUR 1,250.00' } },
+      { fonts: [{ family: 'Invoice Sans', src: 'InvoiceSans-Regular.ttf' }] },
+    )
+
+    expectPdf(parsed)
+      .toHavePageCount(2)
+      .toContainText('Invoice for Acme Corp', { page: 1 })
+      .toHaveLink({ destination: 'terms', page: 1 })
+      .toHaveLink({ url: 'https://example.com/' })
+      .toHaveOutline([{ title: 'Terms' }])
+  })
+})
+```
+
+`renderPdfSfc(file, props, options)` compiles nested SFC imports, discovers local
+images, bundles declared fonts, mounts through the real registry pipeline, and
+returns `{ bytes, parsed, result }`. Use `renderPdfTemplate(Component, props)`
+when the test already has an ordinary Vue component. Both helpers accept the
+same partial `remote` and `limits` options as `nuxt.config`; the SFC helper also
+accepts the same local `fonts` declarations.
+
+## Assertions
+
+`expectPdf(parsed)` returns a chainable expectation:
+
+| Assertion | Checks |
+| --- | --- |
+| `toHavePageCount(n)` | The document has `n` pages |
+| `toContainText(text, { page? })` | The extracted text contains `text` (optionally on a page) |
+| `toHaveLink({ destination? , url? , page? })` | A named-destination or external-URL link annotation exists |
+| `toHaveOutline(shape)` | The bookmark outline matches the given title hierarchy |
+
+`parsePdf` exposes the same data directly. The data includes page text, page count, flattened
+link annotations, and the outline. Use it when you want to assert without the fluent
+API.
+
+## Testing a server route
+
+`parsePdf` also accepts a `PdfRenderResult` straight from the registry, so route
+tests read naturally:
+
+```ts
+import { parsePdf } from '@lupinum/nuxt-pdf/test'
+import { pdf } from '#pdf'
+
+const parsed = await parsePdf(await pdf.invoice.render(props))
+```
+
+## Pixel-level regressions
+
+For visual regressions, `comparePdfSnapshot` follows a **reviewed-baseline**
+policy: it writes per-page PNG baselines into a directory when
+`UPDATE_PDF_BASELINES=1` (or `{ update: true }`) is set, and otherwise compares
+each page against them within a pixel threshold:
+
+```ts
+import { comparePdfSnapshot, renderPdfSfc } from '@lupinum/nuxt-pdf/test'
+
+const { bytes } = await renderPdfSfc('./pdfs/invoice.vue', props)
+await comparePdfSnapshot(bytes, './test/baselines/invoice')
+```
+
+A failed comparison writes expected, actual, and diff PNGs for every changed
+page plus `metrics.json` under `reports/pdf-snapshots`. Upload that directory in
+CI so the failure can be inspected without reproducing it locally. Semantic
+geometry checks are available through `parsePdf(...).pages[n].textRuns`; compare
+coordinates with a tolerance instead of exact equality.
+
+<info icon="lucide:info">
+Raster baselines are environment-sensitive. Review them when they change and
+commit them for review, exactly as you would a visual snapshot. Nuxt PDF does
+not claim byte-identical output across machines.
+</info>
+
+The full set of exports and options is in the
+[test utilities reference](/raw/docs/reference/test-utilities.md).

package/dist/agent/pages/docs/learn/document-tree.md

@@ -0,0 +1,91 @@
+---
+title: "The document tree"
+description: "PDF primitives, valid nesting, Vue composition, and dynamic text."
+url: "https://nuxt-pdf.lupinum.com/docs/learn/document-tree"
+route: "/docs/learn/document-tree"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# The document tree
+
+> PDF primitives, valid nesting, Vue composition, and dynamic text.
+
+Nuxt PDF renders a closed tree of PDF primitives. It does not render HTML or DOM
+components.
+
+## Root and page structure
+
+Each template has one `PdfDocument` root and at least one `PdfPage`:
+
+```vue
+<PdfDocument>
+  <PdfPage>
+    <PdfView>
+      <PdfText>Quarterly report</PdfText>
+    </PdfView>
+  </PdfPage>
+</PdfDocument>
+```
+
+The main primitives are:
+
+| Primitive | Role |
+| --- | --- |
+| `PdfDocument` | Document root and metadata |
+| `PdfPage` | One fixed or wrapping page |
+| `PdfView` | Flex layout container |
+| `PdfText` | Text content and inline text runs |
+| `PdfImage` | PNG or JPEG image |
+| `PdfLink` | External or internal link |
+| `PdfNote` | PDF note annotation |
+
+The [primitive reference](/raw/docs/reference/primitives.md) lists the closed prop and
+nesting surface. The [SVG guide](/raw/docs/guides/svg-graphics.md) covers vector
+graphics.
+
+<warning icon="lucide:triangle-alert">
+Put all visible text inside `PdfText`. Text placed directly under `PdfPage` or
+`PdfView` fails with `PDF_TREE_INVALID`; it is not discarded.
+</warning>
+
+## Vue composition
+
+Use local Vue components, typed props, slots, `v-if`, and keyed `v-for`. Keep
+components owned by one document under a document-specific directory:
+
+```vue [pdfs/components/invoice/InvoiceLine.vue]
+<script setup lang="ts">
+defineProps<{ label: string; amount: string }>()
+</script>
+
+<template>
+  <PdfView :style="{ flexDirection: 'row', justifyContent: 'space-between' }">
+    <PdfText>{{ label }}</PdfText>
+    <PdfText>{{ amount }}</PdfText>
+  </PdfView>
+</template>
+```
+
+Import the component from the template. Nuxt app plugins, global components,
+directives, and app-level provides do not enter the PDF tree.
+
+## Dynamic page text
+
+Use a synchronous `render` callback for values known during pagination:
+
+```vue
+<PdfText
+  fixed
+  :render="({ pageNumber, totalPages }) => `Page ${pageNumber} of ${totalPages}`"
+/>
+```
+
+`fixed` repeats the node on each page. The callback returns a string or number.
+For a table of contents that reads destination page numbers, use
+[`usePdfPageNumbers()`](/raw/docs/guides/contents-links-bookmarks.md).
+
+Invalid nesting, unknown primitive props, DOM attributes, `Teleport`, and
+`v-show` fail instead of producing incomplete PDF content.

package/dist/agent/pages/docs/learn/runtime-and-data.md

@@ -0,0 +1,63 @@
+---
+title: "Runtime and data loading"
+description: "Where PDF templates execute and how data enters a render."
+url: "https://nuxt-pdf.lupinum.com/docs/learn/runtime-and-data"
+route: "/docs/learn/runtime-and-data"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Runtime and data loading
+
+> Where PDF templates execute and how data enters a render.
+
+Each render creates a fresh Vue runtime-core application inside the Node
+process. Nuxt PDF mounts the document tree, lays it out, serializes the PDF, and
+then unmounts the Vue application.
+
+## Load data before rendering
+
+Fetch and authorize data in normal server code. Pass the completed values
+through typed props:
+
+```ts
+import { pdf } from '#pdf'
+
+export default defineEventHandler(async (event) => {
+  const id = getRouterParam(event, 'id')
+  const invoice = await loadAuthorizedInvoice(event, id)
+  const result = await pdf.invoice.render({ invoice })
+
+  return result.response()
+})
+```
+
+This keeps request context, credentials, and database access in the Nuxt server
+where they belong. The template receives only the document data it needs.
+
+## Isolated Vue context
+
+PDF templates can use local imports, Vue reactivity, lifecycle hooks, and
+provide/inject within the document tree. They do not inherit:
+
+- Nuxt app plugins or app-level provides;
+- global application components or directives;
+- browser globals such as `window` and `document`;
+- `onServerPrefetch` as a data-loading mechanism.
+
+Async setup, top-level `await`, and `defineAsyncComponent` are rejected because
+layout cannot wait for document content to appear later.
+
+## Render stages and limits
+
+One render covers metadata resolution, Vue mount, asset admission, layout,
+optional page-number passes, serialization, and output collection. The module
+applies one deadline and resource budget to that operation.
+
+The deadline is checked between engine stages. It cannot interrupt a
+synchronous layout stage midway. Do not run untrusted template code in the
+process. Use the [errors and limits reference](/raw/docs/reference/errors-and-limits.md)
+to size admitted data, and the [deployment guide](/raw/docs/guides/deployment.md) to
+plan timeouts and queues.

package/dist/agent/pages/docs/learn/styling-and-layout.md

@@ -0,0 +1,79 @@
+---
+title: "Styling and layout"
+description: "The PDF style model, flex layout, units, inheritance, and shared geometry."
+url: "https://nuxt-pdf.lupinum.com/docs/learn/styling-and-layout"
+route: "/docs/learn/styling-and-layout"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Styling and layout
+
+> The PDF style model, flex layout, units, inheritance, and shared geometry.
+
+The `style` prop accepts a typed PDF style object. It resembles a subset of CSS,
+but no browser stylesheet or cascade is involved.
+
+## Core rules
+
+- Use camelCase keys such as `backgroundColor` and `marginTop`.
+- Unitless numbers are PDF points.
+- Length strings accept `pt`, `in`, `mm`, `cm`, and `px` where the property
+  supports them.
+- Percentages are strings such as `'50%'`.
+- The default flex direction is `column`.
+- Font family, size, weight, style, line height, color, opacity, and text
+  alignment can inherit through the document tree. Set other layout explicitly.
+
+```vue
+<PdfView
+  :style="{
+    alignItems: 'center',
+    backgroundColor: '#f4f6f4',
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    padding: 12,
+  }"
+>
+  <PdfText>Invoice total</PdfText>
+  <PdfText>EUR 1,250.00</PdfText>
+</PdfView>
+```
+
+## Type shared styles
+
+Use `satisfies PdfStyle` so TypeScript checks keys and values without widening
+the object:
+
+```ts [pdfs/components/theme.ts]
+import type { PdfStyle } from '@lupinum/nuxt-pdf'
+
+export const eyebrow = {
+  color: '#566159',
+  fontSize: 7,
+  letterSpacing: 1.4,
+  textTransform: 'uppercase',
+} satisfies PdfStyle
+```
+
+Style arrays merge left to right. Nested arrays are flattened, and `false`,
+`null`, and `undefined` entries are ignored:
+
+```vue
+<PdfText :style="[base, isTotal && total]">
+  {{ amount }}
+</PdfText>
+```
+
+## Share geometry once
+
+When a table header and its rows must align, define the column widths in one
+TypeScript module and import that definition from both components. A table is a
+column of rows. Each row uses `flexDirection: 'row'` and the same fixed widths.
+The header and body then cannot drift apart.
+
+The [style reference](/raw/docs/reference/styles.md) contains the exact property,
+unit, inheritance, and primitive matrix. The [recipe guide](/raw/docs/guides/recipes.md)
+shows tables, totals, headers, and page-break patterns.

package/dist/agent/pages/docs/learn/templates-and-registry.md

@@ -0,0 +1,96 @@
+---
+title: "Templates and the registry"
+description: "How files under pdfs become typed server-side render functions."
+url: "https://nuxt-pdf.lupinum.com/docs/learn/templates-and-registry"
+route: "/docs/learn/templates-and-registry"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Templates and the registry
+
+> How files under pdfs become typed server-side render functions.
+
+A PDF template is a Vue Single File Component under `pdfs/`. Nuxt PDF discovers
+the file and creates one typed entry in the server-only `#pdf` registry.
+
+Use `Pdf*` components inside PDF templates. In development, using one in an
+application component reports an error. Move it under `pdfs/`, or replace it
+with an HTML component.
+
+## Template discovery
+
+The relative file path becomes the registry key:
+
+| Template file | Registry entry |
+| --- | --- |
+| `pdfs/invoice.vue` | `pdf.invoice` |
+| `pdfs/report.vue` | `pdf.report` |
+| `pdfs/reports/monthly.vue` | `pdf['reports/monthly']` |
+
+Three directories have a different purpose and do not become registry entries:
+
+| Directory | Contents |
+| --- | --- |
+| `pdfs/components` | Local Vue components and shared TypeScript modules |
+| `pdfs/assets` | Local PNG and JPEG files |
+| `pdfs/fonts` | Local TTF, OTF, and WOFF2 files |
+
+A project template replaces a same-key template from an extended Nuxt layer.
+Duplicate keys in the same layer fail during module setup.
+
+## One definition per template
+
+Each discovered template calls `definePdf()` exactly once at the top level of
+`<script setup>`. It declares metadata and development preview data:
+
+```vue [pdfs/report.vue]
+<script setup lang="ts">
+type ReportProps = {
+  id: string
+  title: string
+}
+
+defineProps<ReportProps>()
+
+definePdf<ReportProps>({
+  title: props => props.title,
+  filename: props => `report-${props.id}.pdf`,
+  sampleData: { id: 'sample', title: 'Sample report' },
+})
+</script>
+```
+
+`title` and `filename` can be strings or synchronous functions of the render
+props. `sampleData` and named scenarios are removed from production output.
+They never become a server data source.
+
+The [definePdf reference](/raw/docs/reference/define-pdf.md) lists every option and
+its metadata precedence.
+
+## Typed rendering
+
+Import the generated registry from server code:
+
+```ts [server/api/report.get.ts]
+import { pdf } from '#pdf'
+
+export default defineEventHandler(async () => {
+  const result = await pdf.report.render({
+    id: 'Q2-2026',
+    title: 'Quarterly report',
+  })
+
+  return result.response()
+})
+```
+
+The registry infers the required props from `defineProps<ReportProps>()`. Load
+request, database, and API data before `render()`, then pass the resolved values
+as props.
+
+Use `renderPdf(key, props)` when the template key is only known at runtime. The
+[registry reference](/raw/docs/reference/registry.md) documents its overloads, result
+methods, and errors.

package/dist/agent/pages/docs/reference/composables.md

@@ -0,0 +1,55 @@
+---
+title: "Composables"
+description: "The auto-imported usePdfPageNumbers map that activates multi-pass layout."
+url: "https://nuxt-pdf.lupinum.com/docs/reference/composables"
+route: "/docs/reference/composables"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Composables
+
+> The auto-imported usePdfPageNumbers map that activates multi-pass layout.
+
+## usePdfPageNumbers
+
+```ts
+const pageNumbers = usePdfPageNumbers()
+// pageNumbers: Readonly<Record<string, number | undefined>>
+```
+
+Auto-imported inside PDF templates and the components they render. Returns a
+**readonly, reactive** map from each destination `id` to the 1-based page it
+finally lands on.
+
+Reading it is the only signal that turns on the multi-pass layout loop. The
+engine lays the document out repeatedly, feeding each pass's destination-page map back
+in, until the numbers stabilize.
+
+### Behavior
+
+- **First pass is `undefined`.** Every entry is `undefined` until the loop has
+  located the destination. A template must support a missing number. Keep a
+  fallback such as `pageNumbers[id] ?? ''`.
+- **First page of a section.** A number resolves to the page the destination's
+  node _starts_ on, even when the section spans pages.
+- **Throws outside a render.** Calling it anywhere but a PDF template's setup
+  throws a `PDF_TEMPLATE_INVALID` error, rather than returning an empty map that
+  could be mistaken for first-pass state.
+
+```vue
+<script setup lang="ts">
+const pageNumbers = usePdfPageNumbers()
+</script>
+
+<template>
+  <PdfLink :href="`#${section.id}`">
+    {{ section.title }} {{ pageNumbers[section.id] ?? '' }}
+  </PdfLink>
+</template>
+```
+
+See [Contents, links & bookmarks](/raw/docs/guides/contents-links-bookmarks.md) for
+convergence semantics and `maxPasses`.