flipbookengine 1.0.0 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.0.3 - 2026-10-24
+
+- Fixed placing coordinate notes on Node 18 and on pages served over plain HTTP, where the browser or runtime has no `crypto.randomUUID`; the viewer now falls back to a generated note id.
+
+## 1.0.2 - 2026-10-24
+
+- Native backend search, page-note and coordinate-annotation providers, including multiple note markers per page and host-owned persistence.
+- Optional restricted rich-note editor factory and validated structured-note rendering; native note list, marker popups, edit/delete and failed-save draft retention.
+- Responsive native panels and More actions menu, localized keyboard help, focus restoration and gesture isolation for notes, zoom and page navigation.
+- Optional backend text-layer provider for image/WebP books, with schema v1 normalized logical-page runs and UTF-16 offsets.
+- Bounded current/adjacent-page loading, abort/stale-response isolation, defensive geometry validation and opt-in native text selection.
+- Isolated page images from host padding/margins so normalized overlays align with the complete page viewport.
+- Select-text command in the native More actions menu; Escape exits selection without hijacking page flipping or note gestures.
+- Backend search highlights continue to work independently of a text layer. OCR, persistence and search indexing remain host responsibilities.
+- Muted toolbar and More-menu items no longer show a diagonal strike line; they are only dimmed.
+- Toolbar play/pause and sound icons now switch by rendering a single icon instead of toggling two hidden ones.
+- The bottom toolbar adapts its buttons to the available width.
+- PDF mode renders the previous, current and next pages ahead of time (and the facing page in two-page view), so flipping shows pages without a blank flash; zoom reuses the rendered page image.
+- Page overlays (text layer, search highlights, hotspots, note placement) are drawn only in single-page view where they belong; page images no longer use native lazy loading.
+- The note popover is more compact, with smaller action buttons on mouse devices and touch-sized buttons on touch devices.
+- Removed a duplicate region landmark around the viewer for cleaner screen-reader navigation.
+- Fixed a type error in PDF page rendering when a rendered page has no image data.
+
 ## 1.0.0 - 2026-09-14
 
 - first stable open-source release of the FlipbookEngine viewer
@@ -9,7 +32,7 @@
 - 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
+- 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
@@ -93,4 +116,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 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.
+> **Current release:** `flipbookengine@1.0.3` includes the localized Table of Contents API, backend text layers and coordinate notes.
+> **1.0.0 scope:** Version 1.0.0 added 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)
@@ -27,6 +27,12 @@ FlipbookEngine is a modern, lightweight, and embeddable HTML flipbook viewer for
 - **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.
 
+## Backend text layers for image books
+
+WebP/JPEG books can consume persistent text extracted by the host backend. Supply optional `textLayerProvider(pageIndex, signal)` alongside `searchProvider`. The reader loads at most the current page and its neighbors, validates normalized run coordinates, and overlays transparent selectable text without downloading the PDF. Enable **More actions > Select text**, or call `setTextSelection(true)`; Escape returns to navigation mode. Pointer selection is isolated from flip gestures and note long-press. Toolbar/keyboard page navigation stays available.
+
+Extraction, OCR, indexing, authorization and persistence belong to the host, not the browser. A text layer is fixed-layout accessibility/selection data, not EPUB reflow. See [backend text layer contract](docs/backend-text-layers.md) and [API reference](docs/api-reference.md). These APIs are available from npm 1.0.2.
+
 ## Installation
 
 Install via npm:
@@ -75,7 +81,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@1.0.0/dist/flipbook-engine.css" />
+<link rel="stylesheet" href="https://unpkg.com/flipbookengine@1.0.3/dist/flipbook-engine.css" />
 <div id="viewer" style="width: 100%; height: 600px;"></div>
 
 <script type="importmap">
