@lupinum/nuxt-pdf 0.3.0

package/API_REPORT.md

@@ -0,0 +1,262 @@
+# Public API declaration report
+
+This file is derived from the built declarations and is intentionally checked
+in. Rebuild with `pnpm build && pnpm api:write`; CI verifies it with
+`pnpm test:api`. Package code and generated `#pdf` registries remain the
+canonical sources.
+
+## Package root
+
+Source: `dist/types.d.mts`
+
+```ts
+export { type RemoteAssetOptions } from '../dist/runtime/server/assets/remote.js'
+
+export { type PdfLimitsOptions } from '../dist/runtime/server/render-limits.js'
+
+export { type PdfFontDeclaration, type PdfFontStyle, type PdfFontWeight, type PdfFontWeightName } from '../dist/runtime/fonts.js'
+
+export { type PdfLength, type PdfLengthOrPercentage, type PdfPercentage, type PdfStyle, type PdfStyleEntry, type PdfStyleValue } from '../dist/runtime/authoring.js'
+
+export { type PdfBaseProps, type PdfBookmark, type PdfCircleProps, type PdfClipPathProps, type PdfDefsProps, type PdfDocumentProps, type PdfEllipseProps, type PdfGProps, type PdfImageProps, type PdfImageSource, type PdfLineProps, type PdfLinearGradientProps, type PdfLinkProps, type PdfNoteProps, type PdfPageDimension, type PdfPageProps, type PdfPageSize, type PdfPageSizeName, type PdfPageUnit, type PdfPathProps, type PdfPolygonProps, type PdfPolylineProps, type PdfRadialGradientProps, type PdfRectProps, type PdfStopProps, type PdfSvgLength, type PdfSvgNumber, type PdfSvgPresentationProps, type PdfSvgProps, type PdfSvgTransform, type PdfSvgTransformOperation, type PdfTextProps, type PdfTspanProps, type PdfViewProps } from '../dist/runtime/components/index.js'
+
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'
+```
+
+## Nuxt module
+
+Source: `dist/module.d.mts`
+
+```ts
+import * as _nuxt_schema from '@nuxt/schema';
+import { RemoteAssetOptions } from '../dist/runtime/server/assets/remote.js';
+export { RemoteAssetOptions } from '../dist/runtime/server/assets/remote.js';
+import { PdfLimitsOptions } from '../dist/runtime/server/render-limits.js';
+export { PdfLimitsOptions } from '../dist/runtime/server/render-limits.js';
+import { PdfFontDeclaration } from '../dist/runtime/fonts.js';
+export { PdfFontDeclaration, PdfFontStyle, PdfFontWeight, PdfFontWeightName } from '../dist/runtime/fonts.js';
+export { PdfLength, PdfLengthOrPercentage, PdfPercentage, PdfStyle, PdfStyleEntry, PdfStyleValue } from '../dist/runtime/authoring.js';
+export { PdfBaseProps, PdfBookmark, PdfCircleProps, PdfClipPathProps, PdfDefsProps, PdfDocumentProps, PdfEllipseProps, PdfGProps, PdfImageProps, PdfImageSource, PdfLineProps, PdfLinearGradientProps, PdfLinkProps, PdfNoteProps, PdfPageDimension, PdfPageProps, PdfPageSize, PdfPageSizeName, PdfPageUnit, PdfPathProps, PdfPolygonProps, PdfPolylineProps, PdfRadialGradientProps, PdfRectProps, PdfStopProps, PdfSvgLength, PdfSvgNumber, PdfSvgPresentationProps, PdfSvgProps, PdfSvgTransform, PdfSvgTransformOperation, PdfTextProps, PdfTspanProps, PdfViewProps } from '../dist/runtime/components/index.js';
+
+interface ModuleOptions {
+    fonts?: readonly PdfFontDeclaration[];
+    remote?: RemoteAssetOptions;
+    /**
+     * Canonical render, tree, image, remote-request, and output budgets. Every
+     * field is an optional positive safe integer; omitted fields use the
+     * documented built-in defaults.
+     */
+    limits?: PdfLimitsOptions;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };
+```
+
+## Test entry
+
+Source: `dist/test.d.mts`
+
+```ts
+import { PdfRenderResult, PdfComponentProps } from '../dist/runtime/shared/template.js';
+export { PdfComponentProps } from '../dist/runtime/shared/template.js';
+import { Component } from 'vue';
+import { ModuleOptions } from './module.mjs';
+import '@nuxt/schema';
+import '../dist/runtime/server/assets/remote.js';
+import '../dist/runtime/server/render-limits.js';
+import '../dist/runtime/fonts.js';
+import '../dist/runtime/authoring.js';
+import '../dist/runtime/components/index.js';
+
+/** Raw PDF (or PNG) bytes accepted by the low-level readers. */
+type PdfData = ArrayBuffer | Uint8Array;
+/** Anything the public `parsePdf`/`rasterizePdf` accept: bytes or a render result. */
+type PdfInput = PdfData | PdfRenderResult;
+interface PdfAnnotationReference {
+    generation: number;
+    number: number;
+}
+type PdfAnnotationDestination = string | Array<string | number | null | PdfAnnotationReference>;
+interface PdfAnnotation {
+    annotationType?: number;
+    destination?: PdfAnnotationDestination;
+    rect?: number[];
+    subtype: string;
+    unsafeUrl?: string;
+    url?: string;
+}
+/** A link annotation flattened to the fields users assert against. */
+interface ParsedPdfLink {
+    /** 1-based page the link sits on. */
+    page: number;
+    /** Named internal destination (e.g. a `#id` target), when the link is internal. */
+    destination?: string;
+    /** External URL, when the link points outside the document. */
+    url?: string;
+}
+/** A normalized PDF.js text run for tolerant layout and typography assertions. */
+interface ParsedPdfTextRun {
+    direction: string;
+    fontName: string;
+    fontSize: number;
+    height: number;
+    text: string;
+    width: number;
+    x: number;
+    y: number;
+}
+interface ParsedPdfPage {
+    annotations: PdfAnnotation[];
+    height: number;
+    number: number;
+    rawText: string;
+    text: string;
+    textItems: string[];
+    textRuns: ParsedPdfTextRun[];
+    width: number;
+}
+interface PdfOutlineItem {
+    title: string;
+    /** Initial viewer state for entries with children. Absent on leaf entries. */
+    expanded?: boolean;
+    children: PdfOutlineItem[];
+}
+interface ParsedPdf {
+    pageCount: number;
+    pages: ParsedPdfPage[];
+    /** Every link annotation in the document, flattened across pages. */
+    links: ParsedPdfLink[];
+    /** The bookmark tree (outline), including initial expansion state. */
+    outline: PdfOutlineItem[];
+}
+interface RasterizePdfOptions {
+    background?: string;
+    scale?: number;
+}
+interface PdfPageImage {
+    height: number;
+    number: number;
+    pixels: Uint8ClampedArray;
+    png: Uint8Array;
+    width: number;
+}
+interface PageImageComparison {
+    changedPixelRatio: number;
+    changedPixels: number;
+    dimensionsMatch: boolean;
+    matches: boolean;
+    maxChannelDifference: number;
+    pageNumbersMatch: boolean;
+    totalPixels: number;
+}
+/** Resolve any accepted input (bytes or a `PdfRenderResult`) to raw PDF bytes. */
+declare function toPdfBytes(input: PdfInput): Promise<Uint8Array>;
+/** Parse stable, semantic information from every page of a PDF. */
+declare function parsePdf(input: PdfInput): Promise<ParsedPdf>;
+/** Rasterize every PDF page independently for deterministic page-level diffs. */
+declare function rasterizePdf(input: PdfInput, options?: RasterizePdfOptions): Promise<PdfPageImage[]>;
+
+/**
+ * Error thrown by the `expectPdf` helpers. Named so test runners surface it like
+ * their own assertion errors, without this module depending on any runner.
+ */
+declare class PdfAssertionError extends Error {
+    constructor(message: string);
+}
+interface ToContainTextOptions {
+    /** Restrict the search to a single 1-based page. */
+    page?: number;
+}
+type LinkQuery = {
+    destination: string;
+    page?: number;
+} | {
+    url: string;
+    page?: number;
+} | {
+    destination: string;
+    url: string;
+    page?: number;
+};
+/** A partial outline shape: title is required; state and children are optional. */
+interface OutlineShape {
+    title: string;
+    expanded?: boolean;
+    children?: OutlineShape[];
+}
+interface PdfExpectation {
+    toHavePageCount(count: number): PdfExpectation;
+    toContainText(text: string, options?: ToContainTextOptions): PdfExpectation;
+    toHaveLink(query: LinkQuery): PdfExpectation;
+    toHaveOutline(shape: OutlineShape[]): PdfExpectation;
+}
+/**
+ * Fluent, runner-agnostic assertions over a `ParsedPdf`. Every method returns the
+ * same expectation so calls chain, and throws a `PdfAssertionError` on failure
+ * with a message naming what was expected and what the document actually holds.
+ */
+declare function expectPdf(parsed: ParsedPdf): PdfExpectation;
+
+/** User-shaped render policy, matching the corresponding Nuxt module options. */
+type RenderPdfTemplateOptions = Pick<ModuleOptions, 'limits' | 'remote'>;
+interface RenderedPdfTemplate {
+    /** The rendered PDF bytes. */
+    bytes: Uint8Array;
+    /** The parsed document, ready for `expectPdf`. */
+    parsed: ParsedPdf;
+    /** The underlying completed result (diagnostics, bytes, buffer, and response). */
+    result: PdfRenderResult;
+}
+/**
+ * Render a Vue PDF component through the real Nuxt PDF pipeline — mount, asset
+ * resolution, font registration, single- or multi-pass layout — without booting
+ * Nuxt, then parse the bytes so a test can assert against them immediately.
+ */
+declare function renderPdfTemplate<C extends Component>(component: C, props: PdfComponentProps<C>, options?: RenderPdfTemplateOptions): Promise<RenderedPdfTemplate>;
+
+/** User-shaped SFC render configuration, matching the Nuxt module options. */
+type RenderPdfSfcOptions = RenderPdfTemplateOptions & Pick<ModuleOptions, 'fonts'>;
+/** Compile a real PDF SFC graph with the same compiler used by the Nuxt module. */
+declare function loadPdfSfc(filename: string): Promise<Component>;
+/** Compile and render a real `pdfs/*.vue` template with production resource handling. */
+declare function renderPdfSfc<Props extends object>(filename: string, props: Props, options?: RenderPdfSfcOptions): Promise<RenderedPdfTemplate>;
+
+interface ComparePdfSnapshotOptions {
+    /** Directory for expected, actual, diff, and JSON failure artifacts. */
+    artifactDir?: string;
+    /** Maximum ratio of changed pixels allowed per page (default 0.005). */
+    threshold?: number;
+    /** Maximum per-channel RGBA difference for a matching pixel (default 25). */
+    channelThreshold?: number;
+    /** Raster scale (default 1). */
+    scale?: number;
+    /**
+     * Write the current render as the reviewed baseline instead of comparing.
+     * Defaults to `process.env.UPDATE_PDF_BASELINES === '1'`.
+     */
+    update?: boolean;
+}
+interface PdfSnapshotResult {
+    /** Whether the render matched the reviewed baseline. */
+    matches: boolean;
+    /** Whether the baseline was (re)written this run. */
+    updated: boolean;
+    /** Per-page comparison detail (empty when the baseline was written). */
+    pages: PageImageComparison[];
+}
+/**
+ * Compare a rendered PDF against a directory of reviewed per-page PNG baselines,
+ * following the `UPDATE_PDF_BASELINES` review policy. With `update` (or the env
+ * flag) set, it (re)writes the baselines and returns; otherwise it rasterizes the
+ * document, checks every page against `baselineDir/page-N.png`, and throws a
+ * `PdfAssertionError` on any mismatch.
+ */
+declare function comparePdfSnapshot(input: PdfInput, baselineDir: string, options?: ComparePdfSnapshotOptions): Promise<PdfSnapshotResult>;
+
+export { PdfAssertionError, comparePdfSnapshot, expectPdf, loadPdfSfc, parsePdf, rasterizePdf, renderPdfSfc, renderPdfTemplate, toPdfBytes };
+export type { ComparePdfSnapshotOptions, LinkQuery, OutlineShape, ParsedPdf, ParsedPdfLink, ParsedPdfPage, ParsedPdfTextRun, PdfExpectation, PdfInput, PdfOutlineItem, PdfPageImage, PdfSnapshotResult, RasterizePdfOptions, RenderPdfSfcOptions, RenderPdfTemplateOptions, RenderedPdfTemplate, ToContainTextOptions };
+```

package/CHANGELOG.md

@@ -0,0 +1,168 @@
+# Changelog
+
+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).
+
+## Unreleased
+
+## 0.3.0 - 2026-08-11
+
+### Added
+
+- Public font configuration types (`PdfFontDeclaration`, `PdfFontStyle`,
+  `PdfFontWeight`, and `PdfFontWeightName`) are now exported from the package
+  root instead of leaking through a private server implementation path.
+- `PdfLimitsOptions` is now a named package-root export backed by the same
+  canonical option shape used by the Nuxt module.
+- `RemoteAssetOptions` is now a named package-root export for callers that
+  share remote-image policy between Nuxt configuration and test helpers.
+- One canonical `pdf.limits` budget covering tree nodes/depth/text, pages,
+  image count/source bytes/decoded pixels, remote request count/concurrency,
+  the whole-render deadline, and completed output bytes.
+- Structural PNG/JPEG dimension validation before engine admission, aggregate
+  per-render image accounting, atomic output-cap failure, and fatal sibling
+  request cancellation.
+- Structural SFNT table-directory validation for local TTF/OTF files plus mixed
+  20-render concurrency, 100 sequential-render, and 100-page isolation suites.
+- Immutable resolved render metadata, development-only preview sidecars, stale
+  preview state after render failures, and automatic SFC preview refresh.
+- Normalized PDF text-run geometry and complete raster failure artifacts with
+  expected, actual, diff, and JSON metrics for every changed page.
+- One-tarball npm/pnpm consumer verification, pinned CI/release workflows,
+  CycloneDX SBOM and checksum generation, and registry post-publish smoke tests.
+- Safe registered-font-face diagnostics and an international typography
+  calibration fixture that classifies CJK, bidi text, combining marks, variable
+  fonts, emoji, fallback, and hyphenation from semantic and raster evidence.
+- Scope-aware Vue Composition API and `usePdfPageNumbers` auto-imports inside
+  PDF SFCs, without pretending that the isolated renderer has Nuxt app context.
+
+### Changed
+
+- Failed Vue mounts are transactional, component effects are always disposed,
+  and unhandled production errors fail the render instead of returning an
+  incomplete PDF.
+- PDF SFC compilation rejects async setup, top-level `await`, `Teleport`, and
+  `v-show` with targeted diagnostics; unsupported PDF styles fail closed.
+- Generated registry and test-helper types expose authored component props
+  instead of Vue framework props, and misplaced `definePdf()` calls fail with a
+  focused runtime explanation.
+- Script-setup source maps now compose the Vue compiler, auto-import, and
+  TypeScript transforms back to the original `.vue` source.
+- Nuxt discovery honors `.nuxtignore` and configured ignore rules. Structural
+  PDF/component changes and embedded image/font changes restart Nuxt so the
+  registry, declarations, and bundled resources cannot become stale.
+- Preview HMR derives its Vite client path from `app.baseURL` and
+  `app.buildAssetsDir`; project and layer resource precedence is covered by
+  integration tests.
+- Documentation now states the Node runtime-core lifecycle, synchronous
+  authoring contract, isolated Vue app boundary, and PDF-specific styling model.
+
+### Breaking changes
+
+- `renderPdfTemplate` options now mirror user-facing `pdf.remote` and
+  `pdf.limits` configuration. Generated asset maps, embedded font descriptors,
+  and template attribution fields are internal. `renderPdfSfc` additionally
+  accepts `pdf.fonts` declarations and always infers the application root from
+  the `pdfs/*.vue` path; its `rootDir` override is removed.
+- Root render props are now limited to props authored by the Vue component;
+  renderer-owned `class`, `style`, VNode, and reserved props are no longer
+  accepted by the generated registry or `renderPdfTemplate`.
+- Previously unsupported async components, top-level `await`, `Teleport`,
+  `v-show`, and unrecognized style properties now fail explicitly instead of
+  being silently omitted or admitted as no-ops.
+- Template keys now use one slash-separated vocabulary everywhere. A nested
+  template such as `pdfs/reports/monthly.vue` is registered as
+  `pdf['reports/monthly']`; camel-cased aliases such as `pdf.reportsMonthly`
+  are removed.
+- The inert `diagnostics.warnings` field and preview warning plumbing are
+  removed. Render failures remain typed errors; diagnostics report only
+  measured facts about a completed render.
+- `pdf.remote` now permits images only and contains only `allow` plus
+  `timeoutMs`. Move former `maxImageBytes` configuration to
+  `pdf.limits.maxImageBytes`; remote fonts must become local `pdfs/fonts`
+  inputs.
+- Allowlist entries must be exact `https://host/path/` prefixes. Wildcard hosts
+  and prefixes without a trailing slash are rejected. Redirects are capped at
+  three hops.
+
+## 0.2.0
+
+The contract widens from 0.1.0's core layout primitives to vector graphics, a
+table of contents, internal links, bookmarks, opt-in remote resources, shipped
+testing utilities, and enforced render limits — each backed by an executable
+conformance fixture. Everything is additive: no 0.1.0 public API changed.
+
+### Added
+
+- **SVG drawing primitives.** `PdfSvg`, `PdfG`, `PdfPath`, `PdfRect`,
+  `PdfCircle`, `PdfEllipse`, `PdfLine`, `PdfPolyline`, `PdfPolygon`, `PdfDefs`,
+  `PdfClipPath`, `PdfLinearGradient`, `PdfRadialGradient`, `PdfStop`, and
+  `PdfTspan`, with enforced nesting rules and `url(#id)` def references. Verified
+  by a paired React/Vue raster fixture.
+- **Table of contents via `usePdfPageNumbers()`.** An auto-imported composable
+  returning a readonly, reactive `id → 1-based page` map. Reading it activates a
+  fixed-point multi-pass layout that converges (an ordinary TOC settles in two
+  passes); a document whose geometry depends on the numbers it prints fails
+  closed with `PDF_LIMIT_EXCEEDED`.
+- **Internal `#id` links and bookmarks.** Any primitive `id` becomes a named
+  destination reachable with `<PdfLink src="#id">`; a `bookmark` prop builds a
+  nested PDF outline following the component tree. Internal links stay
+  single-pass (they resolve by name).
+- **Opt-in remote images and fonts.** Off by default. `pdf.remote.allow`
+  configures an explicit `https`-only host + path-prefix allowlist enforced by
+  the module (never the engine) with per-hop redirect re-checks, byte caps,
+  signature validation, and timeouts; admitted bytes take the same embedded path
+  as local assets.
+- **`@lupinum/nuxt-pdf/test` utilities.** The helpers this package is tested with
+  now ship: `renderPdfTemplate`, `parsePdf`, `expectPdf`, `rasterizePdf`, and
+  `comparePdfSnapshot` (reviewed-baseline policy). `pdfjs-dist` and
+  `@napi-rs/canvas` are new **optional** peer dependencies, loaded lazily only by
+  this entry.
+- **Render limits.** Every render is bounded by `pdf.limits.maxPages` (default
+  2000) and `pdf.limits.timeoutMs` (default 30000), validated at setup and
+  enforced on both the single- and multi-pass paths; breaches fail with
+  `PDF_LIMIT_EXCEEDED`. Defaults apply even with no `pdf.limits` configured.
+- **`NuxtPdfError` and `PDF_ERROR_CODES`** exported from `#pdf`, and
+  template-attributed errors: every failure from a template's `render()` carries
+  `templateKey`/`templateFile` and a message prefixed with the source file.
+- **Development preview workbench** at `/_pdf`: scenario tabs, a per-render
+  diagnostics strip (duration, size, page count, and layout passes), and a
+  readable error panel. Server-rendered, absent from production builds.
+- **Documentation site** under `docs/` and a `playground/pdfs/report.vue`
+  demonstrating the TOC, bookmarks, and page numbers end to end.
+- **Serverless build proof.** The module is verified to build under the Vercel
+  Nitro preset (execution remains verified on node-server).
+
+### Improvements (deliberate divergences from React PDF)
+
+- **Dynamic-text line spacing.** Page-number footers now render at correct
+  page-bottom geometry even when a `lineHeight` reaches the dynamic node
+  (inherited, percentage, or its own). Upstream React PDF produces invalid
+  geometry for that combination and silently drops such footers; Nuxt PDF
+  neutralizes the un-carryable `lineHeight` and renders them.
+- **Named-destination anchoring.** Internal links and TOC page numbers resolve to
+  the **first** page a section starts on, even when the section spans pages.
+  React PDF's last-writer-wins destination table points at the last page; Nuxt
+  PDF anchors at the first, copy-on-write so a `fixed` node repeated across pages
+  keeps its first-page destination.
+
+### Breaking changes
+
+One type-level narrowing: the `bookmark` prop is no longer **typed** on
+`PdfLink` and `PdfNote`. It was never tested or claimed there, and outline
+entries are verified only on `PdfPage`/`PdfView`/`PdfText`/`PdfImage`, so the
+types now match the tested contract. Runtime behavior is unchanged.
+
+Everything else in the 0.1.0 public surface — module options, `#pdf` registry,
+components, and `definePdf` — is unchanged; every 0.2.0 addition is opt-in.
+`pdfjs-dist` and `@napi-rs/canvas` are added only as **optional** peer
+dependencies for the new `/test` entry.
+
+## 0.1.0
+
+Initial external alpha: one Nuxt module, one Vue document tree, one Node server
+renderer over exact-pinned React PDF engine packages, and a small set of tested
+layout primitives (`PdfDocument`, `PdfPage`, `PdfView`, `PdfText`, `PdfImage`,
+`PdfLink`, `PdfNote`) with local image and font embedding and a typed `#pdf`
+server registry.