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

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).

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

@@ -0,0 +1,176 @@
+---
+title: "Styles"
+description: "Accepted style keys, values, units, inheritance, and primitive support."
+url: "https://nuxt-pdf.lupinum.com/docs/reference/styles"
+route: "/docs/reference/styles"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Styles
+
+> Accepted style keys, values, units, inheritance, and primitive support.
+
+`PdfStyle` is Nuxt PDF's framework-owned authoring contract. It
+contains the behavior this package tests and supports; it does not re-export
+the wider upstream stylesheet types and it is not browser CSS.
+
+```ts
+import type { PdfStyle } from '@lupinum/nuxt-pdf'
+
+const pageStyle = {
+  color: '#18251d',
+  fontFamily: 'Invoice Sans',
+  fontSize: 10,
+  paddingHorizontal: 48,
+  paddingVertical: 40,
+} satisfies PdfStyle
+```
+
+Use `satisfies`, not a type assertion. It preserves the object's useful
+inferred type while making `vue-tsc` reject unknown keys, invalid enums, and
+unsupported units.
+
+`PdfStyle` belongs to page-flow layout and text metrics. SVG paint and geometry
+use direct props: `PdfG` and shapes do not accept `style`, `PdfSvg.style` places
+the SVG root in page flow, and SVG `PdfText.style` controls text metrics while
+its direct `fill` prop controls paint.
+
+## Values and units
+
+| Type | Accepted values | Notes |
+| --- | --- | --- |
+| `PdfLength` | A number, or `pt`, `px`, `in`, `mm`, `cm`, `rem`, `vh`, or `vw` (for example `12`, `'12pt'`, `'4mm'`) | A unitless number is a PDF point. `px` uses the page DPI; the default is 72. |
+| `PdfPercentage` | A numeric percentage string such as `'50%'` | Accepted only by properties whose type includes percentages. |
+| Color | A color string such as `'#18251d'`, `'rgb(24, 37, 29)'`, or `'red'` | There are no CSS variables or global cascade. |
+| Enum | One of the literals listed below | Browser-only values are rejected even when a similarly named CSS property exists. |
+
+`rem` uses the engine's 18-point base. `vw` and `vh` resolve against the PDF
+page container, not a browser window. Percentages resolve against the relevant
+parent dimension.
+
+`em`, `ch`, `ex`, `calc()`, `var()`, container queries, and arbitrary CSS
+strings are not part of the contract.
+
+## Dimensions and positioning
+
+These keys are valid on page-flow primitives (`PdfPage`, `PdfView`, `PdfText`,
+`PdfImage`, `PdfLink`, and `PdfNote`). `width` and `height` also size `PdfSvg`
+inside page flow.
+
+| Property | Accepted value | Inherited | Behavior |
+| --- | --- | --- | --- |
+| `width`, `height` | `PdfLength \| PdfPercentage` | No | Sets the resolved box size. |
+| `minWidth`, `minHeight`, `maxWidth`, `maxHeight` | `PdfLength \| PdfPercentage` | No | Constrains the resolved box size. |
+| `position` | `'relative' \| 'absolute'` | No | Use the component `fixed` prop to repeat content across pages. Browser `fixed` and `static` values are not accepted. |
+| `top`, `right`, `bottom`, `left` | `PdfLength \| PdfPercentage` | No | Offsets a positioned node. |
+
+## Flex layout
+
+Flex properties primarily belong on `PdfPage` and `PdfView`. Text, links,
+images, notes, and SVGs can be flex items. The engine defaults to a `column`
+direction.
+
+| Property | Accepted value | Inherited | Behavior |
+| --- | --- | --- | --- |
+| `flexDirection` | `'row' \| 'row-reverse' \| 'column' \| 'column-reverse'` | No | Controls the main axis. The default is `column`. |
+| `flex`, `flexGrow`, `flexShrink` | `number` | No | Controls available-space growth and shrinkage. |
+| `flexBasis` | `PdfLength \| PdfPercentage \| 'auto'` | No | Sets the initial main-axis size. |
+| `flexWrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | No | Controls flex-line wrapping. |
+| `alignItems` | `'flex-start' \| 'flex-end' \| 'center' \| 'stretch' \| 'baseline'` | No | Aligns children on the cross axis. |
+| `justifyContent` | `'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-around' \| 'space-evenly'` | No | Distributes children on the main axis. |
+| `gap` | `PdfLength` | No | Adds space between flex children. |
+
+There is no grid, browser block layout, floats, selectors, or CSS cascade.
+
+## Box model
+
+The box model is valid on page-flow primitives. Percentages resolve through
+the engine's PDF layout container, not a browser viewport.
+
+| Property | Accepted value | Inherited | Behavior |
+| --- | --- | --- | --- |
+| `margin`, `marginHorizontal`, `marginVertical`, `marginTop`, `marginRight`, `marginBottom`, `marginLeft` | `PdfLength \| PdfPercentage \| 'auto'` | No | Sets space outside the box. |
+| `padding`, `paddingHorizontal`, `paddingVertical`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` | `PdfLength \| PdfPercentage` | No | Sets space inside the box. Padding does not accept `auto`. |
+
+## Borders and paint
+
+| Property | Accepted value | Inherited | Behavior |
+| --- | --- | --- | --- |
+| `backgroundColor` | color string | Only through nested `PdfText` runs | Paints the page-flow box background. |
+| `color` | color string | Yes | Sets text color on text-bearing primitives. |
+| `opacity` | `number` | Yes | Sets node opacity. |
+| `borderWidth`, `borderTopWidth`, `borderRightWidth`, `borderBottomWidth`, `borderLeftWidth` | `PdfLength` | No | Sets all or individual border widths. |
+| `borderColor`, `borderTopColor`, `borderRightColor`, `borderBottomColor`, `borderLeftColor` | color string | No | Sets all or individual border colors. |
+| `borderStyle`, `borderTopStyle`, `borderRightStyle`, `borderBottomStyle`, `borderLeftStyle` | `'solid' \| 'dashed' \| 'dotted'` | No | Sets all or individual border styles. |
+| `borderRadius` | `PdfLength` | No | Page-flow primitives. Percent shorthand is not accepted because the engine requires a resolved number. |
+| `borderTopLeftRadius`, `borderTopRightRadius`, `borderBottomRightRadius`, `borderBottomLeftRadius` | `PdfLength \| PdfPercentage` | No | Page-flow primitives; edge radii are resolved independently. |
+
+Full CSS border strings such as `'1px solid red'` are not public authoring
+syntax. Use the explicit width, style, and color keys so invalid values remain
+type-checkable.
+
+## Text
+
+Text keys apply to `PdfText` and `PdfLink`. They may be set on ancestor
+`PdfPage`/`PdfView` nodes when the table marks them inherited.
+
+| Property | Accepted value | Inherited | Behavior |
+| --- | --- | --- | --- |
+| `fontFamily` | `string` | Yes | Selects one registered family or a built-in engine family. |
+| `fontSize` | `PdfLength` | Yes | Sets glyph size. |
+| `fontStyle` | `'normal' \| 'italic' \| 'oblique'` | Yes | Selects the matching registered face. |
+| `fontWeight` | `number` or `thin`, `hairline`, `ultralight`, `extralight`, `light`, `normal`, `medium`, `semibold`, `demibold`, `bold`, `ultrabold`, `extrabold`, `heavy`, `black` | Yes | Selects the matching registered numeric weight. |
+| `letterSpacing` | `PdfLength` | Yes | Adds space between glyphs and affects wrapping. |
+| `lineHeight` | unitless multiplier, `PdfLength`, or `PdfPercentage` | Yes for static text | Static text supports it. Dynamic `render` text uses font-default line spacing; see [Supported behavior](/raw/docs/examples/supported-behavior.md). |
+| `maxLines` | `number` | No | Limits rendered lines. Use `textOverflow: 'ellipsis'` for an ellipsis. |
+| `textAlign` | `'left' \| 'right' \| 'center' \| 'justify'` | Yes | Aligns text inside its line box. |
+| `textDecoration` | `'none' \| 'underline' \| 'line-through'` or both decoration names separated by a space | Yes | Applies one or both decorations. |
+| `textDecorationColor` | color string | No | `PdfText` and `PdfLink`. |
+| `textDecorationStyle` | `'solid' \| 'dashed' \| 'dotted'` | No | `PdfText` and `PdfLink`. |
+| `textOverflow` | `'ellipsis'` | No | Adds an ellipsis when `maxLines` truncates text. |
+| `textTransform` | `'none' \| 'capitalize' \| 'lowercase' \| 'uppercase'` | Yes | Transforms rendered text casing. |
+
+`wordSpacing` is not supported. The pinned text layout pipeline accepts
+the key but does not apply it to glyph advances or wrapping. Nuxt PDF does not
+type a no-op as supported authoring; use `letterSpacing` instead.
+
+## Images and transforms
+
+| Property | Accepted value | Inherited | Behavior |
+| --- | --- | --- | --- |
+| `objectFit` | `'contain' \| 'cover'` | No | Fits a `PdfImage` inside its resolved box. |
+| `transform` | One to three space-separated `rotate(...)`, `scale(...)`, or `translate(...)` operations | No | Applies to page-flow primitives. Rotate accepts degrees or radians. Translate uses unitless PDF points. SVG transforms remain direct SVG props. |
+
+## Style arrays
+
+`PdfStyleValue` is either one `PdfStyle` or a recursively nested readonly array.
+Arrays merge left-to-right. `false`, `null`, and `undefined` entries are ignored,
+which makes Vue conditionals direct and type-safe:
+
+```ts
+import type { PdfStyle, PdfStyleValue } from '@lupinum/nuxt-pdf'
+
+const base = { fontSize: 10 } satisfies PdfStyle
+const total = { fontWeight: 700 } satisfies PdfStyle
+
+const style = [base, [isTotal && total], null] satisfies PdfStyleValue
+```
+
+Numbers, strings, `true`, functions, and arbitrary objects are not valid array
+entries.
+
+## Exported style types
+
+Import these types from `@lupinum/nuxt-pdf`:
+
+| Export | Describes |
+| --- | --- |
+| `PdfStyle` | One style object |
+| `PdfStyleValue` | One style object or a nested style array |
+| `PdfStyleEntry` | One accepted entry in a style array |
+| `PdfLength` | A point number or supported length string |
+| `PdfPercentage` | A numeric percentage string |
+| `PdfLengthOrPercentage` | A supported length or percentage |