@@ -86,7 +92,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@1.0.0/dist/flipbook-engine.js';
+  import { FlipbookEngine } from 'https://unpkg.com/flipbookengine@1.0.3/dist/flipbook-engine.js';
 
   const engine = new FlipbookEngine('#viewer', {
     pdfWorkerSrc: 'https://unpkg.com/pdfjs-dist@5.4.530/build/pdf.worker.min.mjs'
@@ -419,5 +425,5 @@ Host uygulamaları, kullanıcı notunu sayfa üzerindeki normalize koordinata ba
 const engine = new FlipbookEngine('#viewer', {
   annotations: [{ id: 'note-1', pageIndex: 4, x: .42, y: .36, text: 'Review pricing' }]
 });
-```
-
+```
+

package/dist/components/AnnotationPlacement.d.ts

@@ -0,0 +1,5 @@
+import { FlipbookStore } from '../state/store';
+
+export declare function AnnotationPlacement(props: {
+    store: FlipbookStore;
+}): import('@serenity-is/domwise').JSXElement;

package/dist/components/AnnotationPopover.d.ts

@@ -0,0 +1,10 @@
+import { FlipbookAnnotation } from '../model/annotations';
+import { FlipbookStore } from '../state/store';
+
+export declare function AnnotationPopover(props: {
+    store: FlipbookStore;
+    signal: AbortSignal;
+    onSave: (note: FlipbookAnnotation) => Promise<boolean>;
+    onDelete: (note: FlipbookAnnotation) => Promise<boolean>;
+    onClose: () => void;
+}): import('@serenity-is/domwise').JSXElement;

package/dist/components/App.d.ts

@@ -1,3 +1,4 @@
+import { FlipbookNoteDocument } from '../model/note-editor';
 import { FlipbookSearchOptions } from '../model/search';
 import { FlipbookHotspot } from '../model/hotspots';
 import { FlipbookAnnotation } from '../model/annotations';
@@ -21,8 +22,13 @@ interface AppProps {
     onShare: () => void;
     onToggleBookmark: () => void;
     onToggleNotes: () => void;
-    onSaveNote: (note: string) => void;
-    onClearNote: () => void;
+    onSelectNote: (pageIndex: number) => void;
+    onBeginAnnotation: () => void;
+    onPlaceAnnotation: (pageIndex: number, x: number, y: number) => void;
+    onSaveAnnotation: (annotation: FlipbookAnnotation) => Promise<boolean>;
+    onDeleteAnnotation: (annotation: FlipbookAnnotation) => Promise<boolean>;
+    onSaveNote: (note: string, document?: FlipbookNoteDocument) => Promise<boolean>;
+    onClearNote: () => Promise<boolean>;
     onCloseNotes: () => void;
     onSearch: (query: string, options?: FlipbookSearchOptions) => void;
     onClearSearch: () => void;
@@ -35,6 +41,7 @@ interface AppProps {
     onToggleFullscreen: () => void;
     store: FlipbookStore;
     pluginRegistry?: FlipbookPluginRegistry;
+    signal: AbortSignal;
 }
 export declare function App(props: AppProps): import('@serenity-is/domwise').JSXElement;
 export {};

package/dist/components/NoteEditor.d.ts

@@ -0,0 +1,13 @@
+import { FlipbookNoteEditor, FlipbookNoteEditorFactory, FlipbookNoteValue } from '../model/note-editor';
+
+export declare function NoteEditor(props: {
+    value: FlipbookNoteValue;
+    factory?: FlipbookNoteEditorFactory;
+    signal: AbortSignal;
+    label: string;
+    view: {
+        current: FlipbookNoteEditor | null;
+    };
+    onReady: (ready: boolean) => void;
+    onDraft?: (value: FlipbookNoteValue) => void;
+}): HTMLDivElement;

package/dist/components/NotePlacementLayer.d.ts

@@ -0,0 +1,11 @@
+import { FlipbookStore } from '../state/store';
+
+type Place = (page: number, x: number, y: number) => void;
+export declare function NotePlacementLayer(props: {
+    store: FlipbookStore;
+    pageIndex: number;
+    onPlace: Place;
+}): import('@serenity-is/domwise').JSXElement;
+/** Long press tolerates small finger movement; dragging/pinching always cancels it. */
+export declare function bindNoteGestures(element: HTMLElement, store: FlipbookStore, place: Place, signal: AbortSignal): void;
+export {};

package/dist/components/NotesPanel.d.ts

@@ -1,14 +1,17 @@
 import { FlipbookStore } from '../state/store';
+import { FlipbookAnnotation } from '../model/annotations';
+import { FlipbookNoteDocument } from '../model/note-editor';
 
 interface NotesPanelProps {
     store: FlipbookStore;
-    onSave: (note: string) => void;
-    onClear: () => void;
+    onSave: (note: string, document?: FlipbookNoteDocument) => Promise<boolean>;
+    onClear: () => Promise<boolean>;
     onClose: () => void;
+    onSelect: (pageIndex: number) => void;
+    onAnnotation: (annotation: FlipbookAnnotation) => void;
+    onAdd: () => void;
+    signal: AbortSignal;
 }
-/**
- * Page-level note UI. Persistence remains host-owned through the engine API and
- * noteChange event; the panel intentionally does not know about a backend.
- */
+/** The editor keeps its draft until the host confirms persistence. */
 export declare function NotesPanel(props: NotesPanelProps): import('@serenity-is/domwise').JSXElement;
 export {};

package/dist/components/ReaderHelp.d.ts

@@ -0,0 +1,3 @@
+import { FlipbookStore } from '../state/store';
+
+export declare function showReaderHelp(root: HTMLElement, store: FlipbookStore): void;

package/dist/components/ReaderShortcuts.d.ts

@@ -0,0 +1,16 @@
+import { FlipbookStore } from '../state/store';
+import { InteractionManager } from '../core/InteractionManager';
+import { PageFlipAdapter } from '../adapters/PageFlipAdapter';
+
+export declare function ReaderShortcuts(root: HTMLElement, store: FlipbookStore, commands: {
+    pageFlipAdapterRef: {
+        current: PageFlipAdapter | null;
+    };
+    interactionManagerRef: {
+        current: InteractionManager | null;
+    };
+    onBeginAnnotation: () => void;
+    onToggleNotes: () => void;
+    onToggleFullscreen: () => void;
+    onAnnotationClose: () => void;
+}, signal: AbortSignal): void;

package/dist/components/TableOfContents.d.ts

@@ -1,6 +1,7 @@
 import { FlipbookStore } from '../state/store';
 
 interface TableOfContentsProps {
+    onClose?: () => void;
     store: FlipbookStore;
     onEntryClick: (pageIndex: number) => void;
 }

package/dist/components/TextLayer.d.ts

@@ -0,0 +1,8 @@
+import { FlipbookStore } from '../state/store';
+
+/** Transparent text is loaded independently of the PDF and page image resolution. */
+export declare function TextLayer(props: {
+    store: FlipbookStore;
+    pageIndex: number;
+    signal: AbortSignal;
+}): import('@serenity-is/domwise').JSXElement;

package/dist/components/Toolbar.d.ts

@@ -20,5 +20,5 @@ interface ToolbarProps {
     onToggleFullscreen: () => void;
     pluginRegistry?: FlipbookPluginRegistry;
 }
-export declare function Toolbar(props: ToolbarProps): import('@serenity-is/domwise').JSXElement;
+export declare function Toolbar(props: ToolbarProps): HTMLElement;
 export {};

package/dist/components/ToolbarMore.d.ts

@@ -0,0 +1,6 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { FlipbookMessages } from '../i18n/service';
+import { FlipbookStore } from '../state/store';
+
+/** Secondary commands retain their original handlers and reactive icons. */
+export declare function attachToolbarMore(toolbar: HTMLElement, messages: ReadonlySignal<FlipbookMessages>, store: FlipbookStore): void;

package/dist/components/Viewer.d.ts

@@ -11,6 +11,8 @@ interface ViewerProps {
     onHotspotClose: () => void;
     onAnnotationActivate: (annotation: FlipbookAnnotation) => void;
     onAnnotationClose: () => void;
+    onPlaceAnnotation: (pageIndex: number, x: number, y: number) => void;
+    signal: AbortSignal;
 }
 export declare function Viewer(props: ViewerProps): import('@serenity-is/domwise').JSXElement;
 export {};

package/dist/core/TextLayerLoader.d.ts

@@ -0,0 +1,5 @@
+import { FlipbookStore } from '../state/store';
+import { FlipbookTextLayerProvider } from '../model/text-layer';
+
+/** At most three visible/adjacent pages; stale requests cannot update a new session. */
+export declare function loadTextLayers(store: FlipbookStore, provider: FlipbookTextLayerProvider, lifetime: AbortSignal): () => void;

package/dist/core/domSignal.d.ts

@@ -0,0 +1,2 @@
+/** DOM event listeners require the AbortSignal from their own document realm. */
+export declare function domSignal(element: HTMLElement, session: AbortSignal): AbortSignal;

package/dist/core-entry.d.ts

@@ -11,3 +11,4 @@ export type { FlipbookThemeMode, FlipbookBackgroundStyle, FlipbookBackgrounds }
 export type { PdfPageMode, PdfPageLayout } from './core/PdfRenderer';
 export { isA3Landscape } from './core/PdfRenderer';
 export type { FlipbookHotspot, FlipbookHotspotKind, FlipbookHotspotMedia, FlipbookHotspotMediaType, FlipbookHotspotGalleryItem } from './model/hotspots';
+export type { FlipbookTextRun, FlipbookTextPage, FlipbookTextLayerProvider } from './model/text-layer';