flipbookengine 0.6.5 → 1.0.0

package/CHANGELOG.md

@@ -1,6 +1,28 @@
 # Changelog
 
-## Next (unreleased)
+## 1.0.0 - 2026-09-14
+
+- first stable open-source release of the FlipbookEngine viewer
+- added framework-agnostic plugin contract with install/uninstall lifecycle, typed events, toolbar buttons, panels, and namespaced APIs
+- added independent `flipbookengine/core` and `flipbookengine/plugins/*` entry points for notes, bookmarks, TOC, search, annotations, hotspots, share, and deep links
+- added runtime `getToc()/setToc()` APIs and origin-validated iframe TOC read/update commands
+- added interactive hotspot overlays with image/video/audio previews, selectable image galleries, and commerce/product links
+- added plugin and embed regression coverage; full suite passes 84/84 tests
+- documented PDF outline extraction, OCR, analytics, backend rendering, and protected downloads as commercial/backend responsibilities
+- breaking change: 0.x releases were alpha/beta and are not compatibility guarantees; applications should validate imports and options against the 1.0 API before upgrading
+- 0.8.0 to 1.0.0 migration: documented public entrypoint changes, explicit plugin activation/deactivation, nested TOC/embed APIs, expanded hotspot payloads, and the unchanged image-mode search limitation
+- added an origin-validated iframe embed bridge with parent-side command and event helpers
+- added opt-in deep links, localized share controls, host-managed bookmarks and notes, and their regression coverage
+- added localized notes toolbar/editor; persistence remains with the host application
+
+## 0.8.0 - 2026-09-14
+
+- added precise PDF.js text-match rectangles and logical left/right split-page mapping
+- replaced full-page search tint with lightweight text-position highlights
+- hardened DOMWise search result rendering so result buttons are not stringified
+- unified search and note focus styling with a single thin accent border and glow
+- disabled text search in image/WebP page-list mode with localized explanation; download URL handling remains independent
+- added localized image-mode messaging and regression coverage
 
 ## 0.6.5
 
@@ -71,5 +93,4 @@
 - introduced dual-license documentation structure
 - prepared package metadata for public distribution
 - preserved legacy `BizekaFlipEngine` compatibility alias
-- added contribution, security, and trademark policy documents
-
+- added contribution, security, and trademark policy documents

package/README.md

@@ -1,7 +1,7 @@
 # FlipbookEngine
 
