flipbookengine 0.6.0 → 1.0.0

package/docs/migration-1.0.0.md

@@ -0,0 +1,59 @@
+# 1.0.0 migration guide
+
+FlipbookEngine 1.0.0 is the first stable open-source release. The 0.x line was
+alpha/beta and does not provide a compatibility guarantee. Test the viewer and
+wrapper integrations against the new package before deploying.
+
+## Plugin entry points
+
+The all-in-one import remains available:
+
+```ts
+import { FlipbookEngine } from 'flipbookengine';
+```
+
+Optional feature adapters can be loaded independently:
+
+```ts
+import { FlipbookEngine } from 'flipbookengine/core';
+import { notesPlugin } from 'flipbookengine/plugins/notes';
+
+const engine = new FlipbookEngine('#viewer', { plugins: [notesPlugin] });
+```
+
+Available adapters are documented in [plugin architecture](./plugin-architecture.md).
+The official OSS package does not include analytics, OCR, PDF outline extraction,
+protected downloads, or backend rendering.
+
+## TOC and iframe API
+
+TOC is supplied as a host-provided `FlipbookTocEntry[]` manifest. Use
+`engine.getToc()` and `engine.setToc(entries, show?)` for runtime updates. Iframe
+controllers additionally expose `getToc()` and `setToc()` through the validated
+postMessage bridge.
+
+## Wrapper validation
+
+React and Vue wrappers continue to accept the engine options object, including
+`plugins`. Validate wrapper lifecycle, CSS import, PDF worker configuration, and
+host-managed note/bookmark persistence during migration.
+
+## 0.8.0 to 1.0.0 differences
+
+The 1.0.0 release is the first compatibility boundary. The 0.x line was alpha/beta, so applications must validate the complete integration instead of assuming semver compatibility.
+
+| Area | 0.8.0 | 1.0.0 | Migration impact |
+| --- | --- | --- | --- |
+| Package surface | All-in-one public entry | All-in-one plus core, plugins, and feature subpaths | Imports from documented public paths are supported; imports from internal src/dist files are breaking and must be replaced. |
+| Optional features | Built-in reader surface only | Plugin contract with install/uninstall, typed events, toolbar/panel/API contributions | If an application wants an adapter API, register the adapter explicitly; omitted adapters are inactive. |
+| TOC | Host-provided TOC panel | Nested TOC plus getToc/setToc and iframe commands | Existing TOC data remains host-provided; update integrations that need runtime or embed control. |
+| Hotspots | Basic text/link overlays | info/media/gallery/commerce, image/video/audio previews, galleries, product links | Existing overlays remain valid; new media/gallery fields are additive. |
+| Image mode search | Disabled for raster page lists | Still disabled; PDF mode only | No change; raster search requires host/server text metadata. |
+| Commercial capabilities | Not part of OSS | Still not part of OSS | Backend rendering, OCR/indexing, protected downloads, persistence, identity, and analytics remain commercial/backend work. |
+
+### Breaking-change requirements
+
+- Do not depend on undocumented internal modules, generated chunk filenames, or 0.x implementation details.
+- Re-run wrapper and iframe smoke tests after upgrading; React and Vue wrappers must be rebuilt against the 1.0.0 declarations.
+- Treat plugin registration as explicit state. Calling uninstallPlugin removes APIs, UI contributions, event listeners, and cleanup callbacks; it does not merely hide a button.
+- Existing all-in-one initialization with documented options is retained, but the 0.x line has no compatibility guarantee and must not be used as a rollback contract.

package/docs/plugin-architecture.md

