retold-remote 0.0.4 → 0.0.6

package/web-application/docs/ebook-reader.md

@@ -0,0 +1,90 @@
+# eBook Reader
+
+The eBook reader displays EPUB files directly in the browser using epub.js, with support for MOBI files through server-side conversion.
+
+## Opening an eBook
+
+- **From the gallery**: select an `.epub` or `.mobi` file and press `Enter`, or double-click it
+- eBooks are detected by the document type system (pdf, epub, mobi are all in the document category)
+
+## EPUB Files
+
+EPUB files are loaded and rendered directly in the browser using the epub.js library. No server-side processing is required.
+
+### Reading Interface
+
+The reader takes up the full viewer area and displays one page at a time in a single-column layout (no spread/two-page mode). Text is styled to match the active theme:
+
+- Body text uses the theme's primary text color
+- Background matches the theme's primary background
+- Links use the theme's accent color
+- Font: Georgia, Times New Roman, serif
+- Line height: 1.6
+- Padding: 20px horizontal, 40px vertical
+
+### Table of Contents
+
+A sidebar on the left shows the book's table of contents. Each chapter is a clickable button. Subchapters are indented up to two levels.
+
+| Action | Effect |
+|--------|--------|
+| Click a chapter | Jump to that chapter |
+| Click "TOC" button | Toggle the sidebar open/closed |
+
+The TOC sidebar starts collapsed and can be toggled with the TOC button in the controls bar.
+
+### Page Navigation
+
+Controls at the bottom of the reader:
+
+| Button | Action |
+|--------|--------|
+| **TOC** | Toggle table of contents sidebar |
+| **Prev** | Go to previous page |
+| **Next** | Go to next page |
+
+Page navigation moves through the reflowed content. Pages are determined by the viewport size, not by the original book pagination.
+
+## MOBI Files
+
+MOBI files (and AZW format) require server-side conversion to EPUB before they can be displayed. This requires **ebook-convert** from Calibre to be installed on the server.
+
+### Conversion Flow
+
+1. The client requests conversion via `/api/media/ebook-convert?path=<file>`
+2. The server runs `ebook-convert` to produce an EPUB file
+3. The converted EPUB is cached on disk
+4. The client fetches the EPUB from `/api/media/ebook/<cacheKey>/<filename>`
+5. The EPUB is rendered using the same epub.js reader
+
+If ebook-convert is not available, MOBI files show a message explaining that conversion is needed and linking to the Calibre download page.
+
+### Installing Calibre (for MOBI support)
+
+**macOS:**
+```bash
+brew install calibre
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get install calibre
+```
+
+**Docker:**
+The provided Dockerfile includes Calibre. If using the minimal Dockerfile, add:
+```dockerfile
+RUN apt-get update && apt-get install -y calibre && rm -rf /var/lib/apt/lists/*
+```
+
+## PDF Files
+
+PDF files are rendered using the browser's native PDF viewer in an iframe. No additional tools or libraries are required. The browser provides its own controls for page navigation, zoom, and search.
+
+## Limitations
+
+- MOBI conversion requires Calibre's `ebook-convert` on the server
+- DRM-protected ebooks cannot be read
+- Complex EPUB layouts (fixed-layout EPUBs, heavy CSS) may not render perfectly
+- The reader uses single-page mode only (no two-page spreads)
+- Page numbers shown in the UI correspond to the reflowed content, not the original book pagination

package/web-application/docs/image-viewer.md

