pretext-pdf 0.2.0 → 0.3.1

package/README.md

@@ -1,92 +1,81 @@
 # pretext-pdf
 
 > **Declarative JSON → PDF generation with professional typography.**
-> 
+>
 > Build sophisticated, multi-page documents with precise text layout, international support, and zero browser overhead.
 
 [![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-75%2B-brightgreen)](#test-coverage)
+[![Tests](https://img.shields.io/badge/tests-146%2B-brightgreen)](#test-coverage)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 ---
 
 ## Why pretext-pdf?
 
-### The Problem
-- **pdfmake** is easy but produces mediocre typography (no kerning, ligatures, proper line breaking)
-- **Puppeteer** renders beautiful PDFs but requires a 400MB browser and is slow at scale
-- **Typst** has perfect typography but is Rust-based (not JavaScript)
+| | pdfmake | Puppeteer | **pretext-pdf** |
+|---|---|---|---|
+| Easy declarative API | ✅ | ❌ | ✅ |
+| Professional typography | ❌ | ✅ | ✅ |
+| Lightweight (no browser) | ✅ | ❌ | ✅ |
+| International text (RTL/CJK) | ❌ | ✅ | ✅ |
+| Pure Node.js | ✅ | ❌ | ✅ |
+| Hyperlinks + annotations | ❌ | ✅ | ✅ |
+| Document assembly | ❌ | ❌ | ✅ |
 
-### The Solution
-**pretext-pdf** bridges the gap: **declarative + professional typography + lightweight**.
+### Powered by [pretext](https://github.com/chenglou/pretext)
+
+Pretext is a precision text layout engine by [Cheng Lou](https://github.com/chenglou) (React core team, Midjourney).
 
 ```
-                 Easy  |  Professional  |  Lightweight
-pdfmake:          ✅   |      ❌        |      ✅
-Puppeteer:        ❌   |      ✅        |      ❌
-pretext-pdf:      ✅   |      ✅        |      ✅
+JSON descriptor  →  pretext layout  →  pdf-lib renderer  →  PDF bytes
+                     (kerning,           (annotations,
+                      hyphenation,        encryption,
+                      RTL, CJK)           hyperlinks)
 ```
 
-### Powered by [pretext](https://github.com/chenglou/pretext)
-Pretext is a precision text layout engine built by [Cheng Lou](https://github.com/chenglou) (React core team, Midjourney).
-It handles:
-- **Proper line breaking** for justified text and optimal paragraph layout
-- **International text**: CJK, Arabic, Hebrew, Thai, and mixed LTR/RTL content
-- **Fast measurement**: 300-600x faster than DOM reflow
-- **Zero dependencies**: 15KB library, pure TypeScript
-
 ---
 
-## Features
+## Output Samples
 
-### Core Capabilities
-- **13 element types**: paragraph, heading, table, image, list, code, blockquote, hr, spacer, page-break, rich-paragraph, SVG, table of contents
-- **Professional typography**: hyphenation, justified text, orphan/widow control, multi-column layout
-- **International support**: RTL text (Arabic/Hebrew), CJK line breaking, per-element direction control
-- **Custom fonts**: Embed TTF fonts with subsetting, bundled Inter font included
-- **Document metadata**: Title, author, subject, keywords, creation date
-- **Headers/footers**: Dynamic `{{pageNumber}}` and `{{totalPages}}` tokens
-- **PDF outlines**: Auto-generated bookmarks from heading structure
-- **Watermarks**: Text or image watermarks on every page
-- **Encryption**: Password-protect PDFs with granular permission control
-- **Hyperlinks**: External URLs, email links, internal page anchors
-- **Comments**: Sticky-note annotations on any element
-- **Forms**: Interactive text fields, checkboxes, radio buttons, dropdowns
-- **SVG support**: Embedded SVG graphics with auto-sizing
-- **Document assembly**: Merge multiple PDFs, attach files
-- **Digital signatures**: Visual signature fields, optional PKCS#7 signing
+Real documents generated with pretext-pdf:
 
----
+| 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) |
 
-## Quick Start
+---
 
-### Installation
+## Install
 
 ```bash
 npm install pretext-pdf
 ```
 
-### Basic Example
+Optional peer dependencies:
+```bash
+npm install @cantoo/pdf-lib    # Required for encryption
+npm install @napi-rs/canvas    # Required for SVG support (auto-installed in most setups)
+```
+
+---
+
+## Quick Start
 
 ```typescript
 import { render } from 'pretext-pdf'
+import { writeFileSync } from 'fs'
 
 const pdf = await render({
   pageSize: 'A4',
-  margins: { top: 40, bottom: 40, left: 40, right: 40 },
+  margins: { top: 40, bottom: 40, left: 50, right: 50 },
+  metadata: { title: 'My Invoice', author: 'Acme Corp' },
   content: [
-    {
-      type: 'heading',
-      level: 1,
-      text: 'Invoice #12345',
-    },
-    {
-      type: 'paragraph',
-      text: 'Thank you for your business.',
-      fontSize: 12,
-    },
+    { type: 'heading', level: 1, text: 'Invoice #12345' },
+    { type: 'paragraph', text: 'Thank you for your business.', fontSize: 12 },
     {
       type: 'table',
       columns: [
@@ -96,193 +85,198 @@ const pdf = await render({
       ],
       rows: [
         { Item: 'Professional Services', Qty: '10', Price: '$1,000' },
-        { Item: 'Hosting', Qty: '1', Price: '$500' },
+        { Item: 'Hosting (annual)', Qty: '1', Price: '$500' },
       ],
     },
+    { type: 'paragraph', text: 'Total: $1,500', align: 'right', fontWeight: 700 },
   ],
 })
 
-// Write to file or send to client
-import fs from 'fs'
-fs.writeFileSync('invoice.pdf', pdf)
+writeFileSync('invoice.pdf', pdf)
 ```
 
-### Using the Builder API
+### Builder API
 
 ```typescript
 import { createPdf } from 'pretext-pdf'
 
 const pdf = await createPdf({ pageSize: 'A4' })
   .addHeading('My Report', 1)
-  .addText('This is a fluent, chainable API.')
-  .addTable({
-    columns: [{ name: 'Col A' }, { name: 'Col B' }],
-    rows: [{ 'Col A': 'Value', 'Col B': 'Data' }],
-  })
+  .addText('Fluent chainable API.')
+  .addTable({ columns: [{ name: 'Col A' }, { name: 'Col B' }], rows: [{ 'Col A': 'x', 'Col B': 'y' }] })
   .build()
 ```
 
 ---
 
-## Documentation
+## Agent / AI Integration
 
-### Element Types
+pretext-pdf works great as a tool for AI agents generating PDFs on demand.
 
-| Element | Description |
-|---------|-------------|
-| **paragraph** | Text block with customizable font, size, color, alignment, background |
-| **heading** | H1-H4 with auto-sizing, bold by default, optional bookmark/anchor |
-| **table** | Fixed/proportional columns, colspan support, header repetition on page breaks |
-| **image** | PNG/JPG with auto-detection, sizing, alignment, optional float |
-| **list** | Ordered/unordered, nested, custom markers |
-| **code** | Monospace with background, padding, syntax highlighting |
-| **blockquote** | Left border + background, italic support |
-| **rich-paragraph** | Mixed bold/italic/color/size spans, hyperlinks, annotations |
-| **svg** | Embedded SVG graphics, auto-sizing, multi-page support |
-| **toc** | Auto-generated table of contents with accurate page numbers |
-| **hr** | Horizontal rule with customizable thickness/color |
-| **spacer** | Fixed-height gap |
-| **page-break** | Force new page |
-| **comment** | Sticky-note annotation |
-| **form-field** | Interactive text input, checkbox, radio, dropdown, button |
-| **callout** | Side box / margin note |
-
-### Document Config
+### Quick pattern for LLMs
 
 ```typescript
-interface DocConfig {
-  // Page layout
-  pageSize?: 'A4' | 'Letter' | 'A3' | 'Legal' | 'A5' | 'Tabloid' | [width, height]
-  margins?: { top: number; bottom: number; left: number; right: number }
-  
-  // Typography
-  defaultFont?: string           // Default font family (default: 'Inter')
-  defaultFontSize?: number       // Default size in pt (default: 12)
-  lineHeight?: number            // Line height multiplier (default: 1.5)
-  hyphenation?: { language: 'en-US' | 'de-DE' | ... }
-  
-  // Document metadata
-  title?: string
-  author?: string
-  subject?: string
-  keywords?: string[]
-  creator?: string
-  producer?: string
-  language?: string              // BCP 47 tag (e.g., 'en-US', 'ar')
-  
-  // Features
-  watermark?: WatermarkSpec      // Text or image watermark on every page
-  bookmarks?: { minLevel: 1; maxLevel: 3 }  // Auto-generate outline from headings
-  encryption?: EncryptionSpec    // Password protection with permission control
-  signature?: SignatureSpec      // Digital signature field (+ optional PKCS#7 signing)
-  
-  // Content
-  content: ContentElement[]
-  header?: HeaderFooterSpec      // Repeated header on every page
-  footer?: HeaderFooterSpec      // Repeated footer on every page
-}
-```
-
-### Feature Matrix
-
-| Feature | Phase | Status |
-|---------|-------|--------|
-| Core rendering | 1-4 | ✅ Complete |
-| Rich text / Builder API | 5 | ✅ Complete |
-| Advanced features | 6 | ✅ Complete |
-| Bookmarks / Outline | 7A | ✅ Complete |
-| Watermarks | 7B | ✅ Complete |
-| Hyphenation | 7C | ✅ Complete |
-| Table of contents | 7D | ✅ Complete |
-| SVG support | 7E | ✅ Complete |
-| RTL text support | 7F | ✅ Complete |
-| Encryption | 7G | ✅ Complete |
-| Hyperlinks | 8G | ✅ Complete |
-| Comments/Annotations | 8A | ✅ Complete |
-| Forms | 8B | ✅ Complete |
-| Multi-file assembly | 8C | ✅ Complete |
-| Font subsetting | 8F | ✅ Complete |
-| Inline formatting | 8H | ✅ Complete |
-| Digital signatures | 8E | ✅ Complete |
-| Advanced layout | 8D | ✅ Complete |
-
----
-
-## API Reference
-
-### `render(doc: DocConfig): Promise<Uint8Array>`
-Render a document configuration to PDF bytes.
+import { render } from 'pretext-pdf'
 
-```typescript
+// Every PdfDocument is a plain JSON object — perfect for AI generation
 const pdf = await render({
-  pageSize: 'A4',
-  content: [...]
+  metadata: { title: 'AI-Generated Report' },
+  content: [
+    { type: 'heading', level: 1, text: 'Summary' },
+    { type: 'paragraph', text: 'Generated content here.' },
+    // ... AI fills this array
+  ]
 })
-// pdf is a Uint8Array — write to file or send to client
 ```
 
-### Builder API: `createPdf(options) → ChainableBuilder`
+### Key facts for AI agents
 
-```typescript
-const pdf = await createPdf({ pageSize: 'A4', defaultFontSize: 12 })
-  .addHeading('Title', 1)
-  .addText('Paragraph text')
-  .addTable({ columns: [...], rows: [...] })
-  .addImage(imageBytes, { width: 200 })
-  .addPageBreak()
-  .build()
-```
+- `content` is an array of typed elements — each has a `type` field
+- All fields are optional except `type` and element-specific required fields (e.g. `text`, `level`)
+- Errors are typed: `err.code` tells you exactly what went wrong
+- `render()` is fully async, safe to `await` in any context
+- Works in Node.js 18+ and modern browsers (with `@napi-rs/canvas` for SVG)
 
-### `assemble(parts): Promise<Uint8Array>`
-Merge multiple PDFs into a single document.
+### Element type reference (quick)
 
-```typescript
-const merged = await assemble([
-  { doc: docConfig1 },
-  { pdf: existingPdfBytes },
-  { doc: docConfig2 },
-])
+```
+paragraph    heading(1-4)   spacer       hr           page-break
+table        image          svg          list         code
+blockquote   rich-paragraph callout      comment      form-field
+toc
 ```
 
-### `merge(pdfs): Promise<Uint8Array>`
-Convenience function to merge pre-rendered PDFs.
+---
 
-```typescript
-const combined = await merge([pdf1, pdf2, pdf3])
-```
+## Features
+
+### Element Types
+
+| Element | What it does |
+|---------|-------------|
+| `paragraph` | Text block — font, size, color, align, background, letterSpacing, smallCaps |
+| `heading` | H1–H4 with bookmarks, URL links, internal anchors |
+| `table` | Fixed/proportional columns, colspan, repeating headers across page breaks |
+| `image` | PNG/JPG/WebP with sizing, alignment, auto-format detection |
+| `list` | Ordered/unordered, nested, custom markers |
+| `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) |
+| `comment` | PDF sticky-note annotation (visible in Acrobat/Preview sidebar) |
+| `hr` | Horizontal rule |
+| `spacer` | Fixed-height gap |
+| `page-break` | Force new page |
+
+### Document Features
+
+| Feature | Config key | Notes |
+|---------|-----------|-------|
+| Watermarks | `doc.watermark` | Text or image, opacity, rotation |
+| Encryption | `doc.encryption` | Password + granular permissions |
+| 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}}` tokens |
+| Metadata | `doc.metadata` | Title, author, subject, keywords, `language` (PDF /Lang), `producer` |
+
+### Phase 8 Features
+
+| Feature | API |
+|---------|-----|
+| **Hyperlinks** | `paragraph.url`, `heading.url`, `heading.anchor`, `span.href` |
+| **Inline formatting** | `span.verticalAlign: 'superscript'\|'subscript'`, `paragraph.letterSpacing`, `heading.smallCaps` |
+| **Sticky notes** | `{ type: 'comment', contents: '...' }`, `paragraph.annotation` |
+| **Document assembly** | `merge(pdfs)`, `assemble(parts)` |
+| **Interactive forms** | `{ type: 'form-field', fieldType: 'text'\|'checkbox'\|'radio'\|'dropdown'\|'button' }`, `doc.flattenForms` |
+| **Signature placeholder** | `doc.signature: { signerName, reason, location, x, y, page }` |
+| **Callout boxes** | `{ type: 'callout', content, style: 'info'\|'warning'\|'tip'\|'note', title }` |
 
 ---
 
 ## Examples
 
-Phase 7 examples are in the `examples/` directory and can be run via npm scripts:
+Run working examples from the `examples/` directory:
 
 ```bash
-npm run example:watermark      # Watermarks
-npm run example:bookmarks      # Bookmarks & outline
-npm run example:toc            # Table of contents
-npm run example:rtl            # RTL text (Arabic/Hebrew)
+# Phase 7 examples
+npm run example                # Basic 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:forms          # Interactive form fields (text, checkbox, radio, dropdown)
+npm run example:callout        # Callout boxes (info, warning, tip, note presets)
 ```
 
-**Phase 8 examples** (hyperlinks, forms, document assembly, annotations, fonts, inline formatting, digital signatures) coming soon.
+All examples write output to `output/*.pdf`.
 
 ---
 
-## Performance
+## API Reference
+
+### `render(doc): Promise<Uint8Array>`
+
+```typescript
+import { render } from 'pretext-pdf'
 
-pretext-pdf is **significantly faster** than Puppeteer for high-volume PDF generation:
+const pdf = await render({
+  pageSize: 'A4',          // 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal' | [w, h]
+  margins: { top: 72, bottom: 72, left: 72, right: 72 },
+  defaultFont: 'Inter',    // Inter 400 bundled; load others via doc.fonts
+  defaultFontSize: 12,
+  metadata: {
+    title: 'Document Title',
+    author: 'Author Name',
+    subject: 'Description',
+    keywords: ['pdf', 'report'],
+  },
+  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' },
+  content: [ /* ContentElement[] */ ],
+})
+```
+
+### `merge(pdfs): Promise<Uint8Array>`
 
-- **Single document**: 50-200ms (depends on content complexity)
-- **Batch (100 documents)**: ~5-20ms per document on modern hardware
-- **Memory**: <10MB per document (Puppeteer: ~50-100MB per instance)
-- **Bundle size**: 15KB engine + pdf-lib dependencies (~200KB gzipped)
+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:
+
+```typescript
+import { assemble } from 'pretext-pdf'
+
+const report = await assemble([
+  { pdf: existingCoverPdf },
+  { doc: { content: [...] } },   // rendered fresh
+  { pdf: standardTermsPdf },
+])
+```
 
 ---
 
 ## Error Handling
 
-All errors throw a `PretextPdfError` with a specific code:
+Every error throws `PretextPdfError` with a typed code:
 
 ```typescript
 import { render, PretextPdfError } from 'pretext-pdf'
