BlueGit

timfa filemanager

Files

filemanager / .github / technical-reference.md

technical-reference.md

dd321017 History
technical-reference.md 54.5 KiB Download Raw

Technical Reference

installsystemdservice.sh

  • bool_is_true(value) - Parses common truthy string values used for installer feature flags.
  • confirm_root_service_mode() - Interactive installer prompt ([y/N]) that decides whether the service should run as root when no env override is provided.
  • FILEMANAGER_SERVICE_RUN_AS_ROOT - Optional installer env override for non-interactive installs; when truthy, writes a root-running systemd unit (omits User=) and enables FILEMANAGER_LIST_ACCESS_CHMOD in the unit environment.

server/index.js

  • start() - Initialises DB/keys, starts HTTP/HTTPS servers, and starts the background thumbnail cache loop.
  • shutdown(opts, ...servers) - Graceful teardown: stops thumbnail loop, closes DB/servers, exits with configurable code after drain/timeout.
  • Express error handler - Logs uncaught route errors to logs.txt before returning a JSON 500 response.
  • GET /share/:token - Calls buildShareOpenGraphPage to serve share.html with injected OG meta tags for all visitors; social media crawlers see rich preview data, browsers get the full interactive page.

server/logger.js

  • logError(message, error, details) - Appends error lines to logs.txt, trimming old lines so the file stays under 1 MB; use for route failures and process-level exceptions.

server/subtitle-debug-log.js

  • appendSubtitleDebugEntries({ videoName, entries, context }) - Appends client-side subtitle timing events to a timestamped per-video text log under the local temp cache (<unix-ms>-videoname-subtitlelog.txt), reusing one file per playback context and pruning the oldest files when the subtitle log cache exceeds 10 MB.
  • getSubtitleDebugLogSnapshot() - Reports the subtitle log cache directory path, existence, file count, byte total, and latest file so the debug dashboard can expose it as a folder.
  • pruneSubtitleDebugLogDir() - Enforces the 10 MB total subtitle-log cache budget by deleting the oldest log files first.
  • subtitleLogFileByContext (LRU) - In-memory context-to-logfile mapping is trimmed with SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX (default 512, capped at 4096) to prevent unbounded session-key growth.
  • subtitleDebugLogFilePath(videoName, timestampMs) - Resolves the timestamped subtitle timing log path for a video name using a filesystem-safe filename.

server/image-subtitles.js

  • parseRenderOptions(options) - Normalises subtitle-frame request options and validates filePath/streamIndex/time/canvas dimensions; stream index 0 is valid and must not be treated as missing; canvas is scaled down within a 1280x720 ceiling, then multiplied by IMAGE_SUBTITLE_RENDER_SCALE (default 0.75) while preserving requested aspect ratio.
  • renderImageSubtitleFrame(options) - Extracts bitmap subtitle streams to cached .sup, parses PGS display sets, and returns {frame: PNG buffer, left, top, width, height, canvasWidth, canvasHeight} with metadata for proper client-side upscaling; the server preserves positioning info instead of throwing it away, allowing the client to calculate percentage-based sizing for downscaled frames; cold event-cache builds now continue in the background while requests return quickly with no frame (null) until parsing finishes, avoiding long-hanging subtitle frame requests after cache purge; request/build/render timing counters are tracked for debug diagnostics.
  • clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path using path-prefixed cache keys, also deletes the corresponding .sup file from disk for each evicted event entry; called when video stream sessions end to prevent memory and disk accumulation.
  • pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame caches for events that have passed their retention threshold of end time + event duration + 5 seconds (e.g., event ending at 30s with 10s duration is dropped after slowest viewer reaches 45s); used during segment pruning to keep memory usage bounded on long videos, especially on resource-limited hardware like Raspberry Pi.
  • purgeSubtitleCacheDir() - Removes the entire subtitle .sup file cache directory from disk; called once at server startup to clean up any files left over from a previous run.
  • touchCachedEntry(cache, key, ttlMs) - Refreshes the TTL of an existing cache entry without changing its value; used to keep actively-watched subtitle tracks alive past their initial 5-minute TTL and prevent expensive full re-parses during long playback sessions.
  • getImageSubtitleDebugSnapshot() - Returns event/frame cache totals, timing counters (cache hits/misses, event build timing, frame render/request timing), and per-video cache usage ({event entries/bytes/count, frame entries/bytes}) so admin diagnostics can distinguish cache-thrash or cold-parse stalls from steady-state rendering.
  • IMAGE_SUBTITLE_EVENT_CACHE_TTL_MS / IMAGE_SUBTITLE_FRAME_CACHE_TTL_MS / IMAGE_SUBTITLE_EVENT_CACHE_MAX_ITEMS / IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS / IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES / IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES / IMAGE_SUBTITLE_RENDER_SCALE / IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS - Environment knobs for subtitle cache retention, optional item caps (0/unbounded disables the cap so byte limits govern), byte caps, render resolution, and prune grace window.

server/thumbnail-cache.js

  • syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files, video files (ffprobe/ffmpeg frame at ~10%), and 3D model files (STL/OBJ, isometric SVG projection via Sharp); removes stale thumbnails and updates manifest hashes.
  • startThumbnailCacheLoop() - Schedules cache sync runs with adaptive cadence: default 5s when idle and heavily throttled while active streams exist (THUMBNAIL_CACHE_ACTIVE_STREAM_DELAY_MS, default 120000 ms).
  • stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
  • getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
  • getThumbPathForSourceFile(sourceFile) - Maps an absolute source file path to its mirrored cache thumbnail path.
  • getThumbRelPathForSourceFile(sourceFile) - Returns public-relative thumbnail path used in manifest entries.
  • getFilesWithThumbnailsInDir(dirPath) - Returns [{filePath, thumbRelPath}] for all files inside dirPath (recursive) that have a cached thumbnail; sorted by filePath.
  • getFolderIconSourceFile(folderPath) - Returns the source image path for a folder's icon: explicit assignment first, then auto-first cached image, null if none.
  • setFolderIconAssignment(folderPath, imagePath) - Saves an explicit folder icon assignment to .folder-icons.json; pass null to clear (auto-detect used instead).

server/db.js

  • initDb() - Initializes SQLite schema for users, file metadata (including watched_by), and auth_sessions (idle timeout/revocation support), and migrates watched_by for existing DB files.
  • getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
  • closeDb() - Closes singleton DB handle to release file locks.

server/auth.js

  • createToken(username, req, fingerprint) - Creates JWT bound to IP/region/fingerprint and linked to a DB-backed session id.
  • requireAuth(req, res, next) - Verifies JWT + binding + session row + 1-hour idle timeout, updates last_seen_at, and attaches req.user.
  • requireAdmin(req, res, next) - Requires authenticated admin user.
  • revokeSession(sessionId) - Revokes a session row so future token use fails immediately.
  • getClientIp(req) - Normalizes request IP (including IPv4-mapped IPv6 loopback cases).
  • getRegion(ip) - Derives coarse region binding from geoip lookup or local fallback.
  • SESSION_IDLE_TIMEOUT_MS - Server-enforced idle timeout window (1 hour).

server/routes/auth.js

  • extractCredentials(body) - Accepts encrypted payloads and compatibility plaintext payloads for login/setup.
  • makeAuthResponse(token, clientPublicKey) - Returns encrypted token when client key exists, plaintext token otherwise.
  • POST /api/auth/setup - Creates first admin and issues token.
  • POST /api/auth/login - Authenticates user by case-insensitive username match and issues token with canonical stored username.
  • GET /api/auth/me - Returns current authenticated user profile.
  • POST /api/auth/logout - Revokes the active session.
  • POST /api/auth/change-password - Authenticated password change using current-password verification and minimum-length validation.

server/routes/admin.js

  • POST /api/admin/users - Creates a new user and enforces case-insensitive username uniqueness.
  • PATCH /api/admin/users/:id - Updates user password/admin flag/permissions; rejects self-demotion and still blocks removing the last admin account.
  • GET /api/admin/orphan-userfolders - Returns non-empty user folders under userPath that no longer match any account, and auto-deletes empty orphan folders.
  • DELETE /api/admin/users/:id - Also removes the deleted user's personal folder when it exists and is empty.
  • normalizePermissions(permissions) - Normalizes permission maps and enforces that write access implies read access.
  • ensureUserFolders(userPath) - Ensures configured userPath exists and creates per-user subfolders for all current users.
  • GET /api/admin/config - Returns admin config including userPath and userFolderSizeLimit (bytes, null for unlimited).
  • PUT /api/admin/config - Persists paths plus userPath/userFolderSizeLimit and ensures per-user folders exist.
  • GET /api/admin/update-status - Returns { underSystemd, commitsAhead[] } where commitsAhead contains non-merge commits as {hash, subject, body}; detects systemd via INVOCATION_ID env var and runs git fetch + git log against origin/HEAD for Restart & Update messaging.
  • GET /api/admin/debug/stream-stats - Admin diagnostics payload with active signed-in users, per-root storage usage, active stream HLS footprint, subtitle cache totals, and per-video rows that also include cached-only videos with zero active viewers.

server/routes/debug.js

  • GET /api/admin/debug/stream-stats - Computes debug dashboard data by combining auth_sessions activity, root disk usage scans, stream snapshot data, and subtitle cache snapshot data into a per-video view for leak/performance monitoring.
  • GET /api/admin/debug/stream-stats - Also reports host/process memory ({total, free, used, usedPercent, processRssBytes, processHeapUsedBytes}) so streaming lag can be correlated with RAM pressure.
  • GET /api/admin/debug/stream-stats - Also reports the subtitle debug cache directory metadata so admins can open the local subtitle log folder from the debug dashboard.

