teamsync-pdf-viewer 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
+## [1.7.0] — 2026-09-15
+
+### Added
+- **Cross-Instance Document Linking**: Links referring to other documents or specific pages can now automatically load and navigate the destination document in a designated target `TeamSyncViewer` instance.
+- **`targetViewer` Prop & Option**: Added `targetViewer` to `<TeamSyncViewer>` and `WebViewerOptions`, accepting another `WebViewerInstance`, a React ref (`useRef<WebViewerInstance>`), a getter function `() => WebViewerInstance | null`, or an instance ID string.
+- **Static Viewer Instance Registry**: Added `WebViewerInstance.getInstance(id)`, `WebViewerInstance.registerInstance(id, inst)`, `WebViewerInstance.unregisterInstance(id)`, and automatic unregistration when the viewer is unmounted/destroyed.
+- **`loadOrNavigate` & `openLink` APIs**: Added `instance.loadOrNavigate(documentUrl, page?)` (smoothly navigates to the page if the document is already loaded, or reloads at that page if not) and `instance.openLink(url, options?)`.
+- **Dual Link Support (TeamSync Annotations & Embedded PDF Links)**:
+  - Native embedded PDF `/Link` annotations are now extracted from PDF.js (`page.getAnnotations({ intent: 'display' })`) and rendered with interactive SVG hitboxes and tooltip preview.
+  - Link annotations and sidebar comment links seamlessly route through the link handler.
+- **"Other Doc" Tab in Insert Link Modal**: Added a dedicated 3rd tab to `InsertLinkModal` for configuring cross-document links with document URL and target page number.
+- **`linkClicked` Event & Custom Handlers**: Added `linkClicked` event to `ViewerEventMap` with a cancellable `LinkClickEvent` supporting `event.preventDefault()`, plus `onLinkClick` and `resolveLinkUrl` props for URL mapping and event interception.
+- **Public Utilities Export**: Exported `parseLinkTarget`, `isDocumentUrl`, `ParsedLinkTarget`, and `LinkClickEvent` from the library root.
+
+## [1.6.1] — 2026-09-15
+
+### Added
+- **`initialWidthRatio` Option**: Added `initialWidthRatio?: number` (with `widthRatio?: number` as an alias) to `<TeamSyncViewer>` and `WebViewerOptions`, allowing clients to target an exact fraction of the available viewing width on initial load (e.g. `0.7` for 70% width).
+- **Responsive PDF Container Resizing**: Added automatic `ResizeObserver` tracking on the document container to refit the open PDF responsively at 60fps via `requestAnimationFrame` when the viewer page, container, or sidebars resize while in a width-ratio, fit-width, or fit-page mode.
+- **`responsive` Prop**: Added `responsive?: boolean` (defaults to `true`) to `<TeamSyncViewer>` and `WebViewerOptions` for explicit control over auto-refitting on container resize.
+- **Public `calculateFitWidthScale` Utility**: Exported `calculateFitWidthScale(availableWidth, pageWidth, ratio?, minScale?, maxScale?)` from the public package root.
+- **Ratio Support in `fitWidth` & `fitToWidth`**: Updated `instance.UI.fitWidth(ratio?)`, `instance.UI.fitToWidth(ratio?)`, and added direct instance methods `instance.fitWidth(ratio?)`, `instance.fitToWidth(ratio?)`, `instance.fitPage()`, and `instance.fitToPage()`.
+
 ## [1.6.0] — 2026-09-06
 
 ### Added

package/README.md

