# 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. - 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. ## server/db.js - initDb() - Initializes SQLite schema for users, file metadata, and auth_sessions (idle timeout/revocation support). - 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. ## 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/thumbnail - Serves cache-only thumbnail images for authorized files; returns 404 while cache is not ready. ## public/app.js - showApp() - Reveals app shell; keeps sidebar folded by default on mobile and shows folder overview sidebar on desktop. - 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. Use instead of window.confirm(). - 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'>. - loadThumbnails() - Registers visible file icons for lazy thumbnail loading; 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. - 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. - buildThumbnailSource(item, blob, kind) - Produces thumbnail image source (data/blob URL) for icon injection. ## 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. - 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. - 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. - 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. - openRenameModal(item) - Renames files/folders; for roots this writes display alias via /api/files/root-alias and reloads roots. ## 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. - (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 on real tile then calls POST /api/files/move, 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. - .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.