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

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@lupinum/nuxt-pdf` are recorded here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.4.0-beta.6
+
+### Patch Changes
+
+- [#68](https://github.com/lupinum-dev/nuxt-pdf/pull/68) [`11d711a`](https://github.com/lupinum-dev/nuxt-pdf/commit/11d711ac83c69d3f468fb7983a15075398fa100e) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix `renderPdfSfc()` to use the fonts from the application's Nuxt configuration, including inherited layers, when the test passes no `fonts` option.
+
+## 0.4.0-beta.5
+
+[compare changes](https://github.com/lupinum-dev/nuxt-pdf/compare/v0.4.0-beta.4...0.4.0-beta.5)
+
+### Added
+
+- **docs:** Ship versioned package guidance ([ca81a32](https://github.com/lupinum-dev/nuxt-pdf/commit/ca81a32))
+
+### Fixed
+
+- **deps:** Clear workspace advisories and update Vitest ([#59](https://github.com/lupinum-dev/nuxt-pdf/pull/59))
+
 ## 0.4.0-beta.4
 
 [compare changes](https://github.com/lupinum-dev/nuxt-pdf/compare/v0.4.0-beta.3...0.4.0-beta.4)

package/CONFORMANCE.md

@@ -1,11 +1,11 @@
-# Nuxt PDF 0.4.0-beta.4 conformance
+# Nuxt PDF conformance
 
 Nuxt PDF claims behavioral compatibility for a deliberately small, tested
 corpus. It does not claim full React PDF API or test-suite compatibility.
 
 ## Version boundary
 
-| Layer | 0.4.0-beta.4 boundary |
+| Layer | Tested boundary |
 |---|---|
 | Node.js | `^22.14.0`, `^24.0.0`, or `^26.0.0` |
 | Nuxt | `^4.4.8` |
@@ -217,7 +217,7 @@ checking.
 
 ### Vue and Nuxt authoring
 
-The 0.4.0-beta.2 tests verify:
+The tests verify:
 
 - `PdfDocument`, `PdfPage`, `PdfView`, `PdfText`, `PdfImage`, `PdfLink`, and
   `PdfNote`;
@@ -456,7 +456,7 @@ parser, not two. Claimed:
 Verified end-to-end against a real rendered template, including assertion
 failure messages, in `test/test-utils-public.test.ts`.
 
-## Explicitly not claimed in 0.4.0-beta.2
+## Explicitly not claimed
 
 - Full React PDF component, hook, browser-helper, or test-suite parity.
 - React runtime compatibility or React-shaped dynamic callback results.

package/README.md

@@ -22,7 +22,7 @@
   <a href="https://www.npmjs.com/package/@lupinum/nuxt-pdf"><img src="https://img.shields.io/npm/v/@lupinum/nuxt-pdf?color=00DC82" alt="npm version"></a>
   <a href="https://github.com/lupinum-dev/nuxt-pdf/actions/workflows/ci.yml"><img src="https://github.com/lupinum-dev/nuxt-pdf/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-00DC82" alt="MIT license"></a>
-  <a href="https://discord.gg/RPH6SeA36N"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord" alt="Discord"></a>
+  <a href="https://discord.lupinum.com"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord" alt="Discord"></a>
   <a href="https://deepwiki.com/lupinum-dev/nuxt-pdf"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
@@ -158,13 +158,58 @@ Nuxt PDF regenerates the typed `#pdf` registry whenever templates change. If
 your editor still shows `#pdf` as untyped, run `nuxt prepare` once to refresh
 the generated types.
 
