xtralab 0.15.0 → 0.15.1

package/src/commandBar/index.ts

@@ -12,25 +12,13 @@ import { IOmnibox, OMNIBOX_OPEN_COMMAND } from '../omnibox/tokens';
 
 const PLUGIN_ID = 'xtralab:command-bar';
 
-/**
- * Factory name of JupyterLab's settings-driven top bar toolbar (`#jp-top-bar`,
- * built by `@jupyterlab/application-extension:top-bar`).
- */
 const TOPBAR_FACTORY = 'TopBar';
 
-/**
- * Name of the pill item within that toolbar. Its placement is declared under
- * `jupyter.lab.toolbars` in this plugin's settings schema
- * (schema/command-bar.json): the core toolbar ships a spacer at rank 50, so
- * the pill's higher rank lands it at the trailing end of the toolbar, next to
- * the right-sidebar toggle button.
- */
 const ITEM_NAME = 'omnibox';
 
 /**
- * A search-bar-styled launcher pill. It holds no text input of its own:
- * clicking it (or pressing Enter/Space while it is focused) runs `onActivate`,
- * which opens the omnibox.
+ * A search-bar-styled launcher pill with no input of its own: activating it
+ * runs `onActivate`, which opens the omnibox.
  */
 class CommandBar extends Widget {
   constructor(options: CommandBar.IOptions) {
@@ -45,19 +33,26 @@ class CommandBar extends Widget {
     this._onActivate = options.onActivate;
   }
 
+  /**
+   * Handle the DOM events for the command bar.
+   */
   handleEvent(event: Event): void {
     if (event.type === 'click') {
       this._onActivate();
     }
   }
 
+  /**
+   * A message handler invoked on an `'after-attach'` message.
+   */
   protected onAfterAttach(): void {
-    // The click bubbles from the inner pill button up to the root node
-    // listened on here; keyboard Enter/Space on the focused button raises the
-    // same synthetic click.
+    // Keyboard Enter/Space on the focused button raises the same synthetic click.
     this.node.addEventListener('click', this);
   }
 
+  /**
+   * A message handler invoked on a `'before-detach'` message.
+   */
   protected onBeforeDetach(): void {
     this.node.removeEventListener('click', this);
   }
@@ -66,6 +61,9 @@ class CommandBar extends Widget {
 }
 
 namespace CommandBar {
+  /**
+   * The options used to create a `CommandBar`.
+   */
   export interface IOptions {
     /**
      * Placeholder-style text shown inside the pill.
@@ -85,15 +83,16 @@ namespace CommandBar {
     onActivate: () => void;
   }
 
+  /**
+   * Create the DOM node for a command bar.
+   */
   export function createNode(
     label: string,
     caption: string,
     shortcut?: string
   ): HTMLElement {
-    // The root is a plain wrapper: as a toolbar item it receives the core
-    // `.jp-Toolbar > .jp-Toolbar-item` sizing (full height, centered flex),
-    // which would otherwise stretch the pill itself; the button inside keeps
-    // its own compact pill height.
+    // Plain wrapper: the core `.jp-Toolbar-item` sizing would otherwise
+    // stretch the pill itself.
     const wrapper = document.createElement('div');
 
     const button = document.createElement('button');
@@ -118,7 +117,6 @@ namespace CommandBar {
       const hint = document.createElement('span');
       hint.className = 'jp-xtralab-CommandBar-shortcut';
       hint.textContent = shortcut;
-      // Decorative: the button's aria-label already names the action.
       hint.setAttribute('aria-hidden', 'true');
       button.appendChild(hint);
     }
@@ -129,19 +127,10 @@ namespace CommandBar {
 }
 
 /**
- * Contribute a search-bar-styled command bar to JupyterLab's top bar toolbar.
- * Clicking it opens the omnibox — a launcher overlay that fuzzy-searches files
- * and commands and routes a typed prompt to an agent.
- *
- * The pill is a regular settings-driven toolbar item: this plugin registers a
- * widget factory for it on the `IToolbarWidgetRegistry` and declares its rank
- * in schema/command-bar.json, so users can move or disable it from the Top
- * Bar settings like any other toolbar item.
- *
- * The factory is only registered when the omnibox is available — the
- * `IOmnibox` token is provided by `xtralab:omnibox` — so the pill never
- * appears with nothing to open (without a factory, the toolbar item resolves
- * to an empty command button that renders nothing).
+ * Contribute a search-bar-styled pill to the top bar toolbar that opens the
+ * omnibox. It is a settings-driven toolbar item (factory here, rank in
+ * schema/command-bar.json) registered only when `IOmnibox` is provided —
+ * without a factory the item resolves to an empty button that renders nothing.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -163,10 +152,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
     const trans = (translator ?? nullTranslator).load('jupyterlab');
 
     toolbarRegistry.addFactory(TOPBAR_FACTORY, ITEM_NAME, () => {
-      // Show the omnibox's keyboard shortcut as a hint in the pill, derived
-      // from the live binding (registered by xtralab:omnibox, which activates
-      // first as the IOmnibox provider) so it stays correct and uses the
-      // platform's modifier symbols. Empty when no binding is registered.
       const binding = app.commands.keyBindings.find(
         keyBinding => keyBinding.command === OMNIBOX_OPEN_COMMAND
       );

package/src/customPanel/index.ts

@@ -31,23 +31,38 @@ class CustomPanel extends SidePanel implements IMovableSectionDestination {
     this.addClass('jp-xtralab-CustomPanel');
   }
 
+  /**
+   * The accordion panel hosting the sections.
+   */
   get accordionPanel(): AccordionPanel {
     return this.content as AccordionPanel;
   }
 
+  /**
+   * The section widgets currently hosted by the panel.
+   */
   get sections(): ReadonlyArray<Widget> {
     return this.content.widgets;
   }
 
+  /**
+   * A signal emitted with the new count when the number of sections changes.
+   */
   get sectionCountChanged(): ISignal<this, number> {
     return this._sectionCountChanged;
   }
 
+  /**
+   * Add a section widget to the panel.
+   */
   addSection(widget: Widget): void {
     this.addWidget(widget);
     this._sectionCountChanged.emit(this.content.widgets.length);
   }
 
+  /**
+   * Remove a section widget from the panel, if it is hosted here.
+   */
   removeSectionWidget(widget: Widget): void {
     if (widget.parent !== this.content) {
       return;

package/src/editorBreadcrumbs/index.ts

@@ -21,6 +21,10 @@ const PLUGIN_ID = 'xtralab:editor-breadcrumbs';
 const EDITOR_FACTORY = 'Editor';
 const TOOLBAR_ITEM_NAME = 'xtralab-editor-breadcrumbs';
 
+/**
+ * A widget extension that adds an `EditorBreadcrumbs` item to the toolbar of
+ * each new editor widget.
+ */
 class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
   IDocumentWidget<Widget, DocumentRegistry.IModel>,
   DocumentRegistry.IModel
@@ -30,6 +34,9 @@ class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
     this._trans = trans;
   }
 
+  /**
+   * Create the breadcrumbs toolbar item for a new editor widget.
+   */
   createNew(
     widget: IDocumentWidget<Widget, DocumentRegistry.IModel>,
     context: DocumentRegistry.IContext<DocumentRegistry.IModel>
@@ -56,12 +63,9 @@ class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
 }
 
 /**
- * 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.
+ * Adds a clickable path breadcrumb to text editor toolbars. Clicks dispatch
+ * `xtralab:reveal-path`; the command registry is the only seam with the file
+ * browser.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,

package/src/editorBreadcrumbs/widget.ts

@@ -15,15 +15,25 @@ 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.
+ * Registered by the file browser plugin; only the name is shared here.
  */
 const REVEAL_COMMAND = 'xtralab:reveal-path';
 
+/**
+ * The options used to create an `EditorBreadcrumbs` widget.
+ */
 interface IEditorBreadcrumbsOptions {
+  /**
+   * The document context whose path is rendered.
+   */
   context: DocumentRegistry.IContext<DocumentRegistry.IModel>;
+  /**
+   * The command registry used to dispatch the reveal command.
+   */
   commands: CommandRegistry;
+  /**
+   * The application translation bundle.
+   */
   trans: TranslationBundle;
 }
 
@@ -38,9 +48,8 @@ export class EditorBreadcrumbs extends Widget {
     this._commands = options.commands;
     this._trans = options.trans;
     this.addClass(EDITOR_BREADCRUMBS_CLASS);
-    // The breadcrumbs stretch to fill the toolbar, so ReactiveToolbar's
-    // overflow math must count them as a spacer (2px) — measured at their
-    // stretched clientWidth they would evict every item into the popup.
+    // ReactiveToolbar must count the stretched breadcrumbs as a spacer (2px);
+    // measured at clientWidth they would evict every item into the popup.
     this.addClass(TOOLBAR_SPACER_CLASS);
     this.node.setAttribute('aria-label', this._trans.__('Editor file path'));
 
@@ -55,6 +64,9 @@ export class EditorBreadcrumbs extends Widget {
     this._render();
   }
 
+  /**
+   * Dispose of the resources held by the widget.
+   */
   dispose(): void {
     if (this.isDisposed) {
       return;
@@ -81,9 +93,7 @@ export class EditorBreadcrumbs extends Widget {
     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.
+      // Canonical @pierre/trees paths: directories carry a trailing slash.
       const canonical = isLast ? subPath : `${subPath}/`;
 
       const item = document.createElement('span');
@@ -117,19 +127,15 @@ export class EditorBreadcrumbs extends Widget {
     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.
+    // Empty path is the workspace-root gesture; the tree has no row for
+    // the 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.
+   * Bind click and keyboard activation on a crumb to the reveal command;
+   * dispatch failures are logged, never thrown into the toolbar.
    */
   private _attachReveal(element: HTMLElement, canonicalPath: string): void {
     const fire = (event: Event): void => {

package/src/editorIndent/index.ts

@@ -14,10 +14,8 @@ 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`.
+ * 2-space fallback for new or undetectable files, matching Prettier's
+ * web-language defaults; unlisted mime types keep the user's setting.
  */
 const FALLBACK_INDENT_BY_MIME: Record<string, number> = {
   'application/ecmascript': 2,
@@ -38,15 +36,20 @@ const FALLBACK_INDENT_BY_MIME: Record<string, number> = {
   'text/yaml': 2
 };
 
+/**
+ * The indentation resolved for a document.
+ */
 interface IResolvedIndent {
+  /**
+   * The string inserted per indent level (spaces or a tab), for `indentUnit`.
+   */
   unit: string;
+  /**
+   * The indent width in columns, for `EditorState.tabSize`.
+   */
   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;
@@ -76,9 +79,8 @@ function resolveIndent(text: string, mimeType: string): IResolvedIndent | null {
 }
 
 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.
+  // `Prec.highest` beats both `defaultConfig` and per-editor
+  // `editorConfig.indentUnit`, which JupyterLab registers at default precedence.
   return Prec.highest([
     indentUnit.of(resolved.unit),
     EditorState.tabSize.of(resolved.width)
@@ -86,18 +88,10 @@ function buildExtension(resolved: IResolvedIndent): Extension {
 }
 
 /**
- * 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.
+ * Sniff each document's indentation and configure CodeMirror's `indentUnit` /
+ * `tabSize` to match, since JupyterLab only has one global indent setting.
+ * Detection reruns on the first content change: the collaborative loader can
+ * settle the file body after the editor view exists, so the factory may see ''.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,

package/src/fileBrowser/commands.ts

@@ -32,11 +32,9 @@ import { toCanonicalPath, toServerPath } from './contents';
 import { FILE_BROWSER_ID, IXtralabFileBrowser } from './widget';
 
 /**
- * Command identifiers exposed by the xtralab browser. We deliberately namespace
- * these under `xtralab:` rather than reusing the `filebrowser:` ids
- * because the core `filebrowser:*` commands look up a `FileBrowser` instance
- * via `IFileBrowserFactory.tracker` — our widget is not a `FileBrowser`, so
- * those handlers would never see it.
+ * Command ids for the xtralab browser. Namespaced `xtralab:` rather than
+ * reusing the `filebrowser:` ids: the core handlers resolve their target via
+ * `IFileBrowserFactory.tracker`, which never sees this widget.
  */
 export namespace CommandIDs {
   export const open = 'xtralab:open';
@@ -56,27 +54,40 @@ export namespace CommandIDs {
 }
 
 /**
- * Submenu id used to host the dynamically populated "Open With" entries.
- * Distinct from the core file browser's `jp-contextmenu-open-with` so the
- * core's populator does not try to fill ours with items derived from the
- * default file browser's selection.
+ * "Open With" submenu id. Distinct from the core `jp-contextmenu-open-with`
+ * so the core's populator does not fill ours from its own selection.
  */
 const OPEN_WITH_SUBMENU_ID = 'jp-contextmenu-xtralab-open-with';
 
+/**
+ * Options for registering the xtralab file browser commands.
+ */
 interface IRegisterCommandsOptions {
+  /**
+   * The JupyterLab application the commands are registered on.
+   */
   app: JupyterFrontEnd;
+  /**
+   * The file browser widget the commands act on.
+   */
   browser: IXtralabFileBrowser;
+  /**
+   * The document manager used to resolve the current widget's file path.
+   */
   docManager: IDocumentManager;
+  /**
+   * The command palette the commands are added to, or `null` when unavailable.
+   */
   palette: ICommandPalette | null;
+  /**
+   * The translator for user-facing strings; `null` falls back to English.
+   */
   translator: ITranslator | null;
 }
 
 /**
- * Resolve the path of the item the user right-clicked. We prefer the
- * contextmenu event's target — that is how `app.contextMenu` resolves which
- * items match a selector — and fall back to the first item in the tree's
- * selection if the command was invoked without an active contextmenu event
- * (e.g. from the command palette).
+ * Path of the right-clicked item, from the contextmenu event's target;
+ * falls back to the tree selection when invoked without one (the palette).
  */
 function getTargetPath(
   app: JupyterFrontEnd,
@@ -92,11 +103,6 @@ function getTargetPath(
   return browser.selectedPaths[0];
 }
 
-/**
- * Resolve the kind of the item that was right-clicked, based on the data
- * attributes emitted by `@pierre/trees` rows. Returns `undefined` if no
- * contextmenu event is active or the target is not a tree item.
- */
 function getTargetKind(app: JupyterFrontEnd): 'file' | 'folder' | undefined {
   const node = app.contextMenuHitTest(
     n => n.dataset !== undefined && n.dataset.type === 'item'
@@ -106,14 +112,9 @@ function getTargetKind(app: JupyterFrontEnd): 'file' | 'folder' | undefined {
 }
 
 /**
- * Resolve the canonical paths the "Open" command should act on. When the
- * user right-clicks a row that is part of the current selection, every
- * selected file is opened — matching the default file browser, where
- * "Open" on any file in a multi-selection opens them all. If the
- * right-clicked row is *not* in the selection, only that row is opened.
- *
- * Folders are always filtered out: there is no "current directory" in
- * this tree, so opening a folder via "Open" is a no-op.
+ * Canonical paths "Open" acts on: the whole selection when the right-clicked
+ * row is part of it (matching the default browser), else just that row.
+ * Folders are filtered out — this tree has no "current directory".
  */
 function getOpenPaths(
   app: JupyterFrontEnd,
@@ -134,9 +135,6 @@ function getOpenPaths(
   return candidates.filter(path => !path.endsWith('/'));
 }
 
-/**
- * True iff there is an actionable target for a command on the right-click.
- */
 function hasTarget(
   app: JupyterFrontEnd,
   browser: IXtralabFileBrowser
@@ -145,11 +143,9 @@ function hasTarget(
 }
 
 /**
- * Resolve the directory used as the working directory for actions that
- * create a new file or folder. Folder selections become their own cwd;
- * file selections fall back to their parent. Returns the empty string
- * when the tree has no selection — that matches the contents API's
- * convention for "the root directory".
+ * Working directory for create actions: a selected folder is its own cwd, a
+ * file falls back to its parent; empty string (the contents-API root) when
+ * nothing is selected.
  */
 function getWorkingDirectory(browser: IXtralabFileBrowser): string {
   const first = browser.selectedPaths[0];
@@ -164,14 +160,10 @@ function getWorkingDirectory(browser: IXtralabFileBrowser): string {
 }
 
 /**
- * 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.
+ * Main-area widget whose tab is the target of the current context-menu
+ * event, or `null`. `contextMenuHitTest` reads the last context-menu event,
+ * which is not cleared when the menu closes, so callers must gate against
+ * resolving a stale tab.
  */
 function contextMenuTabWidget(app: JupyterFrontEnd): Widget | null {
   const node = app.contextMenuHitTest(
@@ -190,10 +182,9 @@ function contextMenuTabWidget(app: JupyterFrontEnd): Widget | 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.
+ * Canonical path of the document to reveal: the right-clicked tab when
+ * `fromContextMenu` is true (the file-tab menu), else the active main-area
+ * widget (the palette).
  */
 function documentPathToReveal(
   app: JupyterFrontEnd,
@@ -211,14 +202,10 @@ function documentPathToReveal(
 }
 
 /**
- * Refresh the "Open With" submenu's items from the document factories that
- * can open the file under the right-click. Mirrors the
- * `@jupyterlab/filebrowser-extension:open-with` pattern: the schema declares
- * an empty submenu by id, and we look it up on the open context menu and
- * fill it before the user can hover.
- *
+ * Build the populator that fills the "Open With" submenu on every
+ * context-menu open, mirroring `filebrowser-extension:open-with`.
  * `preferredWidgetFactories(path)` is path-only, so the populator stays
- * synchronous and the submenu is ready before the user can hover over it.
+ * synchronous and the submenu is ready before the user can hover.
  */
 function makeOpenWithUpdater(
   app: JupyterFrontEnd,
@@ -259,13 +246,9 @@ function makeOpenWithUpdater(
 }
 
 /**
- * Register every xtralab command on the application command registry, attach
- * the items to the application context menu, and wire up the dynamic
- * "Open With" submenu populator.
- *
- * @returns A function that detaches the menu items and signal listener.
- *   The commands themselves are owned by the registry for the lifetime of
- *   the plugin.
+ * Register the xtralab commands, context-menu wiring, and the dynamic
+ * "Open With" populator. Returns a detach function; the commands themselves
+ * stay owned by the registry.
  */
 export function registerCommands(opts: IRegisterCommandsOptions): () => void {
   const { app, browser, docManager, palette, translator } = opts;
@@ -496,23 +479,16 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
-  // Refresh the toggle's state however the filter is shown or hidden —
-  // the toolbar button, or the auto-show that kicks in when typing with
-  // the tree focused opens a search session.
+  // The filter can also auto-show when typing with the tree focused, so
+  // track visibility changes rather than the command's own executions.
   const onFilterVisibleChanged = (): void => {
     commands.notifyCommandChanged(CommandIDs.toggleFileFilter);
   };
   browser.fileFilterVisibleChanged.connect(onFilterVisibleChanged);
 
-  // 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.
-  // The tree is movable, so surface whichever sidebar widget holds it.
+  // Public reveal seam for other plugins; an empty path is the workspace-root
+  // gesture (the root has no tree row of its own). The tree is movable, so
+  // surface whichever sidebar widget holds it.
   const activateTreeHost = (): void => {
     for (const area of ['left', 'right']) {
       for (const widget of app.shell.widgets(area)) {
@@ -538,8 +514,6 @@ 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'),
@@ -579,10 +553,8 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
   commands.addCommand(CommandIDs.newLauncher, {
     label: trans.__('New Launcher'),
     caption: trans.__('Open a new launcher'),
-    // Skip the `menuItem` bindprops the other commands use: this command
-    // lives on the toolbar, where the launcher-extension's blue button
-    // styling expects the raw `jp-icon3` paths from `addIcon` so it can
-    // recolor them against the brand background.
+    // Raw `addIcon`, no `menuItem` bindprops: the launcher-extension's blue
+    // toolbar-button styling recolors the raw `jp-icon3` paths.
     icon: addIcon,
     execute: () => {
       const cwd = getWorkingDirectory(browser);
@@ -590,34 +562,24 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
-  // Re-evaluate enabled/visible state when the user changes the tree
-  // selection, in case a command's predicate depends on the selection.
   browser.selectionChanged.connect(() => {
     for (const id of Object.values(CommandIDs)) {
       commands.notifyCommandChanged(id);
     }
   });
 
-  // 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
-  // `OPEN_WITH_SUBMENU_ID`; we fill it on every open from the document
-  // factories that can open the right-clicked file.
+  // Static context-menu items live in `schema/plugin.json` so users can
+  // override them; the schema declares the empty "Open With" placeholder.
   const updateOpenWithMenu = makeOpenWithUpdater(app, browser);
   app.contextMenu.opened.connect(updateOpenWithMenu);
 
@@ -630,9 +592,8 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
 }
 
 /**
- * The names we register with the toolbar. Kept distinct from
- * {@link CommandIDs} because the toolbar API uses opaque names rather
- * than commands.
+ * Toolbar item names, distinct from {@link CommandIDs}: the toolbar API
+ * uses opaque names rather than commands.
  */
 export namespace ToolbarNames {
   export const newLauncher = 'new-launcher';
@@ -643,10 +604,8 @@ export namespace ToolbarNames {
 }
 
 /**
- * Populate the file browser's toolbar with the buttons that mirror the
- * default JupyterLab file browser: a "+" launcher button, a new-folder
- * button, a refresh button, a collapse-all button, and the file filter
- * toggle.
+ * Populate the toolbar with the buttons that mirror the default JupyterLab
+ * file browser.
  */
 export function populateToolbar(opts: {
   app: JupyterFrontEnd;