pdfjs-reader-core 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -252,18 +252,20 @@ interface PDFViewerProps {
252
252
  src: string | ArrayBuffer | Uint8Array;
253
253
  /** Initial page number (1-indexed) */
254
254
  initialPage?: number;
255
- /** Initial scale/zoom level */
255
+ /** Initial scale/zoom level. Use 'auto' or 'page-width' to fit to container width. */
256
256
  initialScale?: number | 'page-fit' | 'page-width' | 'auto';
257
257
  /** Theme mode */
258
258
  theme?: 'light' | 'dark' | 'sepia';
259
259
  /** Custom class name */
260
260
  className?: string;
261
- /** Whether to show the toolbar */
261
+ /** Whether to show the toolbar (default: true) */
262
262
  showToolbar?: boolean;
263
- /** Whether to show the sidebar */
263
+ /** Whether to show the sidebar (default: true) */
264
264
  showSidebar?: boolean;
265
- /** Whether to show the annotation toolbar */
265
+ /** Whether to show the annotation toolbar (default: false) */
266
266
  showAnnotationToolbar?: boolean;
267
+ /** Whether to show floating zoom controls (default: true) */
268
+ showFloatingZoom?: boolean;
267
269
  /** Default sidebar panel */
268
270
  defaultSidebarPanel?: SidebarPanel;
269
271
  /** View mode for the document */
@@ -469,6 +471,196 @@ interface PDFViewerEventMap {
469
471
  textselect: TextSelection;
470
472
  error: Error;
471
473
  }
474
+ interface HighlightTextOptions {
475
+ /** Highlight color (default: 'yellow') */
476
+ color?: HighlightColor;
477
+ /** Only highlight on specific page (default: all pages) */
478
+ page?: number;
479
+ /** Case sensitive search (default: false) */
480
+ caseSensitive?: boolean;
481
+ /** Scroll to first match (default: true) */
482
+ scrollTo?: boolean;
483
+ }
484
+ interface DrawRectOptions {
485
+ /** Page number (1-indexed) */
486
+ page: number;
487
+ /** X coordinate (percentage of page width, 0-100) */
488
+ x: number;
489
+ /** Y coordinate (percentage of page height, 0-100) */
490
+ y: number;
491
+ /** Width (percentage of page width) */
492
+ width: number;
493
+ /** Height (percentage of page height) */
494
+ height: number;
495
+ /** Border color (default: 'blue') */
496
+ color?: string;
497
+ /** Border width in pixels (default: 2) */
498
+ strokeWidth?: number;
499
+ /** Fill color (optional, transparent if not set) */
500
+ fillColor?: string;
501
+ }
502
+ interface DrawCircleOptions {
503
+ /** Page number (1-indexed) */
504
+ page: number;
505
+ /** Center X coordinate (percentage of page width, 0-100) */
506
+ x: number;
507
+ /** Center Y coordinate (percentage of page height, 0-100) */
508
+ y: number;
509
+ /** Radius (percentage of page width) */
510
+ radius: number;
511
+ /** Border color (default: 'blue') */
512
+ color?: string;
513
+ /** Border width in pixels (default: 2) */
514
+ strokeWidth?: number;
515
+ /** Fill color (optional, transparent if not set) */
516
+ fillColor?: string;
517
+ }
518
+ interface AddNoteOptions {
519
+ /** Page number (1-indexed) */
520
+ page: number;
521
+ /** X coordinate (percentage of page width, 0-100) */
522
+ x: number;
523
+ /** Y coordinate (percentage of page height, 0-100) */
524
+ y: number;
525
+ /** Note content */
526
+ content: string;
527
+ /** Note color (default: 'yellow') */
528
+ color?: string;
529
+ }
530
+ interface SearchOptions {
531
+ /** Case sensitive search (default: false) */
532
+ caseSensitive?: boolean;
533
+ /** Match whole words only (default: false) */
534
+ wholeWord?: boolean;
535
+ /** Highlight all matches (default: true) */
536
+ highlightAll?: boolean;
537
+ }
538
+ /**
539
+ * Imperative handle for PDFViewerClient.
540
+ * Use this to programmatically control the PDF viewer.
541
+ *
542
+ * @example
543
+ * ```tsx
544
+ * const viewerRef = useRef<PDFViewerHandle>(null);
545
+ *
546
+ * // Highlight text
547
+ * viewerRef.current?.highlightText("important keyword");
548
+ *
549
+ * // Draw a rectangle
550
+ * viewerRef.current?.drawRect({ page: 1, x: 10, y: 20, width: 30, height: 10 });
551
+ *
552
+ * // Navigate
553
+ * viewerRef.current?.goToPage(5);
554
+ * ```
555
+ */
556
+ interface PDFViewerHandle {
557
+ /**
558
+ * Find and highlight text in the PDF.
559
+ * @param text - Text to find and highlight
560
+ * @param options - Highlight options
561
+ * @returns Array of highlight IDs created
562
+ */
563
+ highlightText: (text: string, options?: HighlightTextOptions) => Promise<string[]>;
564
+ /**
565
+ * Remove a specific highlight by ID.
566
+ */
567
+ removeHighlight: (id: string) => void;
568
+ /**
569
+ * Clear all highlights.
570
+ */
571
+ clearHighlights: () => void;
572
+ /**
573
+ * Draw a rectangle on the PDF.
574
+ * @param options - Rectangle options (coordinates are percentages 0-100)
575
+ * @returns Annotation ID
576
+ */
577
+ drawRect: (options: DrawRectOptions) => string;
578
+ /**
579
+ * Draw a circle on the PDF.
580
+ * @param options - Circle options (coordinates are percentages 0-100)
581
+ * @returns Annotation ID
582
+ */
583
+ drawCircle: (options: DrawCircleOptions) => string;
584
+ /**
585
+ * Add a note annotation.
586
+ * @param options - Note options
587
+ * @returns Annotation ID
588
+ */
589
+ addNote: (options: AddNoteOptions) => string;
590
+ /**
591
+ * Remove a specific annotation by ID.
592
+ */
593
+ removeAnnotation: (id: string) => void;
594
+ /**
595
+ * Clear all annotations.
596
+ */
597
+ clearAnnotations: () => void;
598
+ /**
599
+ * Go to a specific page.
600
+ * @param page - Page number (1-indexed)
601
+ */
602
+ goToPage: (page: number) => void;
603
+ /**
604
+ * Go to the next page.
605
+ */
606
+ nextPage: () => void;
607
+ /**
608
+ * Go to the previous page.
609
+ */
610
+ previousPage: () => void;
611
+ /**
612
+ * Get the current page number.
613
+ */
614
+ getCurrentPage: () => number;
615
+ /**
616
+ * Get total number of pages.
617
+ */
618
+ getNumPages: () => number;
619
+ /**
620
+ * Set the zoom level.
621
+ * @param scale - Zoom scale (1.0 = 100%)
622
+ */
623
+ setZoom: (scale: number) => void;
624
+ /**
625
+ * Get the current zoom level.
626
+ */
627
+ getZoom: () => number;
628
+ /**
629
+ * Zoom in.
630
+ */
631
+ zoomIn: () => void;
632
+ /**
633
+ * Zoom out.
634
+ */
635
+ zoomOut: () => void;
636
+ /**
637
+ * Search for text in the PDF.
638
+ * @param query - Search query
639
+ * @param options - Search options
640
+ * @returns Search results
641
+ */
642
+ search: (query: string, options?: SearchOptions) => Promise<SearchResult[]>;
643
+ /**
644
+ * Go to the next search result.
645
+ */
646
+ nextSearchResult: () => void;
647
+ /**
648
+ * Go to the previous search result.
649
+ */
650
+ previousSearchResult: () => void;
651
+ /**
652
+ * Clear search results.
653
+ */
654
+ clearSearch: () => void;
655
+ /**
656
+ * Get the underlying PDF document (pdfjs-dist PDFDocumentProxy).
657
+ */
658
+ getDocument: () => PDFDocumentProxy | null;
659
+ /**
660
+ * Check if the document is loaded.
661
+ */
662
+ isLoaded: () => boolean;
663
+ }
472
664
 
473
665
  /**
474
666
  * Main PDF Viewer component.
@@ -496,10 +688,27 @@ interface PDFViewerEventMap {
496
688
  declare const PDFViewer: react.NamedExoticComponent<PDFViewerProps>;
497
689
 
498
690
  /**
499
- * SSR-safe PDF Viewer component.
500
- * Wraps the inner viewer with the context provider.
691
+ * PDF Viewer component with imperative API.
692
+ *
693
+ * @example
694
+ * ```tsx
695
+ * const viewerRef = useRef<PDFViewerHandle>(null);
696
+ *
697
+ * <PDFViewerClient
698
+ * ref={viewerRef}
699
+ * src="/document.pdf"
700
+ * onDocumentLoad={() => {
701
+ * // Highlight text when document loads
702
+ * viewerRef.current?.highlightText("important", { color: "yellow" });
703
+ * }}
704
+ * />
705
+ *
706
+ * // Call methods anytime
707
+ * viewerRef.current?.goToPage(5);
708
+ * viewerRef.current?.drawRect({ page: 1, x: 10, y: 20, width: 30, height: 10 });
709
+ * ```
501
710
  */
502
- declare const PDFViewerClient: react.NamedExoticComponent<PDFViewerProps>;
711
+ declare const PDFViewerClient: react.MemoExoticComponent<react.ForwardRefExoticComponent<PDFViewerProps & react.RefAttributes<PDFViewerHandle>>>;
503
712
 
504
713
  interface DocumentContainerProps {
505
714
  className?: string;
@@ -1020,6 +1229,24 @@ interface MinimapProps {
1020
1229
  */
1021
1230
  declare const Minimap: react.NamedExoticComponent<MinimapProps>;
1022
1231
 
1232
+ interface FloatingZoomControlsProps {
1233
+ /** Position of the controls */
1234
+ position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
1235
+ /** Additional class name */
1236
+ className?: string;
1237
+ /** Show fit to width button */
1238
+ showFitToWidth?: boolean;
1239
+ /** Show fit to page button */
1240
+ showFitToPage?: boolean;
1241
+ /** Show zoom percentage */
1242
+ showZoomLevel?: boolean;
1243
+ }
1244
+ /**
1245
+ * Floating zoom controls for easy zoom adjustment.
1246
+ * Shows +/- buttons and optionally fit-to-width/fit-to-page buttons.
1247
+ */
1248
+ declare const FloatingZoomControls: react.NamedExoticComponent<FloatingZoomControlsProps>;
1249
+
1023
1250
  interface PDFErrorBoundaryProps {
1024
1251
  /** Child components to render */
1025
1252
  children: ReactNode;
@@ -1058,6 +1285,8 @@ interface SearchActions {
1058
1285
  nextResult: () => void;
1059
1286
  previousResult: () => void;
1060
1287
  goToResult: (index: number) => void;
1288
+ setCaseSensitive: (value: boolean) => void;
1289
+ setWholeWord: (value: boolean) => void;
1061
1290
  toggleCaseSensitive: () => void;
1062
1291
  toggleWholeWord: () => void;
1063
1292
  getCurrentResult: () => SearchResult | null;
@@ -2032,4 +2261,4 @@ declare function createAgentAPI(stores: AgentAPIStores): AgentAPI;
2032
2261
  */
2033
2262
  type AgentAPIInstance = ReturnType<typeof createAgentAPI>;
2034
2263
 
2035
- 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 };
2264
+ export { type AddNoteOptions, 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 DrawCircleOptions, type DrawRectOptions, type DrawingAnnotation, DrawingCanvas, type DrawingCanvasProps, type DrawingPath, DualPageContainer, type DualPageContainerProps, type ExportData, FloatingZoomControls, type FloatingZoomControlsProps, FocusRegionLayer, type FocusRegionLayerProps, type FocusedRegion, 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, PDFViewer, PDFViewerClient, PDFViewerContext, type PDFViewerContextValue, type PDFViewerController, type PDFViewerControllerOptions, type PDFViewerEventMap, type PDFViewerHandle, 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, 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 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 };
package/dist/index.d.ts CHANGED
@@ -252,18 +252,20 @@ interface PDFViewerProps {
252
252
  src: string | ArrayBuffer | Uint8Array;
253
253
  /** Initial page number (1-indexed) */
254
254
  initialPage?: number;
255
- /** Initial scale/zoom level */
255
+ /** Initial scale/zoom level. Use 'auto' or 'page-width' to fit to container width. */
256
256
  initialScale?: number | 'page-fit' | 'page-width' | 'auto';
257
257
  /** Theme mode */
258
258
  theme?: 'light' | 'dark' | 'sepia';
259
259
  /** Custom class name */
260
260
  className?: string;
261
- /** Whether to show the toolbar */
261
+ /** Whether to show the toolbar (default: true) */
262
262
  showToolbar?: boolean;
263
- /** Whether to show the sidebar */
263
+ /** Whether to show the sidebar (default: true) */
264
264
  showSidebar?: boolean;
265
- /** Whether to show the annotation toolbar */
265
+ /** Whether to show the annotation toolbar (default: false) */
266
266
  showAnnotationToolbar?: boolean;
267
+ /** Whether to show floating zoom controls (default: true) */
268
+ showFloatingZoom?: boolean;
267
269
  /** Default sidebar panel */
268
270
  defaultSidebarPanel?: SidebarPanel;
269
271
  /** View mode for the document */
@@ -469,6 +471,196 @@ interface PDFViewerEventMap {
469
471
  textselect: TextSelection;
470
472
  error: Error;
471
473
  }
474
+ interface HighlightTextOptions {
475
+ /** Highlight color (default: 'yellow') */
476
+ color?: HighlightColor;
477
+ /** Only highlight on specific page (default: all pages) */
478
+ page?: number;
479
+ /** Case sensitive search (default: false) */
480
+ caseSensitive?: boolean;
481
+ /** Scroll to first match (default: true) */
482
+ scrollTo?: boolean;
483
+ }
484
+ interface DrawRectOptions {
485
+ /** Page number (1-indexed) */
486
+ page: number;
487
+ /** X coordinate (percentage of page width, 0-100) */
488
+ x: number;
489
+ /** Y coordinate (percentage of page height, 0-100) */
490
+ y: number;
491
+ /** Width (percentage of page width) */
492
+ width: number;
493
+ /** Height (percentage of page height) */
494
+ height: number;
495
+ /** Border color (default: 'blue') */
496
+ color?: string;
497
+ /** Border width in pixels (default: 2) */
498
+ strokeWidth?: number;
499
+ /** Fill color (optional, transparent if not set) */
500
+ fillColor?: string;
501
+ }
502
+ interface DrawCircleOptions {
503
+ /** Page number (1-indexed) */
504
+ page: number;
505
+ /** Center X coordinate (percentage of page width, 0-100) */
506
+ x: number;
507
+ /** Center Y coordinate (percentage of page height, 0-100) */
508
+ y: number;
509
+ /** Radius (percentage of page width) */
510
+ radius: number;
511
+ /** Border color (default: 'blue') */
512
+ color?: string;
513
+ /** Border width in pixels (default: 2) */
514
+ strokeWidth?: number;
515
+ /** Fill color (optional, transparent if not set) */
516
+ fillColor?: string;
517
+ }
518
+ interface AddNoteOptions {
519
+ /** Page number (1-indexed) */
520
+ page: number;
521
+ /** X coordinate (percentage of page width, 0-100) */
522
+ x: number;
523
+ /** Y coordinate (percentage of page height, 0-100) */
524
+ y: number;
525
+ /** Note content */
526
+ content: string;
527
+ /** Note color (default: 'yellow') */
528
+ color?: string;
529
+ }
530
+ interface SearchOptions {
531
+ /** Case sensitive search (default: false) */
532
+ caseSensitive?: boolean;
533
+ /** Match whole words only (default: false) */
534
+ wholeWord?: boolean;
535
+ /** Highlight all matches (default: true) */
536
+ highlightAll?: boolean;
537
+ }
538
+ /**
539
+ * Imperative handle for PDFViewerClient.
540
+ * Use this to programmatically control the PDF viewer.
541
+ *
542
+ * @example
543
+ * ```tsx
544
+ * const viewerRef = useRef<PDFViewerHandle>(null);
545
+ *
546
+ * // Highlight text
547
+ * viewerRef.current?.highlightText("important keyword");
548
+ *
549
+ * // Draw a rectangle
550
+ * viewerRef.current?.drawRect({ page: 1, x: 10, y: 20, width: 30, height: 10 });
551
+ *
552
+ * // Navigate
553
+ * viewerRef.current?.goToPage(5);
554
+ * ```
555
+ */
556
+ interface PDFViewerHandle {
557
+ /**
558
+ * Find and highlight text in the PDF.
559
+ * @param text - Text to find and highlight
560
+ * @param options - Highlight options
561
+ * @returns Array of highlight IDs created
562
+ */
563
+ highlightText: (text: string, options?: HighlightTextOptions) => Promise<string[]>;
564
+ /**
565
+ * Remove a specific highlight by ID.
566
+ */
567
+ removeHighlight: (id: string) => void;
568
+ /**
569
+ * Clear all highlights.
570
+ */
571
+ clearHighlights: () => void;
572
+ /**
573
+ * Draw a rectangle on the PDF.
574
+ * @param options - Rectangle options (coordinates are percentages 0-100)
575
+ * @returns Annotation ID
576
+ */
577
+ drawRect: (options: DrawRectOptions) => string;
578
+ /**
579
+ * Draw a circle on the PDF.
580
+ * @param options - Circle options (coordinates are percentages 0-100)
581
+ * @returns Annotation ID
582
+ */
583
+ drawCircle: (options: DrawCircleOptions) => string;
584
+ /**
585
+ * Add a note annotation.
586
+ * @param options - Note options
587
+ * @returns Annotation ID
588
+ */
589
+ addNote: (options: AddNoteOptions) => string;
590
+ /**
591
+ * Remove a specific annotation by ID.
592
+ */
593
+ removeAnnotation: (id: string) => void;
594
+ /**
595
+ * Clear all annotations.
596
+ */
597
+ clearAnnotations: () => void;
598
+ /**
599
+ * Go to a specific page.
600
+ * @param page - Page number (1-indexed)
601
+ */
602
+ goToPage: (page: number) => void;
603
+ /**
604
+ * Go to the next page.
605
+ */
606
+ nextPage: () => void;
607
+ /**
608
+ * Go to the previous page.
609
+ */
610
+ previousPage: () => void;
611
+ /**
612
+ * Get the current page number.
613
+ */
614
+ getCurrentPage: () => number;
615
+ /**
616
+ * Get total number of pages.
617
+ */
618
+ getNumPages: () => number;
619
+ /**
620
+ * Set the zoom level.
621
+ * @param scale - Zoom scale (1.0 = 100%)
622
+ */
623
+ setZoom: (scale: number) => void;
624
+ /**
625
+ * Get the current zoom level.
626
+ */
627
+ getZoom: () => number;
628
+ /**
629
+ * Zoom in.
630
+ */
631
+ zoomIn: () => void;
632
+ /**
633
+ * Zoom out.
634
+ */
635
+ zoomOut: () => void;
636
+ /**
637
+ * Search for text in the PDF.
638
+ * @param query - Search query
639
+ * @param options - Search options
640
+ * @returns Search results
641
+ */
642
+ search: (query: string, options?: SearchOptions) => Promise<SearchResult[]>;
643
+ /**
644
+ * Go to the next search result.
645
+ */
646
+ nextSearchResult: () => void;
647
+ /**
648
+ * Go to the previous search result.
649
+ */
650
+ previousSearchResult: () => void;
651
+ /**
652
+ * Clear search results.
653
+ */
654
+ clearSearch: () => void;
655
+ /**
656
+ * Get the underlying PDF document (pdfjs-dist PDFDocumentProxy).
657
+ */
658
+ getDocument: () => PDFDocumentProxy | null;
659
+ /**
660
+ * Check if the document is loaded.
661
+ */
662
+ isLoaded: () => boolean;
663
+ }
472
664
 
473
665
  /**
474
666
  * Main PDF Viewer component.
@@ -496,10 +688,27 @@ interface PDFViewerEventMap {
496
688
  declare const PDFViewer: react.NamedExoticComponent<PDFViewerProps>;
497
689
 
498
690
  /**
499
- * SSR-safe PDF Viewer component.
500
- * Wraps the inner viewer with the context provider.
691
+ * PDF Viewer component with imperative API.
692
+ *
693
+ * @example
694
+ * ```tsx
695
+ * const viewerRef = useRef<PDFViewerHandle>(null);
696
+ *
697
+ * <PDFViewerClient
698
+ * ref={viewerRef}
699
+ * src="/document.pdf"
700
+ * onDocumentLoad={() => {
701
+ * // Highlight text when document loads
702
+ * viewerRef.current?.highlightText("important", { color: "yellow" });
703
+ * }}
704
+ * />
705
+ *
706
+ * // Call methods anytime
707
+ * viewerRef.current?.goToPage(5);
708
+ * viewerRef.current?.drawRect({ page: 1, x: 10, y: 20, width: 30, height: 10 });
709
+ * ```
501
710
  */
502
- declare const PDFViewerClient: react.NamedExoticComponent<PDFViewerProps>;
711
+ declare const PDFViewerClient: react.MemoExoticComponent<react.ForwardRefExoticComponent<PDFViewerProps & react.RefAttributes<PDFViewerHandle>>>;
503
712
 
504
713
  interface DocumentContainerProps {
505
714
  className?: string;
@@ -1020,6 +1229,24 @@ interface MinimapProps {
1020
1229
  */
1021
1230
  declare const Minimap: react.NamedExoticComponent<MinimapProps>;
1022
1231
 
1232
+ interface FloatingZoomControlsProps {
1233
+ /** Position of the controls */
1234
+ position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
1235
+ /** Additional class name */
1236
+ className?: string;
1237
+ /** Show fit to width button */
1238
+ showFitToWidth?: boolean;
1239
+ /** Show fit to page button */
1240
+ showFitToPage?: boolean;
1241
+ /** Show zoom percentage */
1242
+ showZoomLevel?: boolean;
1243
+ }
1244
+ /**
1245
+ * Floating zoom controls for easy zoom adjustment.
1246
+ * Shows +/- buttons and optionally fit-to-width/fit-to-page buttons.
1247
+ */
1248
+ declare const FloatingZoomControls: react.NamedExoticComponent<FloatingZoomControlsProps>;
1249
+
1023
1250
  interface PDFErrorBoundaryProps {
1024
1251
  /** Child components to render */
1025
1252
  children: ReactNode;
@@ -1058,6 +1285,8 @@ interface SearchActions {
1058
1285
  nextResult: () => void;
1059
1286
  previousResult: () => void;
1060
1287
  goToResult: (index: number) => void;
1288
+ setCaseSensitive: (value: boolean) => void;
1289
+ setWholeWord: (value: boolean) => void;
1061
1290
  toggleCaseSensitive: () => void;
1062
1291
  toggleWholeWord: () => void;
1063
1292
  getCurrentResult: () => SearchResult | null;
@@ -2032,4 +2261,4 @@ declare function createAgentAPI(stores: AgentAPIStores): AgentAPI;
2032
2261
  */
2033
2262
  type AgentAPIInstance = ReturnType<typeof createAgentAPI>;
2034
2263
 
2035
- 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 };
2264
+ export { type AddNoteOptions, 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 DrawCircleOptions, type DrawRectOptions, type DrawingAnnotation, DrawingCanvas, type DrawingCanvasProps, type DrawingPath, DualPageContainer, type DualPageContainerProps, type ExportData, FloatingZoomControls, type FloatingZoomControlsProps, FocusRegionLayer, type FocusRegionLayerProps, type FocusedRegion, 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, PDFViewer, PDFViewerClient, PDFViewerContext, type PDFViewerContextValue, type PDFViewerController, type PDFViewerControllerOptions, type PDFViewerEventMap, type PDFViewerHandle, 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, 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 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 };