xtralab 0.15.0 → 0.15.1

package/lib/fileBrowser/fileBrowser.js

@@ -10,55 +10,28 @@ import { buildIgnoredEntries, loadGitignoreMatcher } from './gitignore';
 import { loadGitStatusEntries } from './gitStatus';
 import { FILE_BROWSER_ICONS } from './icons';
 /**
- * Polling cadence for the git status decoration. Out-of-band changes (a
- * terminal `git add`, a `git pull`, a file edited outside the JupyterLab
- * editor) become visible within this interval without a manual refresh.
- * Aligned with the git panel's own polling so both views update on the
- * same rhythm.
+ * Git status poll cadence, aligned with the git panel's polling so both
+ * views update on the same rhythm.
  */
 const GIT_STATUS_POLL_INTERVAL_MS = 5000;
-/**
- * Upper bound on the git status poll's exponential backoff. Matches the
- * other polls in the plugin so behavior is consistent across views.
- */
 const GIT_STATUS_POLL_MAX_MS = 300000;
 /**
- * Auto-refresh cadence for the file listing itself. Matches the default
- * JupyterLab file browser (`DEFAULT_REFRESH_INTERVAL` in
- * `@jupyterlab/filebrowser`) so the tree picks up files created outside
- * JupyterLab (terminal commands, external editors, `git pull`, …) within
- * the same window as the stock browser.
+ * Listing auto-refresh cadence; matches the default file browser's
+ * `DEFAULT_REFRESH_INTERVAL` for picking up out-of-band file changes.
  */
 const FILE_LISTING_REFRESH_INTERVAL_MS = 10000;
-/**
- * Upper bound on the auto-refresh backoff when polls fail repeatedly.
- * Matches the default file browser's `max: 300 * 1000` — five minutes is
- * long enough that a server-side outage stops hammering the API, but
- * short enough that a transient failure heals on its own.
- */
 const FILE_LISTING_REFRESH_MAX_MS = 300000;
 /**
- * Server-relative repository path used for `/git/*` calls. Empty string
- * means "use the JupyterLab server's root and let git resolve the
- * enclosing repo" — same convention as the git panel and the launcher
- * dashboard.
+ * Repo path for `/git/*` calls; empty means the server root, letting git
+ * resolve the enclosing repo (same convention as the git panel).
  */
 const GIT_REPO_PATH = '';
-/**
- * The custom-element tag used by `@pierre/trees` for its shadow host. Kept
- * as a constant rather than imported so we don't pay the `@pierre/trees`
- * resolution cost just for one string.
- */
 const FILE_TREE_TAG = 'file-tree-container';
 /**
- * Injected into the tree's shadow root. The second rule hides the search
- * box unless the host carries the visibility marker set by the filter
- * bridge effect below — `@pierre/trees` always renders the box when
- * `search` is enabled, and its stylesheet lives in the shadow root where
- * outside CSS cannot reach. The third rule restyles the drag-hover row:
- * the library paints it with the selection background, which xtralab
- * maps to a full-strength brand color that is illegible without the
- * inverted selection foreground — hence the quieter ring.
+ * Injected into the tree's shadow root, where outside CSS cannot reach.
+ * The search box is hidden unless the host carries the filter-bridge marker
+ * (the library always renders it), and the drag-hover row gets a quiet ring
+ * — the library's selection background is illegible with xtralab's colors.
  */
 const FILE_TREE_UNSAFE_CSS = '[data-type="item"][data-item-selected="true"] ' +
     '[data-item-section="spacing-item"] {' +
