@anaralabs/lector 3.14.10 → 3.14.12

package/README.md

@@ -1,44 +1,41 @@
-<p align="center">
-  <p align="center">
-    <i>Simple primitives to compose powerful PDF viewing experiences.<br>powered by <code><a href="https://mozilla.github.io/pdf.js/">PDF.js</a></code> and <code><a href="https://reactjs.org/">React</a></code></i>
-  </p>
-</p>
+# Lector
 
-# `lector`
+**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.
 
-A composable, headless PDF viewer toolkit for React applications, powered by `PDF.js`. Build feature-rich PDF viewing experiences with full control over the UI and functionality.
+[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)
 
-[![npm version](https://badge.fury.io/js/@anaralabs%2Flector.svg)](https://www.npmjs.com/package/@anaralabs/lector)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+## Get a PDF on screen
 
-## Installation
+Use React 19+. The current source expects `pdfjs-dist` `^5.5.207`. These docs track `main`; check the [releases](https://github.com/anaralabs/lector/releases) against your installed package version.
 
 ```bash
-npm install @anaralabs/lector pdfjs-dist
+npm install @anaralabs/lector pdfjs-dist@^5.5.207
+```
 
-# or with yarn
-yarn add @anaralabs/lector pdfjs-dist
+Copy the PDF.js worker from your app's installed dependency to its public assets. Recopy it whenever you update PDF.js so the runtime and worker versions match.
 
-# or with pnpm
-pnpm add @anaralabs/lector pdfjs-dist
+```bash
+mkdir -p public/pdfjs
+cp node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs public/pdfjs/
 ```
 
-## Basic Usage
-
-Here's a simple example of how to create a basic PDF viewer:
+Put a PDF at `public/sample.pdf`, then add this browser-rendered component:
 
 ```tsx
 import { CanvasLayer, Page, Pages, Root, TextLayer } from "@anaralabs/lector";
+import { GlobalWorkerOptions } from "pdfjs-dist/legacy/build/pdf.mjs";
 import "pdfjs-dist/web/pdf_viewer.css";
 
+GlobalWorkerOptions.workerSrc = "/pdfjs/pdf.worker.min.mjs";
+
 export default function PDFViewer() {
   return (
     <Root
       source="/sample.pdf"
-      className="w-full h-[500px] border overflow-hidden rounded-lg"
-      loader={<div className="p-4">Loading...</div>}
+      style={{ height: 600 }}
+      loader={<p role="status">Loading PDF…</p>}
     >
-      <Pages className="p-4">
+      <Pages>
         <Page>
           <CanvasLayer />
           <TextLayer />
@@ -49,68 +46,48 @@ export default function PDFViewer() {
 }
 ```
 
-## Local Development using PNPM and Yalc
-
-When you are using "pnpm link", you are bound to use pnpm on your consumer project when you are developing locally.
-With yalc, we are decoupling the need for pnpm and now the package can be tested with any package managers. Any
-changes should be automatically published to yalc on save, forcing a rebuilt and updating the consumer project.
-
-Install yalc globally:
-
-```
-pnpm i yalc -g
-```
-
-From lector:
+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.
 
-```bash
-# navigate to lector package folder and install dependencies
-pnpm i
-# when you first start development, make sure you publish the package locally
-yalc publish
-# and run the project in development mode to start a watcher that rebuilds the project and pushes the changes locally on save
-pnpm dev
-```
+`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.
 
-From consumer project:
-(It doesn't really matter what package manager you are using)
+## Build the reader your app needs
 
-```bash
-# add local package to your package.json of the consumer project using yalc
-yalc add @anaralabs/lector
-# or if you don't want to add the yalc package in your package.json
-yalc link @anaralabs/lector
-```
+| 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) |
 
-## Features
+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.
 
-- 📱 Responsive and mobile-friendly
-- 🎨 Fully customizable UI components
-- 🔍 Text selection and search functionality
-- 📑 Page thumbnails and outline navigation
-- 🌗 First-class dark mode support
-- 🖱️ Pan and zoom controls
-- 📝 Form filling support
-- 🔗 Internal and external link handling
+## Use with a coding assistant
 
-## Contributing
+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.
 
-We welcome contributions! Key areas we're focusing on:
+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.
 
-1. Performance optimizations
-2. Accessibility improvements
-3. Mobile/touch interactions
-4. Documentation and examples
+## Work on Lector
 
+From the repository root, with Node.js 22.13+ and pnpm 9.5.0:
 
+```bash
+pnpm install --frozen-lockfile
+pnpm --filter @anaralabs/lector build
+pnpm --filter docs dev
+```
 
-## Thanks
+Open [localhost:3000/docs](http://localhost:3000/docs). The docs app uses the local workspace package. For watch mode, validation commands, and testing in another application, read [CONTRIBUTING.md](https://github.com/anaralabs/lector/blob/main/CONTRIBUTING.md).
 
-Special thanks to these open-source projects that provided inspiration:
+## Acknowledgements
 
-- [react-pdf-headless](https://github.com/jkgenser/react-pdf-headless)
-- [pdfreader](https://github.com/OnedocLabs/pdfreader)
+Inspired by [react-pdf-headless](https://github.com/jkgenser/react-pdf-headless) and [pdfreader](https://github.com/OnedocLabs/pdfreader). Built on [PDF.js](https://mozilla.github.io/pdf.js/) and [React](https://react.dev/).
 
 ## License
 
-MIT © [Anara](https://anara.com)
+[MIT](https://github.com/anaralabs/lector/blob/main/LICENSE) © [Anara](https://anara.com)

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

@@ -6,6 +6,7 @@ import { FunctionComponent } from 'react';
 import { HTMLProps } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { JSX as JSX_2 } from 'react';
+import { JSXElementConstructor } from 'react';
 import { MemoExoticComponent } from 'react';
 import type { PageViewport } from 'pdfjs-dist';
 import type { PDFDocumentProxy } from 'pdfjs-dist';
@@ -14,6 +15,7 @@ import type { PDFPageProxy } from 'pdfjs-dist';
 import { default as React_2 } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { ReactPortal } from 'react';
 import { RefAttributes } from 'react';
 import { StoreApi } from 'zustand';
 import type { TypedArray } from 'pdfjs-dist/types/src/display/api';
@@ -21,6 +23,12 @@ import { useFloating } from '@floating-ui/react';
 import { useInteractions } from '@floating-ui/react';
 import type { Virtualizer } from '@tanstack/react-virtual';
 
+/** Shared indexing with bounded PDF.js work; release when the consumer leaves. */
+export declare function acquireDocumentText(pages: PDFPageProxy[]): {
+    promise: Promise<PageText[]>;
+    release(): void;
+};
+
 declare interface Annotation {
     id: string;
     pageNumber: number;
@@ -153,6 +161,15 @@ declare interface AnnotationTooltipProps {
  */
 export declare function applyContextRecolor(ctx: CanvasRenderingContext2D, map: RenderColorMap, options?: RecolorContextOptions): (finalizeRender?: boolean) => void;
 
+declare interface AsyncSearchOptions extends SearchOptions {
+    /** Cancelling rejects with AbortError and never publishes partial results. */
+    signal?: AbortSignal;
+    /** Approximate work budget between yields; defaults to 8 ms. */
+    timeSliceMs?: number;
+}
+export { AsyncSearchOptions }
+export { AsyncSearchOptions as AsyncSearchOptions_alias_1 }
+
 export declare function calculateHighlightRects(pageProxy: PDFPageProxy, textMatch: TextPosition): Promise<HighlightRect[]>;
 
 export declare const cancellable: <T extends Promise<unknown>>(promise: T) => {
@@ -208,6 +225,9 @@ export declare function computeBaseScale(dpr: number, zoom: number, pageWidth: n
 
 export declare function computeTargetScale(dpr: number, zoom: number): number;
 
+/** Reuses two rows across candidate windows and only visits the edit band. */
+export declare function createBoundedDistance(query: string, maxDistance: number): (text: string, offset: number) => number;
+
 /**
  * Builds a memoized color map that flips perceived lightness onto the
  * background<->foreground ramp while preserving hue and chroma (OKLab).
@@ -247,6 +267,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;
@@ -285,6 +312,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"> {
@@ -357,10 +391,15 @@ export declare class LinkService {
 
 export declare const loadPdfJs: () => Promise<pdfjsDist>;
 
+/** Ordered results with bounded in-flight work and cooperative cancellation. */
+export declare function mapConcurrent<T, R>(items: readonly T[], concurrency: number, map: (item: T, index: number) => Promise<R>, isCancelled?: () => boolean): Promise<R[]>;
+
 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> & {
@@ -399,6 +438,11 @@ export declare const Pages: ({ children, gap, virtualizerOptions, initialOffset,
     onOffsetChange?: (offset: number) => void;
 }) => JSX.Element;
 
+declare type PageText = {
+    pageNumber: number;
+    text: string;
+};
+
 export declare interface PdfJsAssetUrls {
     wasmUrl: string;
     cMapUrl: string;
@@ -474,6 +518,13 @@ export declare interface RecolorContextOptions {
     pageArea?: number;
 }
 
+declare type Rect = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+
 /**
  * Removes any recolor wrapper installed on the context. For long-lived
  * contexts (the visible canvas in the no-buffer fallback, thumbnails) that
@@ -553,17 +604,33 @@ export declare interface ScanPaperClass {
     inked: boolean;
 }
 
-export declare const Search: ({ children, loading }: SearchProps) => ReactNode;
+export declare const Search: ({ children, loading, errorFallback, }: SearchProps) => string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | ReactPortal | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | JSX.Element | null | undefined;
+
+export declare function searchDocument(pages: SearchPage[], searchText: string, options?: SearchOptions): SearchResults;
+
+export declare function searchDocumentAsync(pages: SearchPage[], searchText: string, options?: AsyncSearchOptions): Promise<SearchResults>;
 
 declare interface SearchOptions {
     threshold?: number;
     limit?: number;
     textSize?: number;
 }
+export { SearchOptions }
+export { SearchOptions as SearchOptions_alias_1 }
+
+declare type SearchPage = {
+    pageNumber: number;
+    text: string;
+};
 
 declare interface SearchProps {
     children: React.ReactNode;
     loading?: React.ReactNode;
+    /** Replace the default indexing-error message and retry button. */
+    errorFallback?: (state: {
+        error: unknown;
+        retry: () => void;
+    }) => React.ReactNode;
 }
 
 export declare interface SearchResult {
@@ -610,6 +677,11 @@ 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;
@@ -617,19 +689,32 @@ declare interface TextPosition {
     searchText?: string;
 }
 
-export declare const Thumbnail: ({ pageNumber, ...props }: HTMLProps<HTMLCanvasElement> & {
+export declare const Thumbnail: ({ pageNumber, eager, ...props }: HTMLProps<HTMLCanvasElement> & {
     pageNumber?: number;
+    eager?: boolean;
 }) => JSX.Element;
 
-export declare const Thumbnails: ({ children, ...props }: HTMLProps<HTMLDivElement> & {
-    children: ReactElement<typeof Thumbnail>;
-}) => JSX.Element;
+export declare const Thumbnails: ({ children, virtualize, ...props }: ThumbnailsProps) => JSX.Element;
+
+declare type ThumbnailsProps = HTMLProps<HTMLDivElement> & {
+    children: ReactElement;
+    /** Opt in to a bounded list. Give the container a height and each row content that fits itemHeight. */
+    virtualize?: ThumbnailVirtualization;
+};
+
+declare interface ThumbnailVirtualization {
+    /** Fixed row height in CSS pixels, including any desired space between items. */
+    itemHeight: number;
+    overscan?: number;
+}
 
 export declare const TotalPages: ({ ...props }: HTMLProps<HTMLDivElement>) => JSX.Element;
 
 export declare const USE_LAYOUT_ZOOM: boolean;
 
-declare const useAnnotations: () => AnnotationState;
+declare function useAnnotations<T>(selector: (state: AnnotationState) => T): T;
+
+declare function useAnnotations(): AnnotationState;
 export { useAnnotations }
 export { useAnnotations as useAnnotations_alias_1 }
 
@@ -653,6 +738,10 @@ declare interface UseAnnotationTooltipReturn {
 
 export declare const useCreatePDFLinkService: (pdfDocumentProxy: PDFDocumentProxy | null) => LinkService;
 
+declare function usePageAnnotations(pageNumber: number): Annotation[];
+export { usePageAnnotations }
+export { usePageAnnotations as usePageAnnotations_alias_1 }
+
 declare const usePageRendered: (pageNumber: number) => boolean;
 export { usePageRendered }
 export { usePageRendered as usePageRendered_alias_1 }
@@ -697,7 +786,7 @@ export declare interface usePDFDocumentParams {
     /**
      * Override or extend the PDF.js DocumentInitParameters passed to getDocument().
      * These take highest precedence over both the source object and lector's defaults.
-     * Must be a stable reference (module-level constant or useMemo) to avoid reloading the document.
+     * Read when source changes; changing options alone does not reload the document.
      */
     documentOptions?: Partial<DocumentInitParameters>;
     /**
@@ -750,6 +839,9 @@ export declare const useSearch: () => {
     keywords: string[];
     searchResults: SearchResults;
     search: (searchText: string, options?: SearchOptions) => SearchResults;
+    searchAsync: (searchText: string, options?: AsyncSearchOptions) => Promise<SearchResults>;
+    cancelSearch: () => void;
+    isSearching: boolean;
 };
 
 export declare const useSelectionDimensions: () => {

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export { calculateHighlightRects } from './_tsup-dts-rollup.js';
 export { Annotation } from './_tsup-dts-rollup.js';
 export { AnnotationsStoreProvider } from './_tsup-dts-rollup.js';
 export { useAnnotations } from './_tsup-dts-rollup.js';
+export { usePageAnnotations } from './_tsup-dts-rollup.js';
 export { usePageRendered } from './_tsup-dts-rollup.js';
 export { LinkService } from './_tsup-dts-rollup.js';
 export { PDFLinkServiceContext } from './_tsup-dts-rollup.js';
@@ -47,3 +48,5 @@ export { createDarkModeColorMap } from './_tsup-dts-rollup.js';
 export { DarkModeColors } from './_tsup-dts-rollup.js';
 export { DEFAULT_DARK_MODE_COLORS } from './_tsup-dts-rollup.js';
 export { RenderColorMap } from './_tsup-dts-rollup.js';
+export { AsyncSearchOptions } from './_tsup-dts-rollup.js';
+export { SearchOptions } from './_tsup-dts-rollup.js';