retold-remote 0.0.23 → 0.0.25

package/docs/stack-launcher.md

@@ -0,0 +1,218 @@
+# Stack Launcher
+
+The `--stack` flag (and the `retold-stack` shortcut) brings up the full Retold stack as a single command: an embedded Ultravisor coordinator, the Retold Remote media browser, and Orator-Conversion (embedded inside Retold Remote). Point it at any directory and it just works — sane XDG-style data paths, automatic readiness polling, and graceful shutdown of all child processes.
+
+## Quick Start
+
+```bash
+# Run the full stack against the current directory
+retold-stack
+
+# Or against any directory
+retold-stack /mnt/nas/media
+
+# Or via the explicit flag
+retold-remote serve --stack /mnt/nas/media
+```
+
+That's it. No config files, no separate terminals, no manual port wiring.
+
+## What Gets Launched
+
+| Component | Where it runs | Port |
+|-----------|---------------|------|
+| **Ultravisor** | Spawned as a child process | 54321 |
+| **Retold Remote** | Main process (the one you started) | Random 7000-7999 (override with `-p`) |
+| **Orator-Conversion** | Embedded inside Retold Remote (no separate process) | Same as Retold Remote |
+
+The stack launcher:
+1. Resolves XDG-style data paths
+2. Detects whether Ultravisor is already running on port 54321 (and reuses it if so)
+3. Spawns Ultravisor as a child process with a generated config file
+4. Polls until Ultravisor is accepting connections (up to 30 seconds)
+5. Sets the `UltravisorURL` automatically so Retold Remote registers as a beacon
+6. Starts the Retold Remote server with Orator-Conversion embedded
+7. Streams the Ultravisor child's stdout/stderr through the main logger with an `[ultravisor]` prefix
+8. On `SIGINT`/`SIGTERM`, disconnects the beacon, kills the Ultravisor child gracefully, and exits
+
+## Default Data Paths
+
+The stack launcher uses [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) defaults so data lives in predictable, user-scoped locations regardless of what directory you launched from.
+
+| Purpose | Default Path | Override |
+|---------|-------------|----------|
+| Ultravisor datastore | `~/.local/share/ultravisor/datastore/` | `$XDG_DATA_HOME/ultravisor/datastore/` |
+| Ultravisor staging | `~/.local/share/ultravisor/staging/` | `$XDG_DATA_HOME/ultravisor/staging/` |
+| Retold Remote cache | `~/.cache/retold-remote/` | `$XDG_CACHE_HOME/retold-remote/`, or `-c` flag |
+| Stack config files | `~/.config/retold-stack/` | `$XDG_CONFIG_HOME/retold-stack/` |
+
+The cache directory holds thumbnails, video frames, audio waveforms, archive extractions, and converted ebooks/PDFs.
+
+The Ultravisor datastore holds the work-queue journal and beacon registry.
+
+These paths are created on first launch if they do not already exist.
+
+## CLI Reference
+
+### `retold-stack`
+
+Convenience entry point that auto-injects `serve --stack`.
+
+```bash
+retold-stack [content-path] [options]
+```
+
+All options accepted by `retold-remote serve` are forwarded.
+
+### `retold-remote serve --stack`
+
+The full form. Useful when you want to combine `--stack` with other flags.
+
+```bash
+retold-remote serve --stack [content-path] [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--stack` | Spawn Ultravisor as a child process and connect to it. Sets cache root to `~/.cache/retold-remote/` if `-c` is not passed. Auto-sets the Ultravisor URL to `http://localhost:54321`. |
+
+All other `serve` options still apply (`-p`, `--no-hash`, `-c`, `-l`, etc.).
+
+## Examples
+
+### Browse the current directory with the full stack
+
+```bash
+cd ~/Pictures
+retold-stack
+```
+
+### Browse a specific NAS share
+
+```bash
+retold-stack /mnt/nas/media
+```
+
+### Pin the port and stash logs to a file
+
+```bash
+retold-stack /mnt/nas/media -p 8086 -l ~/retold.log
+```
+
+### Override just the Retold cache location
+
+```bash
+retold-remote serve --stack /mnt/nas/media -c /var/cache/retold
+```
+
+### Reuse an already-running Ultravisor
+
+If port 54321 is already accepting connections, the stack launcher detects this and connects to the existing instance instead of spawning a new one. The log line will read:
+
+```
+[stack] ultravisor already running on port 54321, reusing
+```
+
+This means you can leave Ultravisor running across multiple Retold Remote launches without conflict.
+
+## Logging
+
+The stack launcher streams the Ultravisor child process's output through Retold Remote's logger so you have a single log stream for both processes. Lines from the Ultravisor child are prefixed `[ultravisor]`, and stack-launcher events are prefixed `[stack]`:
+
+```
+[stack] launching ultravisor (port 54321)
+[stack]   data:    /Users/steven/.local/share/ultravisor/datastore
+[stack]   staging: /Users/steven/.local/share/ultravisor/staging
+[ultravisor] UltravisorTaskTypeRegistry: 53 built-in task types registered.
+[stack] ultravisor ready (after 1 attempts)
+==========================================================
+  Retold Remote running on http://localhost:7842
+==========================================================
+  Content: /mnt/nas/media
+  Cache:   /Users/steven/.cache/retold-remote
+  Browse:  http://localhost:7842/
+  Beacon:  registered with Ultravisor at http://localhost:54321
+  Stack:   ultravisor + retold-remote (orator-conversion embedded)
+==========================================================
+```
+
+If you also pass `-l <path>`, both streams are written to the file as well.
+
+## Shutdown
+
+Press `Ctrl+C` once. The launcher will:
+
+1. Log `Shutting down...`
+2. Disconnect the Ultravisor beacon (so Ultravisor knows the worker is leaving cleanly)
+3. Send `SIGTERM` to the Ultravisor child process
+4. Wait up to 1 second for graceful exit
+5. Send `SIGKILL` if it has not exited
+6. Exit the main process
+
+If the launcher reused an already-running Ultravisor (rather than spawning one), it will not kill that Ultravisor — it only manages processes it started itself.
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  retold-stack /mnt/media                                    │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │ Main process (retold-remote)                         │  │
+│  │  ┌───────────────────────────────────────────────┐  │  │
+│  │  │ Orator HTTP server (port 7000-7999)           │  │  │
+│  │  │  ├─ Retold Remote routes (/api/media/...)     │  │  │
+│  │  │  ├─ Orator-Conversion (/api/conversion/1.0/)  │  │  │
+│  │  │  └─ Static web app (/)                        │  │  │
+│  │  └───────────────────────────────────────────────┘  │  │
+│  │  ┌───────────────────────────────────────────────┐  │  │
+│  │  │ Ultravisor Beacon client                      │  │  │
+│  │  │  └─ Connects to localhost:54321               │  │  │
+│  │  └───────────────────────────────────────────────┘  │  │
+│  └─────────────────────────────────────────────────────┘  │
+│                          ▲                                  │
+│                          │ HTTP                             │
+│                          ▼                                  │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │ Child process (ultravisor)                           │  │
+│  │  ├─ Coordinator API (port 54321)                     │  │
+│  │  ├─ Beacon registry                                  │  │
+│  │  ├─ Work queue journal                               │  │
+│  │  └─ Web interface                                    │  │
+│  │  Datastore: ~/.local/share/ultravisor/datastore/     │  │
+│  └─────────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────────┘
+```
+
+## Why Stack Mode?
+
+Use `--stack` when you want a single command that brings up the full Retold experience:
+
+- **Heavy media processing offloaded** through the Ultravisor beacon (video frame extraction, audio waveforms, ebook conversion, PDF page rendering)
+- **Document conversion** via the embedded Orator-Conversion service (with the `doc-to-pdf` converter for Word, RTF, ODT, WordPerfect, etc.)
+- **Persistent state** across launches (the Ultravisor datastore lives at a stable XDG location)
+- **No port juggling** — Ultravisor on its standard port 54321, Retold Remote on a random high port
+
+Use the bare `retold-remote serve` command (without `--stack`) when you just want a quick gallery browser without the coordinator infrastructure.
+
+## Comparison
+
+| Feature | `retold-remote serve` | `retold-stack` |
+|---------|----------------------|----------------|
+| Gallery browser | ✓ | ✓ |
+| Image/video/audio viewers | ✓ | ✓ |
+| Document conversion (doc, rtf, etc.) | Embedded only | Embedded + dispatched |
+| Heavy work offloading | No | Yes (via Ultravisor) |
+| Spawns child processes | No | Yes (Ultravisor) |
+| Default cache location | `./dist/retold-cache/` | `~/.cache/retold-remote/` |
+| Survives `cd` | Yes | Yes (XDG paths are absolute) |
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `Could not locate the ultravisor package` | Run `npm install ultravisor` (or `npm install -g retold-remote` to get the bundled version) |
+| `Ultravisor did not become ready within 30000ms` | Check the `[ultravisor]` log lines for an error. Common causes: port 54321 already bound by another process, missing dependencies, or invalid datastore path permissions |
+| Stack mode hangs at `launching ultravisor` | Ultravisor's child process may be waiting on stdin or hitting an interactive prompt. Run with `-l <path>` to capture full logs |
+| Beacon shows "not connected" | Ultravisor came up but the beacon registration failed. Check the Ultravisor child logs for errors and verify nothing is firewalling localhost:54321 |
+| Want to override XDG paths | Set `XDG_DATA_HOME`, `XDG_CACHE_HOME`, or `XDG_CONFIG_HOME` in your environment before launching, or use the `-c` flag for the Retold Remote cache |

package/docs/ultravisor-integration.md

@@ -2,6 +2,8 @@
 
 retold-remote can offload heavy media processing to a remote machine running an Ultravisor beacon worker. This is useful when the server (e.g. a NAS) has limited CPU and RAM but needs to process large video files, raw camera images, audio waveforms, and ebook conversions.
 
+> **Tip:** If you just want to run Ultravisor and Retold Remote together on the same machine without configuring anything, use the [Stack Launcher](stack-launcher.md) — `retold-stack /path/to/media` spawns Ultravisor as a child process automatically with sane XDG-style data paths. This page covers the case where Ultravisor runs on a *different* machine.
+
 ## How It Works
 
 When configured, retold-remote dispatches shell commands (ffmpeg, ffprobe, dcraw, ImageMagick, audiowaveform, ebook-convert) to a beacon worker via HTTP instead of running them locally. The beacon downloads the source file from retold-remote's content API, executes the command, and returns the result as base64-encoded data.

package/package.json

@@ -1,11 +1,12 @@
 {
     "name": "retold-remote",
-    "version": "0.0.23",
+    "version": "0.0.25",
     "description": "Retold Remote - NAS media browser with gallery views and keyboard navigation",
     "main": "source/Pict-RetoldRemote-Bundle.js",
     "bin": {
         "retold-remote": "source/cli/RetoldRemote-CLI-Run.js",
-        "rr": "source/cli/RetoldRemote-CLI-Run.js"
+        "rr": "source/cli/RetoldRemote-CLI-Run.js",
+        "retold-stack": "source/cli/RetoldRemote-Stack-Run.js"
     },
     "files": [
         "source/",
@@ -30,7 +31,7 @@
     "author": "steven velozo <steven@velozo.com>",
     "license": "MIT",
     "dependencies": {
-        "@xmldom/xmldom": "^0.8.11",
+        "@xmldom/xmldom": "^0.9.9",
         "dcraw": "^1.0.3",
         "epubjs": "^0.3.93",
         "exifr": "^7.1.3",
@@ -38,10 +39,11 @@
         "fable-serviceproviderbase": "^3.0.19",
         "node-unrar-js": "^2.0.2",
         "orator": "^6.0.4",
-        "orator-serviceserver-restify": "^2.0.9",
+        "orator-conversion": "^1.0.7",
+        "orator-serviceserver-restify": "^2.0.10",
         "parime": "^1.0.3",
         "pdf-parse": "^2.4.5",
-        "pict": "^1.0.359",
+        "pict": "^1.0.361",
         "pict-application": "^1.0.33",
         "pict-docuserve": "^0.0.32",
         "pict-provider": "^1.0.12",
@@ -50,8 +52,9 @@
         "pict-service-commandlineutility": "^1.0.19",
         "pict-view": "^1.0.67",
         "retold-content-system": "^1.0.12",
-        "ultravisor-beacon": "^0.0.7",
-        "yauzl": "^3.2.1"
+        "ultravisor": "^1.0.15",
+        "ultravisor-beacon": "^0.0.8",
+        "yauzl": "^3.3.0"
     },
     "optionalDependencies": {
         "@img/sharp-wasm32": "^0.34.5",

package/source/Pict-Application-RetoldRemote.js

@@ -30,6 +30,7 @@ const libViewImageExplorer = require('./views/PictView-Remote-ImageExplorer.js')
 const libViewVLCSetup = require('./views/PictView-Remote-VLCSetup.js');
 const libViewCollectionsPanel = require('./views/PictView-Remote-CollectionsPanel.js');
 const libViewFileInfoPanel = require('./views/PictView-Remote-FileInfoPanel.js');
+const libViewSubimagesPanel = require('./views/PictView-Remote-SubimagesPanel.js');
 
 // Application configuration
 const _DefaultConfiguration = require('./Pict-Application-RetoldRemote-Configuration.json');
@@ -65,6 +66,7 @@ class RetoldRemoteApplication extends libContentEditorApplication
 		this.pict.addView('RetoldRemote-VLCSetup', libViewVLCSetup.default_configuration, libViewVLCSetup);
 		this.pict.addView('RetoldRemote-CollectionsPanel', libViewCollectionsPanel.default_configuration, libViewCollectionsPanel);
 		this.pict.addView('RetoldRemote-FileInfoPanel', libViewFileInfoPanel.default_configuration, libViewFileInfoPanel);
+		this.pict.addView('RetoldRemote-SubimagesPanel', libViewSubimagesPanel.default_configuration, libViewSubimagesPanel);
 
 		// Add new providers
 		this.pict.addProvider('RetoldRemote-Provider', libProviderRetoldRemote.default_configuration, libProviderRetoldRemote);

package/source/RetoldRemote-ExtensionMaps.js

@@ -41,7 +41,7 @@ for (let tmpKey in RawImageExtensions)
 
 const VideoExtensions = { 'mp4': true, 'webm': true, 'mov': true, 'mkv': true, 'avi': true, 'wmv': true, 'flv': true, 'm4v': true, 'ogv': true, 'mpg': true, 'mpeg': true, 'mpe': true, 'mpv': true, 'm2v': true, 'ts': true, 'mts': true, 'm2ts': true, 'vob': true, '3gp': true, '3g2': true, 'f4v': true, 'rm': true, 'rmvb': true, 'divx': true, 'asf': true, 'mxf': true, 'dv': true, 'nsv': true, 'nuv': true, 'y4m': true, 'wtv': true, 'swf': true, 'dat': true };
 const AudioExtensions = { 'mp3': true, 'wav': true, 'ogg': true, 'flac': true, 'aac': true, 'm4a': true, 'wma': true, 'oga': true };
-const DocumentExtensions = { 'pdf': true, 'epub': true, 'mobi': true, 'doc': true, 'docx': true };
+const DocumentExtensions = { 'pdf': true, 'epub': true, 'mobi': true, 'doc': true, 'docx': true, 'rtf': true, 'odt': true, 'wpd': true, 'wps': true, 'pages': true, 'odp': true, 'ppt': true, 'pptx': true, 'ods': true, 'xls': true, 'xlsx': true };
 
 /**
  * Get the media category for a file extension.

package/source/cli/RetoldRemote-Server-Setup.js

@@ -48,8 +48,11 @@ const libRetoldRemoteMetadataCache = require('../server/RetoldRemote-MetadataCac
 const libRetoldRemoteFileOperationService = require('../server/RetoldRemote-FileOperationService.js');
 const libRetoldRemoteAISortService = require('../server/RetoldRemote-AISortService.js');
 const libRetoldRemoteImageService = require('../server/RetoldRemote-ImageService.js');
+const libRetoldRemoteSubimageService = require('../server/RetoldRemote-SubimageService.js');
+const libRetoldRemoteCollectionExportService = require('../server/RetoldRemote-CollectionExportService.js');
 const libRetoldRemoteUltravisorDispatcher = require('../server/RetoldRemote-UltravisorDispatcher.js');
 const libRetoldRemoteUltravisorBeacon = require('../server/RetoldRemote-UltravisorBeacon.js');
+const libOratorConversion = require('orator-conversion');
 const libUrl = require('url');
 
 function setupRetoldRemoteServer(pOptions, fCallback)
@@ -189,6 +192,12 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 				ContentPath: tmpContentPath
 			});
 
+			// Set up the subimage region service
+			let tmpSubimageService = new libRetoldRemoteSubimageService(tmpFable,
+			{
+				ContentPath: tmpContentPath
+			});
+
 			// Set up the metadata cache service
 			let tmpMetadataCache = new libRetoldRemoteMetadataCache(tmpFable,
 			{
@@ -212,6 +221,12 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			let tmpCollectionService = new libRetoldRemoteCollectionService(tmpFable, {});
 			tmpCollectionService.setFileOperationService(tmpFileOperationService);
 
+			// Set up the collection export service
+			let tmpCollectionExportService = new libRetoldRemoteCollectionExportService(tmpFable,
+			{
+				ContentPath: tmpContentPath
+			});
+
 			// Set up the media service
 			let tmpMediaService = new libRetoldRemoteMediaService(tmpFable,
 			{
@@ -226,11 +241,23 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			// Set up the Ultravisor beacon for mesh registration
 			let tmpBeacon = new libRetoldRemoteUltravisorBeacon(tmpFable, {});
 
+			// Set up orator-conversion for document format conversion
+			tmpFable.serviceManager.addServiceType('OratorFileTranslation', libOratorConversion);
+			let tmpConversionService = tmpFable.serviceManager.instantiateServiceProvider('OratorFileTranslation',
+			{
+				RoutePrefix: '/api/conversion',
+				MaxFileSize: 100 * 1024 * 1024, // 100MB for large documents
+				LogLevel: 1
+			});
+
 			// Wire the dispatcher to services that can offload processing
 			tmpMediaService.setDispatcher(tmpDispatcher);
 			tmpVideoFrameService.setDispatcher(tmpDispatcher);
 			tmpAudioWaveformService.setDispatcher(tmpDispatcher);
 			tmpEbookService.setDispatcher(tmpDispatcher);
+
+			// Share the orator-conversion service with the ebook service for PDF conversion
+			tmpEbookService.setConversionService(tmpConversionService);
 			tmpImageService.setDispatcher(tmpDispatcher);
 
 			// Share tool capabilities with the image service so it can
@@ -238,10 +265,12 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			// Also provides the centrally-verified sharp module reference.
 			tmpImageService.setCapabilities(tmpMediaService.capabilities);
 
-			// Share the verified sharp module with the metadata cache
+			// Share the verified sharp module with the metadata cache, subimage, and export services
 			if (tmpMediaService.capabilities.sharpModule)
 			{
 				tmpMetadataCache.setSharpModule(tmpMediaService.capabilities.sharpModule);
+				tmpSubimageService.setSharpModule(tmpMediaService.capabilities.sharpModule);
+				tmpCollectionExportService.setSharpModule(tmpMediaService.capabilities.sharpModule);
 			}
 
 			tmpOrator.initialize(
@@ -470,6 +499,74 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			// Connect collection service API routes
 			tmpCollectionService.connectRoutes(tmpServiceServer);
 
+			// Connect subimage region service API routes
+			tmpSubimageService.connectRoutes(tmpServiceServer);
+
+			// Connect collection export service API routes
+			tmpCollectionExportService.connectRoutes(tmpServiceServer);
+
+			// Connect orator-conversion routes and register custom doc-to-pdf converter
+			if (tmpMediaService.capabilities.libreoffice)
+			{
+				let tmpSofficePath = 'soffice';
+				if (libFs.existsSync('/Applications/LibreOffice.app/Contents/MacOS/soffice'))
+				{
+					tmpSofficePath = '/Applications/LibreOffice.app/Contents/MacOS/soffice';
+				}
+
+				tmpConversionService.addConverter('doc-to-pdf',
+					(pInputBuffer, pRequest, fCallback) =>
+					{
+						// Write input to temp file, convert with LibreOffice, return PDF buffer
+						let tmpTempDir = require('os').tmpdir();
+						let tmpUniqueId = Date.now() + '_' + Math.random().toString(36).slice(2);
+						let tmpInputExt = (pRequest.query && pRequest.query.ext) || 'docx';
+						let tmpInputPath = libPath.join(tmpTempDir, 'retold_doc_' + tmpUniqueId + '.' + tmpInputExt);
+						let tmpOutputDir = libPath.join(tmpTempDir, 'retold_docout_' + tmpUniqueId);
+
+						libFs.mkdirSync(tmpOutputDir, { recursive: true });
+
+						try
+						{
+							libFs.writeFileSync(tmpInputPath, pInputBuffer);
+							libChildProcess.execSync(
+								'"' + tmpSofficePath + '" --headless --convert-to pdf --outdir "' + tmpOutputDir + '" "' + tmpInputPath + '"',
+								{ stdio: 'ignore', timeout: 120000 });
+
+							// Find the output PDF (LibreOffice names it after the input)
+							let tmpBaseName = libPath.basename(tmpInputPath, '.' + tmpInputExt);
+							let tmpOutputPath = libPath.join(tmpOutputDir, tmpBaseName + '.pdf');
+
+							if (!libFs.existsSync(tmpOutputPath))
+							{
+								// Clean up
+								try { libFs.unlinkSync(tmpInputPath); } catch (e) { /* */ }
+								try { libFs.rmSync(tmpOutputDir, { recursive: true }); } catch (e) { /* */ }
+								return fCallback(new Error('LibreOffice conversion produced no output.'));
+							}
+
+							let tmpPdfBuffer = libFs.readFileSync(tmpOutputPath);
+
+							// Clean up temp files
+							try { libFs.unlinkSync(tmpInputPath); } catch (e) { /* */ }
+							try { libFs.rmSync(tmpOutputDir, { recursive: true }); } catch (e) { /* */ }
+
+							return fCallback(null, tmpPdfBuffer, 'application/pdf');
+						}
+						catch (pError)
+						{
+							try { libFs.unlinkSync(tmpInputPath); } catch (e) { /* */ }
+							try { libFs.rmSync(tmpOutputDir, { recursive: true }); } catch (e) { /* */ }
+							return fCallback(new Error('Document conversion failed: ' + pError.message));
+						}
+					});
+
+				tmpFable.log.info('Orator-Conversion: doc-to-pdf converter registered (LibreOffice)');
+			}
+
+			tmpConversionService.connectRoutes();
+			tmpFable.log.info('Orator-Conversion: routes connected at /api/conversion/1.0/');
+
 			// Connect AI sort service API routes
 			tmpAISortService.connectRoutes(tmpServiceServer);
 
@@ -486,6 +583,10 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			{
 				tmpFable.log.info('Audio explorer state Bibliograph source initialized.');
 			});
+			tmpSubimageService.initializeState(() =>
+			{
+				tmpFable.log.info('Subimage region state Bibliograph source initialized.');
+			});
 			tmpEpubMetadataService.initialize(() =>
 			{
 				tmpFable.log.info('EPUB metadata service initialized.');
@@ -495,6 +596,81 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 				// Non-fatal — if Ultravisor is down, processing stays local
 			});
 
+			// --- GET /api/media/pdf-text ---
+			// Extract text from a specific PDF page (or all pages if no page specified).
+			tmpServiceServer.get('/api/media/pdf-text',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpParsedUrl = libUrl.parse(pRequest.url, true);
+						let tmpQuery = tmpParsedUrl.query;
+						let tmpRelPath = tmpQuery.path;
+						let tmpPageNum = parseInt(tmpQuery.page, 10) || 0;
+
+						if (!tmpRelPath || typeof (tmpRelPath) !== 'string')
+						{
+							pResponse.send(400, { Success: false, Error: 'Missing path parameter.' });
+							return fNext();
+						}
+
+						tmpRelPath = decodeURIComponent(tmpRelPath).replace(/^\/+/, '');
+						if (tmpRelPath.includes('..') || libPath.isAbsolute(tmpRelPath))
+						{
+							pResponse.send(400, { Success: false, Error: 'Invalid path.' });
+							return fNext();
+						}
+
+						let tmpAbsPath = libPath.join(tmpContentPath, tmpRelPath);
+						if (!libFs.existsSync(tmpAbsPath))
+						{
+							pResponse.send(404, { Success: false, Error: 'File not found.' });
+							return fNext();
+						}
+
+						let tmpExt = tmpRelPath.replace(/^.*\./, '').toLowerCase();
+						if (tmpExt !== 'pdf')
+						{
+							pResponse.send(400, { Success: false, Error: 'Not a PDF file.' });
+							return fNext();
+						}
+
+						let tmpPdfParse = require('pdf-parse');
+						let tmpBuffer = libFs.readFileSync(tmpAbsPath);
+
+						let tmpOptions = {};
+						if (tmpPageNum > 0)
+						{
+							// pdf-parse pagerender callback for specific page
+							tmpOptions.max = tmpPageNum;
+						}
+
+						tmpPdfParse(tmpBuffer, tmpOptions)
+							.then((pData) =>
+							{
+								pResponse.send(
+								{
+									Success: true,
+									Path: tmpRelPath,
+									PageCount: pData.numpages,
+									Text: pData.text,
+									RequestedPage: tmpPageNum || null
+								});
+								return fNext();
+							})
+							.catch((pPdfError) =>
+							{
+								pResponse.send(500, { Success: false, Error: 'PDF parse failed: ' + pPdfError.message });
+								return fNext();
+							});
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Success: false, Error: pError.message });
+						return fNext();
+					}
+				});
+
 			// --- GET /api/media/metadata ---
 			// Get cached metadata (with ID3/format tags) for a single file.
 			tmpServiceServer.get('/api/media/metadata',
@@ -1307,9 +1483,17 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 
 						let tmpStat = libFs.statSync(tmpEbookPath);
 
+						// Determine content type based on file extension
+						let tmpEbookExt = tmpFilename.replace(/^.*\./, '').toLowerCase();
+						let tmpContentType = 'application/epub+zip';
+						if (tmpEbookExt === 'pdf')
+						{
+							tmpContentType = 'application/pdf';
+						}
+
 						pResponse.writeHead(200,
 						{
-							'Content-Type': 'application/epub+zip',
+							'Content-Type': tmpContentType,
 							'Content-Length': tmpStat.size,
 							'Cache-Control': 'public, max-age=86400'
 						});
@@ -1330,6 +1514,57 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 					}
 				});
 
+			// --- GET /api/media/doc-convert ---
+			// Convert a document (DOC, DOCX, RTF, ODT, WPD, etc.) to PDF.
+			tmpServiceServer.get('/api/media/doc-convert',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpParsedUrl = libUrl.parse(pRequest.url, true);
+						let tmpQuery = tmpParsedUrl.query;
+						let tmpRelPath = tmpQuery.path;
+
+						if (!tmpRelPath || typeof (tmpRelPath) !== 'string')
+						{
+							pResponse.send(400, { Success: false, Error: 'Missing path parameter.' });
+							return fNext();
+						}
+
+						tmpRelPath = decodeURIComponent(tmpRelPath).replace(/^\/+/, '');
+						if (tmpRelPath.includes('..') || libPath.isAbsolute(tmpRelPath))
+						{
+							pResponse.send(400, { Success: false, Error: 'Invalid path.' });
+							return fNext();
+						}
+
+						let tmpAbsPath = libPath.join(tmpContentPath, tmpRelPath);
+						if (!libFs.existsSync(tmpAbsPath))
+						{
+							pResponse.send(404, { Success: false, Error: 'File not found.' });
+							return fNext();
+						}
+
+						tmpEbookService.convertToPdf(tmpAbsPath, tmpRelPath,
+						(pError, pResult) =>
+						{
+							if (pError)
+							{
+								pResponse.send(400, { Success: false, Error: pError.message });
+								return fNext();
+							}
+
+							pResponse.send(pResult);
+							return fNext();
+						});
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Success: false, Error: pError.message });
+						return fNext();
+					}
+				});
+
 			// --- GET /api/media/ebook-metadata ---
 			// Extract and return cached EPUB metadata (TOC, spine, word counts, etc.)
 			tmpServiceServer.get('/api/media/ebook-metadata',
@@ -2146,6 +2381,9 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 						ArchiveService: tmpArchiveService,
 						VideoFrameService: tmpVideoFrameService,
 						AudioWaveformService: tmpAudioWaveformService,
+						SubimageService: tmpSubimageService,
+						CollectionExportService: tmpCollectionExportService,
+						ConversionService: tmpConversionService,
 						PathRegistry: tmpPathRegistry,
 						ParimeCache: tmpParimeCache,
 						MetadataCache: tmpMetadataCache,