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

package/dist/agent/pages/docs/guides/recipes.md

@@ -0,0 +1,258 @@
+---
+title: "Production recipes"
+description: "Copyable Vue patterns for invoices, statements, reports, repeating matter, and payment QR codes."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/recipes"
+route: "/docs/guides/recipes"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Production recipes
+
+> Copyable Vue patterns for invoices, statements, reports, repeating matter, and payment QR codes.
+
+These are application recipes, not extra framework primitives. They compose the
+same small `PdfView`/`PdfText` surface used by the tested playground documents.
+
+Use this page as a pattern index:
+
+- [Repeating header, footer, and page numbers](#repeating-header-footer-and-page-numbers)
+- [Address and key/value blocks](#address-or-party-block)
+- [Invoice lines, totals, and shared table columns](#invoice-lines-and-totals)
+- [Dot leaders](#dot-leaders-for-contents-and-price-lists)
+- [Payment details and QR graphics](#payment-details-and-qr)
+- [Headings and continuation headers](#keep-a-heading-with-what-follows)
+- [Reports with a table of contents](#report-sections-and-a-table-of-contents)
+
+Read [Build reusable document components](/raw/docs/guides/reusable-components.md)
+before turning a recipe into a shared component. Exact style values remain in
+the [style reference](/raw/docs/reference/styles.md).
+
+## Repeating header, footer, and page numbers
+
+A `fixed` node repeats when one authored page wraps into multiple output pages.
+Keep the page padding large enough that flowing content never overlaps it.
+
+```vue
+<PdfPage :style="{ paddingBottom: 52, paddingHorizontal: 40, paddingTop: 64 }">
+  <PdfView fixed :style="{ left: 40, position: 'absolute', right: 40, top: 24 }">
+    <PdfText>Quarterly statement</PdfText>
+  </PdfView>
+  <PdfText
+    fixed
+    :render="({ pageNumber, totalPages }) => `Page ${pageNumber} / ${totalPages}`"
+    :style="{ bottom: 24, position: 'absolute', right: 40 }"
+  />
+  <slot />
+</PdfPage>
+```
+
+## Address or party block
+
+Use a typed child component so the invoice template remains readable.
+
+```vue [pdfs/components/PartyBlock.vue]
+<script setup lang="ts">
+defineProps<{ label: string, lines: string[] }>()
+</script>
+
+<template>
+  <PdfView :style="{ width: 220 }">
+    <PdfText :style="{ color: '#68736B', fontSize: 8, marginBottom: 6 }">
+      {{ label }}
+    </PdfText>
+    <PdfText v-for="line in lines" :key="line" :style="{ fontSize: 10 }">
+      {{ line }}
+    </PdfText>
+  </PdfView>
+</template>
+```
+
+## Key/value details
+
+Keep widths explicit; PDF rows should not depend on browser table layout.
+
+```vue
+<PdfView
+  v-for="entry in details"
+  :key="entry.label"
+  :style="{ flexDirection: 'row', marginBottom: 6 }"
+>
+  <PdfText :style="{ color: '#68736B', width: 110 }">{{ entry.label }}</PdfText>
+  <PdfText :style="{ flex: 1 }">{{ entry.value }}</PdfText>
+</PdfView>
+```
+
+## Invoice lines and totals
+
+Make each line indivisible with `wrap="false"`; keyed rows then move as a unit
+instead of losing a description or amount at a page break.
+
+```vue
+<PdfView
+  v-for="line in invoice.lines"
+  :key="line.id"
+  :wrap="false"
+  :style="{ borderBottomColor: '#DDE3DE', borderBottomWidth: 1, flexDirection: 'row', paddingVertical: 10 }"
+>
+  <PdfText :style="{ flex: 1 }">{{ line.description }}</PdfText>
+  <PdfText :style="{ textAlign: 'right', width: 90 }">{{ money(line.total) }}</PdfText>
+</PdfView>
+<PdfView :wrap="false" :style="{ marginLeft: 'auto', marginTop: 16, width: 220 }">
+  <PdfText :style="{ fontWeight: 700, textAlign: 'right' }">Total {{ money(total) }}</PdfText>
+</PdfView>
+```
+
+## Tables with a shared column spec
+
+A table is a column of rows. Give every row the same `flexDirection: 'row'`
+and fixed cell widths, and put those widths in one module. The header and the
+body then cannot drift apart when a column changes.
+
+```ts [pdfs/components/columns.ts]
+export const columns = {
+  amount: { align: 'right', width: 86 },
+  description: { width: 246 },
+  quantity: { align: 'right', width: 52 },
+} as const
+```
+
+```vue
+<PdfView :style="{ flexDirection: 'row', paddingBottom: 8 }" :wrap="false">
+  <PdfText :style="{ fontSize: 7, width: columns.description.width }">Description</PdfText>
+  <PdfText :style="{ fontSize: 7, textAlign: 'right', width: columns.quantity.width }">Qty</PdfText>
+  <PdfText :style="{ fontSize: 7, textAlign: 'right', width: columns.amount.width }">Amount</PdfText>
+</PdfView>
+<PdfView
+  v-for="line in invoice.lines"
+  :key="line.id"
+  :wrap="false"
+  :style="{ borderBottomColor: '#DDE3DE', borderBottomWidth: 1, flexDirection: 'row', paddingVertical: 10 }"
+>
+  <PdfText :style="{ flex: 1 }">{{ line.description }}</PdfText>
+  <PdfText :style="{ textAlign: 'right', width: columns.amount.width }">{{ money(line.total) }}</PdfText>
+</PdfView>
+```
+
+Keep body cells inside a `wrap="false"` row so a long line moves as a unit.
+
+## Dot leaders for contents and price lists
+
+A dotted rule that stretches between a label and a number is one view with a
+dotted bottom border. Wrap each entry in a row with `alignItems: 'flex-end'`
+and let the leader take the remaining space:
+
+```vue [pdfs/components/common/DotLeader.vue]
+<script setup lang="ts">
+defineProps<{
+  baseline?: number
+  color: string
+  gap?: number
+  width?: number
+}>()
+</script>
+
+<template>
+  <PdfView
+    :style="{
+      borderBottomColor: color,
+      borderBottomStyle: 'dotted',
+      borderBottomWidth: width ?? 1,
+      flex: 1,
+      marginBottom: baseline ?? 3,
+      marginHorizontal: gap ?? 7,
+    }"
+  />
+</template>
+```
+
+```vue
+<PdfView :style="{ alignItems: 'flex-end', flexDirection: 'row' }">
+  <PdfText>{{ section.title }}</PdfText>
+  <DotLeader color="#CDD5CF" />
+  <PdfText>{{ pageNumbers[section.id] ?? '' }}</PdfText>
+</PdfView>
+```
+
+The `baseline` offset sits the dots on the text baseline; start at `2` to `4`
+and adjust against your font size.
+
+## Payment details and QR
+
+Generate the payment payload in setup code, turn consecutive dark QR modules
+into one SVG path, and keep the payment panel together with `wrap="false"`.
+
+```vue
+<PdfView :wrap="false" :style="{ flexDirection: 'row', marginTop: 20 }">
+  <PdfView :style="{ flex: 1 }">
+    <PdfText>IBAN {{ payment.iban }}</PdfText>
+    <PdfText>BIC {{ payment.bic }}</PdfText>
+    <PdfText>Reference {{ invoice.number }}</PdfText>
+  </PdfView>
+  <PdfSvg :viewBox="`0 0 ${qrSize} ${qrSize}`" :style="{ height: 72, width: 72 }">
+    <PdfPath :d="qrPath" fill="#000000" />
+  </PdfSvg>
+</PdfView>
+```
+
+## Keep a heading with what follows
+
+`minPresenceAhead` asks pagination to move the heading when too little usable
+space remains. Use `wrap="false"` only when the whole section is genuinely
+small enough to fit on a page.
+
+```vue
+<PdfView :style="{ marginTop: 24 }">
+  <PdfText :min-presence-ahead="54" :style="{ fontSize: 15, marginBottom: 10 }">
+    Payment terms
+  </PdfText>
+  <PdfText>{{ terms }}</PdfText>
+</PdfView>
+```
+
+## Long rows with continuation headers
+
+Put the header and rows in one wrapping page. The fixed header repeats on every
+continuation page; page padding reserves its space.
+
+```vue
+<PdfPage :style="{ paddingHorizontal: 40, paddingTop: 72 }">
+  <PdfView fixed :style="{ flexDirection: 'row', left: 40, position: 'absolute', right: 40, top: 36 }">
+    <PdfText :style="{ flex: 1 }">Description</PdfText>
+    <PdfText :style="{ textAlign: 'right', width: 90 }">Amount</PdfText>
+  </PdfView>
+  <InvoiceLine v-for="line in lines" :key="line.id" :line="line" />
+</PdfPage>
+```
+
+## Report sections and a table of contents
+
+Read the page map only where the document needs it. The first pass returns no
+number, so keep an empty fallback; Nuxt PDF rerenders until the map stabilizes.
+
+```vue
+<script setup lang="ts">
+const pageNumbers = usePdfPageNumbers()
+</script>
+
+<template>
+  <PdfPage>
+    <PdfLink v-for="section in sections" :key="section.id" :href="`#${section.id}`">
+      {{ section.title }} ..... {{ pageNumbers[section.id] ?? '' }}
+    </PdfLink>
+  </PdfPage>
+  <PdfPage v-for="section in sections" :key="section.id">
+    <PdfView :id="section.id" :bookmark="section.title">
+      <PdfText :style="{ fontSize: 22 }">{{ section.title }}</PdfText>
+      <PdfText>{{ section.body }}</PdfText>
+    </PdfView>
+  </PdfPage>
+</template>
+```
+
+The [links and table-of-contents guide](/raw/docs/guides/contents-links-bookmarks.md)
+explains convergence and invalid destinations. Use the
+[testing guide](/raw/docs/guides/testing.md) to protect document text, links, page
+counts, and reviewed raster output.

package/dist/agent/pages/docs/guides/remote-images.md

@@ -0,0 +1,72 @@
+---
+title: "Configure remote images"
+description: "Admit specific HTTPS image paths and understand the request boundary."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/remote-images"
+route: "/docs/guides/remote-images"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Configure remote images
+
+> Admit specific HTTPS image paths and understand the request boundary.
+
+Remote image fetching is off by default. Enable it only for HTTPS locations
+that the application operator controls or trusts.
+
+## Add an allowlist
+
+Configure exact URL prefixes with a trailing slash:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-pdf'],
+  pdf: {
+    remote: {
+      allow: [
+        'https://cdn.example.com/brand/',
+        'https://images.example.com/logos/',
+      ],
+      timeoutMs: 10_000,
+    },
+  },
+})
+```
+
+Use an admitted URL in the template:
+
+```vue
+<PdfImage
+  src="https://cdn.example.com/brand/logo.png"
+  :style="{ height: 40, width: 120 }"
+/>
+```
+
+The module follows at most three redirects and checks the allowlist at each
+hop. An allowed host cannot redirect to a disallowed location.
+
+## Understand the boundary
+
+- Allowlist entries use `https://host/path/`. Wildcards, credentials, query
+  strings, fragments, and missing trailing slashes are rejected.
+- Requested image URLs can contain a query, but errors do not include it.
+- Requests use `GET` without application headers, cookies, or credentials.
+- PNG and JPEG signatures and dimensions are checked before layout. A response
+  `Content-Type` cannot admit other bytes.
+- Per-image bytes, total bytes, decoded pixels, request count, concurrency, and
+  the full render deadline use the shared `pdf.limits` budget.
+- Duplicate URLs are fetched once per render. No cross-render image cache is
+  promised.
+
+<warning icon="lucide:shield-alert">
+The allowlist controls hosts and paths. It does not provide private-IP or
+DNS-rebinding protection. Do not allow user-controlled hosts. Authenticated
+requests, custom headers, proxies, and remote fonts are not supported.
+</warning>
+
+`PDF_ASSET_BLOCKED` means the source form, allowlist, redirect, or timeout
+policy rejected the request. `PDF_ASSET_INVALID` means admitted bytes were not a
+valid PNG or JPEG. Size and request-budget failures use `PDF_LIMIT_EXCEEDED`.
+See [Errors and limits](/raw/docs/reference/errors-and-limits.md) for the exact codes.

package/dist/agent/pages/docs/guides/reusable-components.md

@@ -0,0 +1,81 @@
+---
+title: "Build reusable document components"
+description: "Organize repeated PDF sections without creating a second component system."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/reusable-components"
+route: "/docs/guides/reusable-components"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Build reusable document components
+
+> Organize repeated PDF sections without creating a second component system.
+
+PDF components are ordinary local Vue components whose rendered roots are Nuxt
+PDF primitives. Extract a component when it owns a meaningful document section
+or repeats in more than one place.
+
+## Keep ownership visible
+
+Put document-specific components next to their document family:
+
+```bash [Application files]
+pdfs/
+├── invoice.vue
+└── components/
+    └── invoice/
+        ├── InvoiceAddress.vue
+        ├── InvoiceLine.vue
+        └── columns.ts
+```
+
+Move a component to `pdfs/components/` only when several templates use it. This
+keeps invoice-specific decisions out of a generic component API.
+
+## Pass typed document data
+
+```vue [pdfs/components/invoice/InvoiceAddress.vue]
+<script setup lang="ts">
+defineProps<{
+  label: string
+  lines: string[]
+}>()
+</script>
+
+<template>
+  <PdfView>
+    <PdfText :style="{ fontSize: 8, marginBottom: 4 }">
+      {{ label }}
+    </PdfText>
+    <PdfText v-for="line in lines" :key="line">
+      {{ line }}
+    </PdfText>
+  </PdfView>
+</template>
+```
+
+Import it directly in the template. Use keyed `v-for`, slots, and `v-if` as you
+would in another Vue component. Do not pass DOM attributes such as `class` or
+`aria-*`; the PDF tree has no DOM.
+
+## Share table geometry
+
+Put widths used by both a header and row in one TypeScript module:
+
+```ts [pdfs/components/invoice/columns.ts]
+export const invoiceColumns = {
+  description: '58%',
+  quantity: '14%',
+  price: '14%',
+  total: '14%',
+} as const
+```
+
+A table is a column of rows. Give the header and every row the same
+`flexDirection: 'row'` and column widths. The header and body then cannot drift
+apart.
+
+The [production recipes](/raw/docs/guides/recipes.md) show address blocks, shared
+columns, totals, continuation headers, and table-of-contents patterns.

package/dist/agent/pages/docs/guides/standalone-node.md

@@ -0,0 +1,107 @@
+---
+title: "Render outside Nitro"
+description: "Compile PDF templates once and render the generated registry in a Node worker."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/standalone-node"
+route: "/docs/guides/standalone-node"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Render outside Nitro
+
+> Compile PDF templates once and render the generated registry in a Node worker.
+
+Use the standalone build when a Node worker owns document rendering outside
+Nitro. Keep the Nuxt module for authoring and preview. Both paths use the same
+compiler, resource admission, registry, and PDF engine.
+
+## Build the registry
+
+Keep trusted templates in `pdfs/` at the application root. Import application
+helpers explicitly with relative paths. The standalone build does not read
+Nuxt configuration, aliases, auto-imports, or layer configuration. PDF primitives,
+`definePdf`, and `usePdfPageNumbers` remain available in templates.
+Package imports must provide compiled JavaScript. Do not import source-only
+packages or add runtime filesystem reads to templates or their helpers.
+
+```ts [scripts/build-pdfs.mjs]
+import { buildPdfRegistry } from '@lupinum/nuxt-pdf/build'
+
+await buildPdfRegistry({
+  rootDir: process.cwd(),
+  outDir: './generated/pdfs',
+  fonts: [{ family: 'Invoice Sans', src: 'Roboto-Regular.ttf' }],
+  limits: { maxPages: 100, maxOutputBytes: 8_000_000 },
+})
+```
+
+Put the configured font in `pdfs/fonts/`. Put local images in `pdfs/assets/`.
+Remove the `fonts` option if the templates use only built-in fonts.
+
+Run this script before the backend build:
+
+```bash
+node scripts/build-pdfs.mjs
+```
+
+The output directory contains `index.mjs`, `index.d.mts`, a `types/` declaration
+tree, and an ownership marker. Deploy the generated runtime and its package
+dependencies. Keep the declarations for backend type checking. No Vue source,
+test loader, or build compiler is needed to execute this generated registry.
+The build tools remain package dependencies but are not imported by the runtime.
+
+Use a dedicated output directory inside the application. Never put hand-written
+files in it. Successful rebuilds replace its generated contents. Compilation
+failures preserve the previous output. An existing nonempty directory without
+the ownership marker is rejected. Choose another directory after this error.
+Do not run concurrent builds into one output directory.
+
+## Render validated data
+
+The generated `pdf`, `renderPdf`, `getPdfTemplate`, and `pdfTemplateKeys` exports
+have the same behavior as the [Nitro registry](/raw/docs/reference/registry.md).
+Import the `.mjs` path. Ordinary TypeScript resolves its adjacent declarations.
+
+```ts [workers/render-invoice.ts]
+import { pdf } from '../generated/pdfs/index.mjs'
+
+export async function renderInvoice() {
+  const result = await pdf.invoice.render({
+    customer: 'Example customer',
+    number: '2026-001',
+    lines: [],
+  })
+  return result.toUint8Array()
+}
+```
+
+Match the props to your own invoice template. Validate request data and check
+authorization before rendering. Props are statically typed, not a runtime
+validation schema. Never accept template source, filesystem paths, build
+options, or unrestricted image URLs from a caller.
+
+Local assets and configured fonts are validated and embedded during the build.
+Remote images remain denied unless the build supplies an explicit `remote`
+policy. Existing resource limits and error codes apply to each render. Fix the
+named resource or lower input size after an admission or limit error.
+
+The application owns jobs, snapshots, storage, document issuance, and delivery.
+For an issued document, store and reuse completed bytes. Two fresh renders are
+not promised to be byte-identical.
+
+## Verify the deployment
+
+Standalone Node rendering is tested locally with embedded fonts and images,
+Unicode text, pagination, and concurrent requests. That is not a deployed
+Convex or other serverless-runtime certification. Edge workers remain unsupported.
+
+Before adoption, measure your largest expected document on the target runtime.
+Check cold and warm duration, memory use, output limits, failed asset requests,
+and concurrent isolation. Keep the previously tested Node route available for
+new renders until this proof passes. Do not regenerate issued PDFs during a
+runtime migration.
+
+See [deployment guidance](/raw/docs/guides/deployment.md) for the runtime matrix and
+operational limits.

package/dist/agent/pages/docs/guides/svg-graphics.md

@@ -0,0 +1,165 @@
+---
+title: "Draw SVG graphics"
+description: "The SVG primitive set, direct presentation props, scoped definitions, SVG text, and the supported numeric boundary."
+url: "https://nuxt-pdf.lupinum.com/docs/guides/svg-graphics"
+route: "/docs/guides/svg-graphics"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Draw SVG graphics
+
+> The SVG primitive set, direct presentation props, scoped definitions, SVG text, and the supported numeric boundary.
+
+Nuxt PDF ships a set of SVG drawing primitives that render through the same
+layout and render engine as the document primitives. A `PdfSvg` participates in
+normal page flow as a flex leaf, measured from its `viewBox` aspect ratio.
+
+## The primitive set
+
+| Component | Role |
+| --- | --- |
+| `PdfSvg` | SVG root; a flex leaf in page flow |
+| `PdfG` | A group; presentation attributes cascade to children |
+| `PdfPath` | A path from a `d` string |
+| `PdfRect` | A rectangle (`x`, `y`, `width`, `height`, `rx`, `ry`) |
+| `PdfCircle` | A circle (`cx`, `cy`, `r`) |
+| `PdfEllipse` | An ellipse (`cx`, `cy`, `rx`, `ry`) |
+| `PdfLine` | A line (`x1`, `y1`, `x2`, `y2`) |
+| `PdfPolyline` | An open polyline from a `points` string |
+| `PdfPolygon` | A closed polygon from a `points` string |
+| `PdfDefs` | Holds referenceable defs (gradients, clip paths) |
+| `PdfClipPath` | A clip path referenced by `clipPath="url(#id)"` |
+| `PdfLinearGradient` / `PdfRadialGradient` | Gradients referenced by `fill="url(#id)"` |
+| `PdfStop` | A gradient color stop |
+| `PdfTspan` | A text span inside an SVG `PdfText` |
+
+Full prop tables are in the [primitive reference](/raw/docs/reference/primitives.md).
+
+## A basic drawing
+
+```vue
+<PdfSvg viewBox="0 0 120 120" :style="{ width: 120, height: 120 }">
+  <PdfRect x="8" y="8" width="104" height="104" rx="12" fill="#eef2ee" />
+  <PdfCircle cx="60" cy="60" r="34" fill="#315d3b" />
+  <PdfPath d="M44 62 l12 12 l22 -26" stroke="#ffffff" stroke-width="6" fill="none" />
+</PdfSvg>
+```
+
+## Presentation is direct, not a style cascade
+
+Set SVG paint and geometry with direct props. `PdfG` and the shape primitives
+do not accept a generic `style` prop, so there is no prop-versus-style
+precedence to remember. `transform` is also a direct SVG prop; page-flow
+primitives such as `PdfView` put transforms in `PdfStyle` instead.
+
+`PdfSvg` is the exception only at the page-flow boundary: its `style` sizes and
+positions the SVG root in the surrounding PDF layout. It does not become a bag
+of SVG presentation attributes. SVG `PdfText` may use `style` for text metrics
+such as `fontFamily` and `fontSize`, but its paint color is the direct `fill`
+prop.
+
+Kebab-case attributes written in Vue templates (`stroke-width`, `stop-color`)
+are coerced to the camelCase keys the renderer reads, so both forms work:
+
+```vue
+<!-- stroke-width and strokeWidth are equivalent on SVG nodes -->
+<PdfLine x1="0" y1="0" x2="100" y2="0" stroke="#333" stroke-width="2" />
+```
+
+Presentation attributes set on a `PdfG` cascade to its children:
+
+```vue
+<PdfG fill="#315d3b" transform="translate(10 10) rotate(15)">
+  <PdfRect x="0" y="0" width="20" height="20" />
+  <PdfRect x="30" y="0" width="20" height="20" />
+</PdfG>
+```
+
+## Numbers and transforms
+
+Geometry accepts finite numbers or numeric strings; percentage strings are
+accepted only by props typed as `PdfSvgLength`. `strokeWidth` does not accept a
+percentage. Widths and radii must be non-negative, opacity and gradient-stop
+values must be between `0` and `1` (or `0%` and `100%`), and a `viewBox` must
+contain four finite numbers with positive width and height.
+
+The transform surface accepts one to three space-separated
+`translate(...)` or `rotate(...)` operations with unitless numeric arguments.
+Scale, matrix, skew, angle units, and arbitrary transform strings are rejected.
+
+Explicit zeroes keep SVG meaning despite truthiness fallbacks in the pinned
+serializer:
+
+- `fillOpacity="0"` paints fully transparent;
+- `strokeWidth="0"` paints no stroke (not a PDF hairline); and
+- a zero linear-gradient `x2`, or zero radial-gradient `cx`, `cy`, `fx`, `fy`,
+  or `r`, remains zero.
+
+Nuxt PDF repairs those values after layout on the disposable resolved tree,
+immediately before serialization. This is an engine-boundary correction, not a
+second authoring format.
+
+## Gradients and clip paths
+
+Define a gradient or clip path inside a `PdfDefs` and reference it by `url(#id)`:
+
+```vue
+<PdfSvg viewBox="0 0 200 100" :style="{ width: 200, height: 100 }">
+  <PdfDefs>
+    <PdfLinearGradient id="brand" x1="0" y1="0" x2="1" y2="0">
+      <PdfStop offset="0" stop-color="#315d3b" />
+      <PdfStop offset="1" stop-color="#7bbf88" />
+    </PdfLinearGradient>
+  </PdfDefs>
+  <PdfRect x="0" y="0" width="200" height="100" fill="url(#brand)" />
+</PdfSvg>
+```
+
+<info icon="lucide:info">
+A `url(#id)` reference resolves only against a `PdfDefs` in the same `PdfSvg`
+subtree. Definition ids must be safe and unique within that SVG, and each SVG
+accepts at most one `PdfDefs`. A missing, malformed, or incompatible reference
+(for example a clip path used as a fill) fails with `PDF_TREE_INVALID`; it is
+never rendered as an accidental fallback. The same definition id may be reused
+in another `PdfSvg` because scopes are independent.
+</info>
+
+## SVG text
+
+`PdfText` has two context-specific contracts. In page flow it accepts wrapping,
+pagination, bookmark, destination, and dynamic-text props. Inside `PdfSvg`, both
+`x` and `y` are required, `fill` is the direct paint prop, and page-flow-only
+props are rejected. SVG text may hold `PdfTspan` children, which join and chain
+along the x-axis:
+
+```vue
+<PdfSvg viewBox="0 0 200 40" :style="{ width: 200, height: 40 }">
+  <PdfText :x="0" :y="24" fill="#18251d">
+    <PdfTspan>Total </PdfTspan>
+    <PdfTspan fill="#315d3b">EUR 1,250.00</PdfTspan>
+  </PdfText>
+</PdfSvg>
+```
+
+The text content is preserved in the extracted page text, so it remains
+selectable and testable. `PdfTspan` accepts only
+`x`, `y`, and `fill`; it has no generic `style`, stroke, transform, or other
+shape presentation props.
+
+## Nesting rules and what is not claimed
+
+`PdfSvg` is a valid child of `PdfPage` and `PdfView` but is rejected directly
+inside `PdfText`. Leaf shapes stay childless. Each container accepts only its
+valid children; invalid nesting fails with a targeted diagnostic.
+
+Within SVG, the following are **not** claimed in the current alpha:
+
+- `Marker` (`markerStart` / `markerMid` / `markerEnd`);
+- alternate `gradientUnits`, `gradientTransform`, gradient inheritance, and
+  `preserveAspectRatio` modes;
+- radial-gradient inner radius (`fr`), which the pinned renderer hardcodes to
+  zero; and
+- SVG image _files_ as an image source.