@@ -73,13 +46,9 @@ const FILE_TREE_UNSAFE_CSS = '[data-type="item"][data-item-selected="true"] ' +
     'box-shadow: inset 0 0 0 2px var(--trees-accent);' +
     '}';
 /**
- * Renders a `@pierre/trees` file tree backed by the Jupyter contents API.
- *
- * The Jupyter contents API only returns one directory level per request, so
- * the tree is populated lazily: the root is fetched on mount, and each
- * directory is fetched the first time the user expands it. Expansion is
- * detected by subscribing to the model and diffing against an in-memory load
- * state map.
+ * A `@pierre/trees` file tree backed by the Jupyter contents API. The API
+ * returns one directory level per request, so directories load lazily on
+ * first expand, detected by diffing the model against a load-state map.
  */
 export function FileBrowserComponent(props) {
     const { contentsManager, docManager, onOpenFile, translator, widget } = props;
@@ -96,25 +65,16 @@ export function FileBrowserComponent(props) {
     });
     React.useEffect(() => {
         const knownDirs = new Map();
-        // Mirror of the canonical paths currently loaded into the tree. Kept in
-        // sync with `model.resetPaths`/`model.batch`/`model.add` so we can
-        // re-test every loaded path against the gitignore matcher whenever
-        // either side changes — the model itself does not expose a
-        // path-iteration API.
+        // Mirror of the loaded canonical paths — the model has no path-iteration
+        // API, and the gitignore matcher must re-test every loaded path.
         const loadedPaths = new Set();
         let gitignoreMatcher = null;
         let gitStatusEntries = [];
         let cancelled = false;
         /**
-         * Recompute the combined `GitStatusEntry` list from the current
-         * gitignore matcher and the latest porcelain status, then push it into
-         * the tree. Safe to call at any time: empty inputs result in an empty
-         * payload, which clears any statuses applied previously.
-         *
-         * Ignored entries go first so the porcelain entries win in the
-         * unlikely event of overlap (a tracked path that also matches a
-         * `.gitignore` rule). `@pierre/trees` lets later entries overwrite
-         * earlier ones in its internal `statusByPath` map.
+         * Push the combined gitignore + porcelain entries into the tree.
+         * Ignored entries go first so porcelain entries win on overlap —
+         * `@pierre/trees` lets later entries overwrite earlier ones.
          */
         const syncGitStatus = () => {
             const entries = [];
@@ -128,12 +88,6 @@ export function FileBrowserComponent(props) {
             }
             model.setGitStatus(entries);
         };
-        /**
-         * Reload the workspace `.gitignore`, then re-apply the resulting
-         * ignored statuses. Called on initial mount and whenever the user
-         * triggers a refresh — the file may have been edited or created in
-         * between.
-         */
         const refreshGitignoreMatcher = async () => {
             let next = null;
             try {
@@ -148,12 +102,6 @@ export function FileBrowserComponent(props) {
             gitignoreMatcher = next;
             syncGitStatus();
         };
-        /**
-         * Refresh the porcelain-derived git status entries and re-apply them
-         * to the tree. Runs on mount, on every refresh, and on a periodic
-         * poll so out-of-band changes (terminal `git add`, file edits saved
-         * outside the editor, …) become visible without explicit user action.
-         */
         const refreshGitStatus = async () => {
             const next = await loadGitStatusEntries(GIT_REPO_PATH);
             if (cancelled) {
@@ -182,21 +130,16 @@ export function FileBrowserComponent(props) {
                     }
                 }
                 else {
-                    // Filter out paths already in the model. The path-store throws
-                    // when an explicit directory is added a second time, so any
-                    // entry created out-of-band (e.g. by the "new folder" command's
-                    // `notifyPathAdded` callback) must be skipped here.
+                    // The path-store throws when a path is added twice, and entries
+                    // can arrive out-of-band (e.g. `notifyPathAdded`), so skip those.
                     const operations = paths
                         .filter(path => model.getItem(path) === null)
                         .map(path => ({ type: 'add', path }));
                     if (operations.length > 0) {
                         model.batch(operations);
                     }
-                    // Mirror every directory child into `loadedPaths` regardless of
-                    // whether it was just added or skipped above — paths skipped by
-                    // the filter are already in the model from a prior add and so
-                    // belong in the mirror too. `Set.add` is idempotent, so the
-                    // duplicate adds are a no-op.
+                    // Paths skipped above are already in the model from a prior add,
+                    // so they belong in the mirror too.
                     for (const path of paths) {
                         loadedPaths.add(path);
                     }
@@ -215,10 +158,8 @@ export function FileBrowserComponent(props) {
             }
         };
         /**
-         * Refresh every directory currently loaded into the tree. Walks down
-         * from the root through the previously-expanded subdirectories so the
-         * tree state mirrors what's on disk while preserving the user's
-         * expansion state.
+         * Re-fetch the root and every previously-expanded directory so the tree
+         * mirrors the disk while preserving the user's expansion state.
          */
         const refreshAll = async () => {
             const expandedPaths = new Set();
@@ -251,9 +192,8 @@ export function FileBrowserComponent(props) {
                 return;
             }
             const allPaths = [...rootPaths];
-            // BFS through the previously-expanded subtree, fetching only the
-            // directories the user had opened so the refresh doesn't walk the
-            // entire workspace.
+            // Fetch only the previously-expanded subtree so the refresh doesn't
+            // walk the entire workspace.
             const subdirsByParent = new Map();
             subdirsByParent.set(ROOT_LOAD_KEY, rootSubdirs);
             const queue = rootSubdirs.filter(s => expandedPaths.has(s));
@@ -277,8 +217,6 @@ export function FileBrowserComponent(props) {
                     console.error(`xtralab: refresh failed for "${dir}"`, err);
                 }
             }
-            // Reset the tree contents and restore the load-state map so future
-            // expansions know which directories still need fetching.
             model.resetPaths(allPaths);
             loadedPaths.clear();
             for (const path of allPaths) {
@@ -290,18 +228,10 @@ export function FileBrowserComponent(props) {
                     knownDirs.set(subdir, expandedPaths.has(subdir) ? 'loaded' : 'unloaded');
                 }
             });
-            // Refresh the `.gitignore` matcher in case the file was edited
-            // since the last load, then re-apply the resulting statuses to the
-            // newly-loaded paths. The reload runs in parallel with the rest of
-            // the refresh — `refreshGitignoreMatcher` calls `syncGitStatus`
-            // itself when it completes. The porcelain status is also re-fetched
-            // here so a user-triggered refresh picks up out-of-band git changes
-            // immediately instead of waiting for the next poll tick.
+            // Each re-applies the statuses itself when it completes.
             void refreshGitignoreMatcher();
             void refreshGitStatus();
-            // Re-expand the directories that were expanded before the refresh.
-            // We have to do this after `resetPaths` because the reset starts
-            // every directory in its initial collapsed state.
+            // `resetPaths` starts every directory collapsed, so re-expand after it.
             for (const path of expandedPaths) {
                 const item = model.getItem(path);
                 if (item !== null && item.isDirectory()) {
@@ -310,20 +240,10 @@ export function FileBrowserComponent(props) {
             }
         };
         /**
-         * Auto-refresh tick: walk every directory currently loaded into the
-         * tree, fetch its children, and apply the per-directory diff as a
-         * single batched mutation. Unlike {@link refreshAll} this never calls
-         * `model.resetPaths`, so the user's expansion, selection, and scroll
-         * state survive every poll. Mirrors what the default JupyterLab file
-         * browser does for its single-directory view.
-         *
-         * A failed fetch for a single directory is treated as transient and
-         * is skipped without touching that directory's children — they may
-         * still be valid even if this one fetch lost the race with a server
-         * restart. A deleted directory eventually surfaces through its
-         * parent's diff: when the parent is re-fetched and no longer lists
-         * the missing child, the child is removed recursively from the tree
-         * and from the load-state tracking maps.
+         * Auto-refresh tick: diff every loaded directory and apply batched
+         * mutations without `resetPaths`, so expansion, selection, and scroll
+         * state survive. A failed fetch is skipped as transient; a deleted
+         * directory surfaces through its parent's diff and is removed recursively.
          */
         const quietRefresh = async () => {
             if (cancelled) {
@@ -343,10 +263,8 @@ export function FileBrowserComponent(props) {
                 if (cancelled) {
                     return;
                 }
-                // Skip directories that were removed from `knownDirs` while we
-                // were processing an earlier sibling — the cascade cleanup below
-                // can prune deep subtrees, so a path captured at the start of
-                // the tick may already be gone.
+                // The cascade cleanup below can prune subtrees mid-tick, so a dir
+                // captured at the start may already be gone.
                 if (knownDirs.get(dir) !== 'loaded') {
                     continue;
                 }
@@ -373,8 +291,6 @@ export function FileBrowserComponent(props) {
                     if (newChildren.has(lp)) {
                         continue;
                     }
-                    // Disappeared since the last tick. Remove recursively so any
-                    // descendants that were also being tracked go with it.
                     ops.push({ type: 'remove', path: lp, recursive: true });
                     removals.push(lp);
                     if (lp.endsWith('/')) {
@@ -394,15 +310,12 @@ export function FileBrowserComponent(props) {
                     }
                     catch (err) {
                         console.error(`xtralab: auto-refresh batch failed for "${dir}"`, err);
-                        // Leave the bookkeeping mirrors untouched so the next tick
-                        // sees the same starting state and tries again.
+                        // Leave the mirrors untouched so the next tick retries.
                         continue;
                     }
                     mutated = true;
-                    // Apply the matching mirror updates only after the batch lands
-                    // in the model. The cascade cleanup below mirrors the
-                    // `recursive: true` removal semantics so descendants we were
-                    // tracking don't linger in `loadedPaths` or `knownDirs`.
+                    // Mirror updates only after the batch lands; the cascade below
+                    // mirrors the `recursive: true` removal semantics.
                     for (const r of removals) {
                         loadedPaths.delete(r);
                     }
@@ -431,8 +344,7 @@ export function FileBrowserComponent(props) {
                         loadedPaths.add(a);
                     }
                 }
-                // Register newly-observed subdirectories so the next user expand
-                // triggers a fetch instead of being ignored.
+                // Untracked subdirectories would ignore their first expand.
                 for (const subdir of fetched.subdirectories) {
                     if (!knownDirs.has(subdir)) {
                         knownDirs.set(subdir, 'unloaded');
@@ -444,24 +356,8 @@ export function FileBrowserComponent(props) {
             }
         };
         /**
-         * Reveal {@link canonicalPath} in the tree: load any unloaded
-         * ancestor directories, expand them, and select the target so it is
-         * scrolled into view. Tolerant of partially-loaded state so the
-         * editor breadcrumbs can call it on any path at any time without
-         * caring about what the tree has already fetched.
-         *
-         * Each ancestor is awaited *before* it is expanded — expanding a
-         * directory triggers the model's subscribe callback, which
-         * synchronously sets the directory's load state to `loading` and
-         * kicks off its own fetch in parallel. Awaiting that in-flight
-         * fetch would return immediately on the second await, leaving the
-         * children unloaded when we move to the next iteration.
-         */
-        /**
-         * Clear the tree selection and scroll back to the top. Invoked by
-         * the file browser widget's `scrollToRoot` method when the home
-         * crumb is clicked; gives that gesture visible feedback even when
-         * the sidebar is already focused on the file browser.
+         * Clear the selection and scroll to the top; gives the home-crumb
+         * gesture visible feedback even when the sidebar is already focused.
          */
         const goToRoot = () => {
             var _a;
@@ -476,13 +372,6 @@ export function FileBrowserComponent(props) {
                 container.scrollTop = 0;
             }
         };
-        /**
-         * Collapse every currently expanded directory in the tree. Walks the
-         * `knownDirs` map (the canonical record of which directories have been
-         * observed in the tree) and calls `.collapse()` on each loaded
-         * directory whose handle reports `isExpanded()`. Unloaded directories
-         * are not expanded by definition, so they're skipped.
-         */
         const collapseAll = () => {
             if (cancelled) {
                 return;
@@ -501,6 +390,12 @@ export function FileBrowserComponent(props) {
                 }
             });
         };
+        /**
+         * Reveal `canonicalPath`: fetch and expand ancestors, then select and
+         * scroll to the target. Each ancestor is fetched *before* expanding —
+         * expansion starts the subscribe callback's own fetch, and awaiting that
+         * in-flight fetch resolves with the children still unloaded.
+         */
         const revealPath = async (canonicalPath) => {
             if (cancelled || canonicalPath.length === 0) {
                 return;
@@ -511,9 +406,7 @@ export function FileBrowserComponent(props) {
             if (segments.length === 0) {
                 return;
             }
-            // Build the ordered list of ancestor directory canonical paths.
-            // For "foo/bar/baz.txt" → ["foo/", "foo/bar/"].
-            // For "foo/bar/"       → ["foo/"].
+            // "foo/bar/baz.txt" → ["foo/", "foo/bar/"].
             const ancestors = [];
             let cumulative = '';
             for (let i = 0; i < segments.length - 1; i++) {
@@ -560,15 +453,13 @@ export function FileBrowserComponent(props) {
                 previous === null || previous === void 0 ? void 0 : previous.deselect();
             }
             target.select();
-            // `select` highlights the row; `scrollToPath` focuses it and scrolls it
-            // to the middle of the viewport, even when the row is virtualized out of
-            // the rendered window.
+            // `scrollToPath` focuses and scrolls even when the row is virtualized
+            // out of the rendered window.
             model.scrollToPath(canonicalPath, { focus: true, offset: 'center' });
         };
         /**
-         * Insert a newly-created path (typically from "new folder" or
-         * "duplicate") into the tree without doing a full refresh. Expands
-         * the parent so the user sees the newly created entry immediately.
+         * Insert a newly-created path without a full refresh and expand its
+         * parent so the entry is visible immediately.
          */
         const handlePathAdded = (canonicalPath) => {
             if (model.getItem(canonicalPath) === null) {
@@ -582,9 +473,8 @@ export function FileBrowserComponent(props) {
             }
             loadedPaths.add(canonicalPath);
             if (canonicalPath.endsWith('/') && !knownDirs.has(canonicalPath)) {
-                // The new directory has no children yet, so mark it as already
-                // loaded — there's nothing to fetch and we don't want a stale
-                // "unloaded" entry to trigger a fetch on the next expand.
+                // A new directory has no children; mark it loaded so a stale
+                // "unloaded" entry doesn't trigger a fetch on the next expand.
                 knownDirs.set(canonicalPath, 'loaded');
             }
             syncGitStatus();
@@ -685,10 +575,6 @@ export function FileBrowserComponent(props) {
                 }
             }
         };
-        /**
-         * The tree refused the drop and left its model untouched — almost
-         * always a name collision at the destination.
-         */
         const failedDrop = (error, context) => {
             if (cancelled) {
                 return;
@@ -744,13 +630,8 @@ export function FileBrowserComponent(props) {
             },
             standby: 'when-hidden'
         });
-        // Auto-refresh the file listing on the same cadence as the default
-        // JupyterLab file browser. Backoff on failures so a server-side
-        // outage doesn't hammer the API, and stand by when the tab is
-        // hidden so we don't run the polling loop while the user is in
-        // another tab. `auto: false` keeps the first tick from racing the
-        // initial `fetchDirectory(ROOT_LOAD_KEY)` above — the poll is
-        // started explicitly once the initial load is in flight.
+        // `auto: false` keeps the first tick from racing the initial root
+        // fetch above; the poll is started explicitly below.
         const listingPoll = new Poll({
             auto: false,
             name: '@xtralab/fileBrowser:listing',
@@ -763,26 +644,16 @@ export function FileBrowserComponent(props) {
             standby: 'when-hidden'
         });
         void listingPoll.start();
-        // Surface contents changes that happen inside JupyterLab (file save,
-        // rename, delete) without waiting for the next poll tick. The
-        // default file browser uses the same `fileChanged` signal for the
-        // same reason. We can't tell from the signal alone whether the
-        // change affects a path we're showing, so we just nudge the poll —
-        // it diffs the loaded directories and emits no batch ops when
-        // nothing relevant changed.
+        // In-app contents changes (save, rename, delete) nudge the poll; the
+        // signal doesn't say whether a shown path is affected, the diff does.
         const onContentsFileChanged = () => {
             void listingPoll.refresh();
         };
         contentsManager.fileChanged.connect(onContentsFileChanged);
         const unsubscribe = model.subscribe(() => {
-            // Search-driven expansion must not trigger fetches: the tree
-            // auto-expands every directory whose path matches the query, and
-            // treating those as user expansions would recursively fetch every
-            // matching subtree — a single common letter can walk the whole
-            // workspace, node_modules included. Closing the search restores
-            // the pre-search expansion state, and a directory clicked in the
-            // results is toggled after the session closes, so real expansions
-            // are still fetched the moment the session ends.
+            // Search auto-expands every matching directory — fetching those would
+            // walk whole subtrees (node_modules included); real expansions still
+            // fetch once the search session closes.
             if (model.isSearchOpen()) {
                 return;
             }
@@ -854,11 +725,8 @@ export function FileBrowserComponent(props) {
             }
         };
     }, [model, contentsManager, widget, docManager, trans]);
-    // Bridge the tree's selection state up to the widget so command handlers
-    // can read it without depending on React internals. The tree exposes its
-    // selection through `getSelectedPaths()` and emits a generic notification
-    // through `subscribe`, so we diff against a snapshot to avoid spamming the
-    // widget on every unrelated mutation.
+    // Bridge the tree selection up to the widget. `subscribe` fires on every
+    // mutation, so diff against a snapshot before notifying.
     React.useEffect(() => {
         if (widget === undefined) {
             return;
@@ -879,13 +747,9 @@ export function FileBrowserComponent(props) {
             unsubscribe();
         };
     }, [model, widget]);
-    // Bridge the filter-box visibility between the widget and the tree. The
-    // widget owns the flag; applying it stamps the marker attribute the
-    // unsafeCSS rule keys on and opens or closes the model's search session
-    // (opening focuses the input, closing clears any active filter). The
-    // model subscription covers the reverse direction: typing a printable
-    // character while the tree has focus opens a session on the tree's own
-    // initiative, and the box must surface for that session to be usable.
+    // Applying the widget's filter flag stamps the marker the unsafeCSS rule
+    // keys on and syncs the search session; the subscription surfaces the box
+    // when the tree opens a session itself (typing while focused).
     React.useEffect(() => {
         if (widget === undefined) {
             return;
@@ -952,21 +816,9 @@ export function FileBrowserComponent(props) {
             wrapper.removeEventListener('dblclick', handleDoubleClick);
         };
     }, [onOpenFile]);
-    // Bridge contextmenu events out of the `<file-tree-container>` shadow DOM.
-    //
-    // `@pierre/trees` mounts the tree under an open shadow root attached to the
-    // `<file-tree-container>` custom element. When the user right-clicks a row
-    // inside the shadow tree, the event is retargeted to the host element when
-    // observed from the light DOM, and `app.contextMenu` walks via
-    // `parentElement` — it never enters the shadow tree, so the `[data-type=
-    // "item"]` selectors registered in `schema/plugin.json` never match.
-    //
-    // We listen in the capture phase (so we run before the application's
-    // document-level handler) and copy the right-clicked row's data attributes
-    // onto the host. Lumino then matches the host as if it were the row, and
-    // `app.contextMenuHitTest` from command handlers reads the same attributes
-    // back to recover the path. When the right-click misses any row we clear
-    // the attributes so empty-area clicks don't show stale per-item entries.
+    // Lumino never enters the tree's shadow DOM, so the `[data-type="item"]`
+    // selectors can't match rows; mirror the right-clicked row's data
+    // attributes onto the host (capture phase, cleared on a miss).
     React.useEffect(() => {
         const wrapper = wrapperRef.current;
         if (wrapper === null) {

package/lib/fileBrowser/gitStatus.d.ts

@@ -1,13 +1,8 @@
 import type { GitStatusEntry } from '@pierre/trees';
 /**
- * Fetch the porcelain status for `repoPath` and convert it into a flat list
- * of `GitStatusEntry` values consumable by `FileTree.setGitStatus`. Returns
- * an empty array when the path is not in a git repo, the request fails, or
- * the server reports a non-zero exit — the file browser must still work
- * without git, so any error here is a no-op rather than a thrown exception.
- *
- * Files that have both a staged and an unstaged change are collapsed into a
- * single entry: the unstaged status wins because that mirrors what is
- * actually different on disk and matches VS Code's tree decoration behavior.
+ * Fetch the porcelain status for `repoPath` as `GitStatusEntry` values.
+ * Any failure yields an empty array — the file browser must work without
+ * git. A file both staged and unstaged gets one entry, the unstaged status
+ * winning (mirrors what is on disk, matching VS Code).
  */
 export declare function loadGitStatusEntries(repoPath: string): Promise<GitStatusEntry[]>;

package/lib/fileBrowser/gitStatus.js

@@ -1,10 +1,8 @@
 import { expandStatusFiles, status } from '../git/api';
 /**
- * Translate a `jupyterlab_git` porcelain status into the closest
- * `@pierre/trees` `GitStatus` enum value. The tree library only supports the
- * six common statuses (added, deleted, ignored, modified, renamed, untracked)
- * so the rare ones (unmerged, typechange, unknown) collapse onto `modified`
- * — they all denote a pending change the user should see decorated.
+ * Translate a `jupyterlab_git` porcelain status into a `@pierre/trees`
+ * `GitStatus`. The tree only supports the six common statuses, so the rare
+ * ones (unmerged, typechange, unknown) collapse onto `modified`.
  */
 function toTreeStatus(value) {
     switch (value) {
@@ -22,15 +20,10 @@ function toTreeStatus(value) {
     }
 }
 /**
- * Fetch the porcelain status for `repoPath` and convert it into a flat list
- * of `GitStatusEntry` values consumable by `FileTree.setGitStatus`. Returns
- * an empty array when the path is not in a git repo, the request fails, or
- * the server reports a non-zero exit — the file browser must still work
- * without git, so any error here is a no-op rather than a thrown exception.
- *
- * Files that have both a staged and an unstaged change are collapsed into a
- * single entry: the unstaged status wins because that mirrors what is
- * actually different on disk and matches VS Code's tree decoration behavior.
+ * Fetch the porcelain status for `repoPath` as `GitStatusEntry` values.
+ * Any failure yields an empty array — the file browser must work without
+ * git. A file both staged and unstaged gets one entry, the unstaged status
+ * winning (mirrors what is on disk, matching VS Code).
  */
 export async function loadGitStatusEntries(repoPath) {
     try {
@@ -39,9 +32,6 @@ export async function loadGitStatusEntries(repoPath) {
             return [];
         }
         const changes = expandStatusFiles(result.files);
-        // Collapse staged + unstaged into one decoration per file. Prefer the
-        // unstaged group when both exist; otherwise keep whichever group is
-        // present.
         const byPath = new Map();
         for (const change of changes) {
             if (change.group === 'unstaged' || !byPath.has(change.path)) {

package/lib/fileBrowser/gitignore.d.ts

@@ -8,22 +8,9 @@ import type { GitStatusEntry } from '@pierre/trees';
  */
 export declare function loadGitignoreMatcher(contentsManager: Contents.IManager): Promise<Ignore | null>;
 /**
- * Build `GitStatusEntry`s for the canonical paths that match the given
- * gitignore matcher.
- *
- * `@pierre/trees` propagates the `ignored` style from a directory entry
- * down to every descendant via its internal `ignoredDirectoryPaths` set, so
- * we only emit one entry per ignored subtree root: emitting descendants
- * would also pollute the library's `directoriesWithChanges` set, causing
- * parent directories of nested ignored items to render a "contains git
- * status items" dot.
- *
- * Paths are sorted lexicographically so a directory always precedes its
- * descendants, allowing a simple ancestor-suppression check via
- * `path.startsWith(dir)`. The trailing slash on canonical directory paths
- * (required by `@pierre/trees`, also recognized by `ignore` as the
- * "directory" indicator) keeps the prefix check from accidentally matching
- * sibling paths that happen to share a name prefix (e.g. `node_modules_old`
- * vs `node_modules/`).
+ * One `GitStatusEntry` per ignored subtree root: descendant entries would
+ * pollute the tree's `directoriesWithChanges` set (bogus dots on parents),
+ * and `ignored` already propagates downward. The trailing slash on directory
+ * paths keeps the sorted `startsWith` ancestor check off name-prefix siblings.
  */
 export declare function buildIgnoredEntries(matcher: Ignore, canonicalPaths: Iterable<string>): GitStatusEntry[];