flipbookengine 0.5.2 → 0.5.4

package/README.md

@@ -1,5 +1,7 @@
 # FlipbookEngine
 
+> **Release notice:** `flipbookengine@0.5.3` is a valid published release. Upgrade to `0.5.4` or later for lifecycle, locale, and PDF render error-handling fixes. The post-tag source regression was corrected before the 0.5.4 release.
+
 [![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)
@@ -62,7 +64,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.5.0/dist/flipbook-engine.css" />
+<link rel="stylesheet" href="https://unpkg.com/flipbookengine@0.5.4/dist/flipbook-engine.css" />
 <div id="viewer" style="width: 100%; height: 600px;"></div>
 
 <script type="importmap">
@@ -73,7 +75,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.5.0/dist/flipbook-engine.js';
+  import { FlipbookEngine } from 'https://unpkg.com/flipbookengine@0.5.4/dist/flipbook-engine.js';
 
   const engine = new FlipbookEngine('#viewer', {
     pdfWorkerSrc: 'https://unpkg.com/pdfjs-dist@5.4.530/build/pdf.worker.min.mjs'
@@ -143,7 +145,7 @@ 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.
 
-
+
 ## Public API Reference
 
 The `FlipbookEngine` class exposes the following public methods:
@@ -157,8 +159,8 @@ The `FlipbookEngine` class exposes the following public methods:
 - **`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.
+- **`setLocale(locale: string, messages?: PartialFlipbookMessages | Record<string, PartialFlipbookMessages>)`**: Updates the locale programmatically and optionally overrides messages for that locale.
+- **`destroy(keepContainer = false)`**: Tears down the instance and listeners; when `true`, keeps the container markup for an immediate reinitialization.
 
 ### Subscribing to Events
 
@@ -237,33 +239,33 @@ 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
-
-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.
-
+## 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/THIRD-PARTY-NOTICES.md

@@ -1,117 +1,117 @@
-# Third-Party Notices
-
-This file contains the licenses of the third-party libraries used in the FlipbookEngine project.
-
-## Runtime Dependencies
-
-### 1. PDF.js (pdfjs-dist)
-- **Website:** https://mozilla.github.io/pdf.js/
-- **Repository:** https://github.com/mozilla/pdf.js
-- **License:** Apache License 2.0
-
-```text
-Copyright 2012 Mozilla Foundation
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-```
-
----
-
-### 2. page-flip
-- **Website:** https://nodlik.github.io/StPageFlip/
-- **Repository:** https://github.com/Nodlik/StPageFlip
-- **License:** MIT License
-
-```text
-The MIT License (MIT)
-Copyright (c) 2020 Oleg
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-```
-
----
-
-### 3. @preact/signals-core
-- **Repository:** https://github.com/preactjs/signals
-- **License:** MIT License
-
-```text
-The MIT License (MIT)
-Copyright (c) 2022-present Preact Team
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-```
-
----
-
-### 4. @serenity-is/domwise
-- **Repository:** https://github.com/serenity-is/serenity
-- **License:** MIT License
-
-```text
-The MIT License (MIT)
-Copyright (c) Serenity.is
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-```
-
----
-
-## Development Dependencies
-
-Development dependencies such as `vite`, `typescript`, and their respective plugins are licensed under the MIT License. These tools are used during the build process and are not distributed as part of the compiled FlipbookEngine bundle.
+# Third-Party Notices
+
+This file contains the licenses of the third-party libraries used in the FlipbookEngine project.
+
+## Runtime Dependencies
+
+### 1. PDF.js (pdfjs-dist)
+- **Website:** https://mozilla.github.io/pdf.js/
+- **Repository:** https://github.com/mozilla/pdf.js
+- **License:** Apache License 2.0
+
+```text
+Copyright 2012 Mozilla Foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
+
+---
+
+### 2. page-flip
+- **Website:** https://nodlik.github.io/StPageFlip/
+- **Repository:** https://github.com/Nodlik/StPageFlip
+- **License:** MIT License
+
+```text
+The MIT License (MIT)
+Copyright (c) 2020 Oleg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
+---
+
+### 3. @preact/signals-core
+- **Repository:** https://github.com/preactjs/signals
+- **License:** MIT License
+
+```text
+The MIT License (MIT)
+Copyright (c) 2022-present Preact Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
+---
+
+### 4. @serenity-is/domwise
+- **Repository:** https://github.com/serenity-is/serenity
+- **License:** MIT License
+
+```text
+The MIT License (MIT)
+Copyright (c) Serenity.is
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
+---
+
+## Development Dependencies
+
+Development dependencies such as `vite`, `typescript`, and their respective plugins are licensed under the MIT License. These tools are used during the build process and are not distributed as part of the compiled FlipbookEngine bundle.

package/TRADEMARK_POLICY.md

@@ -1,50 +1,50 @@
-# FlipbookEngine Trademark Policy
-
-This policy governs use of the FlipbookEngine name, logos, and brand assets.
-
-## Covered Marks
-
-The following are treated as protected brand assets:
-
-- FlipbookEngine
-- FlipbookEngine logos
-- any official product lockups, icons, and visual identity files distributed with the project
-
-## What the Open Source License Does Not Grant
-
-The AGPL license applies to source code, not to trademark rights.
-
-Using the FlipbookEngine code does not automatically grant permission to:
-
-- present your product as the official FlipbookEngine product
-- use FlipbookEngine logos in your own branding
-- imply sponsorship, certification, or endorsement
-- register confusingly similar names, domains, or product marks
-
-## Allowed Uses
-
-Unless otherwise stated, you may:
-
-- refer to FlipbookEngine by name in factual descriptions
-- state that your project uses or is powered by FlipbookEngine
-- link to the official project and documentation
-
-## Uses That Require Permission
-
-You must get permission before:
-
-- using official logos in a product UI or marketing page
-- using FlipbookEngine as part of your own product or company name
-- presenting your fork as the official project
-- using the marks in paid advertising or marketplace listings
-
-## Open Source Attribution
-
-Attribution is appreciated in open source projects, but trademark permission is still separate from code licensing.
-
-## Contact
-
-Trademark and brand permission inquiries:
-
-- murat.dogan@hotmail.com.tr
-
+# FlipbookEngine Trademark Policy
+
+This policy governs use of the FlipbookEngine name, logos, and brand assets.
+
+## Covered Marks
+
+The following are treated as protected brand assets:
+
+- FlipbookEngine
+- FlipbookEngine logos
+- any official product lockups, icons, and visual identity files distributed with the project
+
+## What the Open Source License Does Not Grant
+
+The AGPL license applies to source code, not to trademark rights.
+
+Using the FlipbookEngine code does not automatically grant permission to:
+
+- present your product as the official FlipbookEngine product
+- use FlipbookEngine logos in your own branding
+- imply sponsorship, certification, or endorsement
+- register confusingly similar names, domains, or product marks
+
+## Allowed Uses
+
+Unless otherwise stated, you may:
+
+- refer to FlipbookEngine by name in factual descriptions
+- state that your project uses or is powered by FlipbookEngine
+- link to the official project and documentation
+
+## Uses That Require Permission
+
+You must get permission before:
+
+- using official logos in a product UI or marketing page
+- using FlipbookEngine as part of your own product or company name
+- presenting your fork as the official project
+- using the marks in paid advertising or marketplace listings
+
+## Open Source Attribution
+
+Attribution is appreciated in open source projects, but trademark permission is still separate from code licensing.
+
+## Contact
+
+Trademark and brand permission inquiries:
+
+- murat.dogan@hotmail.com.tr
+

package/dist/adapters/PageFlipAdapter.d.ts

@@ -13,6 +13,7 @@ export declare class PageFlipAdapter {
     private audioUnlockHandler;
     private isLibraryFlipping;
     private autoPlayTimer;
+    private layoutUpdateTimer;
     constructor(bookContainer: HTMLElement, options: FlipbookEngineOptions, store: FlipbookStore);
     private unlockAudio;
     init(viewportWidth: number, viewportHeight: number): void;

package/dist/core/LayoutManager.d.ts

@@ -1,7 +1,7 @@
 import { FlipbookStore } from '../state/store';
 
 /**
- * @license FlipbookEngine v0.2.4
+ * @license FlipbookEngine v0.5.4
  * Copyright (c) 2026 Murat Dogan
  *
  * This source code is dual-licensed under the AGPLv3 and a Commercial License.
@@ -23,6 +23,7 @@ export declare class LayoutManager {
     private orientationMediaQuery;
     private orientationChangeHandler;
     private unsubs;
+    private updateTimer;
     onResizeCallback?: () => void;
     constructor(pageViewport: {
         width: number;
@@ -34,4 +35,5 @@ export declare class LayoutManager {
     private setupOrientationMedia;
     updateBookAspectRatio(): void;
     destroy(): void;
+    private scheduleAspectRatioUpdate;
 }