@lupinum/nuxt-pdf 0.4.0-beta.4 → 0.4.0-beta.6

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`.

package/dist/agent/pages/docs/reference/define-pdf.md

@@ -0,0 +1,96 @@
+---
+title: "definePdf"
+description: "The compile-time definition for render metadata, development preview data, and the multi-pass limit."
+url: "https://nuxt-pdf.lupinum.com/docs/reference/define-pdf"
+route: "/docs/reference/define-pdf"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# definePdf
+
+> The compile-time definition for render metadata, development preview data, and the multi-pass limit.
+
+Each `pdfs/*.vue` template calls `definePdf` exactly once. It is a compile-time
+macro (like `defineProps`); it declares render metadata and development-only
+preview data and returns nothing.
+
+```ts
+definePdf<Props>({
+  title: props => `Report ${props.id}`,
+  filename: props => `report-${props.id}.pdf`,
+  language: 'en-GB',
+  maxPasses: 5,
+  sampleData: { id: 'sample' },
+  scenarios: {
+    long: { id: 'long-report' },
+  },
+})
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string \| (props) => string` | None | Document title. A static string or a function of props. |
+| `filename` | `string \| (props) => string` | None | Download filename, sanitized before use in `content-disposition`. |
+| `language` | `string` | None | Document language tag written to the info dictionary (for example `"en-US"`). |
+| `maxPasses` | `number` | `5` | Maximum layout passes before the multi-pass loop declares non-convergence and throws `PDF_LIMIT_EXCEEDED`. A positive integer. |
+| `sampleData` | `Props` | None | Props used for the default development preview. |
+| `scenarios` | `Record<string, Props>` | None | Named prop sets. Each set becomes a preview tab and a `?scenario=` query. |
+
+The `Props` type parameter ties `title`, `filename`, `sampleData`, and each
+`scenario` to the SFC's own props, so a mismatch is a type error.
+
+<info icon="lucide:info">
+`maxPasses` is only relevant to documents that read `usePdfPageNumbers()`.
+Every other document renders in a single pass regardless of the value.
+</info>
+
+## Metadata resolution
+
+`title` and `filename` functions receive the render props and must return a
+string synchronously. They are resolved at render time. When `title` or
+`language` is present, it is authoritative and overrides the corresponding prop
+authored on `PdfDocument`. When it is absent, the `PdfDocument` value remains the
+rendered fallback. The authoritative values are reapplied after every
+page-number update, so a multi-pass document cannot restore stale root metadata
+between layout passes.
+
+`resolveMetadata(props)` on the generated template handle resolves only the
+`definePdf` values without mounting the component. `filename` controls the
+default response filename; it is not a `PdfDocument` prop.
+
+## Preview data is development-only
+
+`sampleData` and `scenarios` are used only by the development preview. They are
+never exposed by the public `PdfTemplate` handle.
+
+Production compilation keeps only `title`, `filename`, `language`, and
+`maxPasses`. Preview expressions and routes are absent from the Nitro server
+output. Keep preview data representative and disposable. Do not use it as
+production runtime state or a place for secrets.
+
+`definePdf()` is module-scoped, like Vue's other hoisted compiler macros. Its
+values may be inline or imported from another module, but they cannot reference
+a variable declared locally in `<script setup>`; that fails compilation instead
+of producing a development-only `ReferenceError`. Keep imported preview-data
+modules free of side effects. Production removes an unused import only when
+evaluating that module has no required behavior.
+
+## Scenarios in the preview
+
+```ts
+definePdf<Props>({
+  sampleData: { id: 'sample' },
+  scenarios: {
+    long: { id: 'long-report' },
+    empty: { id: 'no-sections' },
+  },
+})
+```
+
+The `long` scenario is available at `/_pdf/report?scenario=long`. An unknown
+scenario name returns a 404 listing the available names.

package/dist/agent/pages/docs/reference/errors-and-limits.md

@@ -0,0 +1,89 @@
+---
+title: "Errors and limits"
+description: "Error classes, exact codes, render-budget defaults, and when each failure occurs."
+url: "https://nuxt-pdf.lupinum.com/docs/reference/errors-and-limits"
+route: "/docs/reference/errors-and-limits"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Errors and limits
+
+> Error classes, exact codes, render-budget defaults, and when each failure occurs.
+
+Configuration and asset setup can fail before rendering starts. Public render
+failures use `NuxtPdfError` and one code from `PDF_ERROR_CODES`.
+
+## Error classes and codes
+
+| Failure | Stage | Inspect or change |
+| --- | --- | --- |
+| `TypeError` | Module setup | Read the message and correct the module option, template definition, local asset, or configured font. No render or template error code exists yet. |
+| `PDF_TEMPLATE_NOT_FOUND` | Render dispatch | Check the template's relative filename and generated registry key. |
+| `PDF_TEMPLATE_INVALID` | Template execution | Move `definePdf()` or `usePdfPageNumbers()` to its supported template/render scope. |
+| `PDF_TREE_INVALID` | Vue mount or tree validation | Correct the named root, nesting rule, primitive prop, SVG reference, or text placement. |
+| `PDF_LAYOUT_ERROR` | Layout | Check geometry and registered font family, weight, and style. |
+| `PDF_LIMIT_EXCEEDED` | Any bounded render stage | Read the named limit and cap. Reduce the input or change that one configured budget. |
+| `PDF_ASSET_INVALID` | Image admission | Replace invalid admitted PNG or JPEG bytes, dimensions, or declared format. |
+| `PDF_ASSET_BLOCKED` | Image source or request policy | Check the source form, HTTPS allowlist, redirects, and per-hop timeout. |
+| `PDF_RENDER_ERROR` | Render | Inspect the attached message and template identity for an uncategorized engine failure. |
+
+`NuxtPdfError` exposes `code`, `templateKey`, and, in development,
+`templateFile`. Its message names the template. Production leaves out the
+relative source path.
+
+`PDF_LIMIT_EXCEEDED` covers every configured time and resource budget. An
+oversized local or remote image uses this code. Allowlist and unsupported-source
+policy failures use `PDF_ASSET_BLOCKED`. Invalid bytes that passed the source
+policy use `PDF_ASSET_INVALID`.
+
+## Render limits
+
+Every field is an optional positive safe integer. Omitting the `limits` object
+or one field keeps the default below. Invalid configuration throws `TypeError`
+during module setup.
+
+| Field | Default | Bounded work |
+| --- | --- | --- |
+| `timeoutMs` | `30_000` | Metadata resolution, mount, assets, every layout pass, serialization, and output collection. |
+| `maxPages` | `2_000` | Laid-out page count. |
+| `maxNodes` | `50_000` | Mounted document-tree nodes. |
+| `maxTreeDepth` | `128` | Mounted document-tree depth. |
+| `maxTextCharacters` | `2_000_000` | Unicode code points in text nodes. |
+| `maxImages` | `256` | Image nodes. |
+| `maxImageBytes` | `10_485_760` | Source bytes for one unique image. |
+| `maxTotalImageBytes` | `33_554_432` | Source bytes across unique images. |
+| `maxImagePixels` | `25_000_000` | Decoded pixels for one unique image. |
+| `maxTotalImagePixels` | `100_000_000` | Decoded pixels across unique images. |
+| `maxRemoteRequests` | `32` | Remote requests, including redirect hops. |
+| `maxRemoteConcurrency` | `4` | Simultaneous remote requests. |
+| `maxOutputBytes` | `67_108_864` | Completed PDF bytes. |
+
+Configure overrides in `nuxt.config.ts`:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  pdf: {
+    limits: {
+      maxPages: 500,
+      timeoutMs: 20_000,
+    },
+  },
+})
+```
+
+The timeout is one deadline for the complete public render. It is checked
+between engine stages and cannot interrupt synchronous layout midway. A single
+stage can therefore finish after the deadline before the error is reported.
+
+Tree and content limits are checked after Vue mounts and after each destination
+page-number update. Image budgets apply before engine admission. Output is
+collected into one completed buffer and discarded if `maxOutputBytes` is
+exceeded.
+
+`maxPasses` is a per-template `definePdf()` option, not a module limit. Its
+default is `5`. A table of contents normally settles after destination numbers
+feed into the next layout pass. Geometry that keeps changing fails with
+`PDF_LIMIT_EXCEEDED`.