When exiting panel mode, now properly resets:
- Remove zoom attribute to clear any zoom state
- Scroll to top position to reset viewport
This ensures a clean state when transitioning back to regular reading mode.
- Add 'unsafe-eval' to Content-Security-Policy script-src directive
to support dynamic module evaluation required by ES modules
- Standardize HTML formatting:
- Use lowercase doctype declaration
- Use double quotes consistently
- Improve indentation for readability
- Format CSS properties (box-shadow, transition) across multiple lines
- Close void elements with / for consistency
The CSP change is necessary for the ES module system to function
correctly in the browser environment.
- Add #model private field to cache loaded model instance
- Properly await model.load() before using the model
- Pass cached model to detection function instead of global reference
- Add model cleanup in clear() method to release resources
This prevents redundant model loading and ensures the model is fully
initialized before use, improving performance and reliability of ML-based
panel detection.
Changed contours from cv.Mat to cv.MatVector to match OpenCV.js API
requirements. The findContours method expects a MatVector for contour
storage, not a single Mat object. This fixes a potential runtime error
when using OpenCV-based panel detection.
Set up build system to automatically download and copy ML/CV libraries
during npm run build, eliminating manual file management.
Changes to package.json:
- Add devDependencies:
* @techstark/opencv-js: OpenCV.js for edge detection
* @tensorflow-models/coco-ssd: ML model for panel detection
* @rollup/plugin-terser: Minification plugin (already used)
Changes to rollup.config.js:
- Add custom downloadTensorFlow plugin:
* Downloads TensorFlow UMD build from unpkg.com during build
* Saves to vendor/tfjs/tf.min.js (1.5MB)
* Only runs during build, not in watch mode
- Add copy plugins for ML/CV libraries:
* Copy OpenCV.js from node_modules to vendor/opencv/opencv.js
* Copy COCO-SSD from node_modules to vendor/coco-ssd/coco-ssd.min.js
This automated approach ensures:
1. All vendored libraries are updated when npm install is run
2. No manual file downloads or copy operations needed
3. Reproducible builds across different environments
4. Version tracking via package.json
Build workflow: npm install → npm run build → all ML/CV libraries ready
Add machine learning and computer vision libraries to vendor/ directory
to support panel detection feature. Following foliate-js's existing pattern
of vendoring large dependencies (similar to pdf.js at 13MB).
Vendored libraries (~12.5MB):
- vendor/tfjs/tf.min.js (1.5MB): TensorFlow.js UMD build
* Downloaded from unpkg.com during build via custom Rollup plugin
* Required runtime for COCO-SSD model
- vendor/opencv/opencv.js (~11MB): OpenCV.js UMD build
* Copied from @techstark/opencv-js npm package
* Provides edge detection and image processing
* Requires 'unsafe-eval' CSP directive due to eval() usage
- vendor/coco-ssd/coco-ssd.min.js (~9KB): COCO-SSD model
* Copied from @tensorflow-models/coco-ssd npm package
* Pre-trained object detection for irregular panel layouts
Total vendor size: ~25MB (was 13MB, added 12.5MB)
These UMD/global builds ensure browser compatibility without requiring
ES module imports, which would cause bare specifier errors in browsers.
All libraries are loaded dynamically via script injection when panel
detection is first used, minimizing initial load time.
Implement intelligent panel detection for manga/comics using a three-tier
fallback system that automatically selects the best detection method:
- Tier 1: OpenCV edge detection (fast, accurate for clear panel borders)
- Tier 2: COCO-SSD ML detection (handles irregular layouts)
- Tier 3: Grid-based detection (lightweight, always works)
The system automatically falls back through tiers if higher tiers fail
or if CSP blocks 'unsafe-eval' required by ML libraries.
Changes:
- panel-detection/detector.js: Modified to use dynamic script loading
* Calls loadMLLibraries() on first use for lazy loading
* Checks if ML libraries loaded successfully before using them
* Falls back to grid detection if CSP blocks eval or libraries fail
* Uses globalThis.cv/tf/cocoSsd for UMD/global library access
- panel-detection/load-scripts.js: Created dynamic script loader
* Dynamically injects <script> tags when panel detection enabled
* Checks CSP compatibility with canUseEval() function
* Loads libraries in correct order: TensorFlow → OpenCV → COCO-SSD
* Falls back to grid if ML libraries fail to load
* Uses Promise-based API for clean async loading
This library-native approach keeps all functionality within foliate-js
without requiring changes to reader.html or consumer applications.
Move OpenCV, TensorFlow.js, and COCO-SSD from optionalDependencies
to devDependencies. These libraries are now bundled into the vendor
directory during build instead of being optional runtime dependencies.
Also upgrade @rollup/plugin-terser from 0.4.4 to 1.0.0 which
requires Node.js 20+ and includes updated dependencies.
Related changes:
- Move @techstark/opencv-js to devDependencies
- Move @tensorflow/tfjs to devDependencies
- Move @tensorflow-models/coco-ssd to devDependencies
- Update @rollup/plugin-terser to 1.0.0
Update PanelDetector to load OpenCV, TensorFlow.js, and COCO-SSD
from local vendor directory instead of importing npm packages.
This ensures the libraries are available after build and avoids
runtime dependency resolution issues.
- Change imports to use ../vendor paths instead of npm packages
- Add caching to prevent reloading libraries
- Add error handling for failed library loads with console warnings
- Update OpenCV loading to handle both default and named exports
Add pre-built panel detection libraries to vendor directory.
These are copied from node_modules during the build process and
included with the application for panel detection functionality.
Included libraries:
- vendor/opencv/opencv.js - OpenCV.js for image processing
- vendor/tfjs/tf.min.js - TensorFlow.js for ML inference
- vendor/coco-ssd/coco-ssd.min.js - COCO-SSD model for object detection
These files enable the panel mode feature in the reader.
Update rollup config to copy OpenCV, TensorFlow.js, and COCO-SSD
libraries to vendor directory. These dependencies are used for the
panel detection feature and need to be bundled with the application
instead of loaded from npm packages at runtime.
- Add copyOpenCV() plugin to copy OpenCV.js from node_modules
- Add copyTensorFlow() plugin to copy TensorFlow.js from node_modules
- Add copyCocoSsd() plugin to copy COCO-SSD model from node_modules
- Apply formatting consistency (double quotes for imports)
Fix npm install errors and make ML/CV libraries truly optional.
Changes:
- Move dependencies from "dependencies" to "optionalDependencies"
- Fix @techstark/opencv-js version from "^4.12.0" to "4.12.0-release.1"
- The caret syntax (^) doesn't work with suffix versions like -release.1
- Use exact version match instead
Why optionalDependencies:
- Installation won't fail if these packages fail to install
- Users can opt-out with: npm install foliate-js --omit=optional
- Maintains the library's "no hard dependencies" philosophy
- Graceful degradation: panel detection falls back to grid-only mode
Behavior:
- Default: npm attempts to install OpenCV, TensorFlow, COCO-SSD (~4.5MB)
- With --omit=optional: skips heavy ML/CV libraries
- Either way: library works, panel detection gracefully adapts
This resolves npm install errors where "^4.12.0" couldn't be found
because the actual version is "4.12.0-release.1".
Document the new panel detection feature for manga and comics,
including installation options and usage examples.
Changes to README.md:
- Added "Optional panel detection for manga and comics" to Features list
- Added new "Panel Detection" section after "PDF and Other Fixed-Layout Formats"
- Documented the optionalDependencies approach and --omit=optional flag
- Explained the multi-tier fallback system (OpenCV → ML → Grid)
- Provided code examples for enabling panel mode and navigation
- Documented keyboard shortcuts (P, Arrow keys, Escape)
- Clarified graceful degradation when dependencies are missing
The documentation follows existing README patterns:
- Concise technical style
- Code examples with proper syntax
- Clear installation instructions
- Explanation of feature behavior and fallbacks
This helps users understand:
1. What panel detection is and when it's useful
2. How to install with or without the feature
3. How to use the API in their applications
4. What happens when optional dependencies aren't installed
Add a checkbox menu item to the demo reader's settings menu that
allows users to toggle panel detection mode on or off.
Implementation details:
- Adds "Panel Mode" checkbox to existing settings menu
- Uses the createMenu API with type="checkbox"
- Safely checks for togglePanelMode method availability
- Checks current panel-mode state before toggling
- Properly enables/disables panel mode via attribute API
User-facing behavior:
- Click gear icon → settings menu appears
- Check/uncheck "Panel Mode" to enable/disable
- Works seamlessly with existing layout options
- Only active when viewing fixed-layout content
This change only affects the demo reader (reader.html + reader.js),
not the foliate-js library itself. The library's panel detection
API in fixed-layout.js remains unchanged.
The panel mode toggle provides easy access to the new panel
navigation features for testing and demonstration purposes.
Implement comprehensive panel-aware navigation for manga, comics,
and other fixed-layout content with automatic panel detection.
Core features:
- Panel mode toggle via 'panel-mode' attribute
- Touch gesture support (swipe, tap)
- Visual panel overlay with SVG highlighting
- Auto-zoom to center and fit each panel
- Seamless integration with existing page navigation
Panel detection integration:
- Initialize PanelDetector on component construction
- Detect panels when entering panel mode
- Cache detection results per page
- Support re-detection via force flag
Panel navigation:
- nextPanel(): advance to next panel, wrapping to next page
- prevPanel(): go to previous panel, wrapping to previous page
- Auto-enter panel mode on first panel navigation
- Visual feedback with current panel highlighting
Touch support (previously missing from fixed-layout):
- touchstart: record initial position and timestamp
- touchmove: prevent default for significant movement
- touchend: velocity-based swipe detection
- Panel mode: tap to toggle overlay, swipe to navigate
Visual overlay:
- SVG rectangles showing detected panels
- Highlight current panel in orange (#ff6b35)
- Dim other panels in semi-transparent white
- Pointer-events none for non-blocking overlay
Zoom behavior:
- Calculate scale to fit panel within viewport
- Center panel with scroll positioning
- Apply via existing zoom attribute mechanism
- Re-render overlay after zoom
Internal methods:
- #nextPage() / #prevPage(): bypass panel-mode check
- #enterPanelMode() / #exitPanelMode(): mode management
- #showPanelOverlay() / #hidePanelOverlay(): overlay management
- #zoomToPanel(): auto-center and scale to panel
- #addTouchSupport(): attach touch event listeners
- #onTouchStart/Move/End: touch gesture handling
- #handlePanelTouch: panel-mode specific touch logic
Public API:
- panelCount: number of detected panels
- currentPanelIndex: current panel index
- togglePanelMode(): enter/exit panel mode
Observer attributes:
- 'zoom': existing zoom support
- 'panel-mode': new panel mode attribute
This implementation brings fixed-layout renderer to feature parity
with paginator.js regarding touch support while adding unique
panel-aware navigation capabilities.
Extend keyboard navigation to support panel mode when enabled.
Changes:
- Check for panel-mode attribute before routing key events
- Route Arrow keys and Vim keys (h/l) to panel navigation in panel mode
- Add 'P' key to toggle panel mode
- Add 'Escape' key to exit panel mode
- Maintain backward compatibility with existing page navigation
When panel mode is active:
- ArrowRight/l: next panel
- ArrowLeft/h: previous panel
- Escape/P: exit panel mode
When panel mode is inactive:
- ArrowRight/l: next page (existing behavior)
- ArrowLeft/h: previous page (existing behavior)
- P: enter panel mode (new feature)
Implement a comprehensive panel detection system for manga and comics
with automatic fallback chain for maximum compatibility.
Core detector (detector.js):
- PanelDetector class with in-memory caching
- Lazy-loading of OpenCV and TensorFlow.js
- Validation logic to filter poor detections
- Cache management to avoid re-detection
OpenCV edge detection (opencv.js):
- Canny edge detection for panel boundaries
- Contour finding with bounding box extraction
- Size and aspect ratio filtering
- Reading order sorting (top-to-bottom, left-to-right)
ML-based detection (coco-ssd.js):
- COCO-SSD pre-trained model integration
- Object detection for irregular panel layouts
- Rectangular filtering for panel-like regions
- Handles edge cases where edge detection fails
Grid-based fallback (grid.js):
- Lightweight 3x3 grid detection
- Empty cell detection via alpha channel analysis
- Adjacent panel merging algorithm
- Always works as final fallback
The detection pipeline tries OpenCV first (fast, accurate),
falls back to ML detection if validation fails,
and uses grid detection as ultimate baseline.
john-okeefe