pdfjs-reader-core 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -8,6 +8,244 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as pdfjs_dist_types_src_display_api from 'pdfjs-dist/types/src/display/api';
 import { ClassValue } from 'clsx';
 import * as pdfjs_dist_types_src_display_metadata from 'pdfjs-dist/types/src/display/metadata';
+import { StoreApi } from 'zustand/vanilla';
+
+/**
+ * Context provided by an external AI agent during interaction
+ */
+interface AgentContext {
+    /** The last statement or response from the agent */
+    lastStatement?: string;
+    /** Unique identifier for the conversation session */
+    conversationId?: string;
+    /** Timestamp of the context */
+    timestamp: Date;
+    /** Additional metadata from the agent */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Context passed when user triggers "Ask About This" feature
+ */
+interface AskAboutContext {
+    /** Type of content being asked about */
+    type: 'text' | 'region';
+    /** Page number where the selection is made */
+    pageNumber: number;
+    /** Selected text content (for text type) */
+    selectedText?: string;
+    /** Selected region coordinates (for region type) */
+    region?: PDFRegion;
+    /** Current agent context when asking */
+    agentContext?: AgentContext;
+}
+/**
+ * Represents a rectangular region on a PDF page
+ */
+interface PDFRegion {
+    /** X coordinate (from left) */
+    x: number;
+    /** Y coordinate (from top) */
+    y: number;
+    /** Width of the region */
+    width: number;
+    /** Height of the region */
+    height: number;
+}
+/**
+ * A focused region with visual styling, typically used by AI agent
+ * to highlight content being discussed
+ */
+interface FocusedRegion extends PDFRegion {
+    /** Unique identifier for this focus region */
+    id: string;
+    /** Page number where the region is located */
+    pageNumber: number;
+    /** Visual style for the focus indicator */
+    style?: 'pulse' | 'glow' | 'border';
+    /** Color of the focus indicator */
+    color?: string;
+    /** Auto-clear timeout in milliseconds (0 = no auto-clear) */
+    autoClearTimeout?: number;
+}
+/**
+ * A bookmark saved by the student
+ */
+interface Bookmark {
+    /** Unique identifier */
+    id: string;
+    /** Page number of the bookmark */
+    pageNumber: number;
+    /** When the bookmark was created */
+    timestamp: Date;
+    /** Agent's last statement when bookmarking (captured from context) */
+    agentContext?: string;
+    /** User's personal note about the bookmark */
+    userNote?: string;
+    /** Optional label for the bookmark */
+    label?: string;
+}
+/**
+ * A quick note added by the student
+ */
+interface QuickNote {
+    /** Unique identifier */
+    id: string;
+    /** Page number where the note is placed */
+    pageNumber: number;
+    /** X coordinate on the page */
+    x: number;
+    /** Y coordinate on the page */
+    y: number;
+    /** Note content */
+    content: string;
+    /** When the note was created */
+    timestamp: Date;
+    /** Agent's last statement when creating note */
+    agentLastStatement?: string;
+}
+/**
+ * A key takeaway or summary, typically from the AI agent
+ */
+interface Takeaway {
+    /** Unique identifier */
+    id: string;
+    /** Page number associated with this takeaway */
+    pageNumber: number;
+    /** Summary content */
+    summary: string;
+    /** When the takeaway was added */
+    timestamp: Date;
+    /** Source of the takeaway */
+    source: 'agent' | 'user';
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for creating an agent-sourced highlight
+ */
+interface AgentHighlightParams {
+    /** Page number for the highlight */
+    pageNumber: number;
+    /** Rectangles defining the highlight area */
+    rects: HighlightRect[];
+    /** Text content being highlighted */
+    text: string;
+    /** Highlight color */
+    color?: HighlightColor;
+    /** Optional comment */
+    comment?: string;
+}
+/**
+ * API exposed to external AI agents for interacting with the PDF viewer
+ */
+interface AgentAPI {
+    /**
+     * Focus a region on the page (visual indicator of what agent is discussing)
+     * @returns The ID of the focused region
+     */
+    focusRegion: (region: Omit<FocusedRegion, 'id'>) => string;
+    /**
+     * Clear a focused region by ID, or all if no ID provided
+     */
+    clearFocusedRegion: (id?: string) => void;
+    /**
+     * Add a key takeaway for a page
+     */
+    addTakeaway: (pageNumber: number, summary: string, metadata?: Record<string, unknown>) => Takeaway;
+    /**
+     * Set the current agent context
+     */
+    setAgentContext: (context: Partial<AgentContext>) => void;
+    /**
+     * Add a highlight from the agent (marked with source: 'agent')
+     */
+    addAgentHighlight: (params: AgentHighlightParams) => string;
+    /**
+     * Navigate to a specific page
+     */
+    goToPage: (pageNumber: number) => void;
+    /**
+     * Get current page number
+     */
+    getCurrentPage: () => number;
+    /**
+     * Get current agent context
+     */
+    getAgentContext: () => AgentContext | null;
+}
+interface StudentState {
+    /** User's bookmarks */
+    bookmarks: Bookmark[];
+    /** User's quick notes */
+    quickNotes: QuickNote[];
+    /** Key takeaways (from agent or user) */
+    takeaways: Takeaway[];
+    /** Pages the user has visited */
+    visitedPages: Set<number>;
+    /** Reading progress (0-1) */
+    progress: number;
+}
+interface StudentActions {
+    addBookmark: (bookmark: Omit<Bookmark, 'id' | 'timestamp'>) => Bookmark;
+    updateBookmark: (id: string, updates: Partial<Omit<Bookmark, 'id'>>) => void;
+    removeBookmark: (id: string) => void;
+    addQuickNote: (note: Omit<QuickNote, 'id' | 'timestamp'>) => QuickNote;
+    updateQuickNote: (id: string, updates: Partial<Omit<QuickNote, 'id'>>) => void;
+    removeQuickNote: (id: string) => void;
+    addTakeaway: (takeaway: Omit<Takeaway, 'id' | 'timestamp'>) => Takeaway;
+    removeTakeaway: (id: string) => void;
+    markPageVisited: (pageNumber: number) => void;
+    setProgress: (progress: number) => void;
+    persistToStorage: (documentId: string) => void;
+    loadFromStorage: (documentId: string) => void;
+    reset: () => void;
+}
+interface AgentState {
+    /** Current agent context */
+    currentContext: AgentContext | null;
+    /** Currently focused regions */
+    focusedRegions: FocusedRegion[];
+}
+interface AgentActions {
+    /** Set the current agent context */
+    setAgentContext: (context: Partial<AgentContext>) => void;
+    /** Clear the agent context */
+    clearAgentContext: () => void;
+    /** Add a focused region */
+    addFocusedRegion: (region: Omit<FocusedRegion, 'id'>) => string;
+    /** Remove a focused region by ID */
+    removeFocusedRegion: (id: string) => void;
+    /** Clear all focused regions */
+    clearAllFocusedRegions: () => void;
+    /** Reset agent state */
+    reset: () => void;
+}
+interface StudentModeCallbacks {
+    /** Callback when user triggers "Ask About This" */
+    onAskAbout?: (context: AskAboutContext) => void;
+    /** Callback when a bookmark is added */
+    onBookmarkAdd?: (bookmark: Bookmark) => void;
+    /** Callback when a quick note is added */
+    onQuickNoteAdd?: (note: QuickNote) => void;
+}
+interface StudentModeProps {
+    /** Enable student learning mode features */
+    studentMode?: boolean;
+    /** Callbacks for agent integration */
+    agentCallbacks?: StudentModeCallbacks;
+    /** Initial agent context */
+    initialAgentContext?: AgentContext;
+    /** Show quick note buttons on pages */
+    showQuickNoteButtons?: boolean;
+    /** Show the minimap */
+    showMinimap?: boolean;
+    /** Position of the minimap */
+    minimapPosition?: 'sidebar' | 'floating';
+    /** Enable "Ask About This" feature */
+    enableAskAbout?: boolean;
+    /** Long press duration for ask about trigger (ms) */
+    askAboutLongPressDuration?: number;
+}
 
 interface PDFViewerProps {
     /** URL or ArrayBuffer of the PDF file */
@@ -121,6 +359,8 @@ interface Highlight {
     comment?: string;
     createdAt: Date;
     updatedAt: Date;
+    /** Source of the highlight: user-created or agent-created */
+    source?: 'user' | 'agent';
 }
 interface HighlightRect {
     x: number;
@@ -277,6 +517,16 @@ interface VirtualizedDocumentContainerProps {
     enableTouchGestures?: boolean;
     className?: string;
 }
+/**
+ * VirtualizedDocumentContainer efficiently renders only visible pages.
+ *
+ * Mobile optimizations:
+ * - Only pages in/near viewport are rendered (virtualization)
+ * - Smooth scrolling with -webkit-overflow-scrolling
+ * - Touch gestures for pinch-zoom and swipe navigation
+ * - Passive event listeners for scroll performance
+ * - Smart page caching to avoid re-fetching
+ */
 declare const VirtualizedDocumentContainer: react.NamedExoticComponent<VirtualizedDocumentContainerProps>;
 
 interface ContinuousScrollContainerProps extends VirtualizedDocumentContainerProps {
@@ -338,7 +588,18 @@ interface CanvasLayerProps {
     onRenderStart?: () => void;
     onRenderComplete?: () => void;
     onRenderError?: (error: Error) => void;
+    /** Priority for rendering (lower = higher priority) - used for render ordering */
+    priority?: number;
 }
+/**
+ * CanvasLayer renders a PDF page at full quality.
+ *
+ * Optimizations for mobile:
+ * - Uses requestAnimationFrame for render timing
+ * - Cancels pending renders on unmount/update
+ * - Uses 'display' intent for faster rendering
+ * - Disables alpha channel for better performance
+ */
 declare const CanvasLayer: react.NamedExoticComponent<CanvasLayerProps>;
 
 interface TextLayerProps {
@@ -355,6 +616,8 @@ interface HighlightLayerProps {
     selectedId?: string | null;
     onHighlightClick?: (highlight: Highlight) => void;
     className?: string;
+    /** Filter by source type */
+    sourceFilter?: 'all' | 'user' | 'agent';
 }
 declare const HighlightLayer: react.NamedExoticComponent<HighlightLayerProps>;
 
@@ -390,6 +653,14 @@ interface AnnotationLayerProps {
 }
 declare const AnnotationLayer: react.NamedExoticComponent<AnnotationLayerProps>;
 
+interface FocusRegionLayerProps {
+    focusedRegions: FocusedRegion[];
+    scale: number;
+    pageNumber: number;
+    className?: string;
+}
+declare const FocusRegionLayer: react.NamedExoticComponent<FocusRegionLayerProps>;
+
 interface ToolbarProps {
     className?: string;
     showNavigation?: boolean;
@@ -458,6 +729,22 @@ interface HighlightsPanelProps {
 }
 declare const HighlightsPanel: react.NamedExoticComponent<HighlightsPanelProps>;
 
+interface BookmarksPanelProps {
+    className?: string;
+    /** Callback when a bookmark item is clicked */
+    onBookmarkClick?: (bookmark: Bookmark) => void;
+}
+declare const BookmarksPanel: react.NamedExoticComponent<BookmarksPanelProps>;
+
+interface TakeawaysPanelProps {
+    className?: string;
+    /** Callback when a takeaway item is clicked */
+    onTakeawayClick?: (takeaway: Takeaway) => void;
+    /** Filter by source */
+    sourceFilter?: 'all' | 'agent' | 'user';
+}
+declare const TakeawaysPanel: react.NamedExoticComponent<TakeawaysPanelProps>;
+
 interface SelectionToolbarProps {
     /** Current text selection */
     selection: TextSelection | null;
@@ -627,6 +914,112 @@ interface ShapePreviewProps {
 }
 declare const ShapePreview: react.NamedExoticComponent<ShapePreviewProps>;
 
+interface QuickNoteButtonProps {
+    /** Page number this button is for */
+    pageNumber: number;
+    /** Scale of the page */
+    scale: number;
+    /** Position of the button (relative to page) */
+    position?: 'top-right' | 'bottom-right';
+    /** Callback when button is clicked */
+    onClick: (pageNumber: number, x: number, y: number) => void;
+    /** Custom className */
+    className?: string;
+    /** Whether the button is visible */
+    visible?: boolean;
+}
+/**
+ * Floating button on each page to quickly add a note.
+ */
+declare const QuickNoteButton: react.NamedExoticComponent<QuickNoteButtonProps>;
+
+interface QuickNotePopoverProps {
+    /** Whether the popover is visible */
+    visible: boolean;
+    /** Position of the popover */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Initial content */
+    initialContent?: string;
+    /** Agent's last statement to display */
+    agentLastStatement?: string;
+    /** Callback when note is saved */
+    onSave: (content: string) => void;
+    /** Callback when cancelled */
+    onCancel: () => void;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Popover for entering quick note content.
+ */
+declare const QuickNotePopover: react.NamedExoticComponent<QuickNotePopoverProps>;
+
+interface AskAboutOverlayProps {
+    /** Whether the overlay is visible */
+    visible: boolean;
+    /** Progress of the long press (0-1) */
+    progress: number;
+    /** Position of the overlay */
+    position: {
+        x: number;
+        y: number;
+    } | null;
+    /** Size of the progress indicator */
+    size?: number;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Visual feedback overlay shown during long-press for "Ask About This" feature.
+ * Displays a circular progress indicator.
+ */
+declare const AskAboutOverlay: react.NamedExoticComponent<AskAboutOverlayProps>;
+
+interface AskAboutTriggerProps {
+    /** Position to display the trigger */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Callback when ask about is confirmed */
+    onConfirm: () => void;
+    /** Callback when cancelled */
+    onCancel: () => void;
+    /** Whether to show the trigger */
+    visible: boolean;
+    /** Auto-hide delay in ms (0 = no auto-hide) */
+    autoHideDelay?: number;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Confirmation UI shown after long-press completes.
+ * Provides buttons to confirm or cancel the "Ask About This" action.
+ */
+declare const AskAboutTrigger: react.NamedExoticComponent<AskAboutTriggerProps>;
+
+interface MinimapProps {
+    /** Display variant */
+    variant?: 'sidebar' | 'floating';
+    /** Position for floating variant */
+    floatingPosition?: 'left' | 'right';
+    /** Maximum height in pixels */
+    maxHeight?: number;
+    /** Whether to show page numbers */
+    showPageNumbers?: boolean;
+    /** Callback when a page is clicked */
+    onPageClick?: (pageNumber: number) => void;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Visual minimap showing reading progress and navigation.
+ */
+declare const Minimap: react.NamedExoticComponent<MinimapProps>;
+
 interface PDFErrorBoundaryProps {
     /** Child components to render */
     children: ReactNode;
@@ -673,10 +1066,20 @@ type SearchStore = SearchState & SearchActions;
 declare function createSearchStore(initialOverrides?: Partial<SearchState>): zustand.StoreApi<SearchStore>;
 type SearchStoreApi = ReturnType<typeof createSearchStore>;
 
+type AgentStore = AgentState & AgentActions;
+declare function createAgentStore(initialOverrides?: Partial<AgentState>): zustand.StoreApi<AgentStore>;
+type AgentStoreApi = ReturnType<typeof createAgentStore>;
+
+type StudentStore = StudentState & StudentActions;
+declare function createStudentStore(initialOverrides?: Partial<StudentState>): zustand.StoreApi<StudentStore>;
+type StudentStoreApi = ReturnType<typeof createStudentStore>;
+
 interface PDFViewerContextValue {
     viewerStore: ViewerStoreApi;
     annotationStore: AnnotationStoreApi;
     searchStore: SearchStoreApi;
+    agentStore: AgentStoreApi;
+    studentStore: StudentStoreApi;
 }
 interface PDFViewerProviderProps {
     children: ReactNode;
@@ -684,12 +1087,16 @@ interface PDFViewerProviderProps {
         viewer?: Partial<ViewerState>;
         annotation?: Partial<AnnotationState>;
         search?: Partial<SearchState>;
+        agent?: Partial<AgentState>;
+        student?: Partial<StudentState>;
     };
     theme?: Theme;
     defaultSidebarPanel?: SidebarPanel;
+    /** Enable student learning mode features */
+    studentMode?: boolean;
 }
 declare const PDFViewerContext: react.Context<PDFViewerContextValue | null>;
-declare function PDFViewerProvider({ children, initialState, theme, defaultSidebarPanel, }: PDFViewerProviderProps): react_jsx_runtime.JSX.Element;
+declare function PDFViewerProvider({ children, initialState, theme, defaultSidebarPanel, studentMode: _studentMode, }: PDFViewerProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access the viewer store.
  * Optionally pass a selector to subscribe to specific state.
@@ -705,6 +1112,16 @@ declare function useAnnotationStore<T>(selector: (state: AnnotationStore) => T):
  * Optionally pass a selector to subscribe to specific state.
  */
 declare function useSearchStore<T>(selector: (state: SearchStore) => T): T;
+/**
+ * Hook to access the agent store.
+ * Optionally pass a selector to subscribe to specific state.
+ */
+declare function useAgentStore<T>(selector: (state: AgentStore) => T): T;
+/**
+ * Hook to access the student store.
+ * Optionally pass a selector to subscribe to specific state.
+ */
+declare function useStudentStore<T>(selector: (state: StudentStore) => T): T;
 /**
  * Hook to access all stores directly (for actions).
  */
@@ -760,6 +1177,28 @@ declare function usePDFViewer(): {
     clearSearch: () => void;
     nextSearchResult: () => void;
     previousSearchResult: () => void;
+    agentContext: AgentContext | null;
+    setAgentContext: (context: Partial<AgentContext>) => void;
+    clearAgentContext: () => void;
+    focusedRegions: FocusedRegion[];
+    focusRegion: (region: Omit<FocusedRegion, "id">) => string;
+    clearFocusedRegion: (id: string) => void;
+    clearAllFocusedRegions: () => void;
+    getAgentAPI: () => AgentAPI;
+    bookmarks: Bookmark[];
+    addBookmark: (data: Omit<Bookmark, "id" | "timestamp">) => Bookmark;
+    updateBookmark: (id: string, updates: Partial<Omit<Bookmark, "id">>) => void;
+    removeBookmark: (id: string) => void;
+    quickNotes: QuickNote[];
+    addQuickNote: (data: Omit<QuickNote, "id" | "timestamp">) => QuickNote;
+    updateQuickNote: (id: string, updates: Partial<Omit<QuickNote, "id">>) => void;
+    removeQuickNote: (id: string) => void;
+    takeaways: Takeaway[];
+    addTakeaway: (data: Omit<Takeaway, "id" | "timestamp">) => Takeaway;
+    removeTakeaway: (id: string) => void;
+    visitedPages: Set<number>;
+    progress: number;
+    markPageVisited: (pageNumber: number) => void;
 };
 
 interface UsePageNavigationOptions {
@@ -1079,6 +1518,190 @@ interface UsePluginsReturn {
 }
 declare function usePlugins(options?: UsePluginsOptions): UsePluginsReturn;
 
+interface UseAgentContextOptions {
+    /** Default focus region style */
+    defaultFocusStyle?: 'pulse' | 'glow' | 'border';
+    /** Default focus region color */
+    defaultFocusColor?: string;
+    /** Default auto-clear timeout for focus regions (ms) */
+    defaultAutoClearTimeout?: number;
+}
+interface UseAgentContextReturn {
+    /** Current agent context */
+    agentContext: AgentContext | null;
+    /** Set or update agent context */
+    setAgentContext: (context: Partial<AgentContext>) => void;
+    /** Clear agent context */
+    clearAgentContext: () => void;
+    /** Currently focused regions */
+    focusedRegions: FocusedRegion[];
+    /** Add a focus region and return its ID */
+    focusRegion: (region: Omit<FocusedRegion, 'id'>) => string;
+    /** Remove a focus region by ID */
+    clearFocusedRegion: (id: string) => void;
+    /** Clear all focus regions */
+    clearAllFocusedRegions: () => void;
+    /** Add a takeaway for a page */
+    addTakeaway: (pageNumber: number, summary: string, metadata?: Record<string, unknown>) => Takeaway;
+    /** Add a highlight from the agent */
+    addAgentHighlight: (params: AgentHighlightParams) => string;
+    /** Get the agent API for external integration */
+    getAgentAPI: () => AgentAPI;
+}
+/**
+ * Hook for agent context management and AI agent integration.
+ * Provides methods for agents to interact with the PDF viewer.
+ */
+declare function useAgentContext(options?: UseAgentContextOptions): UseAgentContextReturn;
+
+interface UseAskAboutOptions {
+    /** Whether the feature is enabled */
+    enabled?: boolean;
+    /** Long press duration to trigger ask about (ms) */
+    longPressDuration?: number;
+    /** Callback when ask about is triggered */
+    onAskAbout?: (context: AskAboutContext) => void;
+    /** Minimum selection length to enable ask about for text */
+    minSelectionLength?: number;
+}
+interface UseAskAboutReturn {
+    /** Whether ask about is currently in progress (long press active) */
+    isLongPressing: boolean;
+    /** Progress of the long press (0-1) */
+    longPressProgress: number;
+    /** Position of the long press */
+    longPressPosition: {
+        x: number;
+        y: number;
+    } | null;
+    /** Trigger ask about for selected text */
+    askAboutSelection: (text: string, pageNumber: number) => void;
+    /** Trigger ask about for a region (diagram, image) */
+    askAboutRegion: (region: PDFRegion, pageNumber: number) => void;
+    /** Start long press tracking (for custom implementations) */
+    startLongPress: (x: number, y: number) => void;
+    /** Cancel long press */
+    cancelLongPress: () => void;
+    /** Complete long press and trigger callback */
+    completeLongPress: (type: 'text' | 'region', pageNumber: number, text?: string, region?: PDFRegion) => void;
+    /** Handlers for attaching to elements */
+    handlers: {
+        onMouseDown: (e: React.MouseEvent) => void;
+        onMouseUp: () => void;
+        onMouseLeave: () => void;
+        onTouchStart: (e: React.TouchEvent) => void;
+        onTouchEnd: () => void;
+        onTouchCancel: () => void;
+    };
+}
+/**
+ * Hook for implementing the "Ask About This" feature.
+ * Provides long-press detection and callbacks for asking about text or regions.
+ */
+declare function useAskAbout(options?: UseAskAboutOptions): UseAskAboutReturn;
+
+interface UseBookmarksOptions {
+    /** Callback when bookmark is added */
+    onBookmarkAdd?: (bookmark: Bookmark) => void;
+    /** Callback when bookmark is removed */
+    onBookmarkRemove?: (id: string) => void;
+    /** Automatically capture agent context when bookmarking */
+    captureAgentContext?: boolean;
+}
+interface UseBookmarksReturn {
+    /** All bookmarks */
+    bookmarks: Bookmark[];
+    /** Bookmarks for the current page */
+    currentPageBookmarks: Bookmark[];
+    /** Check if current page is bookmarked */
+    isCurrentPageBookmarked: boolean;
+    /** Add a bookmark */
+    addBookmark: (data?: Partial<Omit<Bookmark, 'id' | 'timestamp'>>) => Bookmark;
+    /** Update a bookmark */
+    updateBookmark: (id: string, updates: Partial<Omit<Bookmark, 'id'>>) => void;
+    /** Remove a bookmark */
+    removeBookmark: (id: string) => void;
+    /** Toggle bookmark on current page */
+    toggleBookmark: () => void;
+    /** Navigate to a bookmarked page */
+    goToBookmark: (bookmark: Bookmark) => void;
+    /** Get bookmarks for a specific page */
+    getBookmarksForPage: (pageNumber: number) => Bookmark[];
+    /** Get bookmarks grouped by page */
+    bookmarksByPage: Map<number, Bookmark[]>;
+}
+/**
+ * Hook for managing bookmarks with agent context capture.
+ */
+declare function useBookmarks(options?: UseBookmarksOptions): UseBookmarksReturn;
+
+interface UseQuickNotesOptions {
+    /** Callback when note is added */
+    onNoteAdd?: (note: QuickNote) => void;
+    /** Callback when note is removed */
+    onNoteRemove?: (id: string) => void;
+    /** Automatically capture agent's last statement when creating notes */
+    captureAgentContext?: boolean;
+}
+interface UseQuickNotesReturn {
+    /** All quick notes */
+    quickNotes: QuickNote[];
+    /** Quick notes for the current page */
+    currentPageNotes: QuickNote[];
+    /** Add a quick note */
+    addQuickNote: (data: {
+        content: string;
+        x: number;
+        y: number;
+        pageNumber?: number;
+    }) => QuickNote;
+    /** Update a quick note */
+    updateQuickNote: (id: string, updates: Partial<Omit<QuickNote, 'id'>>) => void;
+    /** Remove a quick note */
+    removeQuickNote: (id: string) => void;
+    /** Get notes for a specific page */
+    getNotesForPage: (pageNumber: number) => QuickNote[];
+    /** Notes grouped by page */
+    notesByPage: Map<number, QuickNote[]>;
+}
+/**
+ * Hook for managing quick notes with agent context capture.
+ */
+declare function useQuickNotes(options?: UseQuickNotesOptions): UseQuickNotesReturn;
+
+interface UseStudentProgressOptions {
+    /** Automatically track page visits */
+    autoTrack?: boolean;
+    /** Debounce time for page tracking (ms) */
+    trackDebounce?: number;
+}
+interface UseStudentProgressReturn {
+    /** Set of visited page numbers */
+    visitedPages: Set<number>;
+    /** Array of visited page numbers (for easier iteration) */
+    visitedPagesArray: number[];
+    /** Current reading progress (0-1) */
+    progress: number;
+    /** Percentage of pages visited */
+    visitedPercentage: number;
+    /** Number of pages visited */
+    visitedCount: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Current page number */
+    currentPage: number;
+    /** Mark a page as visited */
+    markPageVisited: (pageNumber: number) => void;
+    /** Check if a page has been visited */
+    isPageVisited: (pageNumber: number) => boolean;
+    /** Get page visit status for minimap rendering */
+    getPageStatus: (pageNumber: number) => 'current' | 'visited' | 'unvisited';
+}
+/**
+ * Hook for tracking student reading progress.
+ */
+declare function useStudentProgress(options?: UseStudentProgressOptions): UseStudentProgressReturn;
+
 /**
  * Utility for merging class names with support for conditionals.
  * Uses clsx under the hood.
@@ -1113,6 +1736,12 @@ interface LoadDocumentOptions {
         loaded: number;
         total: number;
     }) => void;
+    /** Enable range requests for faster loading (default: true) */
+    enableRangeRequests?: boolean;
+    /** Enable streaming for progressive display (default: true) */
+    enableStreaming?: boolean;
+    /** Cache the document data (default: true) */
+    cacheDocument?: boolean;
 }
 interface LoadDocumentResult {
     document: PDFDocumentProxy;
@@ -1120,6 +1749,12 @@ interface LoadDocumentResult {
 }
 /**
  * Load a PDF document from a URL or data buffer.
+ *
+ * Optimizations:
+ * - Range requests allow loading only the parts needed (faster initial load)
+ * - Streaming allows pages to render as data arrives
+ * - Document caching prevents duplicate fetches
+ * - Worker handles parsing off the main thread
  */
 declare function loadDocument(options: LoadDocumentOptions): Promise<LoadDocumentResult>;
 /**
@@ -1289,4 +1924,112 @@ declare function createPDFViewer(container: HTMLElement, options?: PDFViewerCont
  */
 declare function quickViewer(container: HTMLElement | string, src: string | ArrayBuffer | Uint8Array, options?: Partial<PDFViewerControllerOptions>): Promise<PDFViewerController>;
 
-export { type Annotation, type AnnotationActions, AnnotationLayer, type AnnotationLayerProps, type AnnotationState, type AnnotationStore, type AnnotationStoreApi, type AnnotationTool, AnnotationToolbar, type AnnotationToolbarProps, type AnnotationType, CanvasLayer, type CanvasLayerProps, type ContextMenuItem, ContinuousScrollContainer, type ContinuousScrollContainerProps, DocumentContainer, type DocumentContainerProps, type DrawingAnnotation, DrawingCanvas, type DrawingCanvasProps, type DrawingPath, DualPageContainer, type DualPageContainerProps, type Highlight, type HighlightColor, HighlightLayer, type HighlightLayerProps, HighlightPopover, type HighlightPopoverProps, type HighlightRect, HighlightsPanel, type HighlightsPanelProps, type LoadDocumentOptions, type LoadDocumentResult, MobileSidebar, type MobileSidebarProps, MobileToolbar, type MobileToolbarProps, type NoteAnnotation, type OutlineItem, OutlinePanel, type OutlinePanelProps, type PDFDocumentLoadedEvent, PDFErrorBoundary, type PDFErrorBoundaryProps, PDFPage, type PDFPageProps, type PDFPageState, 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 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, TextLayer, type TextLayerProps, type TextSelection, type Theme, ThumbnailPanel, type ThumbnailPanelProps, Toolbar, type ToolbarItem, type ToolbarProps, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseHighlightsOptions, type UseHighlightsReturn, type UsePageNavigationOptions, type UsePluginsOptions, type UsePluginsReturn, type UseTextSelectionOptions, type UseTouchGesturesOptions, type UseZoomOptions, type ViewMode, type ViewerActions, type ViewerState, type ViewerStore, type ViewerStoreApi, VirtualizedDocumentContainer, type VirtualizedDocumentContainerProps, type WithErrorBoundaryProps, clearHighlights, cn, createAnnotationStore, createPDFViewer, createPluginManager, createSearchStore, createViewerStore, exportHighlightsAsJSON, exportHighlightsAsMarkdown, generateDocumentId, getAllDocumentIds, getMetadata, getOutline, getPage, getPageTextContent, getPluginManager, importHighlightsFromJSON, initializePDFJS, isPDFJSInitialized, loadDocument, loadHighlights, quickViewer, saveHighlights, useAnnotationStore, useAnnotations, useHighlights, useIsMobile, useIsTouchDevice, usePDFViewer, usePDFViewerStores, usePageNavigation, usePlugins, useSearchStore, useTextSelection, useTouchGestures, useViewerStore, useZoom, withErrorBoundary };
+interface ExportData {
+    highlights?: Highlight[];
+    bookmarks?: Bookmark[];
+    quickNotes?: QuickNote[];
+    takeaways?: Takeaway[];
+    documentTitle?: string;
+}
+/**
+ * Export all annotations as a comprehensive Markdown document.
+ * Organizes content by page with highlights, notes, bookmarks, and takeaways.
+ */
+declare function exportAnnotationsAsMarkdown(data: ExportData): string;
+/**
+ * Export all annotations as JSON.
+ */
+declare function exportAnnotationsAsJSON(data: ExportData): string;
+/**
+ * Download content as a file.
+ */
+declare function downloadFile(content: string, filename: string, mimeType: string): void;
+/**
+ * Export annotations as Markdown and trigger download.
+ */
+declare function downloadAnnotationsAsMarkdown(data: ExportData, filename?: string): void;
+/**
+ * Export annotations as JSON and trigger download.
+ */
+declare function downloadAnnotationsAsJSON(data: ExportData, filename?: string): void;
+
+interface StoredBookmark extends Omit<Bookmark, 'timestamp'> {
+    timestamp: string;
+}
+interface StoredQuickNote extends Omit<QuickNote, 'timestamp'> {
+    timestamp: string;
+}
+interface StoredTakeaway extends Omit<Takeaway, 'timestamp'> {
+    timestamp: string;
+}
+interface StoredStudentData {
+    bookmarks: StoredBookmark[];
+    quickNotes: StoredQuickNote[];
+    takeaways: StoredTakeaway[];
+    visitedPages: number[];
+    progress: number;
+    lastAccessed: string;
+}
+interface StudentData {
+    bookmarks: Bookmark[];
+    quickNotes: QuickNote[];
+    takeaways: Takeaway[];
+    visitedPages: Set<number>;
+    progress: number;
+    lastAccessed: Date;
+}
+/**
+ * Save student data to localStorage.
+ */
+declare function saveStudentData(documentId: string, data: StudentData): boolean;
+/**
+ * Load student data from localStorage.
+ */
+declare function loadStudentData(documentId: string): StudentData | null;
+/**
+ * Clear student data for a specific document.
+ */
+declare function clearStudentData(documentId: string): boolean;
+/**
+ * Get all document IDs that have stored student data.
+ */
+declare function getAllStudentDataDocumentIds(): string[];
+/**
+ * Get storage usage statistics.
+ */
+declare function getStorageStats(): {
+    usedBytes: number;
+    itemCount: number;
+};
+
+interface AgentAPIStores {
+    agentStore: StoreApi<AgentStore>;
+    studentStore: StoreApi<StudentStore>;
+    viewerStore: StoreApi<ViewerStore>;
+    annotationStore: StoreApi<AnnotationStore>;
+}
+/**
+ * Create a standalone Agent API for external AI agent integration.
+ * This allows external agents to interact with the PDF viewer without
+ * needing direct access to React hooks.
+ *
+ * @example
+ * ```typescript
+ * import { createAgentAPI } from 'pdfjs-reader-core';
+ *
+ * // Get stores from the context (this would typically be done in a React component)
+ * const api = createAgentAPI(stores);
+ *
+ * // Now the external agent can use the API
+ * api.setAgentContext({ lastStatement: "The mitochondria is the powerhouse of the cell" });
+ * api.focusRegion({ pageNumber: 1, x: 100, y: 200, width: 300, height: 50, style: 'pulse' });
+ * api.addTakeaway(1, "Key concept: Cell energy production");
+ * ```
+ */
+declare function createAgentAPI(stores: AgentAPIStores): AgentAPI;
+/**
+ * Convenience type for the return value of createAgentAPI
+ */
+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 };