@@ -0,0 +1,90 @@
+# Image Viewer
+
+The image viewer displays image files with three fit modes, manual zoom, and EXIF orientation support.
+
+## Opening an Image
+
+- **From the gallery**: select a file and press `Enter`, or double-click a tile
+- **Force any file as image**: press `1` in the gallery or viewer to open it in the image viewer regardless of extension
+
+## Fit Modes
+
+Cycle through fit modes by pressing `z`.
+
+### Fit to Window
+
+Scales the image to fill the viewport while preserving aspect ratio (CSS `object-fit: contain` behavior). The image is never larger than the viewport.
+
+### Original if Smaller (default)
+
+Displays the image at its native resolution if it fits within the viewport. If the image is larger than the viewport, it scales down using the same logic as Fit to Window. This avoids upscaling small images.
+
+### Original Size
+
+Always displays at native resolution regardless of viewport size. Large images will overflow and can be scrolled.
+
+When the fit mode changes, a brief overlay indicator appears for 1.2 seconds showing the active mode name.
+
+## Zoom
+
+| Key | Action | Range |
+|-----|--------|-------|
+| `+` or `=` | Zoom in | Up to 8x |
+| `-` | Zoom out | Down to 0.25x |
+| `0` | Reset zoom to 1x | |
+| Click on image | Toggle between 1x and 2x | |
+
+Each zoom step multiplies or divides by 1.25. The zoom level applies on top of the current fit mode calculation.
+
+When zoomed beyond the viewport, the cursor changes to a zoom-out icon and the image can be scrolled. When the image fits, the cursor shows zoom-in.
+
+## Mouse Interactions
+
+- **Click** on the image toggles between 1x and 2x zoom
+- **Scroll** when zoomed to pan the image
+
+## Keyboard Shortcuts
+
+These work while viewing any image:
+
+| Key | Action |
+|-----|--------|
+| `z` | Cycle fit mode (Fit to Window -> Original if Smaller -> Original Size) |
+| `+` / `=` | Zoom in |
+| `-` | Zoom out |
+| `0` | Reset zoom |
+| `f` | Toggle fullscreen |
+| `i` | Toggle file info overlay |
+| Right / `j` | Next file |
+| Left / `k` | Previous file |
+| `v` | Stream with VLC |
+| `d` | Distraction-free mode |
+| `Esc` | Back to gallery |
+
+## File Info Overlay
+
+Press `i` to show metadata about the current image:
+
+- **Size**: file size in KB/MB
+- **Dimensions**: width x height in pixels
+- **Format**: image format
+- **Modified**: last modification date
+- **Path**: file path on the server
+
+The overlay appears in the top-right corner and can be toggled on and off.
+
+## Supported Formats
+
+png, jpg, jpeg, gif, webp, svg, bmp, ico, avif, tiff, tif, heic, heif
+
+Animated GIFs and WebP animations play in the browser natively. SVG files render as vector graphics. HEIC/HEIF support depends on the browser.
+
+## EXIF Orientation
+
+Images are displayed with `image-orientation: from-image`, meaning EXIF rotation data is respected automatically. Portrait photos taken on phones display upright without manual rotation.
+
+## Thumbnails
+
+In the gallery, image thumbnails are generated server-side using sharp (preferred) or ImageMagick (fallback) at 200x200 pixels in webp format. Thumbnails are cached on disk and invalidated when the source file changes.
+
+If no image processing tool is available, the full image is loaded directly.

package/web-application/docs/server-setup.md

