@lupinum/nuxt-pdf 0.3.0

package/dist/runtime/server/engine/render-document.js

@@ -0,0 +1,236 @@
+import { Buffer } from "node:buffer";
+import layoutDocument from "@react-pdf/layout";
+import PDFDocument from "@react-pdf/pdfkit";
+import renderPDF from "@react-pdf/render";
+import {
+  createPdfFontStore
+} from "./fonts.js";
+import {
+  NuxtPdfError,
+  PDF_ERROR_CODES
+} from "../../shared/errors.js";
+import {
+  PDF_PRIMITIVES
+} from "../../authoring.js";
+import {
+  enforceMaxPages
+} from "../render-limits.js";
+const runLayout = layoutDocument;
+const DYNAMIC_LINE_HEIGHT_SENTINEL = "";
+const normalizeDynamicTextLineHeight = (node) => {
+  if (node.type === PDF_PRIMITIVES.Text && typeof node.props.render === "function") {
+    node.style = Array.isArray(node.style) ? [...node.style, { lineHeight: DYNAMIC_LINE_HEIGHT_SENTINEL }] : { ...node.style ?? {}, lineHeight: DYNAMIC_LINE_HEIGHT_SENTINEL };
+  }
+  for (const child of node.children) {
+    if ("children" in child) {
+      normalizeDynamicTextLineHeight(child);
+    }
+  }
+};
+const compact = (values) => Object.fromEntries(
+  Object.entries(values).filter(([, value]) => value !== void 0 && value !== null)
+);
+const collectStream = (stream, limits) => new Promise((resolve, reject) => {
+  const chunks = [];
+  let total = 0;
+  stream.on("data", (chunk) => {
+    try {
+      limits?.deadline.check();
+      const bytes = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+      total += bytes.byteLength;
+      if (limits && total > limits.maxOutputBytes) {
+        const error = new NuxtPdfError(
+          PDF_ERROR_CODES.LimitExceeded,
+          `PDF output exceeded pdf.limits.maxOutputBytes (${limits.maxOutputBytes}).`
+        );
+        limits.abortController.abort(error);
+        stream.destroy(error);
+        return;
+      }
+      chunks.push(bytes);
+    } catch (error) {
+      const cause = error instanceof Error ? error : new Error(String(error));
+      limits?.abortController.abort(cause);
+      stream.destroy(cause);
+    }
+  });
+  stream.on("end", () => {
+    try {
+      limits?.deadline.check();
+      resolve(Buffer.concat(chunks, total));
+    } catch (error) {
+      reject(error);
+    }
+  });
+  stream.on("error", reject);
+});
+const createContext = (props, compress) => new PDFDocument({
+  compress,
+  pdfVersion: props.pdfVersion,
+  lang: props.language,
+  displayTitle: true,
+  autoFirstPage: false,
+  pageLayout: props.pageLayout,
+  info: compact({
+    Title: props.title,
+    Author: props.author,
+    Subject: props.subject,
+    Keywords: props.keywords,
+    Creator: props.creator ?? "nuxt-pdf",
+    Producer: props.producer ?? "nuxt-pdf",
+    CreationDate: props.creationDate ?? /* @__PURE__ */ new Date()
+  })
+});
+export const layoutPdfTree = async (document, fontStore, limits) => {
+  limits?.deadline.check();
+  if (document.type !== "DOCUMENT") {
+    throw new NuxtPdfError(
+      PDF_ERROR_CODES.TreeInvalid,
+      `Expected a DOCUMENT root, received ${document.type}.`
+    );
+  }
+  normalizeDynamicTextLineHeight(document);
+  let layout;
+  try {
+    layout = await runLayout(
+      document,
+      fontStore
+    );
+  } catch (error) {
+    throw new NuxtPdfError(
+      PDF_ERROR_CODES.LayoutError,
+      `PDF layout failed: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+  limits?.deadline.check();
+  if (limits) enforceMaxPages(countPages(layout), limits.maxPages);
+  return layout;
+};
+const visitPageNodes = (page, visit) => {
+  if (!("props" in page)) return;
+  visit(page);
+  const children = page.children;
+  if (Array.isArray(children)) {
+    for (const child of children) visitPageNodes(child, visit);
+  }
+};
+const documentPages = (layout) => layout.children ?? [];
+export const countPages = (layout) => documentPages(layout).length;
+const nodeId = (node) => {
+  const id = node.props?.id;
+  return typeof id === "string" && id.length > 0 ? id : void 0;
+};
+export const extractDestinationPages = (layout) => {
+  const pages = /* @__PURE__ */ Object.create(null);
+  documentPages(layout).forEach((page, index) => {
+    const pageNumber = index + 1;
+    visitPageNodes(page, (node) => {
+      const id = nodeId(node);
+      if (id !== void 0 && !Object.hasOwn(pages, id)) pages[id] = pageNumber;
+    });
+  });
+  return pages;
+};
+const anchorDestinationsAtFirstPage = (layout) => {
+  const seen = /* @__PURE__ */ new Set();
+  const strip = (node) => {
+    if (!("props" in node)) return node;
+    const element = node;
+    let next = element;
+    const id = nodeId(element);
+    if (id !== void 0) {
+      if (!seen.has(id)) {
+        seen.add(id);
+      } else {
+        const { id: _dropped, ...rest } = element.props;
+        next = { ...element, props: rest };
+      }
+    }
+    const children = next.children;
+    if (Array.isArray(children)) {
+      let changed = false;
+      const stripped = children.map((child) => {
+        const result = strip(child);
+        if (result !== child) changed = true;
+        return result;
+      });
+      if (changed) next = { ...next, children: stripped };
+    }
+    return next;
+  };
+  const root = layout;
+  root.children = documentPages(layout).map(strip);
+};
+const SVG_SHAPE_TYPES = /* @__PURE__ */ new Set([
+  PDF_PRIMITIVES.Circle,
+  PDF_PRIMITIVES.Ellipse,
+  PDF_PRIMITIVES.G,
+  PDF_PRIMITIVES.Line,
+  PDF_PRIMITIVES.Path,
+  PDF_PRIMITIVES.Polygon,
+  PDF_PRIMITIVES.Polyline,
+  PDF_PRIMITIVES.Rect,
+  PDF_PRIMITIVES.Text
+]);
+const GRADIENT_ZERO_KEYS = {
+  [PDF_PRIMITIVES.LinearGradient]: ["x2"],
+  [PDF_PRIMITIVES.RadialGradient]: ["cx", "cy", "fx", "fy", "r"]
+};
+const normalizeGradientZeros = (value) => {
+  if (typeof value !== "object" || value === null || !("type" in value) || !("props" in value) || value.type !== PDF_PRIMITIVES.LinearGradient && value.type !== PDF_PRIMITIVES.RadialGradient || typeof value.props !== "object" || value.props === null) return;
+  const props = value.props;
+  const keys = GRADIENT_ZERO_KEYS[value.type];
+  for (const key of keys) {
+    if (props[key] === 0) props[key] = "0";
+  }
+};
+const normalizeResolvedSvgZeros = (layout) => {
+  for (const page of documentPages(layout)) {
+    visitPageNodes(page, (node) => {
+      normalizeGradientZeros(node.props.fill);
+      if (!SVG_SHAPE_TYPES.has(node.type)) return;
+      if (node.props.fillOpacity === 0) node.props.fillOpacity = "0";
+      if (node.props.strokeWidth === 0) node.props.stroke = null;
+    });
+  }
+};
+export const serializePdfLayout = async (props, layout, compress, limits) => {
+  limits?.deadline.check();
+  try {
+    anchorDestinationsAtFirstPage(layout);
+    normalizeResolvedSvgZeros(layout);
+    const context = createContext(props, compress);
+    const collected = collectStream(context, limits);
+    try {
+      renderPDF(
+        context,
+        layout
+      );
+    } catch (error) {
+      const cause = error instanceof Error ? error : new Error(String(error));
+      context.destroy(cause);
+      await collected.catch(() => void 0);
+      throw cause;
+    }
+    return await collected;
+  } catch (error) {
+    if (error instanceof NuxtPdfError) throw error;
+    throw new NuxtPdfError(
+      PDF_ERROR_CODES.RenderError,
+      `PDF serialization failed: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+};
+export const renderDocument = async (document, options = {}) => {
+  const fontStore = options.fontStore ?? createPdfFontStore();
+  const layout = await layoutPdfTree(document, fontStore, options.limits);
+  const bytes = await serializePdfLayout(
+    document.props,
+    layout,
+    options.compress ?? true,
+    options.limits
+  );
+  return { bytes, layout };
+};

package/dist/runtime/server/index.d.ts

@@ -0,0 +1,5 @@
+export { createPdfPreviewEntry, createPdfRegistry, createPdfTemplate, } from './registry.js';
+export { NuxtPdfError, PDF_ERROR_CODES, } from '../shared/errors.js';
+export type { PdfErrorCode } from '../shared/errors.js';
+export type { PdfPreviewEntry, PdfPreviewEntryOptions, PdfRegistry, PdfRegistryEntries, } from './registry.js';
+export type { PdfRenderDiagnostics, PdfRenderResult, PdfComponentProps, PdfTemplate, } from '../shared/template.js';

package/dist/runtime/server/index.js

@@ -0,0 +1,9 @@
+export {
+  createPdfPreviewEntry,
+  createPdfRegistry,
+  createPdfTemplate
+} from "./registry.js";
+export {
+  NuxtPdfError,
+  PDF_ERROR_CODES
+} from "../shared/errors.js";

package/dist/runtime/server/preview.d.ts

@@ -0,0 +1,17 @@
+import type { PdfPreviewEntry } from './registry.js';
+type PreviewTemplate = PdfPreviewEntry<object>;
+export type PdfPreviewRegistry = Readonly<Record<string, PreviewTemplate>>;
+export interface PdfPreviewRequest {
+    path?: string;
+    rootPath?: string;
+    scenario?: string;
+    /** Token of a parked viewer render the raw route should serve verbatim. */
+    render?: string;
+    /** Serve a raw response as a download instead of inline. */
+    download?: boolean;
+    /** Nuxt/Vite client path used by the development-only auto-refresh hook. */
+    hmrClientPath?: string;
+}
+export declare const renderPdfPreview: (registry: PdfPreviewRegistry, request?: PdfPreviewRequest) => Promise<Response>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Response>>;
+export default _default;

package/dist/runtime/server/preview.js

@@ -0,0 +1,332 @@
+import { randomBytes } from "node:crypto";
+import {
+  defineEventHandler,
+  getQuery,
+  getRequestURL
+} from "h3";
+import { pdfPreview } from "#pdf";
+import { hmrClientPath } from "#pdf-preview-config";
+import { NuxtPdfError } from "../shared/errors.js";
+const PREVIEW_ROUTE = "/_pdf";
+const parkedRenders = /* @__PURE__ */ new Map();
+const lastSuccessfulRenders = /* @__PURE__ */ new WeakMap();
+const PARKED_RENDER_LIMIT = 8;
+const PARKED_RENDER_TTL_MS = 3e4;
+const DEFAULT_HMR_CLIENT_PATH = "/_nuxt/@vite/client";
+const scenarioCacheKey = (scenario) => scenario ?? "\0";
+const rememberSuccessfulRender = (template, result, scenario) => {
+  let renders = lastSuccessfulRenders.get(template);
+  if (!renders) {
+    renders = /* @__PURE__ */ new Map();
+    lastSuccessfulRenders.set(template, renders);
+  }
+  renders.set(scenarioCacheKey(scenario), result);
+};
+const previousSuccessfulRender = (template, scenario) => lastSuccessfulRenders.get(template)?.get(scenarioCacheKey(scenario));
+const pruneExpiredRenders = (now) => {
+  for (const [token, render] of parkedRenders) {
+    if (render.expiresAt <= now) parkedRenders.delete(token);
+  }
+};
+const createRenderToken = () => {
+  let token;
+  do
+    token = randomBytes(32).toString("base64url");
+  while (parkedRenders.has(token));
+  return token;
+};
+const parkRender = (result, key, scenario) => {
+  const now = Date.now();
+  pruneExpiredRenders(now);
+  const token = createRenderToken();
+  parkedRenders.set(token, {
+    expiresAt: now + PARKED_RENDER_TTL_MS,
+    key,
+    result,
+    scenario
+  });
+  while (parkedRenders.size > PARKED_RENDER_LIMIT) {
+    const oldest = parkedRenders.keys().next().value;
+    if (oldest === void 0) break;
+    parkedRenders.delete(oldest);
+  }
+  return token;
+};
+const takeParkedRender = (token, key, scenario) => {
+  const render = parkedRenders.get(token);
+  if (!render) return void 0;
+  if (render.expiresAt <= Date.now()) {
+    parkedRenders.delete(token);
+    return void 0;
+  }
+  if (render.key !== key || render.scenario !== scenario) return void 0;
+  parkedRenders.delete(token);
+  return render.result;
+};
+const escapeHtml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#039;");
+const htmlResponse = (title, content, status = 200) => new Response(`<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${escapeHtml(title)} \xB7 Nuxt PDF</title>
+    <style>
+      :root { color-scheme: light dark; font-family: ui-sans-serif, system-ui, sans-serif; }
+      * { box-sizing: border-box; }
+      body { margin: 0; background: #101211; color: #f3f5f2; }
+      main { width: min(1120px, calc(100% - 32px)); margin: 0 auto; padding: 32px 0; }
+      a { color: #a9e477; }
+      header { display: flex; align-items: baseline; justify-content: space-between; gap: 16px; margin-bottom: 24px; }
+      h1 { margin: 0; font-size: clamp(1.5rem, 4vw, 2.5rem); letter-spacing: -0.04em; }
+      p { color: #b6beb6; line-height: 1.6; }
+      code { color: #dce4dc; }
+      .actions { display: flex; align-items: baseline; gap: 16px; }
+      nav { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 16px; }
+      nav a { border: 1px solid #3f493f; border-radius: 999px; padding: 6px 11px; text-decoration: none; color: #dce4dc; }
+      nav a.active { background: #a9e477; border-color: #a9e477; color: #101211; font-weight: 600; }
+      iframe { width: 100%; min-height: calc(100vh - 300px); border: 1px solid #343a35; border-radius: 10px; background: white; }
+      .cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 12px; }
+      .card { border: 1px solid #343a35; border-radius: 10px; padding: 16px; display: flex; flex-direction: column; gap: 6px; }
+      .card strong { font-size: 1.05rem; }
+      .card .file { color: #8b948b; font-size: 0.8rem; word-break: break-all; }
+      .card .meta { color: #b6beb6; font-size: 0.85rem; }
+      .card .links { margin-top: 8px; display: flex; gap: 14px; }
+      .diagnostics { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 10px; margin-bottom: 16px; }
+      .stat { border: 1px solid #343a35; border-radius: 10px; padding: 12px 14px; }
+      .stat .label { color: #8b948b; font-size: 0.72rem; letter-spacing: 0.06em; text-transform: uppercase; }
+      .stat .value { font-size: 1.35rem; font-variant-numeric: tabular-nums; margin-top: 4px; }
+      .font-faces { border: 1px solid #343a35; background: #151815; border-radius: 10px; padding: 12px 16px; margin-bottom: 16px; }
+      .font-faces .label { color: #8b948b; font-size: 0.78rem; letter-spacing: 0.04em; text-transform: uppercase; margin-bottom: 8px; }
+      .font-faces ul { list-style: none; margin: 0; padding: 0; display: grid; gap: 6px; }
+      .font-faces li { color: #d7ddd7; font-size: 0.85rem; line-height: 1.5; }
+      .error { border: 1px solid #6b2f2b; background: #1d1210; border-left: 3px solid #ef786f; border-radius: 10px; padding: 18px 20px; }
+      .error h2 { margin: 0 0 12px; font-size: 1.1rem; color: #f3d7d3; }
+      .error dl { display: grid; grid-template-columns: max-content 1fr; gap: 6px 16px; margin: 0 0 12px; }
+      .error dt { color: #c69a95; font-size: 0.8rem; }
+      .error dd { margin: 0; font-family: ui-monospace, SFMono-Regular, monospace; font-size: 0.85rem; word-break: break-all; }
+      .error .message { color: #f0d9d6; line-height: 1.6; white-space: pre-wrap; }
+      .stale { border: 1px solid #755d25; background: #211b0e; color: #f1d88c; border-radius: 10px; padding: 12px 16px; margin: 16px 0; }
+    </style>
+  </head>
+  <body><main>${content}</main></body>
+</html>`, {
+  status,
+  headers: {
+    "cache-control": "no-store",
+    "content-type": "text/html; charset=utf-8",
+    "x-content-type-options": "nosniff"
+  }
+});
+const encodeTemplatePath = (key) => key.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+const templateByKey = (registry, key) => Object.values(registry).find((entry) => entry.template.key === key);
+const scenarioCount = (template) => template.scenarioNames.length > 0 ? `${template.scenarioNames.length} scenario${template.scenarioNames.length === 1 ? "" : "s"}` : "sample data";
+const indexPage = (registry, rootPath) => {
+  const templates = Object.values(registry).sort(
+    (left, right) => left.template.key.localeCompare(right.template.key)
+  );
+  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>"
+    );
+  }
+  const cards = templates.map((template) => {
+    const base = `${rootPath}/${encodeTemplatePath(template.template.key)}`;
+    const file = template.file ? `<span class="file">${escapeHtml(template.file)}</span>` : "";
+    return `<article class="card"><strong>${escapeHtml(template.template.key)}</strong>` + file + `<span class="meta">${scenarioCount(template)}</span><span class="links"><a href="${escapeHtml(base)}">Preview</a><a href="${escapeHtml(`${base}.pdf`)}">Raw PDF</a></span></article>`;
+  }).join("");
+  return htmlResponse(
+    "PDF templates",
+    `<header><h1>PDF templates</h1><span>${templates.length}</span></header><div class="cards">${cards}</div>`
+  );
+};
+const errorPage = (title, message, rootPath, status) => htmlResponse(
+  title,
+  `<header><h1>${escapeHtml(title)}</h1><a href="${escapeHtml(rootPath)}">All templates</a></header><div class="error"><p class="message">${escapeHtml(message)}</p></div>`,
+  status
+);
+const rawUrl = (rootPath, key, scenario, renderToken, download = false) => {
+  const params = new URLSearchParams();
+  if (scenario !== void 0) params.set("scenario", scenario);
+  if (renderToken !== void 0) params.set("render", renderToken);
+  if (download) params.set("download", "1");
+  const query = params.size > 0 ? `?${params.toString()}` : "";
+  return `${rootPath}/${encodeTemplatePath(key)}.pdf${query}`;
+};
+const scenarioNav = (template, rootPath, active) => {
+  const base = `${rootPath}/${encodeTemplatePath(template.template.key)}`;
+  const tab = (label, href, isActive) => `<a href="${escapeHtml(href)}"${isActive ? ' class="active" aria-current="page"' : ""}>${escapeHtml(label)}</a>`;
+  const tabs = [
+    tab("Default", base, active === void 0),
+    ...template.scenarioNames.map(
+      (name) => tab(name, `${base}?scenario=${encodeURIComponent(name)}`, active === name)
+    )
+  ].join("");
+  return `<nav>${tabs}</nav>`;
+};
+const formatDuration = (ms) => ms >= 1e3 ? `${(ms / 1e3).toFixed(2)} s` : `${Math.round(ms)} ms`;
+const formatBytes = (bytes) => bytes >= 1024 * 1024 ? `${(bytes / (1024 * 1024)).toFixed(2)} MB` : `${(bytes / 1024).toFixed(1)} KB`;
+const diagnosticsPanel = (diagnostics) => {
+  const stat = (label, value) => `<div class="stat"><div class="label">${label}</div><div class="value">${escapeHtml(value)}</div></div>`;
+  const stats = [
+    stat("Duration", formatDuration(diagnostics.durationMs)),
+    stat("Size", formatBytes(diagnostics.byteLength)),
+    stat("Pages", String(diagnostics.pageCount)),
+    stat("Layout passes", String(diagnostics.passes)),
+    stat("Font faces", String(diagnostics.registeredFontFaces.length))
+  ].join("");
+  const fonts = diagnostics.registeredFontFaces.length > 0 ? `<div class="font-faces"><div class="label">Registered font faces</div><ul>${diagnostics.registeredFontFaces.map((face) => {
+    const attributes = [face.fontWeight, face.fontStyle].filter((value) => value !== void 0);
+    return `<li>${escapeHtml(face.family)}${attributes.length > 0 ? ` \u2014 ${escapeHtml(attributes.join(" "))}` : ""}</li>`;
+  }).join("")}</ul></div>` : "";
+  return `<div class="diagnostics">${stats}</div>${fonts}`;
+};
+const errorDetails = (error, fallbackKey, fallbackFile) => {
+  const code = error instanceof NuxtPdfError ? error.code : "PDF_RENDER_ERROR";
+  const name = error instanceof NuxtPdfError && error.templateKey ? error.templateKey : fallbackKey;
+  const file = error instanceof NuxtPdfError && error.templateFile ? error.templateFile : fallbackFile;
+  const message = error instanceof NuxtPdfError ? {
+    PDF_ASSET_BLOCKED: "A PDF resource was blocked by the configured policy.",
+    PDF_ASSET_INVALID: "A PDF resource failed validation.",
+    PDF_LAYOUT_ERROR: "PDF layout failed. Check the server output for details.",
+    PDF_LIMIT_EXCEEDED: "The PDF exceeded a configured render limit.",
+    PDF_RENDER_ERROR: "PDF serialization failed. Check the server output for details.",
+    PDF_TEMPLATE_INVALID: "The PDF template definition is invalid.",
+    PDF_TEMPLATE_NOT_FOUND: "The PDF template is not registered.",
+    PDF_TREE_INVALID: "The rendered PDF component tree is invalid."
+  }[error.code] : `Failed to render PDF template "${fallbackKey}".`;
+  const safeFile = file && !/^(?:[A-Z]:\\|\/)/u.test(file) ? file : void 0;
+  const fileRow = safeFile ? `<dt>File</dt><dd>${escapeHtml(safeFile)}</dd>` : "";
+  return `<div class="error"><h2>This template failed to render</h2><dl><dt>Code</dt><dd>${escapeHtml(code)}</dd><dt>Template</dt><dd>${escapeHtml(name)}</dd>` + fileRow + `</dl><p class="message">${escapeHtml(message)}</p></div>`;
+};
+const viewerPage = async (template, props, rootPath, scenario, hmrClientPath2 = DEFAULT_HMR_CLIENT_PATH) => {
+  const handle = template.template;
+  const base = `${rootPath}/${encodeTemplatePath(handle.key)}`;
+  const scenarioQuery = scenario === void 0 ? "" : `?scenario=${encodeURIComponent(scenario)}`;
+  const refreshHref = `${base}${scenarioQuery}${scenarioQuery ? "&" : "?"}_r=${Date.now()}`;
+  const nav = scenarioNav(template, rootPath, scenario);
+  const actions = `<span class="actions"><a href="${escapeHtml(refreshHref)}">Refresh</a><a href="${escapeHtml(rawUrl(rootPath, handle.key, scenario))}">Raw PDF</a><a href="${escapeHtml(rawUrl(rootPath, handle.key, scenario, void 0, true))}">Download</a><a href="${escapeHtml(rootPath)}">All templates</a></span>`;
+  let body;
+  let title;
+  try {
+    const result = await handle.render(props);
+    rememberSuccessfulRender(template, result, scenario);
+    title = result.metadata.title || handle.key;
+    const token = parkRender(result, handle.key, scenario);
+    body = diagnosticsPanel(result.diagnostics) + `<iframe title="${escapeHtml(title)}" src="${escapeHtml(rawUrl(rootPath, handle.key, scenario, token))}"></iframe>`;
+  } catch (error) {
+    title = handle.key;
+    body = errorDetails(error, handle.key, template.file);
+    const stale = previousSuccessfulRender(template, scenario);
+    if (stale) {
+      const token = parkRender(stale, handle.key, scenario);
+      body += `<div class="stale" role="status">Render failed. Showing the previous successful PDF; it is stale.</div><iframe title="${escapeHtml(title)} (stale)" src="${escapeHtml(rawUrl(rootPath, handle.key, scenario, token))}"></iframe>`;
+    }
+  }
+  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>`
+  );
+};
+export const renderPdfPreview = async (registry, request = {}) => {
+  const rootPath = request.rootPath?.replace(/\/$/, "") || PREVIEW_ROUTE;
+  let path;
+  try {
+    path = decodeURIComponent(request.path?.replace(/^\/+|\/+$/g, "") || "");
+  } catch {
+    return errorPage(
+      "Invalid preview URL",
+      "The template path contains invalid URL encoding.",
+      rootPath,
+      400
+    );
+  }
+  if (!path) return indexPage(registry, rootPath);
+  const raw = path.endsWith(".pdf");
+  const key = raw ? path.slice(0, -4) : path;
+  const template = templateByKey(registry, key);
+  if (!template) {
+    return errorPage(
+      "Template not found",
+      `No PDF template is registered as "${key}".`,
+      rootPath,
+      404
+    );
+  }
+  if (request.scenario !== void 0 && !template.scenarioNames.includes(request.scenario)) {
+    const available = template.scenarioNames.length > 0 ? template.scenarioNames.join(", ") : "none";
+    return errorPage(
+      "Scenario not found",
+      `Unknown scenario "${request.scenario}" for "${key}". Available scenarios: ${available}.`,
+      rootPath,
+      404
+    );
+  }
+  const props = template.getPreviewProps(request.scenario);
+  if (!props) {
+    return errorPage(
+      "Preview data required",
+      `Add sampleData to definePdf() in "${key}", or choose one of its named scenarios.`,
+      rootPath,
+      422
+    );
+  }
+  if (!raw) {
+    return viewerPage(
+      template,
+      props,
+      rootPath,
+      request.scenario,
+      request.hmrClientPath
+    );
+  }
+  const disposition = request.download ? "attachment" : "inline";
+  const parked = request.render === void 0 ? void 0 : takeParkedRender(request.render, key, request.scenario);
+  if (parked) {
+    return parked.response({
+      disposition,
+      headers: {
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff"
+      }
+    });
+  }
+  try {
+    const result = await template.template.render(props);
+    return result.response({
+      disposition,
+      headers: {
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff"
+      }
+    });
+  } catch (error) {
+    return errorPage(
+      "PDF render failed",
+      error instanceof NuxtPdfError ? `${error.code}: The PDF could not be rendered. Check the server output for attributed details.` : `Failed to render PDF template "${key}". Check the server output for details.`,
+      rootPath,
+      500
+    );
+  }
+};
+const requestRoute = (pathname) => {
+  const routeIndex = pathname.lastIndexOf(PREVIEW_ROUTE);
+  if (routeIndex < 0) return { path: "", rootPath: PREVIEW_ROUTE };
+  const rootEnd = routeIndex + PREVIEW_ROUTE.length;
+  return {
+    path: pathname.slice(rootEnd),
+    rootPath: pathname.slice(0, rootEnd)
+  };
+};
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event);
+  const query = getQuery(event);
+  const route = requestRoute(url.pathname);
+  return renderPdfPreview(pdfPreview, {
+    ...route,
+    scenario: typeof query.scenario === "string" ? query.scenario : void 0,
+    render: typeof query.render === "string" ? query.render : void 0,
+    download: query.download === "1",
+    hmrClientPath
+  });
+});

package/dist/runtime/server/registry.d.ts

@@ -0,0 +1,41 @@
+import type { Component } from 'vue';
+import { type PdfRenderResult, type PdfTemplate } from '../shared/template.js';
+import { type PdfImageAssetMap } from './assets/resolve-asset.js';
+import type { RemoteAssetPolicy } from './assets/remote.js';
+import { type PdfRenderLimits } from './render-limits.js';
+import type { BundledPdfFontDescriptor } from '../fonts.js';
+export type { PdfRenderDiagnostics } from '../shared/template.js';
+export interface PdfTemplateRuntimeOptions {
+    assets?: PdfImageAssetMap;
+    file?: string;
+    fonts?: readonly BundledPdfFontDescriptor[];
+    remote?: RemoteAssetPolicy;
+    /**
+     * Render limits (time budget + page cap). Absent means the generous built-in
+     * defaults apply, so every render is bounded even with no `pdf.limits` config.
+     */
+    limits?: PdfRenderLimits;
+}
+type PdfTemplateIdentity = Pick<PdfTemplate<object>, 'key' | 'render'>;
+export type PdfRegistryEntries = Readonly<Record<string, PdfTemplateIdentity>>;
+export interface PdfRegistry<Entries extends PdfRegistryEntries = PdfRegistryEntries> {
+    readonly pdf: Readonly<Entries>;
+    readonly pdfTemplateKeys: readonly string[];
+    getPdfTemplate(key: string): Entries[keyof Entries] | undefined;
+    renderPdf(key: string, props: object): Promise<PdfRenderResult>;
+}
+export declare const createPdfTemplate: <Props extends object>(key: string, component: Component, options?: PdfTemplateRuntimeOptions) => PdfTemplate<Props>;
+/**
+ * Internal development-only information for the preview UI. It wraps the
+ * production handle instead of extending it, so preview fixtures and source
+ * paths cannot accidentally become part of the public template contract.
+ */
+export interface PdfPreviewEntry<Props extends object = Record<string, unknown>> {
+    readonly template: PdfTemplate<Props>;
+    readonly file?: string;
+    readonly scenarioNames: readonly string[];
+    getPreviewProps(scenario?: string): Props | undefined;
+}
+export type PdfPreviewEntryOptions = Pick<PdfTemplateRuntimeOptions, 'file'>;
+export declare const createPdfPreviewEntry: <Props extends object>(template: PdfTemplate<Props>, component: Component, options?: PdfPreviewEntryOptions) => PdfPreviewEntry<Props>;
+export declare const createPdfRegistry: <const Entries extends Record<string, PdfTemplateIdentity>>(entries: Entries) => PdfRegistry<Entries>;