xtralab 0.3.0 → 0.5.0

package/lib/fileBrowser/fileBrowser.js

@@ -2,9 +2,11 @@ import * as React from 'react';
 import { fileIcon } from '@jupyterlab/ui-components';
 import { MimeData, PromiseDelegate } from '@lumino/coreutils';
 import { Drag } from '@lumino/dragdrop';
+import { Poll } from '@lumino/polling';
 import { FileTree, useFileTree } from '@pierre/trees/react';
 import { ROOT_LOAD_KEY, listDirectory, toServerPath } from './contents';
 import { buildIgnoredEntries, loadGitignoreMatcher } from './gitignore';
+import { loadGitStatusEntries } from './gitStatus';
 import { FILE_BROWSER_ICONS } from './icons';
 /**
  * MIME types used by the dock panel and other JupyterLab drop targets.
@@ -21,6 +23,41 @@ const CONTENTS_MIME = 'application/x-jupyter-icontents';
  * than a click. Matches the value used by the default JupyterLab listing.
  */
 const DRAG_THRESHOLD = 5;
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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`
@@ -54,20 +91,29 @@ export function FileBrowserComponent(props) {
         // path-iteration API.
         const loadedPaths = new Set();
         let gitignoreMatcher = null;
+        let gitStatusEntries = [];
         let cancelled = false;
         /**
-         * Recompute the `ignored` git status entries from the current
-         * gitignore matcher and the set of loaded paths, and push them into
-         * the tree. Safe to call at any time: when the matcher is `null`
-         * (no `.gitignore` or it failed to load) we send an empty list, which
-         * also clears any statuses that may have been applied previously.
+         * 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.
          */
         const syncGitStatus = () => {
-            if (gitignoreMatcher === null) {
-                model.setGitStatus([]);
-                return;
+            const entries = [];
+            if (gitignoreMatcher !== null) {
+                for (const entry of buildIgnoredEntries(gitignoreMatcher, loadedPaths)) {
+                    entries.push(entry);
+                }
+            }
+            for (const entry of gitStatusEntries) {
+                entries.push(entry);
             }
-            const entries = buildIgnoredEntries(gitignoreMatcher, loadedPaths);
             model.setGitStatus(entries);
         };
         /**
@@ -90,6 +136,20 @@ 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) {
+                return;
+            }
+            gitStatusEntries = next;
+            syncGitStatus();
+        };
         const fetchDirectory = async (canonicalPath) => {
             const current = knownDirs.get(canonicalPath);
             if (current === 'loading' || current === 'loaded') {
@@ -236,8 +296,11 @@ export function FileBrowserComponent(props) {
             // 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.
+            // 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.
             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.
@@ -248,6 +311,259 @@ 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.
+         */
+        const quietRefresh = async () => {
+            if (cancelled) {
+                return;
+            }
+            const dirsToRefresh = [];
+            knownDirs.forEach((state, path) => {
+                if (state === 'loaded') {
+                    dirsToRefresh.push(path);
+                }
+            });
+            if (dirsToRefresh.length === 0) {
+                return;
+            }
+            let mutated = false;
+            for (const dir of dirsToRefresh) {
+                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.
+                if (knownDirs.get(dir) !== 'loaded') {
+                    continue;
+                }
+                let fetched;
+                try {
+                    fetched = await listDirectory(contentsManager, toServerPath(dir));
+                }
+                catch (err) {
+                    console.warn(`xtralab: auto-refresh skipped "${dir}"`, err);
+                    continue;
+                }
+                if (cancelled) {
+                    return;
+                }
+                const newChildren = new Set(fetched.paths);
+                const ops = [];
+                const additions = [];
+                const removals = [];
+                const directoryRemovals = [];
+                for (const lp of loadedPaths) {
+                    if (parentOf(lp) !== dir) {
+                        continue;
+                    }
+                    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('/')) {
+                        directoryRemovals.push(lp);
+                    }
+                }
+                for (const newChild of fetched.paths) {
+                    if (loadedPaths.has(newChild)) {
+                        continue;
+                    }
+                    ops.push({ type: 'add', path: newChild });
+                    additions.push(newChild);
+                }
+                if (ops.length > 0) {
+                    try {
+                        model.batch(ops);
+                    }
+                    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.
+                        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`.
+                    for (const r of removals) {
+                        loadedPaths.delete(r);
+                    }
+                    for (const removedDir of directoryRemovals) {
+                        knownDirs.delete(removedDir);
+                        const descendantPaths = [];
+                        for (const lp of loadedPaths) {
+                            if (lp.startsWith(removedDir)) {
+                                descendantPaths.push(lp);
+                            }
+                        }
+                        for (const lp of descendantPaths) {
+                            loadedPaths.delete(lp);
+                        }
+                        const descendantDirs = [];
+                        knownDirs.forEach((_, kd) => {
+                            if (kd !== ROOT_LOAD_KEY && kd.startsWith(removedDir)) {
+                                descendantDirs.push(kd);
+                            }
+                        });
+                        for (const kd of descendantDirs) {
+                            knownDirs.delete(kd);
+                        }
+                    }
+                    for (const a of additions) {
+                        loadedPaths.add(a);
+                    }
+                }
+                // Register newly-observed subdirectories so the next user expand
+                // triggers a fetch instead of being ignored.
+                for (const subdir of fetched.subdirectories) {
+                    if (!knownDirs.has(subdir)) {
+                        knownDirs.set(subdir, 'unloaded');
+                    }
+                }
+            }
+            if (mutated) {
+                syncGitStatus();
+            }
+        };
+        /**
+         * 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.
+         */
+        const goToRoot = () => {
+            var _a;
+            if (cancelled) {
+                return;
+            }
+            for (const selected of model.getSelectedPaths()) {
+                (_a = model.getItem(selected)) === null || _a === void 0 ? void 0 : _a.deselect();
+            }
+            const container = model.getFileTreeContainer();
+            if (container !== undefined) {
+                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;
+            }
+            knownDirs.forEach((state, path) => {
+                if (path === ROOT_LOAD_KEY || state !== 'loaded') {
+                    return;
+                }
+                const item = model.getItem(path);
+                if (item === null || !item.isDirectory()) {
+                    return;
+                }
+                const handle = item;
+                if (handle.isExpanded()) {
+                    handle.collapse();
+                }
+            });
+        };
+        const revealPath = async (canonicalPath) => {
+            if (cancelled || canonicalPath.length === 0) {
+                return;
+            }
+            const isDir = canonicalPath.endsWith('/');
+            const trimmed = isDir ? canonicalPath.slice(0, -1) : canonicalPath;
+            const segments = trimmed.split('/').filter(s => s.length > 0);
+            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/"].
+            const ancestors = [];
+            let cumulative = '';
+            for (let i = 0; i < segments.length - 1; i++) {
+                cumulative += `${segments[i]}/`;
+                ancestors.push(cumulative);
+            }
+            await fetchDirectory(ROOT_LOAD_KEY);
+            if (cancelled) {
+                return;
+            }
+            for (const ancestor of ancestors) {
+                await fetchDirectory(ancestor);
+                if (cancelled) {
+                    return;
+                }
+                const item = model.getItem(ancestor);
+                if (item === null || !item.isDirectory()) {
+                    return;
+                }
+                const handle = item;
+                if (!handle.isExpanded()) {
+                    handle.expand();
+                }
+            }
+            if (isDir) {
+                await fetchDirectory(canonicalPath);
+                if (cancelled) {
+                    return;
+                }
+            }
+            const target = model.getItem(canonicalPath);
+            if (target === null) {
+                return;
+            }
+            if (target.isDirectory() &&
+                !target.isExpanded()) {
+                target.expand();
+            }
+            for (const selected of model.getSelectedPaths()) {
+                if (selected === canonicalPath) {
+                    continue;
+                }
+                const previous = model.getItem(selected);
+                previous === null || previous === void 0 ? void 0 : previous.deselect();
+            }
+            target.select();
+            model.focusPath(canonicalPath);
+        };
         /**
          * Insert a newly-created path (typically from "new folder" or
          * "duplicate") into the tree without doing a full refresh. Expands
@@ -287,6 +603,46 @@ export function FileBrowserComponent(props) {
         knownDirs.set(ROOT_LOAD_KEY, 'unloaded');
         void fetchDirectory(ROOT_LOAD_KEY);
         void refreshGitignoreMatcher();
+        const gitStatusPoll = new Poll({
+            name: '@xtralab/fileBrowser:gitStatus',
+            factory: () => refreshGitStatus(),
+            frequency: {
+                interval: GIT_STATUS_POLL_INTERVAL_MS,
+                backoff: true,
+                max: GIT_STATUS_POLL_MAX_MS
+            },
+            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.
+        const listingPoll = new Poll({
+            auto: false,
+            name: '@xtralab/fileBrowser:listing',
+            factory: () => quietRefresh(),
+            frequency: {
+                interval: FILE_LISTING_REFRESH_INTERVAL_MS,
+                backoff: true,
+                max: FILE_LISTING_REFRESH_MAX_MS
+            },
+            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.
+        const onContentsFileChanged = () => {
+            void listingPoll.refresh();
+        };
+        contentsManager.fileChanged.connect(onContentsFileChanged);
         const unsubscribe = model.subscribe(() => {
             knownDirs.forEach((state, canonicalPath) => {
                 if (state !== 'unloaded') {
@@ -305,6 +661,9 @@ export function FileBrowserComponent(props) {
         });
         let refreshSlot;
         let pathAddedSlot;
+        let revealSlot;
+        let rootSlot;
+        let collapseAllSlot;
         if (widget !== undefined) {
             refreshSlot = () => {
                 void refreshAll();
@@ -312,11 +671,26 @@ export function FileBrowserComponent(props) {
             pathAddedSlot = (_sender, path) => {
                 handlePathAdded(path);
             };
+            revealSlot = (_sender, path) => {
+                void revealPath(path);
+            };
+            rootSlot = () => {
+                goToRoot();
+            };
+            collapseAllSlot = () => {
+                collapseAll();
+            };
             widget.refreshRequested.connect(refreshSlot);
             widget.pathAdded.connect(pathAddedSlot);
+            widget.revealRequested.connect(revealSlot);
+            widget.rootRequested.connect(rootSlot);
+            widget.collapseAllRequested.connect(collapseAllSlot);
         }
         return () => {
             cancelled = true;
+            gitStatusPoll.dispose();
+            contentsManager.fileChanged.disconnect(onContentsFileChanged);
+            listingPoll.dispose();
             unsubscribe();
             if (widget !== undefined) {
                 if (refreshSlot !== undefined) {
@@ -325,6 +699,15 @@ export function FileBrowserComponent(props) {
                 if (pathAddedSlot !== undefined) {
                     widget.pathAdded.disconnect(pathAddedSlot);
                 }
+                if (revealSlot !== undefined) {
+                    widget.revealRequested.disconnect(revealSlot);
+                }
+                if (rootSlot !== undefined) {
+                    widget.rootRequested.disconnect(rootSlot);
+                }
+                if (collapseAllSlot !== undefined) {
+                    widget.collapseAllRequested.disconnect(collapseAllSlot);
+                }
             }
         };
     }, [model, contentsManager, widget]);

package/lib/fileBrowser/gitStatus.d.ts

@@ -0,0 +1,13 @@
+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.
+ */
+export declare function loadGitStatusEntries(repoPath: string): Promise<GitStatusEntry[]>;

