retold-remote 0.0.1 → 0.0.2

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

@@ -12,16 +12,21 @@
  * specific endpoints (save, upload) that aren't needed here.
  *
  * @param {object}   pOptions
- * @param {string}   pOptions.ContentPath        - Absolute path to the media folder to browse
- * @param {string}   pOptions.DistPath           - Absolute path to the built web-application folder
- * @param {number}   pOptions.Port               - HTTP port
- * @param {string}   [pOptions.ThumbnailCachePath] - Override thumbnail cache location
- * @param {boolean}  [pOptions.HashedFilenames]    - Enable hashed filenames mode
- * @param {Function} fCallback                   - Callback(pError, { Fable, Orator, Port })
+ * @param {string}   pOptions.ContentPath          - Absolute path to the media folder to browse
+ * @param {string}   pOptions.DistPath             - Absolute path to the built web-application folder
+ * @param {number}   pOptions.Port                 - HTTP port
+ * @param {boolean}  [pOptions.HashedFilenames]      - Enable hashed filenames mode
+ * @param {string}   [pOptions.CacheRoot]            - Root cache directory (default: ./dist/retold-cache/)
+ * @param {string}   [pOptions.CacheThumbnails]      - Override thumbnails cache directory
+ * @param {string}   [pOptions.CacheArchives]        - Override archives cache directory
+ * @param {string}   [pOptions.CacheVideoFrames]     - Override video-frames cache directory
+ * @param {string}   [pOptions.CacheAudioWaveforms]  - Override audio-waveforms cache directory
+ * @param {Function} fCallback                     - Callback(pError, { Fable, Orator, Port })
  */
 
 const libFs = require('fs');
 const libPath = require('path');
+const libChildProcess = require('child_process');
 
 const libFable = require('fable');
 const libOrator = require('orator');
@@ -30,6 +35,11 @@ const libFileBrowserService = require('pict-section-filebrowser').FileBrowserSer
 
 const libRetoldRemoteMediaService = require('../server/RetoldRemote-MediaService.js');
 const libRetoldRemotePathRegistry = require('../server/RetoldRemote-PathRegistry.js');
+const libRetoldRemoteArchiveService = require('../server/RetoldRemote-ArchiveService.js');
+const libRetoldRemoteVideoFrameService = require('../server/RetoldRemote-VideoFrameService.js');
+const libRetoldRemoteAudioWaveformService = require('../server/RetoldRemote-AudioWaveformService.js');
+const libRetoldRemoteEbookService = require('../server/RetoldRemote-EbookService.js');
+const libUrl = require('url');
 
 function setupRetoldRemoteServer(pOptions, fCallback)
 {
@@ -79,11 +89,63 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 		tmpFable.log.info('Hashed filenames mode: ENABLED');
 	}
 
+	// --- Resolve cache paths ---
+	// Default root: ./dist/retold-cache/ relative to process cwd.
+	// Individual overrides take precedence over root.
+	let tmpCacheRoot = pOptions.CacheRoot
+		|| libPath.resolve(process.cwd(), 'dist', 'retold-cache');
+
+	let tmpCacheThumbnails = pOptions.CacheThumbnails
+		|| libPath.join(tmpCacheRoot, 'thumbnails');
+	let tmpCacheArchives = pOptions.CacheArchives
+		|| libPath.join(tmpCacheRoot, 'archives');
+	let tmpCacheVideoFrames = pOptions.CacheVideoFrames
+		|| libPath.join(tmpCacheRoot, 'video-frames');
+	let tmpCacheAudioWaveforms = pOptions.CacheAudioWaveforms
+		|| libPath.join(tmpCacheRoot, 'audio-waveforms');
+	let tmpCacheEbooks = pOptions.CacheEbooks
+		|| libPath.join(tmpCacheRoot, 'ebook-conversions');
+
+	tmpFable.log.info(`Cache root: ${tmpCacheRoot}`);
+	tmpFable.log.info(`  Thumbnails:       ${tmpCacheThumbnails}`);
+	tmpFable.log.info(`  Archives:         ${tmpCacheArchives}`);
+	tmpFable.log.info(`  Video frames:     ${tmpCacheVideoFrames}`);
+	tmpFable.log.info(`  Audio waveforms:  ${tmpCacheAudioWaveforms}`);
+	tmpFable.log.info(`  Ebook conversions: ${tmpCacheEbooks}`);
+
+	// Set up the archive service
+	let tmpArchiveService = new libRetoldRemoteArchiveService(tmpFable,
+	{
+		ContentPath: tmpContentPath,
+		CachePath: tmpCacheArchives
+	});
+
+	// Set up the video frame service
+	let tmpVideoFrameService = new libRetoldRemoteVideoFrameService(tmpFable,
+	{
+		ContentPath: tmpContentPath,
+		CachePath: tmpCacheVideoFrames
+	});
+
+	// Set up the audio waveform service
+	let tmpAudioWaveformService = new libRetoldRemoteAudioWaveformService(tmpFable,
+	{
+		ContentPath: tmpContentPath,
+		CachePath: tmpCacheAudioWaveforms
+	});
+
+	// Set up the ebook conversion service
+	let tmpEbookService = new libRetoldRemoteEbookService(tmpFable,
+	{
+		ContentPath: tmpContentPath,
+		CachePath: tmpCacheEbooks
+	});
+
 	// Set up the media service
 	let tmpMediaService = new libRetoldRemoteMediaService(tmpFable,
 	{
 		ContentPath: tmpContentPath,
-		ThumbnailCachePath: pOptions.ThumbnailCachePath || null,
+		ThumbnailCachePath: tmpCacheThumbnails,
 		APIRoutePrefix: '/api/media',
 		PathRegistry: tmpPathRegistry
 	});