@@ -0,0 +1,103 @@
+# Plugin architecture
+
+FlipbookEngine v1 exposes a small plugin contract so optional reader features can
+be distributed independently from the rendering core. Plugins are installed
+before the first render through `plugins` or `engine.installPlugin(plugin)`.
+
+```ts
+import { FlipbookEngine } from 'flipbookengine/core';
+import type { FlipbookPlugin } from 'flipbookengine/plugins';
+
+const tocPlugin: FlipbookPlugin = {
+  name: 'toc',
+  install(engine, context) {
+    context.registerToolbarButton({
+      id: 'toc',
+      label: 'Contents',
+      icon: '☰',
+      onClick: () => context.openPanel('contents')
+    });
+
+    context.registerPanel({
+      id: 'contents',
+      title: 'Table of contents',
+      render: (container) => {
+        container.textContent = `Page ${engine.getCurrentPage() + 1}`;
+      }
+    });
+
+    context.registerApi('getCurrentSection', () => engine.getCurrentPage());
+    return () => context.closePanel('contents');
+  }
+};
+
+const engine = new FlipbookEngine('#viewer', { plugins: [tocPlugin] });
+```
+
+The context provides:
+
+- `registerToolbarButton()` for a framework-agnostic toolbar action.
+- `registerPanel()` for a panel mounted inside the viewer shell.
+- `registerApi()` and `engine.callPluginApi()` for namespaced plugin methods.
+- `on()` for typed engine event subscriptions with automatic cleanup.
+- `openPanel()` / `closePanel()` for panel state.
+
+Plugin names and contribution identifiers must be unique within an engine.
+Calling `engine.destroy()` removes all plugin registrations and runs cleanup
+callbacks. A plugin installed after initialization is available on the next
+viewer render; install initial plugins in the constructor options when their UI
+must be present on the first render.
+
+For example, a host that only needs note persistence can load the notes adapter
+without importing the other feature adapters:
+
+```ts
+import { FlipbookEngine } from 'flipbookengine/core';
+import { notesPlugin } from 'flipbookengine/plugins/notes';
+
+const engine = new FlipbookEngine('#viewer', { plugins: [notesPlugin] });
+await engine.callPluginApi('notes', 'set', 0, 'Review this page');
+```
+
+Official lightweight adapters are available as independent entry points:
+
+- `flipbookengine/plugins/notes`
+- `flipbookengine/plugins/bookmarks`
+- `flipbookengine/plugins/toc`
+- `flipbookengine/plugins/search`
+- `flipbookengine/plugins/annotations`
+- `flipbookengine/plugins/hotspots`
+- `flipbookengine/plugins/share`
+- `flipbookengine/plugins/deep-link`
+
+Each adapter registers namespaced APIs over the existing host-managed engine
+methods. The all-in-one entry remains unchanged, so applications can migrate
+incrementally without loading an adapter they do not use.
+
+The public `flipbookengine` entry remains the all-in-one build. `flipbookengine/core`
+contains the core engine exports, `flipbookengine/plugins` contains the plugin
+contract, and the feature subpaths above contain the optional adapters. Analytics is intentionally not an official
+open-source plugin; applications may consume events directly or use a private
+commercial adapter.
+
+
+## Activating and deactivating plugins
+
+Pass adapters in the constructor to activate them before the first render:
+
+```ts
+import { FlipbookEngine } from 'flipbookengine/core';
+import { hotspotsPlugin } from 'flipbookengine/plugins/hotspots';
+
+const engine = new FlipbookEngine('#viewer', { plugins: [hotspotsPlugin] });
+```
+
+A plugin can also be enabled or disabled after initialization. installPlugin returns the engine instance; uninstallPlugin returns true when a plugin was removed and clears all registered contributions.
+
+```ts
+engine.uninstallPlugin('hotspots');
+engine.installPlugin(hotspotsPlugin);
+await engine.callPluginApi('hotspots', 'activate', 'product-42');
+```
+
+Feature adapters are API-only contributions. The built-in all-in-one viewer continues to render its existing toolbar and panels from the corresponding options; custom plugins can add their own UI contributions with registerToolbarButton and registerPanel.

package/docs/release-checklist.md

