retold-remote 0.0.11 → 0.0.13

package/css/retold-remote.css

@@ -2026,14 +2026,48 @@ html, body
 	flex-shrink: 0;
 	background: var(--retold-bg-secondary);
 	border-right: 1px solid var(--retold-border);
-	overflow-y: auto;
+	display: flex;
+	flex-direction: column;
 	font-size: 0.78rem;
-	padding: 8px 0;
 }
 .retold-remote-ebook-toc.collapsed
 {
 	display: none;
 }
+.retold-remote-ebook-toc-header
+{
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	padding: 8px 12px;
+	border-bottom: 1px solid var(--retold-border);
+	color: var(--retold-text-secondary);
+	font-size: 0.72rem;
+	font-weight: 600;
+	text-transform: uppercase;
+	letter-spacing: 0.04em;
+	flex-shrink: 0;
+}
+.retold-remote-ebook-toc-close
+{
+	border: none;
+	background: none;
+	color: var(--retold-text-muted);
+	font-size: 1.1rem;
+	cursor: pointer;
+	padding: 0 4px;
+	line-height: 1;
+}
+.retold-remote-ebook-toc-close:hover
+{
+	color: var(--retold-text-primary);
+}
+.retold-remote-ebook-toc-items
+{
+	overflow-y: auto;
+	flex: 1;
+	padding: 4px 0;
+}
 .retold-remote-ebook-toc-item
 {
 	display: block;
@@ -2337,6 +2371,16 @@ html, body
 {
 	color: var(--retold-text-secondary);
 }
+.retold-remote-iex-tiling-status
+{
+	color: var(--retold-accent);
+	animation: retold-pulse 1.5s ease-in-out infinite;
+}
+@keyframes retold-pulse
+{
+	0%, 100% { opacity: 1; }
+	50% { opacity: 0.5; }
+}
 .retold-remote-iex-body
 {
 	flex: 1;

package/docs/README.md

@@ -41,9 +41,14 @@ Then open `http://localhost:8086` in a browser.
 |----------|----------|
 | [Server Setup and Docker](server-setup.md) | Installation, CLI options, environment variables, configuration, Docker |
 | [Image Viewer](image-viewer.md) | Fit modes, zoom, keyboard shortcuts, mouse interactions |
-| [Video Viewer](video-viewer.md) | Action menu, playback, frame explorer, timeline, VLC streaming |
-| [Audio Viewer](audio-viewer.md) | Waveform visualization, selection, zoom, segment playback |
+| [Video Viewer](video-viewer.md) | Action menu, in-browser playback, VLC streaming |
+| [Audio Viewer](audio-viewer.md) | HTML5 playback, autoplay, VLC streaming |
 | [eBook Reader](ebook-reader.md) | EPUB/MOBI support, table of contents, page navigation |
+| [Image Explorer](image-explorer.md) | Deep-zoom with OpenSeadragon, DZI tiling, coordinate display |
+| [Video Explorer](video-explorer.md) | Frame grid, timeline, range selection, clip extraction |
+| [Audio Explorer](audio-explorer.md) | Waveform visualization, selection, zoom, segment playback |
+| [Collections](collections.md) | Bookmarks, favorites, quick-add, item types, operation plans |
+| [File Metadata](metadata.md) | Info overlay, sidebar metadata, EXIF/GPS, ffprobe, explorer info bars |
 
 ## Keyboard Shortcuts (All Modes)
 

package/docs/_sidebar.md

@@ -5,6 +5,15 @@
 
 - Media Viewers
   - [Image Viewer](image-viewer.md)
-  - [Video Viewer & Explorer](video-viewer.md)
-  - [Audio Viewer & Explorer](audio-viewer.md)
+  - [Video Viewer](video-viewer.md)
+  - [Audio Viewer](audio-viewer.md)
   - [eBook Reader](ebook-reader.md)
+
+- Explorers
+  - [Image Explorer](image-explorer.md)
+  - [Video Explorer](video-explorer.md)
+  - [Audio Explorer](audio-explorer.md)
+
+- Features
+  - [Collections](collections.md)
+  - [File Metadata](metadata.md)

package/docs/audio-explorer.md

@@ -0,0 +1,120 @@
+# Audio Explorer
+
+The audio explorer displays a canvas-based waveform visualization of an audio file with zoom, selection, and segment extraction. Select a region of the waveform, play it back instantly, or save it to a collection as an audio clip. Requires ffmpeg on the server for waveform analysis and segment extraction.
+
+## Opening the Explorer
+
+- From the audio player, click "Explore Audio"
+- From the gallery (with an audio file selected), press `e`
+- From the media viewer, press `e` while viewing audio
+- URL updates to `#/explore-audio/{id}`
+
+Opening with a pre-existing selection (from a collection item, for example) highlights that range automatically.
+
+## Waveform Display
+
+### Main Canvas
+
+The main canvas shows a zoomed and pannable portion of the waveform. Peaks are drawn as vertical bars above and below a dashed center line, representing the amplitude at each point.
+
+- **Unselected regions** are drawn in the secondary text color
+- **Selected regions** are drawn in the accent color with a semi-transparent highlight
+- A **cursor line** follows the mouse position
+
+### Overview Bar
+
+Below the main canvas, a smaller overview canvas shows the entire audio file at a glance. A highlighted viewport indicator rectangle shows which portion is currently visible in the main canvas.
+
+Click anywhere on the overview bar to pan the main view to that position. The viewport indicator can also be dragged.
+
+## Time Display Bar
+
+A bar above the waveform shows three live-updating fields:
+
+| Field | Content | Example |
+|-------|---------|---------|
+| **View** | Time range currently visible | 0:12.3 - 0:45.7 |
+| **Selection** | Selected range and duration | 0:20.0 - 0:30.5 (10.5s) |
+| **Cursor** | Time position under the mouse | 0:25.8 |
+
+Timestamps are formatted as M:SS.D (minutes, seconds, tenths) or H:MM:SS.D for long files. When no selection exists, "None" is shown. When the cursor is outside the canvas, "--" is shown.
+
+## Info Bar
+
+| Field | Example |
+|-------|---------|
+| Duration | 3:42 |
+| Sample Rate | 44.1 kHz |
+| Channels | 2 (stereo) |
+| Codec | mp3 |
+| Bitrate | 320 kbps |
+| Size | 8.7 MB |
+| Peaks | 2000 (ffmpeg) |
+
+## Selection
+
+Click and drag on the main waveform to select a time range. The selection is highlighted in the accent color with vertical edge markers in both the main canvas and the overview bar.
+
+Selections smaller than approximately 1 millisecond are automatically cleared.
+
+### Controls
+
+| Button | Action |
+|--------|--------|
+| Play Selection | Extract and play the selected segment |
+| Clear | Remove the selection |
+| Save Segment | Add the selection as an audio clip to a collection |
+
+## Zoom
+
+| Key / Action | Effect |
+|--------------|--------|
+| `+` or `=` | Zoom in (halves visible range, centered) |
+| `-` | Zoom out (doubles visible range, centered) |
+| `0` | Zoom to fit (show entire file) |
+| `z` | Zoom to selection (with 5% margin) |
+| Scroll wheel | Zoom at cursor position |
+
+The minimum zoom level is 0.5% of the total duration. Zooming preserves the center point -- the portion of the waveform under the cursor (scroll wheel) or the center of the view (keyboard) stays in place while the view range changes.
+
+## Playing a Selection
+
+With a selection active, press `Space` or click "Play Selection" to hear that segment. The server extracts the audio via ffmpeg and returns an MP3 file. A playback bar appears with an HTML5 audio player for the extracted segment.
+
+The extraction endpoint is `/api/media/audio-segment` with `start` and `end` parameters in seconds.
+
+## Mouse Interactions
+
+| Action | Effect |
+|--------|--------|
+| Click and drag on main waveform | Create or adjust a selection |
+| Mouse move on main waveform | Update cursor position in time bar |
+| Scroll wheel on main waveform | Zoom in or out at cursor position |
+| Click on overview bar | Pan main view to that position |
+| Drag viewport indicator | Pan main view by dragging |
+
+### Touch
+
+Selection drag is supported on touch devices.
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Space` | Play selection |
+| `+` / `=` | Zoom in |
+| `-` | Zoom out |
+| `0` | Zoom to fit |
+| `z` | Zoom to selection |
+| `a` / `s` | Save audio snippet to collection |
+| `b` | Toggle collection panel |
+| `h` | Toggle favorite |
+| `Esc` | Clear selection (if any), or go back to audio player |
+
+## State Persistence
+
+Zoom level and selection state are saved to the server and restored when you return to the same audio file.
+
+## Waveform Analysis
+
+The server analyzes the audio file into 2000 peak sample points by default. Each peak contains min and max amplitude values normalized to the -1.0 to 1.0 range. The analysis method is shown in the info bar (typically "ffmpeg").

package/docs/audio-viewer.md

@@ -24,102 +24,7 @@ Autoplay is off by default. Enable it in Settings > Gallery > Autoplay audio. Wh
 
 ## Audio Explorer
 
-The audio explorer displays a canvas-based waveform visualization with selection, zoom, and segment extraction.
-
-### Opening the Explorer
-
-- From the audio player, click "Explore Audio"
-- The explorer fetches 2000 peak samples from the server via ffmpeg
-
-### Waveform Display
-
-The main canvas shows the audio waveform as vertical bars. The height of each bar represents the amplitude at that point. A dashed center line marks the zero crossing.
-
-- **Unselected regions** are drawn in the secondary text color
-- **Selected regions** are drawn in the accent color with a semi-transparent highlight behind them
-- A **cursor line** follows the mouse position, displayed in white
-
-### Overview Bar
-
-Below the main waveform, a smaller overview canvas shows the entire audio file. A highlighted viewport indicator box shows which portion of the waveform is currently visible in the main canvas.
-
-Click anywhere on the overview to pan the main view to that position.
-
-### Selection
-
-**Click and drag** on the main waveform to select a time range. The selection is highlighted in the accent color with edge markers.
-
-- If the selection is too small (less than 0.1% of the total duration), it is automatically cleared
-- The selection is shown in both the main canvas and the overview
-
-### Time Display Bar
-
-A bar above the waveform shows three pieces of information:
-
-- **View**: the time range currently visible (e.g., "0:12.3 - 0:45.7")
-- **Selection**: the selected time range and its duration (e.g., "0:20.0 - 0:30.5 (10.5s)"), or "None"
-- **Cursor**: the time position under the mouse, or "--"
-
-Timestamps are formatted as `M:SS.D` (minutes, seconds, tenths of a second) or `H:MM:SS.D` for long files.
-
-### Zoom Controls
-
-| Key / Button | Action |
-|--------------|--------|
-| `+` or `=` | Zoom in (centered) |
-| `-` | Zoom out (centered) |
-| `0` | Zoom to fit (show entire file) |
-| `z` | Zoom to selection (with 5% margin) |
-| Mouse wheel | Zoom at cursor position |
-
-Minimum zoom level is 0.5% of the total duration.
-
-Zooming preserves the center point -- the portion of the waveform under the mouse (for wheel zoom) or the center (for keyboard zoom) stays in place while the view range narrows or widens.
-
-### Playing a Selection
-
-With a selection active, press `Space` or click the Play Selection button to extract and play that audio segment.
-
-The server extracts the segment via ffmpeg and returns it as an MP3 file. A playback bar appears with an HTML5 audio player for the extracted segment.
-
-The extraction endpoint is `/api/media/audio-segment` with `start` and `end` parameters in seconds.
-
-### Info Bar
-
-The explorer shows an info bar with metadata from ffprobe:
-
-| Field | Example |
-|-------|---------|
-| Duration | 3:42 |
-| Sample Rate | 44.1 kHz |
-| Channels | 2 (stereo) |
-| Codec | mp3 |
-| Bitrate | 320 kbps |
-| File Size | 8.7 MB |
-| Peaks | 2000 (ffmpeg) |
-
-### Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| `Space` | Play selection |
-| `+` / `=` | Zoom in |
-| `-` | Zoom out |
-| `0` | Zoom to fit |
-| `z` | Zoom to selection |
-| `a` / `s` | Save audio snippet to collection |
-| `b` | Toggle collection panel |
-| `h` | Toggle favorite |
-| `Esc` | Clear selection (if any), or go back to audio player |
-
-### Mouse Interactions
-
-| Action | Effect |
-|--------|--------|
-| Click and drag on main waveform | Create/adjust selection |
-| Mouse move on main waveform | Show cursor position in time bar |
-| Mouse wheel on main waveform | Zoom in/out at cursor position |
-| Click on overview bar | Pan main view to that position |
+Click "Explore Audio" from the player to open the waveform explorer. It provides a canvas-based waveform visualization with zoom, selection, segment playback, and collection integration. See the full [Audio Explorer](audio-explorer.md) documentation for details.
 
 ## File Info Overlay
 

package/docs/collections.md

@@ -0,0 +1,162 @@
+# Collections
+
+Collections let you bookmark files, video frames, audio clips, and video clips into named groups. The collections panel provides a sidebar for managing collections, and keyboard shortcuts let you quick-add items without leaving the current view.
+
+## Quick-Add
+
+Press `a` in any mode to add the current item to a collection. If a collection is already active (open in the panel) or was recently used, the item is added to it immediately with a toast notification. If no collection is active, a dropdown picker appears in the top bar so you can choose one.
+
+### What Gets Added
+
+| Context | Item Type | Data Captured |
+|---------|-----------|---------------|
+| Gallery or viewer (file) | File | File path |
+| Gallery or viewer (folder) | Folder or folder contents | Folder path (prompts for choice) |
+| Gallery or viewer (archive subfile) | Subfile | File path + archive path |
+| Video explorer | Video frame | Path, timestamp, cached frame image |
+| Video explorer (with selection) | Video clip | Path, start time, end time |
+| Audio explorer (with selection) | Audio clip | Path, start time, end time |
+
+### Folder Choice
+
+When quick-adding a folder or archive, a prompt asks whether to add the folder itself or its contents. "Add Folder" creates a single reference. "Add Folder Contents" creates a wildcard reference to everything inside.
+
+### Quick-Add Target
+
+The quick-add target is resolved in this priority order:
+
+1. The collection currently open in detail mode in the panel
+2. The last collection an item was added to
+3. If neither is available, the dropdown picker opens
+
+## Favorites
+
+Favorites is a special system collection with a dedicated heart icon in the top bar.
+
+### Toggle
+
+Press `h` in any mode to toggle the current file as a favorite. The heart icon in the top bar fills when the current file is favorited and empties when it is not.
+
+Favorites work for files, folders (with the same folder choice prompt), and archive subfiles. The favorites collection is created automatically on first use.
+
+### Favorites Pane
+
+Favorited items appear in the sidebar favorites pane, accessible via the sidebar tabs.
+
+## Collections Panel
+
+Press `b` in any mode to toggle the collections panel on the right side of the screen. The panel has three modes.
+
+### List Mode
+
+Shows all collections as cards. Each card displays the collection icon, name, and item count. Click a card to open it in detail mode.
+
+- **New (+)** button creates a new collection (prompts for a name)
+- **Search bar** filters collections by name, description, or tags
+
+### Detail Mode
+
+Shows the items in a single collection. Each item row displays an icon or thumbnail, the item name, a type badge, and a remove button.
+
+#### Sorting
+
+| Sort Mode | Description |
+|-----------|-------------|
+| Manual | Drag-to-reorder using the handle (default) |
+| Name | Alphabetical by label |
+| Date Added | Chronological by when the item was added |
+| Type | Grouped by item type |
+
+A direction toggle switches between ascending and descending order.
+
+#### Item Thumbnails
+
+- **Images and image crops**: Thumbnail from the server
+- **Video frames**: The actual extracted frame image
+- **Other types**: A type icon (folder, audio clip, video clip, subfile, etc.)
+
+#### Clicking Items
+
+Click an item to navigate to it. Files open in the viewer, folders navigate the file browser, video frames open the video explorer at the frame timestamp, and audio clips open the audio explorer with the selection pre-loaded.
+
+### Edit Mode
+
+Click the edit button (pencil icon) in the detail header to open the edit form.
+
+| Field | Description |
+|-------|-------------|
+| Name | Collection display name |
+| Description | Markdown description |
+| Cover Image | File path for a cover image ("Use current file" button fills this with the currently viewed file) |
+| Tags | Comma-separated tags for searching |
+
+The danger zone at the bottom has a "Delete Collection" button with a confirmation step.
+
+## Item Types
+
+| Type | Created By | Special Fields |
+|------|-----------|----------------|
+| `file` | Quick-add on a file | Path |
+| `folder` | Quick-add on a folder (single reference) | Path |
+| `folder-contents` | Quick-add on a folder (contents wildcard) | Path |
+| `subfile` | Quick-add on a file inside an archive | Path, ArchivePath |
+| `video-frame` | `a` key in video explorer | Path, FrameTimestamp, FrameCacheKey, FrameFilename |
+| `video-clip` | `s` key in video explorer | Path, VideoStart, VideoEnd |
+| `audio-clip` | `a`/`s` key in audio explorer | Path, AudioStart, AudioEnd |
+
+Each item also stores an auto-generated label, the date it was added, and an optional sort order for manual sorting.
+
+## Operation Plans
+
+Operation plan collections are a special collection type used for batch file operations (move, copy, rename). They are created programmatically rather than through the standard UI.
+
+### Display
+
+Operation plan collections show a summary bar with counts of pending, completed, failed, and skipped items. Each item row shows:
+
+- Status indicator (pending, completed, failed, skipped)
+- Source path and destination path with an arrow between them
+- Operation badge (MOVE, COPY, or RENAME)
+- Skip button (for pending items)
+- Error message (for failed items)
+
+### Controls
+
+| Button | Action |
+|--------|--------|
+| Execute | Run all pending operations |
+| Undo | Reverse completed operations |
+
+Pending item destinations can be edited inline by clicking the destination path.
+
+## Keyboard Shortcuts
+
+| Key | Mode | Action |
+|-----|------|--------|
+| `a` | Gallery, viewer, all explorers | Quick-add current item to collection |
+| `s` | Video explorer | Add selected range as video clip |
+| `s` | Audio explorer | Save audio snippet to collection |
+| `[` | Video explorer | Set selection start at current frame |
+| `]` | Video explorer | Set selection end at current frame |
+| `b` | All modes | Toggle collection panel |
+| `h` | All modes | Toggle favorite |
+
+## Data Storage
+
+Collections are stored server-side as Bibliograph records. Each collection is a JSON document containing the collection metadata and its items array. The favorites collection uses a well-known GUID and is created automatically.
+
+Client-side state (which collection is open, panel width, last-used collection) persists in the browser via localStorage.
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/collections` | List all collections (summaries) |
+| GET | `/api/collections/:guid` | Get full collection with items |
+| PUT | `/api/collections/:guid` | Create or update a collection |
+| DELETE | `/api/collections/:guid` | Delete a collection |
+| POST | `/api/collections/:guid/items` | Add items to a collection |
+| DELETE | `/api/collections/:guid/items/:itemId` | Remove an item |
+| PUT | `/api/collections/:guid/reorder` | Reorder items (manual sort) |
+| POST | `/api/collections/copy-items` | Copy items between collections |
+| POST | `/api/collections/:guid/execute` | Execute pending operations (operation plans) |

package/docs/image-explorer.md

@@ -0,0 +1,71 @@
+# Image Explorer
+
+The image explorer provides deep-zoom inspection of images using OpenSeadragon. Small images load directly; images larger than 4096 pixels are automatically tiled into a DZI pyramid for smooth pan and zoom at any resolution.
+
+## Opening the Explorer
+
+- From the image viewer, press `e`
+- URL updates to `#/explore-image/{id}`
+
+## Display Modes
+
+### Direct Mode
+
+Images with a longest side of 4096 pixels or less load as a single image. The info bar shows dimensions, megapixels, and "Direct" as the mode.
+
+### DZI Tile Mode
+
+Images exceeding 4096 pixels trigger server-side tile generation using Sharp. The image is sliced into 256-pixel tiles at multiple zoom levels, served from `/api/media/dzi-tile/{cacheKey}/{level}/{col}_{row}.{format}`. The info bar shows tile size, format, and live coordinate and zoom readouts.
+
+If Sharp is not available on the server, the image loads directly regardless of size.
+
+## UI Elements
+
+- **Header**: Back button and filename
+- **Info bar**: Image dimensions, megapixels, mode, and (in DZI mode) coordinates and zoom percentage
+- **Viewer canvas**: Main pan-and-zoom area powered by OpenSeadragon
+- **Navigator**: A minimap in the bottom-right corner showing the full image with a viewport indicator rectangle
+
+## Mouse Interactions
+
+| Action | Effect |
+|--------|--------|
+| Click | Zoom in at click position |
+| Double-click | Toggle zoom level |
+| Click and drag | Pan the image |
+| Scroll wheel | Zoom in or out at cursor position |
+| Mouse move | Updates coordinate display (DZI mode) |
+
+### Touch
+
+| Action | Effect |
+|--------|--------|
+| Pinch | Zoom in or out |
+| Drag | Pan the image |
+| Flick | Momentum-based pan (0.25x velocity) |
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `+` / `=` | Zoom in (1.5x) |
+| `-` | Zoom out (1.5x) |
+| `0` | Reset to home zoom (fit to view) |
+| `a` | Quick-add to active collection |
+| `b` | Toggle collection panel |
+| `h` | Toggle favorite |
+| `Esc` | Back to image viewer |
+
+## Coordinate Display
+
+In DZI tile mode, the info bar shows the pixel coordinates of the point under the cursor in real time (e.g., "(4096, 3072)"). This updates as the mouse moves across the canvas and reflects the actual pixel position in the original full-resolution image.
+
+## Zoom Levels
+
+Each keyboard zoom step multiplies or divides by 1.5. The navigator minimap updates to show the current viewport position. The zoom percentage is displayed in the info bar in DZI mode.
+
+## Supported Formats
+
+All image formats supported by the viewer work in the explorer: png, jpg, jpeg, gif, webp, svg, bmp, ico, avif, tiff, tif, heic, heif.
+
+Animated formats (GIF, WebP) display their first frame in the explorer.

package/docs/image-viewer.md

@@ -67,23 +67,7 @@ These work while viewing any image:
 
 ## Image Explorer
 
-The image explorer provides a dedicated zoom and pan interface for detailed image inspection.
-
-### Opening the Explorer
-
-- From the image viewer, press `e`
-
-### Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| `+` / `=` | Zoom in |
-| `-` | Zoom out |
-| `0` | Reset zoom to home |
-| `a` | Quick-add to collection |
-| `b` | Toggle collection panel |
-| `h` | Toggle favorite |
-| `Esc` | Back to image viewer |
+Press `e` to open the image explorer for deep-zoom inspection with OpenSeadragon. Images larger than 4096 pixels are automatically tiled for smooth pan and zoom at any resolution. See the full [Image Explorer](image-explorer.md) documentation for details.
 
 ## File Info Overlay