teamsync-pdf-viewer 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
+## [1.3.0] — 2026-09-04
+
+### Added
+- **Programmatic & Reactive Page Navigation**: Added `instance.goToPage(pageNumber, options?)` and `instance.setCurrentPage(pageNumber)` (also available via `instance.UI.setCurrentPageNumber` and `instance.Core.documentViewer.goToPage`). Added reactive navigation when `page` or `initialPage` props update on `<TeamSyncViewer>` or `<DocumentViewer>` while the viewer is already open, enabling citation jumping without reopening documents.
+- **Exported Text Search Utilities**: Extracted standalone asynchronous search function `searchPdfText(pdfDoc, query, redactions?, onProgress?)` and exported `usePdfSearch`, `searchPdfText`, `SearchResult`, and `SearchBounds` from the library root. Added `instance.searchText(query)` to execute document searches programmatically.
+- **Transient Citation Highlights Layer**: Added dedicated transient highlights system (`TransientHighlight`, `instance.setTransientHighlights`, `instance.getTransientHighlights`, `instance.addTransientHighlight`, `instance.clearTransientHighlights`, and `instance.highlightSnippet`). Highlights render on an isolated overlay layer with pulse animations and tooltips without polluting `AnnotationManager`, `getAnnotations()`, or XFDF exports.
+
 ## [1.2.1] — 2026-09-01
 
 ### Fixed

package/dist/src/components/DiffSummarySidebar.d.ts

@@ -6,7 +6,7 @@ interface DiffSummarySidebarProps {
     diffItems: DiffItem[];
     textDiffs: TextDiffSegment[];
     currentDiffIndex: number;
-    onSelectDiff: (index: number) => void;
+    onSelectDiff: (index: number, item?: DiffItem) => void;
     onJumpToPage: (pageIndex: number) => void;
 }
 export default function DiffSummarySidebar({ isOpen, diffItems, textDiffs, currentDiffIndex, onSelectDiff, onJumpToPage }: DiffSummarySidebarProps): React.JSX.Element | null;

package/dist/src/components/DocumentViewer.d.ts

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { Annotation } from '../annotations/types';
 import { AnnotationManager } from '../annotations/AnnotationManager';
-import { Redaction, WatermarkOptions, SDKPermissions, PdfAssetPaths } from '../core/types';
+import { Redaction, WatermarkOptions, SDKPermissions, PdfAssetPaths, TransientHighlight } from '../core/types';
 import * as pdfjsLib from 'pdfjs-dist';
 export interface DocumentLoadErrorInfo {
     url: string;
@@ -44,7 +44,9 @@ interface DocumentViewerProps {
     watermarkText?: string;
     enableAnnotations?: boolean;
     initialPage?: number;
+    page?: number;
+    transientHighlights?: TransientHighlight[];
     permissions?: SDKPermissions;
 }
-export default function DocumentViewer({ leftSidebarOpen, rightSidebarOpen, activeTab, annotationManager, initialDoc, loadNonce, withCredentials, assets, sidebars, redactions, regexRedactions, scale, setScale, sidebarTab, setSidebarTab, onAnnotationsChange, onRedactionsChange, onDocumentLoaded, onLoadError, onFirstPageRendered, onPageChange, pageTransition, pageLayout, rotation, setRotation, watermark, watermarkText, enableAnnotations: _enableAnnotations, initialPage, permissions }: DocumentViewerProps): React.JSX.Element;
+export default function DocumentViewer({ leftSidebarOpen, rightSidebarOpen, activeTab, annotationManager, initialDoc, loadNonce, withCredentials, assets, sidebars, redactions, regexRedactions, scale, setScale, sidebarTab, setSidebarTab, onAnnotationsChange, onRedactionsChange, onDocumentLoaded, onLoadError, onFirstPageRendered, onPageChange, pageTransition, pageLayout, rotation, setRotation, watermark, watermarkText, enableAnnotations: _enableAnnotations, initialPage, page, transientHighlights, permissions }: DocumentViewerProps): React.JSX.Element;
 export {};

package/dist/src/components/PageRenderer.d.ts

@@ -1,6 +1,6 @@
 import { default as React } from 'react';
 import { SearchResult } from '../hooks/usePdfSearch';
-import { Redaction, WatermarkOptions } from '../core/types';
+import { Redaction, WatermarkOptions, TransientHighlight } from '../core/types';
 import { Annotation } from '../annotations/types';
 import * as pdfjsLib from 'pdfjs-dist';
 export type { Annotation };
@@ -22,6 +22,7 @@ interface PageRendererProps {
     annotations: Annotation[];
     selectedAnnotationId: string | null;
     activeSearchResult: SearchResult | null;
+    transientHighlights?: TransientHighlight[];
     onMouseDown: (e: React.MouseEvent<Element>, pageNum: number) => void;
     onMouseMove: (e: React.MouseEvent<Element>, pageNum: number) => void;
     onMouseUp: (e: React.MouseEvent<Element>, pageNum: number) => void;
@@ -35,6 +36,6 @@ interface PageRendererProps {
     /** Called after the page canvas has been painted (used for first-page-rendered telemetry). */
     onRendered?: (pageNum: number) => void;
 }
-declare function PageRendererComponent({ pageNum, pdfDoc, scale, rotation, containerWidth: _containerWidth, containerHeight: _containerHeight, scrollTop: _scrollTop, scrollLeft: _scrollLeft, pageTop, pageLeft, basePageWidth, basePageHeight, activeTab, activeTool, annotations, selectedAnnotationId, activeSearchResult, onMouseDown, onMouseMove, onMouseUp, onAnnotationClick, onAnnotationMouseEnter, onClearSelection, watermark, watermarkText, redactions, onDiscardRedaction, onRendered }: PageRendererProps): React.JSX.Element;
+declare function PageRendererComponent({ pageNum, pdfDoc, scale, rotation, containerWidth: _containerWidth, containerHeight: _containerHeight, scrollTop: _scrollTop, scrollLeft: _scrollLeft, pageTop, pageLeft, basePageWidth, basePageHeight, activeTab, activeTool, annotations, selectedAnnotationId, activeSearchResult, transientHighlights, onMouseDown, onMouseMove, onMouseUp, onAnnotationClick, onAnnotationMouseEnter, onClearSelection, watermark, watermarkText, redactions, onDiscardRedaction, onRendered }: PageRendererProps): React.JSX.Element;
 declare const PageRenderer: React.MemoExoticComponent<typeof PageRendererComponent>;
 export default PageRenderer;

package/dist/src/components/TeamSyncViewer.d.ts

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { DocumentLoadErrorInfo } from './DocumentViewer';
 import { WebViewerInstance } from '../core/ViewerInstance';
-import { WebViewerOptions } from '../core/types';
+import { WebViewerOptions, TransientHighlight } from '../core/types';
 import { Annotation } from '../annotations/types';
 export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
     /** URL of the PDF to display. Alias of `initialDoc`; `fileUrl` wins when both are set. */
@@ -28,6 +28,8 @@ export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
     }) => void;
     onPageChange?: (pageNumber: number, numPages: number) => void;
     onAnnotationsChange?: (annotations: Annotation[]) => void;