@@ -0,0 +1,37 @@
+# Release Checklist
+
+Use this checklist for every phase commit and every published release.
+
+## Before committing a phase
+
+- [ ] Confirm the change scope and choose the correct SemVer impact (patch, minor, or major).
+- [ ] Keep each coherent phase in a separate commit with an action-oriented message.
+- [ ] Add or update tests for every new feature, API, bug fix, and changed behavior.
+- [ ] Run the relevant focused tests and record results in the local `development-notes/` report.
+- [ ] Confirm no local audit reports, build output, credentials, or environment files are staged.
+- [ ] Review `git diff --check` and the staged diff.
+
+## Before a release
+
+- [ ] Update the version in `package.json` and `package-lock.json`.
+- [ ] Update every published version reference in README files, CHANGELOG, API documentation, migration guides, examples, and license/source headers.
+- [ ] Add a CHANGELOG entry describing features, fixes, API changes, and test coverage.
+- [ ] Document every new or changed API in the API reference and README examples.
+- [ ] Mark all breaking changes explicitly, explain the impact, and provide migration guidance.
+- [ ] Verify wrapper exports, generated declarations, package entry points, and framework integrations.
+- [ ] Run `npm run typecheck`, `npm test`, `npm run build`, and `npm run pack:check`.
+- [ ] Confirm `npm pkg get version` matches the intended release.
+- [ ] Inspect the `npm pack --dry-run` file list and package size.
+- [ ] Confirm both local repositories have clean working trees and the intended commits are on the correct branches.
+- [ ] Create and push the matching Git tag (for example, `v1.0.0`).
+- [ ] Create or update the GitHub Release from that tag and verify the Latest designation.
+- [ ] Push commits and tags before handing off the manual npm publish step.
+- [ ] Publish to npm manually with maintainer credentials; verify the registry version afterward.
+- [ ] Record all commands, results, release URLs, and follow-up items in local `development-notes/`.
+
+## After publishing
+
+- [ ] Verify the npm package page, tarball version, README, and package contents.
+- [ ] Verify GitHub tag/release and the default branch point to the same release commit.
+- [ ] Check that no deprecated or unreleased version is shown as Latest.
+- [ ] Note any known warnings (for example, network/DNS or jsdom media warnings) separately from failures.

package/docs/theming.md

@@ -0,0 +1,61 @@
+# Theming & Customization
+
+FlipbookEngine provides deep customization support through compiled CSS custom properties (variables) and dark-mode compatibility.
+
+## CSS Custom Properties
+
+The styling system is driven by standard CSS variables. You can override these variables globally in your stylesheet or per-instance:
+
+```css
+:root {
+  --mainbgcolor: #f3f6fb;          /* Main canvas background */
+  --surfacebgcolor: #ffffff;       /* Overlay elements background */
+  --panelbgcolor: #172033;         /* Settings panel background */
+  --flipbook-accent: #7367f0;          /* Buttons and accent color */
+  --thumbrailbgcolor: #0f172a;     /* Thumbnails container background */
+  --bordercolor: #e2e8f0;          /* Border and separations color */
+  --textcolor: #1e293b;            /* General text color */
+}
+```
+
+## Dark Mode
+
+FlipbookEngine is compatible with Bootstrap 5 setups and automatically responds to light/dark themes in the hosting environment.
+
+- It queries `data-bs-theme="dark"` on the body/parent element to toggle styling.
+- You can force dark theme on initialization:
+  ```javascript
+  const engine = new FlipbookEngine('#viewer', {
+    theme: 'dark'
+  });
+  ```
+
+## Instance Overrides
+
+To style a single instance differently from the rest of your app, pass the `cssVariables` object to options:
+
+```javascript
+const engine = new FlipbookEngine('#viewer', {
+  cssVariables: {
+    mainbgcolor: '#0f172a',
+    flipbook-accent: '#10b981'
+  }
+});
+```
+
+
+## Optional Light/Dark Viewer Backgrounds
+
+A host can provide separate, optional backgrounds for the viewer surface. The default is null, so the built-in theme surfaces remain unchanged. Backgrounds are applied outside the PDF pages and automatically follow the selected light, dark, or auto theme.
+
+```ts
+const engine = new FlipbookEngine('#viewer', {
+  theme: 'auto',
+  background: {
+    light: { color: '#f8fafc', image: '/branding/catalog-light.webp', size: 'cover', position: 'center', repeat: 'no-repeat' },
+    dark: { color: '#0f172a', image: '/branding/catalog-dark.webp', size: 'cover' }
+  }
+});
+```
+
+The viewer reserves a bottom attribution area and uses equal responsive page gutters so the watermark does not overlap PDF content. Thumbnail rail scrolling is horizontal-only; thumbnail dimensions are reduced responsively to avoid vertical overflow.

