@lupinum/nuxt-pdf 0.3.1 → 0.4.0-beta.1

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to `@lupinum/nuxt-pdf` are recorded here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.4.0-beta.1 - 2026-08-22
+
+### Added
+
+- Add strict PDF primitive stubs so invalid props fail during authoring instead
+  of reaching the renderer.
+- Add safer local and remote image admission, configured-font validation, and
+  clearer development preview diagnostics.
+- Add source-derived documentation checks for primitive props, error codes,
+  page sizes, render limits, public exports, routes, and complete examples.
+
+### Changed
+
+- Rebuild the documentation around a first-render tutorial, focused task
+  guides, complete API reference, production guidance, and compatibility
+  evidence.
+- Expand the playground with reusable invoice components, production document
+  recipes, and stronger preview scenarios.
+- Refresh the documentation design with stable Ginko packages and the Nuxt
+  visual language.
+
+### Fixed
+
+- Keep release workflows tied to the exact verified artifact and independent
+  of unnecessary GitHub tokens.
+- Build documentation when no previous Vercel deployment baseline exists.
+- Prepare Nuxt-generated types before clean package and documentation builds.
+
 ## 0.3.1 - 2026-08-13
 
 ### Fixed

package/CONFORMANCE.md

@@ -1,11 +1,11 @@
-# Nuxt PDF 0.3.1 conformance
+# Nuxt PDF 0.4.0-beta.1 conformance
 
 Nuxt PDF claims behavioral compatibility for a deliberately small, tested
 corpus. It does not claim full React PDF API or test-suite compatibility.
 
 ## Version boundary
 
-| Layer | 0.3.1 boundary |
+| Layer | 0.4.0-beta.1 boundary |
 |---|---|
 | Node.js | `^22.14.0`, `^24.0.0`, or `^26.0.0` |
 | Nuxt | `^4.4.8` |
@@ -158,7 +158,9 @@ claimed.
 **Images** (`test/corpus/images.test.ts`):
 
 - JPEG file paths, base64 `data:` URLs, and `{ data, format }` buffer sources all
-  decode and render;
+  decode in the lower-engine paired fixture. The public resource boundary
+  accepts bundled paths, admitted byte sources, and allowlisted HTTPS images;
+  it blocks `data:` URL strings on every public render path;
 - explicit width+height, single-dimension aspect scaling, and percent width
   against the page content box size the laid-out box (reviewed baseline);
 - `objectFit` `contain` letterboxes and `cover` crops while the box stays fixed
@@ -202,7 +204,7 @@ checking.
 
 ### Vue and Nuxt authoring
 
-The 0.3.1 tests verify:
+The 0.4.0-beta.1 tests verify:
 
 - `PdfDocument`, `PdfPage`, `PdfView`, `PdfText`, `PdfImage`, `PdfLink`, and
   `PdfNote`;
@@ -215,8 +217,9 @@ The 0.3.1 tests verify:
 - framework-owned `PdfStyle` and exact primitive prop types checked through a
   real Vue SFC, plus closed per-primitive runtime allowlists that reject
   unknown, DOM/event, removed, and wrong-host props without echoing values;
-- exactly one `src`/`source` for `PdfImage`, exactly one `href`/`src` for
-  `PdfLink`, and context-specific page-flow/SVG `PdfText` invariants;
+- a required `src` for `PdfImage`, a required `href` for `PdfLink` (an `href`
+  starting with `#` is an internal destination), and context-specific
+  page-flow/SVG `PdfText` invariants;
 - one completed render held behind immutable byte, buffer, and `Response`
   conversions, with exact frozen resolved metadata and one frozen, content-free
   diagnostics object shared by the public result and development preview; the
@@ -287,7 +290,7 @@ and exposes it through one composable and existing props. The tested boundary:
   `PDF_LIMIT_EXCEEDED` `NuxtPdfError` attributed to the template key and file
   through the same boundary as every other render failure.
 - **Named destinations resolve to a section's first page.** A node's `id` becomes
-  a named destination; a `PdfLink` `src="#id"` jumps to it. When the id sits on a
+  a named destination; a `PdfLink` `href="#id"` jumps to it. When the id sits on a
   node that spans a page boundary, both the printed number and the jump target
   resolve to the section's **first** page (a deliberate divergence from React PDF,
   whose last-writer-wins destination table points at the last page). This holds on
@@ -317,8 +320,10 @@ and exposes it through one composable and existing props. The tested boundary:
 
 ### Local resources
 
-The module validates and embeds configured resources during the Nuxt build.
-The tested boundary includes:
+The module validates configured resources during the Nuxt build. Production
+builds embed validated image bytes in the server bundle; development builds
+point at the source files and re-read them per render, so an edited image
+shows up without a restart. The tested boundary includes:
 
 - PNG and JPEG extension/signature validation and source byte limits;
 - TTF and OTF signature/extension/SFNT table-directory validation,
@@ -432,7 +437,7 @@ parser, not two. Claimed:
 Verified end-to-end against a real rendered template, including assertion
 failure messages, in `test/test-utils-public.test.ts`.
 
-## Explicitly not claimed in 0.3.1
+## Explicitly not claimed in 0.4.0-beta.1
 
 - Full React PDF component, hook, browser-helper, or test-suite parity.
 - React runtime compatibility or React-shaped dynamic callback results.
