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

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

@@ -0,0 +1,90 @@
+---
+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'],
+})
+```
+
+### Use a coding agent
+
+A coding agent is a development tool that can inspect and change your project.
+After installation, copy this prompt into your coding agent:
+
+```text
+Add Nuxt PDF to this Nuxt application and render one PDF from a Vue template.
+Read the project's existing instructions first. Resolve
+@lupinum/nuxt-pdf/agent-docs from this application's directory and read its
+starting pages. Use the installed version's examples and public types. Preserve
+existing routes, security limits, conventions, and AGENTS.md instructions. Add
+or update one short Nuxt PDF pointer in AGENTS.md if the project allows it; do
+not duplicate the documentation. If the file is absent, create only that
+pointer. Report missing guidance. Verify the server route, PDF output, and one
+invalid request.
+```
+
+If the installed package has no `agent-docs` export, read its packaged README,
+types, and `CONFORMANCE.md`. Use documentation from the matching source tag when
+more detail is needed. Installing or updating the package does not edit project
+instructions. The pointer resolves the installed package, so upgrades and
+rollbacks select the matching documentation without copying it into your
+application.
+
+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).

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

@@ -0,0 +1,61 @@
+---
+title: "Overview"
+description: "Decide whether Nuxt PDF fits the document you need to create."
+url: "https://nuxt-pdf.lupinum.com/docs/getting-started"
+route: "/docs/getting-started"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Overview
+
+> Decide whether Nuxt PDF fits the document you need to create.
+
+Nuxt PDF turns Vue components into PDFs on a Nuxt server. Put a typed Vue
+template in `pdfs/`, pass it data from a Nitro route, and return the completed
+PDF response.
+
+Use Nuxt PDF when you control a structured, data-driven document:
+
+- invoices, quotes, and receipts;
+- reports and statements;
+- certificates, tickets, and labels.
+
+The package provides PDF layout primitives, local images and fonts, SVG
+graphics, links, bookmarks, tables of contents, development previews, and test
+helpers. Templates run on Node and stay out of the browser bundle.
+
+## Pick the right rendering tool
+
+Pick a different tool when:
+
+- **You want to print an existing web page.** Use headless Chromium through
+  Playwright or Puppeteer. Nuxt PDF does not compile HTML or browser CSS.
+- **You want to display an existing PDF.** Use
+  [PDF.js](https://mozilla.github.io/pdf.js/). Nuxt PDF creates files; it is not
+  a viewer.
+- **You want to edit, merge, fill, or sign an existing PDF.** Use
+  [pdf-lib](https://pdf-lib.js.org/) or a signing service. Nuxt PDF creates new
+  documents from application data.
+
+## Current scope
+
+Nuxt PDF is in public beta. A minor release can contain a documented
+breaking change before version 1.0.
+
+The current release does not include an HTML or CSS compiler, a table engine, a
+chart engine, form fields, signing, tagged PDF output, browser rendering, or
+edge rendering. It does not promise byte-identical output across machines.
+
+The [supported behavior](/raw/docs/examples/supported-behavior.md) page summarizes the
+tested boundary. The repository's
+[CONFORMANCE.md](https://github.com/lupinum-dev/nuxt-pdf/blob/main/CONFORMANCE.md)
+contains the maintainer-grade evidence.
+
+<cards cols="2">
+<card title="Install Nuxt PDF" description="Add the module to a Nuxt 4 application." icon="lucide:download" to="/docs/getting-started/installation" />
+
+<card title="Render your first PDF" description="Create and download a small invoice." icon="lucide:rocket" to="/docs/getting-started/quickstart" />
+</cards>

package/dist/agent/pages/docs/guides/contents-links-bookmarks.md

@@ -0,0 +1,123 @@
+---
+title: "Add links, bookmarks, and a table of contents"
+description: "usePdfPageNumbers, the multi-pass layout loop, convergence and maxPasses, internal links, and the bookmark outline."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/contents-links-bookmarks"
+route: "/docs/guides/contents-links-bookmarks"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Add links, bookmarks, and a table of contents
+
+> usePdfPageNumbers, the multi-pass layout loop, convergence and maxPasses, internal links, and the bookmark outline.
+
+Nuxt PDF builds a table of contents, internal links, and a bookmark outline from
+ordinary components. There is no TOC component and no automatic heading
+collection. You author the list, and the engine resolves the page numbers.
+
+## Named destinations and internal links
+
+Give any primitive an `id` to make it a named destination, then link to it with
+`<PdfLink href="#id">`:
+
+```vue
+<PdfText id="terms">Terms &amp; conditions</PdfText>
+
+<PdfLink href="#terms">Jump to terms</PdfLink>
+```
+
+Internal `#id` links resolve **by name in a single pass**. They do not trigger
+the multi-pass loop and add no cost. A `#id` that does not match any destination
+in the mounted document fails the render with `PDF_TREE_INVALID`.
+The link and destination must both exist in the initial mounted tree and after
+every page-number update; do not conditionally create a destination only after
+its page number becomes available.
+
+<info icon="lucide:info">
+When an `id` sits on a node that spans a page boundary, both the printed page
+number and the jump target resolve to the section's **first** page. This is a
+deliberate divergence from React PDF, whose last-writer-wins table points at the
+last page.
+</info>
+
+## Printing page numbers: usePdfPageNumbers
+
+To print the page a destination lands on, read the auto-imported
+`usePdfPageNumbers()` composable. It returns a readonly, reactive map from `id`
+to its 1-based page:
+
+```vue
+<script setup lang="ts">
+const pageNumbers = usePdfPageNumbers()
+
+const entries = sections.map(s => ({ id: s.id, title: s.title }))
+</script>
+
+<template>
+  <PdfLink
+    v-for="entry in entries"
+    :key="entry.id"
+    :href="`#${entry.id}`"
+  >
+    {{ entry.title }} {{ pageNumbers[entry.id] ?? '' }}
+  </PdfLink>
+</template>
+```
+
+Reading the composable is the **only** signal that turns on multi-pass layout.
+The engine lays out the document once per pass. Each pass feeds its destination
+page map into the next pass until the map stops changing.
+
+<warning icon="lucide:triangle-alert">
+On the first pass every entry is `undefined`. Always keep a fallback
+(`pageNumbers[id] ?? ''`) so the first pass renders a blank rather than throwing.
+</warning>
+
+Calling `usePdfPageNumbers()` outside a PDF render throws, rather than returning
+an empty map that could be mistaken for first-pass state.
+
+## Convergence and maxPasses
+
+The loop is a fixed point. An ordinary table of contents converges in **two
+passes**: pass one fills the numbers in, pass two lays out with them and the map
+no longer changes.
+
+A document does not converge if its layout depends on the page numbers that it prints.
+For example, a TOC entry can change height when its page number changes. After `maxPasses`
+(a validated positive integer on `definePdf`, default 5) the render fails with a
+`PDF_LIMIT_EXCEEDED` `NuxtPdfError`, attributed to the template:
+
+```ts
+definePdf<Props>({
+  // Raise the cap only if a genuinely convergent document needs more passes.
+  maxPasses: 8,
+})
+```
+
+Non-convergence fails closed; the loop does not force a wrong answer. Raise
+`maxPasses` only when you know the document actually settles.
+
+## Bookmarks (the outline)
+
+Add a `bookmark` to any of `PdfPage`, `PdfView`, `PdfText`, or `PdfImage` to
+build the PDF outline. The value is a title string, or an object:
+
+```vue
+<PdfView :id="section.id" :bookmark="{ title: section.title, expanded: true }">
+  <PdfText :id="sub.id" :bookmark="sub.title">{{ sub.title }}</PdfText>
+</PdfView>
+```
+
+Nesting follows the component tree, so a child's bookmark nests under its
+ancestor's. The outline carries title text, its initially expanded state, and
+parent/child nesting. Nuxt PDF does not expose reader page-mode preferences or
+bookmark destination geometry (`top`/`left`/`zoom`/`fit`).
+
+## A full example
+
+`playground/pdfs/report.vue` in the repository demonstrates the whole feature: a
+contents page linking to each section, live page numbers, per-section bookmarks,
+and a fixed footer with a dynamic page counter. The engine resolves all these features through the
+multi-pass loop.

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

@@ -0,0 +1,118 @@
+---
+title: "Deploy and operate"
+description: "Size, cache, queue, and monitor PDF rendering on a tested Node target."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/deployment"
+route: "/docs/guides/deployment"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Deploy and operate
+
+> Size, cache, queue, and monitor PDF rendering on a tested Node target.
+
+Nuxt PDF renders on Node. The engine, the templates, and the embedded assets
+live in the Nitro server output. The client bundle contains none of them.
+For a separate Node worker, use the
+[standalone registry build](/raw/docs/guides/standalone-node.md).
+
+## Pick a runtime
+
+| Runtime | Support | Notes |
+| --- | --- | --- |
+| Node server (default Nitro preset) | Supported | The tested path. Use it for high-volume or large documents. |
+| Standalone Node registry | Locally tested | Compile with the build entry. Test the deployed worker before production use. |
+| Convex Node action | Not deployment-verified | A candidate for the standalone registry. Measure bundle size, memory, and execution limits on the target deployment. |
+| Vercel serverless build | Build-verified | The package test verifies the Vercel Nitro output. Execute your deployed function before production use. |
+| Other Node serverless functions | Expected, not verified | Use a Node-compatible Nitro preset and test the deployed runtime. |
+| Edge workers | Not supported | The engine needs Node APIs. Do not target edge presets. |
+
+## Size the memory budget
+
+One render holds the document tree, the laid-out pages, and the output bytes in
+memory at the same time. Give each function or container headroom above your
+largest expected document:
+
+- Start from `pdf.limits.maxOutputBytes` (64 MB by default) plus the tree and
+  image budgets.
+- Lower `pdf.limits.maxPages` and `pdf.limits.maxOutputBytes` to cap the worst
+  case for untrusted input.
+- Load-test with your real templates before you pick an instance size.
+
+## Align timeouts
+
+The render deadline lives in `pdf.limits.timeoutMs` (30 seconds by default).
+The platform timeout must stay longer than that budget, or the platform kills
+a render that Nuxt PDF would have finished.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  pdf: {
+    limits: {
+      timeoutMs: 10_000,
+    },
+  },
+})
+```
+
+Set the platform function timeout to at least the same value plus queueing
+headroom.
+
+## Cache completed renders
+
+Cache a PDF only when your application controls every input to the render. A
+template can read the current time or imported application code. An allowlisted
+remote image can also change without a props change. Nuxt PDF does not promise
+that these renders produce the same bytes.
+
+Build the cache key from the template version and the canonical render inputs.
+Include the tenant or authorization boundary when documents differ between
+customers. Store the completed bytes in a bounded cache, object store, or CDN
+with an explicit expiry and invalidation rule.
+
+Do not use a module-level `Map` as a production cache. It has no size limit,
+does not persist reliably across serverless invocations, and can cross request
+boundaries when its key is incomplete.
+
+## Queue long documents
+
+A 200-page report can occupy a worker for seconds. Keep that work off the
+request path when you can:
+
+1. Accept the request and return a job identifier.
+2. Render in a background worker.
+3. Store the bytes and let the client poll or subscribe.
+
+This pattern also keeps interactive routes responsive while batch jobs run.
+
+## Serverless notes
+
+Local fonts and images travel inside the server bundle as validated bytes. The
+repository verifies the Vercel output structure but does not execute that
+deployed function. Test the real target before you send production traffic.
+
+- **Bundle size.** Every font and image under `pdfs/` adds to the bundle.
+  Remove assets that no template uses; the module embeds only discovered
+  files.
+- **Cold starts.** The first invoke parses the bundle. Fewer embedded assets
+  mean faster cold starts.
+- **Concurrency.** Size concurrency from load tests on your deployed runtime.
+  Nuxt PDF does not currently claim cross-render concurrency guarantees.
+- **Filesystem access.** Templates read no files at runtime. Do not add code
+  that reads from the deployment filesystem during a render.
+
+## Monitor renders
+
+Every render returns content-free diagnostics: duration, byte length, page
+count, layout passes, layout warnings, and registered font faces. Log them next
+to your request logs to spot slow or oversized documents before users do.
+
+```ts [server/api/invoice.get.ts]
+export default defineEventHandler(async () => {
+  const result = await pdf.invoice.render(props)
+  console.info('invoice rendered', result.diagnostics)
+  return result.response()
+})
+```

