flipbookengine 1.0.0 → 1.0.2

package/docs/api-reference.md

@@ -1,206 +1,228 @@
-# API Reference
-
-This document describes the options, methods, and events exposed by the `FlipbookEngine` class.
-
-## Constructor Options
-
-When instantiating `new FlipbookEngine(selector, options)`, you can configure the following options:
-
-| Property | Type | Default | Description |
-|---|---|---|---|
-| `allowDownload` | `boolean` | `true` | Exposes a download button in the toolbar. |
-| `showThumbs` | `boolean` | `false` | Starts the viewer with the thumbnail navigation rail hidden. |
-| `showToc` | `boolean` | `false` | Shows the supplied table of contents panel when it contains entries. |
-| `toc` | `FlipbookTocEntry[]` | `[]` | Host-provided chapter/category entries using zero-based page indexes. |
-| `showArrows` | `boolean` | `true` | Shows the previous/next navigation arrows. |
-| `primaryColor` | `string` | `'#7367f0'` | Sets the primary theme accent color. |
-| `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Force light/dark mode or let it respond automatically. |
-| `locale` | `'en' \| 'tr' \| string` | `'en'` | Active language interface. |
-| `soundEnabled` | `boolean` | `true` | Enables page turning sound effect. |
-| `soundUrl` | `string` | `'https://flipbookengine.com/Content/page-flip.mp3'` | URL of the page turning audio file. |
-| `autoPlayInterval` | `number` | `3000` | Duration (ms) before automatically turning to the next page in Autoplay mode. |
-| `flippingTime` | `number` | `1000` | Duration (ms) of the page turning animation; automatically set to `0` when reduced motion is preferred. |
-| `maxShadowOpacity` | `number` | `0.5` | Maximum opacity of the shadow during page turn (0 to 1). |
-| `messages` | `Record<string, PartialFlipbookMessages>` | `null` | Custom localization overrides. |
-| `cssVariables` | `Record<string, string>` | `null` | Per-instance custom CSS property overrides. |
-| `whiteLabel` | `boolean` | `false` | If true, hides the "Powered by FlipbookEngine" watermark. |
-| `watermarkUrl` | `string` | `null` | Custom image logo URL for watermark attribution. |
-| `pdfRenderConcurrency` | `number` | `3` | Maximum number of PDF pages rendered concurrently when on-demand pages are requested. |
-| `pdfRenderCacheSize` | `number` | `32` | Maximum number of rendered PDF page images retained per engine instance (LRU); `0` disables caching. |
-| `pdfPageMode` | `'auto' \| 'single' \| 'split'` | `'auto'` | Automatically split A3 landscape pages, split every landscape page, or keep source pages intact. |
-| `background` | `FlipbookBackgrounds \| null` | `null` | Optional per-theme viewer background styles. |
-| `deepLink` | `boolean` | `false` | Synchronizes the active page with a `?page=` URL parameter and browser history. |
-| `onShare` | `(url: string) => void` | `null` | Optional callback invoked after the localized toolbar Share control shares or copies the generated page URL. |
-| `bookmarks` | `number[]` | `[]` | Initial zero-based page indexes marked as bookmarks; persistence remains with the host application. |
-| `notes` | `Record<number, string>` | `{}` | Initial page notes keyed by zero-based page index; the localized toolbar editor is host-storage agnostic. |
-| `hotspots` | `FlipbookHotspot[]` | `[]` | Normalized page overlays with accessible labels, media/gallery previews, plain-text content, and optional commerce links. |
-| `annotations` | `FlipbookAnnotation[]` | `[]` | Host-managed page note markers with normalized coordinates and plain-text popup content. |
-
----
-
-## Public Methods
-
-### `init(pdfUrl: string, imageList?: FlipbookPageAsset[])`
-Initializes and mounts the viewer into the container element. Returns a `Promise<void>`.
-
-### `goToPage(pageIndex: number)`
-Programmatically turns to the specified 0-based page index.
-
-### `getCurrentPage()`
-Returns the 0-based index of the currently active page.
-
-### `getTotalPages()`
-Returns the total count of normalized pages.
-
-### `getZoom()`
-Returns the current zoom scale (usually `1` to `5`).
-
-### `setZoom(zoomLevel: number)`
-Sets the zoom scale. Acceptable bounds are `0.5` to `5`.
-
-### `setSingleMode(isSingle: boolean)`
-Enforces single page layout (typically for mobile viewports) or spread mode.
-
-### `toggleFullscreen()`
-Toggles browser fullscreen.
-
-### `updateOptions(options: Partial<FlipbookEngineOptions>)`
-Updates options dynamically at runtime.
-
-### `setLocale(locale: string, messages?: PartialFlipbookMessages | Record<string, PartialFlipbookMessages>)`
-Changes the UI language programmatically.
-
-### `getPageUrl(pageIndex = getCurrentPage())`
-Returns a shareable URL with a 1-based `?page=` parameter for the requested 0-based page index.
-
-### `sharePage(pageIndex = getCurrentPage())`
-Uses the native share dialog when available, otherwise copies the page URL to the clipboard. The toolbar exposes this behavior through a localized Share button. Enable `deepLink: true` in the receiving viewer to resolve the `?page=` parameter.
-
-### Bookmark methods
-
-`getBookmarkedPages()`, `isBookmarked()`, `setBookmark(pageIndex, bookmarked)`, and `toggleBookmark(pageIndex)` manage zero-based bookmark state. The `bookmarkChange` event payload is `{ pageIndex, pageNumber, bookmarked }`; hosts should persist this payload in their own storage.
-
-`getNotes()`, `getNote(pageIndex)`, `setNote(pageIndex, note)`, and `clearNote(pageIndex)` manage host-owned notes. The toolbar's localized **Page note** button opens an inline editor; empty notes are removed; `noteChange` emits `{ pageIndex, pageNumber, note }` with `null` when a note is cleared. Hosts can persist that payload in a database or other storage.
-
-### `connectEmbed(options?: FlipbookEmbedOptions)`
-Connects an origin-validated postMessage bridge for iframe integrations. Call this from the document loaded inside the iframe.
-
-### `destroy(keepContainer = false)`
-Tears down the instance, unsubscribes all event handlers, and optionally clears the container element HTML.
-
----
-
-## Iframe embedding
-
-Embed integrations use a small, origin-validated `postMessage` bridge. The viewer page (inside the iframe) connects the bridge:
-
-```ts
-const engine = new FlipbookEngine('#viewer', { showThumbs: false });
-const embedBridge = engine.connectEmbed({
-  allowedOrigins: ['https://catalog.example.com']
-});
-await engine.init('/files/catalog.pdf');
-```
-
-The parent page can control the iframe with the exported controller:
-
-```ts
-import { createFlipbookEmbedController } from 'flipbookengine';
-
-const iframe = document.querySelector('#catalog-frame') as HTMLIFrameElement;
-const catalog = createFlipbookEmbedController(iframe, {
-  targetOrigin: 'https://viewer.example.com'
-});
-
-await catalog.goToPage(3);
-await catalog.setZoom(1.5);
-catalog.on('pageChange', (state) => console.log(state.pageNumber));
-```
-
-Commands are restricted to navigation, zoom, single-mode, option updates, fullscreen, TOC read/update, search, and state queries. Configure an explicit `allowedOrigins` value in the iframe and `targetOrigin` value in the parent for cross-origin deployments. The bridge rejects messages from other windows or origins.
-
-## Event Subscriptions
-
-Use `.on(eventName, handler)` to listen to runtime events:
-
-```javascript
-const unsubscribe = engine.on('pageChange', ({ currentPage, pageNumber, totalPages, isSingle }) => {
-  console.log(`Now on page ${pageNumber} of ${totalPages}`);
-});
-```
-
-### Supported Events
-
-- **`pageChange`**: Emitted when page is changed.
-  - Payload: `{ currentPage: number; pageNumber: number; totalPages: number; isSingle: boolean }`
-- **`zoomChange`**: Emitted when zoom factor changes.
-  - Payload: `{ zoom: number; isActive: boolean }`
-- **`singlePageModeChange`**: Emitted when switching layout mode.
-  - Payload: `{ isSingle: boolean }`
-- **`thumbsToggle`**: Emitted when thumbnail rail is toggled.
-- **`tocToggle`**: Emitted when the table of contents panel is toggled.
-  - Payload: `{ showToc: boolean }`
-  - Payload: `{ showThumbs: boolean }`
-- **`init`**: Emitted after the viewer is ready. Payload: `{ totalPages: number }`
-- **`progress`**: Emitted during PDF loading/rendering. Payload: `{ phase: 'loading' | 'rendering'; completed: number; total: number }`
-- **`orientationChange`**: Emitted when layout orientation changes. Payload: `{ orientation: 'landscape' | 'portrait' }`.
-- **`deepLinkChange`**: Emitted when the active page updates the shareable URL. Payload: `{ pageIndex: number; pageNumber: number; url: string }`.
-- **`bookmarkChange`**: Emitted when a page bookmark is added or removed. Payload: `{ pageIndex: number; pageNumber: number; bookmarked: boolean }`.
-- **`noteChange`**: Emitted when a page note is added, updated, or cleared. Payload: `{ pageIndex: number; pageNumber: number; note: string | null }`.
-- **`error`**: Emitted when PDF loading/rendering fails. Payload: `{ code: 'PDF_LOAD_FAILED' | 'PDF_RENDER_FAILED'; message: string; cause?: unknown }`
-- **`destroy`**: Emitted when the engine is destroyed.
-
-
-## PDF rendering lifecycle
-
-When `pdfUrl` is supplied without a `pages` list, the engine creates lightweight page placeholders immediately after the document metadata loads. The first page is rendered before `init()` resolves, and the next page is prefetched. Remaining pages render on demand as they become visible or are selected. Rendering requests are deduplicated per page and cancelled when initialization is superseded or the engine is destroyed.
-
-Use `pdfRenderConcurrency` to bound concurrent PDF.js work and `pdfRenderCacheSize` to configure the per-instance LRU cache. Set the cache size to `0` when rendered page data should not be retained. `pdfPageMode: 'auto'` detects ISO A3 landscape pages and exposes their left/right halves as two logical pages; `'single'` disables splitting and `'split'` splits every landscape page.
-
-## PDF page formats
-
-The viewer derives its page ratio from PDF.js metadata or the supplied image asset. Portrait A4 and landscape A4 are both supported. For a landscape A3 page that contains two A4 pages, use the default `pdfPageMode: 'auto'` or explicit `'split'`; each half becomes a navigable logical page.
-
-## Table of contents
-
-TOC entries are supplied by the host application so the viewer stays backend-agnostic. `pageIndex` is zero-based and is clamped to the loaded page range. Nested `children` entries are supported.
-
-Use `engine.getToc()` to read the normalized tree or `engine.setToc(entries, show?)` to replace it at runtime. The open-source viewer consumes this manifest; it does not extract PDF outline destinations or generate OCR metadata.
-
-```ts
-const engine = new FlipbookEngine('#viewer', {
-  toc: [
-    { title: 'Introduction', pageIndex: 0 },
-    { title: 'Products', pageIndex: 4, children: [
-      { title: 'Category A', pageIndex: 5 }
-    ] }
-  ],
-  showToc: true
-});
-```
-
-### Search
-
-- **`search(query, options?)`**: Extracts and searches PDF text client-side. Returns `{ pageIndex, pageNumber, matches, snippet, sourcePageNumber, highlights? }[]`, stores results for the built-in search panel, and overlays matching text rectangles. `pageIndex` is zero-based; `pageNumber` is one-based. `highlights` coordinates are normalized to the logical page (0..1), including left/right mapping for split PDF pages.
-- **`clearSearch()`** / **`getSearchResults()`**: Clears or reads the current search state.
-
-### Hotspots
-
-- **`getHotspots(pageIndex = getCurrentPage())`**: Returns host-provided overlays for a logical page.
-- **`activateHotspot(id)`** / **`closeHotspot()`**: Opens or closes a hotspot popup. Activation emits `hotspotActivate`. Hotspots may include `kind`, `media` (`image`, `video`, `audio`), `gallery` image items, and an optional `href` for commerce/product links; popup text is always rendered as plain text.
-
-
-### Page annotations
-
-Host uygulamaları, kullanıcı notunu sayfa üzerindeki normalize koordinata bağlamak için `annotations` seçeneğini kullanabilir. Marker tıklaması popup açar ve `annotationActivate` olayı yayınlanır. Bu sözleşme şimdilik host-managed'dir; annotation kayıtlarının backend koordinatlarına taşınması tüketici uygulamanın sorumluluğundadır.
-
-```ts
-const engine = new FlipbookEngine('#viewer', {
-  annotations: [{ id: 'note-1', pageIndex: 4, x: .42, y: .36, text: 'Review pricing' }]
-});
-```
-
-## Plugins
-
-See [Plugin architecture](./plugin-architecture.md) for the v1 plugin contract and lifecycle.
+# API Reference
 
+This document describes the options, methods, and events exposed by the `FlipbookEngine` class.
+
+## Constructor Options
+
+When instantiating `new FlipbookEngine(selector, options)`, you can configure the following options:
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `allowDownload` | `boolean` | `true` | Exposes a download button in the toolbar. |
+| `showThumbs` | `boolean` | `false` | Starts the viewer with the thumbnail navigation rail hidden. |
+| `showToc` | `boolean` | `false` | Shows the supplied table of contents panel when it contains entries. |
+| `toc` | `FlipbookTocEntry[]` | `[]` | Host-provided chapter/category entries using zero-based page indexes. |
+| `showArrows` | `boolean` | `true` | Shows the previous/next navigation arrows. |
+| `primaryColor` | `string` | `'#7367f0'` | Sets the primary theme accent color. |
+| `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Force light/dark mode or let it respond automatically. |
+| `locale` | `'en' \| 'tr' \| string` | `'en'` | Active language interface. |
+| `soundEnabled` | `boolean` | `true` | Enables page turning sound effect. |
+| `soundUrl` | `string` | `'https://flipbookengine.com/Content/page-flip.mp3'` | URL of the page turning audio file. |
+| `autoPlayInterval` | `number` | `3000` | Duration (ms) before automatically turning to the next page in Autoplay mode. |
+| `flippingTime` | `number` | `1000` | Duration (ms) of the page turning animation; automatically set to `0` when reduced motion is preferred. |
+| `maxShadowOpacity` | `number` | `0.5` | Maximum opacity of the shadow during page turn (0 to 1). |
+| `messages` | `Record<string, PartialFlipbookMessages>` | `null` | Custom localization overrides. |
+| `cssVariables` | `Record<string, string>` | `null` | Per-instance custom CSS property overrides. |
+| `whiteLabel` | `boolean` | `false` | If true, hides the "Powered by FlipbookEngine" watermark. |
+| `watermarkUrl` | `string` | `null` | Custom image logo URL for watermark attribution. |
+| `pdfRenderConcurrency` | `number` | `3` | Maximum number of PDF pages rendered concurrently when on-demand pages are requested. |
+| `pdfRenderCacheSize` | `number` | `32` | Maximum number of rendered PDF page images retained per engine instance (LRU); `0` disables caching. |
+| `pdfPageMode` | `'auto' \| 'single' \| 'split'` | `'auto'` | Automatically split A3 landscape pages, split every landscape page, or keep source pages intact. |
+| `background` | `FlipbookBackgrounds \| null` | `null` | Optional per-theme viewer background styles. |
+| `deepLink` | `boolean` | `false` | Synchronizes the active page with a `?page=` URL parameter and browser history. |
+| `onShare` | `(url: string) => void` | `null` | Optional callback invoked after the localized toolbar Share control shares or copies the generated page URL. |
+| `bookmarks` | `number[]` | `[]` | Initial zero-based page indexes marked as bookmarks; persistence remains with the host application. |
+| `notes` | `Record<number, string>` | `{}` | Initial page notes keyed by zero-based page index; the localized toolbar editor is host-storage agnostic. |
+| `hotspots` | `FlipbookHotspot[]` | `[]` | Normalized page overlays with accessible labels, media/gallery previews, plain-text content, and optional commerce links. |
+| `annotations` | `FlipbookAnnotation[]` | `[]` | Host-managed page note markers with normalized coordinates and plain-text popup content. |
+
+---
+
+## Public Methods
+
+### `init(pdfUrl: string, imageList?: FlipbookPageAsset[])`
+Initializes and mounts the viewer into the container element. Returns a `Promise<void>`.
+
+### `goToPage(pageIndex: number)`
+Programmatically turns to the specified 0-based page index.
+
+### `getCurrentPage()`
+Returns the 0-based index of the currently active page.
+
+### `getTotalPages()`
+Returns the total count of normalized pages.
+
+### `getZoom()`
+Returns the current zoom scale (usually `1` to `5`).
+
+### `setZoom(zoomLevel: number)`
+Sets the zoom scale. Acceptable bounds are `0.5` to `5`.
+
+### `setSingleMode(isSingle: boolean)`
+Enforces single page layout (typically for mobile viewports) or spread mode.
+
+### `toggleFullscreen()`
+Toggles browser fullscreen.
+
+### `updateOptions(options: Partial<FlipbookEngineOptions>)`
+Updates options dynamically at runtime.
+
+### `setLocale(locale: string, messages?: PartialFlipbookMessages | Record<string, PartialFlipbookMessages>)`
+Changes the UI language programmatically.
+
+### `getPageUrl(pageIndex = getCurrentPage())`
+Returns a shareable URL with a 1-based `?page=` parameter for the requested 0-based page index.
+
+### `sharePage(pageIndex = getCurrentPage())`
+Uses the native share dialog when available, otherwise copies the page URL to the clipboard. The toolbar exposes this behavior through a localized Share button. Enable `deepLink: true` in the receiving viewer to resolve the `?page=` parameter.
+
+### Bookmark methods
+
+`getBookmarkedPages()`, `isBookmarked()`, `setBookmark(pageIndex, bookmarked)`, and `toggleBookmark(pageIndex)` manage zero-based bookmark state. The `bookmarkChange` event payload is `{ pageIndex, pageNumber, bookmarked }`; hosts should persist this payload in their own storage.
+
+`getNotes()`, `getNote(pageIndex)`, `setNote(pageIndex, note)`, and `clearNote(pageIndex)` manage host-owned notes. The toolbar's localized **Page note** button opens an inline editor; empty notes are removed; `noteChange` emits `{ pageIndex, pageNumber, note }` with `null` when a note is cleared. Hosts can persist that payload in a database or other storage.
+
+### `connectEmbed(options?: FlipbookEmbedOptions)`
+Connects an origin-validated postMessage bridge for iframe integrations. Call this from the document loaded inside the iframe.
+
+### `destroy(keepContainer = false)`
+Tears down the instance, unsubscribes all event handlers, and optionally clears the container element HTML.
+
+---
+
+## Iframe embedding
+
+Embed integrations use a small, origin-validated `postMessage` bridge. The viewer page (inside the iframe) connects the bridge:
+
+```ts
+const engine = new FlipbookEngine('#viewer', { showThumbs: false });
+const embedBridge = engine.connectEmbed({
+  allowedOrigins: ['https://catalog.example.com']
+});
+await engine.init('/files/catalog.pdf');
+```
+
+The parent page can control the iframe with the exported controller:
+
+```ts
+import { createFlipbookEmbedController } from 'flipbookengine';
+
+const iframe = document.querySelector('#catalog-frame') as HTMLIFrameElement;
+const catalog = createFlipbookEmbedController(iframe, {
+  targetOrigin: 'https://viewer.example.com'
+});
+
+await catalog.goToPage(3);
+await catalog.setZoom(1.5);
+catalog.on('pageChange', (state) => console.log(state.pageNumber));
+```
+
+Commands are restricted to navigation, zoom, single-mode, option updates, fullscreen, TOC read/update, search, and state queries. Configure an explicit `allowedOrigins` value in the iframe and `targetOrigin` value in the parent for cross-origin deployments. The bridge rejects messages from other windows or origins.
+
+## Event Subscriptions
+
+Use `.on(eventName, handler)` to listen to runtime events:
+
+```javascript
+const unsubscribe = engine.on('pageChange', ({ currentPage, pageNumber, totalPages, isSingle }) => {
+  console.log(`Now on page ${pageNumber} of ${totalPages}`);
+});
+```
+
+### Supported Events
+
+- **`pageChange`**: Emitted when page is changed.
+  - Payload: `{ currentPage: number; pageNumber: number; totalPages: number; isSingle: boolean }`
+- **`zoomChange`**: Emitted when zoom factor changes.
+  - Payload: `{ zoom: number; isActive: boolean }`
+- **`singlePageModeChange`**: Emitted when switching layout mode.
+  - Payload: `{ isSingle: boolean }`
+- **`thumbsToggle`**: Emitted when thumbnail rail is toggled.
+- **`tocToggle`**: Emitted when the table of contents panel is toggled.
+  - Payload: `{ showToc: boolean }`
+  - Payload: `{ showThumbs: boolean }`
+- **`init`**: Emitted after the viewer is ready. Payload: `{ totalPages: number }`
+- **`progress`**: Emitted during PDF loading/rendering. Payload: `{ phase: 'loading' | 'rendering'; completed: number; total: number }`
+- **`orientationChange`**: Emitted when layout orientation changes. Payload: `{ orientation: 'landscape' | 'portrait' }`.
+- **`deepLinkChange`**: Emitted when the active page updates the shareable URL. Payload: `{ pageIndex: number; pageNumber: number; url: string }`.
+- **`bookmarkChange`**: Emitted when a page bookmark is added or removed. Payload: `{ pageIndex: number; pageNumber: number; bookmarked: boolean }`.
+- **`noteChange`**: Emitted when a page note is added, updated, or cleared. Payload: `{ pageIndex: number; pageNumber: number; note: string | null }`.
+- **`error`**: Emitted when PDF loading/rendering fails. Payload: `{ code: 'PDF_LOAD_FAILED' | 'PDF_RENDER_FAILED'; message: string; cause?: unknown }`
+- **`destroy`**: Emitted when the engine is destroyed.
+
+
+## PDF rendering lifecycle
+
+When `pdfUrl` is supplied without a `pages` list, the engine creates lightweight page placeholders immediately after the document metadata loads. The first page is rendered before `init()` resolves, and the next page is prefetched. Remaining pages render on demand as they become visible or are selected. Rendering requests are deduplicated per page and cancelled when initialization is superseded or the engine is destroyed.
+
+Use `pdfRenderConcurrency` to bound concurrent PDF.js work and `pdfRenderCacheSize` to configure the per-instance LRU cache. Set the cache size to `0` when rendered page data should not be retained. `pdfPageMode: 'auto'` detects ISO A3 landscape pages and exposes their left/right halves as two logical pages; `'single'` disables splitting and `'split'` splits every landscape page.
+
+## PDF page formats
+
+The viewer derives its page ratio from PDF.js metadata or the supplied image asset. Portrait A4 and landscape A4 are both supported. For a landscape A3 page that contains two A4 pages, use the default `pdfPageMode: 'auto'` or explicit `'split'`; each half becomes a navigable logical page.
+
+## Table of contents
+
+TOC entries are supplied by the host application so the viewer stays backend-agnostic. `pageIndex` is zero-based and is clamped to the loaded page range. Nested `children` entries are supported.
+
+Use `engine.getToc()` to read the normalized tree or `engine.setToc(entries, show?)` to replace it at runtime. The open-source viewer consumes this manifest; it does not extract PDF outline destinations or generate OCR metadata.
+
+```ts
+const engine = new FlipbookEngine('#viewer', {
+  toc: [
+    { title: 'Introduction', pageIndex: 0 },
+    { title: 'Products', pageIndex: 4, children: [
+      { title: 'Category A', pageIndex: 5 }
+    ] }
+  ],
+  showToc: true
+});
+```
+
+### Search
+
+- **`search(query, options?)`**: Extracts and searches PDF text client-side. Returns `{ pageIndex, pageNumber, matches, snippet, sourcePageNumber, highlights? }[]`, stores results for the built-in search panel, and overlays matching text rectangles. `pageIndex` is zero-based; `pageNumber` is one-based. `highlights` coordinates are normalized to the logical page (0..1), including left/right mapping for split PDF pages.
+- **`clearSearch()`** / **`getSearchResults()`**: Clears or reads the current search state.
+
+### Hotspots
+
+- **`getHotspots(pageIndex = getCurrentPage())`**: Returns host-provided overlays for a logical page.
+- **`activateHotspot(id)`** / **`closeHotspot()`**: Opens or closes a hotspot popup. Activation emits `hotspotActivate`. Hotspots may include `kind`, `media` (`image`, `video`, `audio`), `gallery` image items, and an optional `href` for commerce/product links; popup text is always rendered as plain text.
+
+
+### Page annotations
+
+Host uygulamaları, kullanıcı notunu sayfa üzerindeki normalize koordinata bağlamak için `annotations` seçeneğini kullanabilir. Marker tıklaması popup açar ve `annotationActivate` olayı yayınlanır. Bu sözleşme şimdilik host-managed'dir; annotation kayıtlarının backend koordinatlarına taşınması tüketici uygulamanın sorumluluğundadır.
+
+```ts
+const engine = new FlipbookEngine('#viewer', {
+  annotations: [{ id: 'note-1', pageIndex: 4, x: .42, y: .36, text: 'Review pricing' }]
+});
+```
+
+## Plugins
+
+See [Plugin architecture](./plugin-architecture.md) for the v1 plugin contract and lifecycle.
+
+
+## Host backend providers
+
+The native search panel also works with pre-rendered page images. Supply `searchProvider(query, options, signal)` returning logical page results (`pageIndex` is zero-based, `pageNumber` is one-based, plus `matches`, `snippet` and optional normalized `highlights`). The host owns authentication, document identity and authorization. Stale responses are ignored; destroy aborts the session signal. Without a provider, Direct PDF search retains its existing behavior.
+
+Supply initial `notes` and `noteProvider(pageIndex, note, signal)` to persist the native note editor. A cleared note is `null`. The editor awaits the provider before changing the saved note or emitting `noteChange`. On failure it retains the draft and offers another save. `saveNote(pageIndex, note)` exposes the same asynchronous workflow; `setNote` remains a synchronous programmatic update for compatibility.
+
+Contents, search and notes are mutually exclusive panels. Canvas arrows hide while a panel is open; the pager remains available. Contents has a close control. Secondary toolbar commands are in the accessible More actions menu; mobile navigation and primary controls occupy two rows.
+
+## Personal coordinate notes
+
+`annotationProvider(annotation, action, signal)` persists native coordinate notes (`action` is `save` or `delete`). Initial `annotations` load existing notes. `beginAnnotation()` enters a dedicated placement mode; `placeAnnotation(pageIndex,x,y)` uses normalized logical-page coordinates in [0,1]. `saveAnnotation()` commits only after the host succeeds. Multiple note IDs may share a page. The host remains responsible for authentication, ownership and document identity. Right click and a stationary touch/pen hold open an editor at the selected point; movement beyond10px or another pointer cancels long press. A placement overlay consumes page-flip gestures. Escape cancels placement. Markers are available in both single-page and spread views.
+
+The My notes panel includes existing page notes and coordinate notes, navigation, an empty state and a total count. The toolbar shows the count and highlights pages containing notes. Selecting a marker opens a readable popover outside the scaled paper; editing and deletion remain in that popover. Delete requires a second explicit action.
+
+`noteEditor(container,value,signal)` is an optional host editor factory returning `getValue`, `setReadOnly` and `destroy`. `value` contains plain `text` and an optional structured `document`; the base engine retains a textarea fallback and has no Tiptap dependency. Legacy page notes can supply `noteDocuments`; noteProvider receives the document as an optional fourth argument. The built-in viewer renders only doc/paragraph/text/hardBreak nodes with bold, italic, font-size and hex foreground/background marks. It never renders raw note HTML.
+
+When the viewer owns keyboard focus: arrows/PageUp/PageDown navigate, Home/End jump, +/- zoom,0 resets, N places a note, Shift+N opens My notes, / searches, I opens contents, T toggles thumbnails, F toggles fullscreen, and ? shows help. Text inputs and rich editors keep their own shortcuts. Toolbar arrows move focus among visible commands; Tab/Shift+Tab preserve native focus order. Closing panels returns focus. Pinch zoom and one-finger pan suppress page turning; only predominantly horizontal unzoomed single-page swipes turn pages. Ctrl/wheel zoom is scoped to the paper. Native touch behavior still requires real-device acceptance.
+
+## Backend text layer API
+
+Optional `textLayerProvider`, `textSelection` and `setTextSelection(enabled)` add fixed-layout selectable text to image books. Public `FlipbookTextPage`, `FlipbookTextRun` and `FlipbookTextLayerProvider` types are exported from root and core entrypoints. See [schema, lifecycle, geometry and backend responsibilities](backend-text-layers.md). Existing search highlights remain independent. No backend, OCR engine or database is bundled.