package/package.json

@@ -1,114 +1,165 @@
-{
-  "name": "flipbookengine",
-  "version": "0.6.0",
-  "description": "A modern, embeddable HTML flipbook engine for PDF-backed catalogs and digital publications.",
-  "private": false,
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build && vite build --config vite.config.iife.js",
-    "test": "tsx --loader ./tests/css-loader.js --test tests/*.test.ts",
-    "test:e2e": "playwright test",
-    "typecheck": "tsc --noEmit",
-    "clean": "rimraf dist",
-    "pack:check": "npm pack --dry-run",
-    "audit:deps": "npm audit --omit=dev --audit-level=high",
-    "release:verify": "npm run typecheck && npm test && npm run build && npm run audit:deps && npm run pack:check"
-  },
-  "keywords": [
-    "flipbook",
-    "catalog",
-    "pdf",
-    "viewer",
-    "publication",
-    "pageflip",
-    "digital-catalog",
-    "page-flip",
-    "typescript"
-  ],
-  "author": "Murat Dogan",
-  "license": "AGPL-3.0-or-later",
-  "homepage": "https://flipbookengine.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Bizeka/flipbook-engine.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Bizeka/flipbook-engine/issues"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "sideEffects": [
-    "**/*.css"
-  ],
-  "files": [
-    "dist",
-    "react",
-    "vue",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md",
-    "COMMERCIAL_LICENSE.md",
-    "TRADEMARK_POLICY.md",
-    "THIRD-PARTY-NOTICES.md"
-  ],
-  "main": "./dist/flipbook-engine.js",
-  "module": "./dist/flipbook-engine.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/flipbook-engine.js",
-      "default": "./dist/flipbook-engine.js"
-    },
-    "./styles.css": {
-      "default": "./dist/flipbook-engine.css"
-    },
-    "./react": {
-      "types": "./dist/react/index.d.ts",
-      "import": "./dist/flipbook-engine.react.js",
-      "default": "./dist/flipbook-engine.react.js"
-    },
-    "./vue": {
-      "types": "./dist/vue/index.d.ts",
-      "import": "./dist/flipbook-engine.vue.js",
-      "default": "./dist/flipbook-engine.vue.js"
-    }
-  },
-  "peerDependencies": {
-    "react": ">=16.8.0",
-    "vue": ">=3.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    },
-    "vue": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.63.0",
-    "@types/jsdom": "^28.0.3",
-    "@types/node": "^25.0.10",
-    "@types/page-flip": "^2.0.4",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "jsdom": "^26.1.0",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "rimraf": "^6.0.0",
-    "tsx": "^4.22.4",
-    "typescript": "^5.0.0",
-    "vite": "^5.0.0",
-    "vite-plugin-dts": "^3.0.0",
-    "vue": "^3.5.34"
-  },
-  "type": "module",
-  "dependencies": {
-    "@preact/signals-core": "^1.14.3",
-    "@serenity-is/domwise": "^10.2.3",
-    "page-flip": "^2.0.7",
-    "pdfjs-dist": "^5.4.530"
-  }
-}
+{
+  "name": "flipbookengine",
+  "version": "1.0.0",
+  "description": "A modern, embeddable HTML flipbook engine for PDF-backed catalogs and digital publications.",
+  "private": false,
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && vite build --config vite.config.iife.js",
+    "test": "tsx --loader ./tests/css-loader.js --test tests/*.test.ts",
+    "test:e2e": "playwright test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "pack:check": "npm pack --dry-run",
+    "audit:deps": "npm audit --omit=dev --audit-level=high",
+    "release:verify": "npm run typecheck && npm test && npm run build && npm run audit:deps && npm run pack:check"
+  },
+  "keywords": [
+    "flipbook",
+    "catalog",
+    "pdf",
+    "viewer",
+    "publication",
+    "pageflip",
+    "digital-catalog",
+    "page-flip",
+    "typescript"
+  ],
+  "author": "Murat Dogan",
+  "license": "AGPL-3.0-or-later",
+  "homepage": "https://flipbookengine.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bizeka/flipbook-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Bizeka/flipbook-engine/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "docs",
+    "react",
+    "vue",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "COMMERCIAL_LICENSE.md",
+    "TRADEMARK_POLICY.md",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "main": "./dist/flipbook-engine.js",
+  "module": "./dist/flipbook-engine.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/flipbook-engine.js",
+      "default": "./dist/flipbook-engine.js"
+    },
+    "./styles.css": {
+      "default": "./dist/flipbook-engine.css"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/flipbook-engine.react.js",
+      "default": "./dist/flipbook-engine.react.js"
+    },
+    "./vue": {
+      "types": "./dist/vue/index.d.ts",
+      "import": "./dist/flipbook-engine.vue.js",
+      "default": "./dist/flipbook-engine.vue.js"
+    },
+    "./core": {
+      "types": "./dist/core-entry.d.ts",
+      "import": "./dist/flipbook-engine.core.js",
+      "default": "./dist/flipbook-engine.core.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.ts",
+      "import": "./dist/flipbook-engine.plugins.js",
+      "default": "./dist/flipbook-engine.plugins.js"
+    },
+    "./plugins/notes": {
+      "types": "./dist/plugins-notes.d.ts",
+      "import": "./dist/flipbook-engine.plugins-notes.js",
+      "default": "./dist/flipbook-engine.plugins-notes.js"
+    },
+    "./plugins/bookmarks": {
+      "types": "./dist/plugins-bookmarks.d.ts",
+      "import": "./dist/flipbook-engine.plugins-bookmarks.js",
+      "default": "./dist/flipbook-engine.plugins-bookmarks.js"
+    },
+    "./plugins/toc": {
+      "types": "./dist/plugins-toc.d.ts",
+      "import": "./dist/flipbook-engine.plugins-toc.js",
+      "default": "./dist/flipbook-engine.plugins-toc.js"
+    },
+    "./plugins/search": {
+      "types": "./dist/plugins-search.d.ts",
+      "import": "./dist/flipbook-engine.plugins-search.js",
+      "default": "./dist/flipbook-engine.plugins-search.js"
+    },
+    "./plugins/annotations": {
+      "types": "./dist/plugins-annotations.d.ts",
+      "import": "./dist/flipbook-engine.plugins-annotations.js",
+      "default": "./dist/flipbook-engine.plugins-annotations.js"
+    },
+    "./plugins/hotspots": {
+      "types": "./dist/plugins-hotspots.d.ts",
+      "import": "./dist/flipbook-engine.plugins-hotspots.js",
+      "default": "./dist/flipbook-engine.plugins-hotspots.js"
+    },
+    "./plugins/share": {
+      "types": "./dist/plugins-share.d.ts",
+      "import": "./dist/flipbook-engine.plugins-share.js",
+      "default": "./dist/flipbook-engine.plugins-share.js"
+    },
+    "./plugins/deep-link": {
+      "types": "./dist/plugins-deep-link.d.ts",
+      "import": "./dist/flipbook-engine.plugins-deep-link.js",
+      "default": "./dist/flipbook-engine.plugins-deep-link.js"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "vue": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "@types/jsdom": "^28.0.3",
+    "@types/node": "^25.0.10",
+    "@types/page-flip": "^2.0.4",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^26.1.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "rimraf": "^6.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.0.0",
+    "vue": "^3.5.34"
+  },
+  "type": "module",
+  "dependencies": {
+    "@preact/signals-core": "^1.14.3",
+    "@serenity-is/domwise": "^10.2.3",
+    "page-flip": "^2.0.7",
+    "pdfjs-dist": "^5.4.530"
+  }
+}