@anaralabs/lector 3.14.11 → 3.14.13

package/README.md

@@ -2,7 +2,7 @@
 
 **A headless PDF viewer for React.** Compose pages, text selection, search, and annotations into your own reading experience. Lector handles PDF.js rendering and page virtualization; you control the layout and UI.
 
-[Documentation](https://lector-weld.vercel.app/docs) · [Live demo](https://lector-weld.vercel.app) · [npm](https://www.npmjs.com/package/@anaralabs/lector) · [Contributing](https://github.com/anaralabs/lector/blob/main/CONTRIBUTING.md)
+[Documentation](https://anara.com/lector/docs) · [Live demo](https://anara.com/lector) · [npm](https://www.npmjs.com/package/@anaralabs/lector) · [Contributing](https://github.com/anaralabs/lector/blob/main/CONTRIBUTING.md)
 
 ## Get a PDF on screen
 
@@ -46,7 +46,7 @@ export default function PDFViewer() {
 }
 ```
 
-For **Next.js**, load the viewer through a Client Component using `dynamic(..., { ssr: false })`; keep PDF.js setup inside the dynamically loaded module. See [installation](https://lector-weld.vercel.app/docs/installation) for the full wrapper, Vite worker setup, and deployments below a path prefix.
+For **Next.js**, load the viewer through a Client Component using `dynamic(..., { ssr: false })`; keep PDF.js setup inside the dynamically loaded module. See [installation](https://anara.com/lector/docs/installation) for the full wrapper, Vite worker setup, and deployments below a path prefix.
 
 `Root` loads the document and provides its state. `Pages` owns scrolling and clones one `Page` template for visible pages. `CanvasLayer` paints the PDF; `TextLayer` adds selectable text. Give the viewer a definite height and import the PDF.js stylesheet so its layers align.
 
@@ -54,23 +54,23 @@ For **Next.js**, load the viewer through a Client Component using `dynamic(...,
 
 | Feature | Start here |
 | --- | --- |
-| Toolbar, page input, and layout | [Your first viewer](https://lector-weld.vercel.app/docs/basic-usage) |
-| Authenticated URLs, local files, errors, and self-hosted assets | [Loading documents](https://lector-weld.vercel.app/docs/document-loading) |
-| Page navigation and fit width | [Navigation](https://lector-weld.vercel.app/docs/code/page-navigation), [zoom](https://lector-weld.vercel.app/docs/code/zoom-control) |
-| Page previews | [Thumbnails](https://lector-weld.vercel.app/docs/code/thumbnails) |
-| Text search and highlighted results | [Search](https://lector-weld.vercel.app/docs/code/search) |
-| Selection and citation regions | [Selection](https://lector-weld.vercel.app/docs/code/select), [highlights](https://lector-weld.vercel.app/docs/code/highlight) |
-| PDF links and editable form fields | [Links](https://lector-weld.vercel.app/docs/code/links), [forms](https://lector-weld.vercel.app/docs/code/pdf-form) |
-| Dark page rendering | [Dark mode](https://lector-weld.vercel.app/docs/dark-mode) |
-| Props, hooks, and defaults | [API reference](https://lector-weld.vercel.app/docs/api) |
-
-Lector is a toolkit rather than a finished toolbar or a PDF editor. Your app supplies accessible controls, error UI, and storage for user annotations. Search requires embedded text; it does not perform OCR. Custom highlight overlays do not automatically modify the PDF file. See [troubleshooting](https://lector-weld.vercel.app/docs/troubleshooting) for worker errors, blank pages, and layout issues.
+| Toolbar, page input, and layout | [Your first viewer](https://anara.com/lector/docs/basic-usage) |
+| Authenticated URLs, local files, errors, and self-hosted assets | [Loading documents](https://anara.com/lector/docs/document-loading) |
+| Page navigation and fit width | [Navigation](https://anara.com/lector/docs/code/page-navigation), [zoom](https://anara.com/lector/docs/code/zoom-control) |
+| Page previews | [Thumbnails](https://anara.com/lector/docs/code/thumbnails) |
+| Text search and highlighted results | [Search](https://anara.com/lector/docs/code/search) |
+| Selection and citation regions | [Selection](https://anara.com/lector/docs/code/select), [highlights](https://anara.com/lector/docs/code/highlight) |
+| PDF links and editable form fields | [Links](https://anara.com/lector/docs/code/links), [forms](https://anara.com/lector/docs/code/pdf-form) |
+| Dark page rendering | [Dark mode](https://anara.com/lector/docs/dark-mode) |
+| Props, hooks, and defaults | [API reference](https://anara.com/lector/docs/api) |
+
+Lector is a toolkit rather than a finished toolbar or a PDF editor. Your app supplies accessible controls, error UI, and storage for user annotations. Search requires embedded text; it does not perform OCR. Custom highlight overlays do not automatically modify the PDF file. See [troubleshooting](https://anara.com/lector/docs/troubleshooting) for worker errors, blank pages, and layout issues.
 
 ## Use with a coding assistant
 
-Connect an MCP client to `https://lector-weld.vercel.app/mcp` using Streamable HTTP, with no API key. It can search and read every guide through tools and resources. See [AI agents and MCP](https://lector-weld.vercel.app/docs/agents) for setup and example requests.
+Connect an MCP client to `https://anara.com/lector/mcp` using Streamable HTTP, with no API key. It can search and read every guide through tools and resources. See [AI agents and MCP](https://anara.com/lector/docs/agents) for setup and example requests.
 
-For direct fetching, start with [llms.txt](https://lector-weld.vercel.app/llms.txt), read [individual Markdown guides](https://lector-weld.vercel.app/docs/installation.md), or use the [complete documentation](https://lector-weld.vercel.app/llms-full.txt). These exports are generated from the same source as the website.
+For direct fetching, start with [llms.txt](https://anara.com/lector/llms.txt), read [individual Markdown guides](https://anara.com/lector/docs/installation.md), or use the [complete documentation](https://anara.com/lector/llms-full.txt). These exports are generated from the same source as the website.
 
 ## Work on Lector
 

package/dist/_tsup-dts-rollup.d.ts

@@ -9,9 +9,11 @@ import { JSX as JSX_2 } from 'react';
 import { JSXElementConstructor } from 'react';
 import { MemoExoticComponent } from 'react';
 import type { PageViewport } from 'pdfjs-dist';
+import { PageViewport as PageViewport_2 } from 'pdfjs-dist/types/src/display/display_utils';
 import type { PDFDocumentProxy } from 'pdfjs-dist';
 import { pdfjsDist } from 'pdfjs-dist';
 import type { PDFPageProxy } from 'pdfjs-dist';
+import { PDFPageProxy as PDFPageProxy_2 } from 'pdfjs-dist/types/src/display/api';
 import { default as React_2 } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
@@ -161,6 +163,11 @@ declare interface AnnotationTooltipProps {
  */
 export declare function applyContextRecolor(ctx: CanvasRenderingContext2D, map: RenderColorMap, options?: RecolorContextOptions): (finalizeRender?: boolean) => void;
 
+/** Keep viewport geometry and zoom subscribers in the same coordinate space. */
+export declare function applyViewportZoom(viewport: HTMLDivElement | null, zoom: number): void;
+
+declare type ApplyZoom = (zoom: number) => void;
+
 declare interface AsyncSearchOptions extends SearchOptions {
     /** Cancelling rejects with AbortError and never publishes partial results. */
     signal?: AbortSignal;
@@ -267,6 +274,13 @@ export declare function createRecolorCanvasFactory(mapRef: RenderColorMapRef): {
     };
 };
 
+/** Paint native selection once per page; overlapping PDF spans must not
+ * composite their translucent backgrounds on top of each other. */
+export declare const createSelectionBackground: () => {
+    update: (selection: Selection | null, layers: Iterable<HTMLElement>) => void;
+    clear: (layer: HTMLElement) => void;
+};
+
 export declare const CurrentPage: ({ ...props }: HTMLProps<HTMLInputElement>) => JSX.Element;
 
 export declare const CurrentZoom: ({ ...props }: HTMLProps<HTMLInputElement>) => JSX.Element;
@@ -305,6 +319,13 @@ export declare const getFitWidthZoom: (containerWidth: number, viewports: PageVi
 
 export declare const getMidHeightOfHighlightLine: (selection: ColoredHighlight) => number;
 
+/**
+ * Per-text-node client rects for a selection. Avoids the block-level rects
+ * that `range.getClientRects()` returns for `.textLayer` / page wrappers,
+ * which would render as full-page highlights on multi-page selections.
+ */
+export declare const getTextNodeClientRects: (range: Range) => TextNodeRect[];
+
 export declare const HighlightLayer: ForwardRefExoticComponent<HighlightLayerProps & RefAttributes<HTMLDivElement>>;
 
 declare interface HighlightLayerProps extends ComponentPropsWithoutRef<"div"> {
@@ -332,6 +353,8 @@ export declare interface HighlightRect_alias_2 {
 }
 
 export declare interface InitialPDFState {
+    pageResources?: PageResources;
+    initialPage?: number;
     pdfDocumentProxy: PDFDocumentProxy;
     pageProxies: PDFPageProxy[];
     viewports: Array<PageViewport>;
@@ -384,6 +407,8 @@ export declare const MAX_CANVAS_DIMENSION = 32767;
 
 export declare const MAX_CANVAS_PIXELS = 16777216;
 
+export declare const mergeTextRuns: <T extends Rect>(rects: T[]) => T[];
+
 export declare const NextPage: () => void;
 
 export declare const Outline: ({ children, ...props }: HTMLProps<HTMLUListElement> & {
@@ -412,6 +437,41 @@ pageNumber?: number;
 
 declare type PageNavigationCallback = (pageNumber: number, explicitDest?: unknown[]) => void;
 
+/** Owns a document's bounded, deduplicated page acquisition queue. */
+export declare class PageResources {
+    private document;
+    private rotation;
+    private onError;
+    private concurrency;
+    private pages;
+    private requests;
+    private queue;
+    private active;
+    private disposed;
+    private listeners;
+    private notification;
+    private viewports;
+    private completePages;
+    private viewportUpdates;
+    constructor(document: PDFDocumentProxy, firstPage: PDFPageProxy, rotation: number, onError: (error: unknown) => void, concurrency?: number);
+    private viewportFor;
+    get(pageNumber: number): PDFPageProxy_2 | undefined;
+    getSnapshot: () => {
+        viewports: PageViewport_2[];
+        pageProxies: PDFPageProxy_2[] | undefined;
+    };
+    subscribe: (listener: () => void) => () => void;
+    /** Visible pages move ahead of the background queue; in-flight requests are shared. */
+    load: (pageNumber: number) => Promise<PDFPageProxy>;
+    private createRequest;
+    /** Start after the reader mounts, so unrelated page metadata cannot delay its first render. */
+    start: () => void;
+    loadAll: () => Promise<PDFPageProxy[]>;
+    private pump;
+    private notify;
+    dispose: () => void;
+}
+
 export declare const Pages: ({ children, gap, virtualizerOptions, initialOffset, onOffsetChange, ...props }: HTMLProps<HTMLDivElement> & {
     virtualizerOptions?: {
         overscan?: number;
@@ -458,7 +518,14 @@ declare interface PDFState {
     setVirtualizer: (virtualizer: PDFVirtualizer) => void;
     highlights: HighlightRect[];
     setHighlight: (higlights: HighlightRect[]) => void;
+    /** Synchronous access; progressive consumers must load an unresolved page first. */
     getPdfPageProxy: (pageNumber: number) => PDFPageProxy;
+    loadPdfPageProxy: (pageNumber: number) => Promise<PDFPageProxy>;
+    loadPdfPageProxies: () => Promise<PDFPageProxy[]>;
+    isPageLoaded: (pageNumber: number) => boolean;
+    /** False until the ordered pageProxies array is complete in progressive mode. */
+    pagesLoaded: boolean;
+    initialPage: number;
     customSelectionRects: HighlightRect[];
     setCustomSelectionRects: (rects: HighlightRect[]) => void;
     coloredHighlights: ColoredHighlight[];
@@ -502,6 +569,15 @@ export declare interface RecolorContextOptions {
     pageArea?: number;
 }
 
+declare type Rect = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+
+export declare function registerViewportZoom(viewport: HTMLDivElement, apply: ApplyZoom): () => void;
+
 /**
  * Removes any recolor wrapper installed on the context. For long-lived
  * contexts (the visible canvas in the no-buffer fallback, thumbnails) that
@@ -615,6 +691,8 @@ export declare interface SearchResult {
     text: string;
     score: number;
     matchIndex: number;
+    /** Matched UTF-16 span in the original PDF text, when different from searchText.length. */
+    matchLength?: number;
     isExactMatch: boolean;
     searchText?: string;
 }
@@ -654,14 +732,21 @@ declare type TextContent = {
 
 export declare const TextLayer: MemoExoticComponent<({ className, style, ...props }: HTMLProps<HTMLDivElement>) => JSX.Element>;
 
+declare type TextNodeRect = {
+    rect: DOMRect;
+    element: Element | null;
+};
+
 declare interface TextPosition {
     pageNumber: number;
     text: string;
     matchIndex: number;
+    matchLength?: number;
     searchText?: string;
 }
 
-export declare const Thumbnail: ({ pageNumber, eager, ...props }: HTMLProps<HTMLCanvasElement> & {
+/** An unresolved page occupies a stable row while its resource is acquired. */
+export declare const Thumbnail: (props: HTMLProps<HTMLCanvasElement> & {
     pageNumber?: number;
     eager?: boolean;
 }) => JSX.Element;
@@ -722,7 +807,7 @@ declare const usePdf: <T>(selector: (state: PDFState) => T) => T;
 export { usePdf }
 export { usePdf as usePdf_alias_1 }
 
-export declare const usePDFDocumentContext: ({ onDocumentLoad, onError, source, initialRotation, isZoomFitWidth, zoom, zoomOptions, documentOptions, colorScheme, darkModeColors, }: usePDFDocumentParams) => {
+export declare const usePDFDocumentContext: ({ onDocumentLoad, onError, source, initialRotation, progressive, initialPage, isZoomFitWidth, zoom, zoomOptions, documentOptions, colorScheme, darkModeColors, }: usePDFDocumentParams) => {
     initialState: InitialPDFState | null | undefined;
 };
 
@@ -752,6 +837,10 @@ export declare interface usePDFDocumentParams {
         source: Source;
     }) => void;
     initialRotation?: number;
+    /** Render the initial page before acquiring the rest. Unloaded page sizes are estimates. */
+    progressive?: boolean;
+    /** One-based page to load and display first. Read when source changes. */
+    initialPage?: number;
     isZoomFitWidth?: boolean;
     zoom?: number;
     zoomOptions?: ZoomOptions;