@signiphi/pdf-signer 0.1.1

package/README.md

@@ -0,0 +1,1093 @@
+# @signiphi/pdf-signer
+
+Flexible React components for PDF viewing, form filling, and signature capture. Built with React, TypeScript, and PDF.js.
+
+## Features
+
+- 📄 **PDF Viewing** - Render PDFs with PDF.js viewer
+- ✍️ **Signature Capture** - Draw or upload signatures
+- 📝 **Form Filling** - Fill PDF form fields
+- 🎨 **Flexible Styling** - Use headless components or pre-styled components
+- 📱 **Responsive** - Works on desktop and mobile devices
+- 🔧 **TypeScript** - Fully typed API
+- 🌳 **Tree-shakeable** - Import only what you need
+- ⚡ **Performance Optimized** - Lazy loading and bundle size optimization
+- 📊 **Performance Monitoring** - Built-in performance tracking utilities
+
+## Installation
+
+```bash
+npm install @signiphi/pdf-signer
+# or
+pnpm add @signiphi/pdf-signer
+# or
+yarn add @signiphi/pdf-signer
+```
+
+### Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```bash
+npm install react react-dom @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-select @radix-ui/react-checkbox @radix-ui/react-radio-group @radix-ui/react-tabs lucide-react
+```
+
+If using styled components, you'll also need Tailwind CSS:
+
+```bash
+npm install -D tailwindcss
+```
+
+### PDF.js Setup
+
+**The package works out of the box!** PDF.js viewer files are automatically copied to your `public/pdfjs/` directory when you install the package.
+
+#### Automatic Setup (Default)
+
+After installation, PDF.js viewer files are automatically set up:
+
+```bash
+npm install @signiphi/pdf-signer
+# PDF.js files automatically copied to public/pdfjs/
+```
+
+**What happens automatically:**
+- ✅ Viewer files copied to `public/pdfjs/` via postinstall script
+- ✅ Worker loaded from `node_modules` (bundled by your build tool)
+- ✅ No manual configuration needed
+- ✅ Works offline
+- ✅ No CORS issues
+
+**Default configuration:**
+```typescript
+{
+  viewerBasePath: '/pdfjs',  // Viewer files in public/pdfjs/
+  workerSrc: 'node_modules/pdfjs-dist/build/pdf.worker.mjs'  // Worker from node_modules
+}
+```
+
+#### Manual Setup (If Postinstall Fails)
+
+If the automatic setup doesn't work (e.g., in some CI/CD environments or local file installations), run:
+
+```bash
+npx signiphi-setup
+```
+
+**Note for local installations:** When installing from a local directory using `file:` protocol (e.g., `npm install file:../pdf-signer`), npm may not run the postinstall script automatically. You must run `npx signiphi-setup` manually after installation. See [INSTALLING_LOCALLY.md](./INSTALLING_LOCALLY.md) for details.
+
+Or with a custom directory:
+
+```bash
+npx signiphi-setup public/my-custom-path
+npx signiphi-setup --force  # Force reinstall
+```
+
+## Framework Compatibility
+
+### ✅ Supported Frameworks
+
+This package works with all modern React frameworks:
+- ✅ **Vite** - Works out of the box
+- ✅ **Create React App (CRA)** - Works out of the box
+- ✅ **Next.js** - Requires client-side component (see below)
+- ✅ **Remix** - Use with `ClientOnly` wrapper
+- ✅ **Gatsby** - Works out of the box
+- ✅ **Any React 18+ project**
+
+### Next.js Usage
+
+This package uses browser APIs (`window`, `iframe`, `document`) and **must run client-side only**.
+
+#### App Router (Next.js 13+)
+
+Add `'use client'` directive to components using the PDF viewer:
+
+```tsx
+'use client';
+
+import { PdfViewerStyled } from '@signiphi/pdf-signer';
+import '@signiphi/pdf-signer/styles';
+
+export default function PdfPage() {
+  return (
+    <PdfViewerStyled
+      pdfUrl="/document.pdf"
+      onLoad={() => console.log('PDF loaded')}
+    />
+  );
+}
+```
+
+#### Pages Router (Next.js 12 and below)
+
+Use dynamic import with `ssr: false`:
+
+```tsx
+import dynamic from 'next/dynamic';
+
+const PdfViewerStyled = dynamic(
+  () => import('@signiphi/pdf-signer').then(mod => mod.PdfViewerStyled),
+  { ssr: false }
+);
+
+export default function PdfPage() {
+  return <PdfViewerStyled pdfUrl="/document.pdf" />;
+}
+```
+
+#### Next.js Configuration (Optional)
+
+For automatic PDF.js file copying during build:
+
+```javascript
+// next.config.js
+const { withSigniphiPdfJs } = require('@signiphi/pdf-signer/next');
+
+module.exports = withSigniphiPdfJs({
+  // your next.js config
+});
+```
+
+### Framework Plugins (Optional)
+
+For additional build-time reliability:
+
+**Vite:**
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { signiphiPdfJs } from '@signiphi/pdf-signer/vite';
+
+export default defineConfig({
+  plugins: [signiphiPdfJs()],
+});
+```
+
+**Next.js:**
+```javascript
+// next.config.js
+const { withSigniphiPdfJs } = require('@signiphi/pdf-signer/next');
+
+module.exports = withSigniphiPdfJs({
+  // your next.js config
+});
+```
+
+#### Custom Configuration (Advanced)
+
+If you need to use a different path:
+
+```typescript
+import { setPdfJsConfig } from '@signiphi/pdf-signer';
+
+// Custom path
+setPdfJsConfig({ 
+  viewerBasePath: '/custom/path/pdfjs',
+  workerSrc: '/custom/path/pdfjs/build/pdf.worker.mjs'
+});
+```
+
+**Troubleshooting:**
+
+If PDF.js files weren't copied automatically:
+
+1. **Check if postinstall ran:**
+   ```bash
+   # Look for this message during install:
+   # ✓ @signiphi/pdf-signer: PDF.js files copied to /path/to/public/pdfjs
+   ```
+
+2. **Verify pdfjs-dist is installed:**
+   ```bash
+   npm list pdfjs-dist
+   # Should show: pdfjs-dist@5.3.93
+   ```
+
+3. **Run manual setup:**
+   ```bash
+   npx signiphi-setup
+   ```
+
+4. **Check that `public/pdfjs/` directory exists:**
+   ```bash
+   ls public/pdfjs/
+   # Should show: build/, web/, .version
+   ```
+
+5. **If using CI/CD with `--ignore-scripts`:**
+   ```bash
+   # Postinstall won't run, use manual setup:
+   npx signiphi-setup
+   ```
+
+**Note:** CDN loading is not recommended due to CORS issues. The package uses local files by default.
+
+## Quick Start
+
+### Using Styled Components (Easiest)
+
+```tsx
+import { PdfViewer, SignatureCanvas } from '@signiphi/pdf-signer';
+import { useRef } from 'react';
+import type { PdfViewerRef, SignatureCanvasRef } from '@signiphi/pdf-signer';
+
+function App() {
+  const pdfViewerRef = useRef<PdfViewerRef>(null);
+  const signatureRef = useRef<SignatureCanvasRef>(null);
+
+  const handleLoadPdf = async () => {
+    await pdfViewerRef.current?.loadPdf('/path/to/document.pdf');
+  };
+
+  const handleSaveSignature = (dataUrl: string) => {
+    console.log('Signature saved:', dataUrl);
+  };
+
+  return (
+    <div>
+      <PdfViewer
+        ref={pdfViewerRef}
+        onLoad={() => console.log('PDF loaded')}
+        onError={(error) => console.error('Error:', error)}
+      />
+      
+      <SignatureCanvas
+        ref={signatureRef}
+        onSignature={handleSaveSignature}
+      />
+    </div>
+  );
+}
+```
+
+### Using Hooks
+
+```tsx
+import { usePdfViewer, useSignatureCapture } from '@signiphi/pdf-signer';
+
+function App() {
+  const {
+    viewerRef,
+    isLoading,
+    error,
+    loadPdf,
+    getFormFieldValues,
+  } = usePdfViewer();
+
+  const {
+    canvasRef,
+    signatureDataUrl,
+    saveSignature,
+    clear,
+  } = useSignatureCapture();
+
+  const handleSubmit = async () => {
+    const formValues = await getFormFieldValues();
+    const signature = saveSignature();
+    
+    console.log('Form values:', formValues);
+    console.log('Signature:', signature);
+  };
+
+  return (
+    <div>
+      <PdfViewer ref={viewerRef} />
+      <SignatureCanvas ref={canvasRef} />
+      <button onClick={handleSubmit}>Submit</button>
+    </div>
+  );
+}
+```
+
+### Using Headless Components (Maximum Flexibility)
+
+```tsx
+import { PdfViewerCore, SignatureCaptureCore } from '@signiphi/pdf-signer/headless';
+import type { PdfViewerRef, SignatureCanvasRef } from '@signiphi/pdf-signer';
+
+function CustomPdfViewer() {
+  const viewerRef = useRef<PdfViewerRef>(null);
+
+  return (
+    <PdfViewerCore
+      ref={viewerRef}
+      onLoad={() => console.log('Loaded')}
+      onError={(err) => console.error(err)}
+    >
+      {({ iframeRef, handleIframeLoad }) => (
+        <div className="my-custom-viewer">
+          <iframe
+            ref={iframeRef}
+            onLoad={handleIframeLoad}
+            className="w-full h-screen"
+          />
+        </div>
+      )}
+    </PdfViewerCore>
+  );
+}
+```
+
+## Error Handling
+
+The package includes comprehensive error handling with custom error classes and an ErrorBoundary component.
+
+### ErrorBoundary Component
+
+Wrap your PDF components in an ErrorBoundary to catch and handle errors gracefully:
+
+```tsx
+import { ErrorBoundary, PdfViewerStyled } from '@signiphi/pdf-signer';
+
+function App() {
+  return (
+    <ErrorBoundary
+      fallback={({ error, resetErrorBoundary }) => (
+        <div>
+          <h2>Something went wrong</h2>
+          <p>{error.message}</p>
+          <button onClick={resetErrorBoundary}>Try Again</button>
+        </div>
+      )}
+      onError={(error, errorInfo) => {
+        // Log to your error tracking service
+        console.error('PDF Error:', error, errorInfo);
+      }}
+    >
+      <PdfViewerStyled pdfUrl="/document.pdf" formFields={fields} />
+    </ErrorBoundary>
+  );
+}
+```
+
+### Custom Error Classes
+
+The package provides specific error types for better error handling:
+
+```typescript
+import {
+  PdfValidationError,
+  PdfProcessingError,
+  FormFieldError,
+  AttachmentValidationError,
+  isPdfValidationError,
+  getErrorMessage,
+} from '@signiphi/pdf-signer/utils';
+
+try {
+  // PDF operations
+  await loadPdf(url);
+} catch (err) {
+  if (isPdfValidationError(err)) {
+    console.error('PDF validation failed:', err.message);
+  } else if (isFormFieldError(err)) {
+    console.error('Field error:', err.fieldName, err.message);
+  } else {
+    console.error('Unknown error:', getErrorMessage(err));
+  }
+}
+```
+
+## Validation
+
+### PDF Validation
+
+Validate PDF files before loading:
+
+```typescript
+import { validatePdfBytes, validatePdfUrl } from '@signiphi/pdf-signer/utils';
+
+// Validate PDF URL format
+const urlResult = validatePdfUrl('/documents/contract.pdf');
+if (!urlResult.valid) {
+  console.error(urlResult.error);
+}
+
+// Validate PDF bytes (after fetching)
+const pdfBytes = await fetch(url).then(r => r.arrayBuffer());
+const bytesResult = validatePdfBytes(new Uint8Array(pdfBytes));
+if (!bytesResult.valid) {
+  console.error(bytesResult.error);
+}
+```
+
+### Form Field Validation
+
+Validate form fields and field values:
+
+```typescript
+import {
+  validateFormField,
+  validateFieldValues,
+  validateSignatures,
+} from '@signiphi/pdf-signer/utils';
+
+// Validate field definition
+const fieldResult = validateFormField({
+  id: 'field1',
+  name: 'firstName',
+  type: FormFieldType.TEXT,
+  label: 'First Name',
+  position: { x: 100, y: 200, width: 150, height: 30, page: 1 },
+  required: true,
+});
+
+if (!fieldResult.valid) {
+  console.error('Field errors:', fieldResult.errors);
+}
+
+// Validate field values
+const valuesResult = validateFieldValues({
+  field1: 'value1',
+  field2: 'value2',
+});
+
+// Validate signatures
+const sigsResult = validateSignatures({
+  sig1: 'data:image/png;base64,...',
+});
+
+if (!sigsResult.valid) {
+  console.error('Signature errors:', sigsResult.errors);
+}
+```
+
+### Attachment Validation
+
+Validate file uploads with custom constraints:
+
+```typescript
+import {
+  validateFile,
+  validateFiles,
+  validateFileOrThrow,
+  formatFileSize,
+  DEFAULT_ATTACHMENT_CONSTRAINTS,
+} from '@signiphi/pdf-signer/utils';
+
+// Validate single file
+const result = validateFile(file, {
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+  maxTotalSize: 50 * 1024 * 1024, // 50MB
+  maxFiles: 10,
+  allowedTypes: ['image/*', 'application/pdf'],
+  allowedExtensions: ['.pdf', '.jpg', '.png'],
+});
+
+if (!result.valid) {
+  result.errors.forEach(error => console.error(error));
+}
+
+// Throw on validation failure
+try {
+  validateFileOrThrow(file, constraints);
+  // File is valid, proceed with upload
+} catch (err) {
+  if (isAttachmentValidationError(err)) {
+    alert(err.message);
+    console.log('File:', err.fileName);
+  }
+}
+
+// Validate multiple files with existing attachments
+const filesResult = validateFiles(newFiles, existingAttachments, constraints);
+```
+
+## TypeScript Support
+
+The package is built with TypeScript and provides full type safety.
+
+### Strict Type Checking
+
+The package is built with strict TypeScript settings enabled:
+- `strict: true`
+- `noImplicitReturns: true`
+- `noUncheckedIndexedAccess: true`
+
+This ensures maximum type safety and helps catch errors at compile time.
+
+### Type Imports
+
+Import types for use in your code:
+
+```typescript
+import type {
+  FormField,
+  FormFieldType,
+  FormFieldPosition,
+  MultiSignerContext,
+  Attachment,
+  AttachmentConstraints,
+  EsignFormField,
+  Signer,
+  SubmissionData,
+} from '@signiphi/pdf-signer/types';
+
+// Define form fields with full type safety
+const fields: FormField[] = [
+  {
+    id: 'field1',
+    name: 'firstName',
+    type: FormFieldType.TEXT,
+    label: 'First Name',
+    position: { x: 100, y: 200, width: 150, height: 30, page: 1 },
+    required: true,
+  }
+];
+
+// Multi-signer context
+const context: MultiSignerContext = {
+  isMultiSigner: true,
+  currentSignerEmail: 'user@example.com',
+  isPrimarySigner: true,
+  isFinalSigner: false,
+};
+```
+
+### Type Guards
+
+Use type guards to safely handle errors:
+
+```typescript
+import {
+  isPdfValidationError,
+  isPdfProcessingError,
+  isFormFieldError,
+  isAttachmentValidationError,
+} from '@signiphi/pdf-signer/utils';
+
+try {
+  // Operations
+} catch (err) {
+  if (isPdfValidationError(err)) {
+    // TypeScript knows err is PdfValidationError here
+    console.error('PDF error:', err.message, err.details);
+  } else if (isFormFieldError(err)) {
+    // TypeScript knows err is FormFieldError here
+    console.error('Field error:', err.fieldName, err.message);
+  }
+}
+```
+
+## API Reference
+
+### Components
+
+#### `<PdfViewer />`
+
+Pre-styled PDF viewer component.
+
+**Props:**
+- `className?: string` - Additional CSS classes
+- `onLoad?: () => void` - Callback when PDF loads
+- `onError?: (error: string) => void` - Callback on error
+
+**Ref Methods:**
+- `loadPdf(url: string): Promise<void>` - Load a PDF from URL
+- `getFormFieldValues(): Promise<Record<string, string>>` - Get form field values
+- `getAllFieldNames(): Promise<string[]>` - Get all field names
+- `saveDocument(): Promise<Uint8Array | null>` - Save modified PDF
+
+#### `<SignatureCanvas />`
+
+Pre-styled signature canvas component.
+
+**Props:**
+- `width?: number` - Canvas width (default: 400)
+- `height?: number` - Canvas height (default: 200)
+- `onSignature?: (dataUrl: string) => void` - Callback when signature is saved
+- `onCancel?: () => void` - Callback when cancelled
+- `title?: string` - Placeholder text
+- `className?: string` - Additional CSS classes
+- `showActions?: boolean` - Show action buttons (default: true)
+
+**Ref Methods:**
+- `clear(): void` - Clear the canvas
+- `getSignatureDataUrl(): string | null` - Get signature as data URL
+- `isEmpty(): boolean` - Check if canvas is empty
+
+### Hooks
+
+#### `usePdfViewer()`
+
+Hook for managing PDF viewer state.
+
+**Returns:**
+```typescript
+{
+  viewerRef: RefObject<PdfViewerRef>;
+  isLoading: boolean;
+  error: string | null;
+  isLoaded: boolean;
+  loadPdf: (url: string) => Promise<void>;
+  handleLoad: () => void;
+  handleError: (error: string) => void;
+  getFormFieldValues: () => Promise<Record<string, string>>;
+  getAllFieldNames: () => Promise<string[]>;
+  saveDocument: () => Promise<Uint8Array | null>;
+}
+```
+
+#### `useFormFields(fields: FormField[])`
+
+Hook for managing form field state and validation.
+
+**Returns:**
+```typescript
+{
+  fieldValues: Record<string, string>;
+  errors: ValidationError[];
+  hasErrors: boolean;
+  updateField: (fieldId: string, value: string) => void;
+  updateMultipleFields: (values: Record<string, string>) => void;
+  validateFields: () => boolean;
+  resetFields: () => void;
+  getFieldValue: (fieldId: string) => string;
+}
+```
+
+#### `useSignatureCapture()`
+
+Hook for managing signature capture state.
+
+**Returns:**
+```typescript
+{
+  canvasRef: RefObject<SignatureCanvasRef>;
+  signatureDataUrl: string | null;
+  uploadedImage: string | null;
+  uploadError: string | null;
+  clear: () => void;
+  saveSignature: () => string | null;
+  isEmpty: () => boolean;
+  handleFileUpload: (file: File) => void;
+  clearUpload: () => void;
+  reset: () => void;
+}
+```
+
+### Configuration API
+
+#### `setPdfJsConfig(config)`
+
+Configure PDF.js paths globally.
+
+```typescript
+import { setPdfJsConfig } from '@signiphi/pdf-signer';
+
+setPdfJsConfig({
+  viewerBasePath: '/pdfjs',  // Path to PDF.js viewer
+  workerSrc: '/pdfjs/build/pdf.worker.mjs'  // Path to worker (optional, auto-calculated)
+});
+```
+
+#### `getPdfJsConfig()`
+
+Get current PDF.js configuration.
+
+```typescript
+import { getPdfJsConfig } from '@signiphi/pdf-signer';
+
+const config = getPdfJsConfig();
+console.log(config.viewerBasePath); // Current viewer path
+```
+
+#### `resetPdfJsConfig()`
+
+Reset configuration to CDN defaults.
+
+```typescript
+import { resetPdfJsConfig } from '@signiphi/pdf-signer';
+
+resetPdfJsConfig(); // Resets to CDN
+```
+
+### Types
+
+```typescript
+import type {
+  FormField,
+  FormFieldType,
+  FormFieldPosition,
+  PdfViewerRef,
+  SignatureCanvasRef,
+  PdfPage,
+  Submission,
+  ValidationError,
+  PdfJsConfig,
+} from '@signiphi/pdf-signer';
+```
+
+## Tailwind Configuration
+
+The package uses **Tailwind CSS v4** with CSS-based configuration.
+
+### Option 1: Using Vite (Recommended)
+
+If using Vite, install the Tailwind Vite plugin:
+
+```bash
+npm install -D @tailwindcss/vite tailwindcss
+```
+
+Update your `vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+### Option 2: Using PostCSS
+
+Install dependencies:
+
+```bash
+npm install -D @tailwindcss/postcss tailwindcss
+```
+
+Create/update `postcss.config.js`:
+
+```js
+module.exports = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+### Import Styles
+
+In your main entry file:
+
+```tsx
+import '@signiphi/pdf-signer/styles';
+```
+
+That's it! Tailwind v4 uses CSS-based configuration, so no `tailwind.config.js` file is needed.
+
+## Design System
+
+The package uses the **DockMaster Design System** for consistent branding and styling.
+
+### Colors
+
+The package uses OKLCH color space with the following palette:
+
+- **Primary Blue**: `#0099CD` - Buttons, links, interactive elements
+- **Light Blue**: `#BDD9E8` - Borders, secondary backgrounds
+- **Dark Blue**: `#161848` - Text, foreground elements
+- **Yellow**: `#FFC844` - Accent color, highlights
+- **Greys**: Various shades for borders, backgrounds, and muted content
+
+**Dark mode** is fully supported with adjusted colors for optimal readability.
+
+### Typography
+
+#### Body Font
+Uses system font stack for optimal performance and native feel.
+
+#### Signature Font
+**Dancing Script** (Google Fonts) is used for signature and initials fields.
+
+✅ **Automatically included** - The font is imported when you import the package styles, no additional setup needed!
+
+### Border Radius
+
+Default radius: `0.625rem` (10px)
+
+### Responsive Design
+
+All components are fully responsive with breakpoints:
+- **Mobile**: < 640px
+- **Tablet**: 640px - 1024px
+- **Desktop**: 1024px+
+
+Components adapt their layout, spacing, and font sizes for optimal viewing on all devices.
+
+### Dark Mode
+
+Enable dark mode by adding the `dark` class to your root element:
+
+```tsx
+<html className="dark">
+  {/* Your app */}
+</html>
+```
+
+Or use a theme provider like `next-themes`:
+
+```tsx
+import { ThemeProvider } from 'next-themes';
+
+function App() {
+  return (
+    <ThemeProvider attribute="class">
+      <SubmissionForm {...props} />
+    </ThemeProvider>
+  );
+}
+```
+
+For more details, see **[DESIGN_SYSTEM.md](./DESIGN_SYSTEM.md)**.
+
+## Examples
+
+See the `examples/demo` directory for a complete working example.
+
+## Multi-Signer Support
+
+The package supports multi-signer workflows where multiple people sign the same document in sequence. Each signer only sees and fills their assigned fields.
+
+### Quick Start
+
+```tsx
+import { SubmissionForm, type Signer } from '@signiphi/pdf-signer';
+
+function DocumentSigningPage() {
+  // Backend provides current signer information
+  const currentSigner: Signer = {
+    id: "1",
+    email: "user@example.com",
+    name: "John Doe",
+    signOrder: 1,  // 1 = primary, 2+ = secondary
+    status: "pending"
+  };
+
+  return (
+    <SubmissionForm
+      pdfUrl="/contract.pdf"
+      // Multi-signer props
+      currentSigner={currentSigner}
+      isMultipleSignature={true}
+      totalSigners={3}
+      // Callback
+      onSubmit={async (data) => {
+        await submitToBackend(data);
+      }}
+    />
+  );
+}
+```
+
+### Key Features
+
+- **Field Filtering**: Each signer only sees fields assigned to them
+- **Partial Flattening**: Each signer flattens only their fields, leaving others editable
+- **Role-Based Visibility**: Primary, secondary, and final signer roles with different field access
+- **PDF Viewer Filtering**: Modified PDF shown to each signer (fields removed), original preserved
+
+### Signer Roles
+
+#### Primary Signer (`signOrder === 1`)
+- Usually the document creator or main party
+- Sees: Own assigned fields + "recipients" group fields
+
+#### Secondary Signer (`signOrder > 1`, not final)
+- Middle signers in the chain
+- Sees: Only their own assigned fields
+
+#### Final Signer (`signOrder === totalSigners`)
+- Last person in the signing chain
+- Sees: Own assigned fields + "signers" group fields + unassigned fields
+
+### Field Assignment Patterns
+
+```typescript
+// Direct assignment to specific signer
+const field = {
+  id: 'buyer_signature',
+  assignedSignerEmail: 'buyer@example.com',
+  // ...
+};
+
+// Recipients group (all primaries)
+const field = {
+  id: 'company_name',
+  assignedSignerEmail: 'recipients',
+  // ...
+};
+
+// Signers group (final signer only)
+const field = {
+  id: 'completion_date',
+  assignedSignerEmail: 'signers',
+  // ...
+};
+```
+
+### Complete Guide
+
+For detailed information including:
+- Visibility rules matrix
+- Backend integration examples
+- Testing strategies
+- Advanced topics
+
+See **[MULTI_SIGNER.md](./MULTI_SIGNER.md)** for the complete guide.
+
+## Testing
+
+The package includes comprehensive test coverage:
+
+### Test Coverage
+
+- **Utility Tests** (~182 tests) - Validation, PDF manipulation, field visibility, error handling
+- **Hook Tests** (~150 tests) - All React hooks with full integration testing
+  - `useSignatures` - Signature state management
+  - `useAttachments` - File attachment handling
+  - `useFormFields` - Form field state and validation
+  - `useMultiSignerContext` - Multi-signer context logic
+  - `useFieldFiltering` - Field visibility filtering
+  - `usePdfViewer` - PDF viewer operations
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run with coverage
+pnpm test:coverage
+
+# Run in watch mode
+pnpm test:watch
+```
+
+### Test Environment
+
+Tests use Vitest with **happy-dom** for React component testing. The test suite includes:
+- Unit tests for utilities and hooks
+- Integration tests for multi-signer workflows
+- Mocked PDF.js and pdf-lib for fast, reliable testing
+- Comprehensive edge case coverage
+
+**Why happy-dom?** We use happy-dom instead of jsdom for better Windows compatibility, faster execution, and lighter memory footprint while maintaining full DOM API support.
+
+## Browser Support
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Mobile browsers with touch support
+
+## Performance & Bundle Size
+
+### Optimized Bundle Sizes
+
+The package is optimized for minimal bundle size impact:
+
+| Entry Point | Raw Size | Gzipped | Use Case |
+|-------------|----------|---------|----------|
+| Main (`@signiphi/pdf-signer`) | 193 KB | 38 KB | Full package |
+| Headless (`/headless`) | 21 KB | 5 KB | Core functionality only |
+| Components (`/components`) | 167 KB | 33 KB | UI components only |
+| Hooks (`/hooks`) | 71 KB | 14 KB | React hooks only |
+| Utils (`/utils`) | 73 KB | 15 KB | Utilities only |
+
+### Lazy Loading
+
+The package uses lazy loading for heavy dependencies to minimize initial bundle size:
+
+```typescript
+// pdf-lib (~150 KB) is only loaded when actually needed
+import { fillPdfWithSignatures } from '@signiphi/pdf-signer';
+
+// pdf-lib loads automatically on first use
+await fillPdfWithSignatures(pdfBytes, signatures, formValues);
+```
+
+**Benefits:**
+- ✅ View-only users never load pdf-lib (~150 KB savings)
+- ✅ Form filling users only pay the cost when needed
+- ✅ Automatic code splitting
+
+### Tree-Shaking
+
+Import only what you need using specific entry points:
+
+```typescript
+// Import just the headless core (no UI)
+import { PdfViewerCore } from '@signiphi/pdf-signer/headless';
+
+// Import just hooks (no components)
+import { usePdfViewer } from '@signiphi/pdf-signer/hooks';
+
+// Import just utilities (no React code)
+import { validatePdfBytes } from '@signiphi/pdf-signer/utils';
+
+// Import just components (no hooks)
+import { SignatureCanvas } from '@signiphi/pdf-signer/components';
+```
+
+### Performance Monitoring
+
+Built-in performance monitoring utilities for tracking critical operations:
+
+```typescript
+import { createPerformanceMonitor } from '@signiphi/pdf-signer';
+
+// Create a monitor
+const monitor = createPerformanceMonitor();
+
+// Track PDF loading
+const endTimer = monitor.startTimer('pdf-load');
+await loadPdf(url);
+endTimer();
+
+// Get metrics
+const metrics = monitor.getMetrics();
+console.log(`PDF load avg: ${metrics['pdf-load'].avg}ms`);
+```
+
+**Track:**
+- PDF loading time
+- Form field updates
+- Signature capture performance
+- Custom operations
+
+### Bundle Analysis
+
+Analyze your bundle size:
+
+```bash
+# Analyze bundle sizes
+pnpm analyze
+
+# Check against budgets
+pnpm analyze:check
+
+# Build and analyze
+pnpm build:analyze
+```
+
+### Production Builds
+
+For production, set `NODE_ENV=production` to enable minification:
+
+```bash
+NODE_ENV=production pnpm build
+```
+
+This reduces bundle size by ~20-30% through minification.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or pull request.
+
+## Documentation
+
+- **[API.md](./API.md)** - Comprehensive API reference for all components, hooks, and utilities
+- **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** - Common issues and solutions
+- **[MULTI_SIGNER.md](./MULTI_SIGNER.md)** - Complete multi-signer implementation guide
+- **[DESIGN_SYSTEM.md](./DESIGN_SYSTEM.md)** - Design system and styling guide
+
+## Support
+
+For issues and questions, please open a GitHub issue or refer to the TROUBLESHOOTING.md guide.
+