av6-pdf-engine 2.0.0 → 3.0.0

package/README.md

@@ -1,16 +1,38 @@
 # av6-pdf-engine
 
 `av6-pdf-engine` is a JSON-driven PDF layout engine built on top of [PDFKit](https://github.com/foliojs/pdfkit).  
-Describe your document once (page setup, styles, headers, blocks, tables, QR/barcodes, signatures, etc.) and render it to a file or in-memory buffer from any Node.js service.
+Describe your document once and render it to a file or in-memory Buffer from any Node.js service.
 
-## Highlights
+---
 
-- JSON definition that mirrors pdfmake-style blocks while staying close to raw PDFKit features.
-- Built-in layout helpers for headers, footers, watermarks, page backgrounds, and signature flows.
-- Rich block catalog: text, columns, tables, key/value grids, images, QR codes, 1D barcodes, lines, and explicit page breaks.
-- Automatic asset normalization for remote URLs, Buffers, or local paths (images, QR, barcode payloads).
-- Custom font registration plus reusable style definitions with full TypeScript types.
-- Two rendering targets: `renderCustomPdf(def, "/tmp/doc.pdf")` or `renderCustomPdfToBuffer(def)` for HTTP responses/storage.
+## Table of contents
+
+1. [Installation](#installation)
+2. [Quick start](#quick-start)
+3. [Document definition](#document-definition)
+4. [Styles](#styles)
+5. [Header & footer](#header--footer)
+6. [Page background & watermark](#page-background--watermark)
+7. [Box model](#box-model)
+8. [Block catalog](#block-catalog)
+   - [text](#text)
+   - [image](#image)
+   - [qr](#qr)
+   - [barcode](#barcode)
+   - [line](#line)
+   - [shape](#shape)
+   - [columns](#columns)
+   - [table](#table)
+   - [keyValueGrid](#keyvaluegrid)
+   - [list](#list)
+   - [pageBreak](#pagebreak)
+   - [signature](#signature)
+9. [Asset handling](#asset-handling)
+10. [Rendering targets](#rendering-targets)
+11. [Built-in fonts](#built-in-fonts)
+12. [Engine behaviour notes](#engine-behaviour-notes)
+
+---
 
 ## Installation
 
@@ -22,6 +44,8 @@ pnpm add av6-pdf-engine
 yarn add av6-pdf-engine
 ```
 
+---
+
 ## Quick start
 
 ```ts
@@ -29,112 +53,686 @@ import { renderCustomPdfToBuffer, renderCustomPdf, CustomDocDefinition } from "a
 
 const doc: CustomDocDefinition = {
   pageSize: "A4",
-  margins: { top: 80, right: 40, bottom: 80, left: 40 },
-  fonts: [{ name: "Inter", src: "./assets/Inter-Regular.ttf" }],
+  margins: { top: 70, right: 40, bottom: 60, left: 40 },
   styles: {
-    heading: { font: "Helvetica-Bold", fontSize: 16 },
-    label: { color: "#999", fontSize: 9, bold: true },
+    heading: { fontSize: 16, bold: true, color: "#0B4A6F" },
+    label:   { fontSize: 8, bold: true, color: "#6B7280" },
   },
   header: {
-    blocks: [{ type: "text", text: "ACME Corp — Invoice", style: "heading" }],
-    backgroundColor: "#f7f7f7",
-  },
-  footer: (page, size) => ({
+    paddingLeft: 40,
+    paddingTop: 16,
+    backgroundBlocks: [
+      { type: "shape", shape: "rect", fillColor: "#0B4A6F", height: 70 },
+    ],
     blocks: [
-      {
-        type: "text",
-        text: `Page ${page} / ${Math.round(size.height)}`,
-        align: "center",
-      },
+      { type: "text", text: "ACME Corp — Invoice #1234", fontSize: 13, bold: true, color: "#FFFFFF" },
     ],
+  },
+  footer: (page, size) => ({
+    blocks: [{ type: "text", text: `Page ${page}`, align: "center", fontSize: 8 }],
   }),
-  pageBackground: { src: "./assets/background.png", opacity: 0.05 },
-  watermark: { text: "ACME CONFIDENTIAL", mode: "exceptFirst", opacity: 0.1 },
+  watermark: { text: "DRAFT", mode: "all", opacity: 0.07 },
   content: [
+    { type: "text", text: "Hello, PDF!", style: "heading", marginTop: 16 },
+    { type: "line", lineWidth: 1, color: "#0B4A6F", marginBottom: 12 },
     {
-      type: "columns",
-      widths: [200, "*"],
-      columns: [
-        [
-          { type: "text", text: "Invoice #1234", style: "heading" },
-          {
-            type: "keyValueGrid",
-            columns: [
-              [
-                { key: "Issued", value: "2025-12-01" },
-                { key: "Due", value: "2025-12-15" },
-              ],
-            ],
-            keyStyle: "label",
-          },
-        ],
-        [
-          {
-            type: "table",
-            widths: ["*", 80, 80],
-            headerRows: 1,
-            body: [
-              [
-                { text: "Item", style: "label" },
-                { text: "Qty", style: "label", align: "right" },
-                { text: "Total", style: "label", align: "right" },
-              ],
-              [{ text: "Consulting" }, { text: "12", align: "right" }, { text: "$3,000", align: "right" }],
-            ],
-          },
-        ],
+      type: "table",
+      widths: ["*", 80, 80],
+      headerRows: 1,
+      body: [
+        [{ text: "Item", bold: true }, { text: "Qty", bold: true, align: "right" }, { text: "Total", bold: true, align: "right" }],
+        [{ text: "Consulting" }, { text: "12", align: "right" }, { text: "$3,000", align: "right" }],
       ],
     },
-    { type: "qr", value: "https://acme.example.com/pay/1234", size: 80 },
-    { type: "barcode", value: "123456789012", bcType: "EAN13", width: 200 },
-    { type: "signature", height: 100, label: "Authorized signature" },
+    { type: "signature", height: 80, label: "Authorized signature" },
   ],
 };
 
-// Write directly to disk
+// Write to disk
 await renderCustomPdf(doc, "./tmp/invoice.pdf");
 
-// Or capture an in-memory Buffer (perfect for HTTP responses / uploads)
-const pdfBuffer = await renderCustomPdfToBuffer(doc);
+// Or capture a Buffer (HTTP responses, cloud storage, etc.)
+const buf = await renderCustomPdfToBuffer(doc);
 ```
 
+---
+
 ## Document definition
 
-- `pageSize`: Any PDFKit-supported size (`"A4"`, `"LETTER"`, `[width, height]`, etc.). Defaults to A4.
-- `margins`: Required `{ top, right, bottom, left }`. `top`/`bottom` double as header/footer bands.
-- `fonts`: Optional array of `{ name, src }` for custom TTF/OTF registration before rendering.
-- `header` / `footer`: Structured block arrays. Footers can also be a single block, array, or a callback `(pageNumber, pageSize) => Block | FooterDef`.
-- `pageBackground`: Optional image (path, URL, or Buffer) painted before content each page.
-- `watermark`: Text watermark with opacity, angle, font size, color, and placement mode (`all`, `first`, `last`, `exceptFirst`, etc.).
-- `styles`: Named `StyleDef` map that can be referenced via `style` on text/table cells/key-value items.
-- `content`: Ordered array of `Block` objects (see below) rendered top to bottom with automatic pagination.
+`CustomDocDefinition` is the root object passed to both render functions.
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `pageSize` | `string \| [width, height]` | No | Any PDFKit page size (`"A4"`, `"LETTER"`, `"A5"`, etc.) or a `[w, h]` tuple in points. Defaults to `"A4"`. |
+| `pageOrientation` | `"portrait" \| "landscape"` | No | Defaults to portrait. |
+| `margins` | `{ top, right, bottom, left }` | **Yes** | All four margins in points. `top` doubles as the header band height; `bottom` doubles as the footer band height. |
+| `fonts` | `FontRegistration[]` | No | Custom TTF/OTF fonts to register before rendering. See [Custom fonts](#custom-fonts). |
+| `styles` | `Record<string, StyleDef>` | No | Named style map. Any block with a `style` property references an entry here. |
+| `header` | `HeaderDef` | No | Rendered inside the top margin band on every page. |
+| `footer` | `FooterInput` | No | Rendered inside the bottom margin band. Accepts a `FooterDef`, a `Block`, a `Block[]`, or a callback. |
+| `pageBackground` | `PageBackgroundDef` | No | Image painted behind all content on every page. |
+| `watermark` | `WatermarkDef` | No | Diagonal text overlay. |
+| `content` | `Block[]` | **Yes** | Ordered list of blocks rendered top-to-bottom with automatic pagination. |
+| `defaultImage` | `string \| Buffer` | No | Fallback image used whenever an `image`, `qr`, or `barcode` block fails to load its source. |
+
+### Custom fonts
+
+```ts
+fonts: [
+  { name: "Inter",      src: "./assets/Inter-Regular.ttf" },
+  { name: "Inter-Bold", src: "./assets/Inter-Bold.ttf" },
+],
+```
+
+Once registered, use the name in any `font` property: `{ type: "text", font: "Inter", text: "Hello" }`.
+
+---
+
+## Styles
+
+`StyleDef` is a reusable object referenced by name via the `style` property on any text-bearing block or table cell.
+
+```ts
+styles: {
+  h1:    { fontSize: 20, bold: true, color: "#0B4A6F" },
+  label: { fontSize: 8, bold: true, color: "#6B7280" },
+  mono:  { font: "Courier", fontSize: 9 },
+},
+```
+
+| Property | Type | Description |
+|---|---|---|
+| `fontSize` | `number` | Font size in points. |
+| `bold` | `boolean` | Bold weight. |
+| `italic` | `boolean` | Italic style. |
+| `underline` | `boolean` | Underline decoration. |
+| `strike` | `boolean` | Strikethrough decoration. |
+| `color` | `string` | Text fill color (hex, rgb, named). |
+| `align` | `"left" \| "center" \| "right" \| "justify"` | Horizontal alignment. |
+| `lineGap` | `number` | Extra spacing between lines in points. |
+| `font` | `FontName` | Built-in or registered font name. |
+| `link` | `string` | URL to attach to the text as a hyperlink. |
+
+A block can reference multiple styles as an array; properties are merged left-to-right, with the block's own properties taking precedence:
+
+```ts
+{ type: "text", text: "Warning!", style: ["label", "highlight"] }
+```
+
+---
+
+## Header & footer
+
+### Header (`HeaderDef`)
+
+The header is rendered inside the `top` margin band on **every** page (including pages added internally by PDFKit when long text overflows).
+
+| Property | Type | Description |
+|---|---|---|
+| `blocks` | `Block[]` | **Optional.** Foreground blocks rendered inside the band. Omit for a background-only header. |
+| `backgroundBlocks` | `Block[]` | Blocks rendered behind `blocks` — useful for shapes, waves, or filled rectangles. |
+| `backgroundColor` | `string` | Solid fill behind the entire band. |
+| `backgroundImage` | `string \| Buffer` | Image painted to cover the entire band. |
+| `backgroundOpacity` | `number` | Opacity for `backgroundColor` / `backgroundImage` (0–1). |
+| `visible` | `boolean` | Set `false` to suppress the header entirely. |
+| `marginTop/Bottom/Left/Right` | `number` | Outer spacing around the band content. |
+| `padding / paddingTop/Right/Bottom/Left` | `number \| BoxSpacing` | Inner spacing before the foreground blocks. |
+
+```ts
+header: {
+  paddingTop: 14,
+  paddingLeft: 40,
+  backgroundBlocks: [
+    { type: "shape", shape: "rect", fillColor: "#0B4A6F", height: 70 },
+  ],
+  blocks: [
+    { type: "text", text: "My Company", bold: true, color: "#FFFFFF" },
+  ],
+},
+```
+
+### Footer (`FooterInput`)
+
+The footer accepts four different shapes:
+
+**1. FooterDef** — same options as `HeaderDef`:
+```ts
+footer: {
+  blocks: [{ type: "text", text: "© 2025 Acme Corp", align: "center", fontSize: 8 }],
+}
+```
+
+**2. Single Block:**
+```ts
+footer: { type: "text", text: "Confidential", align: "right", fontSize: 8 }
+```
+
+**3. Block array:**
+```ts
+footer: [
+  { type: "line", lineWidth: 0.5, color: "#D1D5DB", marginBottom: 4 },
+  { type: "text", text: "Page footer text", fontSize: 8 },
+]
+```
+
+**4. Callback** — receives `(pageNumber, pageSize)`:
+```ts
+footer: (page, size) => ({
+  blocks: [
+    { type: "text", text: `Page ${page}`, align: "center", fontSize: 8 },
+  ],
+}),
+```
+
+The callback form is the only way to include dynamic per-page data like page numbers.
+
+---
+
+## Page background & watermark
+
+### Page background
+
+Painted before the header and content on every new page.
+
+```ts
+pageBackground: {
+  src: "./assets/letterhead.png", // path, Buffer, or HTTPS URL
+  opacity: 0.05,
+},
+```
+
+### Watermark
+
+Diagonal text overlay drawn on top of content.
+
+```ts
+watermark: {
+  text: "CONFIDENTIAL",
+  mode: "exceptFirst",  // see modes below
+  opacity: 0.07,
+  fontSize: 55,
+  color: "gray",
+  angle: 45,
+},
+```
+
+| `mode` | Pages that receive the watermark |
+|---|---|
+| `"all"` (default) | Every page |
+| `"first"` | First page only |
+| `"last"` | Last page only |
+| `"firstLast"` | First and last pages |
+| `"exceptFirst"` | All pages except the first |
+| `"exceptLast"` | All pages except the last |
+| `"exceptFirstLast"` | All pages except first and last |
+
+---
+
+## Box model
+
+Every block type inherits `BaseBlock`, which adds a box model layer on top of the block's own rendering. This lets you attach a background, an image, or child blocks behind any block, and control inner spacing with padding.
+
+| Property | Type | Description |
+|---|---|---|
+| `visible` | `boolean` | `false` skips rendering entirely (block is also excluded from height measurement). |
+| `backgroundColor` | `string` | Filled rectangle drawn behind the block's content area. |
+| `backgroundImage` | `string \| Buffer` | Image stretched to cover the content area. |
+| `backgroundOpacity` | `number` | Opacity applied to `backgroundColor` / `backgroundImage`. |
+| `backgroundBlocks` | `Block[]` | Arbitrary blocks rendered in a separate background layer before the main content. |
+| `padding` | `number \| { top, right, bottom, left }` | Uniform or per-side inner spacing. |
+| `paddingTop/Right/Bottom/Left` | `number` | Individual padding overrides. |
+
+```ts
+{
+  type: "text",
+  text: "Highlighted note",
+  fontSize: 9,
+  backgroundColor: "#EFF6FF",
+  padding: 10,
+  marginTop: 8,
+  marginBottom: 8,
+}
+```
+
+---
 
 ## Block catalog
 
-- `text`: Paragraph with typography controls (alignment, inline styles, links, margins).
-- `image`: Local path, Buffer, or remote URL (auto-downloaded) with sizing/alignment.
-- `qr`: QR codes via `qrcode` with size, version, and error correction level support.
-- `barcode`: CODE128, EAN13, CODE39, ITF, CODE93 via `bwip-js`, including rotation, scaling, and caption text.
-- `columns`: Multi-column layouts (`widths`, gaps, `keepTogether`) that can nest any other blocks.
-- `table`: Simple table primitive with header rows, cell styles, and optional border layout hints.
-- `keyValueGrid`: Responsive key/value pairs with shared or per-row styles, separators, and column widths.
-- `line`: Horizontal rule with configurable width, color, and surrounding margins.
-- `pageBreak`: Forces the renderer to finish the current page before continuing.
-- `signature`: Reserves space (height/width) and optionally renders nested blocks or an image to support wet/digital signatures.
+All blocks accept the `BaseBlock` properties listed in [Box model](#box-model) in addition to their own properties.
+
+---
+
+### text
+
+Renders a paragraph of text.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `text` | `string` | — | **Required.** Content to render. |
+| `fontSize` | `number` | `10` | Size in points. |
+| `lineGap` | `number` | `4` | Extra vertical space between lines and after the block. |
+| `align` | `Alignment` | `"left"` | `"left"`, `"center"`, `"right"`, `"justify"`. |
+| `bold` | `boolean` | `false` | |
+| `italic` | `boolean` | `false` | |
+| `underline` | `boolean` | `false` | |
+| `strike` | `boolean` | `false` | Strikethrough. |
+| `link` | `string` | — | URL hyperlink attached to the text. |
+| `color` | `string` | `"black"` | Fill color. |
+| `font` | `FontName` | auto | Built-in or registered font. Auto-selects bold/italic variant when those flags are set. |
+| `style` | `string \| string[]` | — | Named style reference(s) from the `styles` map. |
+| `marginTop` | `number` | `0` | Space above the block. |
+| `marginBottom` | `number` | `0` | Space below the block. |
+| `marginLeft` | `number` | `0` | Left indent (reduces available width). |
+| `marginRight` | `number` | `0` | Right indent (reduces available width). |
+
+```ts
+{ type: "text", text: "Hello world", bold: true, marginTop: 12, marginBottom: 8, align: "center" }
+```
+
+---
+
+### image
+
+Renders a raster image (PNG, JPEG).
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string \| Buffer` | — | File path, HTTPS URL, or Buffer. Falls back to `defaultImage` on error. |
+| `width` | `number` | `80` | Render width in points. |
+| `height` | `number` | `50` | Render height in points. |
+| `align` | `Alignment` | `"left"` | Horizontal alignment within the available width. |
+| `marginTop/Bottom/Left/Right` | `number` | `0` | |
+
+```ts
+{ type: "image", src: "https://example.com/logo.png", width: 120, height: 60, align: "right" }
+```
+
+---
+
+### qr
+
+Generates a QR code via `qrcode` and renders it as an image.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Data to encode. |
+| `size` | `number` | `80` | Width and height of the rendered square in points. |
+| `qrVersion` | `number` | auto | QR version (1–40). |
+| `errorCorrectionLevel` | `"L" \| "M" \| "Q" \| "H"` | `"M"` | Error correction level. |
+| `align` | `Alignment` | `"left"` | |
+| `marginTop/Bottom/Left/Right` | `number` | `0` | |
+
+```ts
+{ type: "qr", value: "https://acme.example.com/pay/1234", size: 80, errorCorrectionLevel: "H" }
+```
+
+---
+
+### barcode
 
-Each block supports a `visible` flag so you can skip rendering without mutating arrays.
+Generates a 1D barcode via `bwip-js`.
 
-## Asset handling & async preparation
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Data to encode. |
+| `bcType` | `BarcodeType` | `"CODE128"` | `"CODE128"`, `"EAN13"`, `"CODE39"`, `"ITF"`, `"CODE93"`. |
+| `width` | `number` | auto | Render width in points. |
+| `height` | `number` | `40` | Render height in points. |
+| `align` | `Alignment` | `"left"` | |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | |
+| `rotate` | `number` | `0` | Rotation in degrees. |
+| `scale` | `number` | — | bwip-js scale factor. |
+| `barHeight` | `number` | — | Bar height hint passed to bwip-js. |
+| `includetext` | `boolean` | `false` | Render the human-readable text below the bars. |
+| `textalign` | `"left" \| "center" \| "right"` | `"center"` | Alignment of the human-readable text. |
+| `marginTop/Bottom/Left/Right` | `number` | `0` | |
+
+```ts
+{ type: "barcode", value: "5901234123457", bcType: "EAN13", width: 160, height: 60, includetext: true }
+```
+
+---
+
+### line
+
+Draws a horizontal rule.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `lineWidth` | `number` | `1` | Stroke width in points. |
+| `color` | `string` | black | Stroke color. |
+| `marginTop/Bottom/Left/Right` | `number` | `0` | |
+
+```ts
+{ type: "line", lineWidth: 0.5, color: "#E5E7EB", marginTop: 8, marginBottom: 8 }
+```
+
+---
+
+### shape
+
+Draws a vector shape. All shapes share the same property set; only the `shape` type determines which properties are used.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `shape` | `ShapeType` | — | **Required.** One of `"rect"`, `"roundedRect"`, `"circle"`, `"ellipse"`, `"line"`, `"polygon"`, `"path"`. |
+| `width` | `number` | inner width | Shape width in points. |
+| `height` | `number` | `lineWidth` | Shape height in points. |
+| `radius` | `number` | `6` | Corner radius (`roundedRect`) or circle radius (`circle`). |
+| `points` | `{ x, y }[]` | — | Vertices for `"polygon"` (relative to the shape origin). |
+| `path` | `string` | — | SVG path data for `"path"`. Translated to the shape's `(x, y)` position. |
+| `fillColor` | `string` | — | Fill color. |
+| `strokeColor` | `string` | — | Stroke color. |
+| `lineWidth` | `number` | `1` | Stroke width. |
+| `opacity` | `number` | `1` | Opacity (0–1). |
+| `align` | `Alignment` | `"left"` | Horizontal alignment of the shape within the available width. |
+| `marginTop/Bottom/Left/Right` | `number` | `0` | |
+
+```ts
+// Filled navy rectangle
+{ type: "shape", shape: "rect", fillColor: "#0B4A6F", height: 4 }
+
+// Rounded badge
+{ type: "shape", shape: "roundedRect", width: 60, height: 24, radius: 12, fillColor: "#D1FAE5", strokeColor: "#047857" }
+
+// Triangle polygon
+{
+  type: "shape", shape: "polygon",
+  width: 50, height: 50,
+  strokeColor: "#0B4A6F", lineWidth: 1.5,
+  points: [{ x: 25, y: 0 }, { x: 50, y: 50 }, { x: 0, y: 50 }],
+}
+
+// Custom SVG path (e.g. a wave)
+{
+  type: "shape", shape: "path",
+  height: 40, fillColor: "#0B4A6F",
+  path: "M 0 0 L 200 0 L 200 20 C 150 40 50 10 0 30 Z",
+}
+```
+
+---
+
+### columns
+
+Lays out child block arrays side-by-side.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `columns` | `Block[][]` | — | **Required.** Each element is the block array for one column. |
+| `widths` | `(number \| "*")[]` | equal split | Per-column widths. `"*"` means "take remaining space". |
+| `gap` | `number` | `20` | Fixed gap between columns (used in `"fixedGap"` mode). |
+| `mode` | `"fixedGap" \| "spaceBetween"` | `"fixedGap"` | `"spaceBetween"` distributes all remaining space between columns. |
+| `keepTogether` | `boolean` | `false` | Measure the total columns height before rendering; if it does not fit, trigger a page break first. |
+| `marginTop/Bottom/Left/Right` | `number` | `0` | |
+
+```ts
+{
+  type: "columns",
+  widths: [150, "*"],
+  gap: 24,
+  columns: [
+    [{ type: "text", text: "Left column" }],
+    [{ type: "text", text: "Right column" }],
+  ],
+}
+```
+
+---
+
+### table
+
+Renders a grid with optional header rows, borders, and per-cell styling.
+
+**TableBlock properties:**
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `widths` | `(number \| "*")[]` | — | **Required.** Per-column widths. |
+| `body` | `TableCell[][]` | — | **Required.** 2-D array of cells. |
+| `headerRows` | `number` | `0` | Number of leading rows treated as headers (styled differently and repeated on new pages). |
+| `lineGap` | `number` | `2` | Extra vertical gap inside cells. |
+| `layout.border` | `"all" \| "none"` | `"all"` | Master border switch. |
+| `layout.hLineColor` | `string` | | Horizontal line color. |
+| `layout.vLineColor` | `string` | | Vertical line color. |
+| `layout.borderWidth` | `number` | `1` | Default border width. |
+| `layout.borderDash` | `number[]` | | Dash pattern, e.g. `[2, 2]`. |
+| `layout.rowStyles` | `Record<rowIndex, TableRowStyle>` | | Per-row `fillColor` and `border` overrides. |
+| `layout.columnStyles` | `Record<colIndex, TableColumnStyle>` | | Per-column `fillColor` and `border` overrides. |
+| `marginTop/Bottom/Left/Right` | `number` | `0` | |
+
+**TableCell properties:**
+
+| Property | Type | Description |
+|---|---|---|
+| `text` | `string` | Cell text content. |
+| `blocks` | `Block[]` | Rich block content inside the cell (replaces `text`). |
+| `bold / italic / underline / strike` | `boolean` | Typography flags. |
+| `fontSize` | `number` | |
+| `font` | `FontName` | |
+| `color` | `string` | Text color. |
+| `fillColor` | `string` | Cell background. |
+| `align` | `Alignment` | |
+| `style` | `StyleRef` | Named style reference. |
+| `colSpan` | `number` | Span across N columns. |
+| `rowSpan` | `number` | Span across N rows. |
+| `paddingTop/Right/Bottom/Left` | `number` | Cell inner padding. |
+| `border` | `TableCellBorder` | Per-cell border override. |
+
+```ts
+{
+  type: "table",
+  widths: ["*", 80, 80],
+  headerRows: 1,
+  layout: { hLineColor: "#E5E7EB", rowStyles: { 0: { fillColor: "#0B4A6F" } } },
+  body: [
+    [{ text: "Item", bold: true, color: "#FFFFFF" }, { text: "Qty", bold: true, color: "#FFFFFF", align: "right" }, { text: "Total", bold: true, color: "#FFFFFF", align: "right" }],
+    [{ text: "Consulting" }, { text: "12", align: "right" }, { text: "$3,000", align: "right" }],
+  ],
+}
+```
+
+---
+
+### keyValueGrid
+
+Two-column key/value pairs with flexible orientation and styling.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `columns` | `KeyValueItem[][]` | — | **Required.** Each sub-array is one grid column of items. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `"horizontal"`: key and value on the same row. `"vertical"`: key stacked above value. |
+| `keyWidth` | `number \| "*"` | `80` | Width reserved for the key in horizontal mode. `"*"` uses 35 % of the column. |
+| `columnWidths` | `(number \| "*")[]` | equal | Widths of each grid column. |
+| `separator` | `string` | `""` | Text inserted between key and value (e.g. `":"`). |
+| `rowGap` | `number` | `4` | Vertical gap between rows. |
+| `verticalKeyValueGap` | `number` | `2` | Gap between key and value in vertical orientation. |
+| `keyStyle / valueStyle` | `StyleRef` | | Default named style for all keys / values. |
+| `keyTextStyle / valueTextStyle` | `InlineTextStyle` | | Inline style overrides for keys / values. |
+| `keyAlign / valueAlign` | `Alignment` | | |
+| `marginTop/Bottom/Left/Right` | `number` | `0` | |
+
+**KeyValueItem properties:**
+
+| Property | Type | Description |
+|---|---|---|
+| `key` | `string` | Label text. |
+| `value` | `string` | Value text. |
+| `keyStyle / valueStyle` | `StyleRef` | Per-item style overrides. |
+| `keyTextStyle / valueTextStyle` | `InlineTextStyle` | Per-item inline style overrides. |
+| `keyAlign / valueAlign` | `Alignment` | Per-item alignment. |
+
+```ts
+{
+  type: "keyValueGrid",
+  orientation: "horizontal",
+  keyWidth: 100,
+  separator: ":",
+  keyStyle: "label",
+  rowGap: 5,
+  columns: [
+    [
+      { key: "Invoice", value: "#INV-0042" },
+      { key: "Due",     value: "2025-12-31" },
+    ],
+    [
+      { key: "Client", value: "Acme Corp" },
+      { key: "Total",  value: "$3,000.00", valueStyle: "highlight" },
+    ],
+  ],
+}
+```
+
+---
+
+### list
+
+Bullet or numbered lists with hanging-indent layout. Each item is a string or an object with per-item typography overrides. Long lists paginate item-by-item.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `items` | `(string \| ListItem)[]` | — | **Required.** List entries. |
+| `listStyle` | `"bullet" \| "number"` | `"bullet"` | Marker style. |
+| `bullet` | `string` | `"•"` | Custom bullet character (bullet lists only). |
+| `start` | `number` | `1` | Starting number (numbered lists only). |
+| `markerWidth` | `number` | auto | Fixed marker column width; otherwise computed from widest marker. |
+| `markerGap` | `number` | `6` | Space between marker and text in points. |
+| `itemGap` | `number` | `4` | Vertical gap between items in points. |
+| `fontSize` | `number` | `10` | Default font size for all items. |
+| `lineGap` | `number` | `4` | Default line gap inside items. |
+| `color` | `string` | black | Default text color. |
+| `style` | `StyleRef` | | Default named style for all items. |
+| `marginTop/Bottom/Left/Right` | `number` | `0` | |
+
+**ListItem properties** (when `items` entry is an object):
+
+| Property | Type | Description |
+|---|---|---|
+| `text` | `string` | **Required.** Item body text. |
+| `bold / italic / underline / strike` | `boolean` | Typography flags. |
+| `link` | `string` | Hyperlink URL. |
+| `color` | `string` | Text color override. |
+| `fontSize` | `number` | Font size override. |
+| `font` | `FontName` | Font override. |
+| `lineGap` | `number` | Line gap override. |
+| `style` | `StyleRef` | Named style override. |
+
+```ts
+{
+  type: "list",
+  listStyle: "bullet",
+  style: "label",
+  items: [
+    "Revenue grew 18% year-on-year",
+    { text: "Audited by Grant & Partners", bold: true, link: "https://example.com" },
+  ],
+  marginBottom: 12,
+},
+{
+  type: "list",
+  listStyle: "number",
+  start: 1,
+  fontSize: 9,
+  items: ["Download report", "Review appendix", "Sign authorization"],
+},
+```
+
+---
+
+### pageBreak
+
+Immediately finishes the current page and starts a new one. No additional properties.
+
+```ts
+{ type: "pageBreak" }
+```
+
+---
+
+### signature
+
+Reserves a block of vertical space for a handwritten or digital signature, optionally rendering label text and/or inner blocks below the signing area.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `height` | `number` | — | **Required.** Total reserved height in points. |
+| `width` | `number` | inner width | Width of the signing area. |
+| `label` | `string` | — | Caption printed below the signing line (e.g. `"Authorized signature"`). |
+| `image` | `string` | — | Path to a signature image pre-filled in the space. |
+| `blocks` | `Block[]` | — | Custom blocks rendered inside the reserved area. |
+| `marginLeft / marginRight` | `number` | `0` | |
+
+```ts
+{ type: "signature", height: 80, label: "Chief Executive Officer" }
+```
+
+---
+
+## Asset handling
+
+- **Images, QR codes, and barcodes** accept local file paths, `Buffer` values, or `https://` URLs.  
+  Remote assets are fetched and cached as `Buffer`s before rendering begins (parallel per-asset).
+- Nested assets in `columns`, `signature.blocks`, `header.blocks`, `footer.blocks`, etc. are traversed automatically.
+- If an image source fails to load and `defaultImage` is set on the document, the engine renders the fallback instead.
+- **Performance tip:** for frequently rendered documents, pre-download and pass `Buffer` values directly to avoid network round-trips.
+
+---
+
+## Rendering targets
+
+```ts
+import { renderCustomPdf, renderCustomPdfToBuffer } from "av6-pdf-engine";
+
+// Write to a file path
+await renderCustomPdf(def, "./output/doc.pdf");
+
+// Get a Buffer (for HTTP, S3, etc.)
+const buf: Buffer = await renderCustomPdfToBuffer(def);
+res.setHeader("Content-Type", "application/pdf");
+res.send(buf);
+```
+
+Both functions:
+1. Normalize all remote assets asynchronously.
+2. Create a `PDFDocument`, register fonts, set up layout helpers.
+3. Attach a `pageAdded` listener so PDFKit-internal page additions (e.g. long-text overflow) also receive the header, background, and watermark.
+4. Run the block render loop, then call `doc.end()`.
+
+---
+
+## Built-in fonts
+
+The following PDFKit built-in fonts are always available without registration:
+
+| Family | Variants |
+|---|---|
+| Helvetica | `Helvetica`, `Helvetica-Bold`, `Helvetica-Oblique`, `Helvetica-BoldOblique` |
+| Times | `Times-Roman`, `Times-Bold`, `Times-Italic`, `Times-BoldItalic` |
+| Courier | `Courier`, `Courier-Bold`, `Courier-Oblique`, `Courier-BoldOblique` |
+
+---
+
+## Engine behaviour notes
+
+**Automatic pagination**  
+`ensureSpaceFor` checks whether the next block fits before rendering it. If not, `finishPage(true)` is called — drawing the watermark (if applicable), the footer, and then `doc.addPage()` followed by `startNewPageLayout()` (background → header → watermark).
+
+**PDFKit-internal page additions**  
+When `doc.text()` overflows a page, PDFKit calls `doc.addPage()` internally. The engine listens on the `pageAdded` event to draw the background, header, and watermark on those pages as well. A `ctx.inManualPageAdd` flag prevents double-drawing when the engine's own `finishPage` adds the page.
+
+**Overflow guard**  
+If a block is taller than the entire page content area (between top and bottom margins), the engine emits a `console.warn`:
+```
+[pdf-engine] Block height (420pt) exceeds page content area (701pt). Content will overflow.
+```
 
-- Images, QR payloads, and barcodes accept paths, Buffers, or HTTPS URLs. Remote sources are fetched and cached as Buffers before rendering begins.
-- Nested structures (columns, signature blocks, headers/footers) are traversed automatically, so you can reference assets anywhere in the tree.
-- When using remote assets, ensure your runtime has outbound network access and consider wrapping `renderCustomPdf*` in your own caching layer.
+**Height measurement accuracy**  
+`heightOfString` is called with the same `lineGap` option that is passed to `doc.text()`, so the measured height matches the rendered height even when a custom `lineGap` is set.
 
-## Headers, footers, backgrounds, and watermarks
+**`visible: false`**  
+Any block (including deeply nested ones inside columns, tables, etc.) with `visible: false` is skipped during both rendering and height measurement.
 
-- Headers render inside the `top` margin band; footers render inside the `bottom` band. Adjust `marginTop/marginBottom` on header/footer defs for fine-grained spacing.
-- `pageBackground` is painted before header/content on every new page, while `watermark.mode` decides which pages receive the overlay.
-- Footer callbacks receive `(pageNumber, pageSize)` so you can display pagination, print timestamps, or conditionally hide content.
+---
 
 ## Contributors
 
@@ -142,4 +740,4 @@ Each block supports a `visible` flag so you can skip rendering without mutating
 
 ## License
 
-MIT — see `LICENSE` (provide your own if distributing).
+MIT — see `LICENSE`.