Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Extract file-listing lifecycle from FileTree (#3181)

Dimitri POSTOLOV0452606a868c
diff --git a/.changeset/ninety-beers-find.md b/.changeset/ninety-beers-find.md
new file mode 100644
index 000000000..e65729ef0
--- /dev/null
+++ b/.changeset/ninety-beers-find.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge-app": patch
+---
+
+Refactor the Files sidebar's listing lifecycle into a dedicated hook, preserving progressive loading, reconnect retries, visibility refreshes, and lazy-folder behavior while making rejected folder requests recoverable.
diff --git a/packages/app/src/components/FileTree.tsx b/packages/app/src/components/FileTree.tsx
index 87f6d0d7a..416073891 100644
--- a/packages/app/src/components/FileTree.tsx
+++ b/packages/app/src/components/FileTree.tsx
@@ -2,7 +2,6 @@ import {
CreateFolderSuccessSchema,
CreatePageSuccessSchema,
DeletePathSuccessSchema,
- DocumentListSuccessSchema,
DuplicatePathSuccessSchema,
type HandoffOutcome,
type HandoffTarget,
@@ -153,12 +152,10 @@ import {
classifyEmptyTree,
type DocumentEntry,
type FileEntry,
- filterVisibleEntries,
hasOkPathSegment,
isAssetEntry,
isDocumentEntry,
isFolderEntry,
- toFileEntries,
} from '@/components/file-tree-utils';
import { NewItemDialog } from '@/components/NewItemDialog';
import {
@@ -206,7 +203,7 @@ import {
hashFromFolderPath,
pushHashWithoutNavigation,
} from '@/lib/doc-hash';
-import { emitDocumentsChanged, subscribeToDocumentsChanged } from '@/lib/documents-events';
+import { emitDocumentsChanged } from '@/lib/documents-events';
import {
subscribeToFileTreeMenuActionDelete,
subscribeToFileTreeMenuActionDuplicate,
@@ -215,8 +212,6 @@ import {
import { importTemplate } from '@/lib/folder-config-api';
import { isOverlayLayerOpen } from '@/lib/overlay-layers';
import { parseServerResponse, parseSuccessOrWarn } from '@/lib/parse-server-response';
-import { createRefreshScheduler } from '@/lib/refresh-scheduler';
-import { getRelaunchInFlightSnapshot, useRelaunchInFlight } from '@/lib/relaunch-store';
import { scheduleClipboardWrite } from '@/lib/share/clipboard-adapter';
import {
buildDocShareInput,
@@ -224,17 +219,10 @@ import {
runShareAction,
type ShareTargetInput,
} from '@/lib/share/run-share-action';
-import {
- consumeShowAllStream,
- isNdjsonResponse,
- SHOW_ALL_NDJSON_ACCEPT,
- ShowAllStreamError,
-} from '@/lib/show-all-stream';
import { OK_SIDEBAR_DRAG_MIME, serializeSidebarDragPayload } from '@/lib/sidebar-drag';
import { cn } from '@/lib/utils';
import { getValidationSnapshot, subscribeToValidationStore } from '@/lib/validation-store';
import { joinWorkspacePath } from '@/lib/workspace-paths';
-import { mergeRootEntriesAdditive, spliceLazyFolderChildren } from './file-tree-merge';
import { OpenInAgentContextSubmenu } from './handoff/OpenInAgentContextSubmenu';
import {
buildFolderHandoffInput,
@@ -245,6 +233,7 @@ import {
import { useInstalledAgents } from './handoff/useInstalledAgents';
import { cancelHoverPrewarm, scheduleHoverPrewarm } from './sidebar-hover-prewarm';
import { useSidebar } from './ui/sidebar';
+import { useFileTreeListing } from './use-file-tree-listing';
function focusEditorAfterRename(docName: string): void {
window.requestAnimationFrame(() => {
@@ -344,12 +333,6 @@ const FILE_TREE_EXTERNAL_FILE_DROP_TARGET_ATTR = 'data-ok-external-file-drop-tar
const FILE_TREE_EXTERNAL_FILE_DROP_ROOT_ATTR = 'data-ok-external-file-drop-root-target';
const FILE_TREE_EXTERNAL_FILE_DROP_BUSY_PATH = '__external-file-drop__';
-// Cadence for re-attempting the listing fetch while a desktop auto-update
-// relaunch is in flight. The server is intentionally torn down (up to 10s)
-// before `quitAndInstall`, so a steady retry lets the panel self-heal the
-// moment the server returns — e.g. when a relaunch aborts and the app keeps
-// running — instead of latching a stale error until the next focus/CC1 refresh.
-const CONNECTIVITY_RECONNECT_RETRY_MS = 2000;
const FILE_TREE_EXTERNAL_FILE_DROP_CSS = `
[data-type="item"][${FILE_TREE_EXTERNAL_FILE_DROP_TARGET_ATTR}="true"] {
background: color-mix(in oklab, var(--color-primary) 10%, transparent);
@@ -1090,67 +1073,6 @@ export interface FileTreeHandle {
subscribe(listener: () => void): () => void;
}
-type ShowAllDepth1ListingResult =
- | { kind: 'entries'; entries: FileEntry[]; truncated: boolean }
- | { kind: 'http-error'; title: string }
- | { kind: 'network-error'; cause: unknown };
-
-/**
- * The depth-1 disk-walk listing URL. `showOk` is the request-scoped reveal
- * of `.ok` rows (Show .ok folders axis) — the server admits `.ok` entries on
- * this walk only, so the flag rides the listing URL rather than any global
- * mode.
- */
-function showAllDepth1Url(dir: string, showOk: boolean): string {
- return `/api/documents?showAll=true${showOk ? '&showOk=true' : ''}&dir=${encodeURIComponent(dir)}&depth=1`;
-}
-
-/**
- * One level of the Show All listing for `dir` (`''` = content root), via the
- * same NDJSON-or-buffered branching as the root refresh. Failures come back
- * as values so the component-side caller stays a straight-line function —
- * React Compiler cannot yet lower `try`/`finally` inside component scope.
- * Error titles are parameters because translation lives with the caller.
- */
-async function fetchShowAllDepth1Listing(
- dir: string,
- showOk: boolean,
- signal: AbortSignal,
- fallbackErrorTitle: string,
- schemaMismatchTitle: string,
-): Promise<ShowAllDepth1ListingResult> {
- try {
- const res = await fetch(showAllDepth1Url(dir, showOk), {
- signal,
- headers: SHOW_ALL_NDJSON_ACCEPT,
- });
- if (isNdjsonResponse(res)) {
- const consumed = await consumeShowAllStream(res);
- return {
- kind: 'entries',
- entries: toFileEntries(consumed.entries),
- truncated: consumed.truncated,
- };
- }
- const parsed = await parseServerResponse(res, fallbackErrorTitle);
- if (!parsed.ok) return { kind: 'http-error', title: parsed.title };
- const success = DocumentListSuccessSchema.safeParse(parsed.body);
- if (!success.success) return { kind: 'http-error', title: schemaMismatchTitle };
- return {
- kind: 'entries',
- entries: toFileEntries(success.data.documents),
- truncated: success.data.truncated === true,
- };
- } catch (cause) {
- // A server-emitted NDJSON error line means the server WAS reached — its
- // problem title is the truthful message, not the connectivity copy.
- if (cause instanceof ShowAllStreamError) {
- return { kind: 'http-error', title: cause.message };
- }
- return { kind: 'network-error', cause };
- }
-}
-
/**
* Must be mounted inside a `SidebarProvider` — `useSidebar()` throws otherwise.
* Today only `FileSidebar` mounts it, which is always inside the provider.
@@ -1184,6 +1106,33 @@ export function FileTree({
const { notifySidebarFileSelected } = useSidebar();
const { resolvedTheme } = useTheme();
const { addPage, pageMeta, pages } = usePageList();
+ const { okignoreBinding, merged } = useConfigContext();
+ const showHiddenFiles = merged?.appearance?.sidebar?.showHiddenFiles ?? false;
+ const showOnlyMarkdownFiles = merged?.appearance?.sidebar?.showOnlyMarkdownFiles ?? false;
+ const showOkFolders = merged?.appearance?.sidebar?.showOkFolders ?? false;
+ const previewTabs = merged?.editor?.previewTabs ?? true;
+ const {
+ documents,
+ setDocuments,
+ recordOptimisticAdd,
+ loading,
+ error,
+ setError,
+ reconnecting,
+ relaunchInFlight,
+ truncatedShownCount,
+ unfilteredRootEntryCount,
+ observeExpandedFolderPaths,
+ } = useFileTreeListing({
+ showHiddenFiles,
+ showOnlyMarkdownFiles,
+ showOkFolders,
+ messages: {
+ fallbackErrorTitle: t`Failed to load documents`,
+ schemaMismatchTitle: t`Documents response did not match expected shape.`,
+ couldNotReachServerTitle: t`Could not reach server`,
+ },
+ });
function navigationTargetForDocument(
docName: string,
size: number | null | undefined,
@@ -1196,28 +1145,6 @@ export function FileTree({
}
);
}
- const [documents, setDocuments] = useState<FileEntry[]>([]);
- const [loading, setLoading] = useState(true);
- const [error, setError] = useState<string | null>(null);
- // True while the listing is being silently re-attempted after a reachability
- // failure that coincides with a known desktop auto-update relaunch. Drives a
- // calm "Relaunching…" notice in place of the red "Could not reach server"
- // error, and is cleared the moment a fetch succeeds (self-heal) or the
- // reachability failure outlives the relaunch (then the honest error wins).
- const [reconnecting, setReconnecting] = useState(false);
- // Drives the render copy + the start/abort flip effect. The fetch closures
- // read the live value via `getRelaunchInFlightSnapshot()` at failure time
- // (always current — no effect-synced ref needed).
- const relaunchInFlight = useRelaunchInFlight();
- const connectivityRetryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
- // Count of entries the server returned when the showAll walk hit its entry
- // cap (so the list is a partial prefix); null when the list is complete.
- const [truncatedShownCount, setTruncatedShownCount] = useState<number | null>(null);
- // Pre-filter size of the most recent depth-1 root listing, captured where
- // the listing lands. The filtered `documents` state can't distinguish an
- // empty project from filters hiding everything (raw listings aren't
- // retained), so the empty slot's classifier reads this signal instead.
- const [unfilteredRootEntryCount, setUnfilteredRootEntryCount] = useState(0);
const [busyPath, setBusyPath] = useState<string | null>(null);
const [deleteRequest, setDeleteRequest] = useState<FileTreeDeleteRequest | null>(null);
const [templateConvertRequest, setTemplateConvertRequest] = useState<FileTreeTarget | null>(null);
@@ -1386,58 +1313,17 @@ export function FileTree({
>(() => {});
const busyPathRef = useRef<string | null>(null);
const copiedKeyboardTargetRef = useRef<FileTreeTarget | null>(null);
- // Tracks locally-added tree paths (file/folder creates) with the timestamp
- // when they were optimistically inserted into `documents` state. Used by
- // `refreshDocs` to preserve entries the server's file-watcher index has not
- // yet picked up — without this, the `setDocuments(serverResponse)` call below
- // overwrites local optimistic state, dropping the new entry and breaking the
- // adjacent right-click context-menu flow. The underlying race class is
- // parcel-watcher inotify-event delivery lag on Linux CI. Entries expire
- // after STALE_REFRESH_PRESERVE_WINDOW_MS or when the server confirms.
- const recentLocalAddsRef = useRef<Map<string, number>>(new Map());
- // Lazy Show All expansion (client half): folders fetch their
- // children on first expand via `?showAll=true&dir=<folder>&depth=1`. All
- // three refs key by folder TREE path ('team/'). The loaded-dirs cache and
- // any in-flight child fetches are scoped to one refresh cycle — refreshDocs
- // aborts the fetches, clears the cache, and bumps the generation stamp so a
- // child response racing a root re-seed is discarded instead of splicing
- // stale entries.
- const lazyLoadedDirTreePathsRef = useRef<Set<string>>(new Set());
- const lazyChildFetchControllersRef = useRef<Map<string, AbortController>>(new Map());
- const lazyChildFetchGenerationRef = useRef(0);
- // Snapshot the expanded-folder diff compares against to detect newly
- // expanded folders. Pierre has no expand callback, so the model-subscribe
- // diff is the one mechanism covering row clicks, ArrowRight, drag-hover
- // auto-open, and programmatic expansion alike.
- const prevExpandedFolderTreePathsRef = useRef<ReadonlySet<string>>(new Set());
- const detectLazyFolderExpansionsRef = useRef<() => void>(() => {});
- const revalidateExpandedLazyDirsRef = useRef<() => void>(() => {});
- // The async fetch closures in the docs refresh effect are created once at
- // mount; reading the visibility toggles directly would capture their
- // mount-time values. The refs let a closure read the latest toggle state
- // when the response actually lands. Initialized to `false` (matches the
- // cold-start defaults before config loads); synced in the bulk
- // useLayoutEffect below.
- const showHiddenFilesRef = useRef<boolean>(false);
- const showOnlyMarkdownFilesRef = useRef<boolean>(false);
+ const observeExpandedFolderPathsRef = useRef<(paths: readonly string[]) => void>(() => {});
+ // Pierre reset helpers may run after an awaited mutation, so they read the
+ // latest `showOkFolders` setting rather than the render that started it.
const showOkFoldersRef = useRef<boolean>(false);
// Preview-tab behavior: on (the default), a tree click reuses the active tab
// the way an editor preview tab does; off, every click opens its own tab.
- // Same ref treatment as the visibility toggles above — the open closures are
+ // Same ref treatment as the view setting above — the open closures are
// created at mount and must read the latest value at click time.
const previewTabsRef = useRef<boolean>(true);
const openTabBehavior = (): 'append' | 'replace-active' =>
previewTabsRef.current ? 'replace-active' : 'append';
- const treeVisibilityFromRefs = () => ({
- showHiddenFiles: showHiddenFilesRef.current,
- showOnlyMarkdownFiles: showOnlyMarkdownFilesRef.current,
- showOkFolders: showOkFoldersRef.current,
- });
- // Hoists the docs scheduler's `request()` out of its effect closure so
- // the showHiddenFiles-flip effect can re-fetch without re-mounting the
- // listener / scheduler. Set to a callable in the docs effect; cleared on
- // unmount.
- const refreshDocsScheduleRef = useRef<(() => void) | null>(null);
const fileTreeHostRef = useRef<HTMLDivElement | null>(null);
const handleSelectionChangeRef = useRef<(selectedPaths: readonly string[]) => void>(() => {});
const handleRenameRef = useRef<(event: FileTreeRenameEvent) => void>(() => {});
@@ -1446,70 +1332,6 @@ export function FileTree({
const activeTargetRef = useRef(activeTarget);
const [emptyExternalFileDropActive, setEmptyExternalFileDropActive] = useState(false);
- // --- Reachability handling (desktop auto-update relaunch self-heal) ------
- // The file tree owns the global "Could not reach server" signal the other
- // sidebar sections defer to. During a desktop relaunch the server is
- // intentionally torn down (up to 10s) before `quitAndInstall`, so route
- // reachability failures through these helpers: stay calm and keep retrying
- // while a relaunch is in flight, but surface the honest error immediately for
- // a real outage (unchanged behavior).
- function clearConnectivityRetry() {
- if (connectivityRetryTimerRef.current !== null) {
- clearTimeout(connectivityRetryTimerRef.current);
- connectivityRetryTimerRef.current = null;
- }
- }
- function noteConnectivityRecovered() {
- clearConnectivityRetry();
- setReconnecting(false);
- }
- // An HTTP response (4xx/5xx, shape mismatch, mid-stream error) proves the
- // server WAS reachable — drop any calm-reconnect state so the genuine error
- // is shown, never masked behind the spinner. HTTP errors don't reschedule a
- // retry, so without this the spinner could latch with the error invisible.
- function reportServerReachableError(title: string) {
- noteConnectivityRecovered();
- setError(title);
- }
- function reportConnectivityFailure() {
- clearConnectivityRetry();
- // Read the live store snapshot (always current) rather than an effect-synced
- // ref, so an in-flight fetch failing before a render commits still sees the
- // relaunch and stays calm.
- if (getRelaunchInFlightSnapshot()) {
- setError(null);
- setReconnecting(true);
- connectivityRetryTimerRef.current = setTimeout(() => {
- connectivityRetryTimerRef.current = null;
- refreshDocsScheduleRef.current?.();
- }, CONNECTIVITY_RECONNECT_RETRY_MS);
- return;
- }
- setReconnecting(false);
- setError(t`Could not reach server`);
- }
-
- // Re-attempt the listing whenever a relaunch starts or aborts: starting → the
- // failing fetch flips the banner from red to the calm "Relaunching…" copy;
- // aborting → a successful fetch self-heals the panel without waiting for the
- // next focus / CC1 refresh. Skips the initial render.
- const isFirstRelaunchEffectRunRef = useRef(true);
- // biome-ignore lint/correctness/useExhaustiveDependencies: relaunchInFlight is a transition trigger, not a read — the body calls the hoisted scheduler ref only. Sibling pattern at the visibility-toggle flip effect below.
- useEffect(() => {
- if (isFirstRelaunchEffectRunRef.current) {
- isFirstRelaunchEffectRunRef.current = false;
- return;
- }
- refreshDocsScheduleRef.current?.();
- }, [relaunchInFlight]);
-
- // Drop a pending reconnect retry on unmount so a late timer can't touch state
- // after teardown. `clearConnectivityRetry` only reads a stable ref; it is
- // intentionally NOT a dep — listing it would re-run this effect (and fire its
- // cleanup) every render, cancelling live retries.
- // biome-ignore lint/correctness/useExhaustiveDependencies: mount/unmount-only; see comment above.
- useEffect(() => clearConnectivityRetry, []);
-
useEffect(() => {
if (loading || documents.length === 0) return;
const shadow = fileTreeHostRef.current?.querySelector(FILE_TREE_TAG_NAME)?.shadowRoot;
@@ -1639,12 +1461,6 @@ export function FileTree({
isElectronHost: typeof window !== 'undefined' && window.okDesktop != null,
dispatch: dispatchHandoff,
};
- const { okignoreBinding, merged } = useConfigContext();
- const showHiddenFiles = merged?.appearance?.sidebar?.showHiddenFiles ?? false;
- const showOnlyMarkdownFiles = merged?.appearance?.sidebar?.showOnlyMarkdownFiles ?? false;
- const showOkFolders = merged?.appearance?.sidebar?.showOkFolders ?? false;
- const previewTabs = merged?.editor?.previewTabs ?? true;
-
const isAvailable = () => busyPathRef.current === null;
const { model } = useFileTree({
@@ -1772,105 +1588,6 @@ export function FileTree({
});
};
- // Fetch one level of children for a folder the user just expanded and
- // accumulate them into `documents` — the treePathsSignature
- // reset effect then rebuilds the model with expansion preserved via
- // `initialExpandedPaths`. Failures surface through the same header error
- // affordance as the root refresh.
- async function fetchLazyFolderChildren(folderTreePath: string) {
- const generation = lazyChildFetchGenerationRef.current;
- const controller = new AbortController();
- lazyChildFetchControllersRef.current.set(folderTreePath, controller);
- const result = await fetchShowAllDepth1Listing(
- treeDirectoryPathToFolderPath(folderTreePath),
- showOkFoldersRef.current,
- controller.signal,
- t`Failed to load documents`,
- t`Documents response did not match expected shape.`,
- );
- if (lazyChildFetchControllersRef.current.get(folderTreePath) === controller) {
- lazyChildFetchControllersRef.current.delete(folderTreePath);
- }
- // Stale = deliberately aborted, or a refresh cycle (root re-seed / toggle
- // flip / unmount) superseded this fetch after its response was already
- // being consumed — either way the result must not touch state. Not
- // re-marking the dir as loaded keeps the folder re-expandable.
- if (controller.signal.aborted || generation !== lazyChildFetchGenerationRef.current) return;
- if (result.kind === 'network-error') {
- reportConnectivityFailure();
- // Same folder-scope traceability as the http-error branch below —
- // concurrent child fetches are otherwise indistinguishable in the log.
- console.warn('[FileTree] lazy folder children fetch failed:', folderTreePath, result.cause);
- return;
- }
- if (result.kind === 'http-error') {
- // The banner shows only the title — log the folder so a per-directory
- // failure (4xx/5xx or schema mismatch) is traceable to its scope.
- console.warn('[FileTree] lazy folder children http error:', folderTreePath, result.title);
- reportServerReachableError(result.title);
- return;
- }
- const children = filterVisibleEntries(result.entries, treeVisibilityFromRefs());
- lazyLoadedDirTreePathsRef.current.add(folderTreePath);
- // Functional update: concurrent child fetches resolve in the same
- // microtask batch, and `documentsRef` only syncs on commit — reading it
- // here would let the second splice clobber the first.
- setDocuments((prev) =>
- spliceLazyFolderChildren(prev, folderTreePath, children, recentLocalAddsRef.current),
- );
- setError(null);
- noteConnectivityRecovered();
- // A truncated child level reuses the root truncation affordance — the
- // banner describes the most recent capped listing either way.
- if (result.truncated) setTruncatedShownCount(result.entries.length);
- }
-
- // Diff the expanded-folder set against the previous snapshot on every model
- // state change and kick off a child fetch for each newly expanded, not-yet-
- // loaded folder. The sidebar always loads lazily — one level per expand — so
- // every newly expanded, not-yet-loaded folder fetches its children here.
- const detectLazyFolderExpansions = () => {
- const expanded = collectExpandedFolderTreePaths();
- const previous = prevExpandedFolderTreePathsRef.current;
- prevExpandedFolderTreePathsRef.current = expanded;
- for (const folderTreePath of expanded) {
- if (previous.has(folderTreePath)) continue;
- // Loaded this refresh cycle — collapse/re-expand serves the cached
- // children; the next refreshDocs run clears the cache.
- if (lazyLoadedDirTreePathsRef.current.has(folderTreePath)) continue;
- // Already fetching — a rapid collapse/re-expand rides the in-flight
- // request instead of duplicating it.
- if (lazyChildFetchControllersRef.current.has(folderTreePath)) continue;
- // The depth-1 listing stamps `hasChildren` on folders; a server-marked
- // childless folder expands to empty without a round trip. Folders
- // without the stamp (optimistic local adds) still fetch.
- const folderPath = treeDirectoryPathToFolderPath(folderTreePath);
- const entry = documentsRef.current.find(
- (candidate): candidate is Extract<FileEntry, { kind: 'folder' }> =>
- isFolderEntry(candidate) && candidate.path === folderPath,
- );
- if (entry?.hasChildren === false) continue;
- void fetchLazyFolderChildren(folderTreePath);
- }
- };
-
- // After a root re-seed applies, refetch one level for every folder
- // still expanded so external creates/deletes inside the visible working set
- // land without a full recursive walk and without waiting for a manual
- // collapse/re-expand. The caller (refreshDocs) has already cleared the
- // loaded-dirs cache and aborted prior child fetches, so anything found
- // loaded or in-flight here was started within the current refresh cycle
- // (a folder the user expanded mid-refresh) and is already fresh. Unlike the
- // expansion detector there is no `hasChildren === false` skip: an expanded
- // empty folder must still learn about children created externally.
- const revalidateExpandedLazyDirs = () => {
- for (const folderTreePath of collectExpandedFolderTreePaths()) {
- if (lazyLoadedDirTreePathsRef.current.has(folderTreePath)) continue;
- if (lazyChildFetchControllersRef.current.has(folderTreePath)) continue;
- void fetchLazyFolderChildren(folderTreePath);
- }
- };
-
// Invariant: Pierre's `#focusedPath` and `#selectedPaths` reference paths
// in `documentsToTreePaths(documents)`. If the user deletes the suffix
// before committing an inline rename, Pierre can leave the store keyed by
@@ -2197,202 +1914,6 @@ export function FileTree({
};
}, []);
- // biome-ignore lint/correctness/useExhaustiveDependencies: this is a once-per-`t` mount-lifecycle setup (it wires the refresh scheduler + listeners). The connectivity helpers it calls (reportConnectivityFailure / noteConnectivityRecovered) only touch refs + stable setters and close over the same `t` already in deps, so listing them would re-create the scheduler every render for no behavioral gain.
- useEffect(() => {
- let active = true;
- // Holds the in-flight refresh's AbortController so a superseding refresh (or
- // teardown) can cancel the stale fetch — and the server walk behind it —
- // instead of letting it run to completion. Reassigned on each refreshDocs run.
- let refreshController: AbortController | null = null;
-
- async function refreshDocs() {
- // Supersede any still-in-flight refresh before starting a new one.
- refreshController?.abort();
- const controller = new AbortController();
- refreshController = controller;
- // A refresh cycle also supersedes the lazy child-fetch state: abort
- // in-flight child fetches, invalidate the per-cycle loaded-dirs cache
- // (external changes refetch on next expand), and stamp a new generation
- // so an already-resolved child response can't splice stale entries.
- lazyChildFetchGenerationRef.current += 1;
- for (const childController of lazyChildFetchControllersRef.current.values()) {
- childController.abort();
- }
- lazyChildFetchControllersRef.current.clear();
- lazyLoadedDirTreePathsRef.current.clear();
- try {
- // The sidebar always fetches the disk-walk listing lazily — one level
- // per request (`depth=1`; the empty `dir=` scopes to the content root),
- // each folder stamped `hasChildren` so it can offer expansion without
- // the server walking its subtree. The full recursive walk (no `depth`)
- // remains served for non-sidebar callers.
- const res = await fetch(showAllDepth1Url('', showOkFoldersRef.current), {
- signal: controller.signal,
- // Opt into the NDJSON stream so the server walks disk without
- // buffering the whole listing; the buffered JSON path stays the
- // fallback for non-streaming servers.
- headers: SHOW_ALL_NDJSON_ACCEPT,
- });
- if (isNdjsonResponse(res)) {
- // Streaming listing: consume the NDJSON walk one entry at a time, each
- // validated as it arrives (the per-line analogue of the buffered
- // whole-array safeParse). Paint each chunk's entries additively so the
- // sidebar fills in progressively and the skeleton clears on the first
- // batch — NOT a root splice, which prunes folders not yet streamed.
- // The authoritative prune + optimistic-merge reconcile is the single
- // splice once the stream completes, matching the buffered branch.
- // One snapshot for the whole stream so batches and the completion
- // splice filter identically; a mid-stream toggle flip refetches
- // (flip effect below) rather than half-filtering this run.
- const visibility = treeVisibilityFromRefs();
- let paintedFirstBatch = false;
- const { entries, truncated } = await consumeShowAllStream(res, {
- onBatch: (batch) => {
- if (!active || controller.signal.aborted) return;
- const batchEntries = filterVisibleEntries(toFileEntries(batch), visibility);
- // Only act on a batch that yields a VISIBLE row. The server walk
- // emits hidden entries (dot-dirs/files) in arbitrary readdir order;
- // the client filters them. Clearing `loading` on an all-hidden
- // first chunk would render `loading===false && documents===[]` —
- // the "No files yet" empty state — on a non-empty KB. So defer the
- // skeleton flip until a real row paints; completion owns the rest.
- if (batchEntries.length === 0) return;
- setDocuments((prev) => mergeRootEntriesAdditive(prev, batchEntries));
- if (!paintedFirstBatch) {
- paintedFirstBatch = true;
- setError(null);
- noteConnectivityRecovered();
- setLoading(false);
- }
- },
- });
- if (!active) return;
- const rootEntries = toFileEntries(entries);
- const serverEntries = filterVisibleEntries(rootEntries, visibility);
- // The depth-1 root level replaces in place rather than replacing the
- // whole document set: children already loaded for folders the server
- // still returns keep rendering (no flash-empty on every CC1 push),
- // descendants of folders the server dropped are pruned, and the
- // revalidation pass below refreshes each still-expanded folder's
- // level. Functional update: a child splice resolving in the same
- // batch must not be clobbered.
- setDocuments((prev) =>
- spliceLazyFolderChildren(prev, '', serverEntries, recentLocalAddsRef.current),
- );
- setError(null);
- noteConnectivityRecovered();
- setTruncatedShownCount(truncated ? entries.length : null);
- setUnfilteredRootEntryCount(rootEntries.length);
- revalidateExpandedLazyDirsRef.current();
- } else {
- const parsed = await parseServerResponse(res, t`Failed to load documents`);
- if (!active) return;
- if (!parsed.ok) {
- reportServerReachableError(parsed.title);
- setTruncatedShownCount(null);
- } else {
- const success = DocumentListSuccessSchema.safeParse(parsed.body);
- if (!success.success) {
- reportServerReachableError(t`Documents response did not match expected shape.`);
- setTruncatedShownCount(null);
- } else {
- // Non-streaming fallback for the same depth-1 listing. The disk
- // walk ships everything the server admits; the client-side
- // visibility filter applies the sidebar toggles.
- const rootEntries = toFileEntries(success.data.documents);
- const serverEntries = filterVisibleEntries(rootEntries, treeVisibilityFromRefs());
- // Same in-place root splice + expanded-dir revalidation as the
- // NDJSON branch above — the buffered JSON shape is the
- // non-streaming fallback for the identical depth-1 listing.
- setDocuments((prev) =>
- spliceLazyFolderChildren(prev, '', serverEntries, recentLocalAddsRef.current),
- );
- setError(null);
- noteConnectivityRecovered();
- setTruncatedShownCount(
- success.data.truncated === true ? success.data.documents.length : null,
- );
- setUnfilteredRootEntryCount(rootEntries.length);
- revalidateExpandedLazyDirsRef.current();
- }
- }
- }
- } catch (err) {
- // A superseded or torn-down refresh aborts this run's controller. That
- // is a deliberate cancel, not a server-reachability failure, so don't
- // surface it as an error or clear loading — the trailing re-run (or the
- // next mount) owns the next UI update.
- if (controller.signal.aborted) return;
- // Batches already painted via `onBatch` (incremental seed) are NOT rolled
- // back here: `mergeRootEntriesAdditive` is purely additive, so on a
- // mid-stream error the tree is left over-inclusive (prior-good entries
- // plus the partial stream) rather than flashed empty — the safe
- // direction. The next successful refresh's completion splice reconciles
- // (prunes the stale rows). The authoritative prune only runs on success.
- // A mid-stream server error line reached us over a live connection —
- // the server WAS reachable, so surface its problem title and drop any
- // reconnect state; everything else is a reachability failure, routed
- // through the relaunch-aware self-heal path.
- if (active) {
- if (err instanceof ShowAllStreamError) {
- reportServerReachableError(err.message);
- } else {
- reportConnectivityFailure();
- }
- }
- console.warn('[FileTree] fetch failed:', err);
- }
- if (active) setLoading(false);
- }
-
- const scheduler = createRefreshScheduler(refreshDocs, () => refreshController?.abort());
- refreshDocsScheduleRef.current = () => scheduler.request();
- scheduler.request();
- const handleResume = () => {
- if (document.visibilityState === 'visible') {
- scheduler.request();
- }
- };
- window.addEventListener('focus', handleResume);
- window.addEventListener('visibilitychange', handleResume);
- const unsubscribe = subscribeToDocumentsChanged((channels) => {
- if (channels.includes('files')) {
- scheduler.request();
- }
- });
- return () => {
- active = false;
- refreshDocsScheduleRef.current = null;
- scheduler.dispose();
- // Lazy child fetches outlive the scheduler's cancel hook — abort them
- // here so a response landing after teardown can't touch state.
- for (const childController of lazyChildFetchControllersRef.current.values()) {
- childController.abort();
- }
- lazyChildFetchControllersRef.current.clear();
- window.removeEventListener('focus', handleResume);
- window.removeEventListener('visibilitychange', handleResume);
- unsubscribe();
- };
- }, [t]);
-
- // Re-fetch + re-filter when the user flips a sidebar visibility toggle.
- // Hidden files and only-markdown are pure client-side filters (the server
- // response doesn't depend on them); Show .ok folders parameterizes the
- // request itself (the listing URL carries `showOk`). Either way the flip
- // reuses the scheduler's in-flight coalescing, and the fetch closures read
- // the flipped values through the refs. Skips on first render to avoid
- // double-fetching on mount.
- const isFirstVisibilityFlipEffectRunRef = useRef(true);
- // biome-ignore lint/correctness/useExhaustiveDependencies: the visibility toggles are flip-detection triggers, not reads — the effect body reads refs only. Sibling pattern at the treePathsSignature reset effect above.
- useEffect(() => {
- if (isFirstVisibilityFlipEffectRunRef.current) {
- isFirstVisibilityFlipEffectRunRef.current = false;
- return;
- }
- refreshDocsScheduleRef.current?.();
- }, [showHiddenFiles, showOnlyMarkdownFiles, showOkFolders]);
-
useEffect(() => {
let active = true;
fetch('/api/workspace')
@@ -2544,11 +2065,11 @@ export function FileTree({
});
}, [model]);
- // Lazy Show All expansion detector — see detectLazyFolderExpansions. Reads
- // through the ref so the subscribe callback always sees the latest render's
- // closure (same latest-handler pattern as the bulk useLayoutEffect refs).
+ // biome-ignore lint/correctness/useExhaustiveDependencies: the subscription reads the latest hook callback through its ref and only the Pierre model controls its lifetime.
useEffect(() => {
- return model.subscribe(() => detectLazyFolderExpansionsRef.current());
+ return model.subscribe(() => {
+ observeExpandedFolderPathsRef.current([...collectExpandedFolderTreePaths()]);
+ });
}, [model]);
useEffect(() => {
@@ -2976,7 +2497,7 @@ export function FileTree({
const next = [...current];
for (const entry of uploadedEntries) {
const treePath = fileEntryToTreePath(entry);
- recentLocalAddsRef.current.set(treePath, Date.now());
+ recordOptimisticAdd(entry);
if (existing.has(treePath)) continue;
existing.add(treePath);
next.push(entry);
@@ -2991,7 +2512,6 @@ export function FileTree({
if (uploadedCount > 0) {
emitDocumentsChanged(['files', 'backlinks', 'graph']);
- refreshDocsScheduleRef.current?.();
toast.success(
plural(uploadedCount, {
one: 'Uploaded one file',
@@ -3100,7 +2620,7 @@ export function FileTree({
}
const next = [...current, newFileEntry];
markNextDocumentsAsApplied(next);
- recentLocalAddsRef.current.set(fileEntryToTreePath(newFileEntry), Date.now());
+ recordOptimisticAdd(newFileEntry);
return next;
});
emitDocumentsChanged(['files', 'backlinks', 'graph']);
@@ -3140,7 +2660,7 @@ export function FileTree({
}
const next = [...current, newFolderEntry];
markNextDocumentsAsApplied(next);
- recentLocalAddsRef.current.set(fileEntryToTreePath(newFolderEntry), Date.now());
+ recordOptimisticAdd(newFolderEntry);
return next;
});
emitDocumentsChanged(['files']);
@@ -3238,15 +2758,12 @@ export function FileTree({
activeTargetRef.current = activeTarget;
assetTreePathsRef.current = assetTreePaths;
busyPathRef.current = busyPath;
- showHiddenFilesRef.current = showHiddenFiles;
- showOnlyMarkdownFilesRef.current = showOnlyMarkdownFiles;
showOkFoldersRef.current = showOkFolders;
previewTabsRef.current = previewTabs;
treePathsRef.current = treePaths;
folderTreePathsRef.current = folderTreePaths;
activeAncestorTreePathsRef.current = activeAncestorTreePaths;
- detectLazyFolderExpansionsRef.current = detectLazyFolderExpansions;
- revalidateExpandedLazyDirsRef.current = revalidateExpandedLazyDirs;
+ observeExpandedFolderPathsRef.current = observeExpandedFolderPaths;
cleanupPendingCreateRef.current = cleanupPendingCreate;
uploadExternalFilesRef.current = (files, parentDir, uploadBusyPath) => {
void uploadExternalFilesToTarget(files, parentDir, uploadBusyPath);
diff --git a/packages/app/src/components/file-tree-listing-transport.test.ts b/packages/app/src/components/file-tree-listing-transport.test.ts
new file mode 100644
index 000000000..dc799be75
--- /dev/null
+++ b/packages/app/src/components/file-tree-listing-transport.test.ts
@@ -0,0 +1,197 @@
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { ShowAllStreamError } from '@/lib/show-all-stream';
+import { fetchShowAllDepth1Listing, showAllDepth1Url } from './file-tree-listing-transport';
+
+const messages = {
+ fallbackErrorTitle: 'Failed to load documents',
+ schemaMismatchTitle: 'Documents response did not match expected shape.',
+};
+
+function documentEntry(docName: string) {
+ return {
+ kind: 'document',
+ docName,
+ docExt: '.md',
+ size: 1,
+ modified: '2026-01-01T00:00:00.000Z',
+ isSymlink: false,
+ canonicalDocName: null,
+ targetPath: null,
+ };
+}
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('file-tree-listing transport', () => {
+ test('builds one encoded depth-one URL and includes showOk only when requested', () => {
+ expect(showAllDepth1Url('', false)).toBe('/api/documents?showAll=true&dir=&depth=1');
+ expect(showAllDepth1Url('team notes/a', true)).toBe(
+ '/api/documents?showAll=true&showOk=true&dir=team%20notes%2Fa&depth=1',
+ );
+ });
+
+ test('returns buffered entries', async () => {
+ const controller = new AbortController();
+ const fetchMock = vi.fn(
+ async (_input: RequestInfo | URL, _init?: RequestInit) =>
+ new Response(JSON.stringify({ documents: [documentEntry('notes/a')], truncated: false }), {
+ headers: { 'content-type': 'application/json' },
+ }),
+ );
+ vi.stubGlobal('fetch', fetchMock);
+
+ const result = await fetchShowAllDepth1Listing({
+ dir: '',
+ showOk: false,
+ signal: controller.signal,
+ messages,
+ });
+
+ expect(result).toEqual({
+ kind: 'entries',
+ entries: [documentEntry('notes/a')],
+ truncated: false,
+ });
+ const requestInit = fetchMock.mock.calls[0]?.[1];
+ expect(requestInit?.signal).toBe(controller.signal);
+ expect(requestInit?.headers).toEqual(
+ expect.objectContaining({ Accept: expect.stringContaining('application/x-ndjson') }),
+ );
+ });
+
+ test('publishes NDJSON batches before returning the authoritative entries', async () => {
+ const entry = documentEntry('notes/a');
+ const releaseCompletion = Promise.withResolvers<void>();
+ const encoder = new TextEncoder();
+ const response = new Response(
+ new ReadableStream<Uint8Array>({
+ start(controller) {
+ controller.enqueue(encoder.encode(`${JSON.stringify(entry)}\n`));
+ void releaseCompletion.promise.then(() => {
+ controller.enqueue(
+ encoder.encode(
+ `${JSON.stringify({ type: 'complete', truncated: true, count: 1 })}\n`,
+ ),
+ );
+ controller.close();
+ });
+ },
+ }),
+ { headers: { 'content-type': 'application/x-ndjson' } },
+ );
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => response),
+ );
+ const batches: string[][] = [];
+ let completed = false;
+
+ const resultPromise = fetchShowAllDepth1Listing({
+ dir: '',
+ showOk: true,
+ signal: new AbortController().signal,
+ messages,
+ onBatch: (batch) =>
+ batches.push(batch.map((item) => (item.kind === 'document' ? item.docName : item.path))),
+ }).finally(() => {
+ completed = true;
+ });
+
+ await vi.waitFor(() => expect(batches).toEqual([['notes/a']]));
+ expect(completed).toBe(false);
+ releaseCompletion.resolve();
+ const result = await resultPromise;
+ expect(result).toEqual({ kind: 'entries', entries: [entry], truncated: true });
+ });
+
+ test('preserves HTTP and schema classifications without attaching causes', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => new Response('nope', { status: 500 })),
+ );
+ await expect(
+ fetchShowAllDepth1Listing({
+ dir: '',
+ showOk: false,
+ signal: new AbortController().signal,
+ messages,
+ }),
+ ).resolves.toEqual({
+ kind: 'http-error',
+ title: expect.stringContaining('HTTP 500'),
+ });
+
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(
+ async () =>
+ new Response(JSON.stringify({ nope: true }), {
+ headers: { 'content-type': 'application/json' },
+ }),
+ ),
+ );
+ await expect(
+ fetchShowAllDepth1Listing({
+ dir: '',
+ showOk: false,
+ signal: new AbortController().signal,
+ messages,
+ }),
+ ).resolves.toEqual({ kind: 'http-error', title: messages.schemaMismatchTitle });
+ });
+
+ test('preserves a stream error cause for root diagnostics', async () => {
+ const body = `${JSON.stringify({ type: 'error', problem: { title: 'walk failed' } })}\n`;
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(
+ async () => new Response(body, { headers: { 'content-type': 'application/x-ndjson' } }),
+ ),
+ );
+
+ const result = await fetchShowAllDepth1Listing({
+ dir: '',
+ showOk: false,
+ signal: new AbortController().signal,
+ messages,
+ });
+
+ expect(result).toMatchObject({
+ kind: 'http-error',
+ title: 'walk failed',
+ cause: expect.any(ShowAllStreamError),
+ });
+ });
+
+ test('returns an ordinary network failure with its cause', async () => {
+ const networkFailure = new TypeError('connection reset');
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => Promise.reject(networkFailure)),
+ );
+ await expect(
+ fetchShowAllDepth1Listing({
+ dir: '',
+ showOk: false,
+ signal: new AbortController().signal,
+ messages,
+ }),
+ ).resolves.toEqual({ kind: 'network-error', cause: networkFailure });
+ });
+
+ test('classifies an abort as a network failure carrying the abort as its cause', async () => {
+ const abort = new DOMException('aborted', 'AbortError');
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => Promise.reject(abort)),
+ );
+ await expect(
+ fetchShowAllDepth1Listing({
+ dir: '',
+ showOk: false,
+ signal: new AbortController().signal,
+ messages,
+ }),
+ ).resolves.toEqual({ kind: 'network-error', cause: abort });
+ });
+});
diff --git a/packages/app/src/components/file-tree-listing-transport.ts b/packages/app/src/components/file-tree-listing-transport.ts
new file mode 100644
index 000000000..a890ae896
--- /dev/null
+++ b/packages/app/src/components/file-tree-listing-transport.ts
@@ -0,0 +1,78 @@
+import { DocumentListSuccessSchema } from '@inkeep/open-knowledge-core';
+import { parseServerResponse } from '@/lib/parse-server-response';
+import {
+ consumeShowAllStream,
+ isNdjsonResponse,
+ SHOW_ALL_NDJSON_ACCEPT,
+ ShowAllStreamError,
+} from '@/lib/show-all-stream';
+import { type FileEntry, toFileEntries } from './file-tree-utils';
+
+export type ShowAllDepth1ListingResult =
+ | { kind: 'entries'; entries: FileEntry[]; truncated: boolean }
+ | { kind: 'http-error'; title: string; cause?: unknown }
+ | { kind: 'network-error'; cause: unknown };
+
+export interface FileTreeListingRequest {
+ dir: string;
+ showOk: boolean;
+ signal: AbortSignal;
+ onBatch?: (entries: FileEntry[]) => void;
+ messages: {
+ fallbackErrorTitle: string;
+ schemaMismatchTitle: string;
+ };
+}
+
+export interface FileTreeListingSource {
+ listDepthOne(request: FileTreeListingRequest): Promise<ShowAllDepth1ListingResult>;
+}
+
+export function showAllDepth1Url(dir: string, showOk: boolean): string {
+ return `/api/documents?showAll=true${showOk ? '&showOk=true' : ''}&dir=${encodeURIComponent(dir)}&depth=1`;
+}
+
+export async function fetchShowAllDepth1Listing({
+ dir,
+ showOk,
+ signal,
+ onBatch,
+ messages,
+}: FileTreeListingRequest): Promise<ShowAllDepth1ListingResult> {
+ try {
+ const response = await fetch(showAllDepth1Url(dir, showOk), {
+ signal,
+ headers: SHOW_ALL_NDJSON_ACCEPT,
+ });
+ if (isNdjsonResponse(response)) {
+ const consumed = await consumeShowAllStream(response, {
+ onBatch: onBatch ? (entries) => onBatch(toFileEntries(entries)) : undefined,
+ });
+ return {
+ kind: 'entries',
+ entries: toFileEntries(consumed.entries),
+ truncated: consumed.truncated,
+ };
+ }
+ const parsed = await parseServerResponse(response, messages.fallbackErrorTitle);
+ if (!parsed.ok) return { kind: 'http-error', title: parsed.title };
+ const success = DocumentListSuccessSchema.safeParse(parsed.body);
+ if (!success.success) {
+ return { kind: 'http-error', title: messages.schemaMismatchTitle };
+ }
+ return {
+ kind: 'entries',
+ entries: toFileEntries(success.data.documents),
+ truncated: success.data.truncated === true,
+ };
+ } catch (cause) {
+ if (cause instanceof ShowAllStreamError) {
+ return { kind: 'http-error', title: cause.message, cause };
+ }
+ return { kind: 'network-error', cause };
+ }
+}
+
+export const httpFileTreeListingSource: FileTreeListingSource = {
+ listDepthOne: fetchShowAllDepth1Listing,
+};
diff --git a/packages/app/src/components/use-file-tree-listing.dom.test.tsx b/packages/app/src/components/use-file-tree-listing.dom.test.tsx
new file mode 100644
index 000000000..8f05547f8
--- /dev/null
+++ b/packages/app/src/components/use-file-tree-listing.dom.test.tsx
@@ -0,0 +1,551 @@
+import { act, cleanup, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import type {
+ FileTreeListingRequest,
+ FileTreeListingSource,
+ ShowAllDepth1ListingResult,
+} from './file-tree-listing-transport';
+import { useFileTreeListing } from './use-file-tree-listing';
+
+const relaunchState = vi.hoisted(() => ({ inFlight: false }));
+
+vi.mock('@/lib/relaunch-store', () => ({
+ getRelaunchInFlightSnapshot: () => relaunchState.inFlight,
+ useRelaunchInFlight: () => relaunchState.inFlight,
+}));
+
+vi.mock('@/lib/documents-events', () => ({
+ subscribeToDocumentsChanged: () => () => {},
+}));
+
+const messages = {
+ fallbackErrorTitle: 'Failed to load documents',
+ schemaMismatchTitle: 'Documents response did not match expected shape.',
+ couldNotReachServerTitle: 'Could not reach server',
+};
+
+function documentEntry(docName: string) {
+ return {
+ kind: 'document' as const,
+ docName,
+ docExt: '.md',
+ size: 1,
+ modified: '2026-01-01T00:00:00.000Z',
+ };
+}
+
+function folderEntry(path: string, hasChildren = true) {
+ return {
+ kind: 'folder' as const,
+ path,
+ size: 0,
+ modified: '2026-01-01T00:00:00.000Z',
+ hasChildren,
+ };
+}
+
+function assetEntry(path: string) {
+ return {
+ kind: 'asset' as const,
+ path,
+ assetExt: path.split('.').pop() ?? 'file',
+ mediaKind: null,
+ size: 1,
+ modified: '2026-01-01T00:00:00.000Z',
+ referencedBy: [],
+ };
+}
+
+interface PendingRequest {
+ request: FileTreeListingRequest;
+ resolve(result: ShowAllDepth1ListingResult): void;
+ reject(cause: unknown): void;
+}
+
+function createListingSource() {
+ const pending: PendingRequest[] = [];
+ const source: FileTreeListingSource = {
+ listDepthOne(request) {
+ return new Promise((resolve, reject) => pending.push({ request, resolve, reject }));
+ },
+ };
+ return { source, pending };
+}
+
+interface ListingVisibility {
+ showHiddenFiles: boolean;
+ showOnlyMarkdownFiles: boolean;
+ showOkFolders: boolean;
+}
+
+const defaultVisibility: ListingVisibility = {
+ showHiddenFiles: false,
+ showOnlyMarkdownFiles: false,
+ showOkFolders: false,
+};
+
+function renderListing(
+ source: FileTreeListingSource,
+ initialVisibility: ListingVisibility = defaultVisibility,
+) {
+ return renderHook(
+ (visibility: ListingVisibility) =>
+ useFileTreeListing({
+ ...visibility,
+ messages,
+ source,
+ }),
+ { initialProps: initialVisibility },
+ );
+}
+
+function requestRootRefresh() {
+ Object.defineProperty(document, 'visibilityState', { configurable: true, value: 'visible' });
+ act(() => window.dispatchEvent(new Event('focus')));
+}
+
+afterEach(() => {
+ cleanup();
+ relaunchState.inFlight = false;
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+});
+
+describe('useFileTreeListing', () => {
+ test('starts one root request and publishes streamed batches before completion', async () => {
+ const { source, pending } = createListingSource();
+ const { result } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+
+ act(() => pending[0]?.request.onBatch?.([documentEntry('notes/a')]));
+ await waitFor(() => expect(result.current.documents).toEqual([documentEntry('notes/a')]));
+ expect(result.current.loading).toBe(false);
+
+ await act(async () => {
+ pending[0]?.resolve({
+ kind: 'entries',
+ entries: [documentEntry('notes/a'), documentEntry('notes/b')],
+ truncated: false,
+ });
+ });
+ await waitFor(() => expect(result.current.documents).toHaveLength(2));
+ });
+
+ test('tracks the authoritative unfiltered root count when visibility hides every entry', async () => {
+ const { source, pending } = createListingSource();
+ const { result } = renderListing(source, {
+ ...defaultVisibility,
+ showOnlyMarkdownFiles: true,
+ });
+ await waitFor(() => expect(pending).toHaveLength(1));
+
+ await act(async () => {
+ pending[0]?.resolve({
+ kind: 'entries',
+ entries: [assetEntry('data.csv')],
+ truncated: false,
+ });
+ });
+
+ expect(result.current.documents).toEqual([]);
+ expect(result.current.unfilteredRootEntryCount).toBe(1);
+ });
+
+ test('refetches and filters with each latest visibility setting', async () => {
+ const { source, pending } = createListingSource();
+ const { result, rerender } = renderListing(source);
+ const entries = [
+ documentEntry('README'),
+ documentEntry('.hidden'),
+ assetEntry('data.csv'),
+ folderEntry('.ok'),
+ ];
+ await waitFor(() => expect(pending).toHaveLength(1));
+ await act(async () => {
+ pending[0]?.resolve({ kind: 'entries', entries, truncated: false });
+ });
+ expect(result.current.documents).toEqual([documentEntry('README'), assetEntry('data.csv')]);
+
+ rerender({ ...defaultVisibility, showHiddenFiles: true });
+ await waitFor(() => expect(pending).toHaveLength(2));
+ await act(async () => {
+ pending[1]?.resolve({ kind: 'entries', entries, truncated: false });
+ });
+ expect(result.current.documents).toEqual([
+ documentEntry('README'),
+ documentEntry('.hidden'),
+ assetEntry('data.csv'),
+ ]);
+
+ rerender({
+ ...defaultVisibility,
+ showHiddenFiles: true,
+ showOnlyMarkdownFiles: true,
+ });
+ await waitFor(() => expect(pending).toHaveLength(3));
+ await act(async () => {
+ pending[2]?.resolve({ kind: 'entries', entries, truncated: false });
+ });
+ expect(result.current.documents).toEqual([documentEntry('README'), documentEntry('.hidden')]);
+
+ rerender({
+ showHiddenFiles: true,
+ showOnlyMarkdownFiles: true,
+ showOkFolders: true,
+ });
+ await waitFor(() => expect(pending).toHaveLength(4));
+ expect(pending[3]?.request.showOk).toBe(true);
+ await act(async () => {
+ pending[3]?.resolve({ kind: 'entries', entries, truncated: false });
+ });
+ expect(result.current.documents).toEqual([
+ documentEntry('README'),
+ documentEntry('.hidden'),
+ folderEntry('.ok'),
+ ]);
+ });
+
+ test('retries a relaunch outage and self-heals when the server returns', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { source, pending } = createListingSource();
+ const { result, rerender } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ await act(async () => {
+ pending[0]?.resolve({
+ kind: 'entries',
+ entries: [documentEntry('before')],
+ truncated: false,
+ });
+ });
+
+ relaunchState.inFlight = true;
+ rerender(defaultVisibility);
+ await waitFor(() => expect(pending).toHaveLength(2));
+ vi.useFakeTimers();
+ const outage = new TypeError('server restarting');
+ await act(async () => {
+ pending[1]?.resolve({ kind: 'network-error', cause: outage });
+ });
+ expect(result.current.relaunchInFlight).toBe(true);
+ expect(result.current.reconnecting).toBe(true);
+ expect(result.current.error).toBeNull();
+ expect(warn).toHaveBeenLastCalledWith('[FileTree] fetch failed:', outage);
+
+ act(() => vi.advanceTimersByTime(1_999));
+ expect(pending).toHaveLength(2);
+ act(() => vi.advanceTimersByTime(1));
+ expect(pending).toHaveLength(3);
+
+ await act(async () => {
+ pending[2]?.resolve({
+ kind: 'entries',
+ entries: [documentEntry('after')],
+ truncated: false,
+ });
+ });
+ expect(result.current.documents).toEqual([documentEntry('after')]);
+ expect(result.current.reconnecting).toBe(false);
+ expect(result.current.error).toBeNull();
+ });
+
+ test('normalizes a rejected root source as a network failure', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { source, pending } = createListingSource();
+ const { result } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ const cause = new Error('custom source rejected');
+
+ await act(async () => {
+ pending[0]?.reject(cause);
+ });
+
+ await waitFor(() => expect(result.current.error).toBe(messages.couldNotReachServerTitle));
+ expect(result.current.loading).toBe(false);
+ expect(warn).toHaveBeenLastCalledWith('[FileTree] fetch failed:', cause);
+ });
+
+ test('rejects a superseded root response and aborts its public request signal', async () => {
+ const { source, pending } = createListingSource();
+ const { result } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ requestRootRefresh();
+ expect(pending[0]?.request.signal.aborted).toBe(true);
+ expect(pending).toHaveLength(1);
+
+ await act(async () => {
+ pending[0]?.resolve({ kind: 'entries', entries: [documentEntry('old')], truncated: false });
+ });
+ await waitFor(() => expect(pending).toHaveLength(2));
+ expect(result.current.documents).toEqual([]);
+
+ await act(async () => {
+ pending[1]?.resolve({ kind: 'entries', entries: [documentEntry('new')], truncated: false });
+ });
+ await waitFor(() => expect(result.current.documents).toEqual([documentEntry('new')]));
+ });
+
+ test('starts a lazy request once per expanded folder and aborts it on unmount', async () => {
+ const { source, pending } = createListingSource();
+ const { result, unmount } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ await act(async () => {
+ pending[0]?.resolve({
+ kind: 'entries',
+ entries: [folderEntry('team')],
+ truncated: false,
+ });
+ });
+
+ act(() => {
+ result.current.observeExpandedFolderPaths(['team/']);
+ result.current.observeExpandedFolderPaths(['team/']);
+ });
+ await waitFor(() => expect(pending).toHaveLength(2));
+ unmount();
+ expect(pending[1]?.request.signal.aborted).toBe(true);
+ });
+
+ test('reports a lazy network failure and recovers on a later expansion', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { source, pending } = createListingSource();
+ const { result } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ await act(async () => {
+ pending[0]?.resolve({ kind: 'entries', entries: [folderEntry('team')], truncated: false });
+ });
+
+ act(() => result.current.observeExpandedFolderPaths(['team/']));
+ await waitFor(() => expect(pending).toHaveLength(2));
+ const cause = new TypeError('connection reset');
+ await act(async () => {
+ pending[1]?.resolve({ kind: 'network-error', cause });
+ });
+ expect(result.current.error).toBe(messages.couldNotReachServerTitle);
+ expect(warn).toHaveBeenLastCalledWith(
+ '[FileTree] lazy folder children fetch failed:',
+ 'team/',
+ cause,
+ );
+
+ act(() => {
+ result.current.observeExpandedFolderPaths([]);
+ result.current.observeExpandedFolderPaths(['team/']);
+ });
+ await waitFor(() => expect(pending).toHaveLength(3));
+ await act(async () => {
+ pending[2]?.resolve({
+ kind: 'entries',
+ entries: [documentEntry('team/recovered')],
+ truncated: false,
+ });
+ });
+ expect(result.current.documents).toEqual([
+ folderEntry('team'),
+ documentEntry('team/recovered'),
+ ]);
+ expect(result.current.error).toBeNull();
+ });
+
+ test('reports a lazy HTTP failure and recovers on a later expansion', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { source, pending } = createListingSource();
+ const { result } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ await act(async () => {
+ pending[0]?.resolve({ kind: 'entries', entries: [folderEntry('team')], truncated: false });
+ });
+
+ act(() => result.current.observeExpandedFolderPaths(['team/']));
+ await waitFor(() => expect(pending).toHaveLength(2));
+ await act(async () => {
+ pending[1]?.resolve({ kind: 'http-error', title: 'Folder walk failed' });
+ });
+ expect(result.current.error).toBe('Folder walk failed');
+ expect(warn).toHaveBeenLastCalledWith(
+ '[FileTree] lazy folder children http error:',
+ 'team/',
+ 'Folder walk failed',
+ );
+
+ act(() => {
+ result.current.observeExpandedFolderPaths([]);
+ result.current.observeExpandedFolderPaths(['team/']);
+ });
+ await waitFor(() => expect(pending).toHaveLength(3));
+ await act(async () => {
+ pending[2]?.resolve({
+ kind: 'entries',
+ entries: [documentEntry('team/recovered')],
+ truncated: false,
+ });
+ });
+ expect(result.current.documents).toEqual([
+ folderEntry('team'),
+ documentEntry('team/recovered'),
+ ]);
+ expect(result.current.error).toBeNull();
+ });
+
+ test('normalizes a rejected lazy source and clears its slot for a retry', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { source, pending } = createListingSource();
+ const { result } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ await act(async () => {
+ pending[0]?.resolve({ kind: 'entries', entries: [folderEntry('team')], truncated: false });
+ });
+
+ act(() => result.current.observeExpandedFolderPaths(['team/']));
+ await waitFor(() => expect(pending).toHaveLength(2));
+ const cause = new Error('custom source rejected');
+ await act(async () => {
+ pending[1]?.reject(cause);
+ });
+ expect(result.current.error).toBe(messages.couldNotReachServerTitle);
+ expect(warn).toHaveBeenLastCalledWith(
+ '[FileTree] lazy folder children fetch failed:',
+ 'team/',
+ cause,
+ );
+
+ act(() => {
+ result.current.observeExpandedFolderPaths([]);
+ result.current.observeExpandedFolderPaths(['team/']);
+ });
+ await waitFor(() => expect(pending).toHaveLength(3));
+ });
+
+ test('rejects a stale child result after a root refresh advances the generation', async () => {
+ const { source, pending } = createListingSource();
+ const { result, unmount } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ await act(async () => {
+ pending[0]?.resolve({ kind: 'entries', entries: [folderEntry('team')], truncated: false });
+ });
+ await waitFor(() => expect(result.current.documents).toEqual([folderEntry('team')]));
+
+ act(() => result.current.observeExpandedFolderPaths(['team/']));
+ await waitFor(() => expect(pending).toHaveLength(2));
+ expect(pending[1]?.request.dir).toBe('team');
+
+ requestRootRefresh();
+ await waitFor(() => expect(pending).toHaveLength(3));
+ expect(pending[1]?.request.signal.aborted).toBe(true);
+
+ await act(async () => {
+ pending[1]?.resolve({
+ kind: 'entries',
+ entries: [documentEntry('team/stale')],
+ truncated: false,
+ });
+ });
+ expect(result.current.documents).toEqual([folderEntry('team')]);
+ unmount();
+ });
+
+ test('preserves, confirms, and expires optimistic additions through root listings', async () => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(new Date('2026-08-03T12:00:00.000Z'));
+ const { source, pending } = createListingSource();
+ const { result } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ await act(async () => {
+ pending[0]?.resolve({ kind: 'entries', entries: [], truncated: false });
+ });
+
+ const optimistic = documentEntry('optimistic');
+ act(() => {
+ result.current.setDocuments([optimistic]);
+ result.current.recordOptimisticAdd(optimistic);
+ });
+ requestRootRefresh();
+ await waitFor(() => expect(pending).toHaveLength(2));
+ await act(async () => {
+ pending[1]?.resolve({ kind: 'entries', entries: [], truncated: false });
+ });
+ await waitFor(() => expect(result.current.documents).toEqual([optimistic]));
+
+ const confirmed = { ...optimistic, size: 42 };
+ requestRootRefresh();
+ await waitFor(() => expect(pending).toHaveLength(3));
+ await act(async () => {
+ pending[2]?.resolve({ kind: 'entries', entries: [confirmed], truncated: false });
+ });
+ await waitFor(() => expect(result.current.documents).toEqual([confirmed]));
+
+ const expiring = documentEntry('expiring');
+ act(() => {
+ result.current.setDocuments((current) => [...current, expiring]);
+ result.current.recordOptimisticAdd(expiring);
+ });
+ vi.setSystemTime(new Date('2026-08-03T12:00:05.001Z'));
+ requestRootRefresh();
+ await waitFor(() => expect(pending).toHaveLength(4));
+ await act(async () => {
+ pending[3]?.resolve({ kind: 'entries', entries: [confirmed], truncated: false });
+ });
+ await waitFor(() => expect(result.current.documents).toEqual([confirmed]));
+ });
+
+ test('aborts a pending root request when the hook unmounts', async () => {
+ const { source, pending } = createListingSource();
+ const { unmount } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ unmount();
+ expect(pending[0]?.request.signal.aborted).toBe(true);
+ });
+
+ test('retains the last safe truncation count when a streamed root refresh fails', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { source, pending } = createListingSource();
+ const { result } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ const safeEntries = [documentEntry('notes/a'), documentEntry('notes/b')];
+ await act(async () => {
+ pending[0]?.resolve({ kind: 'entries', entries: safeEntries, truncated: true });
+ });
+ await waitFor(() => expect(result.current.truncatedShownCount).toBe(2));
+
+ requestRootRefresh();
+ await waitFor(() => expect(pending).toHaveLength(2));
+ const streamCause = new Error('stream failure');
+ await act(async () => {
+ pending[1]?.resolve({ kind: 'http-error', title: 'stream failure', cause: streamCause });
+ });
+
+ await waitFor(() => expect(result.current.error).toBe('stream failure'));
+ expect(result.current.documents).toEqual(safeEntries);
+ expect(result.current.truncatedShownCount).toBe(2);
+ expect(warn).toHaveBeenLastCalledWith('[FileTree] fetch failed:', streamCause);
+ });
+
+ test('logs only root failures that carry a transport cause', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { source, pending } = createListingSource();
+ const { result } = renderListing(source);
+ await waitFor(() => expect(pending).toHaveLength(1));
+ const networkCause = new TypeError('connection reset');
+ await act(async () => {
+ pending[0]?.resolve({ kind: 'network-error', cause: networkCause });
+ });
+ await waitFor(() => expect(result.current.error).toBe(messages.couldNotReachServerTitle));
+ expect(warn).toHaveBeenLastCalledWith('[FileTree] fetch failed:', networkCause);
+
+ requestRootRefresh();
+ await waitFor(() => expect(pending).toHaveLength(2));
+ await act(async () => {
+ pending[1]?.resolve({ kind: 'http-error', title: 'HTTP failure' });
+ });
+ await waitFor(() => expect(result.current.error).toBe('HTTP failure'));
+ expect(warn).toHaveBeenCalledTimes(1);
+
+ const streamCause = new Error('stream failure');
+ requestRootRefresh();
+ await waitFor(() => expect(pending).toHaveLength(3));
+ await act(async () => {
+ pending[2]?.resolve({ kind: 'http-error', title: 'stream failure', cause: streamCause });
+ });
+ await waitFor(() => expect(result.current.error).toBe('stream failure'));
+ expect(warn).toHaveBeenLastCalledWith('[FileTree] fetch failed:', streamCause);
+ });
+});
diff --git a/packages/app/src/components/use-file-tree-listing.ts b/packages/app/src/components/use-file-tree-listing.ts
new file mode 100644
index 000000000..43e9e67a2
--- /dev/null
+++ b/packages/app/src/components/use-file-tree-listing.ts
@@ -0,0 +1,326 @@
+import {
+ type Dispatch,
+ type SetStateAction,
+ useEffect,
+ useLayoutEffect,
+ useRef,
+ useState,
+} from 'react';
+import { subscribeToDocumentsChanged } from '@/lib/documents-events';
+import { createRefreshScheduler } from '@/lib/refresh-scheduler';
+import { getRelaunchInFlightSnapshot, useRelaunchInFlight } from '@/lib/relaunch-store';
+import { fileEntryToTreePath, treeDirectoryPathToFolderPath } from './file-tree-adapter';
+import {
+ type FileTreeListingSource,
+ httpFileTreeListingSource,
+} from './file-tree-listing-transport';
+import { mergeRootEntriesAdditive, spliceLazyFolderChildren } from './file-tree-merge';
+import { type FileEntry, filterVisibleEntries, isFolderEntry } from './file-tree-utils';
+
+// Desktop auto-update can intentionally stop the server for up to 10 seconds.
+// A steady retry also self-heals when the relaunch aborts without another focus or CC1 event.
+const CONNECTIVITY_RECONNECT_RETRY_MS = 2_000;
+
+interface ListingMessages {
+ fallbackErrorTitle: string;
+ schemaMismatchTitle: string;
+ couldNotReachServerTitle: string;
+}
+
+interface FileTreeListingOptions {
+ showHiddenFiles: boolean;
+ showOnlyMarkdownFiles: boolean;
+ showOkFolders: boolean;
+ messages: ListingMessages;
+ source?: FileTreeListingSource;
+}
+
+export interface FileTreeListingHandle {
+ documents: FileEntry[];
+ setDocuments: Dispatch<SetStateAction<FileEntry[]>>;
+ recordOptimisticAdd(entry: FileEntry): void;
+ loading: boolean;
+ error: string | null;
+ setError: Dispatch<SetStateAction<string | null>>;
+ reconnecting: boolean;
+ relaunchInFlight: boolean;
+ truncatedShownCount: number | null;
+ unfilteredRootEntryCount: number;
+ observeExpandedFolderPaths(paths: readonly string[]): void;
+}
+
+export function useFileTreeListing({
+ showHiddenFiles,
+ showOnlyMarkdownFiles,
+ showOkFolders,
+ messages,
+ source = httpFileTreeListingSource,
+}: FileTreeListingOptions): FileTreeListingHandle {
+ const [documents, setDocuments] = useState<FileEntry[]>([]);
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState<string | null>(null);
+ const [reconnecting, setReconnecting] = useState(false);
+ const [truncatedShownCount, setTruncatedShownCount] = useState<number | null>(null);
+ // Filtered documents cannot distinguish an empty project from one whose root rows are all
+ // hidden, so preserve the pre-filter count for empty-state classification.
+ const [unfilteredRootEntryCount, setUnfilteredRootEntryCount] = useState(0);
+ const relaunchInFlight = useRelaunchInFlight();
+
+ const documentsRef = useRef(documents);
+ const visibilityRef = useRef({ showHiddenFiles, showOnlyMarkdownFiles, showOkFolders });
+ const messagesRef = useRef(messages);
+ const expandedFolderPathsRef = useRef<ReadonlySet<string>>(new Set());
+ // Preserve local creates while parcel-watcher/inotify catches up; the merge helper expires or
+ // confirms each entry within its bounded window.
+ const optimisticAddsRef = useRef<Map<string, number>>(new Map());
+ const loadedFolderPathsRef = useRef<Set<string>>(new Set());
+ const childControllersRef = useRef<Map<string, AbortController>>(new Map());
+ const childGenerationRef = useRef(0);
+ const requestRefreshRef = useRef<(() => void) | null>(null);
+ const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+ useLayoutEffect(() => {
+ documentsRef.current = documents;
+ }, [documents]);
+
+ function visibility() {
+ return visibilityRef.current;
+ }
+
+ function clearRetry() {
+ if (retryTimerRef.current !== null) {
+ clearTimeout(retryTimerRef.current);
+ retryTimerRef.current = null;
+ }
+ }
+
+ function noteConnectivityRecovered() {
+ clearRetry();
+ setReconnecting(false);
+ }
+
+ function reportServerReachableError(title: string) {
+ noteConnectivityRecovered();
+ setError(title);
+ }
+
+ function reportConnectivityFailure() {
+ clearRetry();
+ if (getRelaunchInFlightSnapshot()) {
+ setError(null);
+ setReconnecting(true);
+ retryTimerRef.current = setTimeout(() => {
+ retryTimerRef.current = null;
+ requestRefreshRef.current?.();
+ }, CONNECTIVITY_RECONNECT_RETRY_MS);
+ return;
+ }
+ setReconnecting(false);
+ setError(messagesRef.current.couldNotReachServerTitle);
+ }
+
+ function recordOptimisticAdd(entry: FileEntry) {
+ optimisticAddsRef.current.set(fileEntryToTreePath(entry), Date.now());
+ }
+
+ function startLazyFolderListing(folderTreePath: string, includeKnownEmpty: boolean) {
+ if (loadedFolderPathsRef.current.has(folderTreePath)) return;
+ if (childControllersRef.current.has(folderTreePath)) return;
+ const folderPath = treeDirectoryPathToFolderPath(folderTreePath);
+ const entry = documentsRef.current.find(
+ (candidate): candidate is Extract<FileEntry, { kind: 'folder' }> =>
+ isFolderEntry(candidate) && candidate.path === folderPath,
+ );
+ if (!includeKnownEmpty && entry?.hasChildren === false) return;
+
+ const generation = childGenerationRef.current;
+ const controller = new AbortController();
+ childControllersRef.current.set(folderTreePath, controller);
+ void source
+ .listDepthOne({
+ dir: folderPath,
+ showOk: visibility().showOkFolders,
+ signal: controller.signal,
+ messages: messagesRef.current,
+ })
+ .catch((cause: unknown) => ({ kind: 'network-error' as const, cause }))
+ .then((result) => {
+ if (childControllersRef.current.get(folderTreePath) === controller) {
+ childControllersRef.current.delete(folderTreePath);
+ }
+ if (controller.signal.aborted || generation !== childGenerationRef.current) return;
+ if (result.kind === 'network-error') {
+ reportConnectivityFailure();
+ console.warn(
+ '[FileTree] lazy folder children fetch failed:',
+ folderTreePath,
+ result.cause,
+ );
+ return;
+ }
+ if (result.kind === 'http-error') {
+ console.warn('[FileTree] lazy folder children http error:', folderTreePath, result.title);
+ reportServerReachableError(result.title);
+ return;
+ }
+ const children = filterVisibleEntries(result.entries, visibility());
+ loadedFolderPathsRef.current.add(folderTreePath);
+ setDocuments((previous) =>
+ spliceLazyFolderChildren(previous, folderTreePath, children, optimisticAddsRef.current),
+ );
+ setError(null);
+ noteConnectivityRecovered();
+ if (result.truncated) setTruncatedShownCount(result.entries.length);
+ });
+ }
+
+ function revalidateExpandedFolders() {
+ for (const path of expandedFolderPathsRef.current) {
+ startLazyFolderListing(path, true);
+ }
+ }
+
+ function observeExpandedFolderPaths(paths: readonly string[]) {
+ const expanded = new Set(paths);
+ const previous = expandedFolderPathsRef.current;
+ expandedFolderPathsRef.current = expanded;
+ for (const path of expanded) {
+ if (!previous.has(path)) startLazyFolderListing(path, false);
+ }
+ }
+
+ useLayoutEffect(() => {
+ messagesRef.current = messages;
+ }, [messages]);
+
+ // biome-ignore lint/correctness/useExhaustiveDependencies: this lifecycle owns one scheduler per source and locale message set; helpers deliberately read live refs so visibility and reconnect state do not recreate it.
+ useEffect(() => {
+ let active = true;
+ let rootController: AbortController | null = null;
+
+ async function refresh() {
+ rootController?.abort();
+ const controller = new AbortController();
+ rootController = controller;
+ childGenerationRef.current += 1;
+ for (const childController of childControllersRef.current.values()) childController.abort();
+ childControllersRef.current.clear();
+ loadedFolderPathsRef.current.clear();
+
+ let paintedFirstVisibleBatch = false;
+ const result = await source
+ .listDepthOne({
+ dir: '',
+ showOk: visibility().showOkFolders,
+ signal: controller.signal,
+ messages: messagesRef.current,
+ onBatch: (batch) => {
+ if (!active || controller.signal.aborted || rootController !== controller) return;
+ const visibleBatch = filterVisibleEntries(batch, visibility());
+ // Hidden rows can arrive first; keep the skeleton until a visible row paints so a
+ // non-empty knowledge base never flashes its empty state.
+ if (visibleBatch.length === 0) return;
+ // Batches only add because pruning here would drop root rows not streamed yet.
+ setDocuments((previous) => mergeRootEntriesAdditive(previous, visibleBatch));
+ if (!paintedFirstVisibleBatch) {
+ paintedFirstVisibleBatch = true;
+ setError(null);
+ noteConnectivityRecovered();
+ setLoading(false);
+ }
+ },
+ })
+ .catch((cause: unknown) => ({ kind: 'network-error' as const, cause }));
+ if (!active || controller.signal.aborted || rootController !== controller) return;
+ if (result.kind === 'network-error') {
+ reportConnectivityFailure();
+ console.warn('[FileTree] fetch failed:', result.cause);
+ } else if (result.kind === 'http-error') {
+ reportServerReachableError(result.title);
+ // Only streamed server errors carry a cause and leave a meaningful partial-list count;
+ // buffered HTTP or schema failures invalidate the prior completed-list count.
+ if (result.cause === undefined) {
+ setTruncatedShownCount(null);
+ } else {
+ console.warn('[FileTree] fetch failed:', result.cause);
+ }
+ } else {
+ const currentVisibility = visibility();
+ const serverEntries = filterVisibleEntries(result.entries, currentVisibility);
+ // Successful completion owns the single authoritative prune and optimistic-add reconcile.
+ setDocuments((previous) =>
+ spliceLazyFolderChildren(previous, '', serverEntries, optimisticAddsRef.current),
+ );
+ setError(null);
+ noteConnectivityRecovered();
+ setTruncatedShownCount(result.truncated ? result.entries.length : null);
+ setUnfilteredRootEntryCount(result.entries.length);
+ revalidateExpandedFolders();
+ }
+ if (active) setLoading(false);
+ }
+
+ const scheduler = createRefreshScheduler(refresh, () => rootController?.abort());
+ requestRefreshRef.current = () => scheduler.request();
+ scheduler.request();
+ const handleResume = () => {
+ if (document.visibilityState === 'visible') scheduler.request();
+ };
+ window.addEventListener('focus', handleResume);
+ window.addEventListener('visibilitychange', handleResume);
+ const unsubscribe = subscribeToDocumentsChanged((channels) => {
+ if (channels.includes('files')) scheduler.request();
+ });
+ return () => {
+ active = false;
+ requestRefreshRef.current = null;
+ scheduler.dispose();
+ for (const controller of childControllersRef.current.values()) controller.abort();
+ childControllersRef.current.clear();
+ window.removeEventListener('focus', handleResume);
+ window.removeEventListener('visibilitychange', handleResume);
+ unsubscribe();
+ };
+ }, [messages.fallbackErrorTitle, messages.schemaMismatchTitle, source]);
+
+ useLayoutEffect(() => {
+ visibilityRef.current = { showHiddenFiles, showOnlyMarkdownFiles, showOkFolders };
+ }, [showHiddenFiles, showOnlyMarkdownFiles, showOkFolders]);
+
+ const firstVisibilityEffectRunRef = useRef(true);
+ // biome-ignore lint/correctness/useExhaustiveDependencies: visibility values are transition triggers; the layout effect owns ref synchronization and this effect schedules through a stable ref.
+ useEffect(() => {
+ if (firstVisibilityEffectRunRef.current) {
+ firstVisibilityEffectRunRef.current = false;
+ return;
+ }
+ requestRefreshRef.current?.();
+ }, [showHiddenFiles, showOnlyMarkdownFiles, showOkFolders]);
+
+ const firstRelaunchEffectRunRef = useRef(true);
+ // biome-ignore lint/correctness/useExhaustiveDependencies: relaunchInFlight is a transition trigger; the body schedules through a stable ref.
+ useEffect(() => {
+ if (firstRelaunchEffectRunRef.current) {
+ firstRelaunchEffectRunRef.current = false;
+ return;
+ }
+ requestRefreshRef.current?.();
+ }, [relaunchInFlight]);
+
+ // biome-ignore lint/correctness/useExhaustiveDependencies: mount/unmount cleanup reads the retry ref and must not cancel a live retry after each render.
+ useEffect(() => clearRetry, []);
+
+ return {
+ documents,
+ setDocuments,
+ recordOptimisticAdd,
+ loading,
+ error,
+ setError,
+ reconnecting,
+ relaunchInFlight,
+ truncatedShownCount,
+ unfilteredRootEntryCount,
+ observeExpandedFolderPaths,
+ };
+}