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

package/dist/agent/pages/docs/reference/module-options.md

@@ -0,0 +1,104 @@
+---
+title: "Module options"
+description: "Build-time configuration for registered fonts, remote images, and render budgets."
+url: "https://nuxt-pdf.lupinum.com/docs/reference/module-options"
+route: "/docs/reference/module-options"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Module options
+
+> Build-time configuration for registered fonts, remote images, and render budgets.
+
+Set module options under `pdf` in `nuxt.config.ts`:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-pdf'],
+  pdf: {
+    fonts: [],
+    limits: {},
+    remote: undefined,
+  },
+})
+```
+
+| Option | Type | Default | Behavior |
+| --- | --- | --- | --- |
+| `fonts` | `PdfFontDeclaration[]` | `[]` | Registers local TTF, OTF, or WOFF2 faces from `pdfs/fonts`. |
+| `remote` | `RemoteAssetOptions` | `undefined` | Enables allowlisted HTTPS image requests. No remote request is admitted when absent. |
+| `limits` | `PdfLimitsOptions` | All documented defaults | Overrides individual fields in the shared render budget. See [Errors and limits](/raw/docs/reference/errors-and-limits.md). |
+
+Unknown `pdf` keys fail during module setup.
+
+## pdf.fonts
+
+Each entry registers one font face:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  pdf: {
+    fonts: [
+      {
+        family: 'Invoice Sans',
+        src: 'InvoiceSans-Regular.ttf',
+        fontStyle: 'normal',
+        fontWeight: 400,
+      },
+    ],
+  },
+})
+```
+
+| Field | Type | Required | Default | Behavior |
+| --- | --- | --- | --- | --- |
+| `family` | `string` | Yes | Required | Family used by the `fontFamily` style property. |
+| `src` | `string` | Yes | Required | TTF, OTF, or WOFF2 path relative to `pdfs/fonts`. |
+| `fontWeight` | `number \| PdfFontWeightName` | No | `400` | Numeric or named weight. |
+| `fontStyle` | `'normal' \| 'italic' \| 'oblique'` | No | `'normal'` | Face style. |
+
+Register each weight and style used by a document. Invalid declarations and
+font files throw `TypeError` during module setup. See
+[Add images and fonts](/raw/docs/guides/images-and-fonts.md).
+
+## pdf.remote
+
+`remote` admits HTTPS images whose URL starts with an allowed prefix:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  pdf: {
+    remote: {
+      allow: ['https://cdn.example.com/brand/'],
+      timeoutMs: 10_000,
+    },
+  },
+})
+```
+
+| Field | Type | Required | Default | Behavior |
+| --- | --- | --- | --- | --- |
+| `allow` | `string[]` | Yes | Required | Non-empty list of exact `https://host/path/` prefixes. |
+| `timeoutMs` | `number` | No | `10_000` | Timeout for each request or redirect hop. |
+
+Allowlist prefixes require a trailing slash. They cannot contain credentials,
+queries, fragments, wildcards, or a non-HTTPS scheme. The
+[remote-image guide](/raw/docs/guides/remote-images.md) defines request and redirect
+behavior.
+
+## Exported types
+
+Import these types from `@lupinum/nuxt-pdf`:
+
+| Export | Describes |
+| --- | --- |
+| `ModuleOptions` | Complete `pdf` module options. |
+| `PdfFontDeclaration` | One registered font face. |
+| `PdfFontStyle` | Accepted font styles. |
+| `PdfFontWeight` | Numeric or named font weight. |
+| `PdfFontWeightName` | Accepted named font weights. |
+| `RemoteAssetOptions` | Remote image allowlist and timeout. |
+| `PdfLimitsOptions` | Optional render-limit overrides. |

package/dist/agent/pages/docs/reference/page-sizes.md