@@ -133,7 +195,22 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 					pResponse.send(
 					{
 						Success: true,
-						HashedFilenames: tmpHashedFilenames
+						HashedFilenames: tmpHashedFilenames,
+						CachePaths:
+						{
+							Root: tmpCacheRoot,
+							Thumbnails: tmpCacheThumbnails,
+							Archives: tmpCacheArchives,
+							VideoFrames: tmpCacheVideoFrames,
+							AudioWaveforms: tmpCacheAudioWaveforms
+						},
+						ArchiveSupport:
+						{
+							Enabled: true,
+							Has7z: tmpArchiveService.has7z,
+							NativeZipOnly: !tmpArchiveService.has7z,
+							SupportedExtensions: tmpArchiveService.getSupportedExtensions()
+						}
 					});
 					return fNext();
 				});
@@ -178,6 +255,49 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 					});
 			}
 
+			// Archive annotation middleware: wrap /api/filebrowser/list responses to
+			// change Type: 'file' to Type: 'archive' for entries with archive extensions.
+			// This makes archive files appear as navigable containers to the client.
+			tmpServiceServer.server.use(
+				(pRequest, pResponse, fNext) =>
+				{
+					if (!pRequest.url.startsWith('/api/filebrowser/list'))
+					{
+						return fNext();
+					}
+
+					let tmpOriginalSendArchive = pResponse.send.bind(pResponse);
+					let tmpSendWrapped = pResponse.send;
+
+					// Wrap send — there may already be a wrapper from hashed filenames.
+					// We chain on top of whatever send is currently set.
+					let tmpPreviousSend = pResponse.send;
+					pResponse.send = function (pStatusOrData, pData)
+					{
+						let tmpFileList = (typeof (pStatusOrData) === 'number') ? pData : pStatusOrData;
+
+						if (Array.isArray(tmpFileList))
+						{
+							for (let i = 0; i < tmpFileList.length; i++)
+							{
+								let tmpEntry = tmpFileList[i];
+								if (tmpEntry.Type === 'file' && tmpEntry.Extension)
+								{
+									if (tmpArchiveService.isArchiveFile(tmpEntry.Extension)
+										&& tmpArchiveService.canHandle(tmpEntry.Extension))
+									{
+										tmpEntry.Type = 'archive';
+									}
+								}
+							}
+						}
+
+						return tmpPreviousSend.call(pResponse, pStatusOrData, pData);
+					};
+
+					return fNext();
+				});
+
 			// Connect file browser API routes
 			tmpFileBrowser.connectRoutes();
 
@@ -203,6 +323,473 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			// Connect media service API routes
 			tmpMediaService.connectRoutes(tmpServiceServer);
 
