From dc894c89ddefcd5d35d11066549336d9a2a14c52 Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Mon, 13 Apr 2026 17:00:33 -0400
Subject: [PATCH] Add panel detection documentation to README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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
---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/README.md b/README.md
index a3fe2d5..a932598 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,7 @@ Library for rendering e-books in the browser.
 
 Features:
 - Supports EPUB, MOBI, KF8 (AZW3), FB2, CBZ, PDF (experimental; requires PDF.js)
+- Optional panel detection for manga and comics (requires optional dependencies)
 - Add support for other formats yourself by implementing the book interface
 - Pure JavaScript
 - Small and modular
@@ -141,6 +142,53 @@ There is a proof-of-concept, highly experimental adapter for [PDF.js](https://mo
 
 CBZs are similarly handled like fixed-layout EPUBs.
 
+### Panel Detection
+
+The fixed-layout renderer includes an optional panel detection feature for manga, comics, and other fixed-layout content. When enabled, it automatically detects panel boundaries and allows for panel-by-panel navigation.
+
+This feature requires optional dependencies that are not installed by default:
+
+```bash
+# Install with panel detection (includes ~4.5MB of ML/CV libraries)
+npm install foliate-js
+
+# Install without panel detection (lightweight, uses grid-based fallback)
+npm install foliate-js --omit=optional
+```
+
+When panel detection is available, it uses a multi-tier fallback system:
+1. OpenCV edge detection (fast, accurate for clear panel borders)
+2. ML-based detection with COCO-SSD (handles irregular layouts)
+3. Grid-based detection (lightweight, always works)
+
+To use panel detection:
+
+```js
+const view = document.createElement('foliate-view')
+await view.open('manga.epub')
+
+// Check if renderer supports panel detection
+if (view.renderer.togglePanelMode) {
+    // Enable panel mode
+    view.renderer.togglePanelMode()
+    
+    // Navigate between panels
+    await view.renderer.nextPanel()
+    await view.renderer.prevPanel()
+    
+    // Get panel information
+    console.log(view.renderer.panelCount)        // number of panels
+    console.log(view.renderer.currentPanelIndex) // current panel
+}
+```
+
+Panel mode can also be toggled via keyboard shortcuts:
+- `P` to toggle panel mode on/off
+- Arrow keys or `h`/`l` to navigate panels when in panel mode
+- `Escape` to exit panel mode
+
+The renderer will gracefully fall back to grid-based detection if the optional dependencies are not available, so panel navigation will work regardless of whether the ML/CV libraries are installed.
+
 ### The Renderers
 
 To simplify things, it has two separate renderers, one for reflowable books, and one for fixed layout books (as such there's no support for mixed layout books). These renderers are custom elements (web components).