@@ -0,0 +1,54 @@
+---
+title: "Page sizes"
+description: "Named and custom page dimensions accepted by PdfPage."
+url: "https://nuxt-pdf.lupinum.com/docs/reference/page-sizes"
+route: "/docs/reference/page-sizes"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Page sizes
+
+> Named and custom page dimensions accepted by PdfPage.
+
+Set `PdfPage.size` to an uppercase named size or to explicit dimensions. The
+default is `A4`.
+
+```vue
+<PdfPage size="LETTER">
+  <PdfText>Letter page</PdfText>
+</PdfPage>
+```
+
+Page-size names are case-sensitive:
+
+| Family | Accepted names |
+| --- | --- |
+| ISO A | `4A0`, `2A0`, `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, `A7`, `A8`, `A9`, `A10` |
+| ISO B | `B0`, `B1`, `B2`, `B3`, `B4`, `B5`, `B6`, `B7`, `B8`, `B9`, `B10` |
+| ISO C | `C0`, `C1`, `C2`, `C3`, `C4`, `C5`, `C6`, `C7`, `C8`, `C9`, `C10` |
+| Raw format | `RA0`, `RA1`, `RA2`, `RA3`, `RA4` |
+| Supplementary raw format | `SRA0`, `SRA1`, `SRA2`, `SRA3`, `SRA4` |
+| North American and other | `EXECUTIVE`, `FOLIO`, `LEGAL`, `LETTER`, `TABLOID`, `ID1` |
+
+## Custom dimensions
+
+Use a two-value tuple or a width/height object. A unitless number is a PDF
+point. String dimensions accept `pt`, `in`, `mm`, `cm`, or `px`:
+
+```vue
+<PdfPage :size="['210mm', '297mm']">
+  <PdfText>Custom A4 dimensions</PdfText>
+</PdfPage>
+```
+
+```vue
+<PdfPage :size="{ width: '4in', height: '6in' }">
+  <PdfText>Shipping label</PdfText>
+</PdfPage>
+```
+
+`px` uses the page's `dpi` prop. The default DPI is `72`. Use `orientation` to
+swap portrait and landscape dimensions without reversing the size tuple.

package/dist/agent/pages/docs/reference/primitives.md

@@ -0,0 +1,216 @@
+---
+title: "Primitives"
+description: "Prop tables for every document and SVG primitive, drawn from the shipped type definitions."
+url: "https://nuxt-pdf.lupinum.com/docs/reference/primitives"
+route: "/docs/reference/primitives"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Primitives
+
+> Prop tables for every document and SVG primitive, drawn from the shipped type definitions.
+
+Every primitive is an auto-registered global component. The tables below are
+drawn from the shipped prop types. `style` values use Nuxt PDF's framework-owned
+`PdfStyle` contract, not CSS or the wider upstream stylesheet types (see
+[Styling and layout](/raw/docs/learn/styling-and-layout.md).
+
+The same surface is enforced after Vue mounts the tree. Each primitive has a
+closed runtime prop allowlist; unknown props, DOM/event attributes, and props
+used on the wrong primitive fail with `PDF_TREE_INVALID` rather than passing
+through or silently doing nothing.
+
+## Shared base props
+
+`PdfPage`, `PdfView`, page-flow `PdfText`, `PdfImage`, `PdfLink`, and `PdfNote`
+share these:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | None | Makes the node a named destination for `#id` links and page-number resolution. |
+| `fixed` | `boolean` | `false` | Repeats the node on every page of its flow. |
+| `break` | `boolean` | `false` | Forces a page break before the node. |
+| `minPresenceAhead` | `number` | `0` | Minimum space in points that must follow, or the node moves to the next page. |
+| `debug` | `boolean` | `false` | Draws the node's layout box for debugging. |
+| `style` | `PdfStyleValue` | None | A style object or nested array. `false`, `null`, and `undefined` entries are ignored. |
+
+`PdfPage`, `PdfView`, `PdfText`, and `PdfImage` additionally accept `bookmark`
+(`string`, or `{ title, expanded? }`) to build the outline.
+
+## PdfDocument
+
+The root. Carries document metadata; takes no base props.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title`, `author`, `subject`, `keywords` | `string` | None | Info-dictionary metadata. |
+| `creator`, `producer` | `string` | `'nuxt-pdf'` | Info-dictionary producer metadata. |
+| `language` | `string` | None | Document language tag. |
+| `creationDate` | `Date` | Current render date | Info-dictionary creation date. |
+| `pdfVersion` | `'1.3'` through `'1.7'` or `'1.7ext3'` | `'1.3'` | PDF version written to the catalog. |
+| `pageLayout` | `'singlePage' \| 'oneColumn' \| 'twoColumnLeft' \| 'twoColumnRight' \| 'twoPageLeft' \| 'twoPageRight'` | None | Reader page layout. |
+
+Reader page mode, encryption passwords, and PDF permission flags are not public
+props. Their serialized behavior is not part of the current public contract.
+
+`modificationDate` is also absent. The pinned engine writes its
+upstream prop under a non-standard custom key rather than the PDF `ModDate`
+entry, so exposing it would promise metadata that common readers do not see.
+
+When `definePdf` supplies `title` or `language`, that value is authoritative and
+overrides the corresponding `PdfDocument` prop. Without a definition value, the
+root prop is preserved as the rendered fallback. Nuxt PDF reapplies the
+authoritative values after each page-number update in a multi-pass render.
+
+## PdfPage
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `PdfPageSizeName \| [w, h] \| { width, height }` | `'A4'` | Uppercase named size or explicit dimensions. See [Page sizes](/raw/docs/reference/page-sizes.md). |
+| `orientation` | `'portrait' \| 'landscape'` | `'portrait'` | Page orientation. |
+| `dpi` | `number` | `72` | DPI used for `px` dimensions. |
+| `wrap` | `boolean` | `true` | Paginates content. `false` grows the page to fit. |
+
+Plus the base and bookmark props.
+
+## PdfView
+
+The flexbox container. Base and bookmark props, plus:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `wrap` | `boolean` | `true` | Allows the view to split across a page boundary. |
+
+## PdfText
+
+The only container for text has two context-specific prop branches.
+
+In normal page flow it accepts the base and bookmark props, plus:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `wrap` | `boolean` | `true` | Allows text to split across pages. |
+| `widows` | `number` | `2` | Minimum lines kept together at a page top. |
+| `orphans` | `number` | `2` | Minimum lines kept together at a page bottom. |
+| `render` | `({ pageNumber, totalPages, subPageNumber, subPageTotalPages }) => string \| number \| null \| undefined` | None | Synchronous dynamic text. |
+| `hyphenationCallback` | `(word: string) => string[]` | Engine default | Returns custom hyphenation break points. |
+
+Inside `PdfSvg`, it instead accepts:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `x`, `y` | `PdfSvgLength` | Required | SVG text coordinates. |
+| `fill` | `string` | None | Direct SVG text paint color. |
+| `style` | `PdfStyleValue` | None | Text metrics such as font family and size. `color` is not SVG paint. |
+| `hyphenationCallback` | `(word: string) => string[]` | Engine default | Returns custom hyphenation break points. |
+
+SVG text rejects page-flow-only props such as `id`, `bookmark`, `fixed`,
+`break`, `wrap`, `widows`, `orphans`, and `render`.
+
+## PdfImage
+
+Base and bookmark props, plus:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` | `PdfImageSource` | Required | Image source. |
+
+`PdfImageSource` is a `pdfs/assets`-relative path, a `Uint8Array`/`ArrayBuffer`,
+`{ data, format: 'png' \| 'jpg' }`, or `{ uri, format? }`.
+
+## PdfLink
+
+Base props (no bookmark), plus:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `href` | `string` | Required | External `https:` or `mailto:` URL, or a `#id` internal destination. |
+| `wrap` | `boolean` | `true` | Allows the link to split across pages. |
+| `hitSlop` | `{ top?, right?, bottom?, left? }` | None | Expands the clickable area. |
+
+## PdfNote
+
+A sticky-note annotation. Base props only; its text comes from its content.
+
+---
+
+## SVG primitives
+
+SVG primitives render inside a `PdfSvg`. Paint, geometry, clipping, and
+transforms are direct props. `PdfG` and the shape primitives have no generic
+`style` prop, so there is no style-precedence path; kebab-case Vue attributes
+are normalized to the equivalent camelCase key. See
+[SVG graphics](/raw/docs/guides/svg-graphics.md).
+
+`PdfSvgNumber` is a finite number or numeric string. `PdfSvgLength` additionally
+accepts a numeric percentage string where the individual prop permits it.
+`strokeWidth` is never a percentage. Non-negative geometry and unit-interval
+opacity/stop ranges are checked at runtime.
+
+### Shared SVG presentation props
+
+Available on `PdfG`, `PdfPath`, `PdfRect`, `PdfCircle`, `PdfEllipse`, `PdfLine`,
+`PdfPolyline`, and `PdfPolygon`:
+
+| Prop | Type |
+| --- | --- |
+| `fill`, `stroke` | `string` |
+| `fillOpacity`, `strokeOpacity` | `PdfSvgLength` (0 to 1 or 0% to 100%) |
+| `strokeWidth` | `PdfSvgNumber` (non-negative) |
+| `strokeLinecap` | `'butt' \| 'round' \| 'square'` |
+| `strokeLinejoin` | `'miter' \| 'round' \| 'bevel'` |
+| `transform` | `PdfSvgTransform`. One to three unitless `translate(...)` or `rotate(...)` operations. |
+| `clipPath` | `string` with the value `url(#id)` |
+
+### Geometry props
+
+| Component | Own props |
+| --- | --- |
+| `PdfSvg` | `viewBox`, `width`, `height`, plus page-flow `style` (not SVG presentation) |
+| `PdfG` | _(presentation props only)_ |
+| `PdfPath` | `d` **(required)** |
+| `PdfRect` | `x`, `y`, `width` **(required)**, `height` **(required)**, `rx`, `ry` |
+| `PdfCircle` | `cx`, `cy`, `r` **(required)** |
+| `PdfEllipse` | `cx`, `cy`, `rx` **(required)**, `ry` **(required)** |
+| `PdfLine` | `x1`, `y1`, `x2`, `y2` **(all required)** |
+| `PdfPolyline` / `PdfPolygon` | `points` **(required)** |
+| `PdfDefs` | None. It holds definitions that other elements can reference. |
+| `PdfClipPath` | `id` **(required)** |
+| `PdfLinearGradient` | `id` **(required)**, `x1`, `y1`, `x2`, `y2` |
+| `PdfRadialGradient` | `id` **(required)**, `cx`, `cy`, `r`, `fx`, `fy` |
+| `PdfStop` | `offset` **(required)**, `stopColor` **(required)**, `stopOpacity` |
+| `PdfTspan` | `x`, `y`, `fill` only |
+
+Alternate gradient coordinate systems, transforms, inheritance, and SVG
+`preserveAspectRatio` modes are not public props. See
+[Supported behavior and limitations](/raw/docs/examples/supported-behavior.md).
+
+Each `PdfSvg` accepts at most one direct `PdfDefs` child. Definition ids are
+safe, unique, and scoped to that one SVG. `fill="url(#id)"` must resolve to a
+linear or radial gradient; `clipPath="url(#id)"` must resolve to a
+`PdfClipPath`. Missing, malformed, or incompatible references fail with
+`PDF_TREE_INVALID`.
+
+Explicit zero has SVG semantics: zero fill opacity is transparent, zero stroke
+width removes the stroke instead of requesting a PDF hairline, and supported
+gradient coordinates remain zero. The engine repairs upstream truthiness
+fallbacks after layout and before serialization.
+
+## Exported primitive types
+
+Import prop and value types from `@lupinum/nuxt-pdf` when you type reusable
+document components:
+
+| Area | Exports |
+| --- | --- |
+| Shared | `PdfBaseProps`, `PdfBookmark` |
+| Document flow | `PdfDocumentProps`, `PdfPageProps`, `PdfViewProps`, `PdfTextProps`, `PdfImageProps`, `PdfLinkProps`, `PdfNoteProps` |
+| Images | `PdfImageSource` |
+| Page dimensions | `PdfPageDimension`, `PdfPageSize`, `PdfPageSizeName`, `PdfPageUnit` |
+| SVG containers | `PdfSvgProps`, `PdfGProps`, `PdfDefsProps`, `PdfClipPathProps` |
+| SVG shapes | `PdfPathProps`, `PdfRectProps`, `PdfCircleProps`, `PdfEllipseProps`, `PdfLineProps`, `PdfPolylineProps`, `PdfPolygonProps` |
+| SVG gradients and text | `PdfLinearGradientProps`, `PdfRadialGradientProps`, `PdfStopProps`, `PdfTspanProps` |
+| SVG values | `PdfSvgNumber`, `PdfSvgLength`, `PdfSvgPresentationProps`, `PdfSvgTransform`, `PdfSvgTransformOperation` |

