flipbookengine 0.6.0 → 0.6.5

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
-## 0.6.0 (unreleased)
+## Next (unreleased)
+
+## 0.6.5
+
+- added automatic A3 landscape PDF splitting with configurable auto, single, and split modes
+- added source-page-aware lazy rendering for split PDF pages
+- added optional light/dark viewer backgrounds and responsive presentation gutters
+- enlarged the opt-in thumbnail rail and moved page labels into transparent, high-contrast overlays
+- kept thumbnail labels black in both themes and preserved a thin neon selected state
+- enabled native mobile scrolling to avoid non-cancelable touchstart interventions
+- fixed single-view PDF hydration after switching from spread mode
+- added regression coverage for PDF splitting, backgrounds, presentation layout, and PDF hydration
+
+## 0.6.0
 
 - added a localized, theme-aware Table of Contents panel with nested host-provided page entries
 - added TOC visibility events, page navigation, normalization, accessibility, and regression tests

package/README.md

@@ -1,7 +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.
-> **Development notice:** `0.6.0` is the next unreleased feature candidate and adds the localized Table of Contents API. `0.5.4` remains the latest published version until the 0.6.0 release.
+> **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.
 
 [![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)
@@ -45,18 +45,23 @@ import pdfWorkerSrc from 'pdfjs-dist/build/pdf.worker.mjs?url';
 
 const engine = new FlipbookEngine('#viewer', {
   allowDownload: true,
-  showThumbs: true,
+  showThumbs: false,
   primaryColor: '#7367f0',
   theme: 'auto',
   locale: 'en',
   pdfWorkerSrc,
-  pdfRenderCacheSize: 32
+  pdfRenderCacheSize: 32,
+  pdfPageMode: 'auto',
+  background: {
+    light: { color: '#f8fafc', image: '/branding/light.webp', size: 'cover' },
+    dark: { color: '#0f172a', image: '/branding/dark.webp', size: 'cover' }
+  }
 });
 
 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.
+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. In `pdfPageMode: 'auto'` (the default), ISO A3 landscape pages are normalized into two logical pages; use `'single'` to keep every PDF page intact or `'split'` to split every landscape PDF page.
 
 `pdfRenderCacheSize` controls the per-instance LRU cache (default `32`, set to `0` to disable it).
 
@@ -65,7 +70,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.4/dist/flipbook-engine.css" />
+<link rel="stylesheet" href="https://unpkg.com/flipbookengine@0.6.5/dist/flipbook-engine.css" />
 <div id="viewer" style="width: 100%; height: 600px;"></div>
 
 <script type="importmap">
@@ -76,7 +81,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.4/dist/flipbook-engine.js';
+  import { FlipbookEngine } from 'https://unpkg.com/flipbookengine@0.6.5/dist/flipbook-engine.js';
 
   const engine = new FlipbookEngine('#viewer', {
     pdfWorkerSrc: 'https://unpkg.com/pdfjs-dist@5.4.530/build/pdf.worker.min.mjs'
@@ -192,6 +197,12 @@ Supported events: `init`, `progress`, `pageChange`, `zoomChange`, `singlePageMod
 | `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. |
+| `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. |
+
+## PDF page formats
+
+PDF.js page dimensions are detected at runtime, so portrait A4, landscape A4, and other page ratios are supported without a fixed size preset. A3 landscape pages are split into left/right logical pages when `pdfPageMode` is `'auto'` or `'split'`; the halves are presented as an A4-like spread in double-page mode.
 
 ## Styling and Theming
 

package/dist/core/LayoutManager.d.ts

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

package/dist/core/PdfRenderer.d.ts

@@ -4,6 +4,14 @@ export interface PdfRenderProgress {
     completed: number;
     total: number;
 }
+export type PdfPageMode = 'auto' | 'single' | 'split';
+export interface PdfPageLayout {
+    width: number;
+    height: number;
+    split: boolean;
+}
+/** Detects ISO A3 landscape pages while allowing PDF metadata rounding and bleed. */
+export declare function isA3Landscape(width: number, height: number): boolean;
 export interface PdfRenderOptions {
     scale?: number;
     quality?: number;
@@ -22,8 +30,10 @@ export declare class PdfRenderer {
     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>;
-    /** Calculates the best viewport dimensions based on the first page. */
-    calculateViewportDimensions(baseShortSide?: number): Promise<{
+    /** 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. */
+    calculateViewportDimensions(baseShortSide?: number, firstPageLayout?: PdfPageLayout): Promise<{
         width: number;
         height: number;
     }>;