server/routes/files.js

  • GET /api/files/roots - Returns readable roots with display label (alias when configured), originalName, and path.
  • GET /api/files/roots - Adds a synthetic 'My folder' root for the authenticated user when userPath is configured.
  • loadConfigAndRoots() - Loads config and effective roots together so route access checks stay consistent.
  • parseOctalMode(rawValue, fallback) - Parses optional octal chmod mode overrides from environment variables and falls back to secure defaults when invalid.
  • envFlagEnabled(name) - Boolean environment flag parser for file-route runtime feature toggles.
  • applyListAccessChmod(startDir) - Best-effort shallow chmod pass for folder-access requests; updates the opened folder and its direct children only, skips symlinks, and continues past individual errors.
  • resolveRootForUser(absPath, roots, user, config) - Resolves access for configured roots plus user-owned personal folder.
  • resolveRootForUser(absPath, roots, user, config) - Allows admins to access orphaned user folders (deleted-account folders) under userPath.
  • resolveRootForUser(absPath, roots, user, config) - Treats the local subtitle debug log directory as an admin-only debug root for browse and maintenance actions from the debug menu.
  • canReadInfo(user, info) / canWriteInfo(user, info) - Permission checks that automatically allow access for personal user-folder roots.
  • checkUserFolderSizeLimit(config, username, addedBytes) - Validates a user-folder capacity limit against current usage.
  • POST /api/files/root-alias - Sets a display-only alias for an exact configured root path (no filesystem rename).
  • GET /api/files/root-access - Returns users who can access an exact configured root and their access mode (R / R+W).
  • GET /api/files/meta - Returns file metadata and lazily computes/stores sha256 when missing.
  • GET /api/files/duplicates - Returns accessible files that share the selected file's sha256 hash.
  • GET /api/files/space - Returns used/free disk space and, for personal folders, user-limit fields (userLimitBytes/userFreeBytes).
  • GET /api/files/thumbnail - Serves cache-only thumbnail images for authorized files; returns 404 while cache is not ready.
  • GET /api/files/folder-images - Returns files inside a directory (recursive) that already have a cached thumbnail (including video thumbnails when cached).
  • GET /api/files/folder-icon - Returns the current icon source file for a folder ({icon:{filePath}} or {icon:null}); explicit assignment takes priority over auto-first.
  • POST /api/files/folder-icon - Sets or clears a folder's explicit icon assignment; imagePath must have a cached thumbnail; write access required.
  • GET /api/files/search - Fuzzy-searches all readable roots (and personal folder when configured) for files, returning ranked matches with path metadata.
  • GET /api/files/list - Returns directory items including name/path/isDir plus size, mtime, and uploadedAt; uploadedAt comes from persisted file_meta.uploaded_at when present, otherwise it is backfilled from filesystem creation/change metadata and saved.
  • GET /api/files/list - When FILEMANAGER_LIST_ACCESS_CHMOD=1, runs a best-effort shallow chmod on the opened folder before listing (opened folder + direct children only; defaults: dirs 0777, files 0666; overrides via FILEMANAGER_LIST_ACCESS_CHMOD_DIR_MODE and FILEMANAGER_LIST_ACCESS_CHMOD_FILE_MODE).
  • GET /api/files/search-images - Fuzzy-searches readable roots for image files with ready thumbnails, returning capped results plus scan-truncation metadata for scalable global favicon selection.
  • GET /api/files/global-favicon-image - Publicly serves the configured global favicon thumbnail file so browsers can load <link rel="icon"> without auth headers.
  • GET /api/files/global-favicon - Returns the configured global favicon source file path ({favicon:{filePath}} or {favicon:null}).
  • POST /api/files/global-favicon - Admin-only route that sets or clears the global favicon source image; image must have a cached thumbnail.
  • GET /api/files/download-zip?dir=<absolute-path> - Authenticated. Streams the directory as a zip archive; caches the zip for up to 1 day in zip-cache/.
  • makeTempUploadPath(dir, originalName) - Builds a hidden per-upload staging filename in the target directory for multipart uploads.
  • unlinkIfExists(targetPath, cb) - Removes a file during upload cleanup while ignoring already-missing temp files.
  • promoteUploadedFile(tempPath, finalPath, cb) - Atomically renames a completed staged upload into place on the Linux server.
  • splitNameExt(name) - Splits a filename into stem/ext, preserving dotless names and hidden-file behavior.
  • pickNumberedPath(dir, requestedName) - Finds the first free name (n).ext path inside a directory.
  • removePathRecursive(targetPath) - Deletes existing file or directory destination to support overwrite moves.
  • movePathWithFallback(from, dest) - Moves files/folders with an EXDEV copy-then-delete fallback so cross-device moves into My Folder still succeed.
  • rewriteMetaPaths(fromPath, toPath) - Rewrites metadata paths after rename/move while preserving all columns in file_meta (including uploaded_at, watched_by, hashes, and future columns).
  • POST /api/files/upload - Streams multipart uploads into hidden temp files, computes/stores sha256, and enforces user-folder size limits.
  • POST /api/files/upload - Stores authoritative upload timestamp in file_meta.uploaded_at at upload time; this timestamp persists across move/rename through metadata path rewrites.
  • POST /api/files/move - Moves file/folder; supports conflict strategies: error (default), overwrite, or rename with optional targetName.
  • POST /api/files/copy - Copies a file to a destination folder with conflict strategies (error, overwrite, rename) and user-folder size-limit checks.
  • POST /api/files/video-stream - Creates a short-lived HLS session for a video and returns playlistUrl, durationSeconds, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary ({total, converted, imageBased, skipped}).
  • GET /api/files/video-stream-subtitle-frame - Authenticated. Renders a PNG subtitle frame for bitmap subtitle tracks via cached PGS decode/composite flow; returns {frame, left, top, width, height, canvasWidth, canvasHeight}; sends response headers X-Subtitle-Frame-{Left,Top,Width,Height,Canvas-Width,Canvas-Height,Start-Time,End-Time} plus X-Subtitle-{Request-Received-At-Ms,Response-Sent-At-Ms} so the client can log subtitle timing against server send time; on failures or no active subtitle it returns 204 so the client can stop retrying.
  • POST /api/files/video-stream-subtitle-log - Authenticated. Accepts batched client-side subtitle timing events for an authorised file and appends them to the local subtitle debug-log cache with file path, username, and stream session context.
  • DELETE /api/files/video-stream/:sessionId - Explicitly releases an active short-lived video stream session and stops backend processing.
  • POST /api/files/watched-statuses - Returns fast per-user watched statuses for up to 500 file paths without triggering expensive metadata/hash work; response is { statuses: { [filePath]: 'fully'|'partway' } }.
  • POST /api/files/watch-progress - Records per-user watch status (partway >=10%, fully >=70%) for sidebar "Watched by" display.

server/routes/share.js

  • getUserFolderPath(config, username) - Resolves the owning user's personal folder path from config.userPath.
  • resolveRootForUser(absPath, roots, user, config) - Resolves configured roots plus the owning user's personal folder for share checks.
  • canReadInfo(user, info) - Read-check helper that always allows the owner of a personal folder root.
  • POST /api/share/create - Authenticated. Creates a 24-hour share token for a file or directory; returns {token, expiresAt} and accepts items inside the authenticated user's My Folder.
  • GET /api/share/info/:token - Public. Returns {name, isDir, expiresAt} for a valid non-expired token; 410 when expired, 404 when unknown.
  • GET /api/share/preview/:token - Public. Streams file content inline for preview (files only, max 50 MB); 400 for directories, 410 expired.
  • GET /api/share/download/:token - Public. Downloads the file or a zip of the directory for a valid token; 410 expired.
  • GET /api/share/video-stream/:token - Public. Creates a short-lived HLS session for a shared video and returns playlistUrl, durationSeconds, subtitleTracks, imageSubtitleTracks, and subtitleSummary ({total, converted, imageBased, skipped}).
  • GET /api/share/video-stream-subtitle-frame/:token - Public. Renders a PNG subtitle frame for shared-video bitmap subtitle tracks using the same cached PGS decode path as the authenticated player; returns the same subtitle timing headers as the authenticated route and 204 with X-Subtitle-Frame-Status when no frame is active or rendering fails.
  • POST /api/share/video-stream-subtitle-log/:token - Public. Accepts batched client-side subtitle timing events for a valid shared-video token and appends them to the local subtitle debug-log cache with share-token and stream-session context.
  • DELETE /api/share/video-stream/session/:sessionId - Public. Explicitly releases a shared HLS lease so the share page can clean up the backend stream session on close/unload instead of waiting for idle expiry.
  • buildShareOpenGraphPage(token, req) - Reads share.html, injects OG meta tags (<og:title>, <og:description>, <og:image> for image files, twitter:card) based on DB lookup of token, and returns the full HTML string. Handles expired and not-found tokens. Exported and used by the /share/:token route in server/index.js.
  • buildZip(dirPath, cacheKey) - Creates (or returns cached) zip in zip-cache/; prunes stale zips before building; exported for reuse in files.js.
  • pruneZipCache() - Deletes zip files in zip-cache/ older than 1 day; called automatically before each zip build.
  • ZIP_CACHE_DIR - Absolute path to the zip-cache/ directory (project root).

server/video-stream.js

  • createVideoStreamSession(sourcePath) - Probes input metadata and reuses a compatible active transcode session per source file when possible; returns a per-viewer lease id as sessionId plus duration, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary data, including same-name sidecar .srt subtitles converted to WebVTT.
  • sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
  • releaseVideoStreamSession(sessionId) - Releases one viewer lease and destroys the underlying transcode session immediately once lease count drops to zero (even if a response is still finishing) so zero-viewer streams are purged right away; cleanup only clears image subtitle frame/event caches once no other active stream session for the same source file remains.
  • parseSegmentIndexFromAssetPath(assetPath) - Extracts the numeric segment index from an HLS segment filename; matches both numeric variant identifiers (stream_0_segment_000000.ts) and named variants (stream_video_segment_000000.ts, stream_Audio-1-jpn_segment_000000.ts) — ffmpeg substitutes the var_stream_map name: value for %v when named streams are used.
  • runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() using the slowest active viewer across all live sessions for the same source file, so file-wide subtitle buffers are not pruned ahead of a newly started second session; segment deletion now runs in bounded batches and records last prune duration/deleted-segment counts for diagnostics; segment filename regex also uses named-variant pattern to match production filenames correctly.
  • hasInitialHlsAssets(outputDir) - Returns true once master.m3u8 or at least one variant playlist/segment exists in an HLS output directory; accepts named variant filenames (stream_video.m3u8) in addition to numeric ones.
  • purgeStreamRootDir() - Best-effort recursive delete of the temporary HLS stream root; used at startup and by idle sweeps to remove orphaned stream session directories from previous runs.
  • cleanupIdleStreamArtifacts() - Periodic idle-time cleaner that purges stream-root artifacts when there are no active sessions or leases, preventing stale segment directories from accumulating after failures.
  • pruneExpiredSessions() sweep - A dedicated interval sweep (VIDEO_STREAM_EXPIRY_SWEEP_MS, default 60000 ms) reclaims expired leases/sessions even when no new stream requests arrive.
  • getVideoStreamDebugSnapshot() - Returns active stream sessions with viewer counts and output-dir stats (segment counts/bytes), plus orphaned output directories left under the stream root for diagnostics.
  • getVideoStreamDebugSnapshot() - Includes segment retention and prune telemetry per session (segmentRetentionCount, slowestViewerSegmentIndex, segmentPrunedUntil, lastSegmentPrune, streamPruneDeleteBatchSize) to explain growth or cleanup stalls in segment counts.
  • STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
  • STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
  • STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated (5 minutes).
  • STREAM_SEGMENT_RETENTION_COUNT - Number of most-recent HLS segment indices kept on disk while older segments are pruned; when not overridden with VIDEO_STREAM_SEGMENT_RETENTION_COUNT it is derived from hardware capacity (RAM + CPU), current memory/CPU pressure, and Raspberry Pi 5 profile bounds.
  • MAX_STREAM_SEGMENT_RETENTION_COUNT - Upper safety cap for retention (360) to avoid runaway in-session segment growth from oversized overrides.
  • VIDEO_STREAM_PRUNE_DELETE_BATCH_SIZE - Optional environment knob that limits how many old HLS segment files are unlinked in parallel during one prune batch; smaller values reduce I/O spikes at the cost of slower cleanup.

server/db.js

  • initDb() - Initializes SQLite schema for users, file metadata, auth_sessions, and share_tokens (expires_at index).
  • getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
  • closeDb() - Closes singleton DB handle to release file locks.

public/share.html

  • Standalone public share page served at /share/:token; no auth required.
  • Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
  • tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
  • Share video preview - Uses the shared browser video-player helper used by app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), subtitle/audio track restore/save by matching track names, image-subtitle overlay support, and explicit backend session release on unload.
  • Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
  • Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.

public/shared-video-player.js

  • applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
  • bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
  • bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, renders seek-bar triangle markers for last requested caption start time (>) and last received/ready caption start time (<), and disables the track after the first hard failure.
  • configureVideoJsBuffering(videojs, opts) - Applies the long forward-buffer settings used for file playback when VHS exposes those knobs.
  • ensureVideoPlaybackUi(player, durationSeconds) - Forces file streams into VOD UI mode, normalises the reported duration, stops live-tracker state, and hides the live badge when present.

public/index.html

  • Auth form - Login/setup form uses username plus mode-specific password autocomplete tokens so browser password managers behave correctly.
  • Top bar - Places icon-only Refresh to the left of breadcrumb/Home, keeps search input with icon-only search button, and groups actions into Upload/User dropdown triggers.
  • User menu - Includes a Change Password action and a dedicated change-password modal with current/new/confirm fields.
  • User menu - Admin users also get a Debug action that opens a live diagnostics dashboard modal.
  • Admin panel - Includes an icon-only global favicon button that opens the shared icon picker modal.
  • Admin panel - Users section includes a conditional orphaned-user-folders subsection that appears only when non-empty orphan folders exist.
  • Debug dashboard modal - Shows active signed-in users, total/per-root storage usage, active stream footprint, cached subtitle usage by video, and orphaned stream output directories.
  • Debug dashboard modal - Also exposes the subtitle debug cache folder with an open-folder action for admins.
  • Debug dashboard modal - Each diagnostics sub-panel includes a copy action for quick report sharing: users/storage copy JSON, stream/cache and orphaned output tables copy CSV.
  • Debug dashboard modal - Storage cards include RAM usage and process RSS; stream/cache table includes retention and prune progress columns for troubleshooting segment buildup.
  • Admin modal - Includes User Folders controls (user path + per-user size limit) and a dedicated save action for that config.
  • Import map - Maps three and three/addons/ to local vendored modules for client-side STL/OBJ previews.