package/dist/agent/pages/docs/reference/registry.md

@@ -0,0 +1,185 @@
+---
+title: "Registry and render result"
+description: "The typed #pdf server module, runtime dispatch, and completed render conversions."
+url: "https://nuxt-pdf.lupinum.com/docs/reference/registry"
+route: "/docs/reference/registry"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Registry and render result
+
+> The typed #pdf server module, runtime dispatch, and completed render conversions.
+
+Nuxt generates an inspectable `#pdf` module from the discovered templates. It is
+a server-only module for Nitro code and is typed from each SFC's props. Do not
+import it from a client component or other browser code.
+
+```ts
+import { pdf, renderPdf, pdfTemplateKeys } from '#pdf'
+```
+
+## pdf
+
+`pdf` is an object keyed by template name. Property access infers each SFC's
+props. Every value has exactly three public members:
+
+```ts
+interface PdfTemplate<Props extends object> {
+  readonly key: string
+  resolveMetadata(props: Props): {
+    title?: string
+    filename?: string
+    language?: string
+  }
+  render(props: Props): Promise<PdfRenderResult>
+}
+```
+
+The handle does not expose the compile-time definition, preview data, source
+file, or a second preview render method.
+
+```ts
+await pdf.invoice.render({ invoice })
+await pdf.report.render({ report })
+```
+
+Nested template paths keep their slash keys (for example
+`pdf['reports/monthly']`).
+
+## renderPdf
+
+`renderPdf(name, props)` is the functional form. A **literal** template name
+infers its props:
+
+```ts
+await renderPdf('invoice', { invoice })
+```
+
+A runtime string cannot be type-checked, so it requires the explicit
+unknown-props escape hatch:
+
+```ts
+await renderPdf(templateName, untypedProps, { unsafe: true })
+```
+
+<warning icon="lucide:triangle-alert">
+`{ unsafe: true }` does **not** validate the props; it only makes the loss of
+static typing visible at the call site. An unknown template name still fails with
+`PDF_TEMPLATE_NOT_FOUND`.
+</warning>
+
+`pdfTemplateKeys` is the array of discovered template names.
+
+`getPdfTemplate(name)` returns that typed three-member handle for a literal name,
+or `undefined` for an unknown name. Reach for it when you need resolved
+`definePdf` metadata without rendering:
+
+```ts
+import { getPdfTemplate } from '#pdf'
+
+const template = getPdfTemplate('invoice')
+const { title, filename } = template.resolveMetadata(props)
+```
+
+`resolveMetadata()` evaluates the `title` and `filename` declared by
+`definePdf`, and returns its `language`. It does not mount the component, so an
+authored `PdfDocument` fallback is not part of this result.
+
+`NuxtPdfError` and `PDF_ERROR_CODES` are also re-exported from `#pdf`, so
+server code can branch on render failures without extra imports. See
+[Errors and limits](/raw/docs/reference/errors-and-limits.md).
+
+## The render result
+
+Both `pdf.name.render(props)` and `renderPdf(...)` resolve to a
+`PdfRenderResult`. The document is rendered once; every conversion reuses that
+completed, immutable byte buffer:
+
+```ts
+const result = await pdf.invoice.render({ invoice })
+
+result.metadata        // frozen title, filename, and language for this render
+await result.toUint8Array() // Promise<Uint8Array>
+await result.toBuffer()     // Promise<Buffer>
+await result.response()     // Promise<Response>
+```
+
+`result.metadata` is the frozen `title`, `filename`, and `language` resolved for
+this render: `definePdf` values win when present, otherwise authored
+`PdfDocument` fallbacks. `title` and `language` describe PDF Info fields;
+`filename` is response/download metadata and is not written into PDF Info.
+`result.diagnostics` is one frozen object shared with the development preview:
+
+| Field | Meaning |
+| --- | --- |
+| `durationMs` | Wall time for the whole public render, including metadata evaluation |
+| `byteLength` | Exact output byte count |
+| `pageCount` | Number of rendered pages |
+| `passes` | Layout passes used (`1` normally, more for a TOC) |
+| `layoutWarnings` | Frozen, structured warnings for layout that rendered but needs attention |
+| `registeredFontFaces` | Frozen family/weight/style facts; never source bytes or paths |
+
+Diagnostics contain no document content, props, or resource URLs. An
+application can send them to its metrics layer.
+
+`layoutWarnings` is empty for a healthy layout. Nuxt PDF currently reports
+`PDF_UNBREAKABLE_NODE_OVERFLOW` when a non-fixed node cannot wrap and is taller
+than the page's usable content height. The warning identifies the page and
+primitive and includes both heights in points, without copying text or ids from
+the document. Allow the node to wrap or make it small enough to fit on one page.
+
+## Development and production boundary
+
+The development preview keeps `sampleData`, named `scenarios`, and the relative
+source file outside the public template handle. It calls the same public
+`render(props)` method as application code and displays that completed result.
+There is no separate preview renderer or second document render.
+
+Editing a template rebuilds its registry and refreshes the document with its
+diagnostics. The preview keeps the selected scenario.
+
+In a production build the SFC transform reconstructs the render definition from
+only `title`, `filename`, `language`, and `maxPasses`. `sampleData` and
+`scenarios` are structurally omitted before Nitro bundles the template; they are
+not public handle properties and are not merely hidden behind runtime checks.
+The development preview data and routes are also absent. Packed-consumer checks
+verify this boundary and keep the renderer and template SFCs out of the client
+output.
+
+Metadata is hoisted: inline values and imports are supported, while references
+to bindings declared locally in `<script setup>` are compile errors. Imported
+preview-data modules must be side-effect-free so their unused production imports
+can be eliminated.
+
+### response(init)
+
+`response()` returns a `Response` with `content-type: application/pdf`, the
+exact `content-length`, and a sanitized, encoded-length-bounded
+`content-disposition` filename:
+
+```ts
+await result.response({
+  disposition: 'inline',      // 'attachment' (default) | 'inline'
+  filename: 'invoice.pdf',    // sanitized before writing the header
+  headers: { 'cache-control': 'no-store' },
+})
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `disposition` | `'attachment' \| 'inline'` | `content-disposition` type; defaults to `attachment` |
+| `filename` | `string` | Download filename; sanitized before use; defaults to template metadata or `document.pdf` |
+| `headers` | `HeadersInit` | Extra response headers merged in |
+| `status`, `statusText` | `number` / `string` | Standard `ResponseInit` fields |
+
+Caller-provided `content-type`, `content-length`, and `content-disposition`
+headers are replaced with the truthful values from the completed result.
+
+## Regenerating the registry
+
+The registry is written during module setup and regenerated whenever templates
+change in development. If `#pdf` imports appear untyped in your editor, run
+`nuxt prepare` once to refresh the generated types.