+## Agent setup
+
+`@lupinum/nuxt-pdf` ships its documentation inside the package for coding
+agents such as Claude Code, Codex and Cursor. The pages match the installed
+version, so an agent does not follow the website for a different version.
+
+To set it up, give your coding agent this task:
+
+```text
+Set up @lupinum/nuxt-pdf for coding agents as described under "Agent setup" in its README.
+```
+
+### Steps for the agent
+
+1. Find `node_modules/@lupinum/nuxt-pdf/dist/agent/AGENTS.md`. Look in the
+   directory of the project that depends on `@lupinum/nuxt-pdf` first, then
+   in its parent directories up to the repository root (workspaces can hoist
+   packages). Read it; it lists the documentation pages.
+2. Add the section below to the project's agent instructions: `AGENTS.md`, or
+   `CLAUDE.md` if the project has only that file. If it has neither, create
+   `AGENTS.md`. Write the path relative to the repository root, through
+   `node_modules/@lupinum/nuxt-pdf` (for example
+   `apps/web/node_modules/@lupinum/nuxt-pdf/...` in a workspace). Never write
+   a resolved path such as `node_modules/.pnpm/...`: it contains the version and
+   breaks after an upgrade. If a section for `@lupinum/nuxt-pdf` already
+   exists, leave it as it is.
+
+   Use the path you found in place of the sample path:
+
+   ```md
+   ## @lupinum/nuxt-pdf
+
+   Before you change code that uses @lupinum/nuxt-pdf, read
+   `node_modules/@lupinum/nuxt-pdf/dist/agent/AGENTS.md` and the pages it
+   lists. They document the installed version. Prefer them over what you
+   remember about this package and over the website.
+   ```
+
+3. Do not copy the documentation into the project and do not install a skill.
+   The section points into the installed package, so it stays correct after
+   every upgrade or downgrade.
+
+If the file does not exist, the installed version has no packaged
+documentation. Read the package README and its TypeScript types instead.
+
 ## Discord
 
 Join the Lupinum OSS community to discuss Nuxt PDF, ask questions, and share
 what you build.
 
 <p align="center">
-  <a href="https://discord.gg/RPH6SeA36N">
+  <a href="https://discord.lupinum.com">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="docs/public/discord-dark.svg">
       <source media="(prefers-color-scheme: light)" srcset="docs/public/discord-light.svg">