+    /** Fires whenever transient highlights change. */
+    onTransientHighlightsChange?: (highlights: TransientHighlight[]) => void;
     className?: string;
     style?: React.CSSProperties;
 }

package/dist/src/core/ViewerInstance.d.ts

@@ -2,7 +2,8 @@ import { ViewerBus } from './eventBus';
 import { ExportOptions } from './export';
 import { Annotation } from '../annotations/types';
 import { AnnotationManager } from '../annotations/AnnotationManager';
-import { Redaction, WatermarkOptions, ViewerEventMap, ViewerEventType } from './types';
+import { Redaction, WatermarkOptions, ViewerEventMap, ViewerEventType, TransientHighlight } from './types';
+import { SearchResult } from '../hooks/usePdfSearch';
 /**
  * © 2026 AngelBot Ai Pvt Ltd. All rights reserved.
  * WebViewerInstance — the imperative handle returned by `createWebViewer()` and exposed through
@@ -21,6 +22,11 @@ export interface ViewerBinding {
     getCurrentPage(): number;
     getPageCount(): number;
     loadDocument(url: string): void;
+    goToPage(pageNumber: number, options?: {
+        smooth?: boolean;
+    }): void;
+    getTransientHighlights(): TransientHighlight[];
+    setTransientHighlights(highlights: TransientHighlight[]): void;
 }
 export declare class WebViewerInstance {
     readonly bus: ViewerBus;
@@ -56,6 +62,39 @@ export declare class WebViewerInstance {
     getPdfDocument(): pdfjsLib.PDFDocumentProxy | null;
     getCurrentPage(): number;
     getPageCount(): number;
+    /** Navigate to a specific page number (1-based). */
+    goToPage(pageNumber: number, options?: {
+        smooth?: boolean;
+    }): void;
+    /** Set the current page number (1-based). Alias of goToPage. */
+    setCurrentPage(pageNumber: number): void;
+    /**
+     * Search the document for text matches, returning snippets and page bounding boxes.
+     */
+    searchText(query: string): Promise<SearchResult[]>;
+    /** Get the current list of transient highlights. */
+    getTransientHighlights(): TransientHighlight[];
+    /**
+     * Set transient visual highlights across one or more pages.
+     * These render directly on the PDF canvas but are NEVER saved into AnnotationManager
+     * or exported to XFDF.
+     */
+    setTransientHighlights(highlights: TransientHighlight[]): void;
+    /** Add a single transient highlight to the current list. */
+    addTransientHighlight(highlight: TransientHighlight): void;
+    /** Clear all active transient highlights. */
+    clearTransientHighlights(): void;
+    /**
+     * Search for a snippet or citation query, scroll to its page, and highlight it temporarily.
+     * Returns the matched SearchResult or null if not found.
+     */
+    highlightSnippet(query: string, options?: {
+        pageIndex?: number;
+        pulse?: boolean;
+        scrollTo?: boolean;
+        color?: string;
+        tooltip?: string;
+    }): Promise<SearchResult | null>;
     getAnnotations(): Annotation[];
     /** Print the exported document (annotations, redactions and watermark baked in). */
     print(): void;
