xtralab 0.8.0 → 0.10.0

package/lib/git/index.d.ts

@@ -1,12 +1,7 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { CommandArguments, CommandIDs } from './commands';
 /**
- * Every plugin contributed by xtralab's git integration:
- *
- *   1. {@link diffCommandPlugin} — the launcher's `xtralab:git:open-diff`.
- *   2. `diffProviderPlugin` — registers the `@pierre/diffs` rendering as
- *      jupyterlab-git's diff providers (replacing its disabled
- *      notebook/text diff plugins).
+ * Plugins contributed by xtralab's git integration.
  */
 declare const plugins: JupyterFrontEndPlugin<unknown>[];
 export { CommandArguments, CommandIDs };

package/lib/git/index.js

@@ -1,19 +1,14 @@
 import { IThemeManager, WidgetTracker } from '@jupyterlab/apputils';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
-import { CommandIDs, registerGitCommands } from './commands';
-import { PREVIEW_DIFF_WIDGET_ID, pinnedDiffWidgetId } from './diffWidget';
+import { CommandIDs, PREVIEW_DIFF_WIDGET_ID, pinnedDiffWidgetId, registerGitCommands } from './commands';
 import diffProviderPlugin from './diffProvider';
 const GIT_DIFF_COMMAND_PLUGIN_ID = 'xtralab:git-diff-command';
 const GIT_DIFF_TRACKER_NAMESPACE = 'xtralab-git-diff';
 /**
  * The launcher's git diff command plugin.
  *
- * The `@jupyterlab/git` frontend stays enabled (only its diff plugins are
- * swapped — see `diffProvider.tsx`), so the upstream git panel is what the
- * user sees in the sidebar. This plugin is the launcher dashboard's
- * independent diff path: the `xtralab:git:open-diff` command the
- * dashboard's "Changes" section calls, plus a tracker so reopening a diff
- * reveals the existing tab and the preview/pin behavior keeps working.
+ * The upstream git panel stays enabled; this plugin only gives the launcher
+ * its own `xtralab:git:open-diff` command and preview/pinned-tab tracking.
  */
 const diffCommandPlugin = {
     id: GIT_DIFF_COMMAND_PLUGIN_ID,
@@ -21,9 +16,7 @@ const diffCommandPlugin = {
     autoStart: true,
     optional: [IThemeManager, IRenderMimeRegistry],
     activate: (app, themeManager, rendermime) => {
-        // Track open diff widgets so the openDiff handler can reveal an
-        // already-open diff for the same file instead of creating a duplicate
-        // (and so a promoted preview can find its pinned twin).
+        // Track open diffs so repeated opens reveal the existing tab.
         const tracker = new WidgetTracker({
             namespace: GIT_DIFF_TRACKER_NAMESPACE
         });
@@ -37,13 +30,9 @@ const diffCommandPlugin = {
             themeManager,
             contentsManager: app.serviceManager.contents,
             rendermime,
-            // The launcher polls git status on its own cadence and the
-            // jupyterlab-git panel auto-refreshes on the contents `fileChanged`
-            // signal a hunk-discard save emits, so no extra refresh is needed.
-            onChanged: () => undefined,
             trackDiff: widget => tracker.add(widget),
             onPinned: current => {
-                const existing = findDiff(current.content.change, true);
+                const existing = findDiff(current.change, true);
                 if (existing !== undefined &&
                     existing !== current &&
                     !existing.isDisposed) {
@@ -51,7 +40,7 @@ const diffCommandPlugin = {
                     current.close();
                     return;
                 }
-                current.id = pinnedDiffWidgetId(current.content.change);
+                current.id = pinnedDiffWidgetId(current.change);
                 current.title.className = '';
                 app.shell.activateById(current.id);
             },
@@ -60,12 +49,7 @@ const diffCommandPlugin = {
     }
 };
 /**
- * Every plugin contributed by xtralab's git integration:
- *
- *   1. {@link diffCommandPlugin} — the launcher's `xtralab:git:open-diff`.
- *   2. `diffProviderPlugin` — registers the `@pierre/diffs` rendering as
- *      jupyterlab-git's diff providers (replacing its disabled
- *      notebook/text diff plugins).
+ * Plugins contributed by xtralab's git integration.
  */
 const plugins = [
     diffCommandPlugin,

package/lib/git/notebookDiff.d.ts

@@ -97,7 +97,7 @@ export declare function parseNotebook(text: string): INotebook | null;
  * nbformat allows multiline string fields (`source`, stream `text`,
  * `text/plain` outputs, …) to be either a single string or an array of
  * strings. Normalize to one string so equality checks and diffs see the
- * same shape regardless of how the writer chose to serialise it.
+ * same shape regardless of how the writer chose to serialize it.
  */
 export declare function joinMultiline(value: string | string[] | undefined): string;
 export declare function cellSource(cell: INotebookCell): string;
@@ -160,6 +160,11 @@ export declare function buildNotebookDiff(options: IBuildNotebookDiffOptions): I
 interface INotebookDiffViewProps {
     diff: INotebookDiffResult;
     dark: boolean;
+    /**
+     * Whether a Pierre JupyterLab theme is active; selects Pierre's rich
+     * highlighting vs the CSS-variable theme (see {@link resolveDiffTheme}).
+     */
+    pierreTheme: boolean;
     rendermime: IRenderMimeRegistry | null;
 }
 /**

package/lib/git/notebookDiff.js

@@ -5,6 +5,7 @@ import { MessageLoop } from '@lumino/messaging';
 import { Widget } from '@lumino/widgets';
 import { FileDiff } from '@pierre/diffs/react';
 import { parseDiffFromFile } from '@pierre/diffs';
+import { resolveDiffTheme } from './diffTheme';
 /**
  * The CSS class added to the root of the notebook diff. Selectors that
  * style cell sections, headers, and the per-cell diff blocks hang off this
@@ -50,7 +51,7 @@ function emptyNotebook() {
  * nbformat allows multiline string fields (`source`, stream `text`,
  * `text/plain` outputs, …) to be either a single string or an array of
  * strings. Normalize to one string so equality checks and diffs see the
- * same shape regardless of how the writer chose to serialise it.
+ * same shape regardless of how the writer chose to serialize it.
  */
 export function joinMultiline(value) {
     if (value === undefined) {
@@ -596,8 +597,8 @@ function MarkdownPreviewSection(props) {
  * the orientation clear without a separate column header.
  */
 export function NotebookDiffView(props) {
-    const { diff, dark, rendermime } = props;
-    const theme = dark ? 'pierre-dark' : 'pierre-light';
+    const { diff, dark, pierreTheme, rendermime } = props;
+    const theme = resolveDiffTheme(dark, pierreTheme);
     const summary = React.useMemo(() => summarize(diff.cells), [diff.cells]);
     return (React.createElement("div", { className: NOTEBOOK_DIFF_CSS_CLASS },
         React.createElement(NotebookDiffHeader, { summary: summary }),

package/lib/index.js

@@ -1,11 +1,13 @@
 import agentSessionsPlugin from './agentSessions';
 import fileBrowserPlugin from './fileBrowser';
+import fileTypeIconsPlugin from './fileTypeIcons';
 import editorBreadcrumbsPlugin from './editorBreadcrumbs';
 import editorIndentPlugin from './editorIndent';
 import gitPlugins from './git';
 import launcherPlugins from './launcher';
 import menusPlugin from './menus';
 import sidebarPlugin from './sidebar';
+import terminalNotificationsPlugin from './terminalNotifications';
 import terminalsPlugin from './terminals';
 import topBarPlugin from './topBar';
 /**
@@ -22,10 +24,12 @@ const plugins = [
     editorBreadcrumbsPlugin,
     editorIndentPlugin,
     fileBrowserPlugin,
+    fileTypeIconsPlugin,
     ...gitPlugins,
     ...launcherPlugins,
     menusPlugin,
     sidebarPlugin,
+    terminalNotificationsPlugin,
     terminalsPlugin,
     topBarPlugin
 ];

package/lib/terminalNotifications/index.d.ts

@@ -0,0 +1,15 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Turns the notifications coding agents already emit (OSC 9, OSC 777, the bell)
+ * into desktop notifications. JupyterLab's xterm renders these sequences but
+ * never forwards them to the OS, so this plugin hooks each terminal and bridges
+ * them through `window.xtralab.notify` (desktop) or the web Notifications API.
+ *
+ * A notification is suppressed while its terminal is the focused, active tab,
+ * and throttled per terminal. The desktop shell advertises
+ * `TERM_PROGRAM=iTerm.app` so agents emit OSC 9 in the first place, and the
+ * session name is forwarded so clicking a notification focuses the terminal
+ * that fired it.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/terminalNotifications/index.js

@@ -0,0 +1,213 @@
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ITerminalTracker } from '@jupyterlab/terminal';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+const PLUGIN_ID = 'xtralab:terminal-notifications';
+// Per-terminal gap between notifications, so the OSC-9-plus-bell agents emit
+// together collapses into one and a chatty program cannot flood the OS.
+const NOTIFY_THROTTLE_MS = 3000;
+// iTerm2 growl notification: `ESC ] 9 ; <message> BEL`. What Claude Code and
+// most agents emit on their default `auto` setting once TERM_PROGRAM is set.
+const OSC_ITERM2_GROWL = 9;
+// rxvt/Ghostty notification: `ESC ] 777 ; notify ; <title> ; <body> BEL`.
+const OSC_RXVT_NOTIFY = 777;
+const MAX_TEXT_LENGTH = 256;
+/**
+ * Turns the notifications coding agents already emit (OSC 9, OSC 777, the bell)
+ * into desktop notifications. JupyterLab's xterm renders these sequences but
+ * never forwards them to the OS, so this plugin hooks each terminal and bridges
+ * them through `window.xtralab.notify` (desktop) or the web Notifications API.
+ *
+ * A notification is suppressed while its terminal is the focused, active tab,
+ * and throttled per terminal. The desktop shell advertises
+ * `TERM_PROGRAM=iTerm.app` so agents emit OSC 9 in the first place, and the
+ * session name is forwarded so clicking a notification focuses the terminal
+ * that fired it.
+ */
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Forwards desktop notifications emitted by agents in xtralab terminals (OSC 9, OSC 777, bell) to the operating system.',
+    autoStart: true,
+    requires: [ITerminalTracker],
+    optional: [ISettingRegistry, ITranslator],
+    activate: async (app, tracker, settingRegistry, translator) => {
+        var _a;
+        const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
+        let enabled = true;
+        let notifyOnBell = true;
+        // Per-widget throttle timestamps and xterm hooks. WeakMaps let disposed
+        // widgets be collected; hooks are torn down when a tab closes.
+        const lastNotified = new WeakMap();
+        const hooks = new WeakMap();
+        // True when the user is already looking at this terminal, so a banner would
+        // just be noise.
+        const isActivelyViewing = (widget) => document.hasFocus() && app.shell.currentWidget === widget;
+        const deliver = (title, body, session) => {
+            const bridge = window.xtralab;
+            if (bridge && typeof bridge.notify === 'function') {
+                void Promise.resolve(bridge.notify(title, body, session)).catch(reason => {
+                    console.warn('xtralab: desktop notification failed', reason);
+                });
+                return;
+            }
+            // Plain-browser fallback (pip install): the Web Notifications API.
+            if (typeof Notification === 'undefined') {
+                return;
+            }
+            if (Notification.permission === 'granted') {
+                new Notification(title, { body });
+            }
+            else if (Notification.permission !== 'denied') {
+                void Notification.requestPermission().then(permission => {
+                    if (permission === 'granted') {
+                        new Notification(title, { body });
+                    }
+                });
+            }
+        };
+        const notify = (widget, title, body) => {
+            var _a;
+            if (!enabled || isActivelyViewing(widget)) {
+                return;
+            }
+            const now = Date.now();
+            const previous = lastNotified.get(widget);
+            if (previous !== undefined && now - previous < NOTIFY_THROTTLE_MS) {
+                return;
+            }
+            lastNotified.set(widget, now);
+            const session = (_a = widget.content.session) === null || _a === void 0 ? void 0 : _a.name;
+            deliver(sanitize(title) || 'xtralab', sanitize(body), session);
+        };
+        // The tab label is the agent's name once the launcher or an xterm title sets
+        // it, so it reads well as the title for body-only sequences (OSC 9, bell).
+        const labelOf = (widget) => widget.title.label || trans.__('Terminal');
+        const onOsc9 = (widget, data) => {
+            // OSC 9 is overloaded: ConEmu/Windows Terminal use `9 ; <n> ; …`
+            // subcommands (e.g. `9 ; 4` progress), so skip a numeric-subcommand
+            // payload and leave it unconsumed rather than treat it as a notification.
+            if (/^\d+(;|$)/.test(data)) {
+                return false;
+            }
+            const message = sanitize(data);
+            if (message) {
+                notify(widget, labelOf(widget), message);
+            }
+            return true;
+        };
+        const onOsc777 = (widget, data) => {
+            var _a;
+            // `notify ; <title> ; <body>`; a body may contain ';'. Other OSC 777
+            // subcommands are left unconsumed.
+            const parts = data.split(';');
+            if (parts.shift() !== 'notify') {
+                return false;
+            }
+            const title = sanitize((_a = parts.shift()) !== null && _a !== void 0 ? _a : '') || labelOf(widget);
+            const body = sanitize(parts.join(';'));
+            if (body || title) {
+                notify(widget, title, body);
+            }
+            return true;
+        };
+        const onBell = (widget) => {
+            if (notifyOnBell) {
+                notify(widget, labelOf(widget), trans.__('Activity in terminal'));
+            }
+        };
+        const hookWidget = (widget) => {
+            if (hooks.has(widget)) {
+                return;
+            }
+            const content = widget.content;
+            void content.ready
+                .then(() => {
+                const term = content._term;
+                if (widget.isDisposed) {
+                    return;
+                }
+                if (!term) {
+                    console.warn('xtralab: xterm internals not found; terminal notifications are disabled for this terminal');
+                    return;
+                }
+                // Handlers are wrapped so a parse slip cannot break xterm's parser; an
+                // OSC handler returns whether it consumed the sequence.
+                const disposables = [
+                    term.onBell(() => guard(() => onBell(widget))),
+                    term.parser.registerOscHandler(OSC_ITERM2_GROWL, data => guardOsc(() => onOsc9(widget, data))),
+                    term.parser.registerOscHandler(OSC_RXVT_NOTIFY, data => guardOsc(() => onOsc777(widget, data)))
+                ];
+                hooks.set(widget, disposables);
+                widget.disposed.connect(() => {
+                    for (const disposable of disposables) {
+                        disposable.dispose();
+                    }
+                    hooks.delete(widget);
+                });
+            })
+                .catch(reason => {
+                console.warn('xtralab: could not hook terminal notifications', reason);
+            });
+        };
+        tracker.forEach(hookWidget);
+        tracker.widgetAdded.connect((_, widget) => hookWidget(widget));
+        // Focus the terminal that fired a notification when the desktop shell
+        // reports a click. `terminal:open` activates its tab or reopens the session.
+        const desktopBridge = window
+            .xtralab;
+        (_a = desktopBridge === null || desktopBridge === void 0 ? void 0 : desktopBridge.onFocusTerminal) === null || _a === void 0 ? void 0 : _a.call(desktopBridge, session => {
+            if (session) {
+                void app.commands.execute('terminal:open', { name: session });
+            }
+        });
+        if (settingRegistry) {
+            try {
+                const settings = await settingRegistry.load(PLUGIN_ID);
+                const readSettings = () => {
+                    enabled = boolOption(settings.composite.enabled, true);
+                    notifyOnBell = boolOption(settings.composite.notifyOnBell, true);
+                };
+                readSettings();
+                settings.changed.connect(readSettings);
+            }
+            catch (reason) {
+                console.error('xtralab: failed to load terminal-notifications settings', reason);
+            }
+        }
+    }
+};
+// Run `fn`, swallowing errors so a malformed escape sequence cannot take the
+// terminal's parser or bell handler down with it.
+function guard(fn) {
+    try {
+        fn();
+    }
+    catch (reason) {
+        console.warn('xtralab: terminal notification handler failed', reason);
+    }
+}
+// `guard` for an OSC handler that reports whether it consumed the sequence.
+function guardOsc(fn) {
+    try {
+        return fn();
+    }
+    catch (reason) {
+        console.warn('xtralab: terminal notification handler failed', reason);
+        return false;
+    }
+}
+// Replace control characters with spaces (so a notification cannot carry escape
+// sequences), collapse whitespace, and clamp the length.
+function sanitize(value) {
+    var _a;
+    let result = '';
+    for (const char of value) {
+        const code = (_a = char.codePointAt(0)) !== null && _a !== void 0 ? _a : 0;
+        const isControl = code < 0x20 || (code >= 0x7f && code <= 0x9f);
+        result += isControl ? ' ' : char;
+    }
+    return result.replace(/\s+/g, ' ').trim().slice(0, MAX_TEXT_LENGTH);
+}
+function boolOption(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+export default plugin;

package/lib/terminals/model.d.ts

@@ -82,7 +82,7 @@ export declare class SessionRegistry implements IDisposable {
     agentCommandFor(name: string): string | null;
     /**
      * Return the open widget for a session, if any. The panel uses this to
-     * switch behaviour between "activate existing tab" and "open a new tab
+     * switch behavior between "activate existing tab" and "open a new tab
      * connected to the live session".
      */
     widgetFor(name: string): TerminalWidget | null;

package/lib/terminals/model.js

@@ -176,7 +176,7 @@ export class SessionRegistry {
     }
     /**
      * Return the open widget for a session, if any. The panel uses this to
-     * switch behaviour between "activate existing tab" and "open a new tab
+     * switch behavior between "activate existing tab" and "open a new tab
      * connected to the live session".
      */
     widgetFor(name) {

package/lib/terminals/widget.d.ts

@@ -18,7 +18,7 @@ export declare const RUNNING_TERMINALS_ID = "xtralab-running-terminals";
  * Backed by {@link SessionRegistry}: a `UseSignal` re-renders the list
  * whenever the registry emits `stateChanged`, so it tracks
  * `runningChanged` and the agent-title cache without any local state.
- * Click behaviour (activate vs. reopen, shutdown, new terminal) is
+ * Click behavior (activate vs. reopen, shutdown, new terminal) is
  * delegated to plugin-supplied callbacks so the widget never imports
  * `app`.
  */

package/lib/terminals/widget.js

@@ -17,7 +17,7 @@ export const RUNNING_TERMINALS_ID = 'xtralab-running-terminals';
  * Backed by {@link SessionRegistry}: a `UseSignal` re-renders the list
  * whenever the registry emits `stateChanged`, so it tracks
  * `runningChanged` and the agent-title cache without any local state.
- * Click behaviour (activate vs. reopen, shutdown, new terminal) is
+ * Click behavior (activate vs. reopen, shutdown, new terminal) is
  * delegated to plugin-supplied callbacks so the widget never imports
  * `app`.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xtralab",
-    "version": "0.8.0",
+    "version": "0.10.0",
     "description": "An opinionated JupyterLab meta-package that bundles a curated set of extensions, ships a path-first file browser, renders jupyterlab-git's text, notebook and image diffs with its own viewers, and applies a quieter default workspace configuration.",
     "keywords": [
         "jupyter",
@@ -87,8 +87,8 @@
         "@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",
+        "@pierre/diffs": "^1.2.7",
+        "@pierre/trees": "1.0.0-beta.4",
         "detect-indent": "^7.0.2",
         "ignore": "^5.3.2",
         "react": "^18.2.0",

package/schema/plugin.json

@@ -58,6 +58,12 @@
         "command": "xtralab:download",
         "selector": ".jp-xtralab-FileBrowser [data-type=\"item\"][data-item-type=\"file\"]",
         "rank": 10
+      },
+      {
+        "command": "xtralab:reveal-in-file-tree",
+        "args": { "fromTab": true },
+        "selector": "[data-type=\"document-title\"]",
+        "rank": 25
       }
     ]
   },

package/schema/terminal-notifications.json

@@ -0,0 +1,21 @@
+{
+  "title": "xtralab terminal notifications",
+  "description": "Desktop notifications from coding agents running in xtralab terminals.",
+  "jupyter.lab.shortcuts": [],
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "title": "Enable terminal notifications",
+      "description": "When true, a desktop notification is shown when a program in a terminal asks for one (the iTerm2/Ghostty OSC sequences or the bell) — for example when a coding agent finishes or needs input. Notifications are suppressed while you are looking at that terminal.",
+      "default": true
+    },
+    "notifyOnBell": {
+      "type": "boolean",
+      "title": "Notify on the terminal bell",
+      "description": "When true, a plain terminal bell also raises a notification. The richer OSC 9 / OSC 777 sequences are always handled; disable this if the bell alone proves too noisy.",
+      "default": true
+    }
+  },
+  "additionalProperties": false
+}

package/src/fileBrowser/commands.ts

@@ -2,11 +2,14 @@ import { JupyterFrontEnd } from '@jupyterlab/application';
 import {
   Clipboard,
   Dialog,
+  ICommandPalette,
   InputDialog,
   showDialog,
   showErrorMessage
 } from '@jupyterlab/apputils';
 import { PageConfig, PathExt } from '@jupyterlab/coreutils';
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import {
   addIcon,
   closeIcon,
@@ -22,7 +25,7 @@ import {
   refreshIcon
 } from '@jupyterlab/ui-components';
 import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
-import { ContextMenu } from '@lumino/widgets';
+import { ContextMenu, Widget } from '@lumino/widgets';
 
 import { toCanonicalPath, toServerPath } from './contents';
 import { FILE_BROWSER_ID, IXtralabFileBrowser } from './widget';
@@ -47,6 +50,7 @@ export namespace CommandIDs {
   export const createNewDirectory = 'xtralab:create-new-directory';
   export const newLauncher = 'xtralab:new-launcher';
   export const revealPath = 'xtralab:reveal-path';
+  export const revealInFileTree = 'xtralab:reveal-in-file-tree';
 }
 
 /**
@@ -60,6 +64,9 @@ export const OPEN_WITH_SUBMENU_ID = 'jp-contextmenu-xtralab-open-with';
 export interface IRegisterCommandsOptions {
   app: JupyterFrontEnd;
   browser: IXtralabFileBrowser;
+  docManager: IDocumentManager;
+  palette: ICommandPalette | null;
+  translator: ITranslator | null;
 }
 
 /**
@@ -152,6 +159,53 @@ function getWorkingDirectory(browser: IXtralabFileBrowser): string {
   return PathExt.dirname(serverPath);
 }
 
+/**
+ * Resolve the main-area widget whose tab is the target of the current
+ * context-menu event, or `null` when that target is not a document tab. The
+ * shell stamps each tab's `data-id` with its widget id, so the right-clicked
+ * tab resolves even when it is not the current one.
+ *
+ * Valid only during a context-menu invocation: `contextMenuHitTest` reads the
+ * last context-menu event, which is not cleared when the menu closes, so
+ * {@link documentPathToReveal} gates this to avoid resolving a stale tab.
+ */
+function contextMenuTabWidget(app: JupyterFrontEnd): Widget | null {
+  const node = app.contextMenuHitTest(
+    n => n.dataset !== undefined && n.dataset.type === 'document-title'
+  );
+  const id = node?.dataset.id;
+  if (id === undefined) {
+    return null;
+  }
+  for (const widget of app.shell.widgets('main')) {
+    if (widget.id === id) {
+      return widget;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the document to reveal as a canonical `@pierre/trees` path: the
+ * right-clicked tab when `fromContextMenu` is true (the file-tab menu),
+ * otherwise the active main-area widget (the palette). A file's context
+ * `path` is already canonical. Returns `undefined` when nothing resolves.
+ */
+function documentPathToReveal(
+  app: JupyterFrontEnd,
+  docManager: IDocumentManager,
+  fromContextMenu: boolean
+): string | undefined {
+  const widget =
+    (fromContextMenu ? contextMenuTabWidget(app) : null) ??
+    app.shell.currentWidget;
+  if (widget === null) {
+    return undefined;
+  }
+  const path = docManager.contextForWidget(widget)?.path ?? '';
+  return path.length > 0 ? path : undefined;
+}
+
 /**
  * Refresh the "Open With" submenu's items from the document factories that
  * can open the file under the right-click. Mirrors the
@@ -210,8 +264,9 @@ function makeOpenWithUpdater(
  *   the plugin.
  */
 export function registerCommands(opts: IRegisterCommandsOptions): () => void {
-  const { app, browser } = opts;
+  const { app, browser, docManager, palette, translator } = opts;
   const { commands } = app;
+  const trans = (translator ?? nullTranslator).load('jupyterlab');
 
   commands.addCommand(CommandIDs.open, {
     label: args =>
@@ -439,6 +494,23 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
+  // Reveal the resolved document in the tree browser via the reveal-path
+  // command, which surfaces the sidebar and scrolls to the target.
+  commands.addCommand(CommandIDs.revealInFileTree, {
+    label: trans.__('Show in File Tree'),
+    caption: trans.__('Show this file in the xtralab file browser'),
+    isEnabled: args =>
+      documentPathToReveal(app, docManager, args.fromTab === true) !==
+      undefined,
+    execute: args => {
+      const path = documentPathToReveal(app, docManager, args.fromTab === true);
+      if (path === undefined) {
+        return undefined;
+      }
+      return commands.execute(CommandIDs.revealPath, { path });
+    }
+  });
+
   commands.addCommand(CommandIDs.createNewDirectory, {
     label: 'New Folder',
     caption: 'Create a new folder',
@@ -479,6 +551,21 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
+  // This command's enabled state tracks the active widget, not the tree
+  // selection, so re-evaluate it on current-widget changes. `currentChanged`
+  // is optional on the shell interface.
+  const onCurrentChanged = (): void => {
+    commands.notifyCommandChanged(CommandIDs.revealInFileTree);
+  };
+  app.shell.currentChanged?.connect(onCurrentChanged);
+
+  // Also surface it in the palette (acts on the active editor); the file-tab
+  // context-menu entry is declared in `schema/plugin.json`.
+  const paletteItem = palette?.addItem({
+    command: CommandIDs.revealInFileTree,
+    category: trans.__('File Browser')
+  });
+
   // The static items are declared in `schema/plugin.json` under
   // `jupyter.lab.menus.context` so users can override or disable them. The
   // schema also declares an empty submenu placeholder with id
@@ -489,6 +576,8 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
 
   return () => {
     app.contextMenu.opened.disconnect(updateOpenWithMenu);
+    app.shell.currentChanged?.disconnect(onCurrentChanged);
+    paletteItem?.dispose();
   };
 }
 

package/src/fileBrowser/fileBrowser.tsx

@@ -652,7 +652,10 @@ export function FileBrowserComponent(
         previous?.deselect();
       }
       target.select();
-      model.focusPath(canonicalPath);
+      // `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.
+      model.scrollToPath(canonicalPath, { focus: true, offset: 'center' });
     };
 
     /**