@@ -234,23 +279,20 @@ pnpm dev
 pnpm verify
 ```
 
-Use `pnpm docs:dev` to run the documentation site. Run `pnpm docs:build` before
-you hand off a documentation change. Use `pnpm release:verify` only for release
-preparation.
+Use `pnpm docs:dev` to run the documentation site. `pnpm verify` runs the same
+checks as CI.
 
-Read [CONTRIBUTING.md](./CONTRIBUTING.md) before you open a pull request.
-Maintainers use [MAINTAINING.md](./MAINTAINING.md) for release and recovery
-procedures.
+Read [CONTRIBUTING.md](.github/CONTRIBUTING.md) before you open a pull request.
 
 ## Support and security
 
 - Read the [documentation](https://nuxt-pdf.lupinum.com).
-- Join the [Lupinum OSS Discord](https://discord.gg/RPH6SeA36N).
-- Open a [bug report](https://github.com/lupinum-dev/nuxt-pdf/issues/new?template=bug.md)
+- Join the [Lupinum OSS Discord](https://discord.lupinum.com).
+- Open a [bug report](https://github.com/lupinum-dev/nuxt-pdf/issues/new?template=bug.yml)
   for a reproducible defect.
-- Open a [feature request](https://github.com/lupinum-dev/nuxt-pdf/issues/new?template=proposal.md)
+- Open a [feature request](https://github.com/lupinum-dev/nuxt-pdf/issues/new?template=feature.yml)
   before you plan a larger change.
-- Follow [SECURITY.md](./SECURITY.md) for a private vulnerability report.
+- Follow [SECURITY.md](.github/SECURITY.md) for a private vulnerability report.
 
 ## License
 

package/dist/agent/AGENTS.md

@@ -0,0 +1,44 @@
+# @lupinum/nuxt-pdf 0.4.0-beta.6 documentation
+
+These pages document the installed version 0.4.0-beta.6. Prefer them over what you
+remember about this package and over the website, which may describe another version.
+Read the pages that match the task before you write code. If they do not answer a question,
+the user can ask in the Lupinum OSS Discord: https://discord.lupinum.com
+
+> Author and render PDFs with Vue components in Nuxt.
+
+## When to use
+
+Use this site to author and render PDF documents with Nuxt PDF.
+
+## Documentation
+
+- [Overview](./pages/docs/getting-started.md): Decide whether Nuxt PDF fits the document you need to create.
+- [Install Nuxt PDF](./pages/docs/getting-started/installation.md): Add server-side PDF rendering to an existing Nuxt 4 application.
+- [Render your first PDF](./pages/docs/getting-started/quickstart.md): Create, download, and preview a small invoice in a Nuxt application.
+- [Templates and the registry](./pages/docs/learn/templates-and-registry.md): How files under pdfs become typed server-side render functions.
+- [The document tree](./pages/docs/learn/document-tree.md): PDF primitives, valid nesting, Vue composition, and dynamic text.
+- [Styling and layout](./pages/docs/learn/styling-and-layout.md): The PDF style model, flex layout, units, inheritance, and shared geometry.
+- [Runtime and data loading](./pages/docs/learn/runtime-and-data.md): Where PDF templates execute and how data enters a render.
+- [Build reusable document components](./pages/docs/guides/reusable-components.md): Organize repeated PDF sections without creating a second component system.
+- [Add images and fonts](./pages/docs/guides/images-and-fonts.md): Bundle local PNG, JPEG, TTF, OTF, and WOFF2 resources with a PDF template.
+- [Configure remote images](./pages/docs/guides/remote-images.md): Admit specific HTTPS image paths and understand the request boundary.
+- [Add links, bookmarks, and a table of contents](./pages/docs/guides/contents-links-bookmarks.md): usePdfPageNumbers, the multi-pass layout loop, convergence and maxPasses, internal links, and the bookmark outline.
+- [Draw SVG graphics](./pages/docs/guides/svg-graphics.md): The SVG primitive set, direct presentation props, scoped definitions, SVG text, and the supported numeric boundary.
+- [Test a PDF](./pages/docs/guides/testing.md): Assert against your own templates with a real render using @lupinum/nuxt-pdf/test, plus a realistic Vitest example.
+- [Diagnose render failures](./pages/docs/guides/errors-and-debugging.md): Use template attribution, preview diagnostics, and exact error messages to recover from a failed render.
+- [Deploy and operate](./pages/docs/guides/deployment.md): Size, cache, queue, and monitor PDF rendering on a tested Node target.
+- [Production recipes](./pages/docs/guides/recipes.md): Copyable Vue patterns for invoices, statements, reports, repeating matter, and payment QR codes.
+- [Render outside Nitro](./pages/docs/guides/standalone-node.md): Compile PDF templates once and render the generated registry in a Node worker.
+- [Module options](./pages/docs/reference/module-options.md): Build-time configuration for registered fonts, remote images, and render budgets.
+- [definePdf](./pages/docs/reference/define-pdf.md): The compile-time definition for render metadata, development preview data, and the multi-pass limit.
+- [Registry and render result](./pages/docs/reference/registry.md): The typed #pdf server module, runtime dispatch, and completed render conversions.
+- [Primitives](./pages/docs/reference/primitives.md): Prop tables for every document and SVG primitive, drawn from the shipped type definitions.
+- [Styles](./pages/docs/reference/styles.md): Accepted style keys, values, units, inheritance, and primitive support.
+- [Page sizes](./pages/docs/reference/page-sizes.md): Named and custom page dimensions accepted by PdfPage.
+- [Composables](./pages/docs/reference/composables.md): The auto-imported usePdfPageNumbers map that activates multi-pass layout.
+- [Errors and limits](./pages/docs/reference/errors-and-limits.md): Error classes, exact codes, render-budget defaults, and when each failure occurs.
+- [Test utilities](./pages/docs/reference/test-utilities.md): The render, parse, assert, and snapshot exports of @lupinum/nuxt-pdf/test.
+- [Standalone build and runtime](./pages/docs/reference/standalone.md): Production registry generation and Node runtime exports outside Nitro.
+- [Example gallery](./pages/docs/examples.md): Six playground templates and the technique that each template demonstrates.
+- [Supported behavior and limitations](./pages/docs/examples/supported-behavior.md): The public compatibility boundary and where to find its executable evidence.

package/dist/agent/pages/docs/examples/supported-behavior.md

@@ -0,0 +1,75 @@
+---
+title: "Supported behavior and limitations"
+description: "The public compatibility boundary and where to find its executable evidence."
+url: "https://nuxt-pdf.lupinum.com/docs/examples/supported-behavior"
+route: "/docs/examples/supported-behavior"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Supported behavior and limitations
+
+> The public compatibility boundary and where to find its executable evidence.
+
+Nuxt PDF supports the behavior listed in its public guides and reference pages
+against exact pinned layout, font, and serialization packages. It does not claim
+the complete React PDF API or test suite.
+
+## Supported areas
+
+The repository tests these user-facing areas:
+
+- document trees, pagination, flex layout, styles, text, and raster images;
+- local fonts and admitted local or allowlisted remote image sources;
+- metadata, links, notes, bookmarks, and destination page numbers;
+- SVG shapes, gradients, clip paths, transforms, and SVG text;
+- semantic PDF inspection and raster snapshot helpers;
+- production removal of preview routes and preview data;
+- bounded render time, tree size, image admission, page count, and output size.
+
+The detailed support status for scripts and fonts is in
+[Add images and fonts](/raw/docs/guides/images-and-fonts.md). Exact primitive and style
+support belongs to the [reference section](/raw/docs/reference/primitives.md).
+
+## Differences from React PDF
+
+Three behaviors differ where matching the pinned lower engine would produce a
+wrong or unstable public result:
+
+- A table-of-contents destination resolves to the section's first page.
+- Dynamic page text does not inherit a `lineHeight` multiplier. Apply line
+  height to static `PdfText` instead.
+- Explicit zero values keep SVG meaning for fill opacity, stroke width, and
+  supported gradient coordinates.
+
+These differences have geometry or raster regression coverage.
+
+## Outside the current boundary
+
+Nuxt PDF does not claim:
+
+- full React PDF API, hook, browser-helper, or runtime compatibility;
+- Nuxt 3, Node 20, browser rendering, or edge rendering;
+- HTML printing, browser CSS, tables, charts, forms, signing, editing, or PDF
+  merging as built-in features;
+- tagged PDF, PDF/UA, or archival compliance profiles;
+- byte-identical output across operating systems and viewers;
+- authenticated remote requests, custom headers, remote fonts, or SSRF
+  protection beyond the exact-prefix allowlist;
+- SVG image files, SVG markers, or the complete browser SVG model;
+- multi-pass resolution of values other than destination page numbers.
+
+## Evidence record
+
+This page is the public summary. Maintainers and reviewers can inspect:
+
+- [CONFORMANCE.md](https://github.com/lupinum-dev/nuxt-pdf/blob/main/CONFORMANCE.md)
+  for version pins, paired comparisons, tested fixtures, and explicit
+  non-claims;
+- [CONTRACTS.md](https://github.com/lupinum-dev/nuxt-pdf/blob/main/src/runtime/server/engine/CONTRACTS.md)
+  for the renderer's durable engine contracts.
+
+When the documentation and public source disagree, the source is authoritative
+and the documentation needs a correction.

package/dist/agent/pages/docs/examples.md

@@ -0,0 +1,163 @@
+---
+title: "Example gallery"
+description: "Six playground templates and the technique that each template demonstrates."
+url: "https://nuxt-pdf.lupinum.com/docs/examples"
+route: "/docs/examples"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Example gallery
+
+> Six playground templates and the technique that each template demonstrates.
+
+The playground under `playground/pdfs/` ships six complete templates. Each is an
+ordinary `.vue` single-file component discovered by the module, rendered through
+the same registry in development and production, and covered by an end-to-end
+rendering test. Selected visually load-bearing showcases additionally compare
+reviewed raster baselines. Run `pnpm dev` and open `/_pdf` to browse them, or
+read each source alongside the excerpts below.
+
+<info icon="lucide:info">
+`renderPdfSfc` compiles the same nested child-SFC graph as the production Nuxt
+module. The packed-package gate exercises typed child props, a local image, and
+multiple local font faces.
+</info>
+
+## At a glance
+
+| Template | Source | Demonstrates |
+| --- | --- | --- |
+| Invoice | `pdfs/invoice.vue` | Typed props, computed totals, a fixed footer, dynamic page count |
+| Report | `pdfs/report.vue` | `usePdfPageNumbers` table of contents, internal links, bookmarks |
+| Annual report | `pdfs/annual-report.vue` | SVG bar / line / donut charts and tables drawn from Views |
+| Certificate | `pdfs/certificate.vue` | SVG ornament craft with an engraver's border and a seal |
+| E-book | `pdfs/ebook.vue` | `usePdfPageNumbers` with chapter-aware running matter |
+| Menu | `pdfs/menu.vue` | Pure typography, diacritics, dotted leaders, tabular prices |
+
+## E-book with chapter-aware running matter
+
+_The Reed Line_ is a 21-page digest novella. It reads the resolved page map from
+[`usePdfPageNumbers`](/raw/docs/reference/composables.md) twice: once to print a
+Contents page with real page numbers, and once for a running foot that names the
+**current** chapter on every page it repeats onto. The chapter is derived from
+measured pagination, never hard-coded.
+
+```vue [pdfs/ebook.vue]
+const pageNumbers = usePdfPageNumbers()
+
+// Derive the current chapter for any page from the resolved start-page map.
+const chapterAt = (pageNumber: number): Ebook['chapters'][number] => {
+  let current = ebook.chapters[0]!
+  for (const chapter of ebook.chapters) {
+    const start = pageNumbers[chapter.id]
+    if (typeof start === 'number' && start <= pageNumber) current = chapter
+  }
+  return current
+}
+```
+
+The foot is a single `fixed` node whose `:render` closes over `chapterAt`, so one
+callback prints the right chapter and folio on every page:
+
+```vue [pdfs/ebook.vue]
+<PdfText
+  fixed
+  :render="({ pageNumber }) => `${chapterAt(pageNumber).title}   ·   ${pageNumber}`"
+  :style="footStyle"
+/>
+```
+
+## Annual report with SVG charts and View tables
+
+The Fieldnote Studio annual report draws a grouped bar chart, a line chart with a
+gradient area tint, and a donut. It uses the [SVG primitives](/raw/docs/guides/svg-graphics.md),
+with every figure computed from one canonical `YearFigures` source. The donut
+segments come from a pure geometry model and render as a `v-for` of paths:
+
+```vue [pdfs/annual-report.vue]
+<PdfSvg :viewBox="`0 0 ${donut.size} ${donut.size}`" :style="{ width: donut.size, height: donut.size }">
+  <PdfPath
+    v-for="segment in donut.segments"
+    :key="segment.id"
+    :d="segment.d"
+    :fill="segment.fill"
+    :transform="segment.transform"
+  />
+</PdfSvg>
+```
+
+The financial statement has no first-class table primitive. It uses
+`View` rows with right-aligned tabular numerals, hairline rules above totals, and
+parenthesised outflows. The quarter and sector breakdowns provably sum to the
+yearly totals (asserted in the template's test).
+
+## Certificate with SVG ornaments
+
+The certificate is a single A4 landscape page whose decoration is drawn entirely
+from primitives: a double-rule engraver's border with corner diamonds, and a
+concentric seal with two rules, a 32-dot beaded coin edge, a five-point star, and a
+single bronze `RadialGradient` used once.
+
+```vue [pdfs/components/certificate/CertificateSeal.vue]
+<script setup lang="ts">
+// Evenly spaced dots in the band between the two rules.
+const beads = Array.from({ length: 32 }, (_, index) => {
+  const angle = (index / 32) * Math.PI * 2 - Math.PI / 2
+  return { cx: 50 + 45.2 * Math.cos(angle), cy: 50 + 45.2 * Math.sin(angle) }
+})
+</script>
+
+<template>
+  <PdfSvg view-box="0 0 100 100">
+    <PdfDefs>
+      <PdfRadialGradient id="seal-bronze" cx="0.5" cy="0.38" r="0.62">
+        <PdfStop offset="0" stop-color="#E7CC86" />
+        <PdfStop offset="0.55" stop-color="#C9A24B" />
+        <PdfStop offset="1" stop-color="#8A6A2F" />
+      </PdfRadialGradient>
+    </PdfDefs>
+    <PdfCircle
+      v-for="(bead, index) in beads"
+      :key="`bead-${index}`"
+      :cx="bead.cx"
+      :cy="bead.cy"
+      :r="0.75"
+    />
+  </PdfSvg>
+</template>
+```
+
+The decorative layers are absolutely positioned, so a long recipient name wraps
+at spaces to two centered lines and the page can never spill to a second sheet.
+
+## Menu with typography and diacritics
+
+The Gasthaus Alpenrose card is two A5 pages of typography without borders or
+boxes. German dish names carry their umlauts through rendering and extraction,
+and a flex-`1` dotted leader ties each name to a right-aligned tabular price:
+
+```vue [pdfs/menu.vue]
+<PdfView :style="{ alignItems: 'flex-end', flexDirection: 'row' }">
+  <PdfText :style="{ fontFamily: 'Inter', fontSize: 10, fontWeight: 600 }">
+    {{ dish.name }}
+  </PdfText>
+  <PdfView :style="{ flex: 1, marginHorizontal: 7, marginBottom: 2,
+    borderBottomWidth: 0.75, borderBottomStyle: 'dotted', borderBottomColor: leader }" />
+  <PdfText :style="{ fontFamily: 'Inter', fontSize: 10, textAlign: 'right', width: 32 }">
+    {{ formatMenuPrice(dish.price) }}
+  </PdfText>
+</PdfView>
+```
+
+Prices use the locale format. For example, `9.5` becomes `9,50`. The whole card
+is data-driven, so the `winter` scenario swaps every dish and pour without
+touching the template.
+
+<idea icon="lucide:lightbulb">
+Every template ships `sampleData` and at least one named `scenario`, so the dev
+preview at `/_pdf` can render each one without a live route. See
+[define-pdf](/raw/docs/reference/define-pdf.md) for the definition shape.
+</idea>

package/dist/agent/pages/docs/getting-started/installation.md

@@ -0,0 +1,75 @@
+---
+title: "Install Nuxt PDF"
+description: "Add server-side PDF rendering to an existing Nuxt 4 application."
+url: "https://nuxt-pdf.lupinum.com/docs/getting-started/installation"
+route: "/docs/getting-started/installation"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Install Nuxt PDF
+
+> Add server-side PDF rendering to an existing Nuxt 4 application.
+
+Nuxt PDF is a Nuxt module. It does not require a separate service or CLI.
+
+## Check the requirements
+
+| Layer | Supported versions |
+| --- | --- |
+| Node.js | `^22.14.0`, `^24.0.0`, or `^26.0.0` |
+| Nuxt | `^4.4.8` |
+| Vue | `^3.5.0` |
+
+Nuxt 3, Node 20, browser rendering, and edge rendering are outside the current
+support boundary.
+
+## Add the module
+
+Install the package:
+
+```bash [Terminal]
+pnpm add @lupinum/nuxt-pdf
+```
+
+Add it to `nuxt.config.ts`:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-pdf'],
+})
+```
+
+### Set up your coding agent
+
+Nuxt PDF ships its documentation inside the package, so coding agents read the
+pages that match the installed version. Give your coding agent this task:
+
+```text
+Set up @lupinum/nuxt-pdf for coding agents as described under "Agent setup" in its README.
+```
+
+The module now discovers Vue templates under `pdfs/`, generates the typed
+server-only `#pdf` registry, and adds the `/_pdf` development preview.
+
+<info icon="lucide:info">
+If your editor does not recognize `#pdf` after installation, run
+`pnpm nuxt prepare` once. Nuxt also refreshes the generated types when the
+development server starts.
+</info>
+
+Continue with [Render your first PDF](/raw/docs/getting-started/quickstart.md).
+
+## Add test dependencies later
+
+The optional test entry uses `pdfjs-dist` for semantic inspection and
+`@napi-rs/canvas` for raster comparisons. Install them only when you start
+testing PDF output:
+
+```bash [Terminal]
+pnpm add -D pdfjs-dist @napi-rs/canvas
+```
+
+The [testing guide](/raw/docs/guides/testing.md) shows the complete workflow.

