flipbookengine 0.6.5 → 1.0.0

package/dist/plugins-share.d.ts

@@ -0,0 +1 @@
+export * from './plugins/share'

package/dist/plugins-toc.d.ts

@@ -0,0 +1 @@
+export * from './plugins/toc'

package/dist/plugins.d.ts

@@ -0,0 +1 @@
+export * from './plugins/index'

package/dist/state/store.d.ts

@@ -4,6 +4,9 @@ import { NormalizedFlipbookPage } from '../model/pages';
 import { FlipbookTocEntry } from '../model/toc';
 import { FlipbookEngineOptions } from '../engine';
 import { PartialFlipbookMessages } from '../i18n/service';
+import { FlipbookSearchResult } from '../model/search';
+import { FlipbookHotspot } from '../model/hotspots';
+import { FlipbookAnnotation } from '../model/annotations';
 
 export type FlipState = 'read' | 'fold_corner' | 'flipping';
 export type Orientation = 'landscape' | 'portrait';
@@ -20,18 +23,29 @@ export interface FlipbookStore {
     isSingleMode: Signal<boolean>;
     showThumbs: Signal<boolean>;
     showToc: Signal<boolean>;
+    showNotes: Signal<boolean>;
+    showSearch: Signal<boolean>;
     showArrows: Signal<boolean>;
     orientation: Signal<Orientation>;
     flipState: Signal<FlipState>;
     themeMode: Signal<FlipbookThemeMode>;
     allowDownload: Signal<boolean>;
+    bookmarkedPages: Signal<ReadonlySet<number>>;
+    pageNotes: Signal<ReadonlyMap<number, string>>;
     hasDownloadUrl: Signal<boolean>;
+    isPdfMode: Signal<boolean>;
     primaryColor: Signal<string>;
     whiteLabel: Signal<boolean>;
     isZoomed: Signal<boolean>;
     isAutoPlaying: Signal<boolean>;
     autoPlayInterval: Signal<number>;
     soundEnabled: Signal<boolean>;
+    searchQuery: Signal<string>;
+    searchResults: Signal<FlipbookSearchResult[]>;
+    hotspots: Signal<FlipbookHotspot[]>;
+    activeHotspotId: Signal<string | null>;
+    annotations: Signal<FlipbookAnnotation[]>;
+    activeAnnotationId: Signal<string | null>;
     locale: Signal<string>;
     messages: Signal<Partial<Record<string, PartialFlipbookMessages>>>;
     zoomState: Signal<ZoomState>;
@@ -40,16 +54,16 @@ export interface FlipbookStore {
     isDoublePageLayout: ReadonlySignal<boolean>;
     isFrontCover: ReadonlySignal<boolean>;
     isBackCover: ReadonlySignal<boolean>;
-    init(options: FlipbookEngineOptions, total: number, mappedPages: NormalizedFlipbookPage[], hasPdfUrl: boolean): void;
+    init(options: FlipbookEngineOptions, total: number, mappedPages: NormalizedFlipbookPage[], hasPdfUrl: boolean, isPdfMode?: boolean): void;
     reset(): void;
 }
 /** Creates an isolated reactive state container for one FlipbookEngine instance. */
 export declare function createFlipbookStore(): FlipbookStore;
 export declare const currentPage: Signal<number>, totalPages: Signal<number>, isSingleMode: Signal<boolean>;
-export declare const showThumbs: Signal<boolean>, showToc: Signal<boolean>, showArrows: Signal<boolean>, orientation: Signal<Orientation>;
-export declare const flipState: Signal<FlipState>, themeMode: Signal<FlipbookThemeMode>, allowDownload: Signal<boolean>;
-export declare const hasDownloadUrl: Signal<boolean>, primaryColor: Signal<string>, whiteLabel: Signal<boolean>;
+export declare const showThumbs: Signal<boolean>, showToc: Signal<boolean>, showNotes: Signal<boolean>, showSearch: Signal<boolean>, showArrows: Signal<boolean>, orientation: Signal<Orientation>;
+export declare const flipState: Signal<FlipState>, themeMode: Signal<FlipbookThemeMode>, allowDownload: Signal<boolean>, bookmarkedPages: Signal<ReadonlySet<number>>, pageNotes: Signal<ReadonlyMap<number, string>>;
+export declare const hasDownloadUrl: Signal<boolean>, isPdfMode: Signal<boolean>, primaryColor: Signal<string>, whiteLabel: Signal<boolean>;
 export declare const isZoomed: Signal<boolean>, isAutoPlaying: Signal<boolean>, autoPlayInterval: Signal<number>;
-export declare const soundEnabled: Signal<boolean>, locale: Signal<string>, messages: Signal<Partial<Record<string, Partial<import('..').FlipbookMessages>>>>, zoomState: Signal<ZoomState>, pages: Signal<NormalizedFlipbookPage[]>, toc: Signal<FlipbookTocEntry[]>;
+export declare const soundEnabled: Signal<boolean>, searchQuery: Signal<string>, searchResults: Signal<FlipbookSearchResult[]>, hotspots: Signal<FlipbookHotspot[]>, activeHotspotId: Signal<string | null>, annotations: Signal<FlipbookAnnotation[]>, activeAnnotationId: Signal<string | null>, locale: Signal<string>, messages: Signal<Partial<Record<string, Partial<import('..').FlipbookMessages>>>>, zoomState: Signal<ZoomState>, pages: Signal<NormalizedFlipbookPage[]>, toc: Signal<FlipbookTocEntry[]>;
 export declare const isDoublePageLayout: ReadonlySignal<boolean>, isFrontCover: ReadonlySignal<boolean>, isBackCover: ReadonlySignal<boolean>;
 export declare function initStore(options: FlipbookEngineOptions, total: number, mappedPages: NormalizedFlipbookPage[], hasPdfUrl: boolean): void;

package/dist/vue/index.d.ts

@@ -41,8 +41,8 @@ export declare const Flipbook: import('vue').DefineComponent<import('vue').Extra
     onPageChange?: ((...args: any[]) => any) | undefined;
 }>, {
     pages: FlipbookPageAsset[];
-    pdfUrl: string;
     options: Omit<FlipbookEngineOptions, "theme"> & {
         theme?: "auto" | "light" | "dark";
     };
+    pdfUrl: string;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

package/docs/api-reference.md

@@ -0,0 +1,206 @@
+# 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.
+

package/docs/frameworks.md

@@ -0,0 +1,73 @@
+# Framework Integrations
+
+FlipbookEngine ships with built-in, type-safe wrappers for both React and Vue 3.
+
+## React Wrapper
+
+### Usage
+
+```tsx
+import React, { useRef } from 'react';
+import { Flipbook, FlipbookRef } from 'flipbookengine/react';
+import 'flipbookengine/dist/flipbook-engine.css';
+
+function App() {
+  const flipbookRef = useRef<FlipbookRef>(null);
+
+  const handleNextPage = () => {
+    if (flipbookRef.current) {
+      const current = flipbookRef.current.getCurrentPage();
+      flipbookRef.current.goToPage(current + 1);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleNextPage}>Next Page</button>
+      
+      <Flipbook
+        ref={flipbookRef}
+        pdfUrl="/catalog.pdf"
+        pages={[
+          { normal: '/1.png', low: '/1-low.png', thumb: '/1-thumb.png' },
+          { normal: '/2.png', low: '/2-low.png', thumb: '/2-thumb.png' }
+        ]}
+        showThumbs={false}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Vue 3 Wrapper
+
+### Usage
+
+```vue
+<template>
+  <div>
+    <Flipbook
+      pdfUrl="/catalog.pdf"
+      :pages="pages"
+      :allowDownload="true"
+      @page-change="onPageChange"
+    />
+  </div>
+</template>
+
+<script setup>
+import { Flipbook } from 'flipbookengine/vue';
+import 'flipbookengine/dist/flipbook-engine.css';
+
+const pages = [
+  { normal: '/1.png', low: '/1-low.png', thumb: '/1-thumb.png' },
+  { normal: '/2.png', low: '/2-low.png', thumb: '/2-thumb.png' }
+];
+
+function onPageChange(event) {
+  console.log('Page index changed to:', event.currentPage);
+}
+</script>
+```

package/docs/getting-started.md

@@ -0,0 +1,128 @@
+# Getting Started
+
+Welcome to **FlipbookEngine**! This guide will help you set up and embed FlipbookEngine into your web applications.
+
+## Quick Installation
+
+You can install FlipbookEngine via npm:
+
+```bash
+npm install flipbookengine
+```
+
+Or reference it directly via CDN (such as unpkg) in your HTML:
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/flipbookengine/dist/flipbook-engine.css" />
+<script src="https://unpkg.com/flipbookengine/dist/flipbook-engine.iife.js"></script>
+```
+
+## Setup Container
+
+Create an element in your HTML that will contain the flipbook viewer. Ensure the container has explicit dimensions:
+
+```html
+<div id="viewer" style="width: 100%; height: 600px;"></div>
+```
+
+## Initialize the Engine
+
+Import `FlipbookEngine` (if using ESM) and instantiate it:
+
+```javascript
+import { FlipbookEngine } from 'flipbookengine';
+import 'flipbookengine/dist/flipbook-engine.css';
+
+const engine = new FlipbookEngine('#viewer', {
+  allowDownload: true,
+  showThumbs: false,
+  primaryColor: '#7367f0'
+});
+
+// Load the PDF catalog file along with its rendered images
+await engine.init('/files/catalog.pdf', [
+  { kind: 'cover', pageNumber: 1, normal: '/img/1.jpg', low: '/img/1-low.jpg', thumb: '/img/1-thumb.jpg' },
+  { kind: 'spread', pageNumbers: [2, 3], normal: '/img/2-3.jpg', low: '/img/2-3-low.jpg', thumb: '/img/2-3-thumb.jpg' }
+]);
+```
+
+## Mixed Page Spreads
+
+FlipbookEngine supports loading single pages, spreads (double-pages), and covers mixed together. The engine will automatically normalize spreads (cutting them into left and right halves on portrait viewports) for responsive mobile viewing.
+
+
+## Iframe embedding
+
+For a viewer hosted in an iframe, connect the bridge from the iframe document and allow only the parent origin:
+
+```javascript
+const engine = new FlipbookEngine('#viewer', { showThumbs: false });
+engine.connectEmbed({
+  allowedOrigins: ['https://catalog.example.com']
+});
+await engine.init('/files/catalog.pdf');
+```
+
+From the parent page, use the controller exported by the package:
+
+```javascript
+import { createFlipbookEmbedController } from 'flipbookengine';
+
+const controller = createFlipbookEmbedController(
+  document.querySelector('#catalog-frame'),
+  { targetOrigin: 'https://viewer.example.com' }
+);
+await controller.goToPage(2);
+```
+
+Always configure explicit origins for cross-origin embeds. The bridge supports page navigation, zoom, single mode, option updates, fullscreen, TOC read/update, search, state queries, and event forwarding.
+
+
+## Deep links and sharing
+
+Enable opt-in URL synchronization with the `deepLink` option. The viewer reads an initial `?page=` value, updates it when the page changes, and responds to browser back/forward navigation. Page numbers in URLs are 1-based; engine API indexes remain 0-based.
+
+```ts
+const engine = new FlipbookEngine('#viewer', { deepLink: true });
+await engine.init('/files/catalog.pdf');
+
+const pageUrl = engine.getPageUrl(4);
+await engine.sharePage(4);
+// The viewer toolbar also exposes a localized Share button.
+// Bookmark state is host-managed and can be persisted from bookmarkChange.
+engine.on('bookmarkChange', ({ pageNumber, bookmarked }) => {
+  console.log(`Page ${pageNumber} bookmarked: ${bookmarked}`);
+});
+engine.on('noteChange', ({ pageNumber, note }) => {
+  console.log(`Page ${pageNumber} note changed`, note);
+});
+engine.on('deepLinkChange', ({ pageNumber, url }) => {
+  console.log(`Sharing page ${pageNumber}: ${url}`);
+});
+```
+
+
+## Client-side PDF search
+
+When initialized with a PDF URL, `search(query)` extracts text through PDF.js without rendering every page. It returns page-level matches and snippets, updates the search toolbar panel, and overlays precise normalized rectangles over matching text when PDF.js exposes text geometry. Search results use a zero-based `pageIndex` for API navigation and a one-based `pageNumber` for display.
+
+```ts
+const results = await engine.search('catalog', { caseSensitive: false, maxResults: 50 });
+engine.goToPage(results[0]?.pageIndex ?? 0);
+engine.clearSearch();
+```
+
+Search is unavailable for image-only page lists because those assets do not contain extractable PDF text or text geometry. For image mode, applications that need search/highlights should generate page text and normalized coordinates on the server and pass the resulting page metadata as a host-side feature; the open-source viewer does not OCR raster images. The iframe controller exposes the same operation with `search`, `clearSearch`, and `getSearchResults`.
+
+## Interactive hotspots
+
+Hosts can provide normalized (0..1) page coordinates for lightweight links and pop-ups:
+
+```ts
+const engine = new FlipbookEngine('#viewer', {
+  hotspots: [{ id: 'product-42', pageIndex: 3, x: 0.60, y: 0.25, width: 0.25, height: 0.18, label: 'Product details', content: 'Open the product details page.', href: '/products/42' }]
+});
+engine.on('hotspotActivate', ({ hotspot }) => console.log(hotspot.id));
+```
+
+Hotspots support `kind: 'info' | 'media' | 'gallery' | 'commerce'`. A hotspot can render a single image/video/audio preview through `media`, a selectable image gallery through `gallery`, and a safe external/product destination through `href`. Content remains plain text; applications should sanitize server-provided URLs before passing them to the viewer. Use `activateHotspot(id)` and `closeHotspot()` for programmatic control.

package/docs/i18n.md

@@ -0,0 +1,47 @@
+# Internationalization (i18n)
+
+FlipbookEngine features built-in support for multiple locales and customization of all user-facing copy.
+
+## Supported Locales
+
+- **`en`** (English - default)
+- **`tr`** (Turkish)
+
+## Set Active Locale
+
+Change the language on initialization or dynamically at runtime:
+
+```javascript
+// Initialization
+const engine = new FlipbookEngine('#viewer', {
+  locale: 'tr'
+});
+
+// Runtime change
+engine.setLocale('en');
+```
+
+## Overriding Messages
+
+Provide translation strings to override specific labels or define messages for a new locale:
+
+```javascript
+const engine = new FlipbookEngine('#viewer', {
+  locale: 'de',
+  messages: {
+    de: {
+      emptyStateTitle: 'Keine Seiten gefunden.',
+      thumbnails: 'Miniaturansichten',
+      singlePageMode: 'Einzelseiten-Modus',
+      pages: 'Seiten',
+      previous: 'Zurück',
+      next: 'Weiter',
+      zoomOut: 'Herauszoomen',
+      zoomIn: 'Herinzoomen',
+      fullscreen: 'Vollbild',
+      settings: 'Einstellungen',
+      downloadCatalog: 'PDF Herunterladen'
+    }
+  }
+});
+```

package/docs/migration-0.4.0.md

@@ -0,0 +1,24 @@
+# Migration Guide for 0.4.0
+
+## Scope
+
+FlipbookEngine 0.4.0 is the stabilization release described by the audit plan. It keeps the core public navigation methods while making lifecycle, state, wrapper, event, and viewer behavior deterministic across multiple instances.
+
+## Required consumer checks
+
+- Keep `pdfjs-dist` installed as the production dependency and provide `pdfWorkerSrc` from the host bundler or CDN. PDF.js is intentionally external to the FlipbookEngine bundle.
+- If host CSS or automation selected fixed viewer IDs, migrate to the instance-scoped classes such as `.bk-book-wrapper`, `.bk-book-sizer`, `.bk-book`, and `.bk-single-view` within the engine container.
+- Treat `pages` as optional when `pdfUrl` is provided. Framework wrappers may update `pdfUrl` and `pages` independently without triggering duplicate initialization.
+- Image-only viewers do not render a download button because no PDF URL is available.
+
+## Runtime behavior changes
+
+- Each `FlipbookEngine` instance owns its reactive state; internal singleton store imports must not be used by integrations.
+- A newer `init()` or `destroy()` cancels stale PDF loading, rendering, timers, and listeners.
+- `progress` and `error` events are available for PDF loading/rendering telemetry and failure handling.
+- High-quality page assets are promoted when pages become visible. PDF rendering uses bounded concurrency controlled by `pdfRenderConcurrency` (default `3`).
+- Toolbar and thumbnail controls expose accessible names, state, and keyboard interaction.
+
+## Verification
+
+Before shipping an integration, run `npm run typecheck`, `npm test`, and `npm run build` against the locked 0.4.0 dependency tree.

package/docs/migration-0.5.0.md

@@ -0,0 +1,25 @@
+# Migration Guide for 0.5.0
+
+## Scope
+
+FlipbookEngine 0.5.0 makes PDF-backed viewers responsive for large documents. Page markup is created from PDF metadata, while rendered page images are requested only for the current/nearby pages or when a page becomes visible.
+
+## Runtime behavior changes
+
+- `init()` resolves after the first PDF page has rendered. The next page is prefetched in the background.
+- PDF render requests are deduplicated and cancelled when a newer initialization starts or the engine is destroyed.
+- `pdfRenderConcurrency` continues to bound PDF.js work (default `3`).
+- `pdfRenderCacheSize` controls a per-instance least-recently-used cache (default `32`). Set it to `0` to disable retention of rendered page images.
+- `progress` reports loading and rendering phases; `error` reports `PDF_LOAD_FAILED` and `PDF_RENDER_FAILED` failures.
+- Browser, React, and Vue wrappers share the same lifecycle-safe on-demand behavior.
+- Keyboard controls and visible focus states remain available, and `prefers-reduced-motion: reduce` disables page-turn animation and shortens CSS transitions.
+
+## Consumer checks
+
+- Keep `pdfjs-dist` installed as the production dependency and provide `pdfWorkerSrc` from the host bundler or CDN.
+- If an application assumed that every PDF page image existed immediately after `init()`, listen for `progress` events or select the page before reading its image element.
+- Choose a cache size based on available memory and page dimensions. A value of `0` is appropriate for strictly bounded memory usage.
+
+## Verification
+
+Run `npm run typecheck`, `npm test`, `npm run build`, and `npm run test:e2e` (after installing Playwright browsers) before shipping an integration.

package/docs/migration-1.0.0.md

@@ -0,0 +1,59 @@
+# 1.0.0 migration guide
+
+FlipbookEngine 1.0.0 is the first stable open-source release. The 0.x line was
+alpha/beta and does not provide a compatibility guarantee. Test the viewer and
+wrapper integrations against the new package before deploying.
+
+## Plugin entry points
+
+The all-in-one import remains available:
+
+```ts
+import { FlipbookEngine } from 'flipbookengine';
+```
+
+Optional feature adapters can be loaded independently:
+
+```ts
+import { FlipbookEngine } from 'flipbookengine/core';
+import { notesPlugin } from 'flipbookengine/plugins/notes';
+
+const engine = new FlipbookEngine('#viewer', { plugins: [notesPlugin] });
+```
+
+Available adapters are documented in [plugin architecture](./plugin-architecture.md).
+The official OSS package does not include analytics, OCR, PDF outline extraction,
+protected downloads, or backend rendering.
+
+## TOC and iframe API
+
+TOC is supplied as a host-provided `FlipbookTocEntry[]` manifest. Use
+`engine.getToc()` and `engine.setToc(entries, show?)` for runtime updates. Iframe
+controllers additionally expose `getToc()` and `setToc()` through the validated
+postMessage bridge.
+
+## Wrapper validation
+
+React and Vue wrappers continue to accept the engine options object, including
+`plugins`. Validate wrapper lifecycle, CSS import, PDF worker configuration, and
+host-managed note/bookmark persistence during migration.
+
+## 0.8.0 to 1.0.0 differences
+
+The 1.0.0 release is the first compatibility boundary. The 0.x line was alpha/beta, so applications must validate the complete integration instead of assuming semver compatibility.
+
+| Area | 0.8.0 | 1.0.0 | Migration impact |
+| --- | --- | --- | --- |
+| Package surface | All-in-one public entry | All-in-one plus core, plugins, and feature subpaths | Imports from documented public paths are supported; imports from internal src/dist files are breaking and must be replaced. |
+| Optional features | Built-in reader surface only | Plugin contract with install/uninstall, typed events, toolbar/panel/API contributions | If an application wants an adapter API, register the adapter explicitly; omitted adapters are inactive. |
+| TOC | Host-provided TOC panel | Nested TOC plus getToc/setToc and iframe commands | Existing TOC data remains host-provided; update integrations that need runtime or embed control. |
+| Hotspots | Basic text/link overlays | info/media/gallery/commerce, image/video/audio previews, galleries, product links | Existing overlays remain valid; new media/gallery fields are additive. |
+| Image mode search | Disabled for raster page lists | Still disabled; PDF mode only | No change; raster search requires host/server text metadata. |
+| Commercial capabilities | Not part of OSS | Still not part of OSS | Backend rendering, OCR/indexing, protected downloads, persistence, identity, and analytics remain commercial/backend work. |
+
+### Breaking-change requirements
+
+- Do not depend on undocumented internal modules, generated chunk filenames, or 0.x implementation details.
+- Re-run wrapper and iframe smoke tests after upgrading; React and Vue wrappers must be rebuilt against the 1.0.0 declarations.
+- Treat plugin registration as explicit state. Calling uninstallPlugin removes APIs, UI contributions, event listeners, and cleanup callbacks; it does not merely hide a button.
+- Existing all-in-one initialization with documented options is retained, but the 0.x line has no compatibility guarantee and must not be used as a rollback contract.