@@ -0,0 +1,262 @@
+# Server Setup and Docker
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g retold-remote
+```
+
+### From source
+
+```bash
+git clone <repo-url>
+cd retold-remote
+npm install
+npm run build
+```
+
+The build step bundles the client-side JavaScript with Quackage and copies assets into `web-application/`.
+
+## Running the Server
+
+### CLI Command
+
+```bash
+retold-remote serve [content-path] [options]
+```
+
+Or using the short alias:
+
+```bash
+rr serve /path/to/media
+```
+
+If `content-path` is omitted, the current directory is served.
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --port [port]` | Port to listen on | Random 7000-7999 |
+| `-H, --hashed-filenames` | Enable hashed filename mode (hides real paths from browser) | Off |
+| `-c, --cache-path [path]` | Root cache directory | `./dist/retold-cache/` |
+| `--cache-thumbnails [path]` | Override thumbnail cache location | `<cache-root>/thumbnails/` |
+| `--cache-archives [path]` | Override archive extraction cache | `<cache-root>/archives/` |
+| `--cache-video-frames [path]` | Override video frame cache | `<cache-root>/video-frames/` |
+| `--cache-audio-waveforms [path]` | Override audio waveform cache | `<cache-root>/audio-waveforms/` |
+
+### Direct Node.js
+
+```bash
+node server.js [content-path]
+```
+
+Default port is `8086` when using `server.js` directly.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | HTTP port | `8086` (server.js) or random (CLI) |
+| `RETOLD_HASHED_FILENAMES` | Set to `true` to enable hashed filenames | `false` |
+
+### Examples
+
+```bash
+# Serve current directory on port 8086
+node server.js
+
+# Serve a specific folder
+node server.js /mnt/nas/media
+
+# CLI with custom port
+retold-remote serve /mnt/nas/media -p 3000
+
+# Hashed filenames for privacy
+retold-remote serve /mnt/nas/media -H
+
+# Custom cache location (useful for Docker volumes)
+retold-remote serve /media -c /cache
+```
+
+## Configuration
+
+### Settings Persistence
+
+User preferences are stored in the browser via `localStorage` under the key `retold-remote-settings`. These include:
+
+- Theme selection
+- View mode (grid or list)
+- Thumbnail size (small, medium, large)
+- Gallery filter and sort preferences
+- Show hidden files toggle
+- Autoplay video / audio toggles
+- Image fit mode
+- Sidebar state
+- Filter presets
+
+Settings are loaded on page load and saved whenever a preference changes.
+
+### Server Capabilities
+
+On startup the server probes for optional tools and reports availability at `GET /api/media/capabilities`. The Settings panel in the UI shows which tools are detected.
+
+| Tool | Detection Method | Feature |
+|------|-----------------|---------|
+| **sharp** | `require('sharp')` | Image thumbnail generation |
+| **ImageMagick** | `identify --version` | Fallback image thumbnails |
+| **ffmpeg** | `ffmpeg -version` | Video thumbnails, frame extraction, audio waveforms |
+| **ffprobe** | `ffprobe -version` | Media metadata (duration, dimensions, codec, bitrate) |
+| **VLC** | macOS: `/Applications/VLC.app`; Linux: `vlc --version` | External video playback |
+| **7-Zip** | `7z --help` | Archive browsing (rar, 7z, tar.*) |
+| **ebook-convert** | `ebook-convert --version` (Calibre) | MOBI/AZW to EPUB conversion |
+
+Without any optional tools the application still works: images are served directly (no thumbnails), videos play in the browser, and zip/cbz archives use native extraction via yauzl.
+
+### Thumbnail Cache
+
+Thumbnails are cached on disk using a SHA-256 hash of `<filepath>:<mtime>:<width>x<height>`. When the source file is modified the mtime changes, invalidating the cache entry automatically.
+
+Default location: `./dist/retold-cache/thumbnails/`
+
+Default thumbnail size: 200x200, format: webp.
+
+Thumbnails are served with `Cache-Control: public, max-age=86400`.
+
+### Hashed Filenames Mode
+
+When enabled (`-H` flag or `RETOLD_HASHED_FILENAMES=true`), real file paths are never exposed to the browser. Instead, deterministic 10-character hex hashes derived from SHA-256 are used in URLs and API responses. The same path always produces the same hash across server restarts.
+
+## Docker
+
+### Using the Included Dockerfile
+
+A `Dockerfile` is provided in the repository root:
+
+```bash
+docker build -t retold-remote .
+docker run -p 8086:8086 -v /path/to/media:/media retold-remote
+```
+
+### Inline Dockerfile
+
+If you need to create a Dockerfile from scratch, here is a complete working version:
+
+```dockerfile
+FROM node:20-slim
+
+# Install optional tools for full functionality
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    imagemagick \
+    p7zip-full \
+    calibre \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy package files and install dependencies
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
+# Install sharp (optional image processing)
+RUN npm install sharp || true
+
+# Copy application source and built assets
+COPY source/ source/
+COPY web-application/ web-application/
+COPY css/ css/
+COPY html/ html/
+COPY server.js ./
+
+# Create cache directory
+RUN mkdir -p /cache
+
+# Default port
+ENV PORT=8086
+
+EXPOSE 8086
+
+# Serve /media with cache at /cache
+CMD ["node", "server.js", "/media"]
+```
+
+### Docker Compose
+
+```yaml
+version: "3.8"
+services:
+  retold-remote:
+    build: .
+    ports:
+      - "8086:8086"
+    volumes:
+      - /path/to/media:/media:ro
+      - retold-cache:/cache
+    environment:
+      - PORT=8086
+    restart: unless-stopped
+
+volumes:
+  retold-cache:
+```
+
+### Docker Usage Notes
+
+- Mount your media folder to `/media` (read-only is fine with `:ro`)
+- Mount a volume to `/cache` for persistent thumbnail and frame caches
+- The `node:20-slim` base keeps the image small while the `apt-get` packages add full media processing
+- `calibre` is the largest optional package; omit it if you do not need MOBI/AZW ebook conversion
+- `sharp` is installed separately because it has native bindings that may fail on some architectures; the `|| true` ensures the build continues without it
+
+### Minimal Dockerfile (No Optional Tools)
+
+If you only need basic browsing without thumbnails or media probing:
+
+```dockerfile
+FROM node:20-slim
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
+COPY source/ source/
+COPY web-application/ web-application/
+COPY css/ css/
+COPY html/ html/
+COPY server.js ./
+
+ENV PORT=8086
+EXPOSE 8086
+
+CMD ["node", "server.js", "/media"]
+```
+
+This produces an image under 200MB. Images display directly (no thumbnails), videos play in the browser, and zip/cbz archives use native extraction.
+
+## Archive Browsing
+
+Archives appear as navigable folders in the file browser. Clicking an archive opens it and displays its contents as if they were a regular directory.
+
+**Supported formats:**
+
+| Format | Tool Required |
+|--------|---------------|
+| `.zip`, `.cbz` | None (native yauzl) |
+| `.7z`, `.rar`, `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.tgz`, `.cbr` | 7-Zip |
+
+Files inside archives can be viewed, thumbnailed, and probed just like regular files. Archive contents are extracted to the cache directory on demand.
+
+## VLC Streaming
+
+The VLC integration allows streaming media files to a VLC player running on the server machine. Press `v` in the media viewer to send the current file to VLC.
+
+Setup instructions for macOS, Windows, and Linux are available in the Settings panel under "VLC Protocol Setup". The setup creates a `vlc://` protocol handler that opens files in VLC when triggered from the browser.
+
+**Platform details:**
+- **macOS**: Creates an AppleScript app at `/Applications/VLCProtocol.app` and registers it as a URL handler
+- **Windows**: Registry entry or batch script that maps `vlc://` to the VLC executable
+- **Linux**: Desktop file at `~/.local/share/applications/vlc-protocol.desktop` registered with xdg-mime

