@hamster-note/reader 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 仓鼠笔记
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# @hamster-note/reader
+
+React reader component package for Hamster Note.
+
+## 安装
+
+Install the package and its peer dependencies:
+
+```bash
+yarn add @hamster-note/reader react react-dom
+```
+
+## 使用
+
+Styles are not injected automatically. Import `@hamster-note/reader/style.css` explicitly before rendering `Reader`.
+
+```tsx
+import { Reader } from '@hamster-note/reader'
+import type { ReaderProps } from '@hamster-note/reader'
+import '@hamster-note/reader/style.css'
+
+const document: NonNullable<ReaderProps['document']> = {
+  id: 'demo-document',
+  title: 'Hello Hamster',
+  pages: []
+}
+
+export function App() {
+  return <Reader document={document} emptyText='No document' />
+}
+```
+
+### How It Works
+
+`Reader` is parser-agnostic. It accepts an intermediate document (produced by parser packages such as `@hamster-note/pdf-parser`, `@hamster-note/docx-parser`, etc.) and renders it through the intermediate-document renderer. Pages are rendered in `contain` fit mode by default (hardcoded inside `IntermediateDocumentViewer`).
+
+The renderer lazily loads page content on demand via a visibility-debounced queue with concurrency control and offscreen-release, designed for long documents without blocking the main thread.
+
+#### Lazy Page Loading Props
+
+The following optional props control the lazy loading queue:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `initialLoadedPages` | `number` | `1` | Number of pages to load immediately on mount (before visibility-based queue kicks in). |
+| `pageLoadConcurrency` | `number` | `3` | Maximum number of pages loaded concurrently. |
+| `pageLoadEnterDelayMs` | `number` | `500` | A non-initial page must remain continuously visible for this duration (ms) before its content load is enqueued. Prevents fast-scroll from triggering loads. |
+| `pageUnloadDelayMs` | `number` | `5000` | After a loaded page leaves the visible window, wait this duration (ms) before unloading its content back to an empty shell. Re-entering before the delay cancels the unload. |
+
+#### Render Timing
+
+To diagnose bottlenecks in the render pipeline, you can opt in to stage-by-stage timing logs. Production builds emit **no timing output by default**.
+
+**Activation paths:**
+
+1. **Callback prop** — receive every timing entry in code:
+   ```tsx
+   <Reader
+     document={document}
+     onIntermediateDocumentRenderTiming={(entry) => {
+       console.table(entry)
+     }}
+   />
+   ```
+
+2. **Environment flag** — print `console.debug` logs when no callback is provided:
+   ```bash
+   VITE_HAMSTER_READER_INTERMEDIATE_TIMING=true
+   ```
+
+Each entry has the following shape:
+
+| Field | Type | Description |
+|---|---|---|
+| `stage` | `string` | One of `document-resolution`, `shell-rendering`, `initial-page-loading`, `content-extraction`, `page-content-rendering`, `visibility-lazy-loading`, `offscreen-unload`, `ocr-processing`. |
+| `startedAt` | `number` | Start timestamp (ms). |
+| `endedAt` | `number` | End timestamp (ms). |
+| `durationMs` | `number` | `endedAt - startedAt`. |
+| `pageNumber` | `number` *(optional)* | Present for page-scoped stages. |
+| `detail` | `object` *(optional)* | Stage-specific context such as `pageCount`, `textCount`, `imageCount`, or `status`. |
+
+#### Demo Upload Formats
+
+The browser Demo supports uploading and previewing the following formats:
+
+- **PDF** (`.pdf`)
+- **TXT** (`.txt`)
+- **DOCX** (`.docx`)
+- **Markdown** (`.md`, `.markdown`)
+
+EPUB (`.epub`) is **not supported** in this browser Demo because `@hamster-note/epub-parser` is Node.js-only and requires a separate server-side design.
+
+## API Notes
+
+Enable OCR for visible pages with the `ocr` prop, and listen for text selection updates with `onTextSelectionChange` and `onTextSelectionEnd`.
+
+```tsx
+<Reader
+  document={document}
+  ocr
+  onTextSelectionChange={(text, detail) => {
+    // handle selection change
+  }}
+  onTextSelectionEnd={(text, detail) => {
+    // handle selection end
+  }}
+/>
+```
+
+## Text Selection (@hamster-note/selection)
+
+`Reader` integrates [`@hamster-note/selection`](https://www.npmjs.com/package/@hamster-note/selection) to provide rich text-selection features, highlighted ranges, popovers, and programmatic control on top of the native browser `Selection` API.
+
+The `<Selection>` component wraps page content inside `<VirtualPaper>` and is active by default. The legacy native callbacks (`onTextSelectionChange`, `onTextSelectionEnd`, `onSelectText`) continue to fire alongside the linked-range Selection component.
+
+### Linked range shape
+
+`Reader` uses a linked range shape. Each endpoint carries a public page `selectionId`, and overlay rectangles are grouped by that page id in `rectsBySelectionId`.
+
+```ts
+{
+  id: 'highlight-1',
+  text: 'Selected text',
+  start: { selectionId: 'page-1', offset: 12 },
+  end: { selectionId: 'page-2', offset: 34 },
+  createdAt: Date.now(),
+  overlayRectType: 'percent',
+  rectsBySelectionId: {
+    'page-1': [{ x: 0.1, y: 0.2, width: 0.5, height: 0.05 }],
+    'page-2': [{ x: 0.05, y: 0.1, width: 0.4, height: 0.05 }]
+  }
+}
+```
+
+Public page ids are always `page-${pageNumber}` (for example, `page-1`, `page-2`). Internally, each `Reader` instance scopes runtime Selection ids so two Readers on the same page cannot collide, but public callbacks and stored data stay unscoped. You should only read and write the public `page-${pageNumber}` ids.
+
+### Quick Start (linked selection)
+
+```tsx
+import { Reader } from '@hamster-note/reader'
+import type { ReaderSelectionRange } from '@hamster-note/reader'
+import '@hamster-note/reader/style.css'   // includes Selection CSS
+import { useState } from 'react'
+
+const initialRanges: ReaderSelectionRange[] = [
+  {
+    id: 'highlight-1',
+    text: 'Selected text on page 1',
+    start: { selectionId: 'page-1', offset: 12 },
+    end: { selectionId: 'page-1', offset: 34 },
+    createdAt: Date.now(),
+    overlayRectType: 'percent',
+    rectsBySelectionId: {
+      'page-1': [{ x: 0.1, y: 0.2, width: 0.5, height: 0.05 }]
+    }
+  }
+]
+
+export function App() {
+  // 受控模式：Reader 不内部修改 ranges，由 onSelect 回调外部追加
+  const [ranges, setRanges] = useState<ReaderSelectionRange[]>(initialRanges)
+
+  return (
+    <Reader
+      document={document}
+      ranges={ranges}
+      overlayRectType='percent'
+      onSelect={(range) => setRanges((prev) => [...prev, range])}
+      onUpdateRange={(range) =>
+        setRanges((prev) => prev.map((r) => (r.id === range.id ? range : r)))
+      }
+    />
+  )
+}
+```
+
+### Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `ranges` | `ReaderSelectionRange[]` | Controlled highlight ranges in the linked shape. Reader does not mutate this array. |
+| `defaultRanges` | `ReaderSelectionRange[]` | Initial ranges for uncontrolled mode (when `ranges` is omitted). |
+| `selectedRangeId` | `string \| null` | Controlled currently-selected range ID. |
+| `defaultSelectedRangeId` | `string \| null` | Initial selected range ID for uncontrolled mode. |
+| `onSelect` | `(range: ReaderSelectionRange) => void` | Fired when the user finishes a new selection. In uncontrolled mode, Reader appends the range internally before calling this. |
+| `onSelectRange` | `(id: string \| null) => void` | Fired when the user clicks an existing highlight. |
+| `onUpdateRange` | `(range: ReaderSelectionRange) => void` | Fired when the user drags a selected highlight range handle. In uncontrolled mode, Reader replaces the matching range internally before calling this; controlled callers must update their `ranges` array. |
+| `onHighlight` | `(range: ReaderSelectionRange) => void` | Fired when a range is highlighted via the ref API or via Reader's internal auto-highlight (when `autoHighlight` is enabled). |
+| `onSelectionStart` | `(mousePos: ReaderMousePosition, selection: Selection) => void` | Fired when a selection gesture begins. |
+| `onSelectionEnd` | `(mousePos: ReaderMousePosition, selection: Selection) => void` | Fired when a selection gesture ends (mouseup-based; touch selection may not trigger this). |
+| `autoHighlight` | `boolean` | When true, completing a text selection automatically creates a highlight. Reader fires `onHighlight` but does not append to ranges array. Defaults to `false`. |
+| `highlightColor` | `string` | CSS color for highlight overlays. In Phase 1, this applies globally to all highlights. |
+| `selectionColor` | `string` | CSS color for active selection overlay. |
+| `selectionPopover` | `React.ReactNode` | Custom popover content shown during active selection (before it becomes a highlight). |
+| `highlightPopover` | `React.ReactNode` | Custom popover content shown when an existing highlight is clicked. |
+| `selectionRef` | `React.Ref<ReaderSelectionRef>` | Reader-owned command ref, distinct from the upstream Selection component ref. Exposes `highlight()`, `clear()`, and additive `scrollToRange(id)` for jumping to an existing range. |
+| `overlayRectType` | `ReaderSelectionOverlayRectType` | Controls whether selection overlay rectangles are stored/rendered as pixel (`'px'`) or percentage (`'percent'`) coordinates relative to the selection container. Defaults to `'percent'`. |
+
+### Exported Types
+
+```ts
+import type {
+  ReaderSelectionRange,    // linked: { id, text, start, end, rectsBySelectionId, overlayRectType? }
+  ReaderSelectionOverlayRectType,  // 'px' | 'percent'
+  ReaderSelectionRef,      // { highlight(): void; clear(): void; scrollToRange(id: string): void }
+  ReaderMousePosition      // { x, y }, viewport coordinates (clientX/clientY)
+} from '@hamster-note/reader'
+```
+
+### CSS
+
+`@hamster-note/reader/style.css` already bundles the Selection library CSS (`.hsn-selection-*` classes). No additional import is needed.
+
+### Legacy Selection Callbacks
+
+The existing `onTextSelectionChange`, `onTextSelectionEnd`, and `onSelectText` callbacks are preserved for backward compatibility. They continue to fire through the native `mouseup`/`touchend`/`selectionchange` listeners on the viewer root element, independent of the `<Selection>` component. They are not affected by the linked range shape.
+
+> **Note**: `onSelectionEnd` is **mouseup-based**. On touch devices, the selection-end signal relies on the legacy `touchend` listener (which fires `onTextSelectionEnd` / `onSelectText`), not `onSelectionEnd`.
+
+### Demo localStorage Migration
+
+The browser Demo persists highlights to localStorage keyed by filename. The stored shape is now `{ version: 2, ranges: ReaderSelectionRange[] }`. Older unversioned bare arrays, or legacy objects with flat numeric `start`/`end` and `rects`, are ignored and return `[]`. Their page ownership cannot be proven, so the demo does not attempt to migrate them. If you have old data, recreate the highlights instead.
+
+### Programmatic Control
+
+`selectionRef` exposes Reader-level commands. `highlight()` and `clear()` are forwarded to the active page Selection instances; `scrollToRange(id)` is implemented by Reader to translate the VirtualPaper viewport to an existing range while preserving the current scale.
+
+```tsx
+import { useRef } from 'react'
+import type { ReaderSelectionRef } from '@hamster-note/reader'
+
+const selectionRef = useRef<ReaderSelectionRef>(null)
+
+// Highlight the current native selection as a range
+selectionRef.current?.highlight()
+
+// Clear all highlights
+selectionRef.current?.clear()
+
+// Scroll the viewer to a specific range by id
+selectionRef.current?.scrollToRange('highlight-1')
+```
+
+## Peer Dependencies
+
+- `react@^19.0.0`
+- `react-dom@^19.0.0`
+
+## 开发脚本
+
+- `yarn dev`: start the local Vite dev server.
+- `yarn build:lib`: build the library output in `dist/`.
+- `yarn build:demo`: build the local demo output in `demo-dist/`.
+- `yarn build:all`: build the library and demo.
+- `yarn build`: run `yarn build:all`.
+- `yarn typecheck`: run TypeScript type checking.
+- `yarn lint`: run ESLint.
+- `yarn test`: start Vitest in watch mode.
+- `yarn test:run`: run Vitest once.
+- `yarn preview`: preview the demo build.
+- `yarn prepublishOnly`: build the library before publish.
+
+## 发版规则
+
+- Push `version/x.y.z` branches for stable releases.
+- Push `version/x.y.z-*` branches for pre-releases.
+- Publish tag selection follows the package version suffix: no suffix -> `latest`, `-dev` -> `dev`, `-beta` -> `beta`.

package/dist/components/IntermediateDocumentViewer/IntermediateDocumentPageContent.d.ts

@@ -0,0 +1,40 @@
+import type { IntermediateImage, IntermediateText } from '@hamster-note/types';
+/**
+ * `intermediate-document` 默认模式已加载页面的内容渲染器。
+ *
+ * 该组件渲染在外壳 `.hamster-reader__intermediate-page` 内部，负责把已加载
+ * 的页面内容 bundle（基础底图、文本 span、OCR 文本 span、IntermediateImage
+ * 内容项）绘制到 DOM。它复用统一的几何辅助函数，
+ * 以保证选择、OCR 与测试行为一致。
+ *
+ * 关键约束：
+ * - 绝不使用 `dangerouslySetInnerHTML`；所有内容均由 React 元素渲染。
+ * - 保留 thumbnail / base-image duck typing。
+ * - 文本 span 沿用 `.hamster-reader__intermediate-text` + `data-text-id` +
+ *   `data-page-number`，以便选择载荷序列化器 / OCR / 测试正常工作。
+ * - IntermediateImage 内容项以绝对定位 `<img>` 绘制，几何由 polygon 决定。
+ */
+/**
+ * 文本 ref 注册回调类型 —— 与 viewer 内 `SetTextRef` 结构兼容，
+ * 使文本 span 能被选择载荷追踪。
+ */
+export type IntermediateDocumentSetTextRef = (text: IntermediateText, pageNumber: number) => (element: HTMLSpanElement | null) => void;
+export type IntermediateDocumentPageContentProps = {
+    /** 当前页码（用于 data-page-number 与文本 ref 注册） */
+    pageNumber: number;
+    /** getContent() 返回的文本内容（已过滤掉图片项） */
+    texts: IntermediateText[];
+    /** OCR 识别产生的文本 span（id 已带 ocr- 前缀） */
+    ocrTexts: IntermediateText[];
+    /** 基础底图 URL（来自 thumbnail / image / getThumbnail() 的 duck typing 解析） */
+    baseImageSource: string | undefined;
+    /** getContent() 返回的 IntermediateImage 内容项 */
+    images: IntermediateImage[];
+    /** 文本 span ref 注册回调 */
+    setTextRef: IntermediateDocumentSetTextRef;
+    onRenderTiming?: (pageNumber: number, startTime: number, commitTime: number, actualDuration: number) => void;
+};
+declare function IntermediateDocumentPageContentComponent({ pageNumber, texts, ocrTexts, baseImageSource, images, setTextRef, onRenderTiming }: IntermediateDocumentPageContentProps): import("react/jsx-runtime").JSX.Element;
+export declare const IntermediateDocumentPageContent: import("react").MemoExoticComponent<typeof IntermediateDocumentPageContentComponent>;
+export {};
+//# sourceMappingURL=IntermediateDocumentPageContent.d.ts.map

package/dist/components/IntermediateDocumentViewer/IntermediateDocumentPageContent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntermediateDocumentPageContent.d.ts","sourceRoot":"","sources":["../../../src/components/IntermediateDocumentViewer/IntermediateDocumentPageContent.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAW9E;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,CAC3C,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,MAAM,KACf,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,KAAK,IAAI,CAAA;AAE9C,MAAM,MAAM,oCAAoC,GAAG;IACjD,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,oCAAoC;IACpC,KAAK,EAAE,gBAAgB,EAAE,CAAA;IACzB,sCAAsC;IACtC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B,uEAAuE;IACvE,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,6CAA6C;IAC7C,MAAM,EAAE,iBAAiB,EAAE,CAAA;IAC3B,uBAAuB;IACvB,UAAU,EAAE,8BAA8B,CAAA;IAC1C,cAAc,CAAC,EAAE,CACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,KACnB,IAAI,CAAA;CACV,CAAA;AA0DD,iBAAS,wCAAwC,CAAC,EAChD,UAAU,EACV,KAAK,EACL,QAAQ,EACR,eAAe,EACf,MAAM,EACN,UAAU,EACV,cAAc,EACf,EAAE,oCAAoC,2CAmDtC;AAED,eAAO,MAAM,+BAA+B,sFAE3C,CAAA"}