package/dist/agent/pages/docs/reference/test-utilities.md

@@ -0,0 +1,124 @@
+---
+title: "Test utilities"
+description: "The render, parse, assert, and snapshot exports of @lupinum/nuxt-pdf/test."
+url: "https://nuxt-pdf.lupinum.com/docs/reference/test-utilities"
+route: "/docs/reference/test-utilities"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Test utilities
+
+> The render, parse, assert, and snapshot exports of @lupinum/nuxt-pdf/test.
+
+`@lupinum/nuxt-pdf/test` exposes the helpers Nuxt PDF is tested with. They are
+runner-agnostic (they throw `PdfAssertionError`, not Vitest/Jest matchers) and
+load `pdfjs-dist` and `@napi-rs/canvas` lazily. See
+[Testing your PDFs](/raw/docs/guides/testing.md) for a worked example.
+
+## renderPdfTemplate
+
+```ts
+const { bytes, parsed } = await renderPdfTemplate(Component, props)
+```
+
+Renders a Vue PDF component through the real registry pipeline, with or without
+a `definePdf` block. Returns the raw `bytes`, immutable `result`, and a `parsed`
+document. Options use the same input shapes as `pdf.remote` and `pdf.limits`, so
+partial limits and URL-prefix allowlists can be shared with `nuxt.config`.
+
+Use `renderPdfSfc` when the document depends on discovered local images or
+custom font files. Prepared asset maps, embedded font descriptors, and template
+attribution are registry internals and are not public test configuration.
+
+## renderPdfSfc
+
+```ts
+const rendered = await renderPdfSfc('./pdfs/invoice.vue', props, {
+  fonts: [{ family: 'Invoice Sans', src: 'InvoiceSans-Regular.ttf' }],
+})
+```
+
+Compiles a real template and its nested child SFCs with the production
+compiler, discovers and validates `pdfs/assets`, and bundles the declared faces
+from `pdfs/fonts`. Its options mirror `pdf.fonts`, `pdf.remote`, and `pdf.limits`;
+the application root and template identity are inferred from the `pdfs/*.vue`
+path. `loadPdfSfc` exposes only the compile step when a test needs the Vue
+component separately.
+
+## parsePdf
+
+```ts
+const parsed = await parsePdf(input)
+```
+
+Accepts PDF bytes (`Uint8Array`/`ArrayBuffer`/`Buffer`) **or** a
+`PdfRenderResult` straight from the `#pdf` registry. Returns page text, page
+count, flattened link annotations (named destination or external URL), and the
+outline hierarchy with its initial expanded/collapsed state.
+
+## expectPdf
+
+```ts
+expectPdf(parsed)
+  .toHavePageCount(2)
+  .toContainText('Invoice for Acme Corp', { page: 1 })
+  .toHaveLink({ destination: 'terms', page: 1 })
+  .toHaveLink({ url: 'https://example.com/' })
+  .toHaveOutline([{ title: 'Terms', expanded: true }])
+```
+
+A chainable expectation that throws `PdfAssertionError` with an actionable
+message on failure.
+
+| Method | Checks |
+| --- | --- |
+| `toHavePageCount(n)` | Page count equals `n` |
+| `toContainText(text, { page? })` | Extracted text contains `text` |
+| `toHaveLink({ destination?, url?, page? })` | A matching link annotation exists |
+| `toHaveOutline(shape)` | The outline matches the title hierarchy and any requested expansion states |
+
+## rasterizePdf and comparePdfSnapshot
+
+```ts
+await comparePdfSnapshot(bytes, './test/baselines/invoice')
+```
+
+`rasterizePdf` renders pages to PNGs; `comparePdfSnapshot` implements the
+reviewed-baseline flow. It writes per-page baselines when
+`UPDATE_PDF_BASELINES=1` (or `{ update: true }`) and otherwise compares within a
+pixel threshold.
+
+`parsePdf` also returns page dimensions and normalized `textRuns` with text,
+position, size, font name, direction, width, and height. Use tolerant numeric
+assertions for geometry because font and raster backends can vary slightly
+between supported environments.
+
+When a raster comparison fails, the helper checks every page and writes
+`expected`, `actual`, and `diff` PNGs plus a machine-readable `metrics.json` to
+`reports/pdf-snapshots/<baseline-name>`. Pass `{ artifactDir }` to choose a
+different CI artifact directory.
+
+## All exports
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `renderPdfTemplate` | function | Render a component through the real pipeline |
+| `renderPdfSfc` | function | Compile and render a real nested `pdfs/*.vue` graph |
+| `loadPdfSfc` | function | Compile a PDF SFC graph into a Vue component |
+| `parsePdf` | function | Parse bytes or a render result into a `ParsedPdf` |
+| `rasterizePdf` | function | Render pages to PNG images |
+| `comparePdfSnapshot` | function | Reviewed-baseline raster comparison |
+| `toPdfBytes` | function | Normalize inputs to PDF bytes |
+| `expectPdf` | function | Fluent, runner-agnostic assertions |
+| `PdfAssertionError` | class | Thrown by assertions on failure |
+| `PdfComponentProps`, `RenderedPdfTemplate`, `RenderPdfTemplateOptions`, `RenderPdfSfcOptions` | types | Typed component props and render results/options |
+| `ParsedPdf`, `ParsedPdfPage`, `ParsedPdfTextRun`, `ParsedPdfLink`, `PdfOutlineItem`, `PdfInput`, `PdfPageImage` | types | Parsed PDF structures |
+| `PdfExpectation`, `LinkQuery`, `OutlineShape`, `ToContainTextOptions` | types | Assertion inputs and chain type |
+| `RasterizePdfOptions`, `ComparePdfSnapshotOptions`, `PdfSnapshotResult` | types | Raster and snapshot options/results |
+
+`pdfjs-dist` and `@napi-rs/canvas` are optional peer dependencies; install them
+in the project under test. They are absent from the module's production
+dependency graph.