@@ -25,7 +25,7 @@ Try the **[Interactive Live Demo](https://pdfviewer.teamsync.com/)** or integrat
 Traditional commercial PDF viewers force developers into expensive per-domain licenses, opaque sales calls, and heavy server-side processing dependencies. **TeamSync PDF Viewer** is built from the ground up to solve these pain points.
 
 - 💰 **Zero-Cost, Transparent Licensing**: Uncapped usage, no per-server fees, and no commercial paywalls. 100% free and open-source under CPAL 1.0.
-- ⚡ **100% Client-Side WebAssembly**: Documents never leave the browser sandbox. Process, redact, and render PDFs entirely on the client. 
+- ⚡ **100% Client-Side PDF Processing**: Documents never leave the browser sandbox. Process, redact, and render PDFs entirely on the client. 
 - 🔌 **Universal WebViewer API**: Clean, intuitive `WebViewer({...})` API interface that makes integrating into your web applications effortless.
 - 🎨 **Headless & Customizable**: Built for modern React 19 SPA lifecycles. No bloated iFrames to fight—customize toolbars, sidebars, context menus, and controls natively.
 

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, TransientHighlight } from '../core/types';
+import { Redaction, WatermarkOptions, SDKPermissions, PdfAssetPaths, TransientHighlight, InitialScale, LinkClickEvent, WebViewerInstance } from '../core/types';
 import * as pdfjsLib from 'pdfjs-dist';
 export interface DocumentLoadErrorInfo {
     url: string;
@@ -56,6 +56,22 @@ interface DocumentViewerProps {
     enableTextSelection?: boolean;
     defaultTool?: 'select' | 'pan';
     showSelectionTooltip?: boolean;
+    initialScale?: InitialScale;
+    initialWidthRatio?: number;
+    responsive?: boolean;
+    instance?: WebViewerInstance;
+    targetViewer?: WebViewerInstance | React.RefObject<WebViewerInstance | null> | (() => WebViewerInstance | null) | string;
+    resolveLinkUrl?: (linkUrl: string, context: {
+        sourceViewer: WebViewerInstance;
+        annotation?: Annotation;
+    }) => string | {
+        url: string;
+        page?: number;
+    } | Promise<string | {
+        url: string;
+        page?: number;
+    } | null> | null;
+    onLinkClick?: (event: LinkClickEvent) => boolean | void | Promise<void>;
 }
-export default function DocumentViewer({ leftSidebarOpen, rightSidebarOpen, activeTab, annotationManager, initialDoc, loadNonce, withCredentials, assets, sidebars, redactions, regexRedactions, scale, setScale, sidebarTab, setSidebarTab, onAnnotationsChange, onRedactionsChange, onRedactionsApplied, onDocumentLoaded, onLoadError, onFirstPageRendered, onPageRendered, onPageChange, pageTransition, pageLayout, rotation, setRotation, watermark, watermarkText, enableAnnotations: _enableAnnotations, initialPage, page, transientHighlights, permissions, hideAnnotationsUntilPageRendered, enableTextSelection, defaultTool, showSelectionTooltip }: 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, onRedactionsApplied, onDocumentLoaded, onLoadError, onFirstPageRendered, onPageRendered, onPageChange, pageTransition, pageLayout, rotation, setRotation, watermark, watermarkText, enableAnnotations: _enableAnnotations, initialPage, page, transientHighlights, permissions, hideAnnotationsUntilPageRendered, enableTextSelection, defaultTool, showSelectionTooltip, initialScale, initialWidthRatio, responsive, instance, targetViewer, resolveLinkUrl, onLinkClick, }: DocumentViewerProps): React.JSX.Element;
 export {};

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

@@ -40,7 +40,8 @@ interface PageRendererProps {
     onRendered?: (pageNum: number) => void;
     /** Whether to hide annotations and transient highlights until the page canvas has finished rendering. Default: true. */
     hideAnnotationsUntilPageRendered?: boolean;
+    onLinkClick?: (url: string, annotation?: Annotation, e?: React.MouseEvent) => 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, transientHighlights, onMouseDown, onMouseMove, onMouseUp, onAnnotationClick, onAnnotationDoubleClick, onStartResize, onStartMove, onAnnotationMouseEnter, onClearSelection, watermark, watermarkText, redactions, onDiscardRedaction, onRendered, hideAnnotationsUntilPageRendered }: 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, onAnnotationDoubleClick, onStartResize, onStartMove, onAnnotationMouseEnter, onClearSelection, watermark, watermarkText, redactions, onDiscardRedaction, onRendered, hideAnnotationsUntilPageRendered, onLinkClick }: PageRendererProps): React.JSX.Element;
 declare const PageRenderer: React.MemoExoticComponent<typeof PageRendererComponent>;
 export default PageRenderer;

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

