| 1 | # Technical Reference
|
| 2 |
|
| 3 | ## server/index.js
|
| 4 | - start() - Initialises DB/keys, starts HTTP/HTTPS servers, and starts the background thumbnail cache loop.
|
| 5 | - shutdown(opts, ...servers) - Graceful teardown: stops thumbnail loop, closes DB/servers, exits with configurable code after drain/timeout.
|
| 6 | - Express error handler - Logs uncaught route errors to logs.txt before returning a JSON 500 response.
|
| 7 | - 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.
|
| 8 |
|
| 9 | ## server/logger.js
|
| 10 | - 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.
|
| 11 |
|
| 12 | ## server/image-subtitles.js
|
| 13 | - 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.
|
| 14 | - renderImageSubtitleFrame({ filePath, streamIndex, timeSeconds, canvasWidth, canvasHeight }) - Extracts bitmap subtitle streams to cached `.sup`, parses PGS display sets, and returns cached/composited PNG subtitle frames for a requested timestamp; returns null when no subtitle is active.
|
| 15 | - clearCachesForFile(filePath) - Removes all event and frame cache entries for a given file path; called when video stream sessions end to prevent memory accumulation.
|
| 16 |
|
| 17 | ## server/thumbnail-cache.js
|
| 18 | - 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.
|
| 19 | - startThumbnailCacheLoop() - Schedules cache sync runs 5 seconds after boot and 5 seconds after each run completes.
|
| 20 | - stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
|
| 21 | - getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
|
| 22 | - getThumbPathForSourceFile(sourceFile) - Maps an absolute source file path to its mirrored cache thumbnail path.
|
| 23 | - getThumbRelPathForSourceFile(sourceFile) - Returns public-relative thumbnail path used in manifest entries.
|
| 24 | - getFilesWithThumbnailsInDir(dirPath) - Returns [{filePath, thumbRelPath}] for all files inside dirPath (recursive) that have a cached thumbnail; sorted by filePath.
|
| 25 | - getFolderIconSourceFile(folderPath) - Returns the source image path for a folder's icon: explicit assignment first, then auto-first cached image, null if none.
|
| 26 | - setFolderIconAssignment(folderPath, imagePath) - Saves an explicit folder icon assignment to .folder-icons.json; pass null to clear (auto-detect used instead).
|
| 27 |
|
| 28 | ## server/db.js
|
| 29 | - 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.
|
| 30 | - getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
|
| 31 | - closeDb() - Closes singleton DB handle to release file locks.
|
| 32 |
|
| 33 | ## server/auth.js
|
| 34 | - createToken(username, req, fingerprint) - Creates JWT bound to IP/region/fingerprint and linked to a DB-backed session id.
|
| 35 | - requireAuth(req, res, next) - Verifies JWT + binding + session row + 1-hour idle timeout, updates last_seen_at, and attaches req.user.
|
| 36 | - requireAdmin(req, res, next) - Requires authenticated admin user.
|
| 37 | - revokeSession(sessionId) - Revokes a session row so future token use fails immediately.
|
| 38 | - getClientIp(req) - Normalizes request IP (including IPv4-mapped IPv6 loopback cases).
|
| 39 | - getRegion(ip) - Derives coarse region binding from geoip lookup or local fallback.
|
| 40 | - SESSION_IDLE_TIMEOUT_MS - Server-enforced idle timeout window (1 hour).
|
| 41 |
|
| 42 | ## server/routes/auth.js
|
| 43 | - extractCredentials(body) - Accepts encrypted payloads and compatibility plaintext payloads for login/setup.
|
| 44 | - makeAuthResponse(token, clientPublicKey) - Returns encrypted token when client key exists, plaintext token otherwise.
|
| 45 | - POST /api/auth/setup - Creates first admin and issues token.
|
| 46 | - POST /api/auth/login - Authenticates user by case-insensitive username match and issues token with canonical stored username.
|
| 47 | - GET /api/auth/me - Returns current authenticated user profile.
|
| 48 | - POST /api/auth/logout - Revokes the active session.
|
| 49 |
|
| 50 | ## server/routes/admin.js
|
| 51 | - POST /api/admin/users - Creates a new user and enforces case-insensitive username uniqueness.
|
| 52 | - normalizePermissions(permissions) - Normalizes permission maps and enforces that write access implies read access.
|
| 53 | - ensureUserFolders(userPath) - Ensures configured userPath exists and creates per-user subfolders for all current users.
|
| 54 | - GET /api/admin/config - Returns admin config including userPath and userFolderSizeLimit (bytes, null for unlimited).
|
| 55 | - PUT /api/admin/config - Persists paths plus userPath/userFolderSizeLimit and ensures per-user folders exist.
|
| 56 | - GET /api/admin/update-status - Returns { underSystemd, commitsAhead[] }. Detects systemd via INVOCATION_ID env var; runs git fetch + git log to find commits ahead of HEAD. Used by the frontend to set button label (Shut down server / Restart Server / Restart & Update).
|
| 57 |
|
| 58 | ## server/routes/files.js
|
| 59 | - GET /api/files/roots - Returns readable roots with display label (alias when configured), originalName, and path.
|
| 60 | - GET /api/files/roots - Adds a synthetic 'My folder' root for the authenticated user when userPath is configured.
|
| 61 | - loadConfigAndRoots() - Loads config and effective roots together so route access checks stay consistent.
|
| 62 | - resolveRootForUser(absPath, roots, user, config) - Resolves access for configured roots plus user-owned personal folder.
|
| 63 | - canReadInfo(user, info) / canWriteInfo(user, info) - Permission checks that automatically allow access for personal user-folder roots.
|
| 64 | - checkUserFolderSizeLimit(config, username, addedBytes) - Validates a user-folder capacity limit against current usage.
|
| 65 | - POST /api/files/root-alias - Sets a display-only alias for an exact configured root path (no filesystem rename).
|
| 66 | - GET /api/files/root-access - Returns users who can access an exact configured root and their access mode (R / R+W).
|
| 67 | - GET /api/files/meta - Returns file metadata and lazily computes/stores sha256 when missing.
|
| 68 | - GET /api/files/duplicates - Returns accessible files that share the selected file's sha256 hash.
|
| 69 | - GET /api/files/space - Returns used/free disk space and, for personal folders, user-limit fields (userLimitBytes/userFreeBytes).
|
| 70 | - GET /api/files/thumbnail - Serves cache-only thumbnail images for authorized files; returns 404 while cache is not ready.
|
| 71 | - GET /api/files/folder-images - Returns files inside a directory (recursive) that already have a cached thumbnail (including video thumbnails when cached).
|
| 72 | - 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.
|
| 73 | - POST /api/files/folder-icon - Sets or clears a folder's explicit icon assignment; imagePath must have a cached thumbnail; write access required.
|
| 74 | - 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/.
|
| 75 | - makeTempUploadPath(dir, originalName) - Builds a hidden per-upload staging filename in the target directory for multipart uploads.
|
| 76 | - unlinkIfExists(targetPath, cb) - Removes a file during upload cleanup while ignoring already-missing temp files.
|
| 77 | - promoteUploadedFile(tempPath, finalPath, cb) - Atomically renames a completed staged upload into place on the Linux server.
|
| 78 | - splitNameExt(name) - Splits a filename into stem/ext, preserving dotless names and hidden-file behavior.
|
| 79 | - pickNumberedPath(dir, requestedName) - Finds the first free `name (n).ext` path inside a directory.
|
| 80 | - removePathRecursive(targetPath) - Deletes existing file or directory destination to support overwrite moves.
|
| 81 | - movePathWithFallback(from, dest) - Moves files/folders with an EXDEV copy-then-delete fallback so cross-device moves into My Folder still succeed.
|
| 82 | - POST /api/files/upload - Streams multipart uploads into hidden temp files, computes/stores sha256, and enforces user-folder size limits.
|
| 83 | - POST /api/files/move - Moves file/folder; supports conflict strategies: `error` (default), `overwrite`, or `rename` with optional `targetName`.
|
| 84 | - POST /api/files/copy - Copies a file to a destination folder with conflict strategies (`error`, `overwrite`, `rename`) and user-folder size-limit checks.
|
| 85 | - 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}).
|
| 86 | - GET /api/files/video-stream-subtitle-frame - Authenticated. Renders a PNG subtitle frame for bitmap subtitle tracks via cached PGS decode/composite flow; on failures or no active subtitle it returns 204 so the client can stop retrying.
|
| 87 | - DELETE /api/files/video-stream/:sessionId - Explicitly releases an active short-lived video stream session and stops backend processing.
|
| 88 | - 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' } }.
|
| 89 | - POST /api/files/watch-progress - Records per-user watch status (`partway` >=10%, `fully` >=70%) for sidebar "Watched by" display.
|
| 90 |
|
| 91 | ## server/routes/share.js
|
| 92 | - getUserFolderPath(config, username) - Resolves the owning user's personal folder path from config.userPath.
|
| 93 | - resolveRootForUser(absPath, roots, user, config) - Resolves configured roots plus the owning user's personal folder for share checks.
|
| 94 | - canReadInfo(user, info) - Read-check helper that always allows the owner of a personal folder root.
|
| 95 | - 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.
|
| 96 | - GET /api/share/info/:token - Public. Returns {name, isDir, expiresAt} for a valid non-expired token; 410 when expired, 404 when unknown.
|
| 97 | - GET /api/share/preview/:token - Public. Streams file content inline for preview (files only, max 50 MB); 400 for directories, 410 expired.
|
| 98 | - GET /api/share/download/:token - Public. Downloads the file or a zip of the directory for a valid token; 410 expired.
|
| 99 | - 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}).
|
| 100 | - 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.
|
| 101 | - buildZip(dirPath, cacheKey) - Creates (or returns cached) zip in zip-cache/; prunes stale zips before building; exported for reuse in files.js.
|
| 102 | - pruneZipCache() - Deletes zip files in zip-cache/ older than 1 day; called automatically before each zip build.
|
| 103 | - ZIP_CACHE_DIR - Absolute path to the zip-cache/ directory (project root).
|
| 104 |
|
| 105 | ## server/video-stream.js
|
| 106 | - 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.
|
| 107 | - 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.
|
| 108 | - releaseVideoStreamSession(sessionId) - Releases one viewer lease; only destroys the underlying transcode session when no active leases remain; cleanup also clears image subtitle frame/event caches to prevent memory accumulation.
|
| 109 | - runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and clears image subtitle caches whenever the prune cutoff advances, so subtitle buffers follow the same retention rules as video chunks.
|
| 110 | - STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
|
| 111 | - STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
|
| 112 | - STREAM_IDLE_STOP_MS - Maximum client inactivity window before an active stream session is terminated (5 minutes).
|
| 113 | - 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.
|
| 114 |
|
| 115 | ## server/db.js
|
| 116 | - initDb() - Initializes SQLite schema for users, file metadata, auth_sessions, and share_tokens (expires_at index).
|
| 117 | - getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
|
| 118 | - closeDb() - Closes singleton DB handle to release file locks.
|
| 119 |
|
| 120 | ## public/share.html
|
| 121 | - Standalone public share page served at /share/:token; no auth required.
|
| 122 | - Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
|
| 123 | - tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
|
| 124 | - Share video preview - Uses the same Video.js playback behaviour as app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), and subtitle/audio track restore/save by matching track names when available.
|
| 125 | - Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
|
| 126 | - Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.
|
| 127 |
|
| 128 | ## public/index.html
|
| 129 | - Auth form - Login/setup form uses username plus mode-specific password autocomplete tokens so browser password managers behave correctly.
|
| 130 | - Admin modal - Includes User Folders controls (user path + per-user size limit) and a dedicated save action for that config.
|
| 131 | - Import map - Maps `three` and `three/addons/` to local vendored modules for client-side STL/OBJ previews.
|
| 132 |
|
| 133 | ## public/app.js
|
| 134 | - showApp() - Reveals app shell; keeps sidebar folded by default on mobile and shows folder overview sidebar on desktop.
|
| 135 | - showAuthOverlay(setupMode) - Displays the login/setup overlay and switches the password autocomplete token between current-password and new-password based on mode.
|
| 136 | - getOrCreateClientBindingId() - Creates/loads a persistent local browser binding id used in auth fingerprint derivation.
|
| 137 | - getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
|
| 138 | - saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
|
| 139 | - loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
|
| 140 | - api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
|
| 141 | - performLogout() - Explicit logout path that revokes server session and clears local session state.
|
| 142 | - initAuth() - Restores prior session when valid and auto-logins without credential prompt.
|
| 143 | - showConfirm(title, message, { html, okLabel }) - In-page confirm dialog; returns Promise<boolean>. `html=true` renders message as innerHTML (caller must escape user data). `okLabel` overrides the OK button text. Use instead of window.confirm().
|
| 144 | - escHtml(s) - HTML-escapes a string (& < > ") for safe use with innerHTML in confirm messages.
|
| 145 | - showPrompt(title, message, defaultValue) - In-page text-input dialog; returns Promise<string|null>. Use instead of window.prompt().
|
| 146 | - showOverwrite(filename) - In-page overwrite-decision dialog for file conflicts; returns Promise<'yes'|'no'|'all'|'none'>.
|
| 147 | - splitNameExt(name) - Client-side filename splitter used for local conflict rename suggestions.
|
| 148 | - nextAvailableName(requestedName, existingNames) - Computes `name (n).ext` for upload/move rename options.
|
| 149 | - listDirNameSet(dir) - Fetches directory listing and returns a Set of existing names.
|
| 150 | - cloneFileWithName(file, newName) - Creates a renamed File object for non-overwrite uploads.
|
| 151 | - showFileConflictChoice(filename, renameTo, mode) - Dialog for single upload/move conflicts; returns overwrite/rename/cancel.
|
| 152 | - parseHumanSize(input) - Parses human-readable sizes like `25 MB`/`1gb` into bytes for admin user-folder limits.
|
| 153 | - updateAdminSizeFeedback(rawValue) - Validates size input and updates admin hint text/classes with parsed byte preview.
|
| 154 | - relativePathFromRoot(targetPath, rootPath) - Produces a root-relative path string for sidebar folder context display.
|
| 155 | - displayPathWithRootLabel(targetPath, rootPath, rootLabel) - Produces Linux-style root-relative display paths like `/Downloads/A/B` for folder context UI.
|
| 156 | - 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.
|
| 157 | - loadThumbnails() - Registers visible file icons for lazy thumbnail loading (both file thumbnails and folder icons); retries missing cache thumbnails during incremental refresh.
|
| 158 | - 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.
|
| 159 | - 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.
|
| 160 | - 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.
|
| 161 | - observeFolderIcon(iconEl) - Registers a folder icon element with IntersectionObserver for lazy loading.
|
| 162 | - loadOneFolderIcon(iconEl) - Fetches /api/files/folder-icon then the thumbnail blob and overlays it inside the folder SVG; no-op if no icon available.
|
| 163 | - applyFolderThumbnail(iconEl, srcUrl) - Injects an SVG <image> element clipped to the folder outline path into the folder's icon SVG.
|
| 164 | - openFolderIconPicker(item) - Opens the folder icon picker modal; shows cached-thumbnail files from the folder (including video thumbnails); allows selection, clearing, and cancellation.
|
| 165 | - refreshAfterIconChange(item) - Resets and reloads the folder icon in both the grid tile and sidebar after set/clear operations.
|
| 166 | - disconnectFolderIconObserver() - Disconnects and clears the folder icon IntersectionObserver on grid rebuild.
|
| 167 | - getThumbnailKind(name) - Classifies files into image/text/badge thumbnail strategies.
|
| 168 | - observeThumbnailIcon(iconEl) - Defers thumbnail fetch work until file icons are near/in the viewport.
|
| 169 | - disconnectThumbnailObserver() - Clears active IntersectionObserver when the grid is rebuilt.
|
| 170 | - setThumbnailPending(iconEl, pending) - Toggles per-icon pending spinner state while a cached image thumbnail is not ready yet.
|
| 171 | - buildThumbnailSource(item, blob, kind) - Produces thumbnail image source (data/blob URL) for icon injection.
|
| 172 | - buildAuthHeaders() - Builds the authenticated fetch headers used by preview-side API calls that need the bearer token plus fingerprint header.
|
| 173 | - 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; 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); disables the track after the first failed frame request to avoid repeated polling.
|
| 174 | - 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.
|
| 175 | - modelPreviewType(name) - Classifies direct client-side 3D preview support for `.stl` and `.obj`.
|
| 176 | - loadThreePreviewModules() - Lazy-loads Three.js plus OrbitControls/STLLoader/OBJLoader via import map aliases.
|
| 177 | - 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.
|
| 178 | - buildModelObjectFromBlob(blob, type, modules) - Parses STL/OBJ blobs and produces a geometry-only model using the standard blue material.
|
| 179 | - renderModelPreview(item, blob, targetEl) - Renders interactive STL/OBJ previews (drag rotate + scroll zoom) with WebGL fallback messaging when unavailable.
|
| 180 | - closePreview(opts) - Closes expanded previews; video previews ignore backdrop close and require explicit close action.
|
| 181 |
|
| 182 | ## tests/thumbnail-cache.test.js
|
| 183 | - thumbnail cache worker / creates cached thumbnail with dimensions smaller than 100px - Verifies cached image generation and manifest write.
|
| 184 | - thumbnail cache worker / removes cached thumbnail when source file is deleted - Verifies stale thumbnail cleanup behavior.
|
| 185 | - thumbnail cache worker / creates cached thumbnail for video files using ffmpeg frame extraction - Verifies video thumbnail generation uses ffprobe duration and ffmpeg frame capture.
|
| 186 | - afterEach() cleanup - Removes temp roots with `fs.rmSync(...maxRetries...)` to tolerate transient Windows file locks.
|
| 187 | - detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension.
|
| 188 | - prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering.
|
| 189 | - highlightCode(raw, lang) - Escapes and syntax-highlights preview text into HTML spans.
|
| 190 | - fileAccentColor(name) - Returns canonical file-type accent color used by icon strokes and preview sheet outline.
|
| 191 | - openFolderSidebar() - Persistent sidebar fallback view that shows current folder/root overview when no item is selected.
|
| 192 | - closeSidebar() - Clears selection; hides the panel entirely on mobile and restores folder overview sidebar on desktop.
|
| 193 | - isMobileViewport() - Central media-query helper for mobile-only sidebar/interaction behavior.
|
| 194 | - hideSidebarPanel() - Hides sidebar panel and removes sidebar-open layout class from the app shell.
|
| 195 | - renderBreadcrumb() - Builds clickable breadcrumb path and marks each folder segment as a drag-drop move target via .crumb-drop-target and data-path.
|
| 196 | - fetchFileBlob(item) - Downloads a file as Blob with auth headers for preview/download flows.
|
| 197 | - 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.
|
| 198 | - downloadOrView(item, sourceSvgEl) - Opens in-place expanded tile preview from a file icon; shows error toast if no source tile is found.
|
| 199 | - renderPreviewBody(item, blob, objectUrl, targetEl) - Renders preview content (image/video/audio/pdf/text) or unsupported message into a target container.
|
| 200 | - animateRect(el, fromRect, toRect, opts) - Helper that animates element rectangle (left/top/width/height) for expand/collapse transitions.
|
| 201 | - openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents the real file tile to body, expands it to viewport preview, injects close/download controls.
|
| 202 | - 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.
|
| 203 | - 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.
|
| 204 | - closeExpandedTilePreview() - Collapses expanded tile preview back to the original grid slot, restores original icon markup, and removes the preview placeholder.
|
| 205 | - closePreview() - Closes either expanded-tile preview or overlay preview, then revokes active preview object URL.
|
| 206 | - closePreview() - Closes expanded-tile preview and revokes active preview object URL.
|
| 207 | - openMovePicker(item) - Opens Move To selector modal with expandable folder tree across all writable roots and executes /api/files/move.
|
| 208 | - openCopyPicker(item) - Opens Copy To selector modal with the same tree and executes /api/files/copy.
|
| 209 | - openDestinationPicker(item, mode) - Shared destination picker state/labels for move vs copy operations.
|
| 210 | - moveWithConflictResolution(item, targetDir) - Attempts move and handles 409 conflicts by prompting overwrite/rename/cancel then retries.
|
| 211 | - copyWithConflictResolution(item, targetDir) - Attempts copy and handles 409 conflicts by prompting overwrite/rename/cancel then retries.
|
| 212 | - rootPermissionLabel(root) - Resolves permission key for a root using originalName when available; personal folders resolve to the built-in My Folder label.
|
| 213 | - ensureMoveModal() - Lazily creates and wires Move To modal UI (tree, selection state, confirm/cancel handlers).
|
| 214 | - createMoveNode(folderPath, label) - Builds an expandable/selectable folder node for the Move To tree.
|
| 215 | - loadMoveChildren(containerEl, dirPath) - Lazy-loads subfolders for a tree node via /api/files/list.
|
| 216 | - isInlinePreviewableBlob(blob, name) - Determines if a blob can be previewed inline by MIME/extension.
|
| 217 | - 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.
|
| 218 | - makeFileItem(item) - Renders tile icons first, then applies any cached watched overlay state (`fully` full-size filled eye, `partway` smaller darker filled eye).
|
| 219 | - 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.
|
| 220 | - attachMobileLongPress(el, item) - Adds mobile long-press detection on file/folder tiles to open the item sidebar without desktop side effects.
|
| 221 | - beginSidebarLoad() - Aborts in-flight sidebar requests and increments a load token so stale async responses cannot mutate the current sidebar state.
|
| 222 | - openSidebar(item) - Renders item details/actions in sidebar; roots show alias + original name + usage stats, hide Move To/Delete, keep Rename.
|
| 223 | - openSidebar(item) - Personal user roots display access as private and skip /files/root-access lookups to avoid forbidden noise.
|
| 224 | - openSidebar(item) - Uses abortable metadata/access requests and stale-load guards to prevent race-condition UI duplication when selection changes quickly.
|
| 225 | - canWrite(item) - Resolves whether the current user may write to the selected item/root; personal folders are always writable for the owner.
|
| 226 | - fetchRootAccessList(rootPath) - Fetches root access users from the server for a specific configured root.
|
| 227 | - formatRootAccessList(users) - Formats root access entries as "username mode" values for sidebar rendering.
|
| 228 | - 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.
|
| 229 | - openFolderSidebar() - Shows current folder details when nothing is selected; when at root base-level it also shows root access list.
|
| 230 | - openRenameModal(item) - Renames files/folders; for roots this writes display alias via /api/files/root-alias and reloads roots.
|
| 231 | - uploadFiles(fileList) - Uploads files one-by-one with per-file conflict prompt (overwrite/rename/cancel) when names already exist.
|
| 232 | - openUserModal(user, paths) - Admin user editor; enforces UI permission rule that Write is disabled/unchecked while Read is unchecked.
|
| 233 |
|
| 234 | ## public/drag-move.js
|
| 235 | - 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.
|
| 236 | - makeDraggable(el, item) - Touch drag now requires a short hold before movement, uses pointer capture, and keeps drag responsive on mobile.
|
| 237 | - (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.
|
| 238 | - (internal) _moveDrag(e) - Moves the real dragged item, hit-tests folder tiles, breadcrumb segments, and parent-folder target, toggles target highlight state.
|
| 239 | - (internal) _endDrag() - On valid target: runs drop animation, calls moveWithConflictResolution() for overwrite/rename/cancel conflicts, then refreshes dir. Otherwise snap-back.
|
| 240 | - (internal) _cleanupDrag(reinsert) - Restores tile styles; reinserts into grid on failure/abort or removes before refresh on success, hides drag helper targets.
|
| 241 |
|
| 242 | ## public/drag-move.css
|
| 243 | - .file-item.dragging - Lifted style for real dragged tile.
|
| 244 | - .file-item.drop-target - Glows folder icon when drag hovers over it.
|
| 245 | - .drag-parent-target - Temporary top-left "move to parent" drop target shown while dragging in nested folders.
|
| 246 | - .crumb-drop-target.active - Highlight style for breadcrumb drop destinations during drag.
|
| 247 | - @keyframes drag-rise-spin-fall - Real tile rises, spins, falls/scales into folder on drop.
|
| 248 | - @keyframes folder-bounce - Target folder bounces down then back on accept.
|
| 249 | - .preview-backdrop/.file-item--preview/.preview-expand-* - In-place expanded tile preview styling (no separate overlay window), including preserved icon-outline layer.
|
| 250 | - .preview-expand-share - Secondary action button positioned next to .preview-expand-download in expanded file preview.
|
| 251 | - .move-modal/.move-tree/.move-node* - Move To tree picker styles with expandable/collapsible folder hierarchy.
|
| 252 |
|
| 253 | ## public/style.css
|
| 254 | - #sidebar-duplicates + related classes - Sidebar duplicate-file list styling with truncation and hover feedback.
|
| 255 | - .admin-size-feedback(.ok/.err) - Validation feedback styling for admin user-folder size-limit input.
|
| 256 |
|
| 257 | ## tests/auth.routes.test.js
|
| 258 | - session lifecycle / POST /api/auth/logout revokes active session - Verifies explicit logout invalidates token immediately.
|
| 259 | - session lifecycle / session expires after 1 hour of inactivity - Verifies server-side idle timeout enforcement.
|
| 260 |
|
| 261 | ## tests/page.load.test.js
|
| 262 | - bootClient() - Boots the app in jsdom and waits until app shell is visible or timeout before assertions.
|
| 263 | - waitFor(dom, predicate, timeoutMs) - Poll helper used by interaction tests to wait for rendered tiles.
|
| 264 | - login overlay uses username and current-password autocomplete tokens - Verifies normal sign-in mode exposes browser-friendly login autocomplete attributes.
|
| 265 | - first-run setup uses new-password autocomplete token - Verifies setup mode switches the password field to the browser-friendly new-password token.
|
| 266 | - 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.
|
| 267 | - expanded STL preview falls back gracefully when WebGL is unavailable - Verifies STL preview path shows a clear fallback message when WebGL contexts are unavailable.
|
| 268 | - 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.
|
| 269 | - video preview does not close on backdrop click and closes via X button - Verifies video previews require explicit close via X.
|
| 270 | - video preview restores per-user saved volume preference - Verifies per-user saved video volume is applied on preview open.
|
| 271 | - video preview restores saved subtitle/audio track names when available - Verifies per-user subtitle/audio selections are reapplied by matching track names.
|
| 272 | - video preview keeps default tracks when saved names are not present - Verifies subtitle/audio defaults remain unchanged when saved names are missing.
|
| 273 | - video preview saves subtitle/audio track names per user when selection changes - Verifies subtitle/audio selections are persisted into per-user video preferences.
|
| 274 | - video preview applies caption overrides per open - Verifies requested caption overrides are always loaded into Video.js settings.
|
| 275 | - video preview does not save caption style settings per user on close - Verifies caption style changes are not persisted to per-user video preferences.
|
| 276 | - video preview releases the backend stream session when closed - Verifies closing a streamed video preview sends an explicit backend release call.
|
| 277 | - rapid file reselection does not duplicate sidebar action buttons after delayed metadata - Verifies stale sidebar loads are ignored so action buttons are not duplicated.
|
| 278 | - 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.
|
| 279 | - 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.
|
| 280 |
|
| 281 | ## tests/video-stream.test.js
|
| 282 | - createVideoStreamSession resolves once ffmpeg starts writing stream assets - Verifies session creation no longer waits for the final master playlist before preview can begin.
|
| 283 | - createVideoStreamSession configures flat segment filenames that match playlist URLs - Verifies ffmpeg segment output paths match the segment URLs emitted in the generated HLS playlists.
|
| 284 | - createVideoStreamSession does not become ready from subtitle files alone - Verifies stream readiness is tied to HLS output instead of extracted subtitle files.
|
| 285 | - createVideoStreamSession keeps playback available when subtitle conversion fails - Verifies subtitle conversion failures are skipped without breaking stream playback.
|
| 286 | - sendVideoStreamAsset prunes old segment files after playback moves far ahead - Verifies old segments are removed only after the retention window passes.
|
| 287 | - createVideoStreamSession reuses one transcode for concurrent viewers of the same file - Verifies two viewers share one ffmpeg transcode while keeping independent lease release behaviour.
|
| 288 |
|
| 289 | ## tests/share.page.load.test.js
|
| 290 | - applies default caption settings for share-page video playback - Verifies requested caption defaults are applied and persisted on share-page video preview.
|
| 291 | - 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.
|
| 292 |
|
| 293 | ## tests/files.routes.test.js
|
| 294 | - POST /api/files/watch-progress stores per-user watched status by thresholds - Verifies watch-status persistence and no downgrade from fully to partway.
|
| 295 | - DELETE /api/files/video-stream/:sessionId releases an active stream session - Verifies explicit stream session release route wiring.
|
| 296 |
|
| 297 | ## public/vendor/three/three.module.js
|
| 298 | - Third-party Three.js runtime module (vendored, unmodified) used for client-side 3D previews.
|
| 299 |
|
| 300 | ## public/vendor/three/addons/controls/OrbitControls.js
|
| 301 | - Third-party OrbitControls module (vendored, unmodified) providing drag-rotate and wheel-zoom interactions.
|
| 302 |
|
| 303 | ## public/vendor/three/addons/loaders/STLLoader.js
|
| 304 | - Third-party STL parser module (vendored, unmodified) for client-side `.stl` geometry loading.
|
| 305 |
|
| 306 | ## public/vendor/three/addons/loaders/OBJLoader.js
|
| 307 | - Third-party OBJ parser module (vendored, unmodified) for client-side `.obj` geometry loading.
|