@@ -446,7 +451,7 @@ failure messages, in `test/test-utils-public.test.ts`.
 - Nuxt 3, Node 20, or versions outside the table above.
 - Authenticated remote fetches, request headers/bodies, credentialed requests,
   proxies, or private-IP/DNS-rebinding protection. Opt-in allowlisted remote
-  images and fonts are claimed above under "Opt-in remote resources".
+  images are claimed above. Remote fonts are not supported.
 - SVG image files (as an image source), SVG `Marker`, alternate gradient
   coordinate systems/transforms/inheritance, and `preserveAspectRatio` modes.
   Radial-gradient inner radius (`fr`) is also absent because the pinned renderer

package/README.md

@@ -1,21 +1,33 @@
 <p align="center">
-  <img src="docs/public/logo.svg" width="128" alt="Nuxt PDF">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/public/icon-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/public/icon-light.svg">
+    <img src="docs/public/icon-light.svg" width="128" alt="Nuxt PDF icon">
+  </picture>
 </p>
 
-<h1 align="center">Nuxt PDF</h1>
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/public/wordmark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/public/wordmark-light.svg">
+    <img src="docs/public/wordmark-light.svg" width="256" alt="Nuxt PDF">
+  </picture>
+</h1>
 
 <p align="center">
   Author and render PDFs with Vue components in Nuxt.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@lupinum/nuxt-pdf"><img src="https://img.shields.io/npm/v/@lupinum/nuxt-pdf?color=315d3b" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@lupinum/nuxt-pdf"><img src="https://img.shields.io/npm/v/@lupinum/nuxt-pdf?color=00DC82" alt="npm version"></a>
   <a href="https://github.com/lupinum-dev/nuxt-pdf/actions/workflows/ci.yml"><img src="https://github.com/lupinum-dev/nuxt-pdf/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-315d3b" alt="MIT license"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-00DC82" alt="MIT license"></a>
+  <a href="https://discord.gg/RPH6SeA36N"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord" alt="Discord"></a>
+  <a href="https://deepwiki.com/lupinum-dev/nuxt-pdf"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
 > [!IMPORTANT]
-> Nuxt PDF is an external alpha. Its tested behavior is stable within each
+> Nuxt PDF is in public beta. Its tested behavior is stable within each
 > release, but a minor release can contain documented breaking changes before
 > version 1.0.
 
