xtralab 0.3.0 → 0.4.0

package/lib/git/panelComponent.js

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { Poll } from '@lumino/polling';
 import { add, addAll, checkout, porcelainToFileChanges, reset, resetAll, showTopLevel, status } from './api';
 /**
  * The polling interval for the panel. We refresh the status periodically so
@@ -6,6 +7,13 @@ import { add, addAll, checkout, porcelainToFileChanges, reset, resetAll, showTop
  * visible without requiring a manual refresh.
  */
 const STATUS_POLL_INTERVAL_MS = 5000;
+/**
+ * Upper bound on the poll's exponential backoff when status requests fail
+ * repeatedly. Matches the default JupyterLab file browser's `max`: long
+ * enough that a server outage stops hammering the API, short enough that
+ * a transient failure heals on its own.
+ */
+const STATUS_POLL_MAX_MS = 300000;
 /**
  * Top-level React component rendered inside the {@link GitPanel} widget.
  * Owns the polling + refresh wiring around the `/git/status` endpoint and
@@ -59,23 +67,32 @@ export function GitPanelComponent(props) {
             });
         }
     }, [repoPath]);
-    // Initial load + polling. `refresh` is stable for a given `repoPath`, so
-    // the polling interval is only re-created when the repo path changes.
-    React.useEffect(() => {
-        void refresh();
-        const interval = window.setInterval(() => void refresh(), STATUS_POLL_INTERVAL_MS);
-        return () => {
-            window.clearInterval(interval);
-        };
-    }, [refresh]);
-    // External refresh triggers (toolbar button, plugin-level events).
+    // Initial load + polling. Driven by a Lumino `Poll` so the panel stops
+    // hitting the git endpoint while the JupyterLab tab is hidden, and so
+    // repeated failures back off exponentially instead of spinning at 5s.
+    // External refresh triggers (toolbar button, plugin-level events) call
+    // `poll.refresh()` to schedule an immediate tick instead of running
+    // `refresh()` directly — that keeps the panel from issuing two parallel
+    // status requests when an automatic tick happens to land at the same
+    // time as an external trigger.
     React.useEffect(() => {
+        const poll = new Poll({
+            name: '@xtralab/git:panelStatus',
+            factory: () => refresh(),
+            frequency: {
+                interval: STATUS_POLL_INTERVAL_MS,
+                backoff: true,
+                max: STATUS_POLL_MAX_MS
+            },
+            standby: 'when-hidden'
+        });
         const handler = () => {
-            void refresh();
+            void poll.refresh();
         };
         refreshSignal.connect(handler);
         return () => {
             refreshSignal.disconnect(handler);
+            poll.dispose();
         };
     }, [refresh, refreshSignal]);
     const runAction = React.useCallback(async (change, action, run) => {

package/lib/index.js

@@ -1,4 +1,6 @@
 import fileBrowserPlugin from './fileBrowser';
+import editorBreadcrumbsPlugin from './editorBreadcrumbs';
+import editorIndentPlugin from './editorIndent';
 import gitPlugin from './git';
 import launcherPlugin from './launcher';
 import menusPlugin from './menus';
@@ -12,6 +14,8 @@ import statusBarPlugin from './statusBar';
  * available end up running.
  */
 const plugins = [
+    editorBreadcrumbsPlugin,
+    editorIndentPlugin,
     fileBrowserPlugin,
     gitPlugin,
     launcherPlugin,

package/lib/launcher/dashboard.js

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { Poll } from '@lumino/polling';
 import { LabIcon, ReactWidget, consoleIcon, notebookIcon, refreshIcon, terminalIcon } from '@jupyterlab/ui-components';
 import { expandStatusFiles, status } from '../git/api';
 import { CommandIDs as GitCommandIDs } from '../git/commands';
@@ -24,6 +25,12 @@ export class LauncherDashboard extends ReactWidget {
  * only opened intentionally, and the grid does not need to be live.
  */
 const CHANGES_POLL_INTERVAL_MS = 8000;
+/**
+ * Upper bound on the exponential backoff when the status request fails
+ * repeatedly. Matches the rest of the plugin's polls so behavior is
+ * consistent across the dashboard, the git panel, and the file tree.
+ */
+const CHANGES_POLL_MAX_MS = 300000;
 function LauncherDashboardComponent(props) {
     const { commands, agents, onAgentLaunch, repoPath, cwd } = props;
     const [prompt, setPrompt] = React.useState('');
@@ -45,12 +52,23 @@ function LauncherDashboardComponent(props) {
             });
         }
     }, [repoPath]);