package/dist/agent/pages/docs/guides/errors-and-debugging.md

@@ -0,0 +1,90 @@
+---
+title: "Diagnose render failures"
+description: "Use template attribution, preview diagnostics, and exact error messages to recover from a failed render."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/errors-and-debugging"
+route: "/docs/guides/errors-and-debugging"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Diagnose render failures
+
+> Use template attribution, preview diagnostics, and exact error messages to recover from a failed render.
+
+First identify whether the failure happens during module setup or during
+`render()`.
+
+- Setup validates configuration, template definitions, local images, and
+  fonts. Invalid setup can throw `TypeError` before a template render exists.
+- Render failures use `NuxtPdfError` with a machine-readable `code` and
+  `templateKey`. Development also includes the relative `templateFile`.
+
+The [errors and limits reference](/raw/docs/reference/errors-and-limits.md) defines
+every code and default budget.
+
+## Inspect a render error
+
+```ts [server/api/report.get.ts]
+import { NuxtPdfError, pdf } from '#pdf'
+
+export default defineEventHandler(async () => {
+  try {
+    const result = await pdf.report.render(props)
+    return result.response()
+  }
+  catch (error) {
+    if (error instanceof NuxtPdfError) {
+      console.error(error.code, error.templateKey, error.templateFile)
+    }
+    throw error
+  }
+})
+```
+
+Log identifiers and diagnostics through the application's normal error system.
+Do not log render props or document text unless the application has a separate
+data-handling policy for them.
+
+## Use the development preview
+
+Open `/_pdf/<template-key>`. The preview renders through the same public
+template method as server code and shows duration, byte length, page count,
+layout passes, and registered font faces.
+
+When a render fails, the preview keeps document content out of the error panel.
+It shows the code, template, relative source path, and a short message. If the
+previous render succeeded, the old PDF stays visible with a stale marker.
+
+## Match the message to a fix
+
+| Message or code | Inspect or change |
+| --- | --- |
+| `Cannot find module '#pdf'` or an untyped import | Run `pnpm nuxt prepare` or restart the development server. |
+| `/_pdf` returns 404 | Use the preview only in development. It is absent from production output. |
+| `PDF_TEMPLATE_NOT_FOUND` | Check the relative filename and registry key. Nested keys retain `/`. |
+| `PDF_TREE_INVALID` | Read the named primitive and prop or nesting rule. Remove DOM attributes and put text inside `PdfText`. |
+| `Font family not registered` | Register the requested family, weight, and style in `pdf.fonts`. |
+| A font throws `TypeError` during setup | Check its relative path, extension, signature, size, and location under `pdfs/fonts`. |
+| `PDF_ASSET_BLOCKED` | Check the image source type, HTTPS allowlist, redirects, and timeout. |
+| `PDF_ASSET_INVALID` | Replace the admitted bytes with a valid PNG or JPEG of the declared format. |
+| `PDF_LIMIT_EXCEEDED` | Read the named limit and cap. Reduce the input or raise only that limit for a known document. |
+
+For `maxPasses`, fix layout that changes when destination page numbers appear.
+Raising the cap does not make unstable geometry converge. See the
+[table-of-contents guide](/raw/docs/guides/contents-links-bookmarks.md).
+
+## Monitor successful renders
+
+Every completed result includes immutable metadata and diagnostics. Record
+duration, output bytes, page count, layout passes, layout warnings, and
+registered font faces.
+
+The development preview explains each layout warning. For example, an
+unbreakable `PdfView` that is taller than the page can render with overflow;
+the preview names the page, node type, node height, and usable page height.
+This is a warning rather than a render failure because the output is still a
+valid PDF and some authors intentionally use oversized pages.
+The failure shows up in a customer's invoice, not a test run. Alert on trends
+before time or output budgets become routine failures.