package/lib/fileBrowser/gitStatus.js

@@ -0,0 +1,60 @@
+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.
+ */
+function toTreeStatus(value) {
+    switch (value) {
+        case 'added':
+        case 'deleted':
+        case 'modified':
+        case 'renamed':
+        case 'untracked':
+            return value;
+        case 'unmerged':
+        case 'typechange':
+        case 'unknown':
+        default:
+            return 'modified';
+    }
+}
+/**
+ * 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.
+ */
+export async function loadGitStatusEntries(repoPath) {
+    try {
+        const result = await status(repoPath);
+        if (result.code !== 0) {
+            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)) {
+                byPath.set(change.path, change.status);
+            }
+        }
+        const entries = [];
+        byPath.forEach((value, path) => {
+            entries.push({ path, status: toTreeStatus(value) });
+        });
+        return entries;
+    }
+    catch (_a) {
+        return [];
+    }
+}

package/lib/fileBrowser/widget.d.ts

@@ -56,6 +56,28 @@ export interface IXtralabFileBrowser {
      * sees the new item without a full refresh.
      */
     readonly pathAdded: ISignal<IXtralabFileBrowser, string>;
+    /**
+     * Emits when an external caller asks the tree to scroll to and select
+     * the given canonical path. The React component listens, lazily loads
+     * any unloaded ancestor directories, expands them, and selects the
+     * target. Used by the editor breadcrumbs to jump back to a file or
+     * folder shown in the breadcrumb trail.
+     */
+    readonly revealRequested: ISignal<IXtralabFileBrowser, string>;
+    /**
+     * Emits when an external caller asks the tree to return to the
+     * workspace root: clear any current selection and scroll back to the
+     * first row. Distinct from {@link revealRequested} because the
+     * workspace root has no tree row of its own — it cannot be reached
+     * by passing a path.
+     */
+    readonly rootRequested: ISignal<IXtralabFileBrowser, void>;
+    /**
+     * Emits when an external caller asks the tree to collapse every
+     * expanded folder. The React component listens and walks the loaded
+     * directories, calling `.collapse()` on each expanded one.
+     */
+    readonly collapseAllRequested: ISignal<IXtralabFileBrowser, void>;
     /** Trigger a refresh of every loaded directory in the tree. */
     refresh(): void;
     /**
@@ -64,6 +86,23 @@ export interface IXtralabFileBrowser {
      * convention: directories carry a trailing slash, files do not.
      */
     notifyPathAdded(canonicalPath: string): void;
+    /**
+     * Ask the tree to reveal {@link canonicalPath}: load and expand any
+     * unloaded ancestor directories, then select and scroll the target
+     * into view. `canonicalPath` follows the `@pierre/trees` convention
+     * (directories carry a trailing slash, files do not). Must be a
+     * non-empty path — use {@link scrollToRoot} for the root gesture.
+     */
+    reveal(canonicalPath: string): void;
+    /**
+     * Ask the tree to return to the workspace root: clear any current
+     * selection and scroll back to the top of the tree.
+     */
+    scrollToRoot(): void;
+    /**
+     * Ask the tree to collapse every currently expanded folder.
+     */
+    collapseAll(): void;
 }
 /**
  * Lumino widget that hosts the React-based `@pierre/trees` file browser.
@@ -78,6 +117,9 @@ export declare class XtralabFileBrowser extends Widget implements IXtralabFileBr
     get selectionChanged(): ISignal<this, readonly string[]>;
     get refreshRequested(): ISignal<this, void>;
     get pathAdded(): ISignal<this, string>;
+    get revealRequested(): ISignal<this, string>;
+    get rootRequested(): ISignal<this, void>;
+    get collapseAllRequested(): ISignal<this, void>;
     /**
      * Update the cached selection. Called from the React tree when the
      * underlying `@pierre/trees` model emits a selection change.
@@ -85,6 +127,9 @@ export declare class XtralabFileBrowser extends Widget implements IXtralabFileBr
     updateSelection(paths: readonly string[]): void;
     refresh(): void;
     notifyPathAdded(canonicalPath: string): void;
+    reveal(canonicalPath: string): void;
+    scrollToRoot(): void;
+    collapseAll(): void;
     private _contentsManager;
     private _docManager;
     private _onOpenFile;
@@ -92,6 +137,9 @@ export declare class XtralabFileBrowser extends Widget implements IXtralabFileBr
     private _selectionChanged;
     private _refreshRequested;
     private _pathAdded;
+    private _revealRequested;
+    private _rootRequested;
+    private _collapseAllRequested;
     private _toolbar;
     private _content;
 }

package/lib/fileBrowser/widget.js

@@ -26,6 +26,9 @@ export class XtralabFileBrowser extends Widget {
         this._selectionChanged = new Signal(this);
         this._refreshRequested = new Signal(this);
         this._pathAdded = new Signal(this);
+        this._revealRequested = new Signal(this);
+        this._rootRequested = new Signal(this);
+        this._collapseAllRequested = new Signal(this);
         const layout = (this.layout = new PanelLayout());
         this._contentsManager = options.contentsManager;
         this._docManager = options.docManager;
@@ -65,6 +68,15 @@ export class XtralabFileBrowser extends Widget {
     get pathAdded() {
         return this._pathAdded;
     }
+    get revealRequested() {
+        return this._revealRequested;
+    }
+    get rootRequested() {
+        return this._rootRequested;
+    }
+    get collapseAllRequested() {
+        return this._collapseAllRequested;
+    }
     /**
      * Update the cached selection. Called from the React tree when the
      * underlying `@pierre/trees` model emits a selection change.
@@ -79,6 +91,18 @@ export class XtralabFileBrowser extends Widget {
     notifyPathAdded(canonicalPath) {
         this._pathAdded.emit(canonicalPath);
     }
+    reveal(canonicalPath) {
+        if (canonicalPath.length === 0) {
+            throw new Error('XtralabFileBrowser.reveal requires a non-empty canonical path; use scrollToRoot for the workspace root.');
+        }
+        this._revealRequested.emit(canonicalPath);
+    }
+    scrollToRoot() {
+        this._rootRequested.emit();
+    }
+    collapseAll() {
+        this._collapseAllRequested.emit();
+    }
 }
 /**
  * The React-rendered region of the file browser. Lives inside the host