BlueGit

timfa filemanager

Files

filemanager / .github / technical-reference.md

technical-reference.md

technical-reference.md 23.9 KiB Download Raw

Technical Reference

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.

server/thumbnail-cache.js

  • syncThumbnailCacheOnce() - Mirrors configured roots into public/thumbs and generates 99x99-max WebP thumbnails for image files; removes stale thumbnails and updates manifest hashes while preserving prior cache entries for temporarily unavailable roots (e.g. removable mounts).
  • startThumbnailCacheLoop() - Schedules cache sync runs 5 seconds after boot and 5 seconds after each run completes.
  • 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.
  • getImagesWithThumbnailsInDir(dirPath) - Returns [{filePath, thumbRelPath}] for all images inside dirPath (recursive) that have a cached thumbnail; sorted by filePath.
  • getFolderIconSourceFile(folderPath) - Returns the source image path for a folder's icon: explicit assignment first, then auto-first cached image, null if none.
  • setFolderIconAssignment(folderPath, imagePath) - Saves an explicit folder icon assignment to .folder-icons.json; pass null to clear (auto-detect used instead).

server/db.js

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

server/auth.js

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

server/routes/auth.js

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

server/routes/admin.js

  • POST /api/admin/users - Creates a new user and enforces case-insensitive username uniqueness.
  • normalizePermissions(permissions) - Normalizes permission maps and enforces that write access implies read access.

server/routes/files.js

  • GET /api/files/roots - Returns readable roots with display label (alias when configured), originalName, and path.
  • 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/thumbnail - Serves cache-only thumbnail images for authorized files; returns 404 while cache is not ready.
  • GET /api/files/folder-images - Returns images inside a directory (recursive) that already have a cached thumbnail; only thumbnailed images are included per user requirement.
  • 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/download-zip?dir=<absolute-path> - Authenticated. Streams the directory as a zip archive; caches the zip for up to 1 day in zip-cache/.
  • makeTempUploadPath(dir, originalName) - Builds a hidden per-upload staging filename in the target directory for multipart uploads.
  • unlinkIfExists(targetPath, cb) - Removes a file during upload cleanup while ignoring already-missing temp files.
  • promoteUploadedFile(tempPath, finalPath, cb) - Atomically renames a completed staged upload into place on the Linux server.
  • splitNameExt(name) - Splits a filename into stem/ext, preserving dotless names and hidden-file behavior.
  • pickNumberedPath(dir, requestedName) - Finds the first free name (n).ext path inside a directory.
  • removePathRecursive(targetPath) - Deletes existing file or directory destination to support overwrite moves.
  • POST /api/files/upload - Streams multipart uploads into hidden temp files, unpipes stream writes on abort/failure, cleans temp files, and only exposes final filenames after completion.
  • POST /api/files/move - Moves file/folder; supports conflict strategies: error (default), overwrite, or rename with optional targetName.
  • POST /api/files/video-stream - Creates a short-lived HLS session for a video and returns playlistUrl, durationSeconds, subtitleTracks, and subtitleSummary ({total, converted, skipped}).
  • POST /api/files/watch-progress - Records per-user watch status (partway >=10%, fully >=70%) for sidebar "Watched by" display.

server/routes/share.js

  • POST /api/share/create - Authenticated. Creates a 24-hour share token for a file or directory; returns {token, expiresAt}.
  • 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, and subtitleSummary ({total, converted, skipped}).
  • buildZip(dirPath, cacheKey) - Creates (or returns cached) zip in zip-cache/; prunes stale zips before building; exported for reuse in files.js.
  • pruneZipCache() - Deletes zip files in zip-cache/ older than 1 day; called automatically before each zip build.
  • ZIP_CACHE_DIR - Absolute path to the zip-cache/ directory (project root).

server/video-stream.js

  • createVideoStreamSession(sourcePath) - Probes the input duration, attempts WebVTT conversion for all subtitle streams (skipping only failed conversions), starts ffmpeg HLS transcoding, and resolves only when HLS assets are present (not subtitle files alone); returns durationSeconds, subtitleTracks, and subtitleSummary {total, converted, skipped}.
  • sendVideoStreamAsset(sessionId, assetPath, res) - Serves HLS playlists, segments, and extracted subtitle files from an active short-lived stream session.
  • STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
  • STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before 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 same Video.js playback behaviour as app previews: VOD UI enforcement, long forward buffer, local caption-style defaults/persistence, and subtitle/audio track restore/save by matching track names when available.
  • 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/index.html

  • Auth form - Login/setup form uses username plus mode-specific password autocomplete tokens so browser password managers behave correctly.

