pretext-pdf 0.8.2 → 0.9.0

package/README.md

@@ -1,27 +1,60 @@
 # pretext-pdf
 
-> **The PDF library AI agents speak natively.**
+> **The PDF library AI agents speak natively — and humans love writing.**
 >
-> A `PdfDocument` is plain JSON. LLMs emit it in one shot — no codegen, no headless browser, no `eval`. Humans get a strict-typed, declarative API for invoices, reports, and templates.
+> A `PdfDocument` is plain JSON. LLMs emit it in one shot — no codegen, no headless browser, no `eval`.
+> Humans get a strict-typed declarative API for invoices, reports, resumes, and templates.
 
 [![npm version](https://img.shields.io/npm/v/pretext-pdf)](https://www.npmjs.com/package/pretext-pdf)
 [![npm downloads](https://img.shields.io/npm/dw/pretext-pdf)](https://www.npmjs.com/package/pretext-pdf)
 [![CI](https://github.com/Himaan1998Y/pretext-pdf/actions/workflows/ci.yml/badge.svg)](https://github.com/Himaan1998Y/pretext-pdf/actions)
 [![TypeScript](https://img.shields.io/badge/typescript-strict-blue)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/tests-598-brightgreen)](#test-coverage)
+[![Tests](https://img.shields.io/badge/tests-650%2B-brightgreen)](#tests)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Bundle](https://img.shields.io/badge/runtime%20deps-7-informational)](#runtime-footprint)
 
-**[Live demo](https://himaan1998y.github.io/pretext-pdf/)** — edit JSON, render PDFs instantly. No install.
-**[`pretext-pdf-mcp`](https://www.npmjs.com/package/pretext-pdf-mcp)** — drop-in MCP server for Claude / Cursor / Windsurf.
-**[Migrating from pdfmake?](docs/MIGRATION_FROM_PDFMAKE.md)** — every pattern mapped.
+**[Live demo](https://himaan1998y.github.io/pretext-pdf/)**  ·  **[`pretext-pdf-mcp`](https://www.npmjs.com/package/pretext-pdf-mcp)** (MCP server)  ·  **[Migrating from pdfmake?](#migrating-from-pdfmake)**
 
 *Layout powered by [`@chenglou/pretext`](https://github.com/chenglou/pretext) — the precision text-layout engine by [Cheng Lou](https://github.com/chenglou) (React core team, Midjourney).*
 
 ---
 
+## Table of contents
+
+- [Why pretext-pdf](#why-pretext-pdf)
+- [Install](#install)
+- [Quick start](#quick-start)
+  - [Library API](#library-api)
+  - [CLI](#cli)
+  - [Markdown](#markdown)
+  - [Templates](#templates)
+  - [pdfmake migration](#migrating-from-pdfmake)
+  - [MCP server (Claude / Cursor / Windsurf)](#mcp-server-claude--cursor--windsurf)
+- [Built for AI agents](#built-for-ai-agents)
+- [Element catalog](#element-catalog)
+- [Document features](#document-level-features)
+- [API reference](#api-reference)
+- [India / GST invoicing](#india--gst-invoicing)
+- [Custom fonts](#custom-fonts)
+- [Rich text](#rich-text)
+- [Footnotes](#footnotes)
+- [Examples](#examples)
+- [Error handling](#error-handling)
+- [Troubleshooting](#troubleshooting)
+- [Non-goals](#non-goals)
+- [Runtime footprint](#runtime-footprint)
+- [Performance](#performance)
+- [Tests](#tests)
+- [Security](#security)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [Credits](#credits)
+
+---
+
 ## Why pretext-pdf
 
-There are three established camps in JS PDF generation, and one gap. pretext-pdf lives in the gap.
+Three established camps in JS PDF generation, and one gap. pretext-pdf lives in the gap.
 
 | | pdfmake / jsPDF / pdfkit | Puppeteer / Playwright | LaTeX / WeasyPrint | **pretext-pdf** |
 |---|---|---|---|---|
@@ -29,54 +62,12 @@ There are three established camps in JS PDF generation, and one gap. pretext-pdf
 | Pure ESM, runs in serverless | ✅ | ⚠️ painful in Lambda | ❌ | ✅ |
 | Professional typography (kerning, hyphenation, RTL/CJK) | ❌ | ✅ | ✅ | ✅ |
 | Declarative — describe the document, don't draw it | ⚠️ partial | ❌ | ❌ | ✅ |
-| **LLM emits a working document in one shot** | ❌ requires a code-execution loop | ❌ requires HTML+CSS knowledge | ❌ requires LaTeX knowledge | ✅ pure JSON |
-| MCP server available out of the box | ❌ | ❌ | ❌ | ✅ |
-
-**The headline:** every other JS PDF library asks an LLM to *write code*. pretext-pdf asks it for a JSON object. That difference is what makes agent-generated PDFs reliable.
-
----
-
-## Built for AI agents
-
-A `PdfDocument` is a plain JSON object. No functions are required. No classes to instantiate. Every field is optional except `type` and a few element-specific essentials. That shape is exactly what an LLM can produce reliably with no tool-use loop.
-
-### Drop into Claude / Cursor / Windsurf via MCP
-
-```json
-{
-  "mcpServers": {
-    "pretext-pdf": {
-      "command": "npx",
-      "args": ["-y", "pretext-pdf-mcp"]
-    }
-  }
-}
-```
-
-Tools exposed: `generate_pdf`, `generate_invoice`, `generate_report`, `generate_from_markdown`, `list_element_types`. Built on the live [`pretext-pdf-mcp`](https://www.npmjs.com/package/pretext-pdf-mcp) package — versioned alongside this library.
-
-### Or call from any agent framework
-
-```typescript
-import { render } from 'pretext-pdf'
+| **LLM emits a working document in one shot** | ❌ requires codegen loop | ❌ requires HTML+CSS knowledge | ❌ requires LaTeX knowledge | ✅ pure JSON |
+| MCP server out of the box | ❌ | ❌ | ❌ | ✅ |
+| Drop-in CLI for shell pipelines | ❌ | ⚠️ wrap with code | ⚠️ separate binary | ✅ `pretext-pdf in.json out.pdf` |
+| pdfmake migration shim | — | ❌ | ❌ | ✅ `fromPdfmake()` |
 
-// Whatever produced this JSON — Claude, GPT, a workflow node, a form submission — works the same
-const pdf = await render({
-  metadata: { title: 'AI-generated quarterly report' },
-  content: [
-    { type: 'heading', level: 1, text: 'Q1 2026 Summary' },
-    { type: 'paragraph', text: 'Revenue grew 18% YoY.' },
-    { type: 'table', columns: [...], rows: [...] },
-  ],
-})
-```
-
-### Why JSON-first matters for agents
-
-- **No code execution loop.** The model returns JSON; you call `render()`. No sandbox, no `vm`, no Vercel Sandbox roundtrip.
-- **Schema-validatable.** Strict TypeScript types double as the contract. Pair with [Anthropic tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use) or [Vercel AI SDK structured output](https://sdk.vercel.ai/docs/ai-sdk-core/generating-structured-data) for guaranteed-shape results.
-- **Self-correcting errors.** Every failure throws `PretextPdfError` with a typed `code`. Feed it back to the model and it fixes itself.
-- **Progressive disclosure.** Optional peer deps mean an agent can ask for QR codes, charts, or markdown only when needed — token-efficient prompts.
+**The headline:** every other JS PDF library asks an LLM (or you) to *write code*. pretext-pdf asks for a JSON object. That difference is what makes agent-generated PDFs reliable — and the same shape happens to be a clean declarative API for humans too.
 
 ---
 
@@ -88,23 +79,25 @@ npm install pretext-pdf
 
 > **ESM only** — use `import`, not `require`. Requires Node.js ≥ 18.
 
-Optional peer dependencies — install only what you need:
+Optional peer dependencies — install only what you use:
 
-```bash
-npm install @napi-rs/canvas    # SVG / qr-code / barcode / chart elements
-npm install qrcode             # qr-code element
-npm install bwip-js            # barcode element
-npm install vega vega-lite     # chart element (Vega-Lite specs → vector SVG)
-npm install marked             # pretext-pdf/markdown entry point
-npm install @signpdf/signpdf   # PKCS#7 cryptographic signing
-```
+| Peer | When you need it |
+|---|---|
+| `@napi-rs/canvas` | SVG / qr-code / barcode / chart elements (Node only — browser uses `OffscreenCanvas`) |
+| `qrcode` | `qr-code` element |
+| `bwip-js` | `barcode` element (100+ symbologies) |
+| `vega` + `vega-lite` | `chart` element |
+| `marked` | `pretext-pdf/markdown` entry point and `--markdown` CLI flag |
+| `@signpdf/signpdf` | PKCS#7 cryptographic signing |
 
-> **Encryption is built-in** since v0.4.0 — no extra install needed. Just add `encryption` to your document config.
+> **Encryption is built-in** since v0.4.0 — no extra install.
 
 ---
 
 ## Quick start
 
+### Library API
+
 ```typescript
 import { render } from 'pretext-pdf'
 import { writeFileSync } from 'fs'
@@ -112,20 +105,21 @@ import { writeFileSync } from 'fs'
 const pdf = await render({
   pageSize: 'A4',
   margins: { top: 40, bottom: 40, left: 50, right: 50 },
-  metadata: { title: 'My Invoice', author: 'Acme Corp' },
+  metadata: { title: 'Invoice #001', author: 'Acme Corp' },
   content: [
     { type: 'heading', level: 1, text: 'Invoice #12345' },
     { type: 'paragraph', text: 'Thank you for your business.', fontSize: 12 },
     {
       type: 'table',
       columns: [
-        { name: 'Item', width: 200 },
-        { name: 'Qty', width: 50, align: 'right' },
-        { name: 'Price', width: 100, align: 'right' },
+        { width: 200 },
+        { width: 50, align: 'right' },
+        { width: 100, align: 'right' },
       ],
       rows: [
-        { Item: 'Professional Services', Qty: '10', Price: '$1,000' },
-        { Item: 'Hosting (annual)', Qty: '1', Price: '$500' },
+        { isHeader: true, cells: [{ text: 'Item', fontWeight: 700 }, { text: 'Qty', fontWeight: 700 }, { text: 'Price', fontWeight: 700 }] },
+        { cells: [{ text: 'Professional Services' }, { text: '10' }, { text: '$1,000' }] },
+        { cells: [{ text: 'Hosting (annual)' }, { text: '1' }, { text: '$500' }] },
       ],
     },
     { type: 'paragraph', text: 'Total: $1,500', align: 'right', fontWeight: 700 },
@@ -135,147 +129,196 @@ const pdf = await render({
 writeFileSync('invoice.pdf', pdf)
 ```
 
-### Builder API (fluent style)
+### CLI
 
-```typescript
-import { createPdf } from 'pretext-pdf'
+`pretext-pdf` ships with a binary that turns a JSON or Markdown file into a PDF — no Node code required.
 
-const pdf = await createPdf({ pageSize: 'A4' })
-  .addHeading('My Report', 1)
-  .addText('Fluent chainable API.')
-  .addTable({ columns: [{ name: 'Col A' }, { name: 'Col B' }], rows: [{ 'Col A': 'x', 'Col B': 'y' }] })
-  .build()
+```bash
+# JSON in, PDF out
+pretext-pdf doc.json invoice.pdf
+
+# Stdin → stdout (pipe-friendly)
+echo '{"content":[{"type":"heading","level":1,"text":"Hi"}]}' | pretext-pdf > out.pdf
+
+# Markdown straight to PDF
+pretext-pdf --markdown --code-font 'Courier New' README.md docs.pdf
+
+# Help / version
+pretext-pdf --help
+pretext-pdf --version
 ```
 
----
+| Flag | Meaning |
+|---|---|
+| `-i, --input <path>` | Read input from file (default: first positional, or stdin) |
+| `-o, --output <path>` | Write PDF to file (default: second positional, or stdout) |
+| `--markdown` | Treat input as Markdown — converts via `pretext-pdf/markdown` |
+| `--code-font <name>` | With `--markdown`, font family for fenced code blocks |
+| `-v, --version` | Print version |
+| `-h, --help` | Print help |
 
-## Output samples
+Exit codes: `0` success, `1` user error (bad args, invalid JSON), `2` render error.
 
-Real documents generated with pretext-pdf:
+### Markdown
 
-| Invoice | Market Report | Resume / CV |
-|---------|--------------|-------------|
-| [![Invoice](docs/screenshots/showcase-invoice.png)](examples/showcase-invoice.ts) | [![Report](docs/screenshots/showcase-report.png)](examples/showcase-report.ts) | [![Resume](docs/screenshots/showcase-resume.png)](examples/showcase-resume.ts) |
-| [View source](examples/showcase-invoice.ts) | [View source](examples/showcase-report.ts) | [View source](examples/showcase-resume.ts) |
+Convert any Markdown string to `ContentElement[]` in one call. Requires `marked` peer dep.
 
----
+```typescript
+import { markdownToContent } from 'pretext-pdf/markdown'
+import { render } from 'pretext-pdf'
 
-## What's in v0.8.0
+const md = `
+# Q1 2026 Report
 
-Five new capabilities, all behind optional peer dependencies (zero extra weight if unused):
+Revenue grew **18%** year-over-year.
 
-- **`qr-code`** — scannable QR codes for UPI payments, URLs, vCards. Requires `qrcode`.
-- **`barcode`** — 100+ symbologies (EAN-13, Code128, PDF417, DataMatrix…). Requires `bwip-js`.
-- **`chart`** — embed Vega-Lite specs as crisp vector SVG. Requires `vega` + `vega-lite`.
-- **`pretext-pdf/markdown`** — convert any Markdown string to `ContentElement[]` in one call. Requires `marked`.
-- **`pretext-pdf/templates`** — zero-dep template helpers: `createInvoice`, `createGstInvoice` (India GST / IGST / CGST+SGST), `createReport`.
+| Metric | Q4 2025 | Q1 2026 | Change |
+|--------|--------:|--------:|:------:|
+| Revenue | $45M | $60M | +33% |
+| Margin  | 62%  | 68%  | +6pp |
 
-See [CHANGELOG.md](CHANGELOG.md) for the full history.
+- [x] Cloud expansion launched
+- [x] Enterprise pipeline doubled
+- [ ] APAC region opening Q2
 
----
+> All figures in USD millions.
+`
 
-## India / GST invoicing
+const content = await markdownToContent(md, { codeFontFamily: 'Courier New' })
+const pdf = await render({ content })
+```
 
-pretext-pdf has built-in support for Indian invoice requirements:
+Supported: headings h1–h4, bold, italic, strikethrough, inline code, links, ordered/unordered lists (recursive nesting), **GFM tables (with column alignment)**, **GFM task lists** (☑/☐), fenced code blocks, blockquotes, horizontal rules.
 
-- **₹ symbol** renders correctly (bundled Inter font includes the Rupee glyph)
-- **Indian number formatting** — helper for 1,00,000 notation (not 100,000)
-- **GST structure** — CGST/SGST (intra-state) and IGST (inter-state) table layouts
-- **Amount in words** — Indian numbering system (Lakh/Crore)
-- **SAC/HSN codes** — column support in line-item tables
+### Templates
 
-Use the `createGstInvoice` template for a complete GST-compliant invoice in one call:
+Pre-built zero-dependency template functions:
 
 ```typescript
-import { createGstInvoice } from 'pretext-pdf/templates'
+import { createInvoice, createGstInvoice, createReport } from 'pretext-pdf/templates'
 import { render } from 'pretext-pdf'
 
-const content = createGstInvoice({
-  supplier: { name: 'Antigravity Systems', address: 'Gurugram, HR', gstin: '06AAACA1234A1ZV', state: 'Haryana' },
-  buyer: { name: 'TechStartup Ltd', address: 'Mumbai, MH', gstin: '27AABCB5678B1ZP', state: 'Maharashtra' },
-  invoiceNumber: 'INV/2026-27/001',
-  invoiceDate: '20 Apr 2026',
-  placeOfSupply: 'Maharashtra (27)',
-  items: [
-    { description: 'Software Development', hsnSac: '998314', quantity: 80, unit: 'Hrs', rate: 3000, taxRate: 18 },
-  ],
-  isInterState: true,            // auto-detected from state fields if omitted
-  qrUpiData: 'upi://pay?pa=merchant@hdfc&pn=Antigravity&am=283200',
-  bankName: 'HDFC Bank', accountNumber: '501001234567', ifscCode: 'HDFC0001234',
+const content = createInvoice({
+  from: { name: 'Acme Corp', address: '123 Main St', email: 'billing@acme.com' },
+  to:   { name: 'Client Ltd', address: '456 Oak Ave' },
+  invoiceNumber: 'INV-2026-001',
+  date: '2026-04-20',
+  items: [{ description: 'Consulting', quantity: 10, unitPrice: 150 }],
+  currency: '$', taxRate: 10, taxLabel: 'GST',
+  qrData: 'upi://pay?pa=acme@bank&am=1650',
 })
 const pdf = await render({ content })
 ```
 
-See [`examples/gst-invoice-india.ts`](examples/gst-invoice-india.ts) for the raw element approach.
-
----
+Available: `createInvoice` (any currency), `createGstInvoice` (India GST/IGST/CGST+SGST + UPI QR + amount-in-words), `createReport` (with optional TOC).
 
-## Markdown → PDF (`pretext-pdf/markdown`)
+### Migrating from pdfmake
 
-Convert any Markdown string to a `pretext-pdf` document in one call. Requires `marked` peer dep.
+`pretext-pdf/compat` translates pdfmake document descriptors into a `PdfDocument` — most common patterns work without code changes.
 
 ```typescript
-import { markdownToContent } from 'pretext-pdf/markdown'
+import { fromPdfmake } from 'pretext-pdf/compat'
 import { render } from 'pretext-pdf'
-import { writeFileSync } from 'fs'
 
-const md = `
-# Q1 2026 Report
-
-Revenue grew **18%** year-over-year, driven by:
+// Existing pdfmake document, unchanged
+const pdfmakeDoc = {
+  pageSize: 'LETTER',
+  pageMargins: [40, 60, 40, 60],
+  defaultStyle: { fontSize: 11 },
+  styles: {
+    header: { fontSize: 22, bold: true },
+    subheader: { fontSize: 16 },
+  },
+  content: [
+    { text: 'Invoice #001', style: 'header' },
+    { text: 'Acme Corp', style: 'subheader' },
+    'Thanks for your business.',
+    {
+      table: {
+        widths: ['*', 'auto', 80],
+        headerRows: 1,
+        body: [
+          ['Item', 'Qty', 'Price'],
+          ['Widget', '3', '$30'],
+          ['Sprocket', '5', '$50'],
+        ],
+      },
+    },
+    { ul: ['Net 30 terms', 'Late fee: 1.5%/mo'] },
+  ],
+}
 
-- Cloud services (+32%)
-- Enterprise licenses (+12%)
+const pdf = await render(fromPdfmake(pdfmakeDoc))
+```
 
-> All figures are in USD millions.
-`
+| pdfmake feature | Compat support |
+|---|---|
+| `string` content | ✅ → paragraph |
+| `{ text, bold, italics, color, fontSize, alignment, font }` | ✅ → paragraph or rich-paragraph |
+| `{ text, style: 'header' }` (style lookup) | ✅ — `header`/`h1`/`title` map to heading 1, `subheader`/`h2` to 2, etc. |
+| `{ ul }` / `{ ol }` (recursive) | ✅ → list |
+| `{ table: { body, widths, headerRows } }` | ✅ → table |
+| `{ image, width, height }` | ✅ → image |
+| `{ qr, fit }` | ✅ → qr-code |
+| `{ pageBreak: 'before' \| 'after' }` | ✅ → page-break |
+| `{ stack }` | ✅ → flattened inline |
+| `{ link }` on inline text | ✅ → span.href |
+| `pageSize`, `pageOrientation`, `pageMargins` | ✅ |
+| `info` (title/author/subject/keywords) | ✅ → metadata |
+| `header`, `footer` (string form) | ✅ |
+| `{ columns }` | ⚠️ flattened with a warning |
+| `{ canvas }` | ❌ unsupported (drawing primitives) |
+| Function-style `header`/`footer` | ❌ pass a string |
+
+Override the heading-name mapping via `fromPdfmake(doc, { headingMap: { ... } })`.
+
+### MCP server (Claude / Cursor / Windsurf)
+
+Drop into any MCP-aware AI agent in 60 seconds:
 
-const content = await markdownToContent(md, {
-  codeFontFamily: 'Courier New',  // enables fenced code block rendering
-})
-const pdf = await render({ content })
-writeFileSync('report.pdf', pdf)
+```json
+{
+  "mcpServers": {
+    "pretext-pdf": {
+      "command": "npx",
+      "args": ["-y", "pretext-pdf-mcp"]
+    }
+  }
+}
 ```
 
-Supported Markdown: headings h1–h4, bold, italic, strikethrough, inline code, links, ordered/unordered lists (2 levels), fenced code blocks, blockquotes, horizontal rules.
+Exposes: `generate_pdf`, `generate_invoice`, `generate_report`, `generate_from_markdown`, `list_element_types`. Versioned alongside this library — see [`pretext-pdf-mcp`](https://www.npmjs.com/package/pretext-pdf-mcp).
 
 ---
 
-## Invoice & report templates (`pretext-pdf/templates`)
+## Built for AI agents
 
-Pre-built zero-dependency template functions that generate `ContentElement[]` arrays:
+A `PdfDocument` is a plain JSON object. No functions are required. Every field is optional except `type` and a few element-specific essentials. That shape is exactly what an LLM can produce reliably with no tool-use loop.
 
 ```typescript
-import { createInvoice, createGstInvoice, createReport } from 'pretext-pdf/templates'
 import { render } from 'pretext-pdf'
 
-// Generic invoice (any currency)
-const invoiceContent = createInvoice({
-  from: { name: 'Acme Corp', address: '123 Main St', email: 'billing@acme.com' },
-  to: { name: 'Client Ltd', address: '456 Oak Ave' },
-  invoiceNumber: 'INV-2026-001', date: '2026-04-20',
-  items: [{ description: 'Consulting', quantity: 10, unitPrice: 150 }],
-  currency: '$', taxRate: 10, taxLabel: 'GST',
-  qrData: 'upi://pay?pa=acme@bank&am=1650',
-})
-
-// Research report with optional TOC
-const reportContent = createReport({
-  title: 'Annual Performance Report',
-  author: 'Finance Team', date: 'April 2026',
-  abstract: 'Revenue grew 18% YoY across all segments.',
-  includeTableOfContents: true,
-  sections: [
-    { title: 'Revenue', paragraphs: ['Cloud +32%, Enterprise +12%.'], bullets: ['SaaS: $2.8M', 'Services: $1.1M'] },
+// Whatever produced this JSON — Claude, GPT, a workflow node, a form submission — works the same
+const pdf = await render({
+  metadata: { title: 'AI-generated quarterly report' },
+  content: [
+    { type: 'heading', level: 1, text: 'Q1 2026 Summary' },
+    { type: 'paragraph', text: 'Revenue grew 18% YoY.' },
+    { type: 'table', columns: [/* ... */], rows: [/* ... */] },
   ],
 })
-
-const pdf = await render({ content: reportContent })
 ```
 
+### Why JSON-first matters for agents
+
+- **No code execution loop.** Model returns JSON; you call `render()`. No sandbox, no `vm`, no Vercel Sandbox roundtrip.
+- **Schema-validatable.** Strict TypeScript types double as the contract. Pair with [Anthropic tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use) or [Vercel AI SDK structured output](https://sdk.vercel.ai/docs/ai-sdk-core/generating-structured-data).
+- **Self-correcting errors.** Every failure throws `PretextPdfError` with a typed `code`. Feed it back to the model and it fixes itself.
+- **Progressive disclosure.** Optional peer deps mean agents only ask for QR codes, charts, or markdown when needed — token-efficient prompts.
+
 ---
 
-## Element type reference
+## Element catalog
 
 ```
 paragraph    heading(1-4)   spacer       hr           page-break
@@ -287,42 +330,39 @@ toc          qr-code        barcode      chart        footnote-def
 | Element | What it does |
 | --- | --- |
 | `paragraph` | Text block — font, size, color, align, background, letterSpacing, smallCaps, tabularNumbers, multi-column (`columns` + `columnGap`), RTL (`dir`) |
-| `heading` | H1–H4 with bookmarks, URL links, internal anchors, tabularNumbers, RTL (`dir`) |
-| `table` | Fixed/proportional columns, colspan, rowspan, repeating headers across page breaks |
-| `image` | PNG/JPG/WebP with sizing, alignment, float left/right with `floatText` or rich `floatSpans` (mixed-format caption) |
-| `list` | Ordered/unordered, 2-level nesting, `nestedNumberingStyle: 'restart' \| 'continue'` |
+| `heading` | H1–H4 with bookmarks, URL links, internal anchors, tabularNumbers, RTL |
+| `table` | Fixed/proportional/auto columns, colspan, rowspan, repeating headers across page breaks |
+| `image` | PNG/JPG/WebP with sizing, alignment, float left/right with `floatText` or rich `floatSpans` |
+| `list` | Ordered/unordered, recursive nesting, `nestedNumberingStyle: 'restart' \| 'continue'` |
 | `code` | Monospace block with background and padding |
 | `blockquote` | Left border + background |
 | `rich-paragraph` | Mixed bold/italic/color/size/super/subscript spans with inline hyperlinks |
 | `svg` | Embedded SVG graphics with auto-sizing from viewBox |
 | `toc` | Auto-generated table of contents with accurate page numbers (two-pass) |
-| `qr-code` | Scannable QR code — UPI payment links, URLs, vCards. `data`, `size`, `errorCorrectionLevel`, `foreground`/`background` color. Requires `qrcode` peer dep. |
-| `barcode` | 100+ symbologies — EAN-13, Code128, PDF417, DataMatrix, and more via `symbology` field. Requires `bwip-js` peer dep. |
-| `chart` | Vega-Lite data visualisation — pass any valid Vega-Lite spec to `spec`. Rendered as vector SVG. Requires `vega` + `vega-lite` peer deps. |
+| `qr-code` | Scannable QR code — UPI, URLs, vCards. Requires `qrcode` peer dep. |
+| `barcode` | 100+ symbologies — EAN-13, Code128, PDF417, DataMatrix, etc. Requires `bwip-js`. |
+| `chart` | Vega-Lite data visualisation as vector SVG. Requires `vega` + `vega-lite`. |
 | `comment` | PDF sticky-note annotation (visible in Acrobat/Preview sidebar) |
-| `hr` | Horizontal rule |
-| `spacer` | Fixed-height gap |
-| `page-break` | Force new page |
+| `form-field` | Interactive text/checkbox/radio/dropdown/button (with `flattenForms` to bake) |
+| `callout` | Info / warning / tip / note callout boxes |
+| `footnote-def` | Paired with `span.footnoteRef` for proper footnote numbering + zone reservation |
+| `hr` / `spacer` / `page-break` | Layout primitives |
 
 ### Document-level features
 
 | Feature | Config key | Notes |
 | --- | --- | --- |
 | Watermarks | `doc.watermark` | Text or image, opacity, rotation |
-| Encryption | `doc.encryption` | Password + granular permissions |
+| Encryption | `doc.encryption` | Password + granular permissions, built-in |
+| Cryptographic signing | `doc.signature: { p12, passphrase, ... }` | PKCS#7, optional `@signpdf/signpdf` |
 | PDF Bookmarks | `doc.bookmarks` | Auto-generated from headings |
-| Hyphenation | `doc.hyphenation` | Liang's algorithm, `language: 'en-us'` |
-| Headers/Footers | `doc.header` / `doc.footer` | `{{pageNumber}}`, `{{totalPages}}`, `{{date}}`, `{{author}}` tokens |
-| Per-section overrides | `doc.sections` | Different header/footer/margins per page range |
-| Metadata | `doc.metadata` | Title, author, subject, keywords, `language` (PDF /Lang), `producer` |
+| Hyphenation | `doc.hyphenation` | Liang's algorithm, e.g. `language: 'en-us'` |
+| Headers/Footers | `doc.header` / `doc.footer` | `{{pageNumber}}`, `{{totalPages}}`, `{{date}}` tokens |
+| Per-section overrides | `doc.sections` | Different header/footer per page range |
+| Metadata | `doc.metadata` | Title, author, subject, keywords, language, producer |
 | Hyperlinks | `paragraph.url`, `heading.url`, `heading.anchor`, `span.href` | External, mailto, internal anchors |
-| Inline formatting | `span.verticalAlign: 'superscript'\|'subscript'`, `paragraph.letterSpacing`, `heading.smallCaps` | |
-| Sticky notes | `{ type: 'comment', contents: '...' }`, `paragraph.annotation` | |
 | Document assembly | `merge(pdfs)`, `assemble(parts)` | Combine pre-rendered + freshly rendered |
-| Interactive forms | `{ type: 'form-field', fieldType: 'text'\|'checkbox'\|'radio'\|'dropdown'\|'button' }`, `doc.flattenForms` | |
-| Cryptographic signing | `doc.signature: { p12, passphrase, signerName, reason, location }` | PKCS#7 via optional `@signpdf/signpdf` |
-| Visual signature placeholder | `doc.signature: { signerName, reason, location, x, y, page }` | |
-| Callout boxes | `{ type: 'callout', content, style: 'info'\|'warning'\|'tip'\|'note', title }` | |
+| Path-traversal lockdown | `doc.allowedFileDirs` | Restrict file-source reads to listed dirs |
 
 ---
 
@@ -334,22 +374,17 @@ toc          qr-code        barcode      chart        footnote-def
 import { render } from 'pretext-pdf'
 
 const pdf = await render({
-  pageSize: 'A4',          // 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal' | [w, h]
+  pageSize: 'A4',          // 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal' | 'Tabloid' | [w, h]
   margins: { top: 72, bottom: 72, left: 72, right: 72 },
-  defaultFont: 'Inter',    // Inter 400 bundled; load others via doc.fonts
+  defaultFont: 'Inter',    // Inter 400/700 bundled
   defaultFontSize: 12,
-  metadata: {
-    title: 'Document Title',
-    author: 'Author Name',
-    subject: 'Description',
-    keywords: ['pdf', 'report'],
-  },
+  metadata: { title: '...', author: '...', keywords: ['pdf'] },
   watermark: { text: 'DRAFT', opacity: 0.15, rotation: -45 },
   encryption: { userPassword: 'open', ownerPassword: 'admin', permissions: { printing: true, copying: false } },
   bookmarks: { minLevel: 1, maxLevel: 3 },
-  hyphenation: { language: 'en-us', minWordLength: 6 }, // ⚠️ Use lowercase: 'en-us' not 'en-US' — matches the npm package name hyphenation.en-us
-  header: { text: 'My Document — {{pageNumber}} of {{totalPages}}', align: 'right' },
-  footer: { text: 'Confidential', align: 'center', color: '#999999' },
+  hyphenation: { language: 'en-us', minWordLength: 6 },
+  header: { text: '{{pageNumber}} of {{totalPages}}', align: 'right' },
+  footer: { text: 'Confidential', align: 'center', color: '#999' },
   content: [ /* ContentElement[] */ ],
 })
 ```
@@ -360,24 +395,74 @@ Combine pre-rendered PDFs:
 
 ```typescript
 import { merge } from 'pretext-pdf'
-
 const combined = await merge([coverPdf, bodyPdf, appendixPdf])
 ```
 
 ### `assemble(parts): Promise<Uint8Array>`
 
-Mix new document configs with existing PDFs:
+Mix new docs with existing PDFs:
 
 ```typescript
 import { assemble } from 'pretext-pdf'
 
 const report = await assemble([
   { pdf: existingCoverPdf },
-  { doc: { content: [...] } },   // rendered fresh
+  { doc: { content: [/* fresh */] } },
   { pdf: standardTermsPdf },
 ])
 ```
 
+### `createPdf(opts): PdfBuilder` (fluent builder)
+
+```typescript
+import { createPdf } from 'pretext-pdf'
+
+const pdf = await createPdf({ pageSize: 'A4' })
+  .addHeading('My Report', 1)
+  .addText('Fluent chainable API.')
+  .addTable({ columns: [{ name: 'Col A' }, { name: 'Col B' }], rows: [{ 'Col A': 'x', 'Col B': 'y' }] })
+  .build()
+```
+
+### `markdownToContent(md, opts?)` *(from `pretext-pdf/markdown`)*
+
+### `createInvoice / createGstInvoice / createReport` *(from `pretext-pdf/templates`)*
+
+### `fromPdfmake(doc, opts?)` *(from `pretext-pdf/compat`)*
+
+---
+
+## India / GST invoicing
+
+Built-in support for Indian invoice requirements:
+
+- **₹ symbol** renders correctly (bundled Inter includes the Rupee glyph)
+- **Indian number formatting** (`1,00,000` not `100,000`)
+- **GST structure** — CGST/SGST (intra-state) and IGST (inter-state) layouts (auto-detected from state fields)
+- **Amount in words** — Indian numbering system (Lakh/Crore), with correct sub-rupee handling
+- **SAC/HSN codes** — column support in line-item tables
+
+```typescript
+import { createGstInvoice } from 'pretext-pdf/templates'
+import { render } from 'pretext-pdf'
+
+const content = createGstInvoice({
+  supplier: { name: 'Antigravity Systems', address: 'Gurugram, HR', gstin: '06AAACA1234A1ZV', state: 'Haryana' },
+  buyer: { name: 'TechStartup Ltd', address: 'Mumbai, MH', gstin: '27AABCB5678B1ZP', state: 'Maharashtra' },
+  invoiceNumber: 'INV/2026-27/001',
+  invoiceDate: '20 Apr 2026',
+  placeOfSupply: 'Maharashtra (27)',
+  items: [
+    { description: 'Software Development', hsnSac: '998314', quantity: 80, unit: 'Hrs', rate: 3000, taxRate: 18 },
+  ],
+  qrUpiData: 'upi://pay?pa=merchant@hdfc&pn=Antigravity&am=283200',
+  bankName: 'HDFC Bank', accountNumber: '501001234567', ifscCode: 'HDFC0001234',
+})
+const pdf = await render({ content })
+```
+
+See [`examples/gst-invoice-india.ts`](examples/gst-invoice-india.ts) for a fully wired example.
+
 ---
 
 ## Custom fonts
@@ -391,13 +476,13 @@ const pdf = await render({
   ],
   defaultFont: 'Roboto',
   content: [
-    { type: 'paragraph', text: 'Uses Roboto font' },
-    { type: 'paragraph', text: 'Bold text', fontWeight: 700 },
+    { type: 'paragraph', text: 'Uses Roboto' },
+    { type: 'paragraph', text: 'Bold', fontWeight: 700 },
   ],
 })
 ```
 
-> **Avoid `system-ui`** as a font name on macOS — it triggers a known layout-measurement inaccuracy in Pretext. Always name fonts explicitly.
+> **Avoid `system-ui`** — known Pretext layout-measurement inaccuracy on macOS. Always name fonts explicitly.
 
 ---
 
@@ -427,7 +512,7 @@ const pdf = await render({
 
 ## Footnotes
 
-Use `createFootnoteSet()` to generate matched reference/definition pairs with guaranteed unique IDs:
+`createFootnoteSet()` produces matched reference/definition pairs with guaranteed unique IDs:
 
 ```typescript
 import { render, createFootnoteSet } from 'pretext-pdf'
@@ -456,37 +541,29 @@ await render({
 
 ## Examples
 
-Run working examples from the `examples/` directory:
-
 ```bash
-# v0.8.0 new element examples (install optional deps first)
-# npm install qrcode bwip-js vega vega-lite marked
-
-# Phase 7 examples
 npm run example                # Basic invoice
+npm run example:gst            # India GST invoice
 npm run example:watermark      # Text/image watermarks
 npm run example:bookmarks      # PDF outline/bookmarks
 npm run example:toc            # Auto table of contents
 npm run example:rtl            # Arabic/Hebrew RTL text
 npm run example:encryption     # Password-protected PDF
-
-# Phase 8 examples
-npm run example:hyperlinks     # External links, email links, internal anchors
-npm run example:annotations    # Sticky notes on elements
-npm run example:assembly       # Merge and assemble multiple PDFs
-npm run example:inline         # Superscript, subscript, letter-spacing, small-caps
+npm run example:hyperlinks     # External + email + internal anchors
+npm run example:annotations    # Sticky notes
+npm run example:assembly       # Merge + assemble multiple PDFs
+npm run example:inline         # Super/subscript, letterSpacing, smallCaps
 npm run example:forms          # Interactive form fields
-npm run example:callout        # Callout boxes (info, warning, tip, note)
-npm run example:gst            # India GST-compliant invoice
+npm run example:callout        # Callout boxes
 ```
 
-All examples write output to `output/*.pdf`.
+All write to `output/*.pdf`.
 
 ---
 
 ## Error handling
 
-Every error throws `PretextPdfError` with a typed `code` — designed so an LLM (or a human) can self-correct:
+Every error throws `PretextPdfError` with a typed `code`:
 
 ```typescript
 import { render, PretextPdfError } from 'pretext-pdf'
@@ -499,36 +576,32 @@ try {
       case 'VALIDATION_ERROR':   // Invalid config
       case 'FONT_LOAD_FAILED':   // Font file not found
       case 'IMAGE_TOO_TALL':     // Image doesn't fit on page
-      case 'ASSEMBLY_EMPTY':     // merge/assemble called with empty array
-      // ... see CHANGELOG.md for full list
+      case 'IMAGE_LOAD_FAILED':  // URL fetch / safety check failed
+      case 'ASSEMBLY_EMPTY':     // merge / assemble called with empty array
+      // ... see CHANGELOG.md for the full list
     }
   }
 }
 ```
 
+This shape is also designed for AI self-correction loops — the typed `code` is enough context for an LLM to fix its own output.
+
 ---
 
 ## Troubleshooting
 
 ### Hyphenation language not found
 
-```
-UNSUPPORTED_LANGUAGE: Language 'en-US' not supported
-```
-
 Use **lowercase** language codes that match the npm package name:
 
 ```typescript
-// Wrong — 'en-US' fails on Linux (case-sensitive filesystem)
-hyphenation: { language: 'en-US' }
-
-// Correct — matches 'hyphenation.en-us' package name
-hyphenation: { language: 'en-us' }
+hyphenation: { language: 'en-us' }  // ✅
+hyphenation: { language: 'en-US' }  // ❌ fails on Linux (case-sensitive FS)
 ```
 
-### SVG rendering requires optional dependency
+### SVG / chart / qr-code / barcode rendering
 
-Install `@napi-rs/canvas` for SVG / chart / qr-code / barcode support:
+Install `@napi-rs/canvas` (Node only — browsers use native `OffscreenCanvas`):
 
 ```bash
 npm install @napi-rs/canvas
@@ -536,16 +609,19 @@ npm install @napi-rs/canvas
 
 ### PDF is blank or too small
 
-Check margins — if left+right margins exceed page width, content width becomes negative:
+Check margins. If `left + right` exceeds page width, content width becomes negative:
 
 ```typescript
-// For narrow pages, reduce margins:
 margins: { top: 36, bottom: 36, left: 36, right: 36 }
 ```
 
-### Form fields not interactive after `flattenForms`
+### Form fields not interactive
 
-`flattenForms: true` bakes fields into static content — by design. Remove it to keep them interactive.
+`flattenForms: true` bakes fields into static content — by design. Remove the flag to keep them interactive.
+
+### Browser usage
+
+Supply font bytes via `doc.fonts: [{ family: 'Inter', weight: 400, src: <Uint8Array> }]` — the bundled Inter loader is Node-only. Also register the same font with `document.fonts.add(new FontFace(...))` so pretext's measurement matches pdf-lib's drawing.
 
 ---
 
@@ -555,66 +631,79 @@ What pretext-pdf is **not** trying to be — pick a different tool for these:
 
 - **Editing or parsing existing PDFs** → [`pdf-lib`](https://github.com/Hopding/pdf-lib), [`pdf-parse`](https://www.npmjs.com/package/pdf-parse)
 - **Filling existing PDF form templates** → [`pdf-lib`](https://github.com/Hopding/pdf-lib), [`pdftk`](https://www.pdflabs.com/tools/pdftk-server/)
-- **Heavily art-directed pages** with CSS grids, SVG illustrations, floats, background images → headless Chrome (Puppeteer) still wins
+- **Heavily art-directed pages** with CSS grids, SVG illustrations, floats, background images → headless Chrome (Puppeteer)
 - **PDF/A archival, PDF/UA accessibility tagging** → not yet
-- **Print-shop kerning pairs, OpenType ligatures, variable-font axes beyond weight** → Pretext itself doesn't model these
+- **Print-shop kerning pairs, OpenType ligatures, variable-font axes beyond weight** → upstream Pretext doesn't model these
 
 ---
 
-## Runtime requirements
+## Runtime footprint
+
+Mandatory runtime dependencies:
 
-- **Node.js ≥ 18** with `@napi-rs/canvas` peer dep (lazy-loaded — only required when you use SVG/chart/QR/barcode elements)
-- **`Intl.Segmenter`** (built-in on Node 18+ and all modern browsers)
-- **Browser support** — works directly in modern browsers; bring your own font bytes
-- **Cold-start cost** on serverless: `@napi-rs/canvas` adds ~5–10 MB and a few hundred ms on the first request. Subsequent requests in a warm container are sub-second.
-- **Fonts must be fully loaded** before `render()` runs — for browser usage, await `document.fonts.ready` first
+- `@cantoo/pdf-lib` — PDF assembly
+- `@chenglou/pretext` — text-layout engine
+- `@fontsource/inter` + `@pdf-lib/fontkit` — bundled Inter + font subsetting
+- `bidi-js` — bidirectional text resolution
+- `hypher` + `hyphenation.en-us` — hyphenation
+
+All other capabilities (SVG, charts, QR, barcodes, markdown, signing) are optional peer deps — install only what you use.
+
+**Browser:** the library imports cleanly from any non-`file://` URL (esm.sh, Vite dev server, browser bundles) since v0.8.1. Bring your own Inter font via `doc.fonts` and register it with `document.fonts.add(...)` for accurate measurement.
 
 ---
 
 ## Performance
 
-Benchmarked on Windows 11 / Node 22 / Intel i7-12th Gen. Numbers are averages over 10 runs, excluding the first cold JIT run.
+Benchmarked on Windows 11 / Node 22 / Intel i7-12th Gen. Averages over 10 runs, excluding the first cold JIT.
 
 | Document | Render time | PDF size |
 | --- | --- | --- |
 | 1 page (heading + paragraph + list) | ~220 ms | ~45 KB |
-| 10 pages (40 sections, mixed elements) | ~1,100 ms | ~180 KB |
 | Mixed (heading + paragraph + 20-row table + list + hr) | ~290 ms | ~60 KB |
+| 10 pages (40 sections, mixed elements) | ~1,100 ms | ~180 KB |
 
-**Font subsetting** is automatic for TTF/OTF fonts. Only the glyphs used in the document are embedded, typically reducing PDF size by 40–60% compared to full font embedding. A typical single-font invoice renders under 65 KB. WOFF2 fonts are embedded without subsetting due to an upstream library limitation.
+**Font subsetting** is automatic for TTF/OTF fonts. Only used glyphs are embedded — typically 40–60% smaller than full-font embedding. Single-font invoices render under 65 KB.
 
-For large documents (10,000+ elements), set `NODE_OPTIONS=--max-old-space-size=4096` to prevent GC pressure.
+For documents with 10,000+ elements, set `NODE_OPTIONS=--max-old-space-size=4096`.
 
 ---
 
-## Test coverage
+## Tests
 
-598+ tests across all phases with 100% pass rate:
+650+ tests across all phases with 100% pass rate:
 
 ```bash
-npm test              # Full suite (unit + e2e + all phases including v0.8.0)
-npm run test:unit     # Validation, builder, rich-text unit tests
-npm run test:e2e      # End-to-end render tests
-npm run test:10a      # QR code + barcode tests
-npm run test:10b      # Vega-Lite chart tests
-npm run test:10c      # Markdown converter tests
-npm run test:10d      # Template function tests
-npm run test:phases   # All phase tests (7–11, performance, signatures)
+npm test              # Full suite (contract + unit + e2e + phases + 2f stress)
+npm run test:unit     # Validation, builder, rich-text
+npm run test:e2e      # End-to-end render
+npm run test:phases   # All phase tests including v0.8/v0.9 features
+npm run test:rich     # Rich-paragraph compositor (incl. v0.8.2 whitespace regressions)
+npm run test:contract # Public API surface contracts
+npm run test:visual   # Pixel-diff visual regressions
 ```
 
-**Coverage**: type safety, path validation, error handling, boundary cases, crypto signing, document assembly, all content elements, optional-dep error codes, MCP tool validation.
+**Coverage**: type safety, path validation, SSRF, error handling, boundary cases, crypto signing, document assembly, every content element, optional-dep error codes, MCP tool validation, browser import simulation.
 
 ---
 
 ## Security
 
-Comprehensive April 2026 security audit completed — 41 issues identified and fixed across path-traversal protection, async I/O, error sanitization, type-safety, and explicit failure modes. See [SECURITY.md](SECURITY.md) for the disclosure policy and [CHANGELOG.md](CHANGELOG.md) for audit details.
+A comprehensive April 2026 audit fixed 41 issues across path-traversal protection, async I/O, error sanitization, type safety, and explicit failure modes. Subsequent fixes:
+
+- **v0.8.3** — IPv4-mapped IPv6 SSRF bypass closed; `fetch` redirects now revalidated per hop.
+- **v0.8.1** — Browser module-init crashes fixed (Node-only APIs gated behind `IS_NODE` checks).
+
+Highlights of the current security posture:
 
-Highlights:
-- Zero known path-traversal vulnerabilities; opt-in `allowedFileDirs` lockdown for user-controlled inputs
-- All error messages sanitized — no filesystem paths or secrets leak through
+- Opt-in `allowedFileDirs` lockdown for user-controlled file inputs
+- All error messages sanitized (no filesystem paths or secrets leak)
 - Async file I/O throughout (non-blocking)
 - Strict TypeScript with documented `any`-casts only at pdf-lib internal boundaries
+- HTTPS-only fetch with private-IP / SSRF guard, including IPv6
+- HTTP redirect chain re-validated against the same SSRF guard
+
+See [SECURITY.md](SECURITY.md) for disclosure policy.
 
 ---
 
@@ -627,15 +716,11 @@ Highlights:
 | 8A–H | Annotations, forms, assembly, callouts, signatures, metadata, hyperlinks, inline formatting | ✅ |
 | 9A–C | Cryptographic signatures (PKCS#7), image floats, font subsetting | ✅ |
 | 10A–D | QR codes, barcodes, Vega-Lite charts, Markdown, templates | ✅ |
-| 11+ | Variable fonts, OpenType features, PDF/A, PDF/UA accessibility | 🔜 |
-
-See [docs/ROADMAP.md](docs/ROADMAP.md) for the full plan.
-
----
-
-## Migration from pdfmake
+| 11+ | Performance enhancements, hardening | ✅ |
+| **0.9.0** | **CLI, pdfmake compat shim, GFM tables + task lists** | ✅ |
+| Future | Variable fonts, OpenType features, PDF/A, PDF/UA accessibility | 🔜 |
 
-Coming from pdfmake? See the **[Migration Guide](docs/MIGRATION_FROM_PDFMAKE.md)** — every common pdfmake pattern mapped to its pretext-pdf equivalent.
+See [docs/ROADMAP.md](docs/ROADMAP.md).
 
 ---
 
@@ -643,6 +728,16 @@ Coming from pdfmake? See the **[Migration Guide](docs/MIGRATION_FROM_PDFMAKE.md)
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). TDD approach — write tests first.
 
+Useful commands:
+
+```bash
+npm install            # one-time setup
+npm run build          # tsc → dist/
+npm run typecheck      # tsc --noEmit
+npm test               # full suite
+npm run example        # run a sample render
+```
+
 ---
 
 ## License