+    // Driven by a Lumino `Poll` so the dashboard stops hitting the git
+    // endpoint while the JupyterLab tab is hidden, and so repeated
+    // failures back off exponentially instead of pegging the 8s cadence.
     React.useEffect(() => {
-        void refresh();
-        const handle = window.setInterval(() => {
-            void refresh();
-        }, CHANGES_POLL_INTERVAL_MS);
-        return () => window.clearInterval(handle);
+        const poll = new Poll({
+            name: '@xtralab/launcher:gitChanges',
+            factory: () => refresh(),
+            frequency: {
+                interval: CHANGES_POLL_INTERVAL_MS,
+                backoff: true,
+                max: CHANGES_POLL_MAX_MS
+            },
+            standby: 'when-hidden'
+        });
+        return () => {
+            poll.dispose();
+        };
     }, [refresh]);
     const launch = React.useCallback(async (agent) => {
         const args = { cwd };
@@ -154,10 +172,9 @@ function AgentSection(props) {
     const { agents, prompt, onPromptChange, onLaunch } = props;
     const trimmed = prompt.trim();
     const promptActive = trimmed.length > 0;
-    // The "primary" agent is the first prompt-capable one in the rendered
-    // order. We mark it visually so the keyboard shortcut target isn't a
-    // mystery, and reuse the same agent when Cmd/Ctrl+Enter fires from the
-    // textarea — picking by the same rule keeps the two behaviors in sync.
+    // The first prompt-capable agent is what Cmd/Ctrl+Enter fires; the hint
+    // text below the textarea names it so the keyboard shortcut target
+    // isn't a mystery.
     const primaryAgent = agents.find(agent => agent.promptArgs !== undefined);
     const hintId = 'jp-xtralab-Launcher-agent-hint';
     return (React.createElement("section", { className: "jp-xtralab-Launcher-section" },
@@ -177,15 +194,10 @@ function AgentSection(props) {
         React.createElement("div", { className: "jp-xtralab-Launcher-agents" }, agents.map(agent => {
             const supportsPrompt = agent.promptArgs !== undefined;
             const disabled = promptActive && !supportsPrompt;
-            const isPrimary = agent === primaryAgent;
             const tooltip = disabled
                 ? `${agent.label} doesn't accept an initial prompt — clear the prompt to launch.`
                 : agent.caption;
-            const classes = ['jp-xtralab-Launcher-agent'];
-            if (isPrimary) {
-                classes.push('jp-xtralab-Launcher-agent-primary');
-            }
-            return (React.createElement("button", { key: agent.id, type: "button", className: classes.join(' '), title: tooltip, "aria-label": agent.label, "aria-describedby": hintId, disabled: disabled, onClick: () => onLaunch(agent) },
+            return (React.createElement("button", { key: agent.id, type: "button", className: "jp-xtralab-Launcher-agent", title: tooltip, "aria-label": agent.label, "aria-describedby": hintId, disabled: disabled, onClick: () => onLaunch(agent) },
                 React.createElement(LabIcon.resolveReact, { icon: agent.icon, tag: "span", className: "jp-xtralab-Launcher-agent-icon" }),
                 React.createElement("span", { className: "jp-xtralab-Launcher-agent-label" }, agent.label)));
         }))));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xtralab",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "An opinionated JupyterLab meta-package that bundles a curated set of extensions, ships a path-first file browser and a VS Code-style git changes panel, and applies a quieter default workspace configuration.",
     "keywords": [
         "jupyter",
@@ -57,8 +57,12 @@
         "watch:labextension": "jupyter-builder watch ."
     },
     "dependencies": {
+        "@codemirror/language": "^6.12.1",
+        "@codemirror/state": "^6.5.4",
+        "@codemirror/view": "^6.39.14",
         "@jupyterlab/application": "^4.6.0-alpha.5",
         "@jupyterlab/apputils": "^4.7.0-alpha.5",
+        "@jupyterlab/codemirror": "^4.6.0-alpha.5",
         "@jupyterlab/coreutils": "^6.6.0-alpha.5",
         "@jupyterlab/docmanager": "^4.6.0-alpha.5",
         "@jupyterlab/docregistry": "^4.6.0-alpha.5",
@@ -78,10 +82,12 @@
         "@lumino/disposable": "^2.0.0",
         "@lumino/dragdrop": "^2.0.0",
         "@lumino/messaging": "^2.0.0",
+        "@lumino/polling": "^2.1.5",
         "@lumino/signaling": "^2.0.0",
         "@lumino/widgets": "^2.0.0",
         "@pierre/diffs": "^1.1.20",
         "@pierre/trees": "1.0.0-beta.3",
+        "detect-indent": "^7.0.2",
         "ignore": "^5.3.2",
         "react": "^18.2.0",
         "react-dom": "^18.2.0"

package/src/editorBreadcrumbs/index.ts

@@ -0,0 +1,70 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import type {
+  DocumentRegistry,
+  IDocumentWidget
+} from '@jupyterlab/docregistry';
+import type { CommandRegistry } from '@lumino/commands';
+import { DisposableDelegate, type IDisposable } from '@lumino/disposable';
+import type { Widget } from '@lumino/widgets';
+
+import { EditorBreadcrumbs } from './widget';
+
+const PLUGIN_ID = 'xtralab:editor-breadcrumbs';
+const EDITOR_FACTORY = 'Editor';
+const TOOLBAR_ITEM_NAME = 'xtralab-editor-breadcrumbs';
+
+class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
+  IDocumentWidget<Widget, DocumentRegistry.IModel>,
+  DocumentRegistry.IModel
+> {
+  constructor(commands: CommandRegistry) {
+    this._commands = commands;
+  }
+
+  createNew(
+    widget: IDocumentWidget<Widget, DocumentRegistry.IModel>,
+    context: DocumentRegistry.IContext<DocumentRegistry.IModel>
+  ): IDisposable | void {
+    const breadcrumbs = new EditorBreadcrumbs({
+      context,
+      commands: this._commands
+    });
+    const added = widget.toolbar.insertItem(0, TOOLBAR_ITEM_NAME, breadcrumbs);
+
+    if (!added) {
+      breadcrumbs.dispose();
+      return;
+    }
+
+    return new DisposableDelegate(() => {
+      breadcrumbs.dispose();
+    });
+  }
+
+  private _commands: CommandRegistry;
+}
+
+/**
+ * Adds a VS Code-style path breadcrumb to text editor toolbars. Each
+ * segment is clickable: clicking dispatches `xtralab:reveal-path` so
+ * any plugin that listens (today, the file browser) can surface the
+ * underlying folder or file. The breadcrumbs plugin therefore does not
+ * import the file browser at all — the JupyterLab command registry is
+ * the only seam between them.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description: 'Display the active file path in text editor toolbars.',
+  autoStart: true,
+  activate: (app: JupyterFrontEnd): void => {
+    app.docRegistry.addWidgetExtension(
+      EDITOR_FACTORY,
+      new EditorBreadcrumbsExtension(app.commands)
+    );
+  }
+};
+
+export default plugin;

package/src/editorBreadcrumbs/widget.ts

@@ -0,0 +1,158 @@
+import { PageConfig } from '@jupyterlab/coreutils';
+import type { DocumentRegistry } from '@jupyterlab/docregistry';
+import { homeIcon as rootIcon } from '@jupyterlab/ui-components';
+import type { CommandRegistry } from '@lumino/commands';
+import { Widget } from '@lumino/widgets';
+
+const EDITOR_BREADCRUMBS_CLASS = 'jp-xtralab-EditorBreadcrumbs';
+const BREADCRUMBS_CONTAINER_CLASS = 'jp-BreadCrumbs-container';
+const BREADCRUMBS_CONTENT_CLASS = 'jp-BreadCrumbs-content';
+const ROOT_CLASS = 'jp-BreadCrumbs-home';
+const ITEM_CLASS = 'jp-BreadCrumbs-item';
+const CURRENT_ITEM_CLASS = 'jp-mod-current';
+const SEPARATOR_CLASS = 'jp-BreadCrumbs-separator';
+
+/**
+ * Command dispatched when the user clicks a breadcrumb segment.
+ * Registered by the file browser plugin; the breadcrumbs only know
+ * the name so they stay decoupled from the file browser internals.
+ */
+const REVEAL_COMMAND = 'xtralab:reveal-path';
+
+export interface IEditorBreadcrumbsOptions {
+  context: DocumentRegistry.IContext<DocumentRegistry.IModel>;
+  commands: CommandRegistry;
+}
+
+/**
+ * Read-only breadcrumb path for file editor toolbars.
+ *
+ * The upstream `@jupyterlab/filebrowser` BreadCrumbs widget is coupled to
+ * FileBrowserModel navigation, drag/drop, and path editing. If that code
+ * becomes reusable upstream, replace this local display-only renderer with
+ * the shared implementation.
+ */
+export class EditorBreadcrumbs extends Widget {
+  constructor(options: IEditorBreadcrumbsOptions) {
+    super({ node: document.createElement('nav') });
+    this._context = options.context;
+    this._commands = options.commands;
+    this.addClass(EDITOR_BREADCRUMBS_CLASS);
+    this.node.setAttribute('aria-label', 'Editor file path');
+
+    this._container = document.createElement('span');
+    this._container.className = BREADCRUMBS_CONTAINER_CLASS;
+    this._content = document.createElement('span');
+    this._content.className = BREADCRUMBS_CONTENT_CLASS;
+    this._container.appendChild(this._content);
+    this.node.appendChild(this._container);
+
+    this._context.pathChanged.connect(this._onPathChanged, this);
+    this._render();
+  }
+
+  dispose(): void {
+    if (this.isDisposed) {
+      return;
+    }
+    this._context.pathChanged.disconnect(this._onPathChanged, this);
+    super.dispose();
+  }
+
+  private _onPathChanged(): void {
+    this._render();
+  }
+
+  private _render(): void {
+    const path = this._context.localPath || this._context.path;
+    const parts = path.split('/').filter(part => part.length > 0);
+
+    this.node.title = this._context.path;
+    this._content.textContent = '';
+    this._content.appendChild(this._createRootCrumb());
+    if (parts.length > 0) {
+      this._content.appendChild(this._createSeparator());
+    }
+
+    parts.forEach((part, index) => {
+      const isLast = index === parts.length - 1;
+      const subPath = parts.slice(0, index + 1).join('/');
+      // Canonical `@pierre/trees` paths: directories carry a trailing
+      // slash, files do not. Every part except the last names a folder
+      // along the way to the open file.
+      const canonical = isLast ? subPath : `${subPath}/`;
+
+      const item = document.createElement('span');
+      item.className = ITEM_CLASS;
+      item.textContent = part;
+      item.title = subPath;
+      item.tabIndex = 0;
+      item.setAttribute('role', 'button');
+      if (isLast) {
+        item.classList.add(CURRENT_ITEM_CLASS);
+        item.setAttribute('aria-current', 'page');
+      }
+      this._attachReveal(item, canonical);
+      this._content.appendChild(item);
+
+      if (!isLast) {
+        this._content.appendChild(this._createSeparator());
+      }
+    });
+  }
+
+  private _createRootCrumb(): HTMLElement {
+    const item = rootIcon.element({
+      className: ROOT_CLASS,
+      tag: 'span',
+      title: PageConfig.getOption('serverRoot') || 'Jupyter Server Root',
+      stylesheet: 'breadCrumb'
+    });
+    item.dataset.path = '/';
+    item.tabIndex = 0;
+    item.setAttribute('role', 'button');
+    // Empty canonical path: the reveal command treats this as the
+    // workspace-root gesture — surface the file browser, clear its
+    // selection, and scroll back to the top. The tree has no row for
+    // the workspace root itself.
+    this._attachReveal(item, '');
+    return item;
+  }
+
+  /**
+   * Bind click and keyboard activation on a crumb element to the
+   * shared reveal command. Dispatch is best-effort: a failure to
+   * resolve or execute the command is logged but never thrown into
+   * the editor's toolbar.
+   */
+  private _attachReveal(element: HTMLElement, canonicalPath: string): void {
+    const fire = (event: Event): void => {
+      event.preventDefault();
+      event.stopPropagation();
+      void this._commands
+        .execute(REVEAL_COMMAND, { path: canonicalPath })
+        .catch((err: unknown) => {
+          console.error(`xtralab: failed to reveal "${canonicalPath}"`, err);
+        });
+    };
+    element.addEventListener('click', fire);
+    element.addEventListener('keydown', event => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        fire(event);
+      }
+    });
+  }
+
+  private _createSeparator(): HTMLElement {
+    const item = document.createElement('span');
+    item.className = SEPARATOR_CLASS;
+    item.setAttribute('aria-hidden', 'true');
+    item.textContent = '/';
+    return item;
+  }
+
+  private _context: DocumentRegistry.IContext<DocumentRegistry.IModel>;
+  private _commands: CommandRegistry;
+  private _container: HTMLElement;
+  private _content: HTMLElement;
+}

package/src/editorIndent/index.ts

@@ -0,0 +1,177 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import {
+  EditorExtensionRegistry,
+  IEditorExtensionRegistry
+} from '@jupyterlab/codemirror';
+import { indentUnit } from '@codemirror/language';
+import { Compartment, EditorState, Extension, Prec } from '@codemirror/state';
+import { EditorView, ViewPlugin } from '@codemirror/view';
+import detectIndent from 'detect-indent';
+
+const PLUGIN_ID = 'xtralab:editor-indent';
+
+/**
+ * Mime types whose newly-created (or too-short-to-detect) files should default
+ * to a 2-space indent. Matches Prettier's defaults for web languages; mime
+ * types not listed here inherit whatever the user has set in JupyterLab.
+ * Covers .ts/.tsx/.jsx/.js variants registered by `@jupyterlab/codemirror`.
+ */
+const FALLBACK_INDENT_BY_MIME: Record<string, number> = {
+  'application/ecmascript': 2,
+  'application/javascript': 2,
+  'application/json': 2,
+  'application/typescript': 2,
+  'application/x-javascript': 2,
+  'application/x-json': 2,
+  'application/x-yaml': 2,
+  'text/css': 2,
+  'text/ecmascript': 2,
+  'text/html': 2,
+  'text/javascript': 2,
+  'text/jsx': 2,
+  'text/typescript-jsx': 2,
+  'text/x-markdown': 2,
+  'text/x-yaml': 2,
+  'text/yaml': 2
+};
+
+interface IResolvedIndent {
+  unit: string;
+  width: number;
+}
+
+/**
+ * Run `detect-indent` against the file's content and convert its result into
+ * something we can hand to CodeMirror.
+ */
+function detectFromContent(text: string): IResolvedIndent | null {
+  if (text.length === 0) {
+    return null;
+  }
+  const result = detectIndent(text);
+  if (!result.type || result.amount <= 0) {
+    return null;
+  }
+  if (result.type === 'tab') {
+    // detect-indent returns `\t` for `indent` in tab mode; use a 4-column tab
+    // as the visual width, which is what most language servers assume.
+    return { unit: '\t', width: 4 };
+  }
+  return { unit: result.indent, width: result.amount };
+}
+
+function resolveIndent(text: string, mimeType: string): IResolvedIndent | null {
+  const detected = detectFromContent(text);
+  if (detected) {
+    return detected;
+  }
+  const fallback = FALLBACK_INDENT_BY_MIME[mimeType];
+  if (fallback === undefined) {
+    return null;
+  }
+  return { unit: ' '.repeat(fallback), width: fallback };
+}
+
+function buildExtension(resolved: IResolvedIndent): Extension {
+  // `Prec.highest` keeps these values first in their respective facets so
+  // they beat both `defaultConfig` and per-editor `editorConfig.indentUnit`,
+  // both of which JupyterLab registers at default precedence.
+  return Prec.highest([
+    indentUnit.of(resolved.unit),
+    EditorState.tabSize.of(resolved.width)
+  ]);
+}
+
+/**
+ * Sniff each opened document's leading whitespace and configure CodeMirror's
+ * `indentUnit` / `tabSize` to match. JupyterLab only exposes a single global
+ * indent setting, which means TypeScript files written with 4-space indent and
+ * Python files written with 2-space indent both look wrong in the same editor;
+ * detecting from the file's own content sidesteps that without forcing every
+ * project to share the same convention.
+ *
+ * Detection runs at editor-construction time and again on the first content
+ * change — that second pass exists because JupyterLab's collaborative document
+ * loader can settle the file body into the shared model after the editor view
+ * already exists, in which case the factory would otherwise have only seen an
+ * empty string.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'Detect each file’s indentation style from its contents and configure CodeMirror to match; new files fall back to a language-based default.',
+  autoStart: true,
+  requires: [IEditorExtensionRegistry],
+  activate: (
+    app: JupyterFrontEnd,
+    registry: IEditorExtensionRegistry
+  ): void => {
+    registry.addExtension({
+      name: 'xtralab:per-language-indent',
+      factory: options => {
+        const { model } = options;
+        const slot = new Compartment();
+        const initialResolved = resolveIndent(
+          model.sharedModel.getSource(),
+          model.mimeType
+        );
+        const initial = initialResolved ? buildExtension(initialResolved) : [];
+
+        let settled = initialResolved !== null;
+
+        const refreshPlugin = ViewPlugin.fromClass(
+          class {
+            disconnect: (() => void) | null = null;
+
+            constructor(public view: EditorView) {
+              if (settled) {
+                return;
+              }
+              const handler = (): void => {
+                if (settled) {
+                  return;
+                }
+                const resolved = resolveIndent(
+                  model.sharedModel.getSource(),
+                  model.mimeType
+                );
+                if (!resolved) {
+                  return;
+                }
+                settled = true;
+                view.dispatch({
+                  effects: slot.reconfigure(buildExtension(resolved))
+                });
+                if (this.disconnect) {
+                  this.disconnect();
+                  this.disconnect = null;
+                }
+              };
+              model.sharedModel.changed.connect(handler);
+              this.disconnect = () => {
+                model.sharedModel.changed.disconnect(handler);
+              };
+            }
+
+            destroy(): void {
+              if (this.disconnect) {
+                this.disconnect();
+                this.disconnect = null;
+              }
+            }
+          }
+        );
+
+        return EditorExtensionRegistry.createImmutableExtension([
+          slot.of(initial),
+          refreshPlugin
+        ]);
+      }
+    });
+  }
+};
+
+export default plugin;

package/src/fileBrowser/commands.ts

@@ -10,6 +10,7 @@ import { PageConfig, PathExt } from '@jupyterlab/coreutils';
 import {
   addIcon,
   closeIcon,
+  collapseAllIcon,
   CommandToolbarButton,
   copyIcon,
   downloadIcon,
@@ -24,7 +25,7 @@ import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
 import { ContextMenu } from '@lumino/widgets';
 
 import { toCanonicalPath, toServerPath } from './contents';
-import { IXtralabFileBrowser } from './widget';
+import { FILE_BROWSER_ID, IXtralabFileBrowser } from './widget';
 
 /**
  * Command identifiers exposed by the xtralab browser. We deliberately namespace
@@ -42,8 +43,10 @@ export namespace CommandIDs {
   export const copyPath = 'xtralab:copy-path';
   export const download = 'xtralab:download';
   export const refresh = 'xtralab:refresh';
+  export const collapseAll = 'xtralab:collapse-all';
   export const createNewDirectory = 'xtralab:create-new-directory';
   export const newLauncher = 'xtralab:new-launcher';
+  export const revealPath = 'xtralab:reveal-path';
 }
 
 /**
@@ -406,6 +409,36 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
+  commands.addCommand(CommandIDs.collapseAll, {
+    label: 'Collapse All Folders',
+    caption: 'Collapse all folders in the file browser',
+    icon: collapseAllIcon.bindprops({ stylesheet: 'menuItem' }),
+    execute: () => {
+      browser.collapseAll();
+    }
+  });
+
+  // Public reveal seam. Other plugins (editor breadcrumbs, future
+  // "reveal in tree" actions) call this command rather than depending
+  // on the file browser widget directly. Activating the sidebar is part
+  // of the contract: the tree is hidden behind a tab and a reveal that
+  // does not surface the panel would silently no-op from the user's
+  // point of view. An empty path is the "workspace root" gesture —
+  // there is no tree row for the root itself, so the browser is asked
+  // to scroll back to the top and clear its selection instead.
+  commands.addCommand(CommandIDs.revealPath, {
+    label: 'Reveal in File Browser',
+    execute: (args: ReadonlyPartialJSONObject) => {
+      const path = (args.path as string | undefined) ?? '';
+      app.shell.activateById(FILE_BROWSER_ID);
+      if (path.length === 0) {
+        browser.scrollToRoot();
+      } else {
+        browser.reveal(path);
+      }
+    }
+  });
+
   commands.addCommand(CommandIDs.createNewDirectory, {
     label: 'New Folder',
     caption: 'Create a new folder',
@@ -468,6 +501,7 @@ export namespace ToolbarNames {
   export const newLauncher = 'new-launcher';
   export const newDirectory = 'new-directory';
   export const refresh = 'refresh';
+  export const collapseAll = 'collapse-all';
 }
 
 /**
@@ -507,4 +541,12 @@ export function populateToolbar(opts: {
       label: ''
     })
   );
+  browser.toolbar.addItem(
+    ToolbarNames.collapseAll,
+    new CommandToolbarButton({
+      commands,
+      id: CommandIDs.collapseAll,
+      label: ''
+    })
+  );
 }