@@ -13,6 +13,7 @@ interface SidebarProps {
     onResultClick: (result: SearchResult) => void;
     activeTab: 'Comments' | 'Search';
     setActiveTab: (tab: 'Comments' | 'Search') => void;
+    onLinkClick?: (url: string, annotation?: any, e?: React.MouseEvent) => void;
 }
-export default function Sidebar({ isOpen, annotations, setAnnotations, selectedAnnotationId, setSelectedAnnotationId, onSearch, searchResults, isSearching, searchProgress, onResultClick, activeTab, setActiveTab }: SidebarProps): React.JSX.Element;
+export default function Sidebar({ isOpen, annotations, setAnnotations, selectedAnnotationId, setSelectedAnnotationId, onSearch, searchResults, isSearching, searchProgress, onResultClick, activeTab, setActiveTab, onLinkClick }: SidebarProps): React.JSX.Element;
 export {};

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, Redaction, TransientHighlight } from '../core/types';
+import { WebViewerOptions, Redaction, TransientHighlight, LinkClickEvent } 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. */
@@ -47,6 +47,33 @@ export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
     onTextCopied?: (info: {
         text: string;
     }) => void;
+    /** Unique ID for this viewer instance, enabling other viewers to target it by name. */
+    id?: string;
+    /**
+     * Target viewer instance, ref, getter, or instance ID to open cross-document links in.
+     * When a link annotation pointing to another PDF is clicked, the document will automatically
+     * be loaded and navigated in this target viewer instance.
+     */
+    targetViewer?: WebViewerInstance | React.RefObject<WebViewerInstance | null> | (() => WebViewerInstance | null) | string;
+    /**
+     * Optional custom resolver for cross-document links.
+     * Allows transforming relative filenames, document IDs, or URNs into full fetchable document URLs or target pages.
+     */
+    resolveLinkUrl?: (linkUrl: string, context: {
+        sourceViewer: WebViewerInstance;
+        annotation?: Annotation;
+    }) => string | {
+        url: string;
+        page?: number;
+    } | Promise<string | {
+        url: string;
+        page?: number;
+    } | null> | null;
+    /**
+     * Fires when a link annotation or embedded PDF link is clicked.
+     * Call `event.preventDefault()` to suppress default behavior.
+     */
+    onLinkClick?: (event: LinkClickEvent) => boolean | void | Promise<void>;
     className?: string;
     style?: React.CSSProperties;
 }

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

@@ -1,14 +1,10 @@
+import { default as React } from 'react';
 import { ViewerBus } from './eventBus';
 import { ExportOptions } from './export';
 import { Annotation } from '../annotations/types';
 import { AnnotationManager } from '../annotations/AnnotationManager';
 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