package/dist/build.mjs

@@ -5,9 +5,9 @@ import { join, relative, dirname, resolve, isAbsolute } from 'node:path';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { build } from 'esbuild';
-import { d as discoverPdfTemplates, a as discoverPdfImageFiles, b as bundlePdfFonts, c as compilePdfSfc } from './shared/nuxt-pdf.DMC_Rdsz.mjs';
+import { d as discoverPdfTemplates, a as discoverPdfImageFiles, b as bundlePdfFonts, c as compilePdfSfc } from './shared/nuxt-pdf.C-E8MM_K.mjs';
 import ts from 'typescript';
-import { p as preparePdfImageAssets, g as generatePdfRuntimeRegistry, a as generateAuthoringTypes, b as generatePdfRegistryTypes } from './shared/nuxt-pdf.D3hUPqOJ.mjs';
+import { p as preparePdfImageAssets, g as generatePdfRuntimeRegistry, a as generateAuthoringTypes, b as generatePdfRegistryTypes } from './shared/nuxt-pdf.CjVyPF31.mjs';
 import { normalizeRemoteAssetPolicy } from '../dist/runtime/server/assets/remote.js';
 import { normalizePdfLimits, DEFAULT_PDF_RENDER_LIMITS } from '../dist/runtime/server/render-limits.js';
 import 'node:buffer';

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/nuxt-pdf",
-  "version": "0.4.0-beta.3",
+  "version": "0.4.0-beta.5",
   "configKey": "pdf",
   "docs": "https://nuxt-pdf.lupinum.com",
   "compatibility": {

package/dist/module.mjs

@@ -2,9 +2,9 @@ import { stat } from 'node:fs/promises';
 import { join, isAbsolute, resolve, relative } from 'node:path';
 import { defineNuxtModule, createResolver, getLayerDirectories, createIsIgnored, addServerTemplate, addTemplate, addImports, addTypeTemplate, logger, addServerHandler, addComponent } from '@nuxt/kit';
 import { joinURL } from 'ufo';
-import { d as discoverPdfTemplates, e as discoverPdfComponentFiles, a as discoverPdfImageFiles, b as bundlePdfFonts, f as createPdfSfcPlugin, g as classifyPdfWatchEvent } from './shared/nuxt-pdf.DMC_Rdsz.mjs';
-import { p as preparePdfImageAssets, g as generatePdfRuntimeRegistry, b as generatePdfRegistryTypes, a as generateAuthoringTypes, c as generatePdfPreviewConfig } from './shared/nuxt-pdf.D3hUPqOJ.mjs';
-import { PDF_STUB_NAMES } from '../dist/runtime/components/stubs.js';
+import { d as discoverPdfTemplates, e as discoverPdfComponentFiles, a as discoverPdfImageFiles, b as bundlePdfFonts, f as createPdfSfcPlugin, g as classifyPdfWatchEvent } from './shared/nuxt-pdf.C-E8MM_K.mjs';
+import { p as preparePdfImageAssets, g as generatePdfRuntimeRegistry, b as generatePdfRegistryTypes, a as generateAuthoringTypes, c as generatePdfPreviewConfig } from './shared/nuxt-pdf.CjVyPF31.mjs';
+import * as pdfStubs from '../dist/runtime/components/stubs.js';
 import { normalizeRemoteAssetPolicy } from '../dist/runtime/server/assets/remote.js';
 import { normalizePdfLimits, DEFAULT_PDF_RENDER_LIMITS } from '../dist/runtime/server/render-limits.js';
 import 'node:buffer';
@@ -16,7 +16,7 @@ import 'unimport';
 import '../dist/runtime/shared/template.js';
 import '../dist/runtime/server/assets/resolve-asset.js';
 
-const version = "0.4.0-beta.3";
+const version = "0.4.0-beta.5";
 
 const existingDirectories = async (directories) => {
   const result = [];
@@ -143,6 +143,14 @@ const module$1 = defineNuxtModule({
       nuxt.hook("vite:serverCreated", (viteServer, environment) => {
         if (environment.isClient) clientViteServer = viteServer;
       });
+      const refreshPreview = () => clientViteServer?.ws.send({
+        type: "custom",
+        event: "nuxt-pdf:update",
+        data: {}
+      });
+      nuxt.hook("nitro:init", (nitro) => {
+        nitro.hooks.hook("dev:reload", refreshPreview);
+      });
       nuxt.hook("builder:watch", async (event, path) => {
         const absolutePath = isAbsolute(path) ? path : resolve(nuxt.options.srcDir, path);
         const action = classifyPdfWatchEvent(
@@ -158,12 +166,7 @@ const module$1 = defineNuxtModule({
           await nuxt.callHook("restart");
           return;
         }
-        if (action !== "refresh") return;
-        clientViteServer?.ws.send({
-          type: "custom",
-          event: "nuxt-pdf:update",
-          data: {}
-        });
+        if (action === "refresh" && /\.(?:png|jpe?g)$/i.test(absolutePath)) refreshPreview();
       });
       addServerTemplate({
         filename: "#pdf-preview-config",
@@ -182,7 +185,7 @@ const module$1 = defineNuxtModule({
           view: { type: "iframe", src: joinURL(nuxt.options.app.baseURL || "/", "_pdf") }
         });
       });
-      for (const name of PDF_STUB_NAMES) {
+      for (const name of Object.keys(pdfStubs)) {
         addComponent({
           name,
           export: name,