@@ -291,112 +285,171 @@ try {
   const pdf = await render(config)
 } catch (err) {
   if (err instanceof PretextPdfError) {
-    console.error(err.code)  // e.g., 'FONT_LOAD_FAILED', 'IMAGE_TOO_TALL'
-    console.error(err.message)
+    switch (err.code) {
+      case 'VALIDATION_ERROR':   // Invalid config
+      case 'FONT_LOAD_FAILED':   // Font file not found
+      case 'IMAGE_TOO_TALL':     // Image doesn't fit on page
+      case 'ENCRYPTION_NOT_AVAILABLE':  // @cantoo/pdf-lib not installed
+      case 'ASSEMBLY_EMPTY':     // merge/assemble called with empty array
+      // ... see CHANGELOG.md for full list
+    }
   }
 }
 ```
 
-See [CHANGELOG.md](CHANGELOG.md) for all error codes.
-
 ---
 
-## Comparison with Alternatives
+## Troubleshooting
 
-### vs. pdfmake
-- ✅ Better typography (kerning, ligatures, proper line breaking)
-- ✅ International support (CJK, Arabic, Hebrew)
-- ✅ Smaller bundle (~15KB vs ~400KB)
-- ❌ Fewer built-in features (pdfmake has table styling, QR codes)
+### Hyphenation language not found
 
-### vs. Puppeteer
-- ✅ 100x faster for bulk PDF generation
-- ✅ 40x smaller memory footprint
-- ✅ No browser installation required
-- ❌ Can't render arbitrary HTML/CSS (pretext-pdf is declarative)
+```
+UNSUPPORTED_LANGUAGE: Language 'en-US' not supported
+```
 
-### vs. Typst
-- ✅ JavaScript ecosystem (can use npm packages)
-- ✅ Faster compilation
-- ❌ Typst has more advanced layout features (floats, complex positioning)
+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' }
+```
+
+### Encryption requires optional dependency
+
+Install `@cantoo/pdf-lib` separately before using `doc.encryption`:
+
+```bash
+npm install @cantoo/pdf-lib
+```
+
+### SVG rendering requires optional dependency
+
+Install `@napi-rs/canvas` for SVG support:
+
+```bash
+npm install @napi-rs/canvas
+```
 
