@kopjra/pdf-sentinel 1.8.0 → 1.9.1

package/README.md

@@ -1,6 +1,6 @@
 # pdf-sentinel Documentation
 
-A powerful React/Preact library for viewing and interacting with PDF forms. Built on top of [embed-pdf-viewer](https://github.com/embedpdf/embed-pdf-viewer), pdf-sentinel provides a complete solution for rendering PDF documents with form fields, custom toolbars, internationalization, and signature management.
+A powerful React/Preact library for viewing and interacting with PDF forms. Built on top of [embed-pdf-viewer](https://github.com/embedpdf/embed-pdf-viewer), pdf-sentinel provides a complete solution for rendering PDF documents with form fields, custom toolbars, internationalization, annotation management, and signature handling.
 
 <img src="pdf-sentinel.png" alt="logo" height="200"/>
 
@@ -11,7 +11,11 @@ A powerful React/Preact library for viewing and interacting with PDF forms. Buil
 - [Features](#features)
 - [API Reference](#api-reference)
   - [usePdfSentinel Hook](#usepdfsentinel-hook)
+  - [Usage Modes](#usage-modes)
+  - [Return Value](#return-value)
   - [Types](#types)
+  - [Form API](#form-api)
+  - [Annotation API](#annotation-api)
   - [Toolbar Customization](#toolbar-customization)
   - [Internationalization](#internationalization)
 - [Examples](#examples)
@@ -33,6 +37,7 @@ function MyPdfViewer() {
     const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
         pdf: "/path/to/document.pdf",
         name: "My Document",
+        usage: { type: "plain" },
     });
 
     return (
@@ -50,32 +55,22 @@ function MyPdfViewer() {
 
 ### Core Functionality
 
-- 📄 **PDF Viewing** - Render PDF documents with zoom, scroll, and navigation
-- 📋 **Form Fields** - Support for text inputs, checkboxes, radio buttons, and signature fields
-- ✍️ **Form Validation** - Built-in validation with error highlighting and auto-scroll to errors
-- 🎨 **Toolbar** - Customizable toolbar with zoom, page navigation, and download
-- 🌍 **Internationalization** - Multi-language support with custom translation overrides
-- 🔧 **Custom Buttons** - Extend the toolbar with custom buttons in left/center/right areas
-- 📝 **Signatures** - Native conditional signature support with automatic group coloring
-- 🎯 **Responsive** - Adaptive layout that responds to zoom and scroll events
-
-### Toolbar Features
-
-- Zoom in/out and fit-to-width
-- Page navigation and page count display
-- PDF download capability
-- Custom button support with spacers
-- Multi-language tooltips and labels
-
-### Form Features
-
-- Text field rendering with readonly support
-- Checkbox field rendering with custom styling
-- Radio button field rendering with custom styling
-- Signature field rendering with conditional group coloring
-- Form state management
-- Field validation with error styling
-- Initial values and readonly properties
+- 📄 **PDF Viewing** — Render PDF documents with zoom, scroll, and page navigation
+- 📋 **Form Fields** — Support for text inputs, checkboxes, radio buttons, and signature fields
+- ✍️ **Form Validation** — Built-in validation with error highlighting and auto-scroll to first error
+- 🎨 **Toolbar** — Customizable toolbar with zoom, page navigation, undo/redo, and download
+- 🌍 **Internationalization** — Multi-language support (en, it, es, fr, de) with custom overrides
+- 🔧 **Annotations** — Full annotation management (add, edit, remove, select) with multiple field types
+- 📝 **Signatures** — Native conditional signature support with automatic group coloring
+- ↩️ **Undo/Redo** — History plugin support for annotation operations
+- 📱 **Pan Support** — Touch device pan support with automatic detection
+- ⬇️ **PDF Download** — Built-in download capability
+
+### Three Usage Modes
+
+1. **`plain`** — View-only PDF rendering
+2. **`form`** — Interactive form filling with initial values, readonly fields, conditional signatures
+3. **`annotation`** — Freeform annotation placement (email, fullname, phone, date, signature, custom)
 
 ## API Reference
 
@@ -95,74 +90,124 @@ function usePdfSentinel(options: PdfSentinelOptions): PdfSentinelResult
 interface PdfSentinelOptions {
     /** PDF document URL or ArrayBuffer */
     pdf: string | ArrayBuffer;
-    
+
     /** Document name/identifier */
     name: string;
-    
-    /** Initial form field values */
-    initialValues?: InitialValuesType;
-    
+
+    /** Locale code (en, it, es, fr, de) */
+    locale?: LocaleType;
+
+    /** Custom translations for any locale */
+    translations?: Record<string, Record<string, string>>;
+
     /** Hide the default toolbar */
     hideToolbar?: boolean;
-    
+
     /** Callback when document finishes loading */
     onDocumentLoaded?: () => void;
-    
-    /** Locale code (en, it, es, fr, de) */
-    locale?: string;
-    
-    /** Custom translations for any locale */
-    translations?: Record<string, Record<string, string>>;
-    
-    /** Custom toolbar buttons */
-    toolbarButtons?: ToolbarItem[];
-    
-    /** Conditional signature configurations */
+
+    /** Usage mode — determines how the PDF is rendered and interacted with */
+    usage: PlainUsage | FormUsage | AnnotationUsage;
+}
+```
+
+### Usage Modes
+
+#### PlainUsage
+
+View-only rendering with no form or annotation interactivity.
+
+```typescript
+interface PlainUsage {
+    type: "plain";
+}
+```
+
+#### FormUsage
+
+Interactive form filling mode.
+
+```typescript
+interface FormUsage {
+    type: "form";
+    /** Initial form field values keyed by field name */
+    initialValues?: InitialValuesType;
+    /** Conditional signature group configurations */
     conditionalSignatures?: ConditionalSignature[];
+    /** Field names to treat as signature fields */
+    signatureFieldNames?: string[];
 }
 ```
 
-#### Return Value
+#### AnnotationUsage
+
+Freeform annotation placement mode.
+
+```typescript
+interface AnnotationUsage {
+    type: "annotation";
+    /** Initial annotations to place, or "readFromDocument" to read existing ones */
+    initialAnnotations?: AnnotationField[] | "readFromDocument";
+    /** Whether to assign the user's email to created annotations */
+    assignEmailToAnnotations?: boolean;
+    /** Default size for newly created annotations */
+    defaultSize?: { width: number; height: number };
+    /** Default annotation field type for new annotations */
+    defaultType?: AnnotationFieldType;
+    /** Whether to auto-select annotations on creation */
+    selectOnCreation?: boolean;
+}
+```
+
+### Return Value
 
 ```typescript
 interface PdfSentinelResult {
     /** Container component that wraps the PDF viewer and toolbar */
-    PdfSentinelContainer: React.ComponentType<{children: React.ReactNode}>;
-    
-    /** Toolbar component - should be rendered inside PdfSentinelContainer */
-    Toolbar: React.ComponentType<{}>;
-    
-    /** Main PDF viewer component - should be rendered inside PdfSentinelContainer */
+    PdfSentinelContainer: React.ComponentType<{ children: React.ReactNode }>;
+
+    /** Toolbar component — accepts optional toolbar customization props */
+    Toolbar: React.ComponentType<{
+        toolbarButtons?: ToolbarItem[];
+        removeButtons?: DefaultButtons[];
+    }>;
+
+    /** Main PDF viewer component */
     PdfSentinel: React.ComponentType<{}>;
-    
-    /** Current form state */
-    form: UsePdfFormsResult | null;
-    
+
+    /** API access for form and annotation operations */
+    api: {
+        form: UsePdfFormsResult | null;
+        annotation: AnnotationsApi | null;
+    };
+
     /** Current page number (1-indexed) */
     currentPage: number | null;
-    
+
     /** Total number of pages */
     totalPages: number | null;
-    
+
     /** Whether PDF is loading */
     loadingPdf: boolean;
-    
+
     /** Whether there was a loading error */
     loadingError: boolean;
-    
+
+    /** The initialized PDF document buffer (available after load) */
+    initializedDocument: ArrayBuffer | null;
+
     /** PDF engine instance */
     engine: PdfEngine<Blob> | null;
-    
+
     /** Whether PDF has been closed */
     closedPdf: boolean;
-    
-    /** Helper methods */
+
+    /** Helper methods for controlling the viewer programmatically */
     helpers: {
         zoomIn: () => void;
         zoomOut: () => void;
         resetZoom: () => void;
         scrollToPage: (pageNumber: number) => void;
-        scrollToPosition: (position: { x: number; y: number; behavior?: ScrollBehavior }) => void;
         download: () => void;
     };
 }
@@ -174,7 +219,7 @@ interface PdfSentinelResult {
 
 ```typescript
 type InitialValuesType = Record<string, {
-    value: string | boolean;
+    value?: string | boolean;
     readonly?: boolean;
 }>;
 ```
@@ -199,7 +244,7 @@ interface ConditionalSignature {
 }
 ```
 
-Defines a group of signature fields that are conditional on the same value.
+Defines a group of signature fields that are conditional on the same clause.
 
 **Example:**
 ```typescript
@@ -209,23 +254,76 @@ const conditionalSignatures: ConditionalSignature[] = [
 ];
 ```
 
-#### UsePdfFormsResult
+#### AnnotationFieldType
+
+```typescript
+enum AnnotationFieldType {
+    EMAIL = "EMAIL",
+    FULLNAME = "FULLNAME",
+    PHONE = "PHONE",
+    DATE = "DATE",
+    SIGNATURE = "SIGNATURE",
+    CONDITIONAL_SIGNATURE = "CONDITIONAL_SIGNATURE",
+    CUSTOM = "CUSTOM",
+}
+```
+
+#### AnnotationField
+
+```typescript
+interface AnnotationField {
+    type: AnnotationFieldType;
+    /** Unique annotation identifier */
+    id: string;
+    originalId?: string;
+    /** Display name */
+    name?: string;
+    /** Description (used for conditional signatures) */
+    description?: string;
+    /** Whether the annotation is required */
+    required?: boolean;
+    /** Page number (1-based) */
+    page: number;
+    /** Bounding rectangle in pixels */
+    rect: { x: number; y: number; width: number; height: number };
+    /** Assigned email address (if applicable) */
+    assignedEmail?: string;
+}
+```
+
+#### DefaultButtons
+
+```typescript
+type DefaultButtons = "zoomIn" | "zoomOut" | "fitWidth" | "download" | "undo" | "redo";
+```
+
+Used to selectively remove built-in toolbar buttons.
+
+### Form API
+
+Returned via `api.form` when using `FormUsage`.
 
 ```typescript
 interface UsePdfFormsResult {
+    /** All form fields in the document */
     fields: Field[];
+    /** Current field values keyed by field name */
     values: Record<string, string | boolean>;
+    /** Set a field value */
     setValue: (name: string, value: string | boolean) => void;
+    /** Validate all required fields — returns validity and errors */
     validate: () => { valid: boolean; errors: Record<string, string> };
+    /** Reload form fields from the document */
     reload: () => void;
+    /** Current validation errors (if any) */
     errors?: Record<string, string>;
+    /** Whether errors should be displayed */
     showErrors: boolean;
+    /** Scroll to a conditional signature group by index */
     scrollToConditionalSignature: (index: string) => Generator;
 }
 ```
 
-Represents the current form state.
-
 #### Field
 
 ```typescript
@@ -241,10 +339,58 @@ interface Field {
 }
 ```
 
-Represents a single form field.
+### Annotation API
+
+Returned via `api.annotation` when using `AnnotationUsage`.
+
+```typescript
+interface AnnotationsApi {
+    /** Get all current annotations */
+    getAnnotations: () => Promise<AnnotationField[]>;
+    /** Get annotation by ID */
+    getAnnotationById: (id: string) => AnnotationField | undefined;
+    /** Add a new annotation */
+    addAnnotation: (annotation: Partial<AnnotationField>) => void;
+    /** Update an existing annotation */
+    updateAnnotation: (annotation: AnnotationField) => void;
+    /** Remove annotations */
+    removeAnnotations: (annotations: AnnotationField[]) => void;
+    /** Get annotations for a specific page (1-based) */
+    getAnnotationsByPage: (page: number) => Promise<AnnotationField[]>;
+    /** Subscribe to annotation changes — returns unsubscribe function */
+    subscribe: (listener: (event: SubscribeEvent) => void) => () => void;
+    /** Select annotations by ID (null to deselect all) */
+    selectAnnotations: (ids: string[] | null) => void;
+}
+```
+
+**Subscribe events:**
+
+```typescript
+// Fired on create, update, or delete
+interface SubscribeEventModificationsOptions {
+    type: "update" | "create" | "delete";
+    annotations: AnnotationField[];
+}
+
+// Fired on selection change
+interface SubscribeEventSelectionOptions {
+    type: "selection";
+    selectedAnnotationsId: string[] | null;
+}
+```
 
 ### Toolbar Customization
 
+The `Toolbar` component accepts optional props for extending or trimming the default toolbar.
+
+```tsx
+<Toolbar
+    toolbarButtons={customButtons}
+    removeButtons={["download", "redo"]}
+/>
+```
+
 #### ToolbarItem
 
 ```typescript
@@ -256,13 +402,14 @@ type ToolbarItem = ToolbarButton | ToolbarSpacer;
 ```typescript
 interface ToolbarButton {
     id: string;
-    label: string;
+    label?: string;
     icon?: string;           // Font Awesome icon class
     title?: string;          // Tooltip text
     onClick: () => void;
     area: "left" | "right";
     disabled?: boolean;
     type: "button";
+    primary?: boolean;
 }
 ```
 
@@ -280,11 +427,11 @@ interface ToolbarSpacer {
 
 #### Supported Locales
 
-- `en` - English (default)
-- `it` - Italian
-- `es` - Spanish
-- `fr` - French
-- `de` - German
+- `en` — English (default)
+- `it` — Italian
+- `es` — Spanish
+- `fr` — French
+- `de` — German
 
 #### Default Translation Keys
 
@@ -296,6 +443,8 @@ interface ToolbarSpacer {
     download: string;
     pageNumberTitle: string;
     signature: string;
+    conditional1: string;   // "By accepting clause %s"
+    conditional2: string;   // "your signature will be placed here"
 }
 ```
 
@@ -307,7 +456,7 @@ Override or add translations for any locale:
 const translations = {
     en: {
         zoomIn: "Enlarge",
-        zoomOut: "Shrink",
+        download: "Download PDF",
         customKey: "Custom value",
     },
     it: {
@@ -318,15 +467,17 @@ const translations = {
 
 ## Examples
 
-### Basic PDF Viewer
+### Basic PDF Viewer (Plain Mode)
 
 ```tsx
 import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+import "@kopjra/pdf-sentinel/style.css";
 
 export function BasicViewer() {
     const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
         pdf: "https://example.com/document.pdf",
         name: "Document",
+        usage: { type: "plain" },
     });
 
     return (
@@ -344,20 +495,27 @@ export function BasicViewer() {
 
 ```tsx
 import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+import "@kopjra/pdf-sentinel/style.css";
 
 export function FormViewer() {
-    const { PdfSentinelContainer, Toolbar, PdfSentinel, form } = usePdfSentinel({
+    const { PdfSentinelContainer, Toolbar, PdfSentinel, api } = usePdfSentinel({
         pdf: "/document.pdf",
         name: "Form Document",
-        initialValues: {
-            "firstName": { value: "John" },
-            "lastName": { value: "Doe" },
+        usage: {
+            type: "form",
+            initialValues: {
+                "firstName": { value: "John" },
+                "lastName": { value: "Doe" },
+            },
         },
     });
 
     const handleValidate = () => {
-        if (form?.validate()) {
-            console.log("Form is valid, values:", form.values);
+        const result = api.form?.validate();
+        if (result?.valid) {
+            console.log("Form is valid, values:", api.form?.values);
+        } else {
+            console.log("Errors:", result?.errors);
         }
     };
 
@@ -375,10 +533,86 @@ export function FormViewer() {
 }
 ```
 
+### Conditional Signatures
+
+```tsx
+import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+import "@kopjra/pdf-sentinel/style.css";
+
+export function SignatureViewer() {
+    const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
+        pdf: "/contract.pdf",
+        name: "Contract",
+        usage: {
+            type: "form",
+            conditionalSignatures: [
+                { index: "1", fieldNames: ["authorizedBy", "authorizedDate"] },
+                { index: "2", fieldNames: ["approvedBy", "approvedDate"] },
+            ],
+        },
+    });
+
+    return (
+        <div style={{ height: "600px" }}>
+            <PdfSentinelContainer>
+                <Toolbar />
+                <PdfSentinel />
+            </PdfSentinelContainer>
+        </div>
+    );
+}
+```
+
+### Annotation Mode
+
+```tsx
+import { usePdfSentinel, AnnotationFieldType } from "@kopjra/pdf-sentinel";
+import "@kopjra/pdf-sentinel/style.css";
+
+export function AnnotationEditor() {
+    const { PdfSentinelContainer, Toolbar, PdfSentinel, api } = usePdfSentinel({
+        pdf: "/document.pdf",
+        name: "Annotate",
+        usage: {
+            type: "annotation",
+            initialAnnotations: "readFromDocument",
+            defaultType: AnnotationFieldType.SIGNATURE,
+            defaultSize: { width: 200, height: 60 },
+            selectOnCreation: true,
+        },
+    });
+
+    const handleExport = async () => {
+        const annotations = await api.annotation?.getAnnotations();
+        console.log("Annotations:", annotations);
+    };
+
+    // Subscribe to annotation changes
+    api.annotation?.subscribe((event) => {
+        if (event.type === "create") {
+            console.log("New annotations:", event.annotations);
+        }
+    });
+
+    return (
+        <>
+            <div style={{ height: "600px" }}>
+                <PdfSentinelContainer>
+                    <Toolbar />
+                    <PdfSentinel />
+                </PdfSentinelContainer>
+            </div>
+            <button onClick={handleExport}>Export Annotations</button>
+        </>
+    );
+}
+```
+
 ### Custom Toolbar Buttons
 
 ```tsx
 import { usePdfSentinel, ToolbarItem } from "@kopjra/pdf-sentinel";
+import "@kopjra/pdf-sentinel/style.css";
 
 export function CustomToolbar() {
     const customButtons: ToolbarItem[] = [
@@ -392,7 +626,7 @@ export function CustomToolbar() {
             onClick: () => window.print(),
         },
         {
-            id: "spacer",
+            id: "spacer-1",
             type: "spacer",
             area: "left",
         },
@@ -403,22 +637,23 @@ export function CustomToolbar() {
             title: "Share document",
             area: "right",
             type: "button",
-            onClick: () => {
-                console.log("Share clicked");
-            },
+            onClick: () => console.log("Share clicked"),
         },
     ];
 
     const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
         pdf: "/document.pdf",
         name: "Document",
-        toolbarButtons: customButtons,
+        usage: { type: "plain" },
     });
 
     return (
         <div style={{ height: "600px" }}>
             <PdfSentinelContainer>
-                <Toolbar />
+                <Toolbar
+                    toolbarButtons={customButtons}
+                    removeButtons={["undo", "redo"]}
+                />
                 <PdfSentinel />
             </PdfSentinelContainer>
         </div>
@@ -430,34 +665,33 @@ export function CustomToolbar() {
 
 ```tsx
 import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+import "@kopjra/pdf-sentinel/style.css";
 import { useState } from "react";
 
 export function MultiLanguageViewer() {
-    const [locale, setLocale] = useState("en");
+    const [locale, setLocale] = useState<"en" | "it" | "es" | "fr" | "de">("en");
 
     const customTranslations = {
-        en: {
-            zoomIn: "Zoom In",
-            download: "Download PDF",
-        },
-        it: {
-            zoomIn: "Ingrandisci",
-            download: "Scarica PDF",
-        },
+        en: { download: "Download PDF" },
+        it: { download: "Scarica PDF" },
     };
 
     const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
         pdf: "/document.pdf",
         name: "Document",
-        locale: locale,
+        locale,
         translations: customTranslations,
+        usage: { type: "plain" },
     });
 
     return (
         <div>
-            <select onChange={(e) => setLocale(e.target.value)} value={locale}>
+            <select onChange={(e) => setLocale(e.target.value as any)} value={locale}>
                 <option value="en">English</option>
                 <option value="it">Italiano</option>
+                <option value="es">Español</option>
+                <option value="fr">Français</option>
+                <option value="de">Deutsch</option>
             </select>
             <div style={{ height: "600px", marginTop: "10px" }}>
                 <PdfSentinelContainer>
@@ -470,120 +704,64 @@ export function MultiLanguageViewer() {
 }
 ```
 
-### Conditional Signatures with Groups
-
-```tsx
-import { usePdfSentinel, ConditionalSignature } from "@kopjra/pdf-sentinel";
-
-export function SignatureViewer() {
-    const conditionalSignatures: ConditionalSignature[] = [
-        { index: "1", fieldNames: ["authorizedBy", "authorizedDate"] },
-        { index: "2", fieldNames: ["approvedBy", "approvedDate"] },
-    ];
-
-    const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
-        pdf: "/contract.pdf",
-        name: "Contract",
-        conditionalSignatures: conditionalSignatures,
-    });
-
-    return (
-        <div style={{ height: "600px" }}>
-            <PdfSentinelContainer>
-                <Toolbar />
-                <PdfSentinel />
-            </PdfSentinelContainer>
-        </div>
-    );
-}
-```
-
-### Form Validation with Error Handling
+### External Toolbar (Custom UI)
 
 ```tsx
 import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+import "@kopjra/pdf-sentinel/style.css";
 
-export function FormWithValidation() {
-    const { PdfSentinelContainer, Toolbar, PdfSentinel, form } = usePdfSentinel({
-        pdf: "/form.pdf",
-        name: "Application Form",
-        initialValues: {
-            "email": { value: "" },
-            "phone": { value: "" },
-        },
+export function ExternalToolbarViewer() {
+    const {
+        PdfSentinelContainer,
+        PdfSentinel,
+        currentPage,
+        totalPages,
+        helpers,
+    } = usePdfSentinel({
+        pdf: "/document.pdf",
+        name: "Document",
+        hideToolbar: true,
+        usage: { type: "plain" },
     });
 
-    const handleSubmit = () => {
-        if (!form) return;
-
-        // Validate required fields
-        let isValid = true;
-        const errors: Record<string, string> = {};
-
-        if (!form.values["email"]) {
-            errors["email"] = "Email is required";
-            isValid = false;
-        }
-
-        if (!form.values["phone"]) {
-            errors["phone"] = "Phone is required";
-            isValid = false;
-        }
-
-        if (!isValid) {
-            // Set errors and show them
-            Object.entries(errors).forEach(([field, error]) => {
-                form.setFieldError(field, error);
-            });
-        } else {
-            console.log("Form submitted:", form.values);
-        }
-    };
-
     return (
-        <>
+        <div>
+            {/* Custom toolbar outside the container */}
+            <div style={{ display: "flex", gap: "8px", padding: "8px" }}>
+                <button onClick={helpers.zoomIn}>+</button>
+                <button onClick={helpers.zoomOut}>−</button>
+                <button onClick={helpers.resetZoom}>Fit</button>
+                <span>{currentPage} / {totalPages}</span>
+                <button onClick={helpers.download}>Download</button>
+            </div>
+
             <div style={{ height: "600px" }}>
                 <PdfSentinelContainer>
-                    <Toolbar />
                     <PdfSentinel />
                 </PdfSentinelContainer>
             </div>
-            <button onClick={handleSubmit}>Submit</button>
-        </>
+        </div>
     );
 }
 ```
 
 ### Using React and Preact Variants
 
-To use the Preact variant use import from `@kopjra/pdf-sentinel/preact` instead of `@kopjra/pdf-sentinel`.
-The React is the default one, however you can also use the import `@kopjra/pdf-sentinel/react` for clarity.
+To use the Preact variant, import from `@kopjra/pdf-sentinel/preact` instead of `@kopjra/pdf-sentinel`.
+The React variant is the default; you can also use `@kopjra/pdf-sentinel/react` for clarity.
 
 ```tsx
-// React variant
+// React variant (default)
+import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+
+// React variant (explicit)
 import { usePdfSentinel } from "@kopjra/pdf-sentinel/react";
 
-// Preact variant (same import, different package)
+// Preact variant
 import { usePdfSentinel } from "@kopjra/pdf-sentinel/preact";
-
-export function Viewer() {
-    const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
-        pdf: "/document.pdf",
-        name: "Document",
-    });
-
-    return (
-        <div style={{ height: "600px" }}>
-            <PdfSentinelContainer>
-                <Toolbar />
-                <PdfSentinel />
-            </PdfSentinelContainer>
-        </div>
-    );
-}
 ```
 
-The same code works for both React and Preact - the library automatically uses the correct variant based on your project configuration.
+The same code works for both React and Preact — the library automatically uses the correct framework variant based on the import path.
 
 ## Browser Support
 
@@ -604,5 +782,3 @@ Contributions are welcome! Please ensure:
 ## License
 
 ISC
-
-2