docs: add Fumadocs documentation site and content

Author: Mythie

.agents/plans/036-documentation.md

@@ -1,33 +1,170 @@
-# @libpdf/core
+# LibPDF
 
-A modern PDF library for TypeScript — parsing and generation.
+A modern PDF library for TypeScript. Parse, modify, and generate PDFs with a clean, intuitive API.
 
-## Why?
+> **Beta Software**: LibPDF is under active development. APIs may change between minor versions. Not yet recommended for production use.
 
-The JavaScript ecosystem's PDF landscape is fragmented:
-- **pdf.js** (Mozilla) - excellent parsing/rendering, but focused on browser viewing, not manipulation
-- **pdf-lib** - great for generation and basic manipulation, but parsing is limited
-- **pdfkit** - generation only, no parsing
+## Why LibPDF?
 
-There's no single, comprehensive library that handles both robust parsing *and* generation with a clean, modern API.
+LibPDF was born from frustration. At [Documenso](https://documenso.com), we found ourselves wrestling with the JavaScript PDF ecosystem:
 
-**@libpdf/core** aims to fill that gap.
+- **PDF.js** is excellent for rendering, but it's read-only
+- **pdf-lib** has a great API, but chokes on slightly malformed documents
+- **pdfkit** only generates, no parsing at all
 
-## Goals
+We kept adding workarounds. A patch here for a malformed xref table. A hack there for an encrypted document. Eventually, we decided to build what we actually needed:
 
-- **Full PDF parsing** - extract text, images, metadata, structure
-- **Full PDF generation** - create documents from scratch
-- **PDF manipulation** - modify existing documents
-- **Modern TypeScript** - strong typing, tree-shakeable, no legacy baggage
-- **Runtime flexible** - Node.js, Bun, and browsers
+- **Lenient like PDFBox and PDF.js**: opens documents other libraries reject
+- **Intuitive like pdf-lib**: clean, TypeScript-first API
+- **Complete**: encryption, digital signatures, incremental saves, form filling
 
-## Known Limitations
+## Features
 
-- **Predefined CJK CMaps**: Only Identity-H and Identity-V CMaps are supported. Legacy CJK PDFs using predefined CMaps (UniGB-UCS2-H, UniJIS-UCS2-H, etc.) without ToUnicode maps may not extract text correctly. Modern PDFs include ToUnicode maps which work correctly.
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Parse any PDF | Yes | Graceful fallback for malformed documents |
+| Create PDFs | Yes | From scratch or modify existing |
+| Encryption | Yes | RC4, AES-128, AES-256 (R2-R6) |
+| Digital Signatures | Yes | PAdES B-B, B-T, B-LT, B-LTA |
+| Form Filling | Yes | Text, checkbox, radio, dropdown, signature |
+| Form Flattening | Yes | Bake fields into page content |
+| Merge & Split | Yes | Combine or extract pages |
+| Attachments | Yes | Embed and extract files |
+| Text Extraction | Yes | With position information |
+| Font Embedding | Yes | TTF/OpenType with subsetting |
+| Images | Yes | JPEG, PNG (with alpha) |
+| Incremental Saves | Yes | Append changes, preserve signatures |
 
-## Development
+## Installation
 
 ```bash
+npm install @libpdf/core
+# or
+bun add @libpdf/core
+```
+
+## Quick Start
+
+### Parse an existing PDF
+
+```typescript
+import { PDF } from "@libpdf/core";
+
+const pdf = await PDF.load(bytes);
+const pages = await pdf.getPages();
+
+console.log(`${pages.length} pages`);
+```
+
+### Open an encrypted PDF
+
+```typescript
+const pdf = await PDF.load(bytes, { credentials: "password" });
+```
+
+### Fill a form
+
+```typescript
+const pdf = await PDF.load(bytes);
+const form = await pdf.getForm();
+
+form.fill({
+  name: "Jane Doe",
+  email: "jane@example.com",
+  agreed: true,
+});
+
+const filled = await pdf.save();
+```
+
+### Sign a document
+
+```typescript
+import { PDF, P12Signer } from "@libpdf/core";
+
+const pdf = await PDF.load(bytes);
+const signer = await P12Signer.create(p12Bytes, "password");
+
+const signed = await pdf.sign({
+  signer,
+  reason: "I approve this document",
+});
+```
+
+### Merge PDFs
+
+```typescript
+const merged = await PDF.merge([pdf1Bytes, pdf2Bytes, pdf3Bytes]);
+```
+
+### Draw on a page
+
+```typescript
+import { PDF, rgb } from "@libpdf/core";
+
+const pdf = PDF.create();
+const page = pdf.addPage({ size: "letter" });
+
+page.drawText("Hello, World!", {
+  x: 50,
+  y: 700,
+  fontSize: 24,
+  color: rgb(0, 0, 0),
+});
+
+page.drawRectangle({
+  x: 50,
+  y: 600,
+  width: 200,
+  height: 100,
+  color: rgb(0.9, 0.9, 0.9),
+  borderColor: rgb(0, 0, 0),
+  borderWidth: 1,
+});
+
+const output = await pdf.save();
+```
+
+## Runtime Support
+
+LibPDF runs everywhere:
+
+- **Node.js** 18+
+- **Bun**
+- **Browsers** (modern, with Web Crypto)
+
+## Philosophy
+
+### Be lenient
+
+Real-world PDFs are messy. Export a document through three different tools and you'll get three slightly different interpretations of the spec. LibPDF prioritizes *opening your document* over strict compliance. When standard parsing fails, we fall back to brute-force recovery, scanning the entire file to rebuild the structure.
+
+### Two API layers
+
+- **High-level**: `PDF`, `PDFPage`, `PDFForm` for common tasks
+- **Low-level**: `PdfDict`, `PdfArray`, `PdfStream` for full control
+
+## Documentation
+
+Full documentation at [libpdf.dev](https://libpdf.dev)
+
+## Sponsors
+
+LibPDF is developed by [Documenso](https://documenso.com), the open-source DocuSign alternative.
+
+<a href="https://documenso.com">
+  <img src="apps/docs/public/sponsors/documenso.png" alt="Documenso" height="24">
+</a>
+
+## Contributing
+
+We welcome contributions! See our [contributing guide](CONTRIBUTING.md) for details.
+
+```bash
+# Clone the repo
+git clone https://github.com/libpdf/core.git
+cd libpdf
+
 # Install dependencies
 bun install
 
@@ -36,19 +173,12 @@ bun run test
 
 # Type check
 bun run typecheck
-
-# Lint and format
-bun run lint:fix
 ```
 
-## Reference Libraries
+## License
 
-This project cross-references these excellent PDF libraries:
+[MIT](LICENSE)
 
-- [Mozilla pdf.js](https://github.com/mozilla/pdf.js) - `checkouts/pdfjs`
-- [pdf-lib](https://github.com/Hopding/pdf-lib) - `checkouts/pdf-lib`
-- [Apache PDFBox](https://github.com/apache/pdfbox) - `checkouts/pdfbox`
+The `src/fontbox/` directory is licensed under [Apache-2.0](src/fontbox/LICENSE) as it is derived from [Apache PDFBox](https://pdfbox.apache.org/).
 
-## License
 
-MIT

README.md

@@ -0,0 +1,26 @@
+# deps
+/node_modules
+
+# generated content
+.source
+
+# test & build
+/coverage
+/.next/
+/out/
+/build
+*.tsbuildinfo
+
+# misc
+.DS_Store
+*.pem
+/.pnp
+.pnp.js
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# others
+.env*.local
+.vercel
+next-env.d.ts

apps/docs/.gitignore

@@ -0,0 +1,23 @@
+# @libpdf/core Documentation
+
+This is the documentation site for @libpdf/core, built with [Fumadocs](https://fumadocs.dev) and [Next.js](https://nextjs.org).
+
+## Structure
+
+- `content/docs/` - Documentation content in MDX format
+- `app/docs/` - Documentation layout and pages
+- `app/(home)/` - Landing page
+
+## Development
+
+```bash
+bun dev
+```
+
+Open http://localhost:3000 to view the docs.
+
+## Building
+
+```bash
+bun run build
+```

apps/docs/README.md

@@ -0,0 +1,28 @@
+'use client';
+
+import { useState } from 'react';
+import { Copy, Check } from 'lucide-react';
+
+export function CopyButton({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText(text);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  return (
+    <button
+      onClick={handleCopy}
+      className="p-1.5 rounded-md hover:bg-muted transition-colors text-muted-foreground hover:text-foreground"
+      aria-label="Copy to clipboard"
+    >
+      {copied ? (
+        <Check className="w-4 h-4 text-green-500" />
+      ) : (
+        <Copy className="w-4 h-4" />
+      )}
+    </button>
+  );
+}

apps/docs/app/(home)/copy-button.tsx

@@ -0,0 +1,22 @@
+import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import { baseOptions } from '@/lib/layout.shared';
+
+export default function Layout({ children }: LayoutProps<'/'>) {
+  return <HomeLayout {...baseOptions()}
+  nav={{  
+    title: <div>LibPDF <span className="text-xs text-muted-foreground font-normal">by Documenso</span></div> 
+  }}
+  links={[
+    {
+      type: "main",
+      text: 'Docs',
+      url: '/docs',
+    },
+    {
+      type: "main",
+      text: 'API Reference',
+      url: '/docs/api',
+    },
+  ]}
+  >{children}</HomeLayout>;
+}