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

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

@@ -0,0 +1,63 @@
+---
+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>
+
+Questions? Ask in the [Lupinum OSS Discord](https://discord.lupinum.com).

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.

package/dist/agent/pages/docs/guides/images-and-fonts.md

@@ -0,0 +1,102 @@
+---
+title: "Add images and fonts"
+description: "Bundle local PNG, JPEG, TTF, OTF, and WOFF2 resources with a PDF template."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/images-and-fonts"
+route: "/docs/guides/images-and-fonts"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Add images and fonts
+
+> Bundle local PNG, JPEG, TTF, OTF, and WOFF2 resources with a PDF template.
+
+Keep local images under `pdfs/assets` and fonts under `pdfs/fonts`. Nuxt PDF
+validates and embeds them in the Nitro server output.
+
+In development, each render reads and validates local image files again.
+Image edits take effect without restarting the server.
+
+## Add a local image
+
+Put a PNG or JPEG in `pdfs/assets`. Set `PdfImage.src` to the path relative to
+that directory:
+
+```vue
+<PdfImage
+  src="brand/logo.png"
+  :style="{ height: 40, objectFit: 'contain', width: 120 }"
+/>
+```
+
+Public rendering accepts local paths, admitted PNG or JPEG byte sources, and
+allowlisted HTTPS URLs. It blocks `data:` URL strings, absolute filesystem
+paths, parent traversal, symlink escapes, and SVG files used as image sources.
+
+Use [`PdfSvg`](/raw/docs/guides/svg-graphics.md) for vector graphics authored in the
+document tree.
+
+## Register a local font
+
+Put a TTF, OTF, or WOFF2 file in `pdfs/fonts`, then register one entry for each weight
+and style used by the document:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-pdf'],
+  pdf: {
+    fonts: [
+      {
+        family: 'Invoice Sans',
+        src: 'InvoiceSans-Regular.ttf',
+        fontStyle: 'normal',
+        fontWeight: 400,
+      },
+      {
+        family: 'Invoice Sans',
+        src: 'InvoiceSans-Bold.ttf',
+        fontStyle: 'normal',
+        fontWeight: 700,
+      },
+    ],
+  },
+})
+```
+
+Set the family on a parent so text descendants inherit it:
+
+```vue
+<PdfPage :style="{ fontFamily: 'Invoice Sans' }">
+  <PdfText>Invoice</PdfText>
+</PdfPage>
+```
+
+If a requested family, weight, or style was not registered, rendering fails
+with `PDF_LAYOUT_ERROR`. If the configured file is invalid, module setup throws
+a `TypeError` before a template render starts.
+
+## Check language coverage
+
+A font must contain the glyphs used by the document. Latin Extended, Greek,
+Cyrillic, and custom hyphenation are covered by the tested corpus with supplied
+fonts. CJK, combining marks, Arabic, bidirectional text, and variable fonts need
+application-specific semantic and raster tests. Emoji and fallback font chains
+are not supported; use an admitted image for an emoji graphic.
+
+## Resource validation
+
+The module checks four things:
+
+- **Structure:** images must decode as PNG or JPEG; fonts need a valid TTF, OTF,
+  or WOFF2 structure and matching extension.
+- **Size:** a local image is limited to 10 MB and a font to 5 MB.
+- **Location:** the resolved path must remain inside its declared root.
+- **Embedding:** validated bytes travel in the Nitro server output, so
+  production rendering does not read these files from disk.
+
+Development reloads local image bytes for the next preview render. The
+[module-options reference](/raw/docs/reference/module-options.md) lists the exact font
+fields. Use the [remote-image guide](/raw/docs/guides/remote-images.md) for HTTPS
+sources.