package/docs/backend-text-layers.md

@@ -0,0 +1,40 @@
+# Backend text layers
+
+## Ownership and compatibility
+
+The viewer consumes host-generated text; it never uploads a PDF, runs OCR, writes a database or supplies authoritative extraction results. Existing image books and Direct PDF books work without a text provider. The API is available from 1.0.2.
+
+## Schema v1
+
+`textLayerProvider(pageIndex, signal): Promise<FlipbookTextPage | null>` returns a logical-page payload. Indexes are zero-based. Return null for unavailable/OCR-pending text. Provider errors do not break image navigation. Providers must honor AbortSignal for network cancellation. Reinitialize to change document identity/provider or retry failed pages.
+
+`FlipbookTextPage`: schemaVersion:1, pageIndex, revision:string, text:string, runs:FlipbookTextRun[]. Revision identifies an immutable source/extraction generation. Hosts must reject a text/image source mismatch before returning data.
+
+`FlipbookTextRun`: text, start (UTF-16 code units into page text), x, y, width, height (finite 0..1 values), optional direction:ltr|rtl. Runs are ordered, nonoverlapping in text offsets and must match their source substring. Max 100,000 page characters and 20,000 runs; invalid pages are rejected. Do not pass user HTML.
+
+Coordinates use top-left origin in the **displayed logical page**, after PDF CropBox and rotation. All image variants must depict precisely that same viewport. Spread/cropped assets require the host to remap each logical half; full-source coordinates must never be applied unchanged to a half-page. Provider geometry precision is explicit: PDF text-run boxes highlight runs, not exact glyphs or words. Rotated/vertical text needs a provider-specific oriented layer for exact selection; schema v1 provides enclosing rectangles.
+
+## Selection and loading
+
+`textSelection?: boolean` defaults false. `engine.setTextSelection(enabled)` changes the mode. More actions provides the same control only when a provider exists. Escape exits. Selection uses native browser text selection over transparent runs; page flipping/long-press note placement are suppressed in selection mode. Toolbar and keyboard pagination remain available. Use a page's text payload directly for a separate accessible reading view when necessary; transparent fixed-layout spans are not a reflowable document.
+
+At most three pages are retained: current and immediate neighbors. Navigating away aborts pending calls. Destroy and reinitialization abort the session and reject stale completions. null/error pages are retried after leaving their visible range or reinitializing. This API is independent of image resolution and optional backend search.
+
+## Example
+
+```ts
+const engine = new FlipbookEngine(container, {
+  textLayerProvider: async (pageIndex, signal) => {
+    const response = await fetch('/books/42/versions/3/pages/' + pageIndex + '/text', { signal });
+    if (!response.ok) throw new Error('Text unavailable');
+    return response.json();
+  },
+  searchProvider: async (query, options, signal) => {
+    // Host endpoint returns pageIndex, pageNumber, matches, snippet and normalized highlights.
+    return searchBook(query, { ...options, signal });
+  }
+});
+await engine.init('', [{ id:'page-0', pageNumber:1, normal:'/normal/1.webp', low:'/small/1.webp', thumb:'/thumb/1.webp' }]);
+```
+
+Hosts must authorize every manifest/text/search request, protect against stale source generations and keep extraction bounded. OCR-produced runs can use the same contract once normalized to the displayed page geometry.