package/dist/agent/pages/docs/getting-started/quickstart.md

@@ -0,0 +1,126 @@
+---
+title: "Render your first PDF"
+description: "Create, download, and preview a small invoice in a Nuxt application."
+url: "https://nuxt-pdf.lupinum.com/docs/getting-started/quickstart"
+route: "/docs/getting-started/quickstart"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Render your first PDF
+
+> Create, download, and preview a small invoice in a Nuxt application.
+
+This tutorial starts after you [install the module](/raw/docs/getting-started/installation.md).
+It creates one invoice from typed data and returns it from a Nitro route.
+
+<steps>
+### Create the invoice template
+
+Create `pdfs/invoice.vue` at the application root:
+
+```vue [pdfs/invoice.vue]
+<script setup lang="ts">
+type InvoiceProps = {
+  invoice: {
+    customer: string
+    number: string
+    total: string
+  }
+}
+
+const props = defineProps<InvoiceProps>()
+
+definePdf<InvoiceProps>({
+  title: ({ invoice }) => `Invoice ${invoice.number}`,
+  filename: ({ invoice }) => `invoice-${invoice.number}.pdf`,
+  sampleData: {
+    invoice: {
+      customer: 'Ada Lovelace',
+      number: 'INV-001',
+      total: 'EUR 1,250.00',
+    },
+  },
+})
+</script>
+
+<template>
+  <PdfDocument>
+    <PdfPage :style="{ fontSize: 11, padding: 48 }">
+      <PdfText :style="{ fontSize: 24, marginBottom: 24 }">
+        Invoice {{ props.invoice.number }}
+      </PdfText>
+      <PdfText>{{ props.invoice.customer }}</PdfText>
+      <PdfText :style="{ marginTop: 12 }">
+        Total: {{ props.invoice.total }}
+      </PdfText>
+    </PdfPage>
+  </PdfDocument>
+</template>
+```
+
+This is the minimum authoring contract:
+
+- Templates live under `pdfs/`.
+- The relative filename becomes the registry key. `pdfs/invoice.vue` becomes
+  `pdf.invoice`; `pdfs/reports/monthly.vue` becomes `pdf['reports/monthly']`.
+- Each template calls `definePdf()` exactly once.
+- The template has one `PdfDocument` root and at least one `PdfPage`.
+- Text belongs inside `PdfText`.
+- Props are typed with `defineProps()` and passed to `render()`.
+- Style keys use camelCase, such as `fontSize` and `marginBottom`.
+- `sampleData` and preview scenarios exist only in development.
+
+### Add a Nitro route
+
+Create `server/api/invoice.get.ts`:
+
+```ts [server/api/invoice.get.ts]
+import { pdf } from '#pdf'
+
+export default defineEventHandler(async () => {
+  const result = await pdf.invoice.render({
+    invoice: {
+      customer: 'Ada Lovelace',
+      number: 'INV-001',
+      total: 'EUR 1,250.00',
+    },
+  })
+
+  return result.response()
+})
+```
+
+`#pdf` is generated from the files under `pdfs/`. Its `render()` method infers
+the props from the matching Vue template. It is available to server code only.
+
+### Start Nuxt
+
+Run the application's normal development command:
+
+```bash [Terminal]
+pnpm dev
+```
+
+### Download the result
+
+Keep the development server running. In another terminal, download the PDF:
+
+```bash [Terminal]
+curl -o invoice.pdf http://localhost:3000/api/invoice
+```
+
+Open `invoice.pdf` in a PDF viewer. The route sends `application/pdf` with the
+filename resolved by `definePdf()`.
+
+### Open the development preview
+
+Open `http://localhost:3000/_pdf/invoice`. The preview uses `sampleData` and
+shows render diagnostics. The `/_pdf` routes and preview data do not exist in a
+production build.
+</steps>
+
+The next useful concepts are [templates and the registry](/raw/docs/learn/templates-and-registry.md)
+and [the document tree](/raw/docs/learn/document-tree.md).