package/dist/agent/pages/docs/reference/standalone.md

@@ -0,0 +1,53 @@
+---
+title: "Standalone build and runtime"
+description: "Production registry generation and Node runtime exports outside Nitro."
+url: "https://nuxt-pdf.lupinum.com/docs/reference/standalone"
+route: "/docs/reference/standalone"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Standalone build and runtime
+
+> Production registry generation and Node runtime exports outside Nitro.
+
+## Build options
+
+`@lupinum/nuxt-pdf/build` exports the `buildPdfRegistry` function and the
+`BuildPdfRegistryOptions` type. The function resolves to `Promise<void>`.
+
+| Option | Type | Behavior |
+| --- | --- | --- |
+| `rootDir` | `string` | Required application root containing `pdfs/`. Relative to the working directory. |
+| `outDir` | `string` | Required dedicated output directory inside `rootDir` and outside `pdfs/`. Relative paths use `rootDir`. An existing directory must carry Nuxt PDF's ownership marker. |
+| `fonts` | `readonly PdfFontDeclaration[]` | Defaults to no custom fonts. Sources resolve under `pdfs/fonts/`. |
+| `limits` | `PdfLimitsOptions` | Existing render and image-admission limits. Omitted fields use the engine defaults. |
+| `remote` | `RemoteAssetOptions` | Existing remote-image policy. Denied by default. |
+
+The build rejects unknown options, missing templates, invalid resources, invalid
+templates, and type errors. A successful build emits `index.mjs`, `index.d.mts`,
+and the declarations needed for inferred props. It uses Vue's type checker at
+build time; consumers use ordinary TypeScript. See
+[standalone rendering](/raw/docs/guides/standalone-node.md) for the procedure and
+output-directory replacement rules.
+
+## Server exports
+
+`@lupinum/nuxt-pdf/server` is a Node-only production entry. It has no Nuxt virtual
+imports or source compiler. Generated registries use `createPdfTemplate` to bind
+a compiled component to its admitted resources, then `createPdfRegistry` to
+assemble named template handles. Application code should use the generated
+registry instead of constructing this resource configuration manually.
+
+`PdfRegistryEntries` describes the readonly named handles. `PdfRegistry`
+describes their runtime dispatch. `PdfComponentProps` extracts authored Vue
+props. `PdfDefinition` describes compile-time metadata. `PdfTemplate` and
+`PdfRenderResult` describe the public handle and completed bytes. The entry
+also exports `usePdfPageNumbers`, `NuxtPdfError`, `PDF_ERROR_CODES`, and
+`PdfErrorCode` with their existing behavior.
+
+No export sends email, stores a document, authenticates a caller, or selects a
+backend provider. The runtime preserves the current Node requirements and
+[resource limits](/raw/docs/reference/errors-and-limits.md).