-> **Release notice:** `flipbookengine@0.6.5` is the latest published release and includes the localized Table of Contents API.
-> **Development notice:** Version 0.6.5 adds automatic PDF A3 splitting, per-theme backgrounds, responsive viewer gutters, enlarged thumbnails, and mobile touch fixes.
+> **Release candidate:** `flipbookengine@1.0.0` is prepared as the first stable release and includes the localized Table of Contents API.
+> **Release scope:** Version 1.0.0 adds the plugin contract, independent feature entrypoints, TOC runtime/embed APIs, and the complete open-source reader surface.
 
 [![NPM Version](https://img.shields.io/npm/v/flipbookengine?style=flat-square&color=blue)](https://www.npmjs.com/package/flipbookengine)
 [![License](https://img.shields.io/npm/l/flipbookengine?style=flat-square)](https://github.com/Bizeka/flipbook-engine/blob/main/LICENSE)
@@ -21,6 +21,11 @@ FlipbookEngine is a modern, lightweight, and embeddable HTML flipbook viewer for
 - **Multi-Language (i18n)**: Out-of-the-box support for English (`en`) and Turkish (`tr`) with customizable overrides.
 - **Framework Wrappers**: Direct React and Vue wrapper exports for seamless modern integration.
 - **Progressive PDF Rendering**: PDF pages render on demand with bounded concurrency and an instance-local LRU cache, keeping large documents responsive.
+- **Localized Sharing**: The toolbar includes a Share control that opens the native share sheet or copies the current page URL; enable `deepLink: true` for shareable page navigation.
+- **Host-Managed Bookmarks**: The toolbar can toggle the current page bookmark; hosts can initialize and persist zero-based bookmark indexes through the public API and `bookmarkChange` event.
+- **Host-Managed Notes**: The localized notes toolbar opens an inline editor; hosts can initialize, update, and persist page notes through the public API and `noteChange` event without coupling the viewer to a storage backend.
+- **Client-Side PDF Search**: Extracts and searches PDF text on demand with localized snippets and normalized text-rectangle highlighting.
+- **Interactive Hotspots**: Adds normalized page overlays with accessible plain-text popups and optional links.
 
 ## Installation
 
@@ -70,7 +75,7 @@ Passing `pages` remains optional. When omitted, FlipbookEngine creates the page
 Use the ESM build with an import map for PDF.js. The worker must be served from a URL your site permits in its Content Security Policy.
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/flipbookengine@0.6.5/dist/flipbook-engine.css" />
+<link rel="stylesheet" href="https://unpkg.com/flipbookengine@1.0.0/dist/flipbook-engine.css" />
 <div id="viewer" style="width: 100%; height: 600px;"></div>
 
 <script type="importmap">
@@ -81,7 +86,7 @@ Use the ESM build with an import map for PDF.js. The worker must be served from
 }
 </script>
 <script type="module">
-  import { FlipbookEngine } from 'https://unpkg.com/flipbookengine@0.6.5/dist/flipbook-engine.js';
+  import { FlipbookEngine } from 'https://unpkg.com/flipbookengine@1.0.0/dist/flipbook-engine.js';
 
   const engine = new FlipbookEngine('#viewer', {
     pdfWorkerSrc: 'https://unpkg.com/pdfjs-dist@5.4.530/build/pdf.worker.min.mjs'
@@ -145,6 +150,34 @@ const pages = [
 </script>
 ```
 
+
+
+## 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.
+
 ## Migration Notes
 
 Upgrading from 0.3.x to 0.4.0 keeps the public engine methods intact. The release isolates state per engine instance, makes wrapper updates lifecycle-safe, and scopes viewer markup to its container. If host CSS or automation selected the former fixed viewer IDs, migrate those selectors to the instance classes documented in the theming guide. PDF-backed consumers should configure `pdfWorkerSrc`; image-only viewers do not expose a download control.
@@ -152,6 +185,8 @@ Upgrading from 0.3.x to 0.4.0 keeps the public engine methods intact. The releas
 For 0.5.0 behavior, see the [0.5.0 migration guide](./docs/migration-0.5.0.md). PDF-backed viewers now render on demand; callers should use `progress` and `error` events for rendering telemetry.
 
 
+For the 1.0.0 migration and the 0.x compatibility boundary, see the [1.0.0 migration guide](./docs/migration-1.0.0.md).
+
 ## Public API Reference
 
 The `FlipbookEngine` class exposes the following public methods:
@@ -166,6 +201,13 @@ The `FlipbookEngine` class exposes the following public methods:
 - **`toggleFullscreen()`**: Programmatically toggles fullscreen mode.
 - **`updateOptions(options: Partial<FlipbookEngineOptions>)`**: Updates instance options at runtime.
 - **`setLocale(locale: string, messages?: PartialFlipbookMessages | Record<string, PartialFlipbookMessages>)`**: Updates the locale programmatically and optionally overrides messages for that locale.
+- **`getPageUrl(pageIndex = getCurrentPage())`**: Returns a shareable URL for a 0-based page index.
+- **`sharePage(pageIndex = getCurrentPage())`**: Opens the native share dialog or copies the page URL to the clipboard. The toolbar exposes this behavior through a localized Share button.
+- **`getBookmarkedPages()`**: Returns the sorted zero-based bookmark indexes.
+- **`isBookmarked(pageIndex = getCurrentPage())`**: Checks whether a page is bookmarked.
+- **`setBookmark(pageIndex, bookmarked)`** / **`toggleBookmark(pageIndex)`**: Updates bookmark state and emits `bookmarkChange`; hosts can persist the event payload.
+- **`getNotes()`** / **`getNote(pageIndex)`**: Reads host-managed page notes.
+- **`setNote(pageIndex, note)`** / **`clearNote(pageIndex)`**: Updates notes and emits `noteChange`; empty notes are removed. The toolbar editor is intentionally host-storage agnostic, so a backend can persist each event later.
 - **`destroy(keepContainer = false)`**: Tears down the instance and listeners; when `true`, keeps the container markup for an immediate reinitialization.
 
 ### Subscribing to Events
@@ -181,7 +223,7 @@ const unsubscribe = engine.on('pageChange', ({ currentPage, totalPages, isSingle
 unsubscribe();
 ```
 
-Supported events: `init`, `progress`, `pageChange`, `zoomChange`, `singlePageModeChange`, `thumbsToggle`, `tocToggle`, `orientationChange`, `error`, `destroy`.
+Supported events: `init`, `progress`, `pageChange`, `zoomChange`, `singlePageModeChange`, `thumbsToggle`, `tocToggle`, `orientationChange`, `deepLinkChange`, `bookmarkChange`, `noteChange`, `searchChange`, `hotspotActivate`, `annotationActivate`, `error`, `destroy`.
 
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
@@ -199,6 +241,13 @@ Supported events: `init`, `progress`, `pageChange`, `zoomChange`, `singlePageMod
 | `pdfRenderCacheSize` | `number` | `32` | Maximum number of rendered PDF page images retained per engine instance (LRU); `0` disables caching. |
 | `pdfPageMode` | `'auto' \| 'single' \| 'split'` | `'auto'` | Controls PDF page splitting: A3 landscape pages are split automatically, all landscape pages can be split explicitly, or splitting can be disabled. |
 | `background` | `FlipbookBackgrounds \| null` | `null` | Optional light/dark viewer backgrounds with color, image, size, position, and repeat settings. |
+| `deepLink` | `boolean` | `false` | Keeps the active page synchronized with a `?page=` URL parameter. The localized toolbar Share control uses this URL format. |
+| `bookmarks` | `number[]` | `[]` | Initial zero-based bookmarked page indexes; the host owns persistence. |
+| `notes` | `Record<number, string>` | `{}` | Initial page notes keyed by zero-based page index; the notes toolbar edits them while the host owns persistence. |
+| `hotspots` | `FlipbookHotspot[]` | `[]` | Normalized (0..1) page overlays with info/media/gallery/commerce popup content and optional links. |
+| `annotations` | `FlipbookAnnotation[]` | `[]` | Host-managed page note markers with normalized coordinates and plain-text popup content. |
+| `onShare` | `(url: string) => void` | `null` | Optional callback invoked after the toolbar shares or copies the generated page URL. |
+
 
 ## PDF page formats
 
@@ -253,13 +302,13 @@ When choosing a flipbook library, here is how we compare to other solutions:
 A special thanks to the incredible team behind **[Serenity](https://github.com/serenity-is/serenity)**. FlipbookEngine's reactive UI layer is powered by **[domwise](https://github.com/serenity-is/serenity/tree/master/packages/domwise)**. Coupled with `@preact/signals-core`, this keeps the UI update path small without requiring a traditional Virtual DOM runtime.
 
 ---
-## Roadmap
+## Release scope
 
-FlipbookEngine has two complementary targets: an AGPL open-source viewer package and a separate closed-source commercial backend edition.
+FlipbookEngine ships an AGPL open-source viewer package and maintains a separate closed-source commercial backend roadmap.
 
 ### Open-source v1.0.0 (AGPL viewer)
 
-The npm package remains an embeddable, framework-agnostic PDF viewer. The open-source v1.0.0 target focuses on client-side reader capabilities:
+The npm package is an embeddable, framework-agnostic PDF viewer. The following client-side reader capabilities are included in the open-source v1.0.0 release:
 
 - **Table of Contents (Index):** Interactive navigation to chapters or product categories.
 - **Page Notes & Annotations:** Reader notes and bookmarks stored by the host application.
@@ -269,6 +318,47 @@ The npm package remains an embeddable, framework-agnostic PDF viewer. The open-s
 
 The open-source viewer continues to use PDF.js as an external npm dependency and does not require a backend renderer.
 
+The v1.0.0 release also defines the framework-agnostic plugin contract. The rendering core stays small while TOC, notes, bookmarks, annotations, search, hotspots, and sharing can be installed as optional plugins. Analytics is not shipped as an official open-source plugin; hosts can consume the documented events or use a private commercial adapter. See [Plugin architecture](./docs/plugin-architecture.md).
+
+
+### Plugin usage and activation
+
+Version 1.0.0 keeps the all-in-one entry point for existing applications and adds optional, tree-shakeable feature adapters. A plugin is active only when it is supplied in the constructor or installed at runtime. Omitting an adapter keeps it inactive.
+
+```ts
+import { FlipbookEngine } from 'flipbookengine/core';
+import { notesPlugin } from 'flipbookengine/plugins/notes';
+import { bookmarksPlugin } from 'flipbookengine/plugins/bookmarks';
+
+const engine = new FlipbookEngine('#viewer', {
+  plugins: [notesPlugin, bookmarksPlugin]
+});
+
+await engine.callPluginApi('notes', 'set', 0, 'Review this page');
+console.log(engine.getPluginNames());
+```
+
+Disable or remove a feature at runtime with `uninstallPlugin(name)`. This removes the plugin APIs, toolbar/panel contributions, event subscriptions, and cleanup callbacks. Re-enable it with `installPlugin(plugin)`:
+
+```ts
+engine.uninstallPlugin('notes');
+engine.installPlugin(notesPlugin);
+```
+
+The official notes, bookmarks, TOC, search, annotations, hotspots, share, and deep-link adapters expose namespaced APIs. Their UI is still controlled by the host/all-in-one viewer options; custom plugins may additionally register toolbar buttons and panels through the plugin contract. Analytics is not included as an official open-source adapter.
+
+### 0.8.0 to 1.0.0 compatibility boundary
+
+Version 1.0.0 is the first stable compatibility boundary. The 0.8.0 line was alpha/beta and does not provide a rollback or compatibility guarantee.
+
+- The documented all-in-one import and engine options remain available.
+- Imports from undocumented internal `src/*` or generated `dist/*` files are not supported; move to `flipbookengine/core`, `flipbookengine/plugins`, or the documented feature subpaths.
+- Optional adapters are explicit: pass them through `plugins`, call `installPlugin()` to enable, and `uninstallPlugin()` to disable and clean up their APIs, UI contributions, and event listeners.
+- TOC runtime/embed APIs and expanded hotspot media/gallery/commerce fields are new 1.0 APIs; existing host-managed data remains the source of truth.
+- Image/WebP text search remains unsupported; PDF mode is required unless the host supplies server-generated text metadata.
+
+See the complete [1.0.0 migration guide](./docs/migration-1.0.0.md) before upgrading from 0.8.0.
+
 ### Commercial edition (closed-source backend)
 
 The commercial roadmap is separate from the AGPL package and is intended for a separate backend project. It will provide licensed server-side capabilities, including:
@@ -293,3 +383,41 @@ For commercial licenses and inquiries, contact: **murat.dogan@hotmail.com.tr**
 
 
 
+
+
+### 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.
+
+
+### 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' }]
+});
+```
+

package/dist/components/App.d.ts

@@ -1,6 +1,10 @@
+import { FlipbookSearchOptions } from '../model/search';
+import { FlipbookHotspot } from '../model/hotspots';
+import { FlipbookAnnotation } from '../model/annotations';
 import { FlipbookStore } from '../state/store';
 import { PageFlipAdapter } from '../adapters/PageFlipAdapter';
 import { InteractionManager } from '../core/InteractionManager';
+import { FlipbookPluginRegistry } from '../plugins';
 
 interface AppProps {
     pageFlipAdapterRef: {
@@ -14,8 +18,23 @@ interface AppProps {
     bookContainerRef: (el: HTMLElement) => void;
     className?: string;
     onDownload: () => void;
+    onShare: () => void;
+    onToggleBookmark: () => void;
+    onToggleNotes: () => void;
+    onSaveNote: (note: string) => void;
+    onClearNote: () => void;
+    onCloseNotes: () => void;
+    onSearch: (query: string, options?: FlipbookSearchOptions) => void;
+    onClearSearch: () => void;
+    onCloseSearch: () => void;
+    onSelectSearchResult: (pageIndex: number) => void;
+    onHotspotActivate: (hotspot: FlipbookHotspot) => void;
+    onHotspotClose: () => void;
+    onAnnotationActivate: (annotation: FlipbookAnnotation) => void;
+    onAnnotationClose: () => void;
     onToggleFullscreen: () => void;
     store: FlipbookStore;
+    pluginRegistry?: FlipbookPluginRegistry;
 }
 export declare function App(props: AppProps): import('@serenity-is/domwise').JSXElement;
 export {};

package/dist/components/HotspotLayer.d.ts

@@ -0,0 +1,14 @@
+import { FlipbookHotspot } from '../model/hotspots';
+import { FlipbookAnnotation } from '../model/annotations';
+import { FlipbookStore } from '../state/store';
+
+interface HotspotLayerProps {
+    store: FlipbookStore;
+    pageIndex: number;
+    onActivate: (hotspot: FlipbookHotspot) => void;
+    onClose: () => void;
+    onAnnotationActivate: (annotation: FlipbookAnnotation) => void;
+    onAnnotationClose: () => void;
+}
+export declare function HotspotLayer(props: HotspotLayerProps): import('@serenity-is/domwise').JSXElement;
+export {};

package/dist/components/NotesPanel.d.ts

@@ -0,0 +1,14 @@
+import { FlipbookStore } from '../state/store';
+
+interface NotesPanelProps {
+    store: FlipbookStore;
+    onSave: (note: string) => void;
+    onClear: () => void;
+    onClose: () => void;
+}
+/**
+ * Page-level note UI. Persistence remains host-owned through the engine API and
+ * noteChange event; the panel intentionally does not know about a backend.
+ */
+export declare function NotesPanel(props: NotesPanelProps): import('@serenity-is/domwise').JSXElement;
+export {};

package/dist/components/PluginPanels.d.ts

@@ -0,0 +1,5 @@
+import { FlipbookPluginRegistry } from '../plugins';
+
+export declare function PluginPanels(props: {
+    registry: FlipbookPluginRegistry;
+}): import('@serenity-is/domwise').JSXElement;

package/dist/components/SearchPanel.d.ts

@@ -0,0 +1,11 @@
+import { FlipbookStore } from '../state/store';
+
+interface SearchPanelProps {
+    store: FlipbookStore;
+    onSearch: (query: string) => void;
+    onClear: () => void;
+    onClose: () => void;
+    onSelect: (pageIndex: number) => void;
+}
+export declare function SearchPanel(props: SearchPanelProps): import('@serenity-is/domwise').JSXElement;
+export {};

package/dist/components/Toolbar.d.ts

@@ -1,18 +1,24 @@
 import { FlipbookStore } from '../state/store';
+import { FlipbookPluginRegistry } from '../plugins';
 
 interface ToolbarProps {
     store: FlipbookStore;
     onToggleThumbs: () => void;
     onToggleToc: () => void;
+    onToggleSearch: () => void;
     onToggleSingleMode: () => void;
     onZoomIn: () => void;
     onZoomOut: () => void;
     onDownload?: () => void;
+    onShare: () => void;
+    onToggleBookmark: () => void;
+    onToggleNotes: () => void;
     onSoundToggle: () => void;
     onNextPage: () => void;
     onPrevPage: () => void;
     onToggleAutoPlay: () => void;
     onToggleFullscreen: () => void;
+    pluginRegistry?: FlipbookPluginRegistry;
 }
 export declare function Toolbar(props: ToolbarProps): import('@serenity-is/domwise').JSXElement;
 export {};

package/dist/components/Viewer.d.ts

@@ -1,10 +1,16 @@
 import { FlipbookStore } from '../state/store';
+import { FlipbookHotspot } from '../model/hotspots';
+import { FlipbookAnnotation } from '../model/annotations';
 
 interface ViewerProps {
     store: FlipbookStore;
     bookWrapperRef: (el: HTMLElement) => void;
     bookSizerRef: (el: HTMLElement) => void;
     bookContainerRef: (el: HTMLElement) => void;
+    onHotspotActivate: (hotspot: FlipbookHotspot) => void;
+    onHotspotClose: () => void;
+    onAnnotationActivate: (annotation: FlipbookAnnotation) => void;
+    onAnnotationClose: () => void;
 }
 export declare function Viewer(props: ViewerProps): import('@serenity-is/domwise').JSXElement;
 export {};

package/dist/core/LayoutManager.d.ts

@@ -1,7 +1,7 @@
 import { FlipbookStore } from '../state/store';
 
 /**
- * @license FlipbookEngine v0.6.5
+ * @license FlipbookEngine v1.0.0
  * Copyright (c) 2026 Murat Dogan
  *
  * This source code is dual-licensed under the AGPLv3 and a Commercial License.

package/dist/core/PdfRenderer.d.ts

@@ -1,4 +1,5 @@
 import { NormalizedFlipbookPage } from '../model/pages';
+import { FlipbookSearchOptions, FlipbookSearchHighlight } from '../model/search';
 
 export interface PdfRenderProgress {
     completed: number;
@@ -25,11 +26,21 @@ export declare class PdfRenderer {
     private loadingTask;
     private options;
     private readonly cache;
+    private readonly textCache;
     constructor(options?: PdfRenderOptions);
     /** Loads a PDF document and cancels PDF.js loading when the signal aborts. */
     loadDocument(pdfUrl: string, signal?: AbortSignal): Promise<number>;
     /** Renders a specific page to a Data URL. The page index is 1-based. */
     renderPageToDataUrl(pageIndex: number, signal?: AbortSignal): Promise<string>;
+    /** Extracts text from a 1-based PDF source page using PDF.js text content. */
+    extractPageText(pageNumber: number): Promise<string>;
+    /** Searches all PDF source pages and returns normalized rectangles for matched text. */
+    searchText(query: string, options?: FlipbookSearchOptions): Promise<Array<{
+        sourcePageNumber: number;
+        matches: number;
+        snippet: string;
+        highlights?: FlipbookSearchHighlight[];
+    }>>;
     /** Returns source page dimensions and whether the page should be split. */
     getPageLayouts(mode?: PdfPageMode): Promise<PdfPageLayout[]>;
     /** Calculates the best viewport dimensions based on the first logical page. */

package/dist/core-entry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license FlipbookEngine v1.0.0
+ * Copyright (c) 2026 Murat Dogan
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+export { FlipbookEngine, type FlipbookEngineOptions, type FlipbookLocaleMessages, type PageImages, type FlipbookEngineEventMap, type FlipbookEngineEventName } from './engine';
+export type { FlipbookPageAsset, FlipbookPageKind, FlipbookCropMode, FlipbookSplitDirection, NormalizedFlipbookPage } from './model/pages';
+export { normalizeFlipbookPages, isFlipbookPageAsset } from './model/pages';
+export type { FlipbookLocale, FlipbookMessages, PartialFlipbookMessages } from './i18n/service';
+export type { FlipbookThemeMode, FlipbookBackgroundStyle, FlipbookBackgrounds } from './theme/theme';
+export type { PdfPageMode, PdfPageLayout } from './core/PdfRenderer';
+export { isA3Landscape } from './core/PdfRenderer';
+export type { FlipbookHotspot, FlipbookHotspotKind, FlipbookHotspotMedia, FlipbookHotspotMediaType, FlipbookHotspotGalleryItem } from './model/hotspots';

package/dist/core.d.ts

@@ -0,0 +1 @@
+export * from './core-entry'

package/dist/embed.d.ts

@@ -0,0 +1,80 @@
+import { FlipbookEngine, FlipbookEngineEventMap, FlipbookEngineEventName, FlipbookEngineOptions } from './engine';
+import { FlipbookSearchOptions, FlipbookSearchResult } from './model/search';
+import { FlipbookTocEntry } from './model/toc';
+
+export type FlipbookEmbedCommandName = 'goToPage' | 'nextPage' | 'prevPage' | 'setZoom' | 'setSingleMode' | 'updateOptions' | 'toggleFullscreen' | 'search' | 'clearSearch' | 'getSearchResults' | 'getToc' | 'setToc' | 'getState';
+export interface FlipbookEmbedOptions {
+    /**
+     * Origins allowed to send commands. Defaults to the current origin.
+     * Use an explicit origin for cross-origin iframe integrations.
+     */
+    allowedOrigins?: string[];
+    /** Origin used for messages sent to the embedding parent. */
+    targetOrigin?: string;
+    /** Response timeout for the parent-side controller. */
+    responseTimeout?: number;
+}
+export interface FlipbookEmbedCommand {
+    type: 'flipbook:command';
+    command: FlipbookEmbedCommandName;
+    requestId?: string;
+    payload?: unknown;
+}
+export interface FlipbookEmbedEvent<T extends FlipbookEngineEventName = FlipbookEngineEventName> {
+    type: 'flipbook:event';
+    event: T;
+    payload: FlipbookEngineEventMap[T];
+}
+export interface FlipbookEmbedResponse {
+    type: 'flipbook:response';
+    requestId?: string;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+export interface FlipbookEmbedState {
+    currentPage: number;
+    totalPages: number;
+    zoom: number;
+}
+/**
+ * Runs inside an iframe and exposes a restricted postMessage command bridge.
+ * Commands are accepted only from window.parent and configured origins.
+ */
+export declare class FlipbookEmbedBridge {
+    private readonly engine;
+    private readonly options;
+    private readonly listener;
+    private readonly unsubs;
+    private connected;
+    private parentOrigin;
+    constructor(engine: FlipbookEngine, options?: FlipbookEmbedOptions);
+    connect(): this;
+    disconnect(): void;
+    private readonly engineEventNames;
+    private isAllowedOrigin;
+    private post;
+    private postEvent;
+    private respond;
+    private handleMessage;
+    private getState;
+}
+export interface FlipbookEmbedController {
+    send(command: FlipbookEmbedCommandName, payload?: unknown): Promise<unknown>;
+    goToPage(pageIndex: number): Promise<FlipbookEmbedState>;
+    nextPage(): Promise<FlipbookEmbedState>;
+    prevPage(): Promise<FlipbookEmbedState>;
+    setZoom(zoom: number): Promise<FlipbookEmbedState>;
+    setSingleMode(isSingle: boolean): Promise<FlipbookEmbedState>;
+    updateOptions(options: Partial<FlipbookEngineOptions>): Promise<FlipbookEmbedState>;
+    toggleFullscreen(): Promise<FlipbookEmbedState>;
+    search(query: string, options?: FlipbookSearchOptions): Promise<FlipbookSearchResult[]>;
+    clearSearch(): Promise<FlipbookEmbedState>;
+    getSearchResults(): Promise<FlipbookSearchResult[]>;
+    getToc(): Promise<FlipbookTocEntry[]>;
+    setToc(entries: FlipbookTocEntry[], show?: boolean): Promise<FlipbookEmbedState>;
+    getState(): Promise<FlipbookEmbedState>;
+    on<T extends FlipbookEngineEventName>(event: T, handler: (payload: FlipbookEngineEventMap[T]) => void): () => void;
+    destroy(): void;
+}
+export declare function createFlipbookEmbedController(iframe: HTMLIFrameElement, options?: FlipbookEmbedOptions): FlipbookEmbedController;