# 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. - start()/shutdown() - Also starts/stops background auth-session and share-token maintenance loops so stale DB rows and zip cache files are trimmed during long uptime. - start()/shutdown() - Also starts/stops the scheduled-restart coordinator, which can trigger a graceful process shutdown (for systemd restart) after scheduled windows and idle-client checks pass. - 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/restart-scheduler.js - startRestartScheduler({ shutdownForRestart }) - Starts a minute-based scheduler that reads persistent restart cadence/time config and triggers shutdown-for-restart only when running under systemd. - Scheduled restart idle guard - After a scheduled window is reached, restart is delayed until there have been no logged-in clients (non-revoked auth sessions) for at least one hour. - getRestartSchedulerSnapshot() - Returns runtime scheduler state (next due timestamp, pending state, last decision/error) for the debug dashboard. - stopRestartScheduler() - Stops the scheduler interval on process shutdown. ## 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 (`-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 and event caches once the slowest viewer has passed event end time plus a 5-second grace window (e.g., event ending at 30s is dropped after slowest viewer reaches 35s); runs unconditionally on prune cycles instead of waiting for event-cache byte cap pressure so old subtitle image bytes are released promptly. - 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. - initDb() - Also creates `user_last_navigation` to persist each user's last visited folder path and timestamp across sessions. - 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. - purgeStaleSessions({ nowMs }) - Physically deletes stale `auth_sessions` rows: revoked sessions older than 24 hours and idle sessions older than idle-timeout + 24 hours. - startAuthSessionCleanupLoop() - Starts a 15-minute background purge loop for stale `auth_sessions` rows and runs one purge immediately on startup. - stopAuthSessionCleanupLoop() - Stops the background auth-session purge loop during server shutdown. - getAuthSessionCleanupSnapshot() - Returns auth-session cleanup loop runtime diagnostics (last run time, purged row count, duration, last error). - 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). - AUTH_SESSION_PURGE_INTERVAL_MS / AUTH_SESSION_REVOKED_RETENTION_MS / AUTH_SESSION_IDLE_RETENTION_MS - Environment-agnostic constants controlling stale auth-session purge cadence and retention windows. ## 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. - normaliseScheduledRestartConfig(value, fallback) - Validates/normalises persistent scheduled restart settings ({enabled, cadence, time}) for admin config reads/writes. - 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). - GET /api/admin/config - Also returns persistent scheduled restart settings ({enabled, cadence, time}). - PUT /api/admin/config - Persists paths plus userPath/userFolderSizeLimit and ensures per-user folders exist. - PUT /api/admin/config - Validates and saves scheduled restart settings globally (`scheduledRestart`); rejects schedule updates when the process is not running under systemd. - 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. - GET /api/admin/debug/stream-stats - Also reports server maintenance diagnostics: auth/share row counts, auth/share cleanup loop snapshots, and scheduled-restart runtime state. ## 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. - GET /api/files/roots - Returns `lastDir` when the authenticated user's previously visited folder is still accessible and exists; clears stale/inaccessible saved folders. - 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 - Persists the authenticated user's most recently opened folder in `user_last_navigation` after a successful directory listing. - 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 `` 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= - 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 (, , 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. - purgeExpiredShareTokens({ nowMs }) - Deletes expired `share_tokens` rows so old public links do not accumulate in SQLite. - startShareMaintenanceLoop() / stopShareMaintenanceLoop() - Runs periodic share maintenance every 30 minutes: purge expired share tokens and prune stale zip-cache files; started/stopped from server lifecycle. - runShareMaintenanceOnce() - Single-run helper used at startup and by the periodic share maintenance interval. - getShareMaintenanceSnapshot() - Returns share-maintenance loop diagnostics (last run time, deleted token/zip counts, duration, last error). - 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, background stream-ahead prefetch (session playlist/variant/segment fetches continue towards video end while playback reads cache), seek-bar cache frontier marker (`:`) for walker progress, service-worker-backed HLS segment cache enablement during playback (with per-session cache cleanup on close), 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), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), supports startup warmup with `initialPrefetchSeconds` (default 60s) so early timeline subtitle frames are requested immediately on player load before playback advances, extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure. - bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Cache-frame time matching now uses a small epsilon window around start/end timestamps to avoid boundary misses; cache-only mode can also perform a throttled direct current-frame fallback fetch on cache miss (`cacheMissFallbackEnabled`, `cacheMissFallbackIntervalMs`) so subtitles recover without waiting for another seek/timeupdate cycle. - bindStreamAheadPrefetch(opts) - Starts a background HLS walker that repeatedly fetches the session playlist, discovers variant playlists and media segments, and prefetches those assets into the browser cache so playback can read already-fetched segments while the backend prunes old files; tracks cached-through timeline progress (primary from playlist segment durations, with filename-based segment-index fallback for `.ts/.m4s` naming and a section-ratio fallback from fetched segments/total discovered segments when absolute timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe(). - bindStreamAheadSeekMarker(player, streamAheadPrefetch, opts) - Renders a non-interactive `:` marker on the playback seek bar showing how far the stream-ahead walker has cached through the timeline; subscribes to walker progress updates, updates tooltip text with formatted cached-through time, and removes itself on detach. - enableVideoStreamClientCache() - Registers a shared service worker (`/stream-cache-sw.js`) that caches HLS playlist/segment responses so already-downloaded stream assets remain playable on rewind after server-side segment pruning. - clearVideoStreamClientCache(playlistUrl) - Best-effort cache cleanup helper that removes cached HLS entries for one stream session when preview playback is closed. ## public/stream-cache-sw.js - fetch handler - Caches successful segment/init GET responses for `/api/files/video-stream/*` and `/api/share/video-stream/*` (`.ts/.m4s/.mp4/.aac/.vtt`), intentionally skips `.m3u8` manifests to avoid stale-playlist seek regressions, warms full-body cache entries when playback uses byte-range requests, and can synthesize 206 partial responses from cached full segments so backward seeks keep working after server-side prune. - configureVideoJsBuffering(videojs, opts) - Applies long forward-buffer settings used for file playback when VHS exposes those knobs (goal/max goal plus low-water-line thresholds) so clients keep larger forward buffers before needing network fetches. - 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. - Debug dashboard modal - Includes a server-maintenance section with auth/share row counts, maintenance loop last-run telemetry, and scheduled-restart state. - Admin modal - Includes User Folders controls (user path + per-user size limit) and a dedicated save action for that config. - Admin modal - Server section includes persistent scheduled-restart controls (enable toggle, cadence, time); controls are disabled when not running under systemd. - 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. - loadRoots(opts) - Prefers local restoreDir/rootPath, then server-provided `lastDir`, and opens that folder automatically when still accessible. - api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls. - Browser popstate navigation - Maintains an in-app folder navigation array mirrored to History API state; browser back/forward steps through folder history. - onBrowserPopState(event) - When history reaches browse index 0, shows: "Do you want to close the application and return to the previous webpage?" and on Yes runs normal browser back navigation. - renderDebugDashboardData(data) - Renders the debug dashboard panels, including the subtitle debug cache folder summary and open-folder action. - renderDebugDashboardData(data) - Also renders server-maintenance diagnostics (auth/share row totals, maintenance loop last-run telemetry, scheduled restart status/timing). - 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. `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. 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 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 `` URL. - refreshAdminOrphanUserFolders() - Fetches `/admin/orphan-userfolders`, conditionally renders orphaned folder rows, and wires "Open folder" navigation for admins. - syncScheduledRestartControls(underSystemd) - Enables/disables admin scheduled-restart controls based on systemd availability and the local enable-toggle state. - refreshAdminConfig() / refreshAdminUpdateStatus() - Populate scheduled-restart form values from persisted config and enforce systemd-only control availability. - openAdminModal() / refreshAdminConfig() / refreshAdminUsers() / refreshAdminOrphanUserFolders() - Admin modal refresh chain now captures stable DOM references and exits safely when the document is torn down, preventing async teardown races from throwing post-close errors in tests or quick navigation flows. - 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. - renderStreamedVideoPreview(item) - For authenticated video previews, creates a backend stream session and starts the background stream-ahead prefetch worker so playlist/segment requests can continue independently of playback reads until cleanup. - 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, enables service-worker-backed HLS segment caching for the active stream session (and clears that cache on close), 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 `` 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.