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

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.

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

@@ -0,0 +1,258 @@
+---
+title: "Production recipes"
+description: "Copyable Vue patterns for invoices, statements, reports, repeating matter, and payment QR codes."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/recipes"
+route: "/docs/guides/recipes"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Production recipes
+
+> Copyable Vue patterns for invoices, statements, reports, repeating matter, and payment QR codes.
+
+These are application recipes, not extra framework primitives. They compose the
+same small `PdfView`/`PdfText` surface used by the tested playground documents.
+
+Use this page as a pattern index:
+
+- [Repeating header, footer, and page numbers](#repeating-header-footer-and-page-numbers)
+- [Address and key/value blocks](#address-or-party-block)
+- [Invoice lines, totals, and shared table columns](#invoice-lines-and-totals)
+- [Dot leaders](#dot-leaders-for-contents-and-price-lists)
+- [Payment details and QR graphics](#payment-details-and-qr)
+- [Headings and continuation headers](#keep-a-heading-with-what-follows)
+- [Reports with a table of contents](#report-sections-and-a-table-of-contents)
+
+Read [Build reusable document components](/raw/docs/guides/reusable-components.md)
+before turning a recipe into a shared component. Exact style values remain in
+the [style reference](/raw/docs/reference/styles.md).
+
+## Repeating header, footer, and page numbers
+
+A `fixed` node repeats when one authored page wraps into multiple output pages.
+Keep the page padding large enough that flowing content never overlaps it.
+
+```vue
+<PdfPage :style="{ paddingBottom: 52, paddingHorizontal: 40, paddingTop: 64 }">
+  <PdfView fixed :style="{ left: 40, position: 'absolute', right: 40, top: 24 }">
+    <PdfText>Quarterly statement</PdfText>
+  </PdfView>
+  <PdfText
+    fixed
+    :render="({ pageNumber, totalPages }) => `Page ${pageNumber} / ${totalPages}`"
+    :style="{ bottom: 24, position: 'absolute', right: 40 }"
+  />
+  <slot />
+</PdfPage>
+```
+
+## Address or party block
+
+Use a typed child component so the invoice template remains readable.
+
+```vue [pdfs/components/PartyBlock.vue]
+<script setup lang="ts">
+defineProps<{ label: string, lines: string[] }>()
+</script>
+
+<template>
+  <PdfView :style="{ width: 220 }">
+    <PdfText :style="{ color: '#68736B', fontSize: 8, marginBottom: 6 }">
+      {{ label }}
+    </PdfText>
+    <PdfText v-for="line in lines" :key="line" :style="{ fontSize: 10 }">
+      {{ line }}
+    </PdfText>
+  </PdfView>
+</template>
+```
+
+## Key/value details
+
+Keep widths explicit; PDF rows should not depend on browser table layout.
+
+```vue
+<PdfView
+  v-for="entry in details"
+  :key="entry.label"
+  :style="{ flexDirection: 'row', marginBottom: 6 }"
+>
+  <PdfText :style="{ color: '#68736B', width: 110 }">{{ entry.label }}</PdfText>
+  <PdfText :style="{ flex: 1 }">{{ entry.value }}</PdfText>
+</PdfView>
+```
+
+## Invoice lines and totals
+
+Make each line indivisible with `wrap="false"`; keyed rows then move as a unit
+instead of losing a description or amount at a page break.
+
+```vue
+<PdfView
+  v-for="line in invoice.lines"
+  :key="line.id"
+  :wrap="false"
+  :style="{ borderBottomColor: '#DDE3DE', borderBottomWidth: 1, flexDirection: 'row', paddingVertical: 10 }"
+>
+  <PdfText :style="{ flex: 1 }">{{ line.description }}</PdfText>
+  <PdfText :style="{ textAlign: 'right', width: 90 }">{{ money(line.total) }}</PdfText>
+</PdfView>
+<PdfView :wrap="false" :style="{ marginLeft: 'auto', marginTop: 16, width: 220 }">
+  <PdfText :style="{ fontWeight: 700, textAlign: 'right' }">Total {{ money(total) }}</PdfText>
+</PdfView>
+```
+
+## Tables with a shared column spec
+
+A table is a column of rows. Give every row the same `flexDirection: 'row'`
+and fixed cell widths, and put those widths in one module. The header and the
+body then cannot drift apart when a column changes.
+
+```ts [pdfs/components/columns.ts]
+export const columns = {
+  amount: { align: 'right', width: 86 },
+  description: { width: 246 },
+  quantity: { align: 'right', width: 52 },
+} as const
+```
+
+```vue
+<PdfView :style="{ flexDirection: 'row', paddingBottom: 8 }" :wrap="false">
+  <PdfText :style="{ fontSize: 7, width: columns.description.width }">Description</PdfText>
+  <PdfText :style="{ fontSize: 7, textAlign: 'right', width: columns.quantity.width }">Qty</PdfText>
+  <PdfText :style="{ fontSize: 7, textAlign: 'right', width: columns.amount.width }">Amount</PdfText>
+</PdfView>
+<PdfView
+  v-for="line in invoice.lines"
+  :key="line.id"
+  :wrap="false"
+  :style="{ borderBottomColor: '#DDE3DE', borderBottomWidth: 1, flexDirection: 'row', paddingVertical: 10 }"
+>
+  <PdfText :style="{ flex: 1 }">{{ line.description }}</PdfText>
+  <PdfText :style="{ textAlign: 'right', width: columns.amount.width }">{{ money(line.total) }}</PdfText>
+</PdfView>
+```
+
+Keep body cells inside a `wrap="false"` row so a long line moves as a unit.
+
+## Dot leaders for contents and price lists
+
+A dotted rule that stretches between a label and a number is one view with a
+dotted bottom border. Wrap each entry in a row with `alignItems: 'flex-end'`
+and let the leader take the remaining space:
+
+```vue [pdfs/components/common/DotLeader.vue]
+<script setup lang="ts">
+defineProps<{
+  baseline?: number
+  color: string
+  gap?: number
+  width?: number
+}>()
+</script>
+
+<template>
+  <PdfView
+    :style="{
+      borderBottomColor: color,
+      borderBottomStyle: 'dotted',
+      borderBottomWidth: width ?? 1,
+      flex: 1,
+      marginBottom: baseline ?? 3,
+      marginHorizontal: gap ?? 7,
+    }"
+  />
+</template>
+```
+
+```vue
+<PdfView :style="{ alignItems: 'flex-end', flexDirection: 'row' }">
+  <PdfText>{{ section.title }}</PdfText>
+  <DotLeader color="#CDD5CF" />
+  <PdfText>{{ pageNumbers[section.id] ?? '' }}</PdfText>
+</PdfView>
+```
+
+The `baseline` offset sits the dots on the text baseline; start at `2` to `4`
+and adjust against your font size.
+
+## Payment details and QR
+
+Generate the payment payload in setup code, turn consecutive dark QR modules
+into one SVG path, and keep the payment panel together with `wrap="false"`.
+
+```vue
+<PdfView :wrap="false" :style="{ flexDirection: 'row', marginTop: 20 }">
+  <PdfView :style="{ flex: 1 }">
+    <PdfText>IBAN {{ payment.iban }}</PdfText>
+    <PdfText>BIC {{ payment.bic }}</PdfText>
+    <PdfText>Reference {{ invoice.number }}</PdfText>
+  </PdfView>
+  <PdfSvg :viewBox="`0 0 ${qrSize} ${qrSize}`" :style="{ height: 72, width: 72 }">
+    <PdfPath :d="qrPath" fill="#000000" />
+  </PdfSvg>
+</PdfView>
+```
+
+## Keep a heading with what follows
+
+`minPresenceAhead` asks pagination to move the heading when too little usable
+space remains. Use `wrap="false"` only when the whole section is genuinely
+small enough to fit on a page.
+
+```vue
+<PdfView :style="{ marginTop: 24 }">
+  <PdfText :min-presence-ahead="54" :style="{ fontSize: 15, marginBottom: 10 }">
+    Payment terms
+  </PdfText>
+  <PdfText>{{ terms }}</PdfText>
+</PdfView>
+```
+
+## Long rows with continuation headers
+
+Put the header and rows in one wrapping page. The fixed header repeats on every
+continuation page; page padding reserves its space.
+
+```vue
+<PdfPage :style="{ paddingHorizontal: 40, paddingTop: 72 }">
+  <PdfView fixed :style="{ flexDirection: 'row', left: 40, position: 'absolute', right: 40, top: 36 }">
+    <PdfText :style="{ flex: 1 }">Description</PdfText>
+    <PdfText :style="{ textAlign: 'right', width: 90 }">Amount</PdfText>
+  </PdfView>
+  <InvoiceLine v-for="line in lines" :key="line.id" :line="line" />
+</PdfPage>
+```
+
+## Report sections and a table of contents
+
+Read the page map only where the document needs it. The first pass returns no
+number, so keep an empty fallback; Nuxt PDF rerenders until the map stabilizes.
+
+```vue
+<script setup lang="ts">
+const pageNumbers = usePdfPageNumbers()
+</script>
+
+<template>
+  <PdfPage>
+    <PdfLink v-for="section in sections" :key="section.id" :href="`#${section.id}`">
+      {{ section.title }} ..... {{ pageNumbers[section.id] ?? '' }}
+    </PdfLink>
+  </PdfPage>
+  <PdfPage v-for="section in sections" :key="section.id">
+    <PdfView :id="section.id" :bookmark="section.title">
+      <PdfText :style="{ fontSize: 22 }">{{ section.title }}</PdfText>
+      <PdfText>{{ section.body }}</PdfText>
+    </PdfView>
+  </PdfPage>
+</template>
+```
+
+The [links and table-of-contents guide](/raw/docs/guides/contents-links-bookmarks.md)
+explains convergence and invalid destinations. Use the
+[testing guide](/raw/docs/guides/testing.md) to protect document text, links, page
+counts, and reviewed raster output.

package/dist/agent/pages/docs/guides/remote-images.md

@@ -0,0 +1,72 @@
+---
+title: "Configure remote images"
+description: "Admit specific HTTPS image paths and understand the request boundary."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/remote-images"
+route: "/docs/guides/remote-images"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Configure remote images
+
+> Admit specific HTTPS image paths and understand the request boundary.
+
+Remote image fetching is off by default. Enable it only for HTTPS locations
+that the application operator controls or trusts.
+
+## Add an allowlist
+
+Configure exact URL prefixes with a trailing slash:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-pdf'],
+  pdf: {
+    remote: {
+      allow: [
+        'https://cdn.example.com/brand/',
+        'https://images.example.com/logos/',
+      ],
+      timeoutMs: 10_000,
+    },
+  },
+})
+```
+
+Use an admitted URL in the template:
+
+```vue
+<PdfImage
+  src="https://cdn.example.com/brand/logo.png"
+  :style="{ height: 40, width: 120 }"
+/>
+```
+
+The module follows at most three redirects and checks the allowlist at each
+hop. An allowed host cannot redirect to a disallowed location.
+
+## Understand the boundary
+
+- Allowlist entries use `https://host/path/`. Wildcards, credentials, query
+  strings, fragments, and missing trailing slashes are rejected.
+- Requested image URLs can contain a query, but errors do not include it.
+- Requests use `GET` without application headers, cookies, or credentials.
+- PNG and JPEG signatures and dimensions are checked before layout. A response
+  `Content-Type` cannot admit other bytes.
+- Per-image bytes, total bytes, decoded pixels, request count, concurrency, and
+  the full render deadline use the shared `pdf.limits` budget.
+- Duplicate URLs are fetched once per render. No cross-render image cache is
+  promised.
+
+<warning icon="lucide:shield-alert">
+The allowlist controls hosts and paths. It does not provide private-IP or
+DNS-rebinding protection. Do not allow user-controlled hosts. Authenticated
+requests, custom headers, proxies, and remote fonts are not supported.
+</warning>
+
+`PDF_ASSET_BLOCKED` means the source form, allowlist, redirect, or timeout
+policy rejected the request. `PDF_ASSET_INVALID` means admitted bytes were not a
+valid PNG or JPEG. Size and request-budget failures use `PDF_LIMIT_EXCEEDED`.
+See [Errors and limits](/raw/docs/reference/errors-and-limits.md) for the exact codes.

package/dist/agent/pages/docs/guides/reusable-components.md

@@ -0,0 +1,81 @@
+---
+title: "Build reusable document components"
+description: "Organize repeated PDF sections without creating a second component system."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/reusable-components"
+route: "/docs/guides/reusable-components"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Build reusable document components
+
+> Organize repeated PDF sections without creating a second component system.
+
+PDF components are ordinary local Vue components whose rendered roots are Nuxt
+PDF primitives. Extract a component when it owns a meaningful document section
+or repeats in more than one place.
+
+## Keep ownership visible
+
+Put document-specific components next to their document family:
+
+```bash [Application files]
+pdfs/
+├── invoice.vue
+└── components/
+    └── invoice/
+        ├── InvoiceAddress.vue
+        ├── InvoiceLine.vue
+        └── columns.ts
+```
+
+Move a component to `pdfs/components/` only when several templates use it. This
+keeps invoice-specific decisions out of a generic component API.
+
+## Pass typed document data
+
+```vue [pdfs/components/invoice/InvoiceAddress.vue]
+<script setup lang="ts">
+defineProps<{
+  label: string
+  lines: string[]
+}>()
+</script>
+
+<template>
+  <PdfView>
+    <PdfText :style="{ fontSize: 8, marginBottom: 4 }">
+      {{ label }}
+    </PdfText>
+    <PdfText v-for="line in lines" :key="line">
+      {{ line }}
+    </PdfText>
+  </PdfView>
+</template>
+```
+
+Import it directly in the template. Use keyed `v-for`, slots, and `v-if` as you
+would in another Vue component. Do not pass DOM attributes such as `class` or
+`aria-*`; the PDF tree has no DOM.
+
+## Share table geometry
+
+Put widths used by both a header and row in one TypeScript module:
+
+```ts [pdfs/components/invoice/columns.ts]
+export const invoiceColumns = {
+  description: '58%',
+  quantity: '14%',
+  price: '14%',
+  total: '14%',
+} as const
+```
+
+A table is a column of rows. Give the header and every row the same
+`flexDirection: 'row'` and column widths. The header and body then cannot drift
+apart.
+
+The [production recipes](/raw/docs/guides/recipes.md) show address blocks, shared
+columns, totals, continuation headers, and table-of-contents patterns.

package/dist/agent/pages/docs/guides/standalone-node.md

@@ -0,0 +1,107 @@
+---
+title: "Render outside Nitro"
+description: "Compile PDF templates once and render the generated registry in a Node worker."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/standalone-node"
+route: "/docs/guides/standalone-node"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Render outside Nitro
+
+> Compile PDF templates once and render the generated registry in a Node worker.
+
+Use the standalone build when a Node worker owns document rendering outside
+Nitro. Keep the Nuxt module for authoring and preview. Both paths use the same
+compiler, resource admission, registry, and PDF engine.
+
+## Build the registry
+
+Keep trusted templates in `pdfs/` at the application root. Import application
+helpers explicitly with relative paths. The standalone build does not read
+Nuxt configuration, aliases, auto-imports, or layer configuration. PDF primitives,
+`definePdf`, and `usePdfPageNumbers` remain available in templates.
+Package imports must provide compiled JavaScript. Do not import source-only
+packages or add runtime filesystem reads to templates or their helpers.
+
+```ts [scripts/build-pdfs.mjs]
+import { buildPdfRegistry } from '@lupinum/nuxt-pdf/build'
+
+await buildPdfRegistry({
+  rootDir: process.cwd(),
+  outDir: './generated/pdfs',
+  fonts: [{ family: 'Invoice Sans', src: 'Roboto-Regular.ttf' }],
+  limits: { maxPages: 100, maxOutputBytes: 8_000_000 },
+})
+```
+
+Put the configured font in `pdfs/fonts/`. Put local images in `pdfs/assets/`.
+Remove the `fonts` option if the templates use only built-in fonts.
+
+Run this script before the backend build:
+
+```bash
+node scripts/build-pdfs.mjs
+```
+
+The output directory contains `index.mjs`, `index.d.mts`, a `types/` declaration
+tree, and an ownership marker. Deploy the generated runtime and its package
+dependencies. Keep the declarations for backend type checking. No Vue source,
+test loader, or build compiler is needed to execute this generated registry.
+The build tools remain package dependencies but are not imported by the runtime.
+
+Use a dedicated output directory inside the application. Never put hand-written
+files in it. Successful rebuilds replace its generated contents. Compilation
+failures preserve the previous output. An existing nonempty directory without
+the ownership marker is rejected. Choose another directory after this error.
+Do not run concurrent builds into one output directory.
+
+## Render validated data
+
+The generated `pdf`, `renderPdf`, `getPdfTemplate`, and `pdfTemplateKeys` exports
+have the same behavior as the [Nitro registry](/raw/docs/reference/registry.md).
+Import the `.mjs` path. Ordinary TypeScript resolves its adjacent declarations.
+
+```ts [workers/render-invoice.ts]
+import { pdf } from '../generated/pdfs/index.mjs'
+
+export async function renderInvoice() {
+  const result = await pdf.invoice.render({
+    customer: 'Example customer',
+    number: '2026-001',
+    lines: [],
+  })
+  return result.toUint8Array()
+}
+```
+
+Match the props to your own invoice template. Validate request data and check
+authorization before rendering. Props are statically typed, not a runtime
+validation schema. Never accept template source, filesystem paths, build
+options, or unrestricted image URLs from a caller.
+
+Local assets and configured fonts are validated and embedded during the build.
+Remote images remain denied unless the build supplies an explicit `remote`
+policy. Existing resource limits and error codes apply to each render. Fix the
+named resource or lower input size after an admission or limit error.
+
+The application owns jobs, snapshots, storage, document issuance, and delivery.
+For an issued document, store and reuse completed bytes. Two fresh renders are
+not promised to be byte-identical.
+
+## Verify the deployment
+
+Standalone Node rendering is tested locally with embedded fonts and images,
+Unicode text, pagination, and concurrent requests. That is not a deployed
+Convex or other serverless-runtime certification. Edge workers remain unsupported.
+
+Before adoption, measure your largest expected document on the target runtime.
+Check cold and warm duration, memory use, output limits, failed asset requests,
+and concurrent isolation. Keep the previously tested Node route available for
+new renders until this proof passes. Do not regenerate issued PDFs during a
+runtime migration.
+
+See [deployment guidance](/raw/docs/guides/deployment.md) for the runtime matrix and
+operational limits.