package/web-application/docs/video-viewer.md

@@ -0,0 +1,134 @@
+# Video Viewer and Explorer
+
+The video viewer provides an action menu for choosing how to interact with a video, inline browser playback, VLC streaming, and a frame explorer for scrubbing through video content visually.
+
+## Opening a Video
+
+- **From the gallery**: select a video file and press `Enter`, or double-click it
+- **Force any file as video**: press `2` in the gallery or viewer to open it in the video viewer regardless of extension
+
+## Video Action Menu
+
+When a video is opened, an action menu appears instead of playing immediately. The menu shows the filename and a preview frame extracted from the video midpoint.
+
+### Menu Options
+
+| Key | Option | Description |
+|-----|--------|-------------|
+| `Space` / `Enter` | **Play in Browser** | Plays the video inline with HTML5 `<video>` controls |
+| `e` | **Explore Video Frames** | Opens the frame explorer (requires ffmpeg) |
+| `t` | **Extract Thumbnail** | Extracts a single frame from the midpoint |
+| `v` | **Stream with VLC** | Sends the file to VLC on the server machine |
+
+The preview frame in the menu is loaded automatically from the server. If ffmpeg is not available, the Explore and Thumbnail options are hidden.
+
+Navigation shortcuts still work while the menu is open:
+
+| Key | Action |
+|-----|--------|
+| Right / `j` | Skip to next file |
+| Left / `k` | Skip to previous file |
+| `Esc` | Back to gallery |
+
+## In-Browser Playback
+
+Pressing `Space` or `Enter` replaces the action menu with an HTML5 video player. The player has native browser controls for play/pause, seeking, volume, and fullscreen.
+
+Below the player, a **stats bar** shows:
+
+- **Duration** (formatted as mm:ss)
+- **Resolution** (width x height)
+- **Codec** (e.g., h264, hevc, vp9)
+- **Bitrate** (in kbps or Mbps)
+- **File Size** (formatted)
+
+The stats bar also includes buttons to jump to the Video Explorer or stream with VLC.
+
+### Autoplay
+
+Autoplay is off by default. Enable it in Settings > Gallery > Autoplay video. When enabled, videos begin playing as soon as the player loads.
+
+## Video Explorer
+
+The video explorer extracts multiple frames from a video and displays them in a grid, letting you scrub through content visually without playing the video.
+
+### Opening the Explorer
+
+- From the video action menu, press `e`
+- From the video stats bar during playback, click "Explore Video"
+
+### Frame Grid
+
+Frames are displayed in a responsive grid. Each frame card shows:
+
+- The extracted frame image
+- A timestamp label (e.g., "1:23")
+- A frame index number
+
+Double-click any frame to open it in a full-screen preview overlay.
+
+### Controls
+
+At the top of the explorer:
+
+| Control | Description |
+|---------|-------------|
+| Frame count dropdown | Choose 10, 20, 40, 60, or 100 frames (default: 20) |
+| Full-res checkbox | Extract frames at 1920x1080 instead of 640x360 |
+| Refresh button | Re-extract frames with current settings |
+
+### Info Bar
+
+Below the controls, an info bar displays video metadata:
+
+- Duration
+- Resolution
+- Codec
+- File size
+- Number of extracted frames
+
+### Timeline Bar
+
+Below the frame grid, a timeline bar shows the video duration with markers at each extracted frame's position. The timeline also shows markers for any custom frames you extract.
+
+**Click anywhere on the timeline** to extract a frame at that exact timestamp. The extracted frame appears in the grid in chronological order, styled with a dashed border to distinguish it from the evenly-spaced frames.
+
+### Frame Preview
+
+Double-click any frame in the grid to open a full-screen preview overlay showing the frame at full size.
+
+In the preview:
+
+| Key | Action |
+|-----|--------|
+| Left / `k` | Previous frame |
+| Right / `j` | Next frame |
+| `Esc` | Close preview |
+
+The Back button in the preview header also closes it. Navigation moves through all frames (regular and custom) in chronological order.
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Back to video viewer |
+
+## VLC Streaming
+
+Press `v` from the action menu, stats bar, or viewer to send the current video to VLC running on the server. This is useful for files in formats the browser cannot play natively.
+
+VLC protocol setup instructions are available in Settings > VLC Protocol Setup, with platform-specific guides for macOS, Windows, and Linux.
+
+## File Info Overlay
+
+Press `i` while viewing a video to see metadata:
+
+- Size, Duration, Resolution, Codec, Bitrate, Format, Modified date, Path
+
+## Supported Formats
+
+**Natively recognized extensions**: mp4, webm, mov, mkv, avi, wmv, flv, m4v, ogv, mpg, mpeg, mpe, mpv, m2v, ts, mts, m2ts, vob, 3gp, 3g2, f4v, rm, rmvb, divx, asf, mxf, dv, nsv, nuv, y4m, wtv, swf, dat
+
+**Browser playback support** varies by format. Most browsers play mp4 (h264), webm (vp8/vp9), and ogg natively. For other formats, use VLC streaming or the frame explorer.
+
+**Force any file as video** by pressing `2` in the gallery or viewer to bypass extension detection. This is useful for misnamed files (e.g., `.avii` instead of `.avi`).