public/app.js

  • showApp() - Reveals app shell; keeps sidebar folded by default on mobile and shows folder overview sidebar on desktop.
  • showAuthOverlay(setupMode) - Displays the login/setup overlay and switches the password autocomplete token between current-password and new-password based on mode.
  • getOrCreateClientBindingId() - Creates/loads a persistent local browser binding id used in auth fingerprint derivation.
  • getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
  • saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
  • loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
  • api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
  • renderDebugDashboardData(data) - Renders the debug dashboard panels, including the subtitle debug cache folder summary and open-folder action.
  • performLogout() - Explicit logout path that revokes server session and clears local session state.
  • initAuth() - Restores prior session when valid and auto-logins without credential prompt.
  • showConfirm(title, message, { html, okLabel, modalClass }) - In-page confirm dialog; returns Promise<boolean>. html=true renders message as innerHTML (caller must escape user data), okLabel overrides the OK button text, and modalClass temporarily widens/restyles the dialog for rich content.
  • escHtml(s) - HTML-escapes a string (& < > ") for safe use with innerHTML in confirm messages.
  • normaliseUpdateCommits(commitsAhead) - Normalises update-status commit entries from string/object formats into {hash, subject, body} for consistent UI rendering.
  • renderUpdateCommitListHtml(commitsAhead) - Builds rich HTML for Restart & Update commit entries with bold subject headers and optional body descriptions.
  • showPrompt(title, message, defaultValue) - In-page text-input dialog; returns Promise<string|null>. Use instead of window.prompt().
  • showOverwrite(filename) - In-page overwrite-decision dialog for file conflicts; returns Promise<'yes'|'no'|'all'|'none'>.
  • splitNameExt(name) - Client-side filename splitter used for local conflict rename suggestions.
  • nextAvailableName(requestedName, existingNames) - Computes name (n).ext for upload/move rename options.
  • listDirNameSet(dir) - Fetches directory listing and returns a Set of existing names.
  • cloneFileWithName(file, newName) - Creates a renamed File object for non-overwrite uploads.
  • showFileConflictChoice(filename, renameTo, mode) - Dialog for single upload/move conflicts; returns overwrite/rename/cancel.
  • parseHumanSize(input) - Parses human-readable sizes like 25 MB/1gb into bytes for admin user-folder limits.
  • updateAdminSizeFeedback(rawValue) - Validates size input and updates admin hint text/classes with parsed byte preview.
  • relativePathFromRoot(targetPath, rootPath) - Produces a root-relative path string for sidebar folder context display.
  • displayPathWithRootLabel(targetPath, rootPath, rootLabel) - Produces Linux-style root-relative display paths like /Downloads/A/B for folder context UI.
  • runGlobalFileSearch() - Executes cross-root fuzzy file search via /files/search, swaps the grid into search-results mode, and updates breadcrumb/folder-stats text.
  • openShareModal(item) - Opens the Delen (share) popup, calls POST /api/share/create, shows the 24-hour URL with a copy button and OK to dismiss.
  • openChangePasswordModal() - Opens the user password modal, validates confirmation/minimum length client-side, and submits to POST /auth/change-password.
  • loadThumbnails() - Registers visible file icons for lazy thumbnail loading (both file thumbnails and folder icons); retries missing cache thumbnails during incremental refresh.
  • loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images, text snapshots for text files, and badges for other files; marks image icons as pending when cache returns 404 and uses direct source SVG thumbnails for SVG files under 1MB.
  • loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images and videos, text snapshots for text files, and badges for other files; marks image/video icons as pending when cache returns 404 and uses direct source SVG thumbnails for SVG files under 1MB.
  • loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images, videos, and supported 3D model files; text files still use text snapshots and badges remain the fallback when no thumbnail strategy exists.
  • observeFolderIcon(iconEl) - Registers a folder icon element with IntersectionObserver for lazy loading.
  • loadOneFolderIcon(iconEl) - Fetches /api/files/folder-icon then the thumbnail blob and overlays it inside the folder SVG; no-op if no icon available.
  • applyFolderThumbnail(iconEl, srcUrl) - Injects an SVG <image> element clipped to the folder outline path into the folder's icon SVG.
  • initTopbarDropdowns() / closeTopbarDropdowns() - Controls Upload/User roll-down menus (open/close, outside-click close, Escape close) without resizing the top bar.
  • setAdminUpdateBadge(count) - Renders the update-count badge and coordinates its anchor between User trigger and Admin menu item.
  • syncAdminUpdateBadgeAnchor() / animateBadgeToTarget(targetEl) / moveBadgeToTarget(targetEl) - Animates badge movement while opening User dropdown and uses a non-animated move on close to prevent snap-to-corner geometry glitches.
  • openFolderIconPicker(item) - Opens the folder icon picker modal; shows cached-thumbnail files from the folder (including video thumbnails); allows selection, clearing, and cancellation.
  • openIconPickerModal(options) - Shared icon-picker modal used by folder-icon and global-favicon flows; includes live thumbnail-name filtering.
  • openGlobalFaviconPicker() - Opens a debounced, server-backed image-search modal across all accessible roots and sets/clears global favicon via /files/global-favicon.
  • refreshGlobalFavicon() - Reads /files/global-favicon, updates admin-panel favicon preview button, and applies/removes the page <link rel="icon"> URL.
  • refreshAdminOrphanUserFolders() - Fetches /admin/orphan-userfolders, conditionally renders orphaned folder rows, and wires "Open folder" navigation for admins.
  • refreshAfterIconChange(item) - Resets and reloads the folder icon in both the grid tile and sidebar after set/clear operations.
  • disconnectFolderIconObserver() - Disconnects and clears the folder icon IntersectionObserver on grid rebuild.
  • getThumbnailKind(name) - Classifies files into image/text/badge thumbnail strategies.
  • observeThumbnailIcon(iconEl) - Defers thumbnail fetch work until file icons are near/in the viewport.
  • disconnectThumbnailObserver() - Clears active IntersectionObserver when the grid is rebuilt.
  • setThumbnailPending(iconEl, pending) - Toggles per-icon pending spinner state while a cached image thumbnail is not ready yet.
  • buildThumbnailSource(item, blob, kind) - Produces thumbnail image source (data/blob URL) for icon injection.
  • buildAuthHeaders() - Builds the authenticated fetch headers used by preview-side API calls that need the bearer token plus fingerprint header.
  • bindImageSubtitleOverlay(player, videojs, prefs, session, item) - Adds the fullscreen-safe image-subtitle button, menu, and bottom overlay used to fetch and display subtitle frames for image-based tracks; keeps subtitle bitmaps horizontally centred at the bottom, highlights the currently selected IM menu option, persists per-user image subtitle stream index + track name, restores by saved track name first (then stream index), batches subtitle timing diagnostics to /api/files/video-stream-subtitle-log, and reads X-Subtitle-Frame-* headers from server responses to properly upscale downscaled frames while maintaining proportions.
  • renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source/track config, enforces non-live playback UI for file streams, uses container-fill sizing to keep previews within bounds, restores per-user video prefs (volume + subtitle/audio track names when present), wires the image-subtitle overlay controller, forces caption overrides on each open (text background opacity transparent + text edge style uniform), reports watch progress, warns when subtitle streams exist but none are web-compatible, and releases the backend stream session on close/unload.
  • modelPreviewType(name) - Classifies direct client-side 3D preview support for .stl and .obj.
  • loadThreePreviewModules() - Lazy-loads Three.js plus OrbitControls/STLLoader/OBJLoader via import map aliases.
  • modelThumbnailDataUrl(item, blob) - Builds a blue SVG thumbnail for STL/OBJ files by parsing their geometry client-side; falls back to a badge when parsing fails.
  • buildModelObjectFromBlob(blob, type, modules) - Parses STL/OBJ blobs and produces a geometry-only model using the standard blue material.
  • renderModelPreview(item, blob, targetEl) - Renders interactive STL/OBJ previews (drag rotate + scroll zoom) with WebGL fallback messaging when unavailable.
  • closePreview(opts) - Closes expanded previews; video previews ignore backdrop close and require explicit close action.

tests/thumbnail-cache.test.js

  • thumbnail cache worker / creates cached thumbnail with dimensions smaller than 100px - Verifies cached image generation and manifest write.
  • thumbnail cache worker / removes cached thumbnail when source file is deleted - Verifies stale thumbnail cleanup behavior.
  • thumbnail cache worker / creates cached thumbnail for video files using ffmpeg frame extraction - Verifies video thumbnail generation uses ffprobe duration and ffmpeg frame capture.
  • afterEach() cleanup - Removes temp roots with fs.rmSync(...maxRetries...) to tolerate transient Windows file locks.
  • detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension.
  • prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering.
  • highlightCode(raw, lang) - Escapes and syntax-highlights preview text into HTML spans.
  • fileAccentColor(name) - Returns canonical file-type accent color used by icon strokes and preview sheet outline.
  • openFolderSidebar() - Persistent sidebar fallback view that shows current folder/root overview when no item is selected.
  • closeSidebar() - Clears selection; hides the panel entirely on mobile and restores folder overview sidebar on desktop.
  • isMobileViewport() - Central media-query helper for mobile-only sidebar/interaction behavior.
  • hideSidebarPanel() - Hides sidebar panel and removes sidebar-open layout class from the app shell.
  • renderBreadcrumb() - Builds clickable breadcrumb path and marks each folder segment as a drag-drop move target via .crumb-drop-target and data-path.
  • fetchFileBlob(item) - Downloads a file as Blob with auth headers for preview/download flows.
  • downloadOrView(item, sourceSvgEl) - Opens preview; prefers in-place expanded tile preview when invoked from a file icon, falls back to overlay when no source tile is available.
  • downloadOrView(item, sourceSvgEl) - Opens in-place expanded tile preview from a file icon; shows error toast if no source tile is found.
  • renderPreviewBody(item, blob, objectUrl, targetEl) - Renders preview content (image/video/audio/pdf/text) or unsupported message into a target container.
  • animateRect(el, fromRect, toRect, opts) - Helper that animates element rectangle (left/top/width/height) for expand/collapse transitions.
  • openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents the real file tile to body, expands it to viewport preview, injects close/download controls.
  • openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents tile to body, shows spinner during expand animation, renders content after animation; applies file-type accent colour to tile border and outline glow.
  • openExpandedTilePreview(item, tileEl, sourceSvgEl, loadPreviewContent) - Preserves the tile's original grid slot with a hidden placeholder while preview is open, then adds preview action buttons for Download and Share.
  • closeExpandedTilePreview() - Collapses expanded tile preview back to the original grid slot, restores original icon markup, and removes the preview placeholder.
  • closePreview() - Closes either expanded-tile preview or overlay preview, then revokes active preview object URL.
  • closePreview() - Closes expanded-tile preview and revokes active preview object URL.
  • openMovePicker(item) - Opens Move To selector modal with expandable folder tree across all writable roots and executes /api/files/move.
  • openCopyPicker(item) - Opens Copy To selector modal with the same tree and executes /api/files/copy.
  • openDestinationPicker(item, mode) - Shared destination picker state/labels for move vs copy operations.
  • moveWithConflictResolution(item, targetDir) - Attempts move and handles 409 conflicts by prompting overwrite/rename/cancel then retries.
  • copyWithConflictResolution(item, targetDir) - Attempts copy and handles 409 conflicts by prompting overwrite/rename/cancel then retries.
  • rootPermissionLabel(root) - Resolves permission key for a root using originalName when available; personal folders resolve to the built-in My Folder label.
  • ensureMoveModal() - Lazily creates and wires Move To modal UI (tree, selection state, confirm/cancel handlers).
  • createMoveNode(folderPath, label) - Builds an expandable/selectable folder node for the Move To tree.
  • loadMoveChildren(containerEl, dirPath) - Lazy-loads subfolders for a tree node via /api/files/list.
  • isInlinePreviewableBlob(blob, name) - Determines if a blob can be previewed inline by MIME/extension.
  • makeFileItem(item) - Builds a .file-item element; roots in Home now use folder-like interaction (single-click focus, double-click open), roots are non-draggable, and mobile long-press contextmenu suppression remains.
  • makeFileItem(item) / renderFileItemName(targetEl, fileName) - Renders tile names with preferred wrap opportunities (space first, then -, ,, . via <wbr> hints) and preserves original visible text; tile-name CSS clamps to 4 lines with truncation.
  • makeFileItem(item) - Renders tile icons first, then applies any cached watched overlay state (fully full-size filled eye, partway smaller darker filled eye).
  • loadWatchedStatusesForCurrentDir() - Fetches watched states in one bulk POST /files/watched-statuses request per directory (with legacy /files/meta fallback), caches statuses per path, and updates tile overlays quickly.
  • attachMobileLongPress(el, item) - Adds mobile long-press detection on file/folder tiles to open the item sidebar without desktop side effects.
  • beginSidebarLoad() - Aborts in-flight sidebar requests and increments a load token so stale async responses cannot mutate the current sidebar state.
  • renderItemActionButtons(actions, item) - Shared action renderer used by sidebar and custom context menu so file/folder actions stay identical.
  • createFolderInCurrentDir() - Shared folder-creation flow used by toolbar and custom context menu.
  • openItemContextMenu(item, x, y) / openFolderContextMenu(x, y) - Desktop custom right-click menus that replace the native context menu for item and background interactions.
  • addContextMenuSubmenu(...) / addContextMenuButton(...) - Context-menu builders used for Sort by / Group by submenus and checkbox-style toggle rows.
  • openSidebar(item) - Renders item details/actions in sidebar; roots show alias + original name + usage stats, hide Move To/Delete, keep Rename.
  • openSidebar(item) - Personal user roots display access as private and skip /files/root-access lookups to avoid forbidden noise.
  • openSidebar(item) - Uses abortable metadata/access requests and stale-load guards to prevent race-condition UI duplication when selection changes quickly.
  • canWrite(item) - Resolves whether the current user may write to the selected item/root; personal folders are always writable for the owner.
  • fetchRootAccessList(rootPath) - Fetches root access users from the server for a specific configured root.
  • formatRootAccessList(users) - Formats root access entries as "username mode" values for sidebar rendering.
  • openSidebar(item) - Renders item details/actions in sidebar; root selections include alias/original name/usage/access list and keep Rename while hiding Move To/Delete.
  • openFolderSidebar() - Shows current folder details when nothing is selected; when at root base-level it also shows root access list.
  • openFolderSidebar() / renderFolderViewControls(actions, dirPath) - In folder overview mode, renders per-folder view controls (Sort by, Group by, folders-first, ascending) and persists them per user+folder in localStorage.
  • renderFileGrid() / buildFileGridRows(items, prefs) - Applies folder view ordering as Group option > folders-first option > sort option, inserts labelled separator rows when grouping is enabled, and uses relative date labels for recent date groups (today, yesterday, two-six days ago, one week ago) before falling back to calendar dates.
  • openRenameModal(item) - Renames files/folders; for roots this writes display alias via /api/files/root-alias and reloads roots.
  • uploadFiles(fileList) - Uploads files one-by-one with per-file conflict prompt (overwrite/rename/cancel) when names already exist.
  • openUserModal(user, paths) - Admin user editor; enforces UI permission rule that Write is disabled/unchecked while Read is unchecked and disables the Admin checkbox when editing the current signed-in admin account.
  • refreshAdminOrphanUserFolders() UI flow - Admin panel shows orphaned user folders only when present and opens selected orphan folder from the section button.

public/drag-move.js

  • makeDraggable(el, item) - Attaches pointerdown to a .file-item; starts drag after threshold movement. Depends on: api(), canWrite(), navigateTo(), STATE, closeSidebar(), toast() from app.js.
  • makeDraggable(el, item) - Touch drag now requires a short hold before movement, uses pointer capture, and keeps drag responsive on mobile.
  • (internal) _beginDrag(e, el, item) - Lifts and re-parents the real .file-item to body, inserts hidden placeholder, and shows parent-folder drag target when applicable.
  • (internal) _moveDrag(e) - Moves the real dragged item, hit-tests folder tiles, breadcrumb segments, and parent-folder target, toggles target highlight state.
  • (internal) _endDrag() - On valid target: runs drop animation, calls moveWithConflictResolution() for overwrite/rename/cancel conflicts, then refreshes dir. Otherwise snap-back.
  • (internal) _cleanupDrag(reinsert) - Restores tile styles; reinserts into grid on failure/abort or removes before refresh on success, hides drag helper targets.

public/drag-move.css

  • .file-item.dragging - Lifted style for real dragged tile.
  • .file-item.drop-target - Glows folder icon when drag hovers over it.
  • .drag-parent-target - Temporary top-left "move to parent" drop target shown while dragging in nested folders.
  • .crumb-drop-target.active - Highlight style for breadcrumb drop destinations during drag.
  • @keyframes drag-rise-spin-fall - Real tile rises, spins, falls/scales into folder on drop.
  • @keyframes folder-bounce - Target folder bounces down then back on accept.
  • .preview-backdrop/.file-item--preview/.preview-expand-* - In-place expanded tile preview styling (no separate overlay window), including preserved icon-outline layer.
  • .preview-expand-share - Secondary action button positioned next to .preview-expand-download in expanded file preview.
  • .move-modal/.move-tree/.move-node* - Move To tree picker styles with expandable/collapsible folder hierarchy.

public/style.css

  • #sidebar-duplicates + related classes - Sidebar duplicate-file list styling with truncation and hover feedback.
  • .admin-size-feedback(.ok/.err) - Validation feedback styling for admin user-folder size-limit input.
  • .top-search* + .global-favicon-preview - Topbar file search controls and global favicon preview button styling.
  • .folder-icon-filter - Search input styling for live filtering in the icon-picker modal.
  • .custom-context-menu* - Desktop context-menu layout with separators and hover-open submenus for folder view options.

tests/auth.routes.test.js

  • session lifecycle / POST /api/auth/logout revokes active session - Verifies explicit logout invalidates token immediately.
  • session lifecycle / session expires after 1 hour of inactivity - Verifies server-side idle timeout enforcement.
  • POST /api/auth/change-password / rejects incorrect current password - Verifies password-change validation when current password is wrong.
  • POST /api/auth/change-password / updates password and invalidates old login credentials - Verifies successful password update and old-password login failure.

tests/page.load.test.js

  • bootClient() - Boots the app in jsdom and waits until app shell is visible or timeout before assertions.
  • waitFor(dom, predicate, timeoutMs) - Poll helper used by interaction tests to wait for rendered tiles.
  • login overlay uses username and current-password autocomplete tokens - Verifies normal sign-in mode exposes browser-friendly login autocomplete attributes.
  • first-run setup uses new-password autocomplete token - Verifies setup mode switches the password field to the browser-friendly new-password token.
  • desktop right-click uses custom context menu for files and folder background - Verifies desktop context menu replacement and folder-view option entries.
  • expanded file preview shows a Share button next to Download - Verifies expanded preview UI includes both actions inside a dedicated footer below the preview content.
  • expanded STL preview falls back gracefully when WebGL is unavailable - Verifies STL preview path shows a clear fallback message when WebGL contexts are unavailable.
  • expanded video preview uses a stream session and video.js - Verifies streamed video preview uses the server-backed HLS session and registers subtitle tracks with video.js.
  • video preview does not close on backdrop click and closes via X button - Verifies video previews require explicit close via X.
  • video preview restores per-user saved volume preference - Verifies per-user saved video volume is applied on preview open.
  • video preview restores saved subtitle/audio track names when available - Verifies per-user subtitle/audio selections are reapplied by matching track names.
  • video preview keeps default tracks when saved names are not present - Verifies subtitle/audio defaults remain unchanged when saved names are missing.
  • video preview saves subtitle/audio track names per user when selection changes - Verifies subtitle/audio selections are persisted into per-user video preferences.
  • video preview applies caption overrides per open - Verifies requested caption overrides are always loaded into Video.js settings.
  • video preview does not save caption style settings per user on close - Verifies caption style changes are not persisted to per-user video preferences.
  • video preview releases the backend stream session when closed - Verifies closing a streamed video preview sends an explicit backend release call.
  • rapid file reselection does not duplicate sidebar action buttons after delayed metadata - Verifies stale sidebar loads are ignored so action buttons are not duplicated.
  • video tiles show centred watched overlays after watched metadata is loaded - Verifies overlays remain absent until watched metadata is fetched, then render as solid eye icons for fully and partway statuses.
  • shows pending icon spinner when video thumbnail cache is not ready - Verifies video tiles use thumbnail-cache loading (instead of badge fallback) and pending-state UI.

tests/video-stream.test.js

  • createVideoStreamSession resolves once ffmpeg starts writing stream assets - Verifies session creation no longer waits for the final master playlist before preview can begin.
  • createVideoStreamSession configures flat segment filenames that match playlist URLs - Verifies ffmpeg segment output paths match the segment URLs emitted in the generated HLS playlists.
  • createVideoStreamSession does not become ready from subtitle files alone - Verifies stream readiness is tied to HLS output instead of extracted subtitle files.
  • createVideoStreamSession keeps playback available when subtitle conversion fails - Verifies subtitle conversion failures are skipped without breaking stream playback.
  • sendVideoStreamAsset prunes old segment files after playback moves far ahead - Verifies old segments are removed only after the retention window passes.
  • createVideoStreamSession reuses one transcode for concurrent viewers of the same file - Verifies two viewers share one ffmpeg transcode while keeping independent lease release behaviour.

tests/share.page.load.test.js

  • applies default caption settings for share-page video playback - Verifies requested caption defaults are applied and persisted on share-page video preview.
  • restores and saves share-page subtitle/audio track preferences by name - Verifies share-page subtitle/audio choices are restored and persisted by track-name matching.

tests/files.routes.test.js

  • POST /api/files/watch-progress stores per-user watched status by thresholds - Verifies watch-status persistence and no downgrade from fully to partway.
  • DELETE /api/files/video-stream/:sessionId releases an active stream session - Verifies explicit stream session release route wiring.

public/vendor/three/three.module.js

  • Third-party Three.js runtime module (vendored, unmodified) used for client-side 3D previews.

public/vendor/three/addons/controls/OrbitControls.js

  • Third-party OrbitControls module (vendored, unmodified) providing drag-rotate and wheel-zoom interactions.

public/vendor/three/addons/loaders/STLLoader.js

  • Third-party STL parser module (vendored, unmodified) for client-side .stl geometry loading.

public/vendor/three/addons/loaders/OBJLoader.js

  • Third-party OBJ parser module (vendored, unmodified) for client-side .obj geometry loading.
Source
1# Technical Reference
2
3## installsystemdservice.sh
4- bool_is_true(value) - Parses common truthy string values used for installer feature flags.
5- confirm_root_service_mode() - Interactive installer prompt (`[y/N]`) that decides whether the service should run as root when no env override is provided.
6- FILEMANAGER_SERVICE_RUN_AS_ROOT - Optional installer env override for non-interactive installs; when truthy, writes a root-running systemd unit (omits User=) and enables FILEMANAGER_LIST_ACCESS_CHMOD in the unit environment.
7
8## server/index.js
9- start() - Initialises DB/keys, starts HTTP/HTTPS servers, and starts the background thumbnail cache loop.
10- shutdown(opts, ...servers) - Graceful teardown: stops thumbnail loop, closes DB/servers, exits with configurable code after drain/timeout.
11- Express error handler - Logs uncaught route errors to logs.txt before returning a JSON 500 response.
12- GET /share/:token - Calls buildShareOpenGraphPage to serve share.html with injected OG meta tags for all visitors; social media crawlers see rich preview data, browsers get the full interactive page.
13
14## server/logger.js
15- logError(message, error, details) - Appends error lines to logs.txt, trimming old lines so the file stays under 1 MB; use for route failures and process-level exceptions.
16
17## server/subtitle-debug-log.js
18- appendSubtitleDebugEntries({ videoName, entries, context }) - Appends client-side subtitle timing events to a timestamped per-video text log under the local temp cache (`<unix-ms>-videoname-subtitlelog.txt`), reusing one file per playback context and pruning the oldest files when the subtitle log cache exceeds 10 MB.
19- getSubtitleDebugLogSnapshot() - Reports the subtitle log cache directory path, existence, file count, byte total, and latest file so the debug dashboard can expose it as a folder.
20- pruneSubtitleDebugLogDir() - Enforces the 10 MB total subtitle-log cache budget by deleting the oldest log files first.
21- subtitleLogFileByContext (LRU) - In-memory context-to-logfile mapping is trimmed with `SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX` (default 512, capped at 4096) to prevent unbounded session-key growth.
22- subtitleDebugLogFilePath(videoName, timestampMs) - Resolves the timestamped subtitle timing log path for a video name using a filesystem-safe filename.
23
24## server/image-subtitles.js
25- parseRenderOptions(options) - Normalises subtitle-frame request options and validates filePath/streamIndex/time/canvas dimensions; stream index `0` is valid and must not be treated as missing; canvas is scaled down within a 1280x720 ceiling, then multiplied by `IMAGE_SUBTITLE_RENDER_SCALE` (default `0.75`) while preserving requested aspect ratio.
26- renderImageSubtitleFrame(options) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns {frame: PNG buffer, left, top, width, height, canvasWidth, canvasHeight} with metadata for proper client-side upscaling; the server preserves positioning info instead of throwing it away, allowing the client to calculate percentage-based sizing for downscaled frames; cold event-cache builds now continue in the background while requests return quickly with no frame (`null`) until parsing finishes, avoiding long-hanging subtitle frame requests after cache purge; request/build/render timing counters are tracked for debug diagnostics.
27- clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path using path-prefixed cache keys, also deletes the corresponding `.sup` file from disk for each evicted event entry; called when video stream sessions end to prevent memory and disk accumulation.
28- pruneOldImageSubtitleCaches(filePath, slowestViewerTimeSeconds) - Drops subtitle frame caches for events that have passed their retention threshold of end time + event duration + 5 seconds (e.g., event ending at 30s with 10s duration is dropped after slowest viewer reaches 45s); used during segment pruning to keep memory usage bounded on long videos, especially on resource-limited hardware like Raspberry Pi.
29- purgeSubtitleCacheDir() - Removes the entire subtitle `.sup` file cache directory from disk; called once at server startup to clean up any files left over from a previous run.
30- touchCachedEntry(cache, key, ttlMs) - Refreshes the TTL of an existing cache entry without changing its value; used to keep actively-watched subtitle tracks alive past their initial 5-minute TTL and prevent expensive full re-parses during long playback sessions.
31- getImageSubtitleDebugSnapshot() - Returns event/frame cache totals, timing counters (cache hits/misses, event build timing, frame render/request timing), and per-video cache usage ({event entries/bytes/count, frame entries/bytes}) so admin diagnostics can distinguish cache-thrash or cold-parse stalls from steady-state rendering.
32- IMAGE_SUBTITLE_EVENT_CACHE_TTL_MS / IMAGE_SUBTITLE_FRAME_CACHE_TTL_MS / IMAGE_SUBTITLE_EVENT_CACHE_MAX_ITEMS / IMAGE_SUBTITLE_FRAME_CACHE_MAX_ITEMS / IMAGE_SUBTITLE_EVENT_CACHE_MAX_BYTES / IMAGE_SUBTITLE_FRAME_CACHE_MAX_BYTES / IMAGE_SUBTITLE_RENDER_SCALE / IMAGE_SUBTITLE_PRUNE_GRACE_SECONDS - Environment knobs for subtitle cache retention, optional item caps (`0`/`unbounded` disables the cap so byte limits govern), byte caps, render resolution, and prune grace window.
33
34## server/thumbnail-cache.js
35- syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files, video files (ffprobe/ffmpeg frame at ~10%), and 3D model files (STL/OBJ, isometric SVG projection via Sharp); removes stale thumbnails and updates manifest hashes.
36- startThumbnailCacheLoop() - Schedules cache sync runs with adaptive cadence: default 5s when idle and heavily throttled while active streams exist (`THUMBNAIL_CACHE_ACTIVE_STREAM_DELAY_MS`, default 120000 ms).
37- stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
38- getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
39- getThumbPathForSourceFile(sourceFile) - Maps an absolute source file path to its mirrored cache thumbnail path.
40- getThumbRelPathForSourceFile(sourceFile) - Returns public-relative thumbnail path used in manifest entries.
41- getFilesWithThumbnailsInDir(dirPath) - Returns [{filePath, thumbRelPath}] for all files inside dirPath (recursive) that have a cached thumbnail; sorted by filePath.
42- getFolderIconSourceFile(folderPath) - Returns the source image path for a folder's icon: explicit assignment first, then auto-first cached image, null if none.
43- setFolderIconAssignment(folderPath, imagePath) - Saves an explicit folder icon assignment to .folder-icons.json; pass null to clear (auto-detect used instead).
44
45## server/db.js
46- initDb() - Initializes SQLite schema for users, file metadata (including watched_by), and auth_sessions (idle timeout/revocation support), and migrates watched_by for existing DB files.
47- getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
48- closeDb() - Closes singleton DB handle to release file locks.
49
50## server/auth.js
51- createToken(username, req, fingerprint) - Creates JWT bound to IP/region/fingerprint and linked to a DB-backed session id.
52- requireAuth(req, res, next) - Verifies JWT + binding + session row + 1-hour idle timeout, updates last_seen_at, and attaches req.user.
53- requireAdmin(req, res, next) - Requires authenticated admin user.
54- revokeSession(sessionId) - Revokes a session row so future token use fails immediately.
55- getClientIp(req) - Normalizes request IP (including IPv4-mapped IPv6 loopback cases).
56- getRegion(ip) - Derives coarse region binding from geoip lookup or local fallback.
57- SESSION_IDLE_TIMEOUT_MS - Server-enforced idle timeout window (1 hour).
58
59## server/routes/auth.js
60- extractCredentials(body) - Accepts encrypted payloads and compatibility plaintext payloads for login/setup.
61- makeAuthResponse(token, clientPublicKey) - Returns encrypted token when client key exists, plaintext token otherwise.
62- POST /api/auth/setup - Creates first admin and issues token.
63- POST /api/auth/login - Authenticates user by case-insensitive username match and issues token with canonical stored username.
64- GET /api/auth/me - Returns current authenticated user profile.
65- POST /api/auth/logout - Revokes the active session.
66- POST /api/auth/change-password - Authenticated password change using current-password verification and minimum-length validation.
67
68## server/routes/admin.js
69- POST /api/admin/users - Creates a new user and enforces case-insensitive username uniqueness.
70- PATCH /api/admin/users/:id - Updates user password/admin flag/permissions; rejects self-demotion and still blocks removing the last admin account.
71- GET /api/admin/orphan-userfolders - Returns non-empty user folders under userPath that no longer match any account, and auto-deletes empty orphan folders.
72- DELETE /api/admin/users/:id - Also removes the deleted user's personal folder when it exists and is empty.
73- normalizePermissions(permissions) - Normalizes permission maps and enforces that write access implies read access.
74- ensureUserFolders(userPath) - Ensures configured userPath exists and creates per-user subfolders for all current users.
75- GET /api/admin/config - Returns admin config including userPath and userFolderSizeLimit (bytes, null for unlimited).
76- PUT /api/admin/config - Persists paths plus userPath/userFolderSizeLimit and ensures per-user folders exist.
77- GET /api/admin/update-status - Returns { underSystemd, commitsAhead[] } where commitsAhead contains non-merge commits as {hash, subject, body}; detects systemd via INVOCATION_ID env var and runs git fetch + git log against origin/HEAD for Restart & Update messaging.
78- GET /api/admin/debug/stream-stats - Admin diagnostics payload with active signed-in users, per-root storage usage, active stream HLS footprint, subtitle cache totals, and per-video rows that also include cached-only videos with zero active viewers.
79
80## server/routes/debug.js
81- GET /api/admin/debug/stream-stats - Computes debug dashboard data by combining auth_sessions activity, root disk usage scans, stream snapshot data, and subtitle cache snapshot data into a per-video view for leak/performance monitoring.
82- GET /api/admin/debug/stream-stats - Also reports host/process memory ({total, free, used, usedPercent, processRssBytes, processHeapUsedBytes}) so streaming lag can be correlated with RAM pressure.
83- GET /api/admin/debug/stream-stats - Also reports the subtitle debug cache directory metadata so admins can open the local subtitle log folder from the debug dashboard.
84
85## server/routes/files.js
86- GET /api/files/roots - Returns readable roots with display label (alias when configured), originalName, and path.
87- GET /api/files/roots - Adds a synthetic 'My folder' root for the authenticated user when userPath is configured.
88- loadConfigAndRoots() - Loads config and effective roots together so route access checks stay consistent.
89- parseOctalMode(rawValue, fallback) - Parses optional octal chmod mode overrides from environment variables and falls back to secure defaults when invalid.
90- envFlagEnabled(name) - Boolean environment flag parser for file-route runtime feature toggles.
91- applyListAccessChmod(startDir) - Best-effort shallow chmod pass for folder-access requests; updates the opened folder and its direct children only, skips symlinks, and continues past individual errors.
92- resolveRootForUser(absPath, roots, user, config) - Resolves access for configured roots plus user-owned personal folder.
93- resolveRootForUser(absPath, roots, user, config) - Allows admins to access orphaned user folders (deleted-account folders) under userPath.
94- resolveRootForUser(absPath, roots, user, config) - Treats the local subtitle debug log directory as an admin-only debug root for browse and maintenance actions from the debug menu.
95- canReadInfo(user, info) / canWriteInfo(user, info) - Permission checks that automatically allow access for personal user-folder roots.
96- checkUserFolderSizeLimit(config, username, addedBytes) - Validates a user-folder capacity limit against current usage.
97- POST /api/files/root-alias - Sets a display-only alias for an exact configured root path (no filesystem rename).
98- GET /api/files/root-access - Returns users who can access an exact configured root and their access mode (R / R+W).
99- GET /api/files/meta - Returns file metadata and lazily computes/stores sha256 when missing.
100- GET /api/files/duplicates - Returns accessible files that share the selected file's sha256 hash.
101- GET /api/files/space - Returns used/free disk space and, for personal folders, user-limit fields (userLimitBytes/userFreeBytes).
102- GET /api/files/thumbnail - Serves cache-only thumbnail images for authorized files; returns 404 while cache is not ready.
103- GET /api/files/folder-images - Returns files inside a directory (recursive) that already have a cached thumbnail (including video thumbnails when cached).
104- GET /api/files/folder-icon - Returns the current icon source file for a folder ({icon:{filePath}} or {icon:null}); explicit assignment takes priority over auto-first.
105- POST /api/files/folder-icon - Sets or clears a folder's explicit icon assignment; imagePath must have a cached thumbnail; write access required.
106- GET /api/files/search - Fuzzy-searches all readable roots (and personal folder when configured) for files, returning ranked matches with path metadata.
107- GET /api/files/list - Returns directory items including name/path/isDir plus size, mtime, and uploadedAt; uploadedAt comes from persisted `file_meta.uploaded_at` when present, otherwise it is backfilled from filesystem creation/change metadata and saved.
108- GET /api/files/list - When FILEMANAGER_LIST_ACCESS_CHMOD=1, runs a best-effort shallow chmod on the opened folder before listing (opened folder + direct children only; defaults: dirs 0777, files 0666; overrides via FILEMANAGER_LIST_ACCESS_CHMOD_DIR_MODE and FILEMANAGER_LIST_ACCESS_CHMOD_FILE_MODE).
109- GET /api/files/search-images - Fuzzy-searches readable roots for image files with ready thumbnails, returning capped results plus scan-truncation metadata for scalable global favicon selection.
110- GET /api/files/global-favicon-image - Publicly serves the configured global favicon thumbnail file so browsers can load `<link rel="icon">` without auth headers.
111- GET /api/files/global-favicon - Returns the configured global favicon source file path ({favicon:{filePath}} or {favicon:null}).
112- POST /api/files/global-favicon - Admin-only route that sets or clears the global favicon source image; image must have a cached thumbnail.
113- GET /api/files/download-zip?dir=<absolute-path> - Authenticated. Streams the directory as a zip archive; caches the zip for up to 1 day in zip-cache/.
114- makeTempUploadPath(dir, originalName) - Builds a hidden per-upload staging filename in the target directory for multipart uploads.
115- unlinkIfExists(targetPath, cb) - Removes a file during upload cleanup while ignoring already-missing temp files.
116- promoteUploadedFile(tempPath, finalPath, cb) - Atomically renames a completed staged upload into place on the Linux server.
117- splitNameExt(name) - Splits a filename into stem/ext, preserving dotless names and hidden-file behavior.
118- pickNumberedPath(dir, requestedName) - Finds the first free `name (n).ext` path inside a directory.
119- removePathRecursive(targetPath) - Deletes existing file or directory destination to support overwrite moves.
120- movePathWithFallback(from, dest) - Moves files/folders with an EXDEV copy-then-delete fallback so cross-device moves into My Folder still succeed.
121- rewriteMetaPaths(fromPath, toPath) - Rewrites metadata paths after rename/move while preserving all columns in `file_meta` (including uploaded_at, watched_by, hashes, and future columns).
122- POST /api/files/upload - Streams multipart uploads into hidden temp files, computes/stores sha256, and enforces user-folder size limits.
123- POST /api/files/upload - Stores authoritative upload timestamp in `file_meta.uploaded_at` at upload time; this timestamp persists across move/rename through metadata path rewrites.
124- POST /api/files/move - Moves file/folder; supports conflict strategies: `error` (default), `overwrite`, or `rename` with optional `targetName`.
125- POST /api/files/copy - Copies a file to a destination folder with conflict strategies (`error`, `overwrite`, `rename`) and user-folder size-limit checks.
126- POST /api/files/video-stream - Creates a short-lived HLS session for a video and returns playlistUrl, durationSeconds, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary ({total, converted, imageBased, skipped}).
127- GET /api/files/video-stream-subtitle-frame - Authenticated. Renders a PNG subtitle frame for bitmap subtitle tracks via cached PGS decode/composite flow; returns {frame, left, top, width, height, canvasWidth, canvasHeight}; sends response headers X-Subtitle-Frame-{Left,Top,Width,Height,Canvas-Width,Canvas-Height,Start-Time,End-Time} plus X-Subtitle-{Request-Received-At-Ms,Response-Sent-At-Ms} so the client can log subtitle timing against server send time; on failures or no active subtitle it returns 204 so the client can stop retrying.
128- POST /api/files/video-stream-subtitle-log - Authenticated. Accepts batched client-side subtitle timing events for an authorised file and appends them to the local subtitle debug-log cache with file path, username, and stream session context.
129- DELETE /api/files/video-stream/:sessionId - Explicitly releases an active short-lived video stream session and stops backend processing.
130- POST /api/files/watched-statuses - Returns fast per-user watched statuses for up to 500 file paths without triggering expensive metadata/hash work; response is { statuses: { [filePath]: 'fully'|'partway' } }.
131- POST /api/files/watch-progress - Records per-user watch status (`partway` >=10%, `fully` >=70%) for sidebar "Watched by" display.
132
133## server/routes/share.js
134- getUserFolderPath(config, username) - Resolves the owning user's personal folder path from config.userPath.
135- resolveRootForUser(absPath, roots, user, config) - Resolves configured roots plus the owning user's personal folder for share checks.
136- canReadInfo(user, info) - Read-check helper that always allows the owner of a personal folder root.
137- POST /api/share/create - Authenticated. Creates a 24-hour share token for a file or directory; returns {token, expiresAt} and accepts items inside the authenticated user's My Folder.
138- GET /api/share/info/:token - Public. Returns {name, isDir, expiresAt} for a valid non-expired token; 410 when expired, 404 when unknown.
139- GET /api/share/preview/:token - Public. Streams file content inline for preview (files only, max 50 MB); 400 for directories, 410 expired.
140- GET /api/share/download/:token - Public. Downloads the file or a zip of the directory for a valid token; 410 expired.
141- GET /api/share/video-stream/:token - Public. Creates a short-lived HLS session for a shared video and returns playlistUrl, durationSeconds, subtitleTracks, imageSubtitleTracks, and subtitleSummary ({total, converted, imageBased, skipped}).
142- GET /api/share/video-stream-subtitle-frame/:token - Public. Renders a PNG subtitle frame for shared-video bitmap subtitle tracks using the same cached PGS decode path as the authenticated player; returns the same subtitle timing headers as the authenticated route and 204 with X-Subtitle-Frame-Status when no frame is active or rendering fails.
143- POST /api/share/video-stream-subtitle-log/:token - Public. Accepts batched client-side subtitle timing events for a valid shared-video token and appends them to the local subtitle debug-log cache with share-token and stream-session context.
144- DELETE /api/share/video-stream/session/:sessionId - Public. Explicitly releases a shared HLS lease so the share page can clean up the backend stream session on close/unload instead of waiting for idle expiry.
145- buildShareOpenGraphPage(token, req) - Reads share.html, injects OG meta tags (<og:title>, <og:description>, <og:image> for image files, twitter:card) based on DB lookup of token, and returns the full HTML string. Handles expired and not-found tokens. Exported and used by the /share/:token route in server/index.js.
146- buildZip(dirPath, cacheKey) - Creates (or returns cached) zip in zip-cache/; prunes stale zips before building; exported for reuse in files.js.
147- pruneZipCache() - Deletes zip files in zip-cache/ older than 1 day; called automatically before each zip build.
148- ZIP_CACHE_DIR - Absolute path to the zip-cache/ directory (project root).
149
150## server/video-stream.js
151- createVideoStreamSession(sourcePath) - Probes input metadata and reuses a compatible active transcode session per source file when possible; returns a per-viewer lease id as sessionId plus duration, videoWidth, videoHeight, subtitleTracks, imageSubtitleTracks, and subtitleSummary data, including same-name sidecar `.srt` subtitles converted to WebVTT.
152- sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
153- releaseVideoStreamSession(sessionId) - Releases one viewer lease and destroys the underlying transcode session immediately once lease count drops to zero (even if a response is still finishing) so zero-viewer streams are purged right away; cleanup only clears image subtitle frame/event caches once no other active stream session for the same source file remains.
154- parseSegmentIndexFromAssetPath(assetPath) - Extracts the numeric segment index from an HLS segment filename; matches both numeric variant identifiers (stream_0_segment_000000.ts) and named variants (stream_video_segment_000000.ts, stream_Audio-1-jpn_segment_000000.ts) — ffmpeg substitutes the var_stream_map name: value for %v when named streams are used.
155- runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() using the slowest active viewer across all live sessions for the same source file, so file-wide subtitle buffers are not pruned ahead of a newly started second session; segment deletion now runs in bounded batches and records last prune duration/deleted-segment counts for diagnostics; segment filename regex also uses named-variant pattern to match production filenames correctly.
156- hasInitialHlsAssets(outputDir) - Returns true once master.m3u8 or at least one variant playlist/segment exists in an HLS output directory; accepts named variant filenames (stream_video.m3u8) in addition to numeric ones.
157- purgeStreamRootDir() - Best-effort recursive delete of the temporary HLS stream root; used at startup and by idle sweeps to remove orphaned stream session directories from previous runs.
158- cleanupIdleStreamArtifacts() - Periodic idle-time cleaner that purges stream-root artifacts when there are no active sessions or leases, preventing stale segment directories from accumulating after failures.
159- pruneExpiredSessions() sweep - A dedicated interval sweep (`VIDEO_STREAM_EXPIRY_SWEEP_MS`, default 60000 ms) reclaims expired leases/sessions even when no new stream requests arrive.
160- getVideoStreamDebugSnapshot() - Returns active stream sessions with viewer counts and output-dir stats (segment counts/bytes), plus orphaned output directories left under the stream root for diagnostics.
161- getVideoStreamDebugSnapshot() - Includes segment retention and prune telemetry per session (segmentRetentionCount, slowestViewerSegmentIndex, segmentPrunedUntil, lastSegmentPrune, streamPruneDeleteBatchSize) to explain growth or cleanup stalls in segment counts.
162- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
163- STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
164- STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated (5 minutes).
165- STREAM_SEGMENT_RETENTION_COUNT - Number of most-recent HLS segment indices kept on disk while older segments are pruned; when not overridden with VIDEO_STREAM_SEGMENT_RETENTION_COUNT it is derived from hardware capacity (RAM + CPU), current memory/CPU pressure, and Raspberry Pi 5 profile bounds.
166- MAX_STREAM_SEGMENT_RETENTION_COUNT - Upper safety cap for retention (360) to avoid runaway in-session segment growth from oversized overrides.
167- VIDEO_STREAM_PRUNE_DELETE_BATCH_SIZE - Optional environment knob that limits how many old HLS segment files are unlinked in parallel during one prune batch; smaller values reduce I/O spikes at the cost of slower cleanup.
168
169## server/db.js
170- initDb() - Initializes SQLite schema for users, file metadata, auth_sessions, and share_tokens (expires_at index).
171- getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
172- closeDb() - Closes singleton DB handle to release file locks.
173
174## public/share.html
175- Standalone public share page served at /share/:token; no auth required.
176- Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
177- tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
178- Share video preview - Uses the shared browser video-player helper used by app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), subtitle/audio track restore/save by matching track names, image-subtitle overlay support, and explicit backend session release on unload.
179- Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
180- Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.
181
182## public/shared-video-player.js
183- applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
184- bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
185- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, renders seek-bar triangle markers for last requested caption start time (`>`) and last received/ready caption start time (`<`), and disables the track after the first hard failure.
186- configureVideoJsBuffering(videojs, opts) - Applies the long forward-buffer settings used for file playback when VHS exposes those knobs.
187- ensureVideoPlaybackUi(player, durationSeconds) - Forces file streams into VOD UI mode, normalises the reported duration, stops live-tracker state, and hides the live badge when present.
188
189## public/index.html
190- Auth form - Login/setup form uses username plus mode-specific password autocomplete tokens so browser password managers behave correctly.
191- Top bar - Places icon-only Refresh to the left of breadcrumb/Home, keeps search input with icon-only search button, and groups actions into Upload/User dropdown triggers.
192- User menu - Includes a Change Password action and a dedicated change-password modal with current/new/confirm fields.
193- User menu - Admin users also get a Debug action that opens a live diagnostics dashboard modal.
194- Admin panel - Includes an icon-only global favicon button that opens the shared icon picker modal.
195- Admin panel - Users section includes a conditional orphaned-user-folders subsection that appears only when non-empty orphan folders exist.
196- Debug dashboard modal - Shows active signed-in users, total/per-root storage usage, active stream footprint, cached subtitle usage by video, and orphaned stream output directories.
197- Debug dashboard modal - Also exposes the subtitle debug cache folder with an open-folder action for admins.
198- Debug dashboard modal - Each diagnostics sub-panel includes a copy action for quick report sharing: users/storage copy JSON, stream/cache and orphaned output tables copy CSV.
199- Debug dashboard modal - Storage cards include RAM usage and process RSS; stream/cache table includes retention and prune progress columns for troubleshooting segment buildup.
200- Admin modal - Includes User Folders controls (user path + per-user size limit) and a dedicated save action for that config.
201- Import map - Maps `three` and `three/addons/` to local vendored modules for client-side STL/OBJ previews.
202
203## public/app.js
204- showApp() - Reveals app shell; keeps sidebar folded by default on mobile and shows folder overview sidebar on desktop.
205- showAuthOverlay(setupMode) - Displays the login/setup overlay and switches the password autocomplete token between current-password and new-password based on mode.
206- getOrCreateClientBindingId() - Creates/loads a persistent local browser binding id used in auth fingerprint derivation.
207- getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
208- saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
209- loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
210- api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
211- renderDebugDashboardData(data) - Renders the debug dashboard panels, including the subtitle debug cache folder summary and open-folder action.
212- performLogout() - Explicit logout path that revokes server session and clears local session state.
213- initAuth() - Restores prior session when valid and auto-logins without credential prompt.
214- showConfirm(title, message, { html, okLabel, modalClass }) - In-page confirm dialog; returns Promise<boolean>. `html=true` renders message as innerHTML (caller must escape user data), `okLabel` overrides the OK button text, and `modalClass` temporarily widens/restyles the dialog for rich content.
215- escHtml(s) - HTML-escapes a string (& < > ") for safe use with innerHTML in confirm messages.
216- normaliseUpdateCommits(commitsAhead) - Normalises update-status commit entries from string/object formats into {hash, subject, body} for consistent UI rendering.
217- renderUpdateCommitListHtml(commitsAhead) - Builds rich HTML for Restart & Update commit entries with bold subject headers and optional body descriptions.
218- showPrompt(title, message, defaultValue) - In-page text-input dialog; returns Promise<string|null>. Use instead of window.prompt().
219- showOverwrite(filename) - In-page overwrite-decision dialog for file conflicts; returns Promise<'yes'|'no'|'all'|'none'>.
220- splitNameExt(name) - Client-side filename splitter used for local conflict rename suggestions.
221- nextAvailableName(requestedName, existingNames) - Computes `name (n).ext` for upload/move rename options.
222- listDirNameSet(dir) - Fetches directory listing and returns a Set of existing names.
223- cloneFileWithName(file, newName) - Creates a renamed File object for non-overwrite uploads.
224- showFileConflictChoice(filename, renameTo, mode) - Dialog for single upload/move conflicts; returns overwrite/rename/cancel.
225- parseHumanSize(input) - Parses human-readable sizes like `25 MB`/`1gb` into bytes for admin user-folder limits.
226- updateAdminSizeFeedback(rawValue) - Validates size input and updates admin hint text/classes with parsed byte preview.
227- relativePathFromRoot(targetPath, rootPath) - Produces a root-relative path string for sidebar folder context display.
228- displayPathWithRootLabel(targetPath, rootPath, rootLabel) - Produces Linux-style root-relative display paths like `/Downloads/A/B` for folder context UI.
229- runGlobalFileSearch() - Executes cross-root fuzzy file search via `/files/search`, swaps the grid into search-results mode, and updates breadcrumb/folder-stats text.
230- openShareModal(item) - Opens the Delen (share) popup, calls POST /api/share/create, shows the 24-hour URL with a copy button and OK to dismiss.
231- openChangePasswordModal() - Opens the user password modal, validates confirmation/minimum length client-side, and submits to POST /auth/change-password.
232- loadThumbnails() - Registers visible file icons for lazy thumbnail loading (both file thumbnails and folder icons); retries missing cache thumbnails during incremental refresh.
233- loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images, text snapshots for text files, and badges for other files; marks image icons as pending when cache returns 404 and uses direct source SVG thumbnails for SVG files under 1MB.
234- loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images and videos, text snapshots for text files, and badges for other files; marks image/video icons as pending when cache returns 404 and uses direct source SVG thumbnails for SVG files under 1MB.
235- loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images, videos, and supported 3D model files; text files still use text snapshots and badges remain the fallback when no thumbnail strategy exists.
236- observeFolderIcon(iconEl) - Registers a folder icon element with IntersectionObserver for lazy loading.
237- loadOneFolderIcon(iconEl) - Fetches /api/files/folder-icon then the thumbnail blob and overlays it inside the folder SVG; no-op if no icon available.
238- applyFolderThumbnail(iconEl, srcUrl) - Injects an SVG <image> element clipped to the folder outline path into the folder's icon SVG.
239- initTopbarDropdowns() / closeTopbarDropdowns() - Controls Upload/User roll-down menus (open/close, outside-click close, Escape close) without resizing the top bar.
240- setAdminUpdateBadge(count) - Renders the update-count badge and coordinates its anchor between User trigger and Admin menu item.
241- syncAdminUpdateBadgeAnchor() / animateBadgeToTarget(targetEl) / moveBadgeToTarget(targetEl) - Animates badge movement while opening User dropdown and uses a non-animated move on close to prevent snap-to-corner geometry glitches.
242- openFolderIconPicker(item) - Opens the folder icon picker modal; shows cached-thumbnail files from the folder (including video thumbnails); allows selection, clearing, and cancellation.
243- openIconPickerModal(options) - Shared icon-picker modal used by folder-icon and global-favicon flows; includes live thumbnail-name filtering.
244- openGlobalFaviconPicker() - Opens a debounced, server-backed image-search modal across all accessible roots and sets/clears global favicon via `/files/global-favicon`.
245- refreshGlobalFavicon() - Reads `/files/global-favicon`, updates admin-panel favicon preview button, and applies/removes the page `<link rel="icon">` URL.
246- refreshAdminOrphanUserFolders() - Fetches `/admin/orphan-userfolders`, conditionally renders orphaned folder rows, and wires "Open folder" navigation for admins.
247- refreshAfterIconChange(item) - Resets and reloads the folder icon in both the grid tile and sidebar after set/clear operations.
248- disconnectFolderIconObserver() - Disconnects and clears the folder icon IntersectionObserver on grid rebuild.
249- getThumbnailKind(name) - Classifies files into image/text/badge thumbnail strategies.
250- observeThumbnailIcon(iconEl) - Defers thumbnail fetch work until file icons are near/in the viewport.
251- disconnectThumbnailObserver() - Clears active IntersectionObserver when the grid is rebuilt.
252- setThumbnailPending(iconEl, pending) - Toggles per-icon pending spinner state while a cached image thumbnail is not ready yet.
253- buildThumbnailSource(item, blob, kind) - Produces thumbnail image source (data/blob URL) for icon injection.
254- buildAuthHeaders() - Builds the authenticated fetch headers used by preview-side API calls that need the bearer token plus fingerprint header.
255- bindImageSubtitleOverlay(player, videojs, prefs, session, item) - Adds the fullscreen-safe image-subtitle button, menu, and bottom overlay used to fetch and display subtitle frames for image-based tracks; keeps subtitle bitmaps horizontally centred at the bottom, highlights the currently selected IM menu option, persists per-user image subtitle stream index + track name, restores by saved track name first (then stream index), batches subtitle timing diagnostics to `/api/files/video-stream-subtitle-log`, and reads X-Subtitle-Frame-* headers from server responses to properly upscale downscaled frames while maintaining proportions.
256- renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source/track config, enforces non-live playback UI for file streams, uses container-fill sizing to keep previews within bounds, restores per-user video prefs (volume + subtitle/audio track names when present), wires the image-subtitle overlay controller, forces caption overrides on each open (text background opacity transparent + text edge style uniform), reports watch progress, warns when subtitle streams exist but none are web-compatible, and releases the backend stream session on close/unload.
257- modelPreviewType(name) - Classifies direct client-side 3D preview support for `.stl` and `.obj`.
258- loadThreePreviewModules() - Lazy-loads Three.js plus OrbitControls/STLLoader/OBJLoader via import map aliases.
259- modelThumbnailDataUrl(item, blob) - Builds a blue SVG thumbnail for STL/OBJ files by parsing their geometry client-side; falls back to a badge when parsing fails.
260- buildModelObjectFromBlob(blob, type, modules) - Parses STL/OBJ blobs and produces a geometry-only model using the standard blue material.
261- renderModelPreview(item, blob, targetEl) - Renders interactive STL/OBJ previews (drag rotate + scroll zoom) with WebGL fallback messaging when unavailable.
262- closePreview(opts) - Closes expanded previews; video previews ignore backdrop close and require explicit close action.
263
264## tests/thumbnail-cache.test.js
265- thumbnail cache worker / creates cached thumbnail with dimensions smaller than 100px - Verifies cached image generation and manifest write.
266- thumbnail cache worker / removes cached thumbnail when source file is deleted - Verifies stale thumbnail cleanup behavior.
267- thumbnail cache worker / creates cached thumbnail for video files using ffmpeg frame extraction - Verifies video thumbnail generation uses ffprobe duration and ffmpeg frame capture.
268- afterEach() cleanup - Removes temp roots with `fs.rmSync(...maxRetries...)` to tolerate transient Windows file locks.
269- detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension.
270- prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering.
271- highlightCode(raw, lang) - Escapes and syntax-highlights preview text into HTML spans.
272- fileAccentColor(name) - Returns canonical file-type accent color used by icon strokes and preview sheet outline.
273- openFolderSidebar() - Persistent sidebar fallback view that shows current folder/root overview when no item is selected.
274- closeSidebar() - Clears selection; hides the panel entirely on mobile and restores folder overview sidebar on desktop.
275- isMobileViewport() - Central media-query helper for mobile-only sidebar/interaction behavior.
276- hideSidebarPanel() - Hides sidebar panel and removes sidebar-open layout class from the app shell.
277- renderBreadcrumb() - Builds clickable breadcrumb path and marks each folder segment as a drag-drop move target via .crumb-drop-target and data-path.
278- fetchFileBlob(item) - Downloads a file as Blob with auth headers for preview/download flows.
279- downloadOrView(item, sourceSvgEl) - Opens preview; prefers in-place expanded tile preview when invoked from a file icon, falls back to overlay when no source tile is available.
280- downloadOrView(item, sourceSvgEl) - Opens in-place expanded tile preview from a file icon; shows error toast if no source tile is found.
281- renderPreviewBody(item, blob, objectUrl, targetEl) - Renders preview content (image/video/audio/pdf/text) or unsupported message into a target container.
282- animateRect(el, fromRect, toRect, opts) - Helper that animates element rectangle (left/top/width/height) for expand/collapse transitions.
283- openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents the real file tile to body, expands it to viewport preview, injects close/download controls.
284- openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents tile to body, shows spinner during expand animation, renders content after animation; applies file-type accent colour to tile border and outline glow.
285- openExpandedTilePreview(item, tileEl, sourceSvgEl, loadPreviewContent) - Preserves the tile's original grid slot with a hidden placeholder while preview is open, then adds preview action buttons for Download and Share.
286- closeExpandedTilePreview() - Collapses expanded tile preview back to the original grid slot, restores original icon markup, and removes the preview placeholder.
287- closePreview() - Closes either expanded-tile preview or overlay preview, then revokes active preview object URL.
288- closePreview() - Closes expanded-tile preview and revokes active preview object URL.
289- openMovePicker(item) - Opens Move To selector modal with expandable folder tree across all writable roots and executes /api/files/move.
290- openCopyPicker(item) - Opens Copy To selector modal with the same tree and executes /api/files/copy.
291- openDestinationPicker(item, mode) - Shared destination picker state/labels for move vs copy operations.
292- moveWithConflictResolution(item, targetDir) - Attempts move and handles 409 conflicts by prompting overwrite/rename/cancel then retries.
293- copyWithConflictResolution(item, targetDir) - Attempts copy and handles 409 conflicts by prompting overwrite/rename/cancel then retries.
294- rootPermissionLabel(root) - Resolves permission key for a root using originalName when available; personal folders resolve to the built-in My Folder label.
295- ensureMoveModal() - Lazily creates and wires Move To modal UI (tree, selection state, confirm/cancel handlers).
296- createMoveNode(folderPath, label) - Builds an expandable/selectable folder node for the Move To tree.
297- loadMoveChildren(containerEl, dirPath) - Lazy-loads subfolders for a tree node via /api/files/list.
298- isInlinePreviewableBlob(blob, name) - Determines if a blob can be previewed inline by MIME/extension.
299- makeFileItem(item) - Builds a .file-item element; roots in Home now use folder-like interaction (single-click focus, double-click open), roots are non-draggable, and mobile long-press contextmenu suppression remains.
300- makeFileItem(item) / renderFileItemName(targetEl, fileName) - Renders tile names with preferred wrap opportunities (space first, then `-`, `,`, `.` via `<wbr>` hints) and preserves original visible text; tile-name CSS clamps to 4 lines with truncation.
301- makeFileItem(item) - Renders tile icons first, then applies any cached watched overlay state (`fully` full-size filled eye, `partway` smaller darker filled eye).
302- loadWatchedStatusesForCurrentDir() - Fetches watched states in one bulk POST /files/watched-statuses request per directory (with legacy /files/meta fallback), caches statuses per path, and updates tile overlays quickly.
303- attachMobileLongPress(el, item) - Adds mobile long-press detection on file/folder tiles to open the item sidebar without desktop side effects.
304- beginSidebarLoad() - Aborts in-flight sidebar requests and increments a load token so stale async responses cannot mutate the current sidebar state.
305- renderItemActionButtons(actions, item) - Shared action renderer used by sidebar and custom context menu so file/folder actions stay identical.
306- createFolderInCurrentDir() - Shared folder-creation flow used by toolbar and custom context menu.
307- openItemContextMenu(item, x, y) / openFolderContextMenu(x, y) - Desktop custom right-click menus that replace the native context menu for item and background interactions.
308- addContextMenuSubmenu(...) / addContextMenuButton(...) - Context-menu builders used for Sort by / Group by submenus and checkbox-style toggle rows.
309- openSidebar(item) - Renders item details/actions in sidebar; roots show alias + original name + usage stats, hide Move To/Delete, keep Rename.
310- openSidebar(item) - Personal user roots display access as private and skip /files/root-access lookups to avoid forbidden noise.
311- openSidebar(item) - Uses abortable metadata/access requests and stale-load guards to prevent race-condition UI duplication when selection changes quickly.
312- canWrite(item) - Resolves whether the current user may write to the selected item/root; personal folders are always writable for the owner.
313- fetchRootAccessList(rootPath) - Fetches root access users from the server for a specific configured root.
314- formatRootAccessList(users) - Formats root access entries as "username mode" values for sidebar rendering.
315- openSidebar(item) - Renders item details/actions in sidebar; root selections include alias/original name/usage/access list and keep Rename while hiding Move To/Delete.
316- openFolderSidebar() - Shows current folder details when nothing is selected; when at root base-level it also shows root access list.
317- openFolderSidebar() / renderFolderViewControls(actions, dirPath) - In folder overview mode, renders per-folder view controls (Sort by, Group by, folders-first, ascending) and persists them per user+folder in localStorage.
318- renderFileGrid() / buildFileGridRows(items, prefs) - Applies folder view ordering as Group option > folders-first option > sort option, inserts labelled separator rows when grouping is enabled, and uses relative date labels for recent date groups (`today`, `yesterday`, `two`-`six days ago`, `one week ago`) before falling back to calendar dates.
319- openRenameModal(item) - Renames files/folders; for roots this writes display alias via /api/files/root-alias and reloads roots.
320- uploadFiles(fileList) - Uploads files one-by-one with per-file conflict prompt (overwrite/rename/cancel) when names already exist.
321- openUserModal(user, paths) - Admin user editor; enforces UI permission rule that Write is disabled/unchecked while Read is unchecked and disables the Admin checkbox when editing the current signed-in admin account.
322- refreshAdminOrphanUserFolders() UI flow - Admin panel shows orphaned user folders only when present and opens selected orphan folder from the section button.
323
324## public/drag-move.js
325- makeDraggable(el, item) - Attaches pointerdown to a .file-item; starts drag after threshold movement. Depends on: api(), canWrite(), navigateTo(), STATE, closeSidebar(), toast() from app.js.
326- makeDraggable(el, item) - Touch drag now requires a short hold before movement, uses pointer capture, and keeps drag responsive on mobile.
327- (internal) _beginDrag(e, el, item) - Lifts and re-parents the real .file-item to body, inserts hidden placeholder, and shows parent-folder drag target when applicable.
328- (internal) _moveDrag(e) - Moves the real dragged item, hit-tests folder tiles, breadcrumb segments, and parent-folder target, toggles target highlight state.
329- (internal) _endDrag() - On valid target: runs drop animation, calls moveWithConflictResolution() for overwrite/rename/cancel conflicts, then refreshes dir. Otherwise snap-back.
330- (internal) _cleanupDrag(reinsert) - Restores tile styles; reinserts into grid on failure/abort or removes before refresh on success, hides drag helper targets.
331
332## public/drag-move.css
333- .file-item.dragging - Lifted style for real dragged tile.
334- .file-item.drop-target - Glows folder icon when drag hovers over it.
335- .drag-parent-target - Temporary top-left "move to parent" drop target shown while dragging in nested folders.
336- .crumb-drop-target.active - Highlight style for breadcrumb drop destinations during drag.
337- @keyframes drag-rise-spin-fall - Real tile rises, spins, falls/scales into folder on drop.
338- @keyframes folder-bounce - Target folder bounces down then back on accept.
339- .preview-backdrop/.file-item--preview/.preview-expand-* - In-place expanded tile preview styling (no separate overlay window), including preserved icon-outline layer.
340- .preview-expand-share - Secondary action button positioned next to .preview-expand-download in expanded file preview.
341- .move-modal/.move-tree/.move-node* - Move To tree picker styles with expandable/collapsible folder hierarchy.
342
343## public/style.css
344- #sidebar-duplicates + related classes - Sidebar duplicate-file list styling with truncation and hover feedback.
345- .admin-size-feedback(.ok/.err) - Validation feedback styling for admin user-folder size-limit input.
346- .top-search* + .global-favicon-preview - Topbar file search controls and global favicon preview button styling.
347- .folder-icon-filter - Search input styling for live filtering in the icon-picker modal.
348- .custom-context-menu* - Desktop context-menu layout with separators and hover-open submenus for folder view options.
349
350## tests/auth.routes.test.js
351- session lifecycle / POST /api/auth/logout revokes active session - Verifies explicit logout invalidates token immediately.
352- session lifecycle / session expires after 1 hour of inactivity - Verifies server-side idle timeout enforcement.
353- POST /api/auth/change-password / rejects incorrect current password - Verifies password-change validation when current password is wrong.
354- POST /api/auth/change-password / updates password and invalidates old login credentials - Verifies successful password update and old-password login failure.
355
356## tests/page.load.test.js
357- bootClient() - Boots the app in jsdom and waits until app shell is visible or timeout before assertions.
358- waitFor(dom, predicate, timeoutMs) - Poll helper used by interaction tests to wait for rendered tiles.
359- login overlay uses username and current-password autocomplete tokens - Verifies normal sign-in mode exposes browser-friendly login autocomplete attributes.
360- first-run setup uses new-password autocomplete token - Verifies setup mode switches the password field to the browser-friendly new-password token.
361- desktop right-click uses custom context menu for files and folder background - Verifies desktop context menu replacement and folder-view option entries.
362- expanded file preview shows a Share button next to Download - Verifies expanded preview UI includes both actions inside a dedicated footer below the preview content.
363- expanded STL preview falls back gracefully when WebGL is unavailable - Verifies STL preview path shows a clear fallback message when WebGL contexts are unavailable.
364- expanded video preview uses a stream session and video.js - Verifies streamed video preview uses the server-backed HLS session and registers subtitle tracks with video.js.
365- video preview does not close on backdrop click and closes via X button - Verifies video previews require explicit close via X.
366- video preview restores per-user saved volume preference - Verifies per-user saved video volume is applied on preview open.
367- video preview restores saved subtitle/audio track names when available - Verifies per-user subtitle/audio selections are reapplied by matching track names.
368- video preview keeps default tracks when saved names are not present - Verifies subtitle/audio defaults remain unchanged when saved names are missing.
369- video preview saves subtitle/audio track names per user when selection changes - Verifies subtitle/audio selections are persisted into per-user video preferences.
370- video preview applies caption overrides per open - Verifies requested caption overrides are always loaded into Video.js settings.
371- video preview does not save caption style settings per user on close - Verifies caption style changes are not persisted to per-user video preferences.
372- video preview releases the backend stream session when closed - Verifies closing a streamed video preview sends an explicit backend release call.
373- rapid file reselection does not duplicate sidebar action buttons after delayed metadata - Verifies stale sidebar loads are ignored so action buttons are not duplicated.
374- video tiles show centred watched overlays after watched metadata is loaded - Verifies overlays remain absent until watched metadata is fetched, then render as solid eye icons for fully and partway statuses.
375- shows pending icon spinner when video thumbnail cache is not ready - Verifies video tiles use thumbnail-cache loading (instead of badge fallback) and pending-state UI.
376
377## tests/video-stream.test.js
378- createVideoStreamSession resolves once ffmpeg starts writing stream assets - Verifies session creation no longer waits for the final master playlist before preview can begin.
379- createVideoStreamSession configures flat segment filenames that match playlist URLs - Verifies ffmpeg segment output paths match the segment URLs emitted in the generated HLS playlists.
380- createVideoStreamSession does not become ready from subtitle files alone - Verifies stream readiness is tied to HLS output instead of extracted subtitle files.
381- createVideoStreamSession keeps playback available when subtitle conversion fails - Verifies subtitle conversion failures are skipped without breaking stream playback.
382- sendVideoStreamAsset prunes old segment files after playback moves far ahead - Verifies old segments are removed only after the retention window passes.
383- createVideoStreamSession reuses one transcode for concurrent viewers of the same file - Verifies two viewers share one ffmpeg transcode while keeping independent lease release behaviour.
384
385## tests/share.page.load.test.js
386- applies default caption settings for share-page video playback - Verifies requested caption defaults are applied and persisted on share-page video preview.
387- restores and saves share-page subtitle/audio track preferences by name - Verifies share-page subtitle/audio choices are restored and persisted by track-name matching.
388
389## tests/files.routes.test.js
390- POST /api/files/watch-progress stores per-user watched status by thresholds - Verifies watch-status persistence and no downgrade from fully to partway.
391- DELETE /api/files/video-stream/:sessionId releases an active stream session - Verifies explicit stream session release route wiring.
392
393## public/vendor/three/three.module.js
394- Third-party Three.js runtime module (vendored, unmodified) used for client-side 3D previews.
395
396## public/vendor/three/addons/controls/OrbitControls.js
397- Third-party OrbitControls module (vendored, unmodified) providing drag-rotate and wheel-zoom interactions.
398
399## public/vendor/three/addons/loaders/STLLoader.js
400- Third-party STL parser module (vendored, unmodified) for client-side `.stl` geometry loading.
401
402## public/vendor/three/addons/loaders/OBJLoader.js
403- Third-party OBJ parser module (vendored, unmodified) for client-side `.obj` geometry loading.