+			// --- GET /api/media/video-frames ---
+			// Extract evenly-spaced frames from a video for the Video Explorer.
+			tmpServiceServer.get('/api/media/video-frames',
+				(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();
+						}
+
+						// Sanitize
+						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();
+						}
+
+						tmpVideoFrameService.extractFrames(tmpAbsPath, tmpRelPath,
+						{
+							count: tmpQuery.count,
+							width: tmpQuery.width,
+							height: tmpQuery.height,
+							format: tmpQuery.format
+						},
+						(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/video-frame/:cacheKey/:filename ---
+			// Serve a single cached video frame image.
+			tmpServiceServer.get('/api/media/video-frame/:cacheKey/:filename',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpCacheKey = pRequest.params.cacheKey;
+						let tmpFilename = pRequest.params.filename;
+
+						let tmpFramePath = tmpVideoFrameService.getFramePath(tmpCacheKey, tmpFilename);
+
+						if (!tmpFramePath)
+						{
+							pResponse.send(404, { Success: false, Error: 'Frame not found.' });
+							return fNext();
+						}
+
+						let tmpStat = libFs.statSync(tmpFramePath);
+						let tmpExt = libPath.extname(tmpFilename).toLowerCase();
+						let tmpMimeTypes = { '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.webp': 'image/webp' };
+						let tmpMime = tmpMimeTypes[tmpExt] || 'image/jpeg';
+
+						pResponse.writeHead(200,
+						{
+							'Content-Type': tmpMime,
+							'Content-Length': tmpStat.size,
+							'Cache-Control': 'public, max-age=86400'
+						});
+
+						let tmpStream = libFs.createReadStream(tmpFramePath);
+						tmpStream.pipe(pResponse);
+						tmpStream.on('end', () => { return fNext(false); });
+						tmpStream.on('error', () =>
+						{
+							pResponse.send(500, { Error: 'Failed to serve frame.' });
+							return fNext(false);
+						});
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Success: false, Error: pError.message });
+						return fNext();
+					}
+				});
+
+			// --- GET /api/media/video-frame-at ---
+			// Extract a single frame at an arbitrary timestamp (for timeline click).
+			tmpServiceServer.get('/api/media/video-frame-at',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpParsedUrl = libUrl.parse(pRequest.url, true);
+						let tmpQuery = tmpParsedUrl.query;
+						let tmpRelPath = tmpQuery.path;
+						let tmpCacheKey = tmpQuery.cacheKey;
+						let tmpTimestamp = parseFloat(tmpQuery.timestamp);
+
+						if (!tmpRelPath || typeof (tmpRelPath) !== 'string')
+						{
+							pResponse.send(400, { Success: false, Error: 'Missing path parameter.' });
+							return fNext();
+						}
+						if (!tmpCacheKey || typeof (tmpCacheKey) !== 'string')
+						{
+							pResponse.send(400, { Success: false, Error: 'Missing cacheKey parameter.' });
+							return fNext();
+						}
+						if (isNaN(tmpTimestamp) || tmpTimestamp < 0)
+						{
+							pResponse.send(400, { Success: false, Error: 'Invalid timestamp.' });
+							return fNext();
+						}
+
+						// Sanitize
+						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();
+						}
+
+						tmpVideoFrameService.extractSingleFrame(tmpAbsPath, tmpCacheKey, tmpTimestamp,
+						{
+							width: tmpQuery.width,
+							height: tmpQuery.height,
+							format: tmpQuery.format
+						},
+						(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/audio-waveform ---
+			// Extract waveform peak data from an audio file for the Audio Explorer.
+			tmpServiceServer.get('/api/media/audio-waveform',
+				(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();
+						}
+
+						// Sanitize
+						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();
+						}
+
+						tmpAudioWaveformService.extractWaveform(tmpAbsPath, tmpRelPath,
+						{
+							peaks: tmpQuery.peaks
+						},
+						(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/audio-segment ---
+			// Extract an audio sub-clip for remote playback.
+			tmpServiceServer.get('/api/media/audio-segment',
+				(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();
+						}
+
+						// Sanitize
+						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();
+						}
+
+						tmpAudioWaveformService.extractSegment(tmpAbsPath, tmpRelPath,
+						{
+							start: tmpQuery.start,
+							end: tmpQuery.end,
+							format: tmpQuery.format
+						},
+						(pError, pResult) =>
+						{
+							if (pError)
+							{
+								pResponse.send(400, { Success: false, Error: pError.message });
+								return fNext();
+							}
+
+							// Stream the segment file back
+							try
+							{
+								let tmpSegPath = pResult.SegmentPath;
+								let tmpSegStat = libFs.statSync(tmpSegPath);
+								let tmpMimeMap = { 'mp3': 'audio/mpeg', 'aac': 'audio/aac', 'ogg': 'audio/ogg', 'wav': 'audio/wav', 'flac': 'audio/flac' };
+								let tmpMime = tmpMimeMap[pResult.Format] || 'audio/mpeg';
+
+								pResponse.writeHead(200,
+								{
+									'Content-Type': tmpMime,
+									'Content-Length': tmpSegStat.size,
+									'Cache-Control': 'public, max-age=86400',
+									'Content-Disposition': `inline; filename="segment_${pResult.Start.toFixed(0)}-${pResult.End.toFixed(0)}.${pResult.Format}"`
+								});
+
+								let tmpStream = libFs.createReadStream(tmpSegPath);
+								tmpStream.pipe(pResponse);
+								tmpStream.on('end', () => { return fNext(false); });
+								tmpStream.on('error', () =>
+								{
+									pResponse.send(500, { Error: 'Failed to serve segment.' });
+									return fNext(false);
+								});
+							}
+							catch (pStreamError)
+							{
+								pResponse.send(500, { Success: false, Error: pStreamError.message });
+								return fNext();
+							}
+						});
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Success: false, Error: pError.message });
+						return fNext();
+					}
+				});
+
+			// --- GET /api/media/ebook-convert ---
+			// Convert an ebook (MOBI, AZW, etc.) to EPUB for in-browser reading.
+			tmpServiceServer.get('/api/media/ebook-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();
+						}
+
+						// Sanitize
+						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.convertToEpub(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/:cacheKey/:filename ---
+			// Serve a cached converted ebook file.
+			tmpServiceServer.get('/api/media/ebook/:cacheKey/:filename',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpCacheKey = pRequest.params.cacheKey;
+						let tmpFilename = pRequest.params.filename;
+
+						let tmpEbookPath = tmpEbookService.getConvertedPath(tmpCacheKey, tmpFilename);
+
+						if (!tmpEbookPath)
+						{
+							pResponse.send(404, { Success: false, Error: 'Ebook not found.' });
+							return fNext();
+						}
+
+						let tmpStat = libFs.statSync(tmpEbookPath);
+
+						pResponse.writeHead(200,
+						{
+							'Content-Type': 'application/epub+zip',
+							'Content-Length': tmpStat.size,
+							'Cache-Control': 'public, max-age=86400'
+						});
+
+						let tmpStream = libFs.createReadStream(tmpEbookPath);
+						tmpStream.pipe(pResponse);
+						tmpStream.on('end', () => { return fNext(false); });
+						tmpStream.on('error', () =>
+						{
+							pResponse.send(500, { Error: 'Failed to serve ebook.' });
+							return fNext(false);
+						});
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Success: false, Error: pError.message });
+						return fNext();
+					}
+				});
+
+			// --- POST /api/media/open ---
+			// Open a media file with an external application (e.g. VLC).
+			tmpServiceServer.post('/api/media/open',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpBody = pRequest.body || {};
+						let tmpRelPath = tmpBody.path;
+
+						if (!tmpRelPath || typeof (tmpRelPath) !== 'string')
+						{
+							pResponse.send(400, { Success: false, Error: 'Missing or invalid path.' });
+							return fNext();
+						}
+
+						// Sanitize: no absolute paths, no directory traversal
+						if (tmpRelPath.indexOf('..') !== -1 || libPath.isAbsolute(tmpRelPath))
+						{
+							pResponse.send(400, { Success: false, Error: 'Invalid path.' });
+							return fNext();
+						}
+
+						let tmpAbsPath = libPath.join(tmpContentPath, tmpRelPath);
+
+						// Verify file exists
+						if (!libFs.existsSync(tmpAbsPath))
+						{
+							pResponse.send(404, { Success: false, Error: 'File not found.' });
+							return fNext();
+						}
+
+						// Determine the open command based on platform
+						let tmpSpawnArgs;
+						if (process.platform === 'darwin')
+						{
+							tmpSpawnArgs = ['open', ['-a', 'VLC', tmpAbsPath]];
+						}
+						else
+						{
+							tmpSpawnArgs = ['vlc', [tmpAbsPath]];
+						}
+
+						let tmpChild = libChildProcess.spawn(tmpSpawnArgs[0], tmpSpawnArgs[1],
+						{
+							detached: true,
+							stdio: 'ignore'
+						});
+						tmpChild.unref();
+
+						pResponse.send({ Success: true });
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Success: false, Error: pError.message });
+					}
+					return fNext();
+				});
+
 			// Content-hashed URL rewrite: resolve /content-hashed/<hash>
 			// to /content/<resolved-path> so the static route serves the file.
 			// Uses server.pre() to rewrite BEFORE route matching.