package/web-application/docs.html

@@ -0,0 +1,59 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta http-equiv="X-UA-Compatible" content="IE=edge">
+		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+		<meta name="description" content="Retold Remote Documentation">
+
+		<title>Retold Remote - Documentation</title>
+
+		<!-- Docuserve base stylesheet -->
+		<link href="css/docuserve.css" rel="stylesheet">
+		<!-- PICT Dynamic View CSS Container -->
+		<style id="PICT-CSS"></style>
+
+		<!-- Load the PICT library -->
+		<script src="js/pict.min.js" type="text/javascript"></script>
+		<!-- Bootstrap the Application -->
+		<script type="text/javascript">
+			Pict.safeOnDocumentReady(function()
+			{
+				// Intercept AppData.Docuserve creation to inject DocsBaseURL
+				// before pict-docuserve starts fetching markdown files.
+				var _origInit = PictDocuserve.prototype.onAfterInitializeAsync;
+				PictDocuserve.prototype.onAfterInitializeAsync = function(fCallback)
+				{
+					var _appData = this.pict.AppData;
+					// One-shot setter: when onAfterInitializeAsync assigns
+					// AppData.Docuserve, modify DocsBaseURL before loadCatalog runs.
+					Object.defineProperty(_appData, 'Docuserve',
+					{
+						configurable: true,
+						enumerable: true,
+						set: function(pValue)
+						{
+							pValue.DocsBaseURL = 'docs/';
+							Object.defineProperty(_appData, 'Docuserve',
+							{
+								configurable: true,
+								enumerable: true,
+								writable: true,
+								value: pValue
+							});
+						}
+					});
+					return _origInit.call(this, fCallback);
+				};
+				Pict.safeLoadPictApplication(PictDocuserve, 2);
+			});
+		</script>
+	</head>
+	<body>
+		<!-- The root container for the Pict application -->
+		<div id="Docuserve-Application-Container"></div>
+
+		<!-- Load the Docuserve PICT Application Bundle -->
+		<script src="js/pict-docuserve.min.js" type="text/javascript"></script>
+	</body>
+</html>