From e8a976ff8ffe4eefa092555df444645d65a0b0f5 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Wed, 22 Jul 2026 14:58:37 +0200
Subject: [PATCH 1/3] feat(web): add file tree expansion controls

---
 .../src/components/files/FileBrowserPanel.tsx |  59 +++++-
 .../files/fileTreeExpansion.test.ts           | 192 ++++++++++++++++++
 .../src/components/files/fileTreeExpansion.ts |  90 ++++++++
 3 files changed, 336 insertions(+), 5 deletions(-)
 create mode 100644 apps/web/src/components/files/fileTreeExpansion.test.ts
 create mode 100644 apps/web/src/components/files/fileTreeExpansion.ts

diff --git a/apps/web/src/components/files/FileBrowserPanel.tsx b/apps/web/src/components/files/FileBrowserPanel.tsx
index 3f53d65533d..3e1b8a1d393 100644
--- a/apps/web/src/components/files/FileBrowserPanel.tsx
+++ b/apps/web/src/components/files/FileBrowserPanel.tsx
@@ -5,8 +5,8 @@ import type {
 import type { EnvironmentId, ProjectEntry } from "@t3tools/contracts";
 import { FileTree, useFileTree } from "@pierre/trees/react";
 import { serializeComposerFileLink } from "@t3tools/shared/composerTrigger";
-import { RefreshCw, Search } from "lucide-react";
-import { useEffect, useMemo, useRef } from "react";
+import { ChevronsDownUp, ChevronsUpDown, RefreshCw, Search } from "lucide-react";
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 
 import { toastManager } from "~/components/ui/toast";
 import { useComposerHandleContext } from "~/composerHandleContext";
@@ -17,6 +17,14 @@ import { readLocalApi } from "~/localApi";
 import { T3_PIERRE_ICONS } from "~/pierre-icons";
 
 import { createFileTreeDragMentionController } from "./fileTreeDragMention";
+import {
+  COLLAPSE_ALL_FOLDERS_LABEL,
+  directoryTreePaths,
+  EXPAND_ALL_FOLDERS_LABEL,
+  getFileTreeExpansionSnapshot,
+  initiallyExpandedDirectoryPaths,
+  setAllDirectoriesExpanded,
+} from "./fileTreeExpansion";
 import { useProjectEntriesQuery } from "./projectFilesQueryState";
 
 interface FileBrowserPanelProps {
@@ -58,6 +66,7 @@ export default function FileBrowserPanel({
   );
   const entryKindsRef = useRef<ReadonlyMap<string, ProjectEntry["kind"]>>(entryKinds);
   const treePaths = useMemo(() => entries.map(treePath), [entries]);
+  const directoryPaths = useMemo(() => directoryTreePaths(entries), [entries]);
   const previousTreePathsRef = useRef<readonly string[]>([]);
 
   // The tree renders rows in shadow DOM and its anchor rect is unreliable, so
@@ -161,7 +170,7 @@ export default function FileBrowserPanel({
     density: "compact",
     fileTreeSearchMode: "hide-non-matches",
     flattenEmptyDirectories: true,
-    initialExpansion: 1,
+    initialExpansion: "closed",
     icons: T3_PIERRE_ICONS,
     onSelectionChange: (selectedPaths) => {
       dragMention.handleSelectionChange(selectedPaths);
@@ -179,13 +188,35 @@ export default function FileBrowserPanel({
     search: true,
     unsafeCSS: TREE_UNSAFE_CSS,
   });
+  const subscribeToTree = useCallback((listener: () => void) => model.subscribe(listener), [model]);
+  const getExpansionSnapshot = useCallback(
+    () => getFileTreeExpansionSnapshot(model, directoryPaths),
+    [directoryPaths, model],
+  );
+  const expansionSnapshot = useSyncExternalStore(
+    subscribeToTree,
+    getExpansionSnapshot,
+    getExpansionSnapshot,
+  );
+  const expansionControlsDisabled =
+    expansionSnapshot === "empty" || expansionSnapshot === "searching";
+  const canCollapseAll =
+    !expansionControlsDisabled &&
+    (expansionSnapshot === "expanded" || expansionSnapshot === "mixed");
+  const canExpandAll =
+    !expansionControlsDisabled &&
+    (expansionSnapshot === "collapsed" || expansionSnapshot === "mixed");
 
   useEffect(() => {
     if (previousTreePathsRef.current === treePaths) return;
     entryKindsRef.current = entryKinds;
     previousTreePathsRef.current = treePaths;
-    model.resetPaths(treePaths);
-  }, [entryKinds, model, treePaths]);
+    // A closed default lets bulk operations replace expansion in one reset;
+    // explicitly retain the explorer's existing depth-one initial state.
+    model.resetPaths(treePaths, {
+      initialExpandedPaths: initiallyExpandedDirectoryPaths(directoryPaths),
+    });
+  }, [directoryPaths, entryKinds, model, treePaths]);
 
   const fileCount = useMemo(
     () => entries.reduce((count, entry) => count + (entry.kind === "file" ? 1 : 0), 0),
@@ -233,6 +264,24 @@ export default function FileBrowserPanel({
             {entriesQuery.data?.truncated ? " · partial" : ""}
           </div>
         </div>
+        <button
+          type="button"
+          className="rounded-md p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
+          aria-label={COLLAPSE_ALL_FOLDERS_LABEL}
+          disabled={!canCollapseAll}
+          onClick={() => setAllDirectoriesExpanded(model, treePaths, directoryPaths, false)}
+        >
+          <ChevronsDownUp className="size-3.5" />
+        </button>
+        <button
+          type="button"
+          className="rounded-md p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
+          aria-label={EXPAND_ALL_FOLDERS_LABEL}
+          disabled={!canExpandAll}
+          onClick={() => setAllDirectoriesExpanded(model, treePaths, directoryPaths, true)}
+        >
+          <ChevronsUpDown className="size-3.5" />
+        </button>
         <button
           type="button"
           className="rounded-md p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground"
diff --git a/apps/web/src/components/files/fileTreeExpansion.test.ts b/apps/web/src/components/files/fileTreeExpansion.test.ts
new file mode 100644
index 00000000000..0493e155c22
--- /dev/null
+++ b/apps/web/src/components/files/fileTreeExpansion.test.ts
@@ -0,0 +1,192 @@
+import { describe, expect, it, vi } from "@effect/vitest";
+import { FileTree } from "@pierre/trees";
+import type { ProjectEntry } from "@t3tools/contracts";
+
+import {
+  COLLAPSE_ALL_FOLDERS_LABEL,
+  directoryTreePaths,
+  EXPAND_ALL_FOLDERS_LABEL,
+  getFileTreeExpansionSnapshot,
+  initiallyExpandedDirectoryPaths,
+  setAllDirectoriesExpanded,
+} from "./fileTreeExpansion.ts";
+
+function makeModel(expansionByPath: Record<string, boolean>, searching = false) {
+  const state = new Map(Object.entries(expansionByPath));
+  const expand = vi.fn((path: string) => state.set(path, true));
+  const collapse = vi.fn((path: string) => state.set(path, false));
+  const resetPaths = vi.fn(
+    (_paths: readonly string[], options: { initialExpandedPaths: readonly string[] }) => {
+      const expandedPaths = new Set(options.initialExpandedPaths);
+      for (const path of state.keys()) state.set(path, expandedPaths.has(path));
+    },
+  );
+  return {
+    collapse,
+    expand,
+    model: {
+      getItem: (path: string) =>
+        state.has(path)
+          ? {
+              collapse: () => collapse(path),
+              expand: () => expand(path),
+              isDirectory: () => true as const,
+              isExpanded: () => state.get(path) ?? false,
+            }
+          : null,
+      isSearchOpen: () => searching,
+      resetPaths,
+    },
+    resetPaths,
+    state,
+  };
+}
+
+describe("file tree expansion controls", () => {
+  it("collects unique nested directory paths in parent-first order for flattened trees", () => {
+    const entries: ProjectEntry[] = [
+      { kind: "file", path: "src/ui/index.ts" },
+      { kind: "directory", path: "src/ui" },
+      { kind: "directory", path: "src" },
+      { kind: "directory", path: "src/ui/" },
+    ];
+
+    expect(directoryTreePaths(entries)).toEqual(["src/", "src/ui/"]);
+    expect(initiallyExpandedDirectoryPaths(["src/", "src/ui/", "docs/"])).toEqual([
+      "src/",
+      "docs/",
+    ]);
+  });
+
+  it("expands and collapses every directory in a flattened tree model", () => {
+    const modelPaths = ["src/", "src/ui/", "src/ui/components/", "src/ui/components/Button.tsx"];
+    const model = new FileTree({
+      flattenEmptyDirectories: true,
+      initialExpansion: "closed",
+      paths: modelPaths,
+    });
+    const directoryPaths = ["src/", "src/ui/", "src/ui/components/"];
+
+    try {
+      setAllDirectoriesExpanded(model, modelPaths, directoryPaths, true);
+      expect(getFileTreeExpansionSnapshot(model, directoryPaths)).toBe("expanded");
+
+      setAllDirectoriesExpanded(model, modelPaths, directoryPaths, false);
+      expect(getFileTreeExpansionSnapshot(model, directoryPaths)).toBe("collapsed");
+    } finally {
+      model.cleanUp();
+    }
+  });
+
+  it("preserves the previous depth-one initial expansion", () => {
+    const modelPaths = ["docs/", "docs/guide/", "docs/guide/start.md", "src/", "src/index.ts"];
+    const directoryPaths = ["docs/", "src/", "docs/guide/"];
+    const previousModel = new FileTree({ initialExpansion: 1, paths: modelPaths });
+    const batchedModel = new FileTree({
+      initialExpandedPaths: initiallyExpandedDirectoryPaths(directoryPaths),
+      initialExpansion: "closed",
+      paths: modelPaths,
+    });
+
+    try {
+      expect(
+        directoryPaths.map((path) => getFileTreeExpansionSnapshot(previousModel, [path])),
+      ).toEqual(directoryPaths.map((path) => getFileTreeExpansionSnapshot(batchedModel, [path])));
+    } finally {
+      previousModel.cleanUp();
+      batchedModel.cleanUp();
+    }
+  });
+
+  it("reports an empty tree and uses explicit accessible labels", () => {
+    const { model } = makeModel({});
+
+    expect(getFileTreeExpansionSnapshot(model, [])).toBe("empty");
+    expect(COLLAPSE_ALL_FOLDERS_LABEL).toBe("Collapse all folders");
+    expect(EXPAND_ALL_FOLDERS_LABEL).toBe("Expand all folders");
+  });
+
+  it("expands only collapsed directories", () => {
+    const { expand, model, resetPaths, state } = makeModel({
+      "docs/": true,
+      "src/": false,
+      "src/ui/": false,
+    });
+
+    expect(getFileTreeExpansionSnapshot(model, [...state.keys()])).toBe("mixed");
+    const paths = [...state.keys()];
+    setAllDirectoriesExpanded(model, paths, paths, true);
+
+    expect(resetPaths).toHaveBeenCalledOnce();
+    expect(resetPaths).toHaveBeenCalledWith(paths, { initialExpandedPaths: paths });
+    expect(expand).not.toHaveBeenCalled();
+    expect(getFileTreeExpansionSnapshot(model, [...state.keys()])).toBe("expanded");
+
+    setAllDirectoriesExpanded(model, paths, paths, true);
+    expect(resetPaths).toHaveBeenCalledOnce();
+  });
+
+  it("collapses only expanded directories", () => {
+    const { collapse, model, resetPaths, state } = makeModel({
+      "docs/": false,
+      "src/": true,
+      "src/ui/": true,
+    });
+
+    const paths = [...state.keys()];
+    setAllDirectoriesExpanded(model, paths, paths, false);
+
+    expect(resetPaths).toHaveBeenCalledOnce();
+    expect(resetPaths).toHaveBeenCalledWith(paths, { initialExpandedPaths: [] });
+    expect(collapse).not.toHaveBeenCalled();
+    expect(getFileTreeExpansionSnapshot(model, [...state.keys()])).toBe("collapsed");
+  });
+
+  it("emits and recomputes subscribed state only once for a large tree", () => {
+    const directoryPaths = Array.from({ length: 2_000 }, (_, index) => `folder-${index}/`);
+    const model = new FileTree({ initialExpansion: "closed", paths: directoryPaths });
+    const originalGetItem = model.getItem.bind(model);
+    let itemReads = 0;
+    const countedModel = {
+      getItem: (path: string) => {
+        itemReads += 1;
+        return originalGetItem(path);
+      },
+      isSearchOpen: () => model.isSearchOpen(),
+      resetPaths: (
+        paths: readonly string[],
+        options: { initialExpandedPaths: readonly string[] },
+      ) => model.resetPaths(paths, options),
+    };
+    let subscriptionEmissions = 0;
+    const unsubscribe = model.subscribe(() => {
+      subscriptionEmissions += 1;
+      getFileTreeExpansionSnapshot(countedModel, directoryPaths);
+    });
+    const emissionsBeforeExpansion = subscriptionEmissions;
+    itemReads = 0;
+
+    try {
+      setAllDirectoriesExpanded(countedModel, directoryPaths, directoryPaths, true);
+
+      expect(subscriptionEmissions - emissionsBeforeExpansion).toBe(1);
+      expect(itemReads).toBeLessThanOrEqual(directoryPaths.length * 2);
+      expect(getFileTreeExpansionSnapshot(model, directoryPaths)).toBe("expanded");
+    } finally {
+      unsubscribe();
+      model.cleanUp();
+    }
+  });
+
+  it("does not change temporary expansion while search is open", () => {
+    const { collapse, expand, model, resetPaths } = makeModel({ "src/": true }, true);
+
+    expect(getFileTreeExpansionSnapshot(model, ["src/"])).toBe("searching");
+    setAllDirectoriesExpanded(model, ["src/"], ["src/"], false);
+    setAllDirectoriesExpanded(model, ["src/"], ["src/"], true);
+
+    expect(collapse).not.toHaveBeenCalled();
+    expect(expand).not.toHaveBeenCalled();
+    expect(resetPaths).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/web/src/components/files/fileTreeExpansion.ts b/apps/web/src/components/files/fileTreeExpansion.ts
new file mode 100644
index 00000000000..babfe626db7
--- /dev/null
+++ b/apps/web/src/components/files/fileTreeExpansion.ts
@@ -0,0 +1,90 @@
+import type { ProjectEntry } from "@t3tools/contracts";
+
+export const COLLAPSE_ALL_FOLDERS_LABEL = "Collapse all folders";
+export const EXPAND_ALL_FOLDERS_LABEL = "Expand all folders";
+
+interface FileTreeExpansionDirectoryItem {
+  collapse(): void;
+  expand(): void;
+  isDirectory(): true;
+  isExpanded(): boolean;
+}
+
+interface FileTreeExpansionFileItem {
+  isDirectory(): false;
+}
+
+type FileTreeExpansionItem = FileTreeExpansionDirectoryItem | FileTreeExpansionFileItem;
+
+interface FileTreeExpansionModel {
+  getItem(path: string): FileTreeExpansionItem | null;
+  isSearchOpen(): boolean;
+  resetPaths(paths: readonly string[], options: { initialExpandedPaths: readonly string[] }): void;
+}
+
+export type FileTreeExpansionSnapshot = "collapsed" | "empty" | "expanded" | "mixed" | "searching";
+
+function isDirectoryItem(
+  item: FileTreeExpansionItem | null,
+): item is FileTreeExpansionDirectoryItem {
+  return item?.isDirectory() === true;
+}
+
+export function directoryTreePaths(entries: readonly ProjectEntry[]): string[] {
+  return [
+    ...new Set(
+      entries
+        .filter((entry) => entry.kind === "directory")
+        .map((entry) => `${entry.path.replace(/\/$/, "")}/`),
+    ),
+  ].sort((left, right) => left.split("/").length - right.split("/").length);
+}
+
+export function initiallyExpandedDirectoryPaths(directoryPaths: readonly string[]): string[] {
+  return directoryPaths.filter((path) => path.split("/").filter(Boolean).length <= 1);
+}
+
+export function getFileTreeExpansionSnapshot(
+  model: FileTreeExpansionModel,
+  directoryPaths: readonly string[],
+): FileTreeExpansionSnapshot {
+  if (model.isSearchOpen()) return "searching";
+
+  let hasCollapsedDirectory = false;
+  let hasExpandedDirectory = false;
+  for (const path of directoryPaths) {
+    const item = model.getItem(path);
+    if (!isDirectoryItem(item)) continue;
+    if (item.isExpanded()) {
+      hasExpandedDirectory = true;
+    } else {
+      hasCollapsedDirectory = true;
+    }
+    if (hasCollapsedDirectory && hasExpandedDirectory) return "mixed";
+  }
+
+  if (hasExpandedDirectory) return "expanded";
+  if (hasCollapsedDirectory) return "collapsed";
+  return "empty";
+}
+
+export function setAllDirectoriesExpanded(
+  model: FileTreeExpansionModel,
+  treePaths: readonly string[],
+  directoryPaths: readonly string[],
+  expanded: boolean,
+): void {
+  if (model.isSearchOpen()) return;
+  const snapshot = getFileTreeExpansionSnapshot(model, directoryPaths);
+  if (
+    snapshot === "empty" ||
+    snapshot === "searching" ||
+    (expanded ? snapshot === "expanded" : snapshot === "collapsed")
+  ) {
+    return;
+  }
+
+  model.resetPaths(treePaths, {
+    initialExpandedPaths: expanded ? directoryPaths : [],
+  });
+}

From e487f19d7520a4be228645c9fc56607b22613c95 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Wed, 22 Jul 2026 15:05:37 +0200
Subject: [PATCH 2/3] test(web): cover flattened file tree initialization

---
 apps/web/src/components/files/fileTreeExpansion.test.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/files/fileTreeExpansion.test.ts b/apps/web/src/components/files/fileTreeExpansion.test.ts
index 0493e155c22..9acb605e029 100644
--- a/apps/web/src/components/files/fileTreeExpansion.test.ts
+++ b/apps/web/src/components/files/fileTreeExpansion.test.ts
@@ -81,8 +81,13 @@ describe("file tree expansion controls", () => {
   it("preserves the previous depth-one initial expansion", () => {
     const modelPaths = ["docs/", "docs/guide/", "docs/guide/start.md", "src/", "src/index.ts"];
     const directoryPaths = ["docs/", "src/", "docs/guide/"];
-    const previousModel = new FileTree({ initialExpansion: 1, paths: modelPaths });
+    const previousModel = new FileTree({
+      flattenEmptyDirectories: true,
+      initialExpansion: 1,
+      paths: modelPaths,
+    });
     const batchedModel = new FileTree({
+      flattenEmptyDirectories: true,
       initialExpandedPaths: initiallyExpandedDirectoryPaths(directoryPaths),
       initialExpansion: "closed",
       paths: modelPaths,

From dca78bff89c6590585c590508f6355cb1aa23155 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Wed, 22 Jul 2026 16:49:10 +0200
Subject: [PATCH 3/3] refactor(web): use one file tree expansion toggle

---
 .../src/components/files/FileBrowserPanel.tsx | 33 +++++++------------
 .../files/fileTreeExpansion.test.ts           | 29 ++++++++++++++--
 .../src/components/files/fileTreeExpansion.ts | 14 ++++++++
 3 files changed, 52 insertions(+), 24 deletions(-)

diff --git a/apps/web/src/components/files/FileBrowserPanel.tsx b/apps/web/src/components/files/FileBrowserPanel.tsx
index 3e1b8a1d393..eef5d872cc5 100644
--- a/apps/web/src/components/files/FileBrowserPanel.tsx
+++ b/apps/web/src/components/files/FileBrowserPanel.tsx
@@ -18,9 +18,8 @@ import { T3_PIERRE_ICONS } from "~/pierre-icons";
 
 import { createFileTreeDragMentionController } from "./fileTreeDragMention";
 import {
-  COLLAPSE_ALL_FOLDERS_LABEL,
   directoryTreePaths,
-  EXPAND_ALL_FOLDERS_LABEL,
+  getFileTreeExpansionToggle,
   getFileTreeExpansionSnapshot,
   initiallyExpandedDirectoryPaths,
   setAllDirectoriesExpanded,
@@ -200,12 +199,7 @@ export default function FileBrowserPanel({
   );
   const expansionControlsDisabled =
     expansionSnapshot === "empty" || expansionSnapshot === "searching";
-  const canCollapseAll =
-    !expansionControlsDisabled &&
-    (expansionSnapshot === "expanded" || expansionSnapshot === "mixed");
-  const canExpandAll =
-    !expansionControlsDisabled &&
-    (expansionSnapshot === "collapsed" || expansionSnapshot === "mixed");
+  const expansionToggle = getFileTreeExpansionToggle(expansionSnapshot);
 
   useEffect(() => {
     if (previousTreePathsRef.current === treePaths) return;
@@ -267,20 +261,17 @@ export default function FileBrowserPanel({
         <button
           type="button"
           className="rounded-md p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
-          aria-label={COLLAPSE_ALL_FOLDERS_LABEL}
-          disabled={!canCollapseAll}
-          onClick={() => setAllDirectoriesExpanded(model, treePaths, directoryPaths, false)}
+          aria-label={expansionToggle.label}
+          disabled={expansionControlsDisabled}
+          onClick={() =>
+            setAllDirectoriesExpanded(model, treePaths, directoryPaths, expansionToggle.expanded)
+          }
         >
-          <ChevronsDownUp className="size-3.5" />
-        </button>
-        <button
-          type="button"
-          className="rounded-md p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
-          aria-label={EXPAND_ALL_FOLDERS_LABEL}
-          disabled={!canExpandAll}
-          onClick={() => setAllDirectoriesExpanded(model, treePaths, directoryPaths, true)}
-        >
-          <ChevronsUpDown className="size-3.5" />
+          {expansionToggle.expanded ? (
+            <ChevronsUpDown className="size-3.5" />
+          ) : (
+            <ChevronsDownUp className="size-3.5" />
+          )}
         </button>
         <button
           type="button"
diff --git a/apps/web/src/components/files/fileTreeExpansion.test.ts b/apps/web/src/components/files/fileTreeExpansion.test.ts
index 9acb605e029..2a027bdbc6a 100644
--- a/apps/web/src/components/files/fileTreeExpansion.test.ts
+++ b/apps/web/src/components/files/fileTreeExpansion.test.ts
@@ -6,9 +6,11 @@ import {
   COLLAPSE_ALL_FOLDERS_LABEL,
   directoryTreePaths,
   EXPAND_ALL_FOLDERS_LABEL,
+  getFileTreeExpansionToggle,
   getFileTreeExpansionSnapshot,
   initiallyExpandedDirectoryPaths,
   setAllDirectoriesExpanded,
+  TOGGLE_ALL_FOLDERS_LABEL,
 } from "./fileTreeExpansion.ts";
 
 function makeModel(expansionByPath: Record<string, boolean>, searching = false) {
@@ -103,12 +105,33 @@ describe("file tree expansion controls", () => {
     }
   });
 
-  it("reports an empty tree and uses explicit accessible labels", () => {
+  it("reports an empty tree and gives the toggle an explicit accessible label", () => {
     const { model } = makeModel({});
 
     expect(getFileTreeExpansionSnapshot(model, [])).toBe("empty");
-    expect(COLLAPSE_ALL_FOLDERS_LABEL).toBe("Collapse all folders");
-    expect(EXPAND_ALL_FOLDERS_LABEL).toBe("Expand all folders");
+    expect(getFileTreeExpansionToggle("empty")).toEqual({
+      expanded: false,
+      label: TOGGLE_ALL_FOLDERS_LABEL,
+    });
+    expect(getFileTreeExpansionToggle("searching")).toEqual({
+      expanded: false,
+      label: TOGGLE_ALL_FOLDERS_LABEL,
+    });
+  });
+
+  it("toggles toward the opposite uniform expansion state", () => {
+    expect(getFileTreeExpansionToggle("collapsed")).toEqual({
+      expanded: true,
+      label: EXPAND_ALL_FOLDERS_LABEL,
+    });
+    expect(getFileTreeExpansionToggle("expanded")).toEqual({
+      expanded: false,
+      label: COLLAPSE_ALL_FOLDERS_LABEL,
+    });
+    expect(getFileTreeExpansionToggle("mixed")).toEqual({
+      expanded: false,
+      label: COLLAPSE_ALL_FOLDERS_LABEL,
+    });
   });
 
   it("expands only collapsed directories", () => {
diff --git a/apps/web/src/components/files/fileTreeExpansion.ts b/apps/web/src/components/files/fileTreeExpansion.ts
index babfe626db7..82a5fac3ebe 100644
--- a/apps/web/src/components/files/fileTreeExpansion.ts
+++ b/apps/web/src/components/files/fileTreeExpansion.ts
@@ -2,6 +2,7 @@ import type { ProjectEntry } from "@t3tools/contracts";
 
 export const COLLAPSE_ALL_FOLDERS_LABEL = "Collapse all folders";
 export const EXPAND_ALL_FOLDERS_LABEL = "Expand all folders";
+export const TOGGLE_ALL_FOLDERS_LABEL = "Expand or collapse all folders";
 
 interface FileTreeExpansionDirectoryItem {
   collapse(): void;
@@ -24,6 +25,19 @@ interface FileTreeExpansionModel {
 
 export type FileTreeExpansionSnapshot = "collapsed" | "empty" | "expanded" | "mixed" | "searching";
 
+export function getFileTreeExpansionToggle(snapshot: FileTreeExpansionSnapshot): {
+  expanded: boolean;
+  label: string;
+} {
+  if (snapshot === "collapsed") {
+    return { expanded: true, label: EXPAND_ALL_FOLDERS_LABEL };
+  }
+  if (snapshot === "expanded" || snapshot === "mixed") {
+    return { expanded: false, label: COLLAPSE_ALL_FOLDERS_LABEL };
+  }
+  return { expanded: false, label: TOGGLE_ALL_FOLDERS_LABEL };
+}
+
 function isDirectoryItem(
   item: FileTreeExpansionItem | null,
 ): item is FileTreeExpansionDirectoryItem {