@@ -232,6 +819,198 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 					});
 			}
 
+			// Archive file listing: intercept /api/filebrowser/list requests
+			// where the path crosses into an archive.  Uses server.pre() to
+			// respond before the normal file browser route handler.
+			tmpServiceServer.server.pre(
+				(pRequest, pResponse, fNext) =>
+				{
+					if (!pRequest.url.startsWith('/api/filebrowser/list'))
+					{
+						return fNext();
+					}
+
+					let tmpParsedUrl = libUrl.parse(pRequest.url, true);
+					let tmpPathParam = (tmpParsedUrl.query && tmpParsedUrl.query.path) || '';
+
+					// Resolve hash to path if hashed filenames is enabled
+					// (server.pre runs before server.use middleware, so hash resolution hasn't happened yet)
+					if (tmpHashedFilenames && /^[a-f0-9]{10}$/.test(tmpPathParam))
+					{
+						let tmpResolved = tmpPathRegistry.resolve(tmpPathParam);
+						if (tmpResolved !== null)
+						{
+							tmpPathParam = tmpResolved;
+						}
+					}
+
+					let tmpArchiveInfo = tmpArchiveService.parseArchivePath(tmpPathParam);
+
+					if (!tmpArchiveInfo)
+					{
+						return fNext();
+					}
+
+					let tmpArchiveAbsPath = libPath.join(tmpContentPath, tmpArchiveInfo.archivePath);
+
+					if (!libFs.existsSync(tmpArchiveAbsPath))
+					{
+						pResponse.send(404, { Error: 'Archive not found.' });
+						return fNext(false);
+					}
+
+					tmpArchiveService.listContents(
+						tmpArchiveAbsPath, tmpArchiveInfo.innerPath, tmpArchiveInfo.archivePath,
+						(pError, pFileList) =>
+						{
+							if (pError)
+							{
+								pResponse.send(400, { Error: pError.message });
+								return fNext(false);
+							}
+
+							// Annotate with hashes if enabled
+							if (tmpHashedFilenames)
+							{
+								tmpPathRegistry.annotateFileList(pFileList);
+
+								// Register the archive inner path as a folder
+								let tmpFolderPath = tmpArchiveInfo.innerPath
+									? (tmpArchiveInfo.archivePath + '/' + tmpArchiveInfo.innerPath)
+									: tmpArchiveInfo.archivePath;
+								let tmpFolderHash = tmpPathRegistry.register(tmpFolderPath);
+								pResponse.header('X-Retold-Folder-Hash', tmpFolderHash);
+							}
+
+							pResponse.send(pFileList);
+							return fNext(false);
+						});
+				});
+
+			// Archive content serving: intercept /content/* requests that cross
+			// into an archive.  Extracts the file to cache and streams it back.
+			tmpServiceServer.server.pre(
+				(pRequest, pResponse, fNext) =>
+				{
+					if (!pRequest.url.startsWith('/content/'))
+					{
+						return fNext();
+					}
+
+					let tmpRelPath = decodeURIComponent(pRequest.url.replace(/^\/content\//, ''));
+					let tmpArchiveInfo = tmpArchiveService.parseArchivePath(tmpRelPath);
+
+					if (!tmpArchiveInfo || !tmpArchiveInfo.innerPath)
+					{
+						return fNext();
+					}
+
+					let tmpArchiveAbsPath = libPath.join(tmpContentPath, tmpArchiveInfo.archivePath);
+
+					tmpArchiveService.extractFile(
+						tmpArchiveAbsPath, tmpArchiveInfo.innerPath,
+						(pError, pCachedPath) =>
+						{
+							if (pError || !pCachedPath)
+							{
+								pResponse.send(404, { Error: 'Could not extract file from archive.' });
+								return fNext(false);
+							}
+
+							// Stream the cached file
+							try
+							{
+								let tmpStat = libFs.statSync(pCachedPath);
+								let tmpExt = libPath.extname(pCachedPath).toLowerCase();
+								let tmpMime = tmpArchiveService.getMimeType(tmpExt);
+
+								pResponse.writeHead(200,
+								{
+									'Content-Type': tmpMime,
+									'Content-Length': tmpStat.size,
+									'Cache-Control': 'public, max-age=3600'
+								});
+
+								let tmpStream = libFs.createReadStream(pCachedPath);
+								tmpStream.pipe(pResponse);
+								tmpStream.on('end', () => { return fNext(false); });
+								tmpStream.on('error', () =>
+								{
+									pResponse.send(500, { Error: 'Failed to serve extracted file.' });
+									return fNext(false);
+								});
+							}
+							catch (pStreamError)
+							{
+								pResponse.send(500, { Error: pStreamError.message });
+								return fNext(false);
+							}
+						});
+				});
+
+			// Archive-aware thumbnail/probe: intercept /api/media/thumbnail and
+			// /api/media/probe requests for files inside archives.  Extracts the
+			// file to cache first, then rewrites the URL to point at the cached
+			// copy so the normal MediaService handler processes it.
+			tmpServiceServer.server.pre(
+				(pRequest, pResponse, fNext) =>
+				{
+					if (!pRequest.url.startsWith('/api/media/thumbnail')
+						&& !pRequest.url.startsWith('/api/media/probe'))
+					{
+						return fNext();
+					}
+
+					let tmpParsedUrl = libUrl.parse(pRequest.url, true);
+					let tmpPathParam = (tmpParsedUrl.query && tmpParsedUrl.query.path) || '';
+
+					// Resolve hash to path if hashed filenames is enabled
+					if (tmpHashedFilenames && /^[a-f0-9]{10}$/.test(tmpPathParam))
+					{
+						let tmpResolved = tmpPathRegistry.resolve(tmpPathParam);
+						if (tmpResolved !== null)
+						{
+							tmpPathParam = tmpResolved;
+						}
+					}
+
+					let tmpArchiveInfo = tmpArchiveService.parseArchivePath(tmpPathParam);
+
+					if (!tmpArchiveInfo || !tmpArchiveInfo.innerPath)
+					{
+						return fNext();
+					}
+
+					let tmpArchiveAbsPath = libPath.join(tmpContentPath, tmpArchiveInfo.archivePath);
+
+					tmpArchiveService.extractFile(
+						tmpArchiveAbsPath, tmpArchiveInfo.innerPath,
+						(pError, pCachedPath) =>
+						{
+							if (pError || !pCachedPath)
+							{
+								pResponse.send(404, { Error: 'Could not extract file from archive.' });
+								return fNext(false);
+							}
+
+							// Rewrite the path query param to point at the cached file
+							// relative to the content root.  The MediaService resolves
+							// paths relative to ContentPath, so we need to compute the
+							// relative path from contentPath to the cached file.
+							let tmpRelCached = libPath.relative(tmpContentPath, pCachedPath);
+
+							tmpParsedUrl.query.path = tmpRelCached;
+							delete tmpParsedUrl.search;
+							pRequest.url = libUrl.format(tmpParsedUrl);
+							if (pRequest.query)
+							{
+								pRequest.query.path = tmpRelCached;
+							}
+
+							return fNext();
+						});
+				});
+
 			// Serve content files at /content/ (for direct media access)
 			tmpOrator.addStaticRoute(`${tmpContentPath}/`, 'index.html', '/content/*', '/content/');
 
@@ -247,6 +1026,9 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 						Fable: tmpFable,
 						Orator: tmpOrator,
 						MediaService: tmpMediaService,
+						ArchiveService: tmpArchiveService,
+						VideoFrameService: tmpVideoFrameService,
+						AudioWaveformService: tmpAudioWaveformService,
 						PathRegistry: tmpPathRegistry,
 						Port: tmpPort
 					});