public/app.js

  • showApp() - Reveals app shell; keeps sidebar folded by default on mobile and shows folder overview sidebar on desktop.
  • showAuthOverlay(setupMode) - Displays the login/setup overlay and switches the password autocomplete token between current-password and new-password based on mode.
  • getOrCreateClientBindingId() - Creates/loads a persistent local browser binding id used in auth fingerprint derivation.
  • getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
  • saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
  • loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
  • api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
  • 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) - In-page confirm dialog; returns Promise<boolean>. Use instead of window.confirm().
  • showPrompt(title, message, defaultValue) - In-page text-input dialog; returns Promise<string|null>. Use instead of window.prompt().
  • showOverwrite(filename) - In-page overwrite-decision dialog for file conflicts; returns Promise<'yes'|'no'|'all'|'none'>.
  • splitNameExt(name) - Client-side filename splitter used for local conflict rename suggestions.
  • nextAvailableName(requestedName, existingNames) - Computes name (n).ext for upload/move rename options.
  • listDirNameSet(dir) - Fetches directory listing and returns a Set of existing names.
  • cloneFileWithName(file, newName) - Creates a renamed File object for non-overwrite uploads.
  • showFileConflictChoice(filename, renameTo, mode) - Dialog for single upload/move conflicts; returns overwrite/rename/cancel.
  • 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.
  • 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.
  • observeFolderIcon(iconEl) - Registers a folder icon element with IntersectionObserver for lazy loading.
  • loadOneFolderIcon(iconEl) - Fetches /api/files/folder-icon then the thumbnail blob and overlays it inside the folder SVG; no-op if no icon available.
  • applyFolderThumbnail(iconEl, srcUrl) - Injects an SVG <image> element clipped to the folder outline path into the folder's icon SVG.
  • openFolderIconPicker(item) - Opens the folder icon picker modal; shows cached-thumbnail images from the folder; allows selection, clearing, and cancellation.
  • 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.
  • 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 + caption style + subtitle/audio track names when present), applies default caption style presets when no per-user caption style exists, reports watch progress, and warns when subtitle streams exist but none are web-compatible.
  • 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.
  • 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) - Adds preview action buttons for Download and Share; Share opens the same modal flow as sidebar sharing.
  • closeExpandedTilePreview() - Collapses expanded tile preview back to original grid position and restores original icon markup.
  • 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.
  • moveWithConflictResolution(item, targetDir) - Attempts move and handles 409 conflicts by prompting overwrite/rename/cancel then retries.
  • rootPermissionLabel(root) - Resolves permission key for a root using originalName when available (alias-safe permission checks).
  • 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.
  • attachMobileLongPress(el, item) - Adds mobile long-press detection on file/folder tiles to open the item sidebar without desktop side effects.
  • openSidebar(item) - Renders item details/actions in sidebar; roots show alias + original name + usage stats, hide Move To/Delete, keep Rename.
  • 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.
  • 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.

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.

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.

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.
  • 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 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 default caption style per user when no saved style exists - Verifies requested caption defaults are loaded and persisted for first-use users.
  • video preview saves caption style settings per user on close - Verifies Video.js text-track settings persist per user after closing previews.

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.

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.
Source
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
7## server/thumbnail-cache.js
8- syncThumbnailCacheOnce() - Mirrors configured roots into public/thumbs and generates 99x99-max WebP thumbnails for image files; removes stale thumbnails and updates manifest hashes while preserving prior cache entries for temporarily unavailable roots (e.g. removable mounts).
9- startThumbnailCacheLoop() - Schedules cache sync runs 5 seconds after boot and 5 seconds after each run completes.
10- stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
11- getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
12- getThumbPathForSourceFile(sourceFile) - Maps an absolute source file path to its mirrored cache thumbnail path.
13- getThumbRelPathForSourceFile(sourceFile) - Returns public-relative thumbnail path used in manifest entries.
14- getImagesWithThumbnailsInDir(dirPath) - Returns [{filePath, thumbRelPath}] for all images inside dirPath (recursive) that have a cached thumbnail; sorted by filePath.
15- getFolderIconSourceFile(folderPath) - Returns the source image path for a folder's icon: explicit assignment first, then auto-first cached image, null if none.
16- setFolderIconAssignment(folderPath, imagePath) - Saves an explicit folder icon assignment to .folder-icons.json; pass null to clear (auto-detect used instead).
17
18## server/db.js
19- 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.
20- getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
21- closeDb() - Closes singleton DB handle to release file locks.
22
23## server/auth.js
24- createToken(username, req, fingerprint) - Creates JWT bound to IP/region/fingerprint and linked to a DB-backed session id.
25- requireAuth(req, res, next) - Verifies JWT + binding + session row + 1-hour idle timeout, updates last_seen_at, and attaches req.user.
26- requireAdmin(req, res, next) - Requires authenticated admin user.
27- revokeSession(sessionId) - Revokes a session row so future token use fails immediately.
28- getClientIp(req) - Normalizes request IP (including IPv4-mapped IPv6 loopback cases).
29- getRegion(ip) - Derives coarse region binding from geoip lookup or local fallback.
30- SESSION_IDLE_TIMEOUT_MS - Server-enforced idle timeout window (1 hour).
31
32## server/routes/auth.js
33- extractCredentials(body) - Accepts encrypted payloads and compatibility plaintext payloads for login/setup.
34- makeAuthResponse(token, clientPublicKey) - Returns encrypted token when client key exists, plaintext token otherwise.
35- POST /api/auth/setup - Creates first admin and issues token.
36- POST /api/auth/login - Authenticates user by case-insensitive username match and issues token with canonical stored username.
37- GET /api/auth/me - Returns current authenticated user profile.
38- POST /api/auth/logout - Revokes the active session.
39
40## server/routes/admin.js
41- POST /api/admin/users - Creates a new user and enforces case-insensitive username uniqueness.
42- normalizePermissions(permissions) - Normalizes permission maps and enforces that write access implies read access.
43
44## server/routes/files.js
45- GET /api/files/roots - Returns readable roots with display label (alias when configured), originalName, and path.
46- POST /api/files/root-alias - Sets a display-only alias for an exact configured root path (no filesystem rename).
47- GET /api/files/root-access - Returns users who can access an exact configured root and their access mode (R / R+W).
48- GET /api/files/thumbnail - Serves cache-only thumbnail images for authorized files; returns 404 while cache is not ready.
49- GET /api/files/folder-images - Returns images inside a directory (recursive) that already have a cached thumbnail; only thumbnailed images are included per user requirement.
50- 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.
51- POST /api/files/folder-icon - Sets or clears a folder's explicit icon assignment; imagePath must have a cached thumbnail; write access required.
52- 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/.
53- makeTempUploadPath(dir, originalName) - Builds a hidden per-upload staging filename in the target directory for multipart uploads.
54- unlinkIfExists(targetPath, cb) - Removes a file during upload cleanup while ignoring already-missing temp files.
55- promoteUploadedFile(tempPath, finalPath, cb) - Atomically renames a completed staged upload into place on the Linux server.
56- splitNameExt(name) - Splits a filename into stem/ext, preserving dotless names and hidden-file behavior.
57- pickNumberedPath(dir, requestedName) - Finds the first free `name (n).ext` path inside a directory.
58- removePathRecursive(targetPath) - Deletes existing file or directory destination to support overwrite moves.
59- POST /api/files/upload - Streams multipart uploads into hidden temp files, unpipes stream writes on abort/failure, cleans temp files, and only exposes final filenames after completion.
60- POST /api/files/move - Moves file/folder; supports conflict strategies: `error` (default), `overwrite`, or `rename` with optional `targetName`.
61- POST /api/files/video-stream - Creates a short-lived HLS session for a video and returns playlistUrl, durationSeconds, subtitleTracks, and subtitleSummary ({total, converted, skipped}).
62- POST /api/files/watch-progress - Records per-user watch status (`partway` >=10%, `fully` >=70%) for sidebar "Watched by" display.
63
64## server/routes/share.js
65- POST /api/share/create - Authenticated. Creates a 24-hour share token for a file or directory; returns {token, expiresAt}.
66- GET /api/share/info/:token - Public. Returns {name, isDir, expiresAt} for a valid non-expired token; 410 when expired, 404 when unknown.
67- GET /api/share/preview/:token - Public. Streams file content inline for preview (files only, max 50 MB); 400 for directories, 410 expired.
68- GET /api/share/download/:token - Public. Downloads the file or a zip of the directory for a valid token; 410 expired.
69- GET /api/share/video-stream/:token - Public. Creates a short-lived HLS session for a shared video and returns playlistUrl, durationSeconds, subtitleTracks, and subtitleSummary ({total, converted, skipped}).
70- buildZip(dirPath, cacheKey) - Creates (or returns cached) zip in zip-cache/; prunes stale zips before building; exported for reuse in files.js.
71- pruneZipCache() - Deletes zip files in zip-cache/ older than 1 day; called automatically before each zip build.
72- ZIP_CACHE_DIR - Absolute path to the zip-cache/ directory (project root).
73
74## server/video-stream.js
75- createVideoStreamSession(sourcePath) - Probes the input duration, attempts WebVTT conversion for all subtitle streams (skipping only failed conversions), starts ffmpeg HLS transcoding, and resolves only when HLS assets are present (not subtitle files alone); returns durationSeconds, subtitleTracks, and subtitleSummary {total, converted, skipped}.
76- sendVideoStreamAsset(sessionId, assetPath, res) - Serves HLS playlists, segments, and extracted subtitle files from an active short-lived stream session.
77- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
78- STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
79
80## server/db.js
81- initDb() - Initializes SQLite schema for users, file metadata, auth_sessions, and share_tokens (expires_at index).
82- getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
83- closeDb() - Closes singleton DB handle to release file locks.
84
85## public/share.html
86- Standalone public share page served at /share/:token; no auth required.
87- Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
88- tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
89- Share video preview - Uses the same Video.js playback behaviour as app previews: VOD UI enforcement, long forward buffer, local caption-style defaults/persistence, and subtitle/audio track restore/save by matching track names when available.
90- Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
91- Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.
92
93## public/index.html
94- Auth form - Login/setup form uses username plus mode-specific password autocomplete tokens so browser password managers behave correctly.
95
96## public/app.js
97- showApp() - Reveals app shell; keeps sidebar folded by default on mobile and shows folder overview sidebar on desktop.
98- showAuthOverlay(setupMode) - Displays the login/setup overlay and switches the password autocomplete token between current-password and new-password based on mode.
99- getOrCreateClientBindingId() - Creates/loads a persistent local browser binding id used in auth fingerprint derivation.
100- getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
101- saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
102- loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
103- api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
104- performLogout() - Explicit logout path that revokes server session and clears local session state.
105- initAuth() - Restores prior session when valid and auto-logins without credential prompt.
106- showConfirm(title, message) - In-page confirm dialog; returns Promise<boolean>. Use instead of window.confirm().
107- showPrompt(title, message, defaultValue) - In-page text-input dialog; returns Promise<string|null>. Use instead of window.prompt().
108- showOverwrite(filename) - In-page overwrite-decision dialog for file conflicts; returns Promise<'yes'|'no'|'all'|'none'>.
109- splitNameExt(name) - Client-side filename splitter used for local conflict rename suggestions.
110- nextAvailableName(requestedName, existingNames) - Computes `name (n).ext` for upload/move rename options.
111- listDirNameSet(dir) - Fetches directory listing and returns a Set of existing names.
112- cloneFileWithName(file, newName) - Creates a renamed File object for non-overwrite uploads.
113- showFileConflictChoice(filename, renameTo, mode) - Dialog for single upload/move conflicts; returns overwrite/rename/cancel.
114- 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.
115- loadThumbnails() - Registers visible file icons for lazy thumbnail loading (both file thumbnails and folder icons); retries missing cache thumbnails during incremental refresh.
116- 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.
117- observeFolderIcon(iconEl) - Registers a folder icon element with IntersectionObserver for lazy loading.
118- loadOneFolderIcon(iconEl) - Fetches /api/files/folder-icon then the thumbnail blob and overlays it inside the folder SVG; no-op if no icon available.
119- applyFolderThumbnail(iconEl, srcUrl) - Injects an SVG <image> element clipped to the folder outline path into the folder's icon SVG.
120- openFolderIconPicker(item) - Opens the folder icon picker modal; shows cached-thumbnail images from the folder; allows selection, clearing, and cancellation.
121- refreshAfterIconChange(item) - Resets and reloads the folder icon in both the grid tile and sidebar after set/clear operations.
122- disconnectFolderIconObserver() - Disconnects and clears the folder icon IntersectionObserver on grid rebuild.
123- getThumbnailKind(name) - Classifies files into image/text/badge thumbnail strategies.
124- observeThumbnailIcon(iconEl) - Defers thumbnail fetch work until file icons are near/in the viewport.
125- disconnectThumbnailObserver() - Clears active IntersectionObserver when the grid is rebuilt.
126- setThumbnailPending(iconEl, pending) - Toggles per-icon pending spinner state while a cached image thumbnail is not ready yet.
127- buildThumbnailSource(item, blob, kind) - Produces thumbnail image source (data/blob URL) for icon injection.
128- 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 + caption style + subtitle/audio track names when present), applies default caption style presets when no per-user caption style exists, reports watch progress, and warns when subtitle streams exist but none are web-compatible.
129- closePreview(opts) - Closes expanded previews; video previews ignore backdrop close and require explicit close action.
130
131## tests/thumbnail-cache.test.js
132- thumbnail cache worker / creates cached thumbnail with dimensions smaller than 100px - Verifies cached image generation and manifest write.
133- thumbnail cache worker / removes cached thumbnail when source file is deleted - Verifies stale thumbnail cleanup behavior.
134- afterEach() cleanup - Removes temp roots with `fs.rmSync(...maxRetries...)` to tolerate transient Windows file locks.
135- detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension.
136- prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering.
137- highlightCode(raw, lang) - Escapes and syntax-highlights preview text into HTML spans.
138- fileAccentColor(name) - Returns canonical file-type accent color used by icon strokes and preview sheet outline.
139- openFolderSidebar() - Persistent sidebar fallback view that shows current folder/root overview when no item is selected.
140- closeSidebar() - Clears selection; hides the panel entirely on mobile and restores folder overview sidebar on desktop.
141- isMobileViewport() - Central media-query helper for mobile-only sidebar/interaction behavior.
142- hideSidebarPanel() - Hides sidebar panel and removes sidebar-open layout class from the app shell.
143- renderBreadcrumb() - Builds clickable breadcrumb path and marks each folder segment as a drag-drop move target via .crumb-drop-target and data-path.
144- fetchFileBlob(item) - Downloads a file as Blob with auth headers for preview/download flows.
145- 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.
146- downloadOrView(item, sourceSvgEl) - Opens in-place expanded tile preview from a file icon; shows error toast if no source tile is found.
147- renderPreviewBody(item, blob, objectUrl, targetEl) - Renders preview content (image/video/audio/pdf/text) or unsupported message into a target container.
148- animateRect(el, fromRect, toRect, opts) - Helper that animates element rectangle (left/top/width/height) for expand/collapse transitions.
149- openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents the real file tile to body, expands it to viewport preview, injects close/download controls.
150- 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.
151- openExpandedTilePreview(item, tileEl, sourceSvgEl, loadPreviewContent) - Adds preview action buttons for Download and Share; Share opens the same modal flow as sidebar sharing.
152- closeExpandedTilePreview() - Collapses expanded tile preview back to original grid position and restores original icon markup.
153- closePreview() - Closes either expanded-tile preview or overlay preview, then revokes active preview object URL.
154- closePreview() - Closes expanded-tile preview and revokes active preview object URL.
155- openMovePicker(item) - Opens Move To selector modal with expandable folder tree across all writable roots and executes /api/files/move.
156- moveWithConflictResolution(item, targetDir) - Attempts move and handles 409 conflicts by prompting overwrite/rename/cancel then retries.
157- rootPermissionLabel(root) - Resolves permission key for a root using originalName when available (alias-safe permission checks).
158- ensureMoveModal() - Lazily creates and wires Move To modal UI (tree, selection state, confirm/cancel handlers).
159- createMoveNode(folderPath, label) - Builds an expandable/selectable folder node for the Move To tree.
160- loadMoveChildren(containerEl, dirPath) - Lazy-loads subfolders for a tree node via /api/files/list.
161- isInlinePreviewableBlob(blob, name) - Determines if a blob can be previewed inline by MIME/extension.
162- 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.
163- attachMobileLongPress(el, item) - Adds mobile long-press detection on file/folder tiles to open the item sidebar without desktop side effects.
164- openSidebar(item) - Renders item details/actions in sidebar; roots show alias + original name + usage stats, hide Move To/Delete, keep Rename.
165- fetchRootAccessList(rootPath) - Fetches root access users from the server for a specific configured root.
166- formatRootAccessList(users) - Formats root access entries as "username mode" values for sidebar rendering.
167- 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.
168- openFolderSidebar() - Shows current folder details when nothing is selected; when at root base-level it also shows root access list.
169- openRenameModal(item) - Renames files/folders; for roots this writes display alias via /api/files/root-alias and reloads roots.
170- uploadFiles(fileList) - Uploads files one-by-one with per-file conflict prompt (overwrite/rename/cancel) when names already exist.
171- openUserModal(user, paths) - Admin user editor; enforces UI permission rule that Write is disabled/unchecked while Read is unchecked.
172
173## public/drag-move.js
174- 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.
175- makeDraggable(el, item) - Touch drag now requires a short hold before movement, uses pointer capture, and keeps drag responsive on mobile.
176- (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.
177- (internal) _moveDrag(e) - Moves the real dragged item, hit-tests folder tiles, breadcrumb segments, and parent-folder target, toggles target highlight state.
178- (internal) _endDrag() - On valid target: runs drop animation, calls moveWithConflictResolution() for overwrite/rename/cancel conflicts, then refreshes dir. Otherwise snap-back.
179- (internal) _cleanupDrag(reinsert) - Restores tile styles; reinserts into grid on failure/abort or removes before refresh on success, hides drag helper targets.
180
181## public/drag-move.css
182- .file-item.dragging - Lifted style for real dragged tile.
183- .file-item.drop-target - Glows folder icon when drag hovers over it.
184- .drag-parent-target - Temporary top-left "move to parent" drop target shown while dragging in nested folders.
185- .crumb-drop-target.active - Highlight style for breadcrumb drop destinations during drag.
186- @keyframes drag-rise-spin-fall - Real tile rises, spins, falls/scales into folder on drop.
187- @keyframes folder-bounce - Target folder bounces down then back on accept.
188- .preview-backdrop/.file-item--preview/.preview-expand-* - In-place expanded tile preview styling (no separate overlay window), including preserved icon-outline layer.
189- .preview-expand-share - Secondary action button positioned next to .preview-expand-download in expanded file preview.
190- .move-modal/.move-tree/.move-node* - Move To tree picker styles with expandable/collapsible folder hierarchy.
191
192## tests/auth.routes.test.js
193- session lifecycle / POST /api/auth/logout revokes active session - Verifies explicit logout invalidates token immediately.
194- session lifecycle / session expires after 1 hour of inactivity - Verifies server-side idle timeout enforcement.
195
196## tests/page.load.test.js
197- bootClient() - Boots the app in jsdom and waits until app shell is visible or timeout before assertions.
198- waitFor(dom, predicate, timeoutMs) - Poll helper used by interaction tests to wait for rendered tiles.
199- login overlay uses username and current-password autocomplete tokens - Verifies normal sign-in mode exposes browser-friendly login autocomplete attributes.
200- first-run setup uses new-password autocomplete token - Verifies setup mode switches the password field to the browser-friendly new-password token.
201- 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.
202- 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.
203- video preview does not close on backdrop click and closes via X button - Verifies video previews require explicit close via X.
204- video preview restores per-user saved volume preference - Verifies per-user saved video volume is applied on preview open.
205- video preview restores saved subtitle/audio track names when available - Verifies per-user subtitle/audio selections are reapplied by matching track names.
206- video preview keeps default tracks when saved names are not present - Verifies subtitle/audio defaults remain unchanged when saved names are missing.
207- video preview saves subtitle/audio track names per user when selection changes - Verifies subtitle/audio selections are persisted into per-user video preferences.
208- video preview applies default caption style per user when no saved style exists - Verifies requested caption defaults are loaded and persisted for first-use users.
209- video preview saves caption style settings per user on close - Verifies Video.js text-track settings persist per user after closing previews.
210
211## tests/video-stream.test.js
212- createVideoStreamSession resolves once ffmpeg starts writing stream assets - Verifies session creation no longer waits for the final master playlist before preview can begin.
213- createVideoStreamSession configures flat segment filenames that match playlist URLs - Verifies ffmpeg segment output paths match the segment URLs emitted in the generated HLS playlists.
214- createVideoStreamSession does not become ready from subtitle files alone - Verifies stream readiness is tied to HLS output instead of extracted subtitle files.
215- createVideoStreamSession keeps playback available when subtitle conversion fails - Verifies subtitle conversion failures are skipped without breaking stream playback.
216
217## tests/share.page.load.test.js
218- applies default caption settings for share-page video playback - Verifies requested caption defaults are applied and persisted on share-page video preview.
219- 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.
220
221## tests/files.routes.test.js
222- POST /api/files/watch-progress stores per-user watched status by thresholds - Verifies watch-status persistence and no downgrade from fully to partway.