@@ -65,7 +77,7 @@ export default defineNuxtConfig({
 
 Create `pdfs/invoice.vue`:
 
-```vue
+```vue [pdfs/invoice.vue]
 <script setup lang="ts">
 type InvoiceProps = {
   invoice: {
@@ -80,6 +92,7 @@ const props = defineProps<InvoiceProps>()
 definePdf<InvoiceProps>({
   title: ({ invoice }) => `Invoice ${invoice.number}`,
   filename: ({ invoice }) => `invoice-${invoice.number}.pdf`,
+  language: 'en-GB',
   sampleData: {
     invoice: {
       customer: 'Ada Lovelace',
@@ -123,14 +136,42 @@ export default defineEventHandler(async () => {
 })
 ```
 
-Start Nuxt. Open these development routes:
+Start Nuxt:
+
+```bash
+pnpm dev
+```
+
+Download the PDF from a second terminal:
+
+```bash
+curl -o invoice.pdf http://localhost:3000/api/invoice
+```
+
+Open these development routes:
 
 - `/_pdf` lists the discovered templates.
 - `/_pdf/invoice` shows the document preview.
 - `/api/invoice` returns the production-style PDF response.
 
-Restart `nuxt dev` after you first enable the module. This action generates
-the typed `#pdf` registry.
+Nuxt PDF regenerates the typed `#pdf` registry whenever templates change. If
+your editor still shows `#pdf` as untyped, run `nuxt prepare` once to refresh
+the generated types.
+
+## Discord
+
+Join the Lupinum OSS community to discuss Nuxt PDF, ask questions, and share
+what you build.
+
+<p align="center">
+  <a href="https://discord.gg/RPH6SeA36N">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="docs/public/discord-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="docs/public/discord-light.svg">
+      <img src="docs/public/discord-light.svg" width="500" alt="Join the Lupinum OSS Discord">
+    </picture>
+  </a>
+</p>
 
 ## How it works
 
@@ -181,6 +222,10 @@ assets, links, bookmarks, tables of contents, testing, and the complete API
 reference. Read [CONFORMANCE.md](./CONFORMANCE.md) for the exact tested behavior
 and known limitations.
 
+Coding agents should start with
+[`/llms.txt`](https://nuxt-pdf.lupinum.com/llms.txt). It links to concise raw
+Markdown for common tasks, reference pages, errors, and compatibility evidence.
+
 ## Contributing and development
 
 ```bash

package/dist/module.json

@@ -1,10 +1,11 @@
 {
-  "name": "nuxt-pdf",
+  "name": "@lupinum/nuxt-pdf",
+  "version": "0.4.0-beta.1",
   "configKey": "pdf",
+  "docs": "https://nuxt-pdf.lupinum.com",
   "compatibility": {
-    "nuxt": "^4.4.8"
+    "nuxt": ">=4.4.8"
   },
-  "version": "0.3.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -1,11 +1,12 @@
 import { stat } from 'node:fs/promises';
-import { join, isAbsolute, resolve } from 'node:path';
-import { defineNuxtModule, createResolver, getLayerDirectories, createIsIgnored, addServerTemplate, addTemplate, addImports, addTypeTemplate, addServerHandler } from '@nuxt/kit';
-import { d as discoverPdfTemplates, a as discoverPdfComponentFiles, b as discoverPdfImageFiles, c as bundlePdfFonts, e as createPdfSfcPlugin, f as classifyPdfWatchEvent } from './shared/nuxt-pdf.D2ZziYn4.mjs';
 import { Buffer } from 'node:buffer';
+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, a as discoverPdfComponentFiles, b as discoverPdfImageFiles, c as bundlePdfFonts, e as createPdfSfcPlugin, f as classifyPdfWatchEvent } from './shared/nuxt-pdf._V584vX4.mjs';
+import { pdfImageFormatFromKey, loadPdfImageAsset } from '../dist/runtime/server/assets/resolve-asset.js';
+import { PDF_STUB_NAMES } from '../dist/runtime/components/stubs.js';
 import { normalizeRemoteAssetPolicy } from '../dist/runtime/server/assets/remote.js';
-import { loadPdfImageAsset } from '../dist/runtime/server/assets/resolve-asset.js';
 import { normalizePdfLimits, DEFAULT_PDF_RENDER_LIMITS } from '../dist/runtime/server/render-limits.js';
 import 'node:fs';
 import '@vue/compiler-sfc';
@@ -14,6 +15,8 @@ import 'esbuild';
 import 'unimport';
 import '../dist/runtime/shared/template.js';
 
+const version = "0.4.0-beta.1";
+
 const compareText = (left, right) => {
   if (left < right) return -1;
   if (left > right) return 1;
@@ -31,14 +34,20 @@ const runtimeOptionsSource = (options) => {
   const assets = options.assets ?? [];
   const fonts = options.fonts ?? [];
   const { remote, limits } = options;
+  for (const asset of assets) {
+    if (asset.root !== void 0 === (asset.dataB64 !== void 0)) {
+      throw new TypeError(
+        `PDF image asset "${asset.key}" must declare exactly one of root or dataB64.`
+      );
+    }
+  }
   if (assets.length === 0 && fonts.length === 0 && !remote && !limits) return [];
   const lines = ["", "const __pdfRuntimeOptions = Object.freeze({"];
   if (assets.length > 0) {
     lines.push("  assets: Object.freeze({");
     for (const asset of assets) {
-      lines.push(
-        `    ${quote$1(asset.key)}: Object.freeze({ data: __pdfBuffer.from(${quote$1(Buffer.from(asset.data).toString("base64"))}, 'base64'), format: ${quote$1(asset.format)} }),`
-      );
+      const entry = asset.root !== void 0 ? `{ format: ${quote$1(asset.format)}, root: ${quote$1(asset.root)} }` : `{ dataB64: ${quote$1(asset.dataB64 ?? "")}, format: ${quote$1(asset.format)} }`;
+      lines.push(`    ${quote$1(asset.key)}: Object.freeze(${entry}),`);
     }
     lines.push("  }),");
   }
@@ -86,9 +95,6 @@ const generatePdfRuntimeRegistry = (templates, options) => {
   const lines = [
     `import { ${runtimeImports} } from ${quote$1(options.runtimeImport)}`
   ];
-  if ((options.assets?.length ?? 0) > 0) {
-    lines.push("import { Buffer as __pdfBuffer } from 'node:buffer'");
-  }
   ordered.forEach((template, index) => {
     lines.push(
       `import __pdfTemplate${index} from ${quote$1(importPath(template.filePath))}`
@@ -219,10 +225,12 @@ export {}
 `;
 const module$1 = defineNuxtModule({
   meta: {
-    name: "nuxt-pdf",
+    name: "@lupinum/nuxt-pdf",
+    version: version,
     configKey: "pdf",
+    docs: "https://nuxt-pdf.lupinum.com",
     compatibility: {
-      nuxt: "^4.4.8"
+      nuxt: ">=4.4.8"
     }
   },
   defaults: {
@@ -248,13 +256,24 @@ const module$1 = defineNuxtModule({
     const limits = normalizePdfLimits(options.limits);
     const resolvedLimits = limits ?? DEFAULT_PDF_RENDER_LIMITS;
     const imageFiles = await discoverPdfImageFiles(layers, isIgnored);
-    const assets = await Promise.all(imageFiles.map(
-      (image) => loadPdfImageAsset(image.key, {
-        roots: [image.rootDir],
-        maxBytes: resolvedLimits.maxImageBytes,
-        maxPixels: resolvedLimits.maxImagePixels
-      })
-    ));
+    const assetEntries = [];
+    for (const image of imageFiles) {
+      const format = pdfImageFormatFromKey(image.key);
+      if (nuxt.options.dev) {
+        assetEntries.push({ format, key: image.key, root: image.rootDir });
+      } else {
+        const loaded = await loadPdfImageAsset(image.key, {
+          roots: [image.rootDir],
+          maxBytes: resolvedLimits.maxImageBytes,
+          maxPixels: resolvedLimits.maxImagePixels
+        });
+        assetEntries.push({
+          dataB64: Buffer.from(loaded.data).toString("base64"),
+          format,
+          key: image.key
+        });
+      }
+    }
     const fontRoots = await existingDirectories(
       layers.map((layer) => join(layer.rootDir, "pdfs", "fonts"))
     );
@@ -272,7 +291,7 @@ const module$1 = defineNuxtModule({
     addServerTemplate({
       filename: "#pdf",
       getContents: () => generatePdfRuntimeRegistry(templates, {
-        assets,
+        assets: assetEntries,
         development: nuxt.options.dev,
         fonts,
         remote,
@@ -342,6 +361,9 @@ const module$1 = defineNuxtModule({
           isIgnored
         );
         if (action === "restart") {
+          logger.info(
+            `nuxt-pdf: ${relative(nuxt.options.rootDir, absolutePath) || absolutePath} changed; restarting to rebuild the PDF registry\u2026`
+          );
           await nuxt.callHook("restart");
           return;
         }
@@ -361,6 +383,21 @@ const module$1 = defineNuxtModule({
       });
       addServerHandler({ route: "/_pdf", handler: previewHandler });
       addServerHandler({ route: "/_pdf/**", handler: previewHandler });
+      nuxt.hook("devtools:customTabs", (tabs) => {
+        tabs.push({
+          name: "nuxt-pdf",
+          title: "PDF",
+          icon: "i-lucide-file-text",
+          view: { type: "iframe", src: joinURL(nuxt.options.app.baseURL || "/", "_pdf") }
+        });
+      });
+      for (const name of PDF_STUB_NAMES) {
+        addComponent({
+          name,
+          export: name,
+          filePath: resolver.resolve("./runtime/components/stubs")
+        });
+      }
     }
   }
 });

package/dist/runtime/components/_props.d.ts

@@ -71,22 +71,16 @@ export type PdfImageSource = string | Uint8Array | ArrayBuffer | {
     uri: string;
     format?: 'png' | 'jpg';
 };
-type PdfImageSourceProp = {
+export type PdfImageProps = PdfBaseProps & PdfBookmarkProp & {
+    /** Local bundled path, remote allowlisted URL, or inline bytes. */
     src: PdfImageSource;
-    source?: never;
-} | {
-    src?: never;
-    source: PdfImageSource;
 };
-export type PdfImageProps = PdfBaseProps & PdfBookmarkProp & PdfImageSourceProp;
-type PdfLinkTarget = {
+export type PdfLinkProps = PdfBaseProps & {
+    /**
+     * Link target. A string starting with `#` jumps to the element whose `id`
+     * matches the rest of the string; every other value opens as an external URL.
+     */
     href: string;
-    src?: never;
-} | {
-    href?: never;
-    src: string;
-};
-export type PdfLinkProps = PdfBaseProps & PdfLinkTarget & {
     wrap?: boolean;
     hitSlop?: {
         top?: number;

package/dist/runtime/components/stubs.d.ts

@@ -0,0 +1,10 @@
+import { defineComponent } from 'vue';
+/**
+ * Development-only guards for the global `Pdf*` component names. Types declare
+ * these names globally so `pdfs/*.vue` templates typecheck, which means an
+ * accidental `<PdfText>` inside an ordinary app component also typechecks —
+ * while resolving to nothing at runtime. Registering these stubs turns that
+ * silent failure into an immediate, actionable error.
+ */
+export declare const PDF_STUB_NAMES: readonly ["PdfCircle", "PdfClipPath", "PdfDefs", "PdfDocument", "PdfEllipse", "PdfG", "PdfImage", "PdfLine", "PdfLinearGradient", "PdfLink", "PdfNote", "PdfPage", "PdfPath", "PdfPolygon", "PdfPolyline", "PdfRadialGradient", "PdfRect", "PdfStop", "PdfSvg", "PdfText", "PdfTspan", "PdfView"];
+export declare const createPdfStubs: () => Record<string, ReturnType<typeof defineComponent>>;

package/dist/runtime/components/stubs.js

@@ -0,0 +1,37 @@
+import { defineComponent } from "vue";
+import { NuxtPdfError, PDF_ERROR_CODES } from "../shared/errors.js";
+export const PDF_STUB_NAMES = [
+  "PdfCircle",
+  "PdfClipPath",
+  "PdfDefs",
+  "PdfDocument",
+  "PdfEllipse",
+  "PdfG",
+  "PdfImage",
+  "PdfLine",
+  "PdfLinearGradient",
+  "PdfLink",
+  "PdfNote",
+  "PdfPage",
+  "PdfPath",
+  "PdfPolygon",
+  "PdfPolyline",
+  "PdfRadialGradient",
+  "PdfRect",
+  "PdfStop",
+  "PdfSvg",
+  "PdfText",
+  "PdfTspan",
+  "PdfView"
+];
+const stubMessage = (name) => `<${name}> only works inside a discovered pdfs/*.vue template rendered by @lupinum/nuxt-pdf. Move this component under pdfs/, or replace it with ordinary Vue/HTML components.`;
+const createPdfStub = (name) => defineComponent({
+  name,
+  setup() {
+    throw new NuxtPdfError(PDF_ERROR_CODES.TemplateInvalid, stubMessage(name));
+  },
+  render: () => null
+});
+export const createPdfStubs = () => Object.fromEntries(
+  PDF_STUB_NAMES.map((name) => [name, createPdfStub(name)])
+);

package/dist/runtime/renderer/patch-prop.d.ts

@@ -1,3 +1,5 @@
 import type { RendererOptions } from 'vue';
-import { type PdfHostElement, type PdfHostNode } from './types.js';
+import { type PdfElementType, type PdfHostElement, type PdfHostNode } from './types.js';
+/** Closed runtime prop surface; TypeScript alone cannot reject Vue attrs. */
+export declare const PDF_PROP_KEYS: Record<PdfElementType, ReadonlySet<string>>;
 export declare const patchPdfProp: RendererOptions<PdfHostNode, PdfHostElement>['patchProp'];

package/dist/runtime/renderer/patch-prop.js

@@ -26,7 +26,7 @@ const SVG_PRESENTATION_PROP_NAMES = [
   "strokeWidth",
   "transform"
 ];
-const PDF_PROP_KEYS = {
+export const PDF_PROP_KEYS = {
   [PDF_PRIMITIVES.Document]: exactPropNames()([
     "author",
     "creationDate",
@@ -67,14 +67,12 @@ const PDF_PROP_KEYS = {
   [PDF_PRIMITIVES.Image]: exactPropNames()([
     ...BASE_PROP_NAMES,
     ...BOOKMARK_PROP_NAMES,
-    "source",
     "src"
   ]),
   [PDF_PRIMITIVES.Link]: exactPropNames()([
     ...BASE_PROP_NAMES,
     "hitSlop",
     "href",
-    "src",
     "wrap"
   ]),
   [PDF_PRIMITIVES.Note]: exactPropNames()(BASE_PROP_NAMES),

package/dist/runtime/renderer/validate-tree.js

@@ -256,18 +256,15 @@ const validatePage = (node) => {
 };
 const validateLinkAndImageSources = (node) => {
   if (node.type === PDF_PRIMITIVES.Image) {
-    if (hasProp(node, "src") === hasProp(node, "source")) {
-      treeInvalid('<PdfImage> requires exactly one of "src" or "source".');
+    if (!hasProp(node, "src")) {
+      treeInvalid('<PdfImage> requires a "src" prop.');
     }
   }
   if (node.type === PDF_PRIMITIVES.Link) {
-    const hasHref = hasProp(node, "href");
-    const hasSrc = hasProp(node, "src");
-    if (hasHref === hasSrc) {
-      treeInvalid('<PdfLink> requires exactly one of "href" or "src".');
+    if (!hasProp(node, "href")) {
+      treeInvalid('<PdfLink> requires an "href" prop.');
     }
-    const target = hasHref ? node.props.href : node.props.src;
-    if (typeof target !== "string" || target.trim() === "") {
+    if (typeof node.props.href !== "string" || node.props.href.trim() === "") {
       treeInvalid("<PdfLink> targets must be non-empty strings.");
     }
   }

package/dist/runtime/server/assets/resolve-asset.d.ts

@@ -4,14 +4,23 @@ import { type RemoteAssetPolicy, type RemoteRequestState } from './remote.js';
 import { type RenderLimits } from '../render-limits.js';
 export { PDF_ASSET_ERROR_CODES, PdfAssetError, type PdfAssetErrorCode, } from './errors.js';
 export type PdfImageFormat = 'jpg' | 'png';
-export type PdfImageAsset = Readonly<{
-    data: Uint8Array;
+/**
+ * One discovered local image. In development the entry points at the source
+ * file on disk so edits show up without a restart; in production the validated
+ * bytes travel as base64 inside the server bundle so every Nitro preset stays
+ * self-contained. Both forms resolve through the same validation boundary.
+ */
+export type PdfImageAssetEntry = Readonly<{
+    format: PdfImageFormat;
+    root: string;
+} | {
+    dataB64: string;
     format: PdfImageFormat;
 }>;
-export type LoadedPdfImageAsset = PdfImageAsset & Readonly<{
+export type PdfImageAssetMap = Readonly<Record<string, PdfImageAssetEntry>>;
+export type LoadedPdfImageAsset = Readonly<{
     key: string;
-}>;
-export type PdfImageAssetMap = Readonly<Record<string, PdfImageAsset>>;
+}> & ResolvedPdfImageAsset;
 export interface LoadPdfImageAssetOptions {
     roots: readonly string[];
     maxBytes?: number;
@@ -28,6 +37,13 @@ export interface ResolvePdfImageAssetsOptions {
      */
     state?: PdfImageResolutionState;
 }
+type ResolvedPdfImageAsset = Readonly<{
+    data: Buffer;
+    format: PdfImageFormat;
+    height: number;
+    pixels: number;
+    width: number;
+}>;
 type ImageBudgetState = {
     bytes: number;
     pixels: number;
@@ -39,6 +55,8 @@ export interface PdfImageResolutionState {
     readonly remote: RemoteRequestState;
     readonly resolved: ImageResolutionCache;
 }
+/** Format for a discovered asset key, validated at module setup time. */
+export declare const pdfImageFormatFromKey: (key: string) => PdfImageFormat;
 /**
  * Loads and validates one local image while the Nuxt module still has access to
  * source files. Generated server code should store the returned bytes under

package/dist/runtime/server/assets/resolve-asset.js

@@ -72,6 +72,12 @@ const formatFromExtension = (key) => {
   if (extension === ".jpg" || extension === ".jpeg") return "jpg";
   return invalid("PDF images must be PNG or JPEG files.");
 };
+export const pdfImageFormatFromKey = (key) => {
+  const extension = extname(key).toLowerCase();
+  if (extension === ".png") return "png";
+  if (extension === ".jpg" || extension === ".jpeg") return "jpg";
+  throw new TypeError(`PDF images must be PNG or JPEG files: "${key}".`);
+};
 const claimedFormat = (value) => {
   if (value === void 0) return void 0;
   if (typeof value !== "string") {
@@ -270,7 +276,30 @@ export const loadPdfImageAsset = async (relativePath, options) => {
     "The local PDF image was not found in a configured asset root."
   );
 };
-const resolveLocalImage = (source, assets, maxBytes, maxPixels, declaredFormat) => {
+const RESOLVED_IMAGE_CACHE_BYTES = 32 * 1024 * 1024;
+const resolvedImageCache = /* @__PURE__ */ new Map();
+let resolvedImageCacheBytes = 0;
+const embeddedImageCache = /* @__PURE__ */ new WeakMap();
+const rememberResolvedImage = (cacheKey, image) => {
+  if (resolvedImageCache.has(cacheKey)) return;
+  resolvedImageCache.set(cacheKey, image);
+  resolvedImageCacheBytes += image.data.byteLength;
+  while (resolvedImageCacheBytes > RESOLVED_IMAGE_CACHE_BYTES && resolvedImageCache.size > 1) {
+    const oldest = resolvedImageCache.keys().next().value;
+    if (oldest === void 0) break;
+    resolvedImageCacheBytes -= resolvedImageCache.get(oldest).data.byteLength;
+    resolvedImageCache.delete(oldest);
+  }
+};
+const cachedResolvedImage = (cacheKey) => {
+  const cached = resolvedImageCache.get(cacheKey);
+  if (!cached) return void 0;
+  return {
+    ...cached,
+    data: Buffer.from(cached.data)
+  };
+};
+const resolveLocalImage = async (source, assets, maxBytes, maxPixels, declaredFormat) => {
   const key = canonicalAssetKey(source);
   const pathFormat = formatFromExtension(key);
   const sourceFormat = claimedFormat(declaredFormat);
@@ -279,20 +308,66 @@ const resolveLocalImage = (source, assets, maxBytes, maxPixels, declaredFormat)
   }
   if (!hasOwn(assets, key)) {
     return invalid(
-      "The local PDF image was not included in the generated asset map."
+      `The local PDF image "${key}" was not found under pdfs/assets. Add the file or fix the path.`
     );
   }
-  const asset = assets[key];
-  if (!asset || typeof asset !== "object") {
+  const entry = assets[key];
+  if (!entry || typeof entry !== "object") {
     return invalid("The generated PDF image asset is invalid.");
   }
-  const assetFormat = claimedFormat(asset.format);
+  const assetFormat = claimedFormat(entry.format);
   if (!assetFormat || assetFormat !== pathFormat) {
     return invalid(
       "The generated PDF image format does not match its asset key."
     );
   }
-  return validateImageBytes(asset.data, maxBytes, assetFormat, maxPixels);
+  if ("dataB64" in entry) {
+    const limitsKey = `${maxBytes}\0${maxPixels}`;
+    let byLimits = embeddedImageCache.get(entry);
+    if (!byLimits) {
+      byLimits = /* @__PURE__ */ new Map();
+      embeddedImageCache.set(entry, byLimits);
+    }
+    const cached2 = byLimits.get(limitsKey);
+    if (cached2) return { ...cached2, data: Buffer.from(cached2.data) };
+    const resolved2 = validateImageBytes(
+      Buffer.from(entry.dataB64, "base64"),
+      maxBytes,
+      assetFormat,
+      maxPixels
+    );
+    byLimits.set(limitsKey, resolved2);
+    return { ...resolved2, data: Buffer.from(resolved2.data) };
+  }
+  let fileStat;
+  try {
+    fileStat = await stat(resolve(entry.root, ...key.split("/")));
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return invalid(`The local PDF image "${key}" was not found under pdfs/assets.`);
+    }
+    return invalid("The local PDF image cannot be inspected.", error);
+  }
+  if (!fileStat.isFile()) {
+    return invalid("The local PDF image is not a regular file.");
+  }
+  const cacheKey = `disk\0${key}\0${fileStat.mtimeMs}\0${fileStat.size}\0${maxBytes}\0${maxPixels}`;
+  const cached = cachedResolvedImage(cacheKey);
+  if (cached) return cached;
+  const loaded = await loadPdfImageAsset(key, {
+    roots: [entry.root],
+    maxBytes,
+    maxPixels
+  });
+  const resolved = Object.freeze({
+    data: loaded.data,
+    format: assetFormat,
+    height: loaded.height,
+    pixels: loaded.pixels,
+    width: loaded.width
+  });
+  rememberResolvedImage(cacheKey, resolved);
+  return { ...resolved, data: Buffer.from(resolved.data) };
 };
 const isRemoteCandidate = (source) => /^https?:/i.test(source);
 const imageResolutionCacheKey = (source) => {
@@ -443,12 +518,10 @@ export const resolvePdfImageAssets = async (document, options) => {
     if (hasOwn(node.props, "srcSet") && node.props.srcSet !== void 0) {
       return blocked("PDF image srcSet sources are blocked.");
     }
-    const hasSrc = hasOwn(node.props, "src") && node.props.src !== void 0;
-    const hasSource = hasOwn(node.props, "source") && node.props.source !== void 0;
-    if (hasSrc === hasSource) {
-      return invalid("Each PDF image must have exactly one src or source prop.");
+    if (!hasOwn(node.props, "src") || node.props.src === void 0) {
+      return invalid("Each PDF image must have a src prop.");
     }
-    targets.push({ node, prop: hasSrc ? "src" : "source" });
+    targets.push({ node });
   }
   if (targets.length > limits.maxImages) {
     return imageLimitExceeded(
@@ -459,7 +532,7 @@ export const resolvePdfImageAssets = async (document, options) => {
   try {
     resolved = await Promise.all(targets.map(
       (target) => resolveImageBuffer(
-        target.node.props[target.prop],
+        target.node.props.src,
         options.assets,
         limits,
         options.remote,
@@ -475,7 +548,7 @@ export const resolvePdfImageAssets = async (document, options) => {
   }
   targets.forEach((target, index) => {
     const data = resolved[index];
-    target.node.props[target.prop] = data;
+    target.node.props.src = data;
     state.resolved.set(data, Promise.resolve(data));
   });
   return document;

package/dist/runtime/server/engine/fonts.d.ts

@@ -5,4 +5,5 @@ export type PdfFontStore = {
     readonly [pdfFontStoreBrand]: true;
 };
 export declare const createPdfFontStore: (fonts?: readonly BundledPdfFontDescriptor[]) => PdfFontStore;
+export declare const getSharedPdfFontStore: (fonts?: readonly BundledPdfFontDescriptor[]) => PdfFontStore;
 export {};

package/dist/runtime/server/engine/fonts.js

@@ -17,3 +17,16 @@ export const createPdfFontStore = (fonts = []) => {
   }
   return fontStore;
 };
+const sameFontList = (left, right) => left.length === right.length && left.every((font, index) => {
+  const other = right[index];
+  return font.family === other.family && font.src === other.src && font.fontStyle === other.fontStyle && font.fontWeight === other.fontWeight;
+});
+let sharedFontStore;
+export const getSharedPdfFontStore = (fonts = []) => {
+  if (sharedFontStore && sameFontList(sharedFontStore.fonts, fonts)) {
+    return sharedFontStore.store;
+  }
+  const store = createPdfFontStore(fonts);
+  sharedFontStore = { fonts, store };
+  return store;
+};

package/dist/runtime/server/preview.js

@@ -127,7 +127,7 @@ const indexPage = (registry, rootPath) => {
   if (templates.length === 0) {
     return htmlResponse(
       "PDF templates",
-      "<header><h1>PDF templates</h1></header><p>No templates found. Add <code>pdfs/invoice.vue</code> and restart the development server.</p>"
+      "<header><h1>PDF templates</h1></header><p>No templates found. Add <code>pdfs/invoice.vue</code>; Nuxt PDF restarts and registers it automatically.</p>"
     );
   }
   const cards = templates.map((template) => {
@@ -225,7 +225,7 @@ const viewerPage = async (template, props, rootPath, scenario, hmrClientPath2 =
   }
   return htmlResponse(
     title,
-    `<header><h1>${escapeHtml(title)}</h1>${actions}</header>${nav}${body}<script type="module">import { createHotContext } from ${JSON.stringify(hmrClientPath2)};createHotContext('/_pdf').on('nuxt-pdf:update',()=>location.reload());<\/script>`
+    `<header><h1>${escapeHtml(title)}</h1>${actions}</header>${nav}${body}<script type="module">import { createHotContext } from ${JSON.stringify(hmrClientPath2)};createHotContext('/_pdf').on('nuxt-pdf:update',()=>{const frame=document.querySelector('iframe');if(frame&&frame.contentWindow){frame.contentWindow.location.reload();}else{location.reload();}});<\/script>`
   );
 };
 export const renderPdfPreview = async (registry, request = {}) => {

package/dist/runtime/server/registry.js

@@ -17,7 +17,7 @@ import {
   enforceTreeLimits,
   resolvePdfRenderLimits
 } from "./render-limits.js";
-import { createPdfFontStore } from "./engine/fonts.js";
+import { getSharedPdfFontStore } from "./engine/fonts.js";
 import { createPdfRenderResult } from "./result.js";
 const EMPTY_SCENARIOS = Object.freeze({});
 const EMPTY_ASSETS = Object.freeze({});
@@ -123,7 +123,7 @@ const renderTemplate = async (component, props, metadata, options, maxPasses, li
       component,
       props
     );
-    const fontStore = createPdfFontStore(options.fonts);
+    const fontStore = getSharedPdfFontStore(options.fonts);
     if (mounted.usesPageNumbers) {
       const live = mounted;
       const result2 = await renderDocumentMultiPass(

package/dist/shared/{nuxt-pdf.D2ZziYn4.mjs → nuxt-pdf._V584vX4.mjs}

@@ -22,7 +22,7 @@ const classifyPdfWatchEvent = (event, absolutePath, layers, isIgnored) => {
     if (PDF_STRUCTURE_EVENTS.has(event)) return "restart";
     if (event !== "change") return "ignore";
     const [rootDirectory] = pathWithinPdfs.split(/[\\/]/);
-    return rootDirectory === "assets" || rootDirectory === "fonts" ? "restart" : "refresh";
+    return rootDirectory === "fonts" ? "restart" : "refresh";
   }
   return "ignore";
 };

package/dist/test.mjs

@@ -2,7 +2,7 @@ import { createRequire } from 'node:module';
 import { defineComponent, h } from 'vue';
 import { normalizeRemoteAssetPolicy } from '../dist/runtime/server/assets/remote.js';
 import { createPdfTemplate } from '../dist/runtime/server/registry.js';
-import { normalizePdfLimits, resolvePdfRenderLimits } from '../dist/runtime/server/render-limits.js';
+import { normalizePdfLimits } from '../dist/runtime/server/render-limits.js';
 import { PDF_DEFINITION_PROPERTY } from '../dist/runtime/shared/template.js';
 import { Buffer } from 'node:buffer';
 import { existsSync } from 'node:fs';
@@ -10,8 +10,8 @@ import { mkdir, writeFile, rm, readFile, readdir } from 'node:fs/promises';
 import { resolve, dirname, join, relative, basename } from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { build } from 'esbuild';
-import { t as templateKeyFromRelativePath, b as discoverPdfImageFiles, c as bundlePdfFonts, g as compilePdfSfc } from './shared/nuxt-pdf.D2ZziYn4.mjs';
-import { loadPdfImageAsset } from '../dist/runtime/server/assets/resolve-asset.js';
+import { t as templateKeyFromRelativePath, b as discoverPdfImageFiles, c as bundlePdfFonts, g as compilePdfSfc } from './shared/nuxt-pdf._V584vX4.mjs';
+import { pdfImageFormatFromKey } from '../dist/runtime/server/assets/resolve-asset.js';
 import '@vue/compiler-sfc';
 import '@jridgewell/remapping';
 import 'unimport';
@@ -571,18 +571,15 @@ async function renderPdfSfc(filename, props, options = {}) {
     throw new Error(`PDF SFC ${JSON.stringify(entry)} must be a template directly inside pdfs/ or one of its feature directories.`);
   }
   const normalizedLimits = normalizePdfLimits(options.limits);
-  const limits = resolvePdfRenderLimits(normalizedLimits);
   const [component, imageFiles, fonts] = await Promise.all([
     loadPdfSfc(entry),
     discoverPdfImageFiles([{ name: "test", rootDir }]),
     bundlePdfFonts(options.fonts ?? [], { fontRoots: [join(rootDir, "pdfs", "fonts")] })
   ]);
-  const loadedAssets = await Promise.all(imageFiles.map((image) => loadPdfImageAsset(image.key, {
-    roots: [image.rootDir],
-    maxBytes: limits.maxImageBytes,
-    maxPixels: limits.maxImagePixels
-  })));
-  const assets = Object.fromEntries(loadedAssets.map((asset) => [asset.key, asset]));
+  const assets = Object.fromEntries(imageFiles.map((image) => [
+    image.key,
+    Object.freeze({ format: pdfImageFormatFromKey(image.key), root: image.rootDir })
+  ]));
   return renderPreparedPdfTemplate(component, props, {
     assets,
     file: `pdfs/${relativePath}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/nuxt-pdf",
-  "version": "0.3.1",
+  "version": "0.4.0-beta.1",
   "description": "Author and render PDFs with Vue components in Nuxt",
   "keywords": [
     "nuxt",
@@ -56,9 +56,10 @@
     "build": "nuxt prepare && nuxt-module-build build",
     "api:write": "node scripts/check-api-report.mjs --write",
     "changelog": "changelogen --no-output",
-    "docs:build": "pnpm build && pnpm --dir docs build",
+    "docs:build": "pnpm docs:theme && pnpm build && pnpm --dir docs build",
     "docs:build:vercel": "node scripts/build-docs-vercel.mjs",
     "docs:dev": "pnpm --dir docs dev",
+    "docs:theme": "node scripts/check-docs-theme.mjs",
     "format": "eslint . --fix",
     "format:check": "eslint .",
     "lint": "eslint .",
@@ -70,7 +71,7 @@
     "release:verify": "pnpm verify && pnpm release:pack",
     "test:artifact": "node scripts/check-release-artifact.mjs",
     "test:dependencies": "node scripts/check-production-dependencies.mjs",
-    "test:docs": "node scripts/check-documentation.mjs && pnpm --dir docs check",
+    "test:docs": "node scripts/check-documentation.mjs && pnpm docs:theme && pnpm --dir docs check",
     "test:package": "node scripts/check-package.mjs",
     "test:package-metadata": "node scripts/check-api-report.mjs",
     "test:performance": "node --expose-gc ./node_modules/vitest/vitest.mjs run --config vitest.performance.config.ts",
@@ -139,6 +140,7 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.8",
     "vue": "3.5.40",
-    "vue-tsc": "^3.3.3"
+    "vue-tsc": "^3.3.3",
+    "yaml": "2.9.0"
   }
 }