pdfjs-reader-core 0.1.4 → 0.2.0

package/dist/index.d.ts

@@ -250,20 +250,24 @@ interface StudentModeProps {
 interface PDFViewerProps {
     /** URL or ArrayBuffer of the PDF file */
     src: string | ArrayBuffer | Uint8Array;
-    /** Initial page number (1-indexed) */
+    /** Initial page number (1-indexed) - used in uncontrolled mode */
     initialPage?: number;
-    /** Initial scale/zoom level */
+    /** Controlled page - viewer syncs to this value when provided */
+    page?: number;
+    /** Initial scale/zoom level. Use 'auto' or 'page-width' to fit to container width. */
     initialScale?: number | 'page-fit' | 'page-width' | 'auto';
     /** Theme mode */
     theme?: 'light' | 'dark' | 'sepia';
     /** Custom class name */
     className?: string;
-    /** Whether to show the toolbar */
+    /** Whether to show the toolbar (default: true) */
     showToolbar?: boolean;
-    /** Whether to show the sidebar */
+    /** Whether to show the sidebar (default: true) */
     showSidebar?: boolean;
-    /** Whether to show the annotation toolbar */
+    /** Whether to show the annotation toolbar (default: false) */
     showAnnotationToolbar?: boolean;
+    /** Whether to show floating zoom controls (default: true) */
+    showFloatingZoom?: boolean;
     /** Default sidebar panel */
     defaultSidebarPanel?: SidebarPanel;
     /** View mode for the document */
@@ -280,6 +284,22 @@ interface PDFViewerProps {
     onError?: (error: Error) => void;
     /** Worker source URL for pdf.js */
     workerSrc?: string;
+    /** Callback when a page starts rendering */
+    onPageRenderStart?: (pageNumber: number) => void;
+    /** Callback when a page finishes rendering */
+    onPageRenderComplete?: (pageNumber: number) => void;
+    /** Callback when a highlight is added */
+    onHighlightAdded?: (highlight: Highlight) => void;
+    /** Callback when a highlight is removed */
+    onHighlightRemoved?: (highlightId: string) => void;
+    /** Callback when an annotation is added */
+    onAnnotationAdded?: (annotation: Annotation) => void;
+    /** Callback when zoom/scale changes (alias for onScaleChange) */
+    onZoomChange?: (scale: number) => void;
+    /** Custom loading component */
+    loadingComponent?: React.ReactNode;
+    /** Custom error component - can be a node or a function receiving error and retry callback */
+    errorComponent?: React.ReactNode | ((error: Error, retry: () => void) => React.ReactNode);
 }
 interface PDFDocumentLoadedEvent {
     numPages: number;
@@ -310,6 +330,12 @@ type ViewMode = 'single' | 'dual' | 'continuous';
 type ScrollMode = 'single' | 'continuous';
 type SidebarPanel = 'thumbnails' | 'outline' | 'search' | 'annotations' | null;
 type Theme = 'light' | 'dark' | 'sepia';
+/** Request to scroll to a specific page */
+interface ScrollToPageRequest {
+    page: number;
+    requestId: string;
+    behavior: 'smooth' | 'instant';
+}
 interface ViewerState {
     document: PDFDocumentProxy | null;
     numPages: number;
@@ -318,6 +344,7 @@ interface ViewerState {
     currentPage: number;
     scale: number;
     rotation: number;
+    scrollToPageRequest: ScrollToPageRequest | null;
     viewMode: ViewMode;
     scrollMode: ScrollMode;
     theme: Theme;
@@ -334,6 +361,8 @@ interface ViewerActions {
     goToPage: (page: number) => void;
     nextPage: () => void;
     previousPage: () => void;
+    requestScrollToPage: (page: number, behavior?: 'smooth' | 'instant') => Promise<void>;
+    completeScrollRequest: (requestId: string) => void;
     setScale: (scale: number) => void;
     zoomIn: () => void;
     zoomOut: () => void;
@@ -359,8 +388,8 @@ interface Highlight {
     comment?: string;
     createdAt: Date;
     updatedAt: Date;
-    /** Source of the highlight: user-created or agent-created */
-    source?: 'user' | 'agent';
+    /** Source of the highlight: user-created, agent-created, or search result */
+    source?: 'user' | 'agent' | 'search';
 }
 interface HighlightRect {
     x: number;
@@ -469,6 +498,291 @@ interface PDFViewerEventMap {
     textselect: TextSelection;
     error: Error;
 }
+interface HighlightTextOptions {
+    /** Highlight color (default: 'yellow') */
+    color?: HighlightColor;
+    /** Only highlight on specific page (default: all pages) */
+    page?: number;
+    /** Case sensitive search (default: false) */
+    caseSensitive?: boolean;
+    /** Scroll to first match (default: true) */
+    scrollTo?: boolean;
+}
+interface DrawRectOptions {
+    /** Page number (1-indexed) */
+    page: number;
+    /** X coordinate (percentage of page width, 0-100) */
+    x: number;
+    /** Y coordinate (percentage of page height, 0-100) */
+    y: number;
+    /** Width (percentage of page width) */
+    width: number;
+    /** Height (percentage of page height) */
+    height: number;
+    /** Border color (default: 'blue') */
+    color?: string;
+    /** Border width in pixels (default: 2) */
+    strokeWidth?: number;
+    /** Fill color (optional, transparent if not set) */
+    fillColor?: string;
+}
+interface DrawCircleOptions {
+    /** Page number (1-indexed) */
+    page: number;
+    /** Center X coordinate (percentage of page width, 0-100) */
+    x: number;
+    /** Center Y coordinate (percentage of page height, 0-100) */
+    y: number;
+    /** Radius (percentage of page width) */
+    radius: number;
+    /** Border color (default: 'blue') */
+    color?: string;
+    /** Border width in pixels (default: 2) */
+    strokeWidth?: number;
+    /** Fill color (optional, transparent if not set) */
+    fillColor?: string;
+}
+interface AddNoteOptions {
+    /** Page number (1-indexed) */
+    page: number;
+    /** X coordinate (percentage of page width, 0-100) */
+    x: number;
+    /** Y coordinate (percentage of page height, 0-100) */
+    y: number;
+    /** Note content */
+    content: string;
+    /** Note color (default: 'yellow') */
+    color?: string;
+}
+interface SearchOptions {
+    /** Case sensitive search (default: false) */
+    caseSensitive?: boolean;
+    /** Match whole words only (default: false) */
+    wholeWord?: boolean;
+    /** Highlight all matches (default: true) */
+    highlightAll?: boolean;
+}
+interface GoToPageOptions {
+    /** Scroll behavior (default: 'smooth') */
+    behavior?: 'smooth' | 'instant';
+}
+interface SearchAndHighlightOptions {
+    /** Highlight color (default: 'yellow') */
+    color?: HighlightColor;
+    /** Page range to search - either { start, end } or array of page numbers */
+    pageRange?: {
+        start: number;
+        end: number;
+    } | number[];
+    /** Case sensitive search (default: false) */
+    caseSensitive?: boolean;
+    /** Match whole words only (default: false) */
+    wholeWord?: boolean;
+    /** Scroll to first match (default: true) */
+    scrollToFirst?: boolean;
+    /** Clear previous search highlights (default: true) */
+    clearPrevious?: boolean;
+}
+interface SearchAndHighlightResult {
+    /** Total number of matches found */
+    matchCount: number;
+    /** IDs of created highlights */
+    highlightIds: string[];
+    /** Detailed match information */
+    matches: Array<{
+        pageNumber: number;
+        text: string;
+        highlightId: string;
+        rects: HighlightRect[];
+    }>;
+}
+interface AgentToolResult<T = void> {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+interface AgentTools {
+    /** Navigate to a specific page */
+    navigateToPage: (page: number) => Promise<AgentToolResult<{
+        previousPage: number;
+        currentPage: number;
+    }>>;
+    /** Highlight text with structured response */
+    highlightText: (text: string, options?: HighlightTextOptions) => Promise<AgentToolResult<{
+        matchCount: number;
+        highlightIds: string[];
+    }>>;
+    /** Get text content of a specific page */
+    getPageContent: (page: number) => Promise<AgentToolResult<{
+        text: string;
+    }>>;
+    /** Clear all visual elements (highlights and annotations) */
+    clearAllVisuals: () => Promise<AgentToolResult<void>>;
+}
+interface PageCoordinates {
+    x: number;
+    y: number;
+}
+interface PageDimensionsInfo {
+    width: number;
+    height: number;
+    rotation: number;
+}
+interface CoordinateHelpers {
+    /** Get dimensions of a specific page */
+    getPageDimensions: (page: number) => PageDimensionsInfo | null;
+    /** Convert percent coordinates (0-100) to pixels */
+    percentToPixels: (xPercent: number, yPercent: number, page: number) => PageCoordinates | null;
+    /** Convert pixel coordinates to percent (0-100) */
+    pixelsToPercent: (x: number, y: number, page: number) => PageCoordinates | null;
+}
+/**
+ * Imperative handle for PDFViewerClient.
+ * Use this to programmatically control the PDF viewer.
+ *
+ * @example
+ * ```tsx
+ * const viewerRef = useRef<PDFViewerHandle>(null);
+ *
+ * // Highlight text
+ * viewerRef.current?.highlightText("important keyword");
+ *
+ * // Draw a rectangle
+ * viewerRef.current?.drawRect({ page: 1, x: 10, y: 20, width: 30, height: 10 });
+ *
+ * // Navigate
+ * viewerRef.current?.goToPage(5);
+ * ```
+ */
+interface PDFViewerHandle {
+    /**
+     * Find and highlight text in the PDF.
+     * @param text - Text to find and highlight
+     * @param options - Highlight options
+     * @returns Array of highlight IDs created
+     */
+    highlightText: (text: string, options?: HighlightTextOptions) => Promise<string[]>;
+    /**
+     * Remove a specific highlight by ID.
+     */
+    removeHighlight: (id: string) => void;
+    /**
+     * Clear all highlights.
+     */
+    clearHighlights: () => void;
+    /**
+     * Draw a rectangle on the PDF.
+     * @param options - Rectangle options (coordinates are percentages 0-100)
+     * @returns Annotation ID
+     */
+    drawRect: (options: DrawRectOptions) => string;
+    /**
+     * Draw a circle on the PDF.
+     * @param options - Circle options (coordinates are percentages 0-100)
+     * @returns Annotation ID
+     */
+    drawCircle: (options: DrawCircleOptions) => string;
+    /**
+     * Add a note annotation.
+     * @param options - Note options
+     * @returns Annotation ID
+     */
+    addNote: (options: AddNoteOptions) => string;
+    /**
+     * Remove a specific annotation by ID.
+     */
+    removeAnnotation: (id: string) => void;
+    /**
+     * Clear all annotations.
+     */
+    clearAnnotations: () => void;
+    /**
+     * Go to a specific page. Returns a Promise that resolves when scroll completes.
+     * @param page - Page number (1-indexed)
+     * @param options - Navigation options
+     * @returns Promise that resolves when the page is visible
+     */
+    goToPage: (page: number, options?: GoToPageOptions) => Promise<void>;
+    /**
+     * Go to the next page.
+     */
+    nextPage: () => void;
+    /**
+     * Go to the previous page.
+     */
+    previousPage: () => void;
+    /**
+     * Get the current page number.
+     */
+    getCurrentPage: () => number;
+    /**
+     * Get total number of pages.
+     */
+    getNumPages: () => number;
+    /**
+     * Set the zoom level.
+     * @param scale - Zoom scale (1.0 = 100%)
+     */
+    setZoom: (scale: number) => void;
+    /**
+     * Get the current zoom level.
+     */
+    getZoom: () => number;
+    /**
+     * Zoom in.
+     */
+    zoomIn: () => void;
+    /**
+     * Zoom out.
+     */
+    zoomOut: () => void;
+    /**
+     * Search for text in the PDF.
+     * @param query - Search query
+     * @param options - Search options
+     * @returns Search results
+     */
+    search: (query: string, options?: SearchOptions) => Promise<SearchResult[]>;
+    /**
+     * Go to the next search result.
+     */
+    nextSearchResult: () => void;
+    /**
+     * Go to the previous search result.
+     */
+    previousSearchResult: () => void;
+    /**
+     * Clear search results.
+     */
+    clearSearch: () => void;
+    /**
+     * Search for text and highlight all matches in one operation.
+     * @param query - Text to search for
+     * @param options - Search and highlight options
+     * @returns Structured result with match count and highlight IDs
+     */
+    searchAndHighlight: (query: string, options?: SearchAndHighlightOptions) => Promise<SearchAndHighlightResult>;
+    /**
+     * Agent-friendly tools with structured responses.
+     * Each method returns { success, data?, error? } for easy agent integration.
+     */
+    agentTools: AgentTools;
+    /**
+     * Coordinate conversion utilities for working with PDF page coordinates.
+     */
+    coordinates: CoordinateHelpers;
+    /**
+     * Get the underlying PDF document (pdfjs-dist PDFDocumentProxy).
+     */
+    getDocument: () => PDFDocumentProxy | null;
+    /**
+     * Check if the document is loaded.
+     */
+    isLoaded: () => boolean;
+}
 
 /**
  * Main PDF Viewer component.
@@ -496,10 +810,27 @@ interface PDFViewerEventMap {
 declare const PDFViewer: react.NamedExoticComponent<PDFViewerProps>;
 
 /**
- * SSR-safe PDF Viewer component.
- * Wraps the inner viewer with the context provider.
+ * PDF Viewer component with imperative API.
+ *
+ * @example
+ * ```tsx
+ * const viewerRef = useRef<PDFViewerHandle>(null);
+ *
+ * <PDFViewerClient
+ *   ref={viewerRef}
+ *   src="/document.pdf"
+ *   onDocumentLoad={() => {
+ *     // Highlight text when document loads
+ *     viewerRef.current?.highlightText("important", { color: "yellow" });
+ *   }}
+ * />
+ *
+ * // Call methods anytime
+ * viewerRef.current?.goToPage(5);
+ * viewerRef.current?.drawRect({ page: 1, x: 10, y: 20, width: 30, height: 10 });
+ * ```
  */
-declare const PDFViewerClient: react.NamedExoticComponent<PDFViewerProps>;
+declare const PDFViewerClient: react.MemoExoticComponent<react.ForwardRefExoticComponent<PDFViewerProps & react.RefAttributes<PDFViewerHandle>>>;
 
 interface DocumentContainerProps {
     className?: string;
@@ -1020,6 +1351,52 @@ interface MinimapProps {
  */
 declare const Minimap: react.NamedExoticComponent<MinimapProps>;
 
+interface FloatingZoomControlsProps {
+    /** Position of the controls */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Additional class name */
+    className?: string;
+    /** Show fit to width button */
+    showFitToWidth?: boolean;
+    /** Show fit to page button */
+    showFitToPage?: boolean;
+    /** Show zoom percentage */
+    showZoomLevel?: boolean;
+}
+/**
+ * Floating zoom controls for easy zoom adjustment.
+ * Shows +/- buttons and optionally fit-to-width/fit-to-page buttons.
+ */
+declare const FloatingZoomControls: react.NamedExoticComponent<FloatingZoomControlsProps>;
+
+interface PDFThumbnailNavProps {
+    /** Scale for thumbnails (default: 0.15) */
+    thumbnailScale?: number;
+    /** Orientation of the thumbnail strip */
+    orientation?: 'horizontal' | 'vertical';
+    /** Maximum number of thumbnails visible at once */
+    maxVisible?: number;
+    /** Custom class name */
+    className?: string;
+    /** Callback when a thumbnail is clicked */
+    onThumbnailClick?: (page: number) => void;
+    /** Gap between thumbnails in pixels (default: 8) */
+    gap?: number;
+    /** Show page numbers below thumbnails (default: true) */
+    showPageNumbers?: boolean;
+}
+/**
+ * PDFThumbnailNav provides a navigable strip of PDF page thumbnails.
+ * Syncs with the current PDF viewer via store subscription.
+ *
+ * Features:
+ * - Virtualized rendering (only visible thumbnails are rendered)
+ * - Auto-scrolls to keep current page visible
+ * - Click to navigate to page
+ * - Horizontal or vertical orientation
+ */
+declare const PDFThumbnailNav: react.NamedExoticComponent<PDFThumbnailNavProps>;
+
 interface PDFErrorBoundaryProps {
     /** Child components to render */
     children: ReactNode;
@@ -1058,6 +1435,8 @@ interface SearchActions {
     nextResult: () => void;
     previousResult: () => void;
     goToResult: (index: number) => void;
+    setCaseSensitive: (value: boolean) => void;
+    setWholeWord: (value: boolean) => void;
     toggleCaseSensitive: () => void;
     toggleWholeWord: () => void;
     getCurrentResult: () => SearchResult | null;
@@ -2032,4 +2411,256 @@ declare function createAgentAPI(stores: AgentAPIStores): AgentAPI;
  */
 type AgentAPIInstance = ReturnType<typeof createAgentAPI>;
 
-export { type AgentAPI, type AgentAPIInstance, type AgentAPIStores, type AgentActions, type AgentContext, type AgentHighlightParams, type AgentState, type AgentStore, type AgentStoreApi, type Annotation, type AnnotationActions, AnnotationLayer, type AnnotationLayerProps, type AnnotationState, type AnnotationStore, type AnnotationStoreApi, type AnnotationTool, AnnotationToolbar, type AnnotationToolbarProps, type AnnotationType, type AskAboutContext, AskAboutOverlay, type AskAboutOverlayProps, AskAboutTrigger, type AskAboutTriggerProps, type Bookmark, BookmarksPanel, type BookmarksPanelProps, CanvasLayer, type CanvasLayerProps, type ContextMenuItem, ContinuousScrollContainer, type ContinuousScrollContainerProps, DocumentContainer, type DocumentContainerProps, type DrawingAnnotation, DrawingCanvas, type DrawingCanvasProps, type DrawingPath, DualPageContainer, type DualPageContainerProps, type ExportData, FocusRegionLayer, type FocusRegionLayerProps, type FocusedRegion, type Highlight, type HighlightColor, HighlightLayer, type HighlightLayerProps, HighlightPopover, type HighlightPopoverProps, type HighlightRect, HighlightsPanel, type HighlightsPanelProps, type LoadDocumentOptions, type LoadDocumentResult, Minimap, type MinimapProps, MobileSidebar, type MobileSidebarProps, MobileToolbar, type MobileToolbarProps, type NoteAnnotation, type OutlineItem, OutlinePanel, type OutlinePanelProps, type PDFDocumentLoadedEvent, PDFErrorBoundary, type PDFErrorBoundaryProps, PDFPage, type PDFPageProps, type PDFPageState, type PDFRegion, PDFViewer, PDFViewerClient, PDFViewerContext, type PDFViewerContextValue, type PDFViewerController, type PDFViewerControllerOptions, type PDFViewerEventMap, type PDFViewerProps, PDFViewerProvider, type PDFViewerProviderProps, type PageDimensions, type Plugin, type PluginAPI, PluginManager, type PluginManagerOptions, type QuickNote, QuickNoteButton, type QuickNoteButtonProps, QuickNotePopover, type QuickNotePopoverProps, type ScrollMode, type SearchActions, SearchPanel, type SearchPanelProps, type SearchResult, type SearchState, type SearchStore, type SearchStoreApi, SelectionToolbar, type SelectionToolbarProps, type ShapeAnnotation, ShapePreview, type ShapePreviewProps, ShapeRenderer, type ShapeRendererProps, type ShapeType, Sidebar, type SidebarPanel, type SidebarPanelConfig, type SidebarProps, StickyNote, type StickyNoteProps, type StoredStudentData, type StudentActions, type StudentData, type StudentModeCallbacks, type StudentModeProps, type StudentState, type StudentStore, type StudentStoreApi, type Takeaway, TakeawaysPanel, type TakeawaysPanelProps, TextLayer, type TextLayerProps, type TextSelection, type Theme, ThumbnailPanel, type ThumbnailPanelProps, Toolbar, type ToolbarItem, type ToolbarProps, type UseAgentContextOptions, type UseAgentContextReturn, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseAskAboutOptions, type UseAskAboutReturn, type UseBookmarksOptions, type UseBookmarksReturn, type UseHighlightsOptions, type UseHighlightsReturn, type UsePageNavigationOptions, type UsePluginsOptions, type UsePluginsReturn, type UseQuickNotesOptions, type UseQuickNotesReturn, type UseStudentProgressOptions, type UseStudentProgressReturn, type UseTextSelectionOptions, type UseTouchGesturesOptions, type UseZoomOptions, type ViewMode, type ViewerActions, type ViewerState, type ViewerStore, type ViewerStoreApi, VirtualizedDocumentContainer, type VirtualizedDocumentContainerProps, type WithErrorBoundaryProps, clearHighlights, clearStudentData, cn, createAgentAPI, createAgentStore, createAnnotationStore, createPDFViewer, createPluginManager, createSearchStore, createStudentStore, createViewerStore, downloadAnnotationsAsJSON, downloadAnnotationsAsMarkdown, downloadFile, exportAnnotationsAsJSON, exportAnnotationsAsMarkdown, exportHighlightsAsJSON, exportHighlightsAsMarkdown, generateDocumentId, getAllDocumentIds, getAllStudentDataDocumentIds, getMetadata, getOutline, getPage, getPageTextContent, getPluginManager, getStorageStats, importHighlightsFromJSON, initializePDFJS, isPDFJSInitialized, loadDocument, loadHighlights, loadStudentData, quickViewer, saveHighlights, saveStudentData, useAgentContext, useAgentStore, useAnnotationStore, useAnnotations, useAskAbout, useBookmarks, useHighlights, useIsMobile, useIsTouchDevice, usePDFViewer, usePDFViewerStores, usePageNavigation, usePlugins, useQuickNotes, useSearchStore, useStudentProgress, useStudentStore, useTextSelection, useTouchGestures, useViewerStore, useZoom, withErrorBoundary };
+interface TextMatch {
+    /** The matched text */
+    text: string;
+    /** Position rects on the page */
+    rects: HighlightRect[];
+    /** Page number where the match was found */
+    pageNumber: number;
+    /** Character index where the match starts in the page text */
+    startIndex: number;
+}
+interface FindTextOptions {
+    /** Case sensitive search (default: false) */
+    caseSensitive?: boolean;
+    /** Match whole words only (default: false) */
+    wholeWord?: boolean;
+}
+interface CharPosition {
+    char: string;
+    rect: HighlightRect;
+}
+/**
+ * Extract text content with character positions from a PDF page.
+ */
+declare function extractPageText(document: PDFDocumentProxy, pageNumber: number): Promise<{
+    fullText: string;
+    charPositions: CharPosition[];
+}>;
+/**
+ * Find all occurrences of text on a specific page.
+ */
+declare function findTextOnPage(document: PDFDocumentProxy, pageNumber: number, query: string, options?: FindTextOptions): Promise<TextMatch[]>;
+/**
+ * Find all occurrences of text across multiple pages.
+ */
+declare function findTextInDocument(document: PDFDocumentProxy, query: string, options?: FindTextOptions & {
+    pageRange?: number[];
+}): Promise<TextMatch[]>;
+/**
+ * Merge adjacent rects into larger rects.
+ */
+declare function mergeAdjacentRects(rects: HighlightRect[]): HighlightRect[];
+/**
+ * Get the full text content of a page as a string.
+ */
+declare function getPageText(document: PDFDocumentProxy, pageNumber: number): Promise<string>;
+/**
+ * Count occurrences of text on a page without extracting positions.
+ */
+declare function countTextOnPage(document: PDFDocumentProxy, pageNumber: number, query: string, options?: FindTextOptions): Promise<number>;
+
+/**
+ * Convert PDF coordinates to viewport (screen) coordinates.
+ * PDF coordinates have origin at bottom-left, viewport at top-left.
+ *
+ * @param x - X coordinate in PDF space
+ * @param y - Y coordinate in PDF space
+ * @param scale - Current zoom scale
+ * @param pageHeight - Height of the page in PDF units
+ * @returns Viewport coordinates { x, y }
+ */
+declare function pdfToViewport(x: number, y: number, scale: number, pageHeight: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Convert viewport (screen) coordinates to PDF coordinates.
+ * Viewport coordinates have origin at top-left, PDF at bottom-left.
+ *
+ * @param x - X coordinate in viewport space
+ * @param y - Y coordinate in viewport space
+ * @param scale - Current zoom scale
+ * @param pageHeight - Height of the page in PDF units
+ * @returns PDF coordinates { x, y }
+ */
+declare function viewportToPDF(x: number, y: number, scale: number, pageHeight: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Convert percentage-based coordinates to PDF coordinates.
+ * Useful for positioning elements based on relative position.
+ *
+ * @param xPercent - X coordinate as percentage (0-100)
+ * @param yPercent - Y coordinate as percentage (0-100)
+ * @param pageWidth - Width of the page in PDF units
+ * @param pageHeight - Height of the page in PDF units
+ * @returns PDF coordinates { x, y }
+ */
+declare function percentToPDF(xPercent: number, yPercent: number, pageWidth: number, pageHeight: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Convert PDF coordinates to percentage-based coordinates.
+ *
+ * @param x - X coordinate in PDF space
+ * @param y - Y coordinate in PDF space
+ * @param pageWidth - Width of the page in PDF units
+ * @param pageHeight - Height of the page in PDF units
+ * @returns Percentage coordinates { x, y } (0-100)
+ */
+declare function pdfToPercent(x: number, y: number, pageWidth: number, pageHeight: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Convert percentage coordinates to viewport (screen) pixels.
+ *
+ * @param xPercent - X coordinate as percentage (0-100)
+ * @param yPercent - Y coordinate as percentage (0-100)
+ * @param pageWidth - Width of the page in PDF units
+ * @param pageHeight - Height of the page in PDF units
+ * @param scale - Current zoom scale
+ * @returns Viewport coordinates { x, y }
+ */
+declare function percentToViewport(xPercent: number, yPercent: number, pageWidth: number, pageHeight: number, scale: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Convert viewport (screen) pixels to percentage coordinates.
+ *
+ * @param x - X coordinate in viewport space
+ * @param y - Y coordinate in viewport space
+ * @param pageWidth - Width of the page in PDF units
+ * @param pageHeight - Height of the page in PDF units
+ * @param scale - Current zoom scale
+ * @returns Percentage coordinates { x, y } (0-100)
+ */
+declare function viewportToPercent(x: number, y: number, pageWidth: number, pageHeight: number, scale: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Apply rotation to coordinates.
+ * Rotates point around the center of the page.
+ *
+ * @param x - X coordinate
+ * @param y - Y coordinate
+ * @param rotation - Rotation in degrees (0, 90, 180, 270)
+ * @param pageWidth - Width of the page
+ * @param pageHeight - Height of the page
+ * @returns Rotated coordinates { x, y }
+ */
+declare function applyRotation(x: number, y: number, rotation: number, pageWidth: number, pageHeight: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Remove rotation from coordinates.
+ * Inverse of applyRotation.
+ *
+ * @param x - X coordinate
+ * @param y - Y coordinate
+ * @param rotation - Rotation in degrees (0, 90, 180, 270)
+ * @param pageWidth - Width of the page (original, before rotation)
+ * @param pageHeight - Height of the page (original, before rotation)
+ * @returns Unrotated coordinates { x, y }
+ */
+declare function removeRotation(x: number, y: number, rotation: number, pageWidth: number, pageHeight: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate the bounding box dimensions after rotation.
+ *
+ * @param width - Original width
+ * @param height - Original height
+ * @param rotation - Rotation in degrees
+ * @returns Rotated dimensions { width, height }
+ */
+declare function getRotatedDimensions(width: number, height: number, rotation: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Convert a rectangle from one coordinate space to another.
+ *
+ * @param rect - Rectangle with x, y, width, height
+ * @param fromScale - Source scale
+ * @param toScale - Target scale
+ * @returns Scaled rectangle
+ */
+declare function scaleRect(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, fromScale: number, toScale: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Check if a point is inside a rectangle.
+ *
+ * @param point - Point coordinates { x, y }
+ * @param rect - Rectangle { x, y, width, height }
+ * @returns True if point is inside rectangle
+ */
+declare function isPointInRect(point: {
+    x: number;
+    y: number;
+}, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): boolean;
+/**
+ * Check if two rectangles intersect.
+ *
+ * @param rectA - First rectangle
+ * @param rectB - Second rectangle
+ * @returns True if rectangles intersect
+ */
+declare function doRectsIntersect(rectA: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, rectB: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): boolean;
+/**
+ * Get the intersection of two rectangles.
+ *
+ * @param rectA - First rectangle
+ * @param rectB - Second rectangle
+ * @returns Intersection rectangle or null if no intersection
+ */
+declare function getRectIntersection(rectA: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, rectB: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+
+export { type AddNoteOptions, type AgentAPI, type AgentAPIInstance, type AgentAPIStores, type AgentActions, type AgentContext, type AgentHighlightParams, type AgentState, type AgentStore, type AgentStoreApi, type AgentToolResult, type AgentTools, type Annotation, type AnnotationActions, AnnotationLayer, type AnnotationLayerProps, type AnnotationState, type AnnotationStore, type AnnotationStoreApi, type AnnotationTool, AnnotationToolbar, type AnnotationToolbarProps, type AnnotationType, type AskAboutContext, AskAboutOverlay, type AskAboutOverlayProps, AskAboutTrigger, type AskAboutTriggerProps, type Bookmark, BookmarksPanel, type BookmarksPanelProps, CanvasLayer, type CanvasLayerProps, type CharPosition, type ContextMenuItem, ContinuousScrollContainer, type ContinuousScrollContainerProps, type CoordinateHelpers, DocumentContainer, type DocumentContainerProps, type DrawCircleOptions, type DrawRectOptions, type DrawingAnnotation, DrawingCanvas, type DrawingCanvasProps, type DrawingPath, DualPageContainer, type DualPageContainerProps, type ExportData, type FindTextOptions, FloatingZoomControls, type FloatingZoomControlsProps, FocusRegionLayer, type FocusRegionLayerProps, type FocusedRegion, type GoToPageOptions, type Highlight, type HighlightColor, HighlightLayer, type HighlightLayerProps, HighlightPopover, type HighlightPopoverProps, type HighlightRect, type HighlightTextOptions, HighlightsPanel, type HighlightsPanelProps, type LoadDocumentOptions, type LoadDocumentResult, Minimap, type MinimapProps, MobileSidebar, type MobileSidebarProps, MobileToolbar, type MobileToolbarProps, type NoteAnnotation, type OutlineItem, OutlinePanel, type OutlinePanelProps, type PDFDocumentLoadedEvent, PDFErrorBoundary, type PDFErrorBoundaryProps, PDFPage, type PDFPageProps, type PDFPageState, type PDFRegion, PDFThumbnailNav, type PDFThumbnailNavProps, PDFViewer, PDFViewerClient, PDFViewerContext, type PDFViewerContextValue, type PDFViewerController, type PDFViewerControllerOptions, type PDFViewerEventMap, type PDFViewerHandle, type PDFViewerProps, PDFViewerProvider, type PDFViewerProviderProps, type PageCoordinates, type PageDimensions, type PageDimensionsInfo, type Plugin, type PluginAPI, PluginManager, type PluginManagerOptions, type QuickNote, QuickNoteButton, type QuickNoteButtonProps, QuickNotePopover, type QuickNotePopoverProps, type ScrollMode, type ScrollToPageRequest, type SearchActions, type SearchAndHighlightOptions, type SearchAndHighlightResult, type SearchOptions, SearchPanel, type SearchPanelProps, type SearchResult, type SearchState, type SearchStore, type SearchStoreApi, SelectionToolbar, type SelectionToolbarProps, type ShapeAnnotation, ShapePreview, type ShapePreviewProps, ShapeRenderer, type ShapeRendererProps, type ShapeType, Sidebar, type SidebarPanel, type SidebarPanelConfig, type SidebarProps, StickyNote, type StickyNoteProps, type StoredStudentData, type StudentActions, type StudentData, type StudentModeCallbacks, type StudentModeProps, type StudentState, type StudentStore, type StudentStoreApi, type Takeaway, TakeawaysPanel, type TakeawaysPanelProps, TextLayer, type TextLayerProps, type TextMatch, type TextSelection, type Theme, ThumbnailPanel, type ThumbnailPanelProps, Toolbar, type ToolbarItem, type ToolbarProps, type UseAgentContextOptions, type UseAgentContextReturn, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseAskAboutOptions, type UseAskAboutReturn, type UseBookmarksOptions, type UseBookmarksReturn, type UseHighlightsOptions, type UseHighlightsReturn, type UsePageNavigationOptions, type UsePluginsOptions, type UsePluginsReturn, type UseQuickNotesOptions, type UseQuickNotesReturn, type UseStudentProgressOptions, type UseStudentProgressReturn, type UseTextSelectionOptions, type UseTouchGesturesOptions, type UseZoomOptions, type ViewMode, type ViewerActions, type ViewerState, type ViewerStore, type ViewerStoreApi, VirtualizedDocumentContainer, type VirtualizedDocumentContainerProps, type WithErrorBoundaryProps, applyRotation, clearHighlights, clearStudentData, cn, countTextOnPage, createAgentAPI, createAgentStore, createAnnotationStore, createPDFViewer, createPluginManager, createSearchStore, createStudentStore, createViewerStore, doRectsIntersect, downloadAnnotationsAsJSON, downloadAnnotationsAsMarkdown, downloadFile, exportAnnotationsAsJSON, exportAnnotationsAsMarkdown, exportHighlightsAsJSON, exportHighlightsAsMarkdown, extractPageText, findTextInDocument, findTextOnPage, generateDocumentId, getAllDocumentIds, getAllStudentDataDocumentIds, getMetadata, getOutline, getPage, getPageText, getPageTextContent, getPluginManager, getRectIntersection, getRotatedDimensions, getStorageStats, importHighlightsFromJSON, initializePDFJS, isPDFJSInitialized, isPointInRect, loadDocument, loadHighlights, loadStudentData, mergeAdjacentRects, pdfToPercent, pdfToViewport, percentToPDF, percentToViewport, quickViewer, removeRotation, saveHighlights, saveStudentData, scaleRect, useAgentContext, useAgentStore, useAnnotationStore, useAnnotations, useAskAbout, useBookmarks, useHighlights, useIsMobile, useIsTouchDevice, usePDFViewer, usePDFViewerStores, usePageNavigation, usePlugins, useQuickNotes, useSearchStore, useStudentProgress, useStudentStore, useTextSelection, useTouchGestures, useViewerStore, useZoom, viewportToPDF, viewportToPercent, withErrorBoundary };