@@ -67,6 +106,8 @@ export declare class WebViewerInstance {
     readonly UI: {
         /** Theming is not implemented; kept for API compatibility. */
         setTheme: (_theme: string) => void;
+        goToPage: (pageNumber: number) => void;
+        setCurrentPageNumber: (pageNumber: number) => void;
         openElements: (elements: string[]) => void;
         closeElements: (elements: string[]) => void;
         enableElements: (elements: string[]) => void;
@@ -90,6 +131,9 @@ export declare class WebViewerInstance {
             removeEventListener: (event: string, callback: (detail: unknown) => void) => void;
             getCurrentPage: () => number;
             getPageCount: () => number;
+            goToPage: (pageNumber: number) => void;
+            setCurrentPage: (pageNumber: number) => void;
+            setCurrentPageNumber: (pageNumber: number) => void;
             getDocument: () => {
                 getFileData: (options?: ExportOptions) => Promise<Uint8Array<ArrayBufferLike>>;
             };

package/dist/src/core/types.d.ts

@@ -3,6 +3,27 @@ import { Annotation } from '../annotations/types';
 import { AnnotationChangedEvent } from '../annotations/AnnotationManager';
 import { PdfAssetPaths } from './pdfAssets';
 export type { PdfAssetPaths };
+export interface SearchBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface TransientHighlight {
+    id?: string;
+    /** 1-based page number */
+    pageIndex: number;
+    /** Bounding boxes on the page in PDF coordinate points */
+    bounds: SearchBounds[];
+    /** Background fill color (default 'rgba(250, 204, 21, 0.4)') */
+    color?: string;
+    /** Border color (default 'rgba(234, 179, 8, 0.8)') */
+    borderColor?: string;
+    /** Whether to animate with a pulsing focus ring */
+    pulse?: boolean;
+    /** Optional tooltip text displayed above the highlight */
+    tooltip?: string;
+}
 export interface Redaction {
     id?: string;
     /** 1-based page number */
@@ -47,6 +68,10 @@ export interface WebViewerOptions {
     initialScale?: InitialScale;
     /** 1-based page to scroll to after load. */
     initialPage?: number;
+    /** Current 1-based page to display. Changes navigate to the given page. */
+    page?: number;
+    /** Transient visual highlights that render on pages without polluting AnnotationManager. */
+    transientHighlights?: TransientHighlight[];
     plugins?: ViewerPlugin[];
     redactions?: Redaction[];
     regexRedactions?: RegExp[];
@@ -100,6 +125,9 @@ export interface ViewerEventMap {
     };
     /** Granular add / modify / delete (with the `imported` flag) from the AnnotationManager. */
     annotationChanged: AnnotationChangedEvent;
+    transientHighlightsChanged: {
+        highlights: TransientHighlight[];
+    };
     toolChanged: {
         tool: string | null;
     };

package/dist/src/hooks/usePdfSearch.d.ts

@@ -1,11 +1,6 @@
-import { Redaction } from '../core/types';
-import * as pdfjsLib from 'pdfjs-dist';
-export interface SearchBounds {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
+import { Redaction, SearchBounds } from '../core/types';
+import type * as pdfjsLib from 'pdfjs-dist';
+export type { SearchBounds };
 export interface SearchResult {
     id: string;
     pageIndex: number;
@@ -14,6 +9,11 @@ export interface SearchResult {
     matchLength: number;
     bounds: SearchBounds[];
 }
+/**
+ * Standalone asynchronous text search across all pages of a PDFDocumentProxy.
+ * Sanitizes redacted regions and returns matching snippets and bounding boxes.
+ */
+export declare function searchPdfText(pdfDoc: pdfjsLib.PDFDocumentProxy, query: string, redactions?: Redaction[], onProgress?: (progress: number) => void): Promise<SearchResult[]>;
 export declare function usePdfSearch(pdfDoc: pdfjsLib.PDFDocumentProxy | null, redactions?: Redaction[]): {
     search: (query: string) => Promise<void>;
     searchResults: SearchResult[];

package/dist/src/index.d.ts

@@ -28,4 +28,7 @@ export { annotationsToXfdf, annotationToXfdfFragment, parseXfdf, toPdfDate, from
 export type { XfdfExportOptions } from './annotations/xfdf';
 export { printPdfBytes } from './core/print';
 export type { PrintOptions } from './core/print';
+export { usePdfSearch, searchPdfText } from './hooks/usePdfSearch';
+export type { SearchResult, SearchBounds } from './hooks/usePdfSearch';
+export type { TransientHighlight } from './core/types';
 export * from './plugins/types';