flipbookengine 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,4 +1,24 @@
-# Changelog
+# Changelog
+
+## 0.5.0
+
+- added on-demand PDF page rendering with first-page readiness and next-page prefetch
+- added bounded per-instance PDF render cache via `pdfRenderCacheSize`
+- added React/Vue wrapper, browser E2E, and large-document regression coverage
+- added reduced-motion support for JavaScript page turns and CSS transitions
+- removed test exception suppression so asynchronous teardown failures surface
+
+
+
+## 0.4.0
+
+- externalized PDF.js as an npm dependency with consumer-provided worker configuration
+- fixed PDF-only initialization when `pages` is omitted
+- isolated engine state and lifecycle cancellation per instance
+- aligned framework wrappers, events, options, fullscreen, audio, and download controls
+- added progressive image quality loading and bounded PDF rendering with cancellation
+- added accessibility semantics, structured PDF progress/error events, and expanded regression tests
+- added CI dependency audit, reproducible package verification, and provenance-enabled release workflow
 
 ## 0.1.0
 

package/README.md

@@ -1,221 +1,279 @@
-# FlipbookEngine
-
-[![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)
-[![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/flipbookengine?style=flat-square)](https://www.npmjs.com/package/flipbookengine)
-[![NPM Downloads](https://img.shields.io/npm/dt/flipbookengine?style=flat-square)](https://www.npmjs.com/package/flipbookengine)
-
-**[🔥 Live Demo & Playground](https://flipbookengine.com)**
-
-FlipbookEngine is a modern, lightweight, and embeddable HTML flipbook viewer for PDF-backed catalogs, brochures, and digital publications. Written in TypeScript, it features single-page and spread modes, a thumbnail rail, smooth zoom/pan, full internationalization (i18n), and robust theme customization.
-
-## Highlights
-
-- **Dual-Mode Layout**: Seamlessly switches between single-page (mobile-optimized) and spread (book/catalog layout) modes.
-- **Rich Interaction**: Built-in thumbnail navigation rail, smooth zoom & pan, and HTML5 fullscreen support.
-- **Media & Autoplay**: Configurable page-flip sound effects and automated slideshow presentation with `Autoplay`.
-- **Theme Engine**: Styled with compiled CSS and CSS Custom Properties, featuring full support for light/dark modes (auto-responsive to Bootstrap 5 or tailorable per instance).
-- **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.
-
-## Installation
-
-Install via npm:
-
-```bash
-npm install flipbookengine
-```
-
-For direct CDN usage in the browser (Vanilla HTML/JS):
-
-```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>
-```
-
-## Quick Start
-
-### Vanilla HTML / JS
-
-Include the styles and script, then initialize the engine:
-
-```html
-<div id="viewer" style="width: 100%; height: 600px;"></div>
-
-<script>
-  const engine = new FlipbookEngine('#viewer', {
-    allowDownload: true,
-    showThumbs: true,
-    primaryColor: '#7367f0',
-    theme: 'auto',
-    locale: 'en'
-  });
-
-  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' }
-  ]);
-</script>
-```
-
-### React
-
-```tsx
-import React, { useRef } from 'react';
-import { Flipbook, FlipbookRef } from 'flipbookengine/react';
-import 'flipbookengine/dist/flipbook-engine.css';
-
-function CatalogViewer() {
-  const flipbookRef = useRef<FlipbookRef>(null);
-
-  const handleNextPage = () => {
-    flipbookRef.current?.goToPage(flipbookRef.current.getCurrentPage() + 1);
-  };
-
-  return (
-    <Flipbook
-      ref={flipbookRef}
-      pdfUrl="/files/catalog.pdf"
-      pages={[
-        { 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' }
-      ]}
-      allowDownload={true}
-      showThumbs={true}
-      primaryColor="#7367f0"
-    />
-  );
-}
-```
-
-### Vue 3
-
-```vue
-<template>
-  <Flipbook
-    pdfUrl="/files/catalog.pdf"
-    :pages="pages"
-    :allowDownload="true"
-    :showThumbs="true"
-    primaryColor="#7367f0"
-  />
-</template>
-
-<script setup>
-import { Flipbook } from 'flipbookengine/vue';
-import 'flipbookengine/dist/flipbook-engine.css';
-
-const pages = [
-  { 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' }
-];
-</script>
-```
-
-## Public API Reference
-
-The `FlipbookEngine` class exposes the following public methods:
-
-- **`init(pdfUrl: string, imageList?: FlipbookPageAsset[])`**: Initializes the viewer and loads the flipbook with pages.
-- **`goToPage(pageIndex: number)`**: Navigates programmatically to a 0-based page index.
-- **`getCurrentPage()`**: Returns the 0-based index of the currently active page.
-- **`getTotalPages()`**: Returns the total number of pages.
-- **`getZoom()`**: Returns the current zoom level (default is `1`).
-- **`setZoom(zoomLevel: number)`**: Programmatically sets the zoom level (accepts values between `0.5` and `5`).
-- **`setSingleMode(isSingle: boolean)`**: Programmatically toggles between single-page mode (`true`) and double-page spread mode (`false`).
-- **`toggleFullscreen()`**: Programmatically toggles fullscreen mode.
-- **`updateOptions(options: Partial<FlipbookEngineOptions>)`**: Updates instance options at runtime.
-- **`setLocale(locale: string, messages?: PartialFlipbookMessages)`**: Updates the locale programmatically.
-- **`destroy(clearMarkup = true)`**: Tears down the instance and clean up DOM listeners.
-
-### Subscribing to Events
-
-You can subscribe to events using `.on()`:
-
-```ts
-const unsubscribe = engine.on('pageChange', ({ currentPage, totalPages, isSingle }) => {
-  console.log('Page Changed:', currentPage, 'Total:', totalPages);
-});
-
-// To unsubscribe:
-unsubscribe();
-```
-
-Supported events: `pageChange`, `zoomChange`, `singlePageModeChange`, `thumbsToggle`, `destroy`.
-
-| Option | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `soundEnabled` | `boolean` | `true` | Enables page turning sound effect. |
-| `soundUrl` | `string` | `'https://.../page-flip.mp3'` | URL of the audio file. |
-| `autoPlayInterval`| `number` | `3000` | Autoplay page duration in milliseconds. |
-| `flippingTime` | `number` | `1000` | Duration of the page turn animation in milliseconds. |
-| `maxShadowOpacity` | `number` | `0.5` | Maximum opacity of the shadow during page turn (0 to 1). |
-| `whiteLabel` | `boolean` | `false` | Hides the "Powered by FlipbookEngine" watermark. |
-
-## Styling and Theming
-
-FlipbookEngine features fully custom-property-based styling compatible with modern styling systems.
-
-### Global CSS Variables
-
-```css
-:root {
-  --mainbgcolor: #f3f6fb;
-  --panelbgcolor: #172033;
-  --accentcolor: #7367f0;
-  --thumbrailbgcolor: #0f172a;
-}
-```
-
-## 🚀 Performance & Bundle Metrics
-
-FlipbookEngine is engineered for high performance, utilizing hardware-accelerated CSS 3D transforms instead of heavy WebGL, ensuring a smooth **60 FPS** experience even on low-end mobile devices.
-
-### 📦 Bundle Size (Zero-Config PDF Engine)
-Unlike other libraries that require complex external PDF.js worker configurations, FlipbookEngine ships as an **"All-in-One"** package. It includes the Core Engine, UI layout, StPageFlip, and the full PDF.js rendering engine out of the box.
-
-*   **Core + PDF Engine (Gzipped):** `~788 KB` *(A single drop-in script, no external workers needed)*
-*   **Styles (CSS Gzipped):** `~2.9 KB`
-*   **React / Vue Wrappers (Gzipped):** `< 1 KB`
-
-### ⚡ Performance Highlights
-*   **Hardware Accelerated:** Uses purely CSS-based 3D transformations (`transform: rotateY`, `translateZ`) which offloads rendering to the GPU. No heavy WebGL overhead.
-*   **Smart Memory Management (Lazy Loading):** Automatically unloads hidden pages from the DOM and destroys unused PDF blobs to prevent memory leaks on large catalogs.
-*   **Zero-CLS Layouts:** Prevents Cumulative Layout Shift (CLS) by utilizing highly optimized `AbortController` bound resize event listeners and native CSS `aspect-ratio` calculations.
-*   **Eco-Friendly Standby:** Stops running layout calculations when the catalog is not actively being dragged or flipped.
-
-## 🥊 FlipbookEngine vs. The Industry
-
-When choosing a flipbook library, here is how we compare to other solutions:
-
-*   **Legacy Libraries (e.g., Turn.js):** Turn.js is over a decade old, relies on jQuery, and lacks native PDF support. **FlipbookEngine** uses a modern framework-agnostic stack (Vanilla/React/Vue), TypeScript, and has built-in PDF.js integration.
-*   **Heavy 3D Plugins (e.g., DearFlip, Real3D):** Many 3D plugins use WebGL, which drains CPU/RAM and can be sluggish on mobile. **FlipbookEngine** is powered by StPageFlip, delivering buttery-smooth 60FPS CSS 2D/3D performance while remaining lightweight.
-*   **Closed SaaS Platforms (e.g., Issuu, Heyzine):** These charge high monthly fees and lock your data on their servers. **FlipbookEngine** gives you 100% control to host and embed directly in your own code (AGPL-3.0).
-
----
-
-## 🙏 Acknowledgments
-
-A special thanks to the incredible team behind **[Serenity](https://github.com/serenity-is/serenity)**. FlipbookEngine's reactive UI layer is proudly powered by **[domwise](https://github.com/serenity-is/serenity/tree/master/packages/domwise)** (a brilliant DOM manipulation library developed by the Serenity team). Coupled with `@preact/signals-core`, `domwise` allows us to completely bypass the heavy overhead of traditional Virtual DOM diffing. This architectural choice is a massive contributor to FlipbookEngine's lightning-fast UI updates, ensuring buttery-smooth 60 FPS performance even on low-end mobile devices.
-
----
-
-## 🗺️ Roadmap (Upcoming in v1.0.0)
-
-We are constantly working to make FlipbookEngine the definitive choice for enterprise digital catalogs. The upcoming **v1.0.0 Major Release** will introduce several advanced features designed for commercial scale:
-
-- 📑 **Table of Contents (Index):** A dedicated, interactive side-menu allowing readers to instantly jump to specific chapters or product categories.
-- 📝 **Page Notes & Annotations:** Allow readers to drop personal notes or bookmarks directly onto pages.
-- 🔍 **Full-Text PDF Search:** Client-side search capabilities via extracted JSON indices, enabling instant text highlighting across hundreds of pages without locking the UI.
-- 🎯 **Interactive Hotspots & Pop-ups:** Draw custom coordinates over the canvas to embed YouTube videos, image galleries, or direct "Buy Now" e-commerce links right on top of the catalog pages.
-
----
-
-## 📄 Licensing
-
-FlipbookEngine is distributed under a dual-license model:
-
-- **Open Source**: GNU Affero General Public License v3.0 or later (see [LICENSE](./LICENSE)).
-- **Commercial**: For use in closed-source projects, proprietary SaaS platforms, or agency client deliveries (see [COMMERCIAL_LICENSE.md](./COMMERCIAL_LICENSE.md)).
-
-For commercial licenses and inquiries, contact: **murat.dogan@hotmail.com.tr**
+# FlipbookEngine
+
+[![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)
+[![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/flipbookengine?style=flat-square)](https://www.npmjs.com/package/flipbookengine)
+[![NPM Downloads](https://img.shields.io/npm/dt/flipbookengine?style=flat-square)](https://www.npmjs.com/package/flipbookengine)
+
+**[Live Demo & Playground ↗](https://flipbookengine.com)**
+
+FlipbookEngine is a modern, lightweight, and embeddable HTML flipbook viewer for PDF-backed catalogs, brochures, and digital publications. Written in TypeScript, it features single-page and spread modes, a thumbnail rail, smooth zoom/pan, full internationalization (i18n), and robust theme customization.
+
+## Highlights
+
+- **Dual-Mode Layout**: Seamlessly switches between single-page (mobile-optimized) and spread (book/catalog layout) modes.
+- **Rich Interaction**: Built-in thumbnail navigation rail, smooth zoom & pan, and HTML5 fullscreen support.
+- **Media & Autoplay**: Configurable page-flip sound effects and automated slideshow presentation with `Autoplay`.
+- **Theme Engine**: Styled with compiled CSS and CSS Custom Properties, featuring full support for light/dark modes (auto-responsive to Bootstrap 5 or tailorable per instance).
+- **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.
+
+## Installation
+
+Install via npm:
+
+```bash
+npm install flipbookengine
+```
+
+`pdfjs-dist` is a production dependency of FlipbookEngine. It is installed by npm, but is deliberately excluded from the FlipbookEngine bundle so applications can deduplicate, cache, and upgrade PDF.js independently.
+
+## Quick Start
+
+### npm and Bundlers
+
+Configure the PDF.js worker in the consuming application. The `?url` suffix is supported by Vite and other modern bundlers that emit imported assets.
+
+```ts
+import { FlipbookEngine } from 'flipbookengine';
+import 'flipbookengine/styles.css';
+import pdfWorkerSrc from 'pdfjs-dist/build/pdf.worker.mjs?url';
+
+const engine = new FlipbookEngine('#viewer', {
+  allowDownload: true,
+  showThumbs: true,
+  primaryColor: '#7367f0',
+  theme: 'auto',
+  locale: 'en',
+  pdfWorkerSrc,
+  pdfRenderCacheSize: 32
+});
+
+await engine.init('/files/catalog.pdf');
+```
+
+Passing `pages` remains optional. When omitted, FlipbookEngine creates the page structure from `pdfUrl`, renders the first page before `init` resolves, and prefetches the next page. Additional pages render as they become visible or are selected.
+
+`pdfRenderCacheSize` controls the per-instance LRU cache (default `32`, set to `0` to disable it).
+
+### Browser CDN
+
+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.5.0/dist/flipbook-engine.css" />
+<div id="viewer" style="width: 100%; height: 600px;"></div>
+
+<script type="importmap">
+{
+  "imports": {
+    "pdfjs-dist": "https://unpkg.com/pdfjs-dist@5.4.530/build/pdf.min.mjs"
+  }
+}
+</script>
+<script type="module">
+  import { FlipbookEngine } from 'https://unpkg.com/flipbookengine@0.5.0/dist/flipbook-engine.js';
+
+  const engine = new FlipbookEngine('#viewer', {
+    pdfWorkerSrc: 'https://unpkg.com/pdfjs-dist@5.4.530/build/pdf.worker.min.mjs'
+  });
+
+  await engine.init('/files/catalog.pdf');
+</script>
+```
+
+### React
+
+```tsx
+import React, { useRef } from 'react';
+import { Flipbook, FlipbookRef } from 'flipbookengine/react';
+import 'flipbookengine/styles.css';
+
+function CatalogViewer() {
+  const flipbookRef = useRef<FlipbookRef>(null);
+
+  const handleNextPage = () => {
+    flipbookRef.current?.goToPage(flipbookRef.current.getCurrentPage() + 1);
+  };
+
+  return (
+    <Flipbook
+      ref={flipbookRef}
+      pdfUrl="/files/catalog.pdf"
+      pages={[
+        { 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' }
+      ]}
+      allowDownload={true}
+      showThumbs={true}
+      primaryColor="#7367f0"
+    />
+  );
+}
+```
+
+### Vue 3
+
+```vue
+<template>
+  <Flipbook
+    pdfUrl="/files/catalog.pdf"
+    :pages="pages"
+    :allowDownload="true"
+    :showThumbs="true"
+    primaryColor="#7367f0"
+  />
+</template>
+
+<script setup>
+import { Flipbook } from 'flipbookengine/vue';
+import 'flipbookengine/styles.css';
+
+const pages = [
+  { 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' }
+];
+</script>
+```
+
+## 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.
+
+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.
+
+
+## Public API Reference
+
+The `FlipbookEngine` class exposes the following public methods:
+
+- **`init(pdfUrl: string, imageList?: FlipbookPageAsset[])`**: Initializes the viewer and loads the flipbook with pages.
+- **`goToPage(pageIndex: number)`**: Navigates programmatically to a 0-based page index.
+- **`getCurrentPage()`**: Returns the 0-based index of the currently active page.
+- **`getTotalPages()`**: Returns the total number of pages.
+- **`getZoom()`**: Returns the current zoom level (default is `1`).
+- **`setZoom(zoomLevel: number)`**: Programmatically sets the zoom level (accepts values between `0.5` and `5`).
+- **`setSingleMode(isSingle: boolean)`**: Programmatically toggles between single-page mode (`true`) and double-page spread mode (`false`).
+- **`toggleFullscreen()`**: Programmatically toggles fullscreen mode.
+- **`updateOptions(options: Partial<FlipbookEngineOptions>)`**: Updates instance options at runtime.
+- **`setLocale(locale: string, messages?: PartialFlipbookMessages)`**: Updates the locale programmatically.
+- **`destroy(clearMarkup = true)`**: Tears down the instance and clean up DOM listeners.
+
+### Subscribing to Events
+
+You can subscribe to events using `.on()`. PDF-backed initialization reports loading/rendering progress and emits a structured `error` event when loading or rendering fails:
+
+```ts
+const unsubscribe = engine.on('pageChange', ({ currentPage, totalPages, isSingle }) => {
+  console.log('Page Changed:', currentPage, 'Total:', totalPages);
+});
+
+// To unsubscribe:
+unsubscribe();
+```
+
+Supported events: `init`, `progress`, `pageChange`, `zoomChange`, `singlePageModeChange`, `thumbsToggle`, `orientationChange`, `error`, `destroy`.
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `showArrows` | `boolean` | `true` | Shows the previous/next navigation arrows. |
+| `soundEnabled` | `boolean` | `true` | Enables page turning sound effect. |
+| `soundUrl` | `string` | `'https://.../page-flip.mp3'` | URL of the audio file. |
+| `autoPlayInterval`| `number` | `3000` | Autoplay page duration in milliseconds. |
+| `flippingTime` | `number` | `1000` | Duration of the page turn animation in milliseconds; automatically disabled when reduced motion is preferred. |
+| `maxShadowOpacity` | `number` | `0.5` | Maximum opacity of the shadow during page turn (0 to 1). |
+| `whiteLabel` | `boolean` | `false` | Hides the "Powered by FlipbookEngine" watermark. |
+| `pdfWorkerSrc` | `string` | - | URL of the PDF.js worker emitted or hosted by the consuming application. |
+| `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. |
+
+## Styling and Theming
+
+FlipbookEngine features fully custom-property-based styling compatible with modern styling systems.
+
+### Global CSS Variables
+
+```css
+:root {
+  --mainbgcolor: #f3f6fb;
+  --panelbgcolor: #172033;
+  --flipbook-accent: #7367f0;
+  --thumbrailbgcolor: #0f172a;
+}
+```
+
+## Performance & Bundle Metrics
+
+FlipbookEngine is designed for responsive rendering with hardware-accelerated CSS 3D transforms and a lightweight DOM update path.
+
+### Package Size and PDF.js
+
+FlipbookEngine does not bundle PDF.js or its worker. `pdfjs-dist` remains a normal npm dependency, while the host application supplies `pdfWorkerSrc`. This keeps the FlipbookEngine package smaller and lets the application control PDF.js versioning, caching, CSP, and worker hosting.
+
+*   **Core engine:** excludes PDF.js and the PDF worker.
+*   **Styles:** distributed as `flipbookengine/styles.css`.
+*   **PDF rendering:** enabled by configuring `pdfWorkerSrc` as shown above.
+
+### Performance Highlights
+*   **Hardware Accelerated:** Uses CSS-based 3D transformations (`transform: rotateY`, `translateZ`) without a WebGL runtime.
+*   **Progressive Image Quality:** Loads low-quality page assets first and upgrades visible pages to their normal-quality source through `IntersectionObserver`.
+*   **On-demand PDF Rendering:** Large PDFs create lightweight placeholders first; the current page and next page render before or during navigation.
+*   **Bounded PDF Rendering:** PDF pages are rendered with configurable concurrency (`pdfRenderConcurrency`, default `3`) and can be cancelled when an initialization is superseded or destroyed.
+*   **PDF Render Cache:** A bounded per-instance LRU cache (`pdfRenderCacheSize`, default `32`) avoids repeated canvas work while preventing unbounded memory growth.
+
+## FlipbookEngine vs. The Industry
+
+When choosing a flipbook library, here is how we compare to other solutions:
+
+*   **Legacy Libraries (e.g., Turn.js):** Turn.js is over a decade old, relies on jQuery, and lacks native PDF support. **FlipbookEngine** uses a modern framework-agnostic stack (Vanilla/React/Vue), TypeScript, and has built-in PDF.js integration.
+*   **Heavy 3D Plugins (e.g., DearFlip, Real3D):** Many 3D plugins use WebGL, which can increase runtime overhead on mobile. **FlipbookEngine** uses StPageFlip with CSS 2D/3D transforms and no WebGL runtime.
+*   **Closed SaaS Platforms (e.g., Issuu, Heyzine):** These charge high monthly fees and lock your data on their servers. **FlipbookEngine** gives you 100% control to host and embed directly in your own code (AGPL-3.0).
+
+---
+
+## Acknowledgments
+
+A special thanks to the domwise project. FlipbookEngine's reactive UI layer is powered by **domwise** and `@preact/signals-core`, keeping the UI update path small without requiring a traditional Virtual DOM runtime.
+
+---
+## Roadmap
+
+FlipbookEngine has two complementary targets: an AGPL open-source viewer package and a separate closed-source commercial backend edition.
+
+### 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:
+
+- **Table of Contents (Index):** Interactive navigation to chapters or product categories.
+- **Page Notes & Annotations:** Reader notes and bookmarks stored by the host application.
+- **Full-Text PDF Search:** Client-side text extraction and highlighting without blocking the viewer.
+- **Interactive Hotspots & Pop-ups:** Custom overlays for media, galleries, and commerce links.
+- **Deep Linking & Social Share:** URLs that address specific pages or spreads.
+
+The open-source viewer continues to use PDF.js as an external npm dependency and does not require a backend renderer.
+
+### 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:
+
+- **Backend PDF rendering:** Secure, server-side rendering and caching for protected documents and high-volume workloads.
+- **Protected partial downloads:** Server-generated page selections and authorization-aware download policies.
+- **AI-assisted document features:** Backend indexing, catalog search, and Chat with Docs integrations.
+- **Enterprise identity and provenance:** OIDC, auditability, tenant controls, and deployment integration.
+
+These backend renderer and enterprise features will not be included in the public `flipbookengine` npm package; they will be delivered under the commercial license.
+
+---
+
+## Licensing
+
+FlipbookEngine is distributed under a dual-license model:
+
+- **Open Source**: GNU Affero General Public License v3.0 or later (see [LICENSE](./LICENSE)).
+- **Commercial**: For use in closed-source projects, proprietary SaaS platforms, or agency client deliveries (see [COMMERCIAL_LICENSE.md](./COMMERCIAL_LICENSE.md)).
+
+For commercial licenses and inquiries, contact: **murat.dogan@hotmail.com.tr**
+
+
+

package/dist/adapters/PageFlipAdapter.d.ts

@@ -1,14 +1,19 @@
+import { FlipbookStore } from '../state/store';
 import { FlipbookEngineOptions } from '../engine';
 
+export declare function prefersReducedMotion(): boolean;
+export declare function resolveFlippingTime(flippingTime?: number, reducedMotion?: boolean): number;
 export declare class PageFlipAdapter {
     private pageFlip;
     private bookContainer;
     private options;
+    private store;
     private unsubs;
     private audioEl;
+    private audioUnlockHandler;
     private isLibraryFlipping;
     private autoPlayTimer;
-    constructor(bookContainer: HTMLElement, options: FlipbookEngineOptions);
+    constructor(bookContainer: HTMLElement, options: FlipbookEngineOptions, store: FlipbookStore);
     private unlockAudio;
     init(viewportWidth: number, viewportHeight: number): void;
     private bindEvents;

package/dist/components/App.d.ts

@@ -1,3 +1,4 @@
+import { FlipbookStore } from '../state/store';
 import { PageFlipAdapter } from '../adapters/PageFlipAdapter';
 import { InteractionManager } from '../core/InteractionManager';
 
@@ -13,6 +14,8 @@ interface AppProps {
     bookContainerRef: (el: HTMLElement) => void;
     className?: string;
     onDownload: () => void;
+    onToggleFullscreen: () => void;
+    store: FlipbookStore;
 }
 export declare function App(props: AppProps): import('@serenity-is/domwise').JSXElement;
 export {};

package/dist/components/NavigationArrows.d.ts

@@ -1,4 +1,7 @@
+import { FlipbookStore } from '../state/store';
+
 interface NavigationArrowsProps {
+    store: FlipbookStore;
     onPrevPage: () => void;
     onNextPage: () => void;
 }

package/dist/components/Thumbnails.d.ts

@@ -1,4 +1,7 @@
+import { FlipbookStore } from '../state/store';
+
 interface ThumbnailsProps {
+    store: FlipbookStore;
     onThumbClick: (pageIndex: number) => void;
 }
 export declare function Thumbnails(props: ThumbnailsProps): import('@serenity-is/domwise').JSXElement;

package/dist/components/Toolbar.d.ts

@@ -1,4 +1,7 @@
+import { FlipbookStore } from '../state/store';
+
 interface ToolbarProps {
+    store: FlipbookStore;
     onToggleThumbs: () => void;
     onToggleSingleMode: () => void;
     onZoomIn: () => void;

package/dist/components/Viewer.d.ts

@@ -1,4 +1,7 @@
+import { FlipbookStore } from '../state/store';
+
 interface ViewerProps {
+    store: FlipbookStore;
     bookWrapperRef: (el: HTMLElement) => void;
     bookSizerRef: (el: HTMLElement) => void;
     bookContainerRef: (el: HTMLElement) => void;

package/dist/core/InteractionManager.d.ts

@@ -1,11 +1,14 @@
+import { FlipbookStore } from '../state/store';
 import { PageFlipAdapter } from '../adapters/PageFlipAdapter';
 
 export declare class InteractionManager {
     private container;
     private pageFlipAdapter;
+    private store;
     private touchStartX;
     private unsubs;
-    constructor(container: HTMLElement, pageFlipAdapter: PageFlipAdapter);
+    private listenerAbortController;
+    constructor(container: HTMLElement, pageFlipAdapter: PageFlipAdapter, store: FlipbookStore);
     init(): void;
     private setupStateSync;
     private bindWheel;