- * `<TeamSyncViewer ref>`. Keeps the legacy `UI` / `Core` facade for drop-in compatibility.
- */
 import type * as pdfjsLib from 'pdfjs-dist';
 /** Callbacks the React component installs so the instance can reach live state. */
 export interface ViewerBinding {
@@ -29,15 +25,31 @@ export interface ViewerBinding {
     setTransientHighlights(highlights: TransientHighlight[]): void;
 }
 export declare class WebViewerInstance {
+    private static instances;
+    /** Retrieve a registered WebViewerInstance by its ID. */
+    static getInstance(id: string): WebViewerInstance | undefined;
+    /** Register a WebViewerInstance with an ID. */
+    static registerInstance(id: string, instance: WebViewerInstance): void;
+    /** Unregister an instance by its ID. */
+    static unregisterInstance(id: string): void;
+    /** Clear all registered instances (primarily for testing). */
+    static clearInstances(): void;
     readonly bus: ViewerBus;
     /** Annotation list, history, permissions and XFDF import/export. */
     readonly annotationManager: AnnotationManager;
     /** Root element of the viewer once mounted. */
     element: HTMLElement | null;
+    /** Unique identifier for this instance. */
+    id?: string;
     private binding;
     private unmountRoot;
     private destroyed;
-    constructor(bus: ViewerBus, annotationManager?: AnnotationManager);
+    private targetViewerTarget;
+    constructor(bus: ViewerBus, annotationManager?: AnnotationManager, id?: string);
+    /** Sets the target viewer instance, ref, getter, or ID to receive cross-document links. */
+    setTargetViewer(target: WebViewerInstance | React.RefObject<WebViewerInstance | null> | (() => WebViewerInstance | null) | string | null): void;
+    /** Resolves the target viewer instance if configured. */
+    getTargetViewer(): WebViewerInstance | null;
     /** @internal */
     _bind(binding: ViewerBinding, element: HTMLElement | null): void;
     /** @internal */
@@ -54,10 +66,29 @@ export declare class WebViewerInstance {
     on<K extends ViewerEventType>(type: K, listener: (detail: ViewerEventMap[K]) => void): () => void;
     off<K extends ViewerEventType>(type: K, listener: (detail: ViewerEventMap[K]) => void): void;
     /** Load (or reload) a document by URL. Resolves when loaded, rejects on load error. */
-    loadDocument(url: string): Promise<{
+    loadDocument(url: string, options?: {
+        page?: number;
+        initialPage?: number;
+    }): Promise<{
         url: string;
         numPages: number;
     }>;
+    /**
+     * Loads a document or navigates to a page within it. If the document is already loaded,
+     * directly navigates to the requested page without reloading.
+     */
+    loadOrNavigate(url: string, options?: {
+        page?: number;
+        initialPage?: number;
+    }): Promise<{
+        url: string;
+        numPages: number;
+    } | void>;
+    /**
+     * Programmatically trigger link following for a given link URL or target,
+     * routing through targetViewer or opening appropriately.
+     */
+    openLink(linkUrl: string): void;
     getDocumentUrl(): string | undefined;
     getPdfDocument(): pdfjsLib.PDFDocumentProxy | null;
     getCurrentPage(): number;
@@ -68,6 +99,19 @@ export declare class WebViewerInstance {
     }): void;
     /** Set the current page number (1-based). Alias of goToPage. */
     setCurrentPage(pageNumber: number): void;
+    /**
+     * Scale the document to fit the container width.
+     *
+     * @param ratio - Optional width ratio fraction (e.g. `0.7` for 70% of available width).
+     *   Defaults to `1.0` (100% full-width fit).
+     */
+    fitWidth(ratio?: number): void;
+    /** Alias of `fitWidth`. */
+    fitToWidth(ratio?: number): void;
+    /** Scale the document to fit the entire page within the container viewport. */
+    fitPage(): void;
+    /** Alias of `fitPage`. */
+    fitToPage(): void;
     /**
      * Search the document for text matches, returning snippets and page bounding boxes.
      *
@@ -145,9 +189,9 @@ export declare class WebViewerInstance {
         setToolMode: (tool: string | null) => void;
         getSelectedText: () => string;
         copySelectedText: () => Promise<boolean>;
-        fitWidth: () => void;
+        fitWidth: (ratio?: number) => void;
         fitPage: () => void;
-        fitToWidth: () => void;
+        fitToWidth: (ratio?: number) => void;
         fitToPage: () => void;
         startCompare: (docA: any, docB: any, options?: any) => void;
         stopCompare: () => void;

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

@@ -1,8 +1,10 @@
+import { default as React } from 'react';
 import { ViewerPlugin } from '../plugins/types';
 import { Annotation } from '../annotations/types';
 import { AnnotationChangedEvent } from '../annotations/AnnotationManager';
 import { PdfAssetPaths } from './pdfAssets';
-export type { PdfAssetPaths };
+import { WebViewerInstance } from './ViewerInstance';
+export type { PdfAssetPaths, WebViewerInstance };
 export interface SearchBounds {
     x: number;
     y: number;
@@ -53,7 +55,10 @@ export interface ViewerUser {
     id: string;
     name: string;
 }
-export type InitialScale = number | 'fit-width' | 'fit-page';
+export type InitialScale = number | 'fit-width' | 'fit-page' | {
+    type: 'fit-width';
+    ratio?: number;
+};
 export type ToolMode = 'select' | 'pan' | 'rectangle' | 'ellipse' | 'line' | 'arrow' | 'freehand' | 'highlight' | 'underline' | 'strikeout' | 'squiggly' | 'text' | 'eraser' | 'note' | 'callout' | 'signature' | 'digital_signature' | 'link' | 'redaction' | null;
 /**
  * Options accepted by `createWebViewer()` (and the deprecated `WebViewer()` alias).
@@ -67,6 +72,18 @@ export interface WebViewerOptions {
     /** Display name used for downloads. */
     fileName?: string;
     initialScale?: InitialScale;
+    /**
+     * Initial page width target as a ratio of the available viewing container width (e.g. `0.7` for 70%).
+     * When provided, the viewer scales the document to occupy this fraction of available width on initial render.
+     */
+    initialWidthRatio?: number;
+    /** Alias of `initialWidthRatio`. */
+    widthRatio?: number;
+    /**
+     * Automatically re-calculate scale when the viewer container or window resizes while in a fit or width-ratio mode.
+     * Default: true.
+     */
+    responsive?: boolean;
     /** 1-based page to scroll to after load. */
     initialPage?: number;
     /** Current 1-based page to display. Changes navigate to the given page. */
@@ -117,6 +134,52 @@ export interface WebViewerOptions {
     onRedactionsChange?: (redactions: Redaction[]) => void;
     /** Fires once per user click of Apply in the confirmation modal with all applied redactions. */
     onRedactionsApplied?: (redactions: Redaction[]) => void;
+    /** Unique identifier for this viewer instance, allowing other viewers to target it by name. */
+    id?: string;
+    /**
+     * Target viewer instance, ref, getter, or instance ID to open cross-document links in.
+     * When a link annotation pointing to another PDF is clicked, the document will automatically
+     * be loaded and navigated in this target viewer instance.
+     */
+    targetViewer?: WebViewerInstance | React.RefObject<WebViewerInstance | null> | (() => WebViewerInstance | null) | string;
+    /**
+     * Optional custom resolver for cross-document links.
+     * Allows transforming relative filenames, document IDs, or URNs into full fetchable document URLs or target pages.
+     */
+    resolveLinkUrl?: (linkUrl: string, context: {
+        sourceViewer: WebViewerInstance;
+        annotation?: Annotation;
+    }) => string | {
+        url: string;
+        page?: number;
+    } | Promise<string | {
+        url: string;
+        page?: number;
+    } | null> | null;
+    /**
+     * Fires when a link annotation or embedded PDF link is clicked.
+     * Call `event.preventDefault()` to suppress default behavior.
+     */
+    onLinkClick?: (event: LinkClickEvent) => boolean | void | Promise<void>;
+}
+/** Details provided when a link annotation or embedded PDF link is clicked. */
+export interface LinkClickEvent {
+    /** The raw link URL or target string. */
+    url: string;
+    /** Target document URL if the link points to a document (clean without page hash). */
+    docUrl?: string;
+    /** Target page number (1-based), if specified in the link. */
+    pageNumber?: number;
+    /** True if the link points to an internal page in the current document. */
+    isInternalPage: boolean;
+    /** The annotation object if clicked from a link annotation. */
+    annotation?: Annotation;
+    /** Original mouse event if triggered by user interaction. */
+    originalEvent?: React.MouseEvent;
+    /** Calling this prevents default behavior (e.g. scrolling current document, auto-forwarding to targetViewer, or opening window.open). */
+    preventDefault: () => void;
+    /** Whether preventDefault() was called. */
+    readonly defaultPrevented: boolean;
 }
 /** Events available through `instance.on(type, listener)`. */
 export interface ViewerEventMap {
@@ -164,6 +227,7 @@ export interface ViewerEventMap {
     textCopied: {
         text: string;
     };
+    linkClicked: LinkClickEvent;
     destroy: Record<string, never>;
 }
 export type ViewerEventType = keyof ViewerEventMap;

package/dist/src/index.d.ts

@@ -17,7 +17,9 @@ export { ViewerBus } from './core/eventBus';
 export type { BusListener } from './core/eventBus';
 export { buildPdfBytes, MAX_EXPORT_BYTES } from './core/export';
 export type { ExportInput, ExportOptions } from './core/export';
-export type { WebViewerOptions, Redaction, WatermarkOptions, SDKPermissions, ViewerUser, InitialScale, ViewerEventMap, ViewerEventType, ToolMode, } from './core/types';
+export type { WebViewerOptions, Redaction, WatermarkOptions, SDKPermissions, ViewerUser, InitialScale, ViewerEventMap, ViewerEventType, ToolMode, LinkClickEvent, } from './core/types';
+export { parseLinkTarget, isDocumentUrl } from './utils/linkUtils';
+export type { ParsedLinkTarget } from './utils/linkUtils';
 export { copyTextToClipboard } from './utils/clipboardUtils';
 export { TextSelectionTooltip } from './components/TextSelectionTooltip';
 export type { Annotation, AnnotationType, AnnotationPoint, AnnotationInput } from './annotations/types';
@@ -33,7 +35,7 @@ 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 { MIN_SCALE, MAX_SCALE, clampScale, calculateNextZoomIn, calculateNextZoomOut, calculateScrollCompensation } from './utils/zoomUtils';
+export { MIN_SCALE, MAX_SCALE, clampScale, calculateNextZoomIn, calculateNextZoomOut, calculateFitWidthScale, calculateScrollCompensation } from './utils/zoomUtils';
 export type { ScrollCompensationParams, ScrollPosition } from './utils/zoomUtils';
 export { estimatePageDimensions, computeRowLayout, DEFAULT_FALLBACK_DIMS, hasDimensionMismatch } from './utils/layoutUtils';
 export type { PageDimension, RowLayout } from './utils/layoutUtils';

package/dist/src/utils/linkUtils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * © 2026 AngelBot Ai Pvt Ltd. All rights reserved.
+ */
+export interface ParsedLinkTarget {
+    /** Raw input URL or link target string. */
+    rawUrl: string;
+    /** True if the link refers only to an internal page jump within the current document (e.g. '#page=5' or '#5'). */
+    isInternalPage: boolean;
+    /** Clean document URL without page hash if referencing another document (e.g. 'supporting.pdf' or 'https://.../doc.pdf'). */
+    docUrl?: string;
+    /** Target page number (1-based) if specified (e.g. 5 from '#page=5' or 'doc.pdf#page=5'). */
+    pageNumber?: number;
+    /** True if this is an external web URL (e.g. 'https://google.com') that is not a PDF/document. */
+    isExternalWeb: boolean;
+}
+/**
+ * Checks whether a given URL or filename refers to a PDF / document rather than a general web page.
+ */
+export declare function isDocumentUrl(url: string): boolean;
+/**
+ * Parses any link URL into structured destination information, extracting target documents and page numbers.
+ */
+export declare function parseLinkTarget(linkUrl: string): ParsedLinkTarget;

package/dist/src/utils/zoomUtils.d.ts

@@ -27,6 +27,11 @@ export declare function calculateNextZoomOut(currentScale: number, minScale?: nu
  * Clamps and rounds a requested zoom level within [minScale, maxScale].
  */
 export declare function clampScale(scale: number, minScale?: number, maxScale?: number): number;
+/**
+ * Calculates the target scale to fit a given page width to an available container width,
+ * optionally scaled by a width ratio (e.g. 0.7 for 70% of available width).
+ */
+export declare function calculateFitWidthScale(availableWidth: number, pageWidth: number, ratio?: number, minScale?: number, maxScale?: number): number;
 /**
  * Calculates the safe rasterization scale for PDF.js viewport rendering so that
  * canvas dimensions and texture memory stay strictly within hardware limits.