-## Browser Support
+### PDF is blank or too small
 
-pretext-pdf is **Node.js only**. It requires a Canvas polyfill for text measurement.
-The library automatically installs `@napi-rs/canvas` (included) for server-side rendering.
+Check margins — if left+right margins exceed page width, content width becomes negative:
 
-For browser usage, see the [Future Roadmap](#future-roadmap).
+```typescript
+// For narrow pages, reduce margins:
+margins: { top: 36, bottom: 36, left: 36, right: 36 }
+```
+
+### Form fields not interactive after flattenForms
+
+`flattenForms: true` bakes fields into static content — by design. Remove it to keep interactive.
 
 ---
 
 ## Test Coverage
 
-All phases have comprehensive test coverage:
+146 tests across all phases:
 
 ```bash
-npm test                  # Run all 75+ tests
-npm run test:unit        # Unit tests (pure pagination logic)
-npm run test:visual      # Visual regression tests (pixel-perfect comparison)
+npm test              # All 146 tests
+npm run test:unit     # Validation, builder, rich-text unit tests
+npm run test:e2e      # End-to-end render tests
+npm run test:phase-7  # Phase 7A-7G feature tests
+npm run test:phase-8  # Phase 8A-8H feature tests
 ```
 
-Tests include:
-- Unit tests for validation, pagination, text measurement
-- End-to-end tests for complete document rendering
-- Visual regression tests with pixel-perfect comparison (pixelmatch)
-- Feature-specific tests for each phase (Phase 7A-7G, 8A-8H)
+---
+
+## Custom Fonts
+
+```typescript
+const pdf = await render({
+  fonts: [
+    { family: 'Roboto', weight: 400, src: '/path/to/Roboto-Regular.ttf' },
+    { family: 'Roboto', weight: 700, src: '/path/to/Roboto-Bold.ttf' },
+    { family: 'Roboto', style: 'italic', src: '/path/to/Roboto-Italic.ttf' },
+  ],
+  defaultFont: 'Roboto',
+  content: [
+    { type: 'paragraph', text: 'Uses Roboto font' },
+    { type: 'paragraph', text: 'Bold text', fontWeight: 700 },
+  ],
+})
+```
 
 ---
 
-## Contributing
+## Rich Text
 
-Contributions welcome! Please:
-1. Write tests first (TDD approach)
-2. Ensure 80%+ code coverage
-3. Run `npm run build && npm test` before submitting PR
-4. Update [CHANGELOG.md](CHANGELOG.md)
+```typescript
+{
+  type: 'rich-paragraph',
+  fontSize: 13,
+  spans: [
+    { text: 'Normal ' },
+    { text: 'bold', fontWeight: 700 },
+    { text: ' and ', fontStyle: 'italic' },
+    { text: 'colored', color: '#e63946' },
+    { text: ' and ' },
+    { text: 'linked', href: 'https://example.com', underline: true, color: '#0070f3' },
+    { text: '. Also: E=mc' },
+    { text: '2', verticalAlign: 'superscript' },
+    { text: ' and H' },
+    { text: '2', verticalAlign: 'subscript' },
+    { text: 'O.' },
+  ],
+}
+```
 
 ---
 
 ## Roadmap
 
-### Near-term (Phase 8)
-- ✅ All Phase 8 features (hyperlinks, forms, annotations, assembly, signatures)
+| Phase | Feature | Status |
+|-------|---------|--------|
+| 1–4 | Core engine, pagination, typography | ✅ |
+| 5 | Rich text / builder API | ✅ |
+| 6 | Headers/footers, columns, decoration | ✅ |
+| 7A | PDF Bookmarks / Outline | ✅ |
+| 7B | Watermarks | ✅ |
+| 7C | Hyphenation | ✅ |
+| 7D | Table of Contents | ✅ |
+| 7E | SVG support | ✅ |
+| 7F | RTL text (Arabic/Hebrew) | ✅ |
+| 7G | Encryption | ✅ |
+| 8A | Sticky note annotations | ✅ |
+| 8B | Interactive forms (text/checkbox/radio/dropdown/button) | ✅ |
+| 8C | Document assembly (merge + assemble) | ✅ |
+| 8D | Callout boxes (info/warning/tip/note) | ✅ |
+| 8E | Signature placeholder | ✅ |
+| 8F | Document metadata (language, producer) | ✅ |
+| 8G | Hyperlinks | ✅ |
+| 8H | Inline formatting (super/subscript, letterSpacing, smallCaps) | ✅ |
+| 9A | Digital signatures (cryptographic, PKCS#7) | 🔜 |
+| 9B | Image floats (text flowing around images) | 🔜 |
+| 9C | Font subsetting pre-computation | 🔜 |
+
+---
+
+## Contributing
 
-### Future (Phase 9+)
-- Justified text alignment (currently left/right/center only)
-- Enhanced text decorations (underline color, underline style)
-- Font subsetting optimization (reduce file size for limited character sets)
-- Browser compatibility (via WASM)
-- PDF/A compliance (archival format)
-- Accessibility tags (tagged PDF for screen readers)
+See [CONTRIBUTING.md](CONTRIBUTING.md). TDD approach — write tests first.
 
 ---
 
 ## License
 
-[MIT](LICENSE) — Use freely in commercial and personal projects.
+[MIT](LICENSE)
 
 ---
 
 ## Credits
 
-Built by [Himanshu Jain](https://github.com/Himanshu-Jain-32) on top of:
+Built by [Himanshu Jain](https://github.com/Himaan1998Y) on top of:
 - **[pretext](https://github.com/chenglou/pretext)** — Text layout engine (Cheng Lou)
 - **[pdf-lib](https://github.com/Hopding/pdf-lib)** — PDF manipulation
-- **[fontkit](https://github.com/foliojs/fontkit)** — Font parsing & subsetting
-- **[@napi-rs/canvas](https://github.com/napi-rs/canvas)** — Server-side Canvas for Node.js
-
----
-
-## Questions?
-
-- 📖 Read the [CHANGELOG.md](CHANGELOG.md) for all features and error codes
-- 🔍 Check the `examples/` directory for working code samples
-- 🐛 Report issues on [GitHub](https://github.com/Himanshu-Jain-32/pretext-pdf/issues)
-- 💬 Discussions & feature requests welcome
-
----
+- **[@napi-rs/canvas](https://github.com/napi-rs/canvas)** — Server-side Canvas API for Node.js
 
-**Happy PDF generating!** 🎉
+Questions? [Open an issue](https://github.com/Himaan1998Y/pretext-pdf/issues)