BlueGit

timfa filemanager

Files

filemanager / .github / technical-reference.md

technical-reference.md

pip
timfa Tim Falken · pushed by timfa · 6 months ago
aefbcaaa History
technical-reference.md 15.6 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, 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.
  • 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.
  • 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/move - Moves file/folder; supports conflict strategies: error (default), overwrite, or rename with optional targetName.

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<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.
  • 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.

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.
  • 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.
  • .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.
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, and auth_sessions (idle timeout/revocation support).
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- splitNameExt(name) - Splits a filename into stem/ext, preserving dotless names and hidden-file behavior.
53- pickNumberedPath(dir, requestedName) - Finds the first free `name (n).ext` path inside a directory.
54- removePathRecursive(targetPath) - Deletes existing file or directory destination to support overwrite moves.
55- POST /api/files/move - Moves file/folder; supports conflict strategies: `error` (default), `overwrite`, or `rename` with optional `targetName`.
56
57## public/app.js
58- showApp() - Reveals app shell; keeps sidebar folded by default on mobile and shows folder overview sidebar on desktop.
59- getOrCreateClientBindingId() - Creates/loads a persistent local browser binding id used in auth fingerprint derivation.
60- getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
61- saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
62- loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
63- api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
64- performLogout() - Explicit logout path that revokes server session and clears local session state.
65- initAuth() - Restores prior session when valid and auto-logins without credential prompt.
66- showConfirm(title, message) - In-page confirm dialog; returns Promise<boolean>. Use instead of window.confirm().
67- showPrompt(title, message, defaultValue) - In-page text-input dialog; returns Promise<string|null>. Use instead of window.prompt().
68- showOverwrite(filename) - In-page overwrite-decision dialog for file conflicts; returns Promise<'yes'|'no'|'all'|'none'>.
69- splitNameExt(name) - Client-side filename splitter used for local conflict rename suggestions.
70- nextAvailableName(requestedName, existingNames) - Computes `name (n).ext` for upload/move rename options.
71- listDirNameSet(dir) - Fetches directory listing and returns a Set of existing names.
72- cloneFileWithName(file, newName) - Creates a renamed File object for non-overwrite uploads.
73- showFileConflictChoice(filename, renameTo, mode) - Dialog for single upload/move conflicts; returns overwrite/rename/cancel.
74- loadThumbnails() - Registers visible file icons for lazy thumbnail loading (both file thumbnails and folder icons); retries missing cache thumbnails during incremental refresh.
75- 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.
76- observeFolderIcon(iconEl) - Registers a folder icon element with IntersectionObserver for lazy loading.
77- loadOneFolderIcon(iconEl) - Fetches /api/files/folder-icon then the thumbnail blob and overlays it inside the folder SVG; no-op if no icon available.
78- applyFolderThumbnail(iconEl, srcUrl) - Injects an SVG <image> element clipped to the folder outline path into the folder's icon SVG.
79- openFolderIconPicker(item) - Opens the folder icon picker modal; shows cached-thumbnail images from the folder; allows selection, clearing, and cancellation.
80- refreshAfterIconChange(item) - Resets and reloads the folder icon in both the grid tile and sidebar after set/clear operations.
81- disconnectFolderIconObserver() - Disconnects and clears the folder icon IntersectionObserver on grid rebuild.
82- getThumbnailKind(name) - Classifies files into image/text/badge thumbnail strategies.
83- observeThumbnailIcon(iconEl) - Defers thumbnail fetch work until file icons are near/in the viewport.
84- disconnectThumbnailObserver() - Clears active IntersectionObserver when the grid is rebuilt.
85- setThumbnailPending(iconEl, pending) - Toggles per-icon pending spinner state while a cached image thumbnail is not ready yet.
86- buildThumbnailSource(item, blob, kind) - Produces thumbnail image source (data/blob URL) for icon injection.
87
88## tests/thumbnail-cache.test.js
89- thumbnail cache worker / creates cached thumbnail with dimensions smaller than 100px - Verifies cached image generation and manifest write.
90- thumbnail cache worker / removes cached thumbnail when source file is deleted - Verifies stale thumbnail cleanup behavior.
91- afterEach() cleanup - Removes temp roots with `fs.rmSync(...maxRetries...)` to tolerate transient Windows file locks.
92- detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension.
93- prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering.
94- highlightCode(raw, lang) - Escapes and syntax-highlights preview text into HTML spans.
95- fileAccentColor(name) - Returns canonical file-type accent color used by icon strokes and preview sheet outline.
96- openFolderSidebar() - Persistent sidebar fallback view that shows current folder/root overview when no item is selected.
97- closeSidebar() - Clears selection; hides the panel entirely on mobile and restores folder overview sidebar on desktop.
98- isMobileViewport() - Central media-query helper for mobile-only sidebar/interaction behavior.
99- hideSidebarPanel() - Hides sidebar panel and removes sidebar-open layout class from the app shell.
100- renderBreadcrumb() - Builds clickable breadcrumb path and marks each folder segment as a drag-drop move target via .crumb-drop-target and data-path.
101- fetchFileBlob(item) - Downloads a file as Blob with auth headers for preview/download flows.
102- 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.
103- downloadOrView(item, sourceSvgEl) - Opens in-place expanded tile preview from a file icon; shows error toast if no source tile is found.
104- renderPreviewBody(item, blob, objectUrl, targetEl) - Renders preview content (image/video/audio/pdf/text) or unsupported message into a target container.
105- animateRect(el, fromRect, toRect, opts) - Helper that animates element rectangle (left/top/width/height) for expand/collapse transitions.
106- openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents the real file tile to body, expands it to viewport preview, injects close/download controls.
107- 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.
108- closeExpandedTilePreview() - Collapses expanded tile preview back to original grid position and restores original icon markup.
109- closePreview() - Closes either expanded-tile preview or overlay preview, then revokes active preview object URL.
110- closePreview() - Closes expanded-tile preview and revokes active preview object URL.
111- openMovePicker(item) - Opens Move To selector modal with expandable folder tree across all writable roots and executes /api/files/move.
112- moveWithConflictResolution(item, targetDir) - Attempts move and handles 409 conflicts by prompting overwrite/rename/cancel then retries.
113- rootPermissionLabel(root) - Resolves permission key for a root using originalName when available (alias-safe permission checks).
114- ensureMoveModal() - Lazily creates and wires Move To modal UI (tree, selection state, confirm/cancel handlers).
115- createMoveNode(folderPath, label) - Builds an expandable/selectable folder node for the Move To tree.
116- loadMoveChildren(containerEl, dirPath) - Lazy-loads subfolders for a tree node via /api/files/list.
117- isInlinePreviewableBlob(blob, name) - Determines if a blob can be previewed inline by MIME/extension.
118- 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.
119- attachMobileLongPress(el, item) - Adds mobile long-press detection on file/folder tiles to open the item sidebar without desktop side effects.
120- openSidebar(item) - Renders item details/actions in sidebar; roots show alias + original name + usage stats, hide Move To/Delete, keep Rename.
121- fetchRootAccessList(rootPath) - Fetches root access users from the server for a specific configured root.
122- formatRootAccessList(users) - Formats root access entries as "username mode" values for sidebar rendering.
123- 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.
124- openFolderSidebar() - Shows current folder details when nothing is selected; when at root base-level it also shows root access list.
125- openRenameModal(item) - Renames files/folders; for roots this writes display alias via /api/files/root-alias and reloads roots.
126- uploadFiles(fileList) - Uploads files one-by-one with per-file conflict prompt (overwrite/rename/cancel) when names already exist.
127- openUserModal(user, paths) - Admin user editor; enforces UI permission rule that Write is disabled/unchecked while Read is unchecked.
128
129## public/drag-move.js
130- 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.
131- makeDraggable(el, item) - Touch drag now requires a short hold before movement, uses pointer capture, and keeps drag responsive on mobile.
132- (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.
133- (internal) _moveDrag(e) - Moves the real dragged item, hit-tests folder tiles, breadcrumb segments, and parent-folder target, toggles target highlight state.
134- (internal) _endDrag() - On valid target: runs drop animation, calls moveWithConflictResolution() for overwrite/rename/cancel conflicts, then refreshes dir. Otherwise snap-back.
135- (internal) _cleanupDrag(reinsert) - Restores tile styles; reinserts into grid on failure/abort or removes before refresh on success, hides drag helper targets.
136
137## public/drag-move.css
138- .file-item.dragging - Lifted style for real dragged tile.
139- .file-item.drop-target - Glows folder icon when drag hovers over it.
140- .drag-parent-target - Temporary top-left "move to parent" drop target shown while dragging in nested folders.
141- .crumb-drop-target.active - Highlight style for breadcrumb drop destinations during drag.
142- @keyframes drag-rise-spin-fall - Real tile rises, spins, falls/scales into folder on drop.
143- @keyframes folder-bounce - Target folder bounces down then back on accept.
144- .preview-backdrop/.file-item--preview/.preview-expand-* - In-place expanded tile preview styling (no separate overlay window), including preserved icon-outline layer.
145- .move-modal/.move-tree/.move-node* - Move To tree picker styles with expandable/collapsible folder hierarchy.
146
147## tests/auth.routes.test.js
148- session lifecycle / POST /api/auth/logout revokes active session - Verifies explicit logout invalidates token immediately.
149- session lifecycle / session expires after 1 hour of inactivity - Verifies server-side idle timeout enforcement.
150
151## tests/page.load.test.js
152- bootClient() - Boots the app in jsdom and waits until app shell is visible or timeout before assertions.
153- waitFor(dom, predicate, timeoutMs) - Poll helper used by interaction tests to wait for rendered tiles.