From 90b6762869eef1f919f93c75763ca058733225c4 Mon Sep 17 00:00:00 2001 From: Reece Date: Tue, 1 Sep 2026 15:35:40 +0100 Subject: [PATCH] docs(folders): trim the comments this branch adds The same three lines explaining which folder kinds can go offline sat above both the grid card and the list row; one copy carries the reasoning and the other points at it. The rest is the module docs on the new stores, saying the same things with less around them. --- .../core/components/filesPage/FileGrid.tsx | 9 +++---- .../src/core/services/localFolderContents.ts | 11 ++++----- .../src/core/services/localFolderStorage.ts | 24 ++++++++----------- .../editor/src/core/services/mountWrites.ts | 13 +++++----- .../src/core/services/virtualFolderStorage.ts | 19 +++++++-------- .../desktop/services/localFolderContents.ts | 14 +++++------ 6 files changed, 37 insertions(+), 53 deletions(-) diff --git a/frontend/editor/src/core/components/filesPage/FileGrid.tsx b/frontend/editor/src/core/components/filesPage/FileGrid.tsx index 29a3a97871..5da319c629 100644 --- a/frontend/editor/src/core/components/filesPage/FileGrid.tsx +++ b/frontend/editor/src/core/components/filesPage/FileGrid.tsx @@ -534,9 +534,8 @@ function FolderCard({ }: FolderCardProps) { const { t } = useTranslation(); const { serverReachable, setError } = useFolders(); - // Only server folders go offline: a virtual folder is browser-owned and a - // local one takes its name, look, and lifetime from its directory on disk — - // so its edit items are hidden rather than disabled-with-a-wrong-excuse. + // Only a server folder can go offline: the other kinds take their name, look and + // lifetime from elsewhere, so their edit items are hidden rather than disabled. const kind = folderKind(folder); const originBadge = useFolderOriginBadge(folder); const editsDisabled = kind === "server" && !serverReachable; @@ -1285,9 +1284,7 @@ function FolderRow({ }: FolderRowProps) { const { t } = useTranslation(); const { serverReachable, setError } = useFolders(); - // Only server folders go offline: a virtual folder is browser-owned and a - // local one takes its name, look, and lifetime from its directory on disk — - // so its edit items are hidden rather than disabled-with-a-wrong-excuse. + // Kinds gate the edit items, as in FolderCard. const kind = folderKind(folder); const originBadge = useFolderOriginBadge(folder); const editsDisabled = kind === "server" && !serverReachable; diff --git a/frontend/editor/src/core/services/localFolderContents.ts b/frontend/editor/src/core/services/localFolderContents.ts index 25c42b7e22..0522fe6962 100644 --- a/frontend/editor/src/core/services/localFolderContents.ts +++ b/frontend/editor/src/core/services/localFolderContents.ts @@ -1,11 +1,8 @@ /** - * Reading a mounted local folder's contents straight off the disk. - * - * A local folder is read-through: the directory is the source of truth and - * nothing is ingested to show it — the listing IS the directory, taken fresh - * on every look. Only an environment that can see the filesystem can do - * this, so core reports the capability absent and the desktop build shadows - * this module with the Tauri filesystem plugin. + * Reading a mounted folder's contents straight off the disk. Read-through: the + * listing is the directory, taken fresh each look, with nothing ingested to show it. + * Only an environment that can see the filesystem can do this, so core reports the + * capability absent and the desktop build shadows this module. */ /** One file inside a mounted directory, as the file manager lists it. */ diff --git a/frontend/editor/src/core/services/localFolderStorage.ts b/frontend/editor/src/core/services/localFolderStorage.ts index d731696c51..a119c70b86 100644 --- a/frontend/editor/src/core/services/localFolderStorage.ts +++ b/frontend/editor/src/core/services/localFolderStorage.ts @@ -1,13 +1,11 @@ /** - * Local Folder Storage - the record of directories mounted into the file - * manager (kind "local"). + * The record of directories mounted into the file manager (kind "local"): a pointer + * at a directory, nothing more. The directory owns its name, contents and lifetime, + * so the record holds only where it is and how to show it, and removing a mount + * removes the record and nothing else. * - * A local folder is a pointer at a directory on the machine; the directory - * itself is the source of truth for everything else — name, contents, - * lifetime — so the record carries only where it is and how to show it. - * Mounts are flat by construction: they have no parent, and a directory's - * subdirectories are the filesystem's business, not a folder hierarchy for - * this store to model. Removing a mount removes the record and nothing else. + * Mounts are flat by construction - no parent, and a directory's subdirectories are + * the filesystem's business rather than a hierarchy for this store to model. */ import { @@ -73,12 +71,10 @@ class LocalFolderStorageService { } /** - * Mount a directory. Mounting the same directory twice hands back the - * existing record — two rows for one directory would be two names for one - * truth, and removing one would lie about the other. Nesting is fine: a - * mount lists only its own files, so a subdirectory needs its own mount to - * be reachable at all — the same way a file manager pins both a folder and - * one of its children. + * Mount a directory, or hand back the existing record for one already mounted: + * two rows for one directory would be two names for one truth. Nesting is fine - + * a mount lists only its own files, so a subdirectory needs its own mount to be + * reachable. */ async mountDirectory(directory: string, name: string): Promise { const key = directoryKey(directory); diff --git a/frontend/editor/src/core/services/mountWrites.ts b/frontend/editor/src/core/services/mountWrites.ts index 9c7a975d2b..300d9c77bd 100644 --- a/frontend/editor/src/core/services/mountWrites.ts +++ b/frontend/editor/src/core/services/mountWrites.ts @@ -7,13 +7,12 @@ export interface MountWriteItem { } /** - * Write a batch of named blobs into a mounted directory — the one engine - * behind "upload while standing in a mount" and "move library files into a - * mount", so failure accounting and collision behavior can't drift between - * them. Failures are counted, never thrown: the caller owes the user one - * banner for the batch, not an abort at the first bad file. `written[i]` - * tells the caller which items verifiably landed (and are safe to retire - * from app storage). + * Write named blobs into a mounted directory - the one engine behind both uploading + * into a mount and moving library files into one, so failure accounting and + * collision behaviour cannot drift apart. Failures are counted, never thrown: the + * caller owes one banner for the batch rather than an abort at the first bad file. + * `written[i]` says which items verifiably landed and are safe to retire from app + * storage. */ export async function writeIntoMount( directory: string | undefined, diff --git a/frontend/editor/src/core/services/virtualFolderStorage.ts b/frontend/editor/src/core/services/virtualFolderStorage.ts index 011319e729..994746c6ac 100644 --- a/frontend/editor/src/core/services/virtualFolderStorage.ts +++ b/frontend/editor/src/core/services/virtualFolderStorage.ts @@ -1,16 +1,13 @@ /** - * Virtual Folder Storage - the system of record for kind "virtual" folders. + * The system of record for kind "virtual" folders - rows this store owns rather + * than caches. {@link folderStorage} is wiped and rewritten on every sync because + * the server is authoritative there; a virtual folder exists only in this browser, + * with nothing to restore it from. They organise files where there is no login, no + * server storage, or no network. * - * Unlike {@link folderStorage} (a passive cache of the server's folder - * hierarchy, wiped and rewritten on every sync), this store OWNS its rows: - * a virtual folder exists only in this browser's IndexedDB and has no server - * copy to be restored from. That is the point — virtual folders organise - * files on installs with no login, no server storage, or no network. - * - * Because there is no server to be authoritative, the invariants the server - * enforces for its folders are enforced here instead: no reparenting a folder - * under its own subtree (cycles), and a bounded chain depth. Limits mirror - * FolderService so a hierarchy never behaves differently for being virtual. + * No server to enforce them means the invariants live here: no reparenting a folder + * under its own subtree, and a bounded depth, with the limits mirroring + * FolderService so a hierarchy does not behave differently for being virtual. */ import { diff --git a/frontend/editor/src/desktop/services/localFolderContents.ts b/frontend/editor/src/desktop/services/localFolderContents.ts index d5de7821ad..b3db319cf1 100644 --- a/frontend/editor/src/desktop/services/localFolderContents.ts +++ b/frontend/editor/src/desktop/services/localFolderContents.ts @@ -24,15 +24,13 @@ import type { export type { DiskDirEntry, DiskFileEntry, DiskListing }; /** - * Containment: file reads and writes here run under a filesystem-wide Tauri - * capability, but this module's contract is mounted directories only — - * refuse any path outside one. The capability layer is the real trust - * boundary; this keeps the contract explicit and a bad path inert. + * Containment: these reads and writes run under a filesystem-wide Tauri capability, + * but the contract here is mounted directories only, so any path outside one is + * refused. The capability layer is the real trust boundary; this keeps a bad path + * inert. * - * The mount store is read fresh on every call: it holds a handful of rows, - * which is nothing next to the file bytes about to cross the IPC bridge, - * and the heavy callers (thumbnails) are already concurrency-throttled. - * Fresh reads mean a removed mount is refused immediately. + * The mount store is read fresh every call - a handful of rows against the file + * bytes about to cross the IPC bridge - so a removed mount is refused at once. */ async function isWithinMount(path: string): Promise { const pathKey = directoryKey(path);