flipbookengine 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,4 +1,14 @@
-# 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
 

package/README.md

@@ -17,6 +17,7 @@ FlipbookEngine is a modern, lightweight, and embeddable HTML flipbook viewer for
 - **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
 
@@ -45,20 +46,23 @@ const engine = new FlipbookEngine('#viewer', {
   primaryColor: '#7367f0',
   theme: 'auto',
   locale: 'en',
-  pdfWorkerSrc
+  pdfWorkerSrc,
+  pdfRenderCacheSize: 32
 });
 
 await engine.init('/files/catalog.pdf');
 ```
 
-Passing `pages` remains optional. When omitted, FlipbookEngine renders the pages from `pdfUrl`.
+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.4.0/dist/flipbook-engine.css" />
+<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">
@@ -69,7 +73,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.4.0/dist/flipbook-engine.js';
+  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'
@@ -137,30 +141,9 @@ const pages = [
 
 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.
+
 
-## Local npm Release
-
-Run the complete release verification locally before publishing:
-
-```bash
-npm ci
-npm run release:verify
-npm login
-npm publish --provenance --access public
-```
-
-Confirm the package version with `npm pkg get version` before publishing. The publish command is intentionally separate from `release:verify` so credentials and the final npm upload remain under the maintainer's direct control.
-### Windows PowerShell
-
-If PowerShell blocks `npm.ps1` because script execution is disabled, use the Windows command shim explicitly:
-
-```powershell
-npm.cmd ci
-npm.cmd run release:verify
-npm.cmd login
-npm.cmd whoami
-npm.cmd publish --access public
-```
 ## Public API Reference
 
 The `FlipbookEngine` class exposes the following public methods:
@@ -198,11 +181,12 @@ Supported events: `init`, `progress`, `pageChange`, `zoomChange`, `singlePageMod
 | `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. |
+| `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 during initialization. |
+| `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
 
@@ -234,7 +218,9 @@ FlipbookEngine does not bundle PDF.js or its worker. `pdfjs-dist` remains a norm
 ### 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
 
@@ -248,22 +234,36 @@ When choosing a flipbook library, here is how we compare to other solutions:
 
 ## Acknowledgments
 
-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.
+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 (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.
-- **Partial PDF Downloads:** Allow readers to select and download specific pages. Features a hybrid architecture: standalone client-side generation using `pdf-lib`, or an event-driven `onDownloadRequest` hook to offload generation to your own secure backend.
-- **AI Chatbot (Chat with Docs):** A built-in AI assistant interface to help users query catalog contents, find products, and get page recommendations instantly.
-- **Deep Linking & Social Share:** Generate and share URLs that point to specific pages or spreads directly via social media.
-
+## 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

package/dist/adapters/PageFlipAdapter.d.ts

@@ -1,6 +1,8 @@
 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;

package/dist/core/PdfRenderCache.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Small LRU cache for rendered PDF page data URLs.
+ * The cache is intentionally owned by one PdfRenderer instance so pages from
+ * different engine instances or documents can never be mixed.
+ */
+export declare class PdfRenderCache {
+    private readonly maxEntries;
+    private readonly entries;
+    private hits;
+    private misses;
+    constructor(maxEntries?: number);
+    get(pageNumber: number): string | undefined;
+    set(pageNumber: number, dataUrl: string): void;
+    clear(): void;
+    get size(): number;
+    getStats(): {
+        size: number;
+        maxEntries: number;
+        hits: number;
+        misses: number;
+    };
+}

package/dist/core/PdfRenderer.d.ts

@@ -10,11 +10,13 @@ export interface PdfRenderOptions {
     format?: string;
     workerSrc?: string;
     concurrency?: number;
+    cacheSize?: number;
 }
 export declare class PdfRenderer {
     private pdfDoc;
     private loadingTask;
     private options;
+    private readonly cache;
     constructor(options?: PdfRenderOptions);
     /** Loads a PDF document and cancels PDF.js loading when the signal aborts. */
     loadDocument(pdfUrl: string, signal?: AbortSignal): Promise<number>;
@@ -27,6 +29,12 @@ export declare class PdfRenderer {
     }>;
     /** Renders pages concurrently with a bounded worker pool and preserves page order. */
     renderAllPages(signal?: AbortSignal, onProgress?: (progress: PdfRenderProgress) => void): Promise<NormalizedFlipbookPage[]>;
+    getCacheStats(): {
+        size: number;
+        maxEntries: number;
+        hits: number;
+        misses: number;
+    };
     private throwIfAborted;
     private createAbortError;
     destroy(): void;