xtralab 0.15.0 → 0.15.2

package/src/launcher/editors.ts

@@ -3,11 +3,10 @@ import { LabIcon, textEditorIcon } from '@jupyterlab/ui-components';
 import { BUILTIN_EDITOR_ICONS } from './icons';
 
 /**
- * A terminal text editor surfaced on the launcher's "Open" section. An editor
- * takes no initial prompt and is launched by typing its command into a fresh
- * terminal (e.g. `nvim`). The launcher shows a single editor tile (the first
- * available candidate; see {@link resolveEditor}); the full list is shared with
- * the terminals panel to badge running editors.
+ * A terminal text editor on the launcher's "Open" section, launched by typing
+ * its command into a fresh terminal. The launcher shows one tile
+ * ({@link resolveEditor}); the full list badges running editors in the
+ * terminals panel.
  */
 export interface IEditor {
   /**
@@ -31,57 +30,59 @@ export interface IEditor {
    */
   icon: LabIcon;
   /**
-   * Preference order for the single launcher tile: the first candidate, by
-   * ascending rank, that qualifies wins (Neovim before Vim by default).
+   * Preference order: the first qualifying candidate by rank wins the tile.
    */
   rank: number;
   /**
-   * When false, the launcher skips the `which`-based availability check for
-   * this entry — useful for a shell alias or function that isn't on PATH but
-   * still resolves when typed in a real terminal. Defaults to true.
+   * When false, skip the `which`-based availability check — for aliases or
+   * shell functions not on PATH. Defaults to true.
    */
   requireAvailable: boolean;
 }
 
 /**
- * The settings-side shape: every field except `id` is optional, so a user can
- * override a single field on a built-in editor (e.g. swap `vim`'s command for
- * a wrapper) without restating the whole entry. New ids define brand-new
- * editors. Mirrors `IAgentSettings` minus `promptArgs`.
+ * The settings-side shape: every field except `id` is optional so a user can
+ * override a single field on a built-in editor; new ids define new editors.
+ * Mirrors `IAgentSettings` minus `promptArgs`.
  */
 export interface IEditorSettings {
+  /**
+   * Id of the editor to override; a new id defines a new editor.
+   */
   id: string;
+  /**
+   * See {@link IEditor.label}.
+   */
   label?: string;
+  /**
+   * See {@link IEditor.caption}.
+   */
   caption?: string;
+  /**
+   * See {@link IEditor.command}.
+   */
   command?: string;
   /**
-   * Inline SVG for a custom editor's icon. Required for new ids whose icon
-   * isn't shipped with xtralab; ignored for built-in ids unless explicitly
-   * set (in which case it overrides the built-in).
+   * Inline SVG icon. Required for new ids; overrides the built-in when set on
+   * a built-in id.
    */
   iconSvg?: string;
+  /**
+   * See {@link IEditor.rank}.
+   */
   rank?: number;
   /**
-   * When false, the editor is hidden from the launcher's Open section (and no
-   * longer recognised by the terminals panel). Disable both built-ins to drop
-   * the editor tile entirely. Defaults to true.
+   * When false, hides the editor. Disable both built-ins to drop the editor
+   * tile entirely.
    */
   enabled?: boolean;
   /**
-   * See {@link IEditor.requireAvailable}. Defaults to true for a built-in
-   * editor that still uses its shipped command, and to false once you override
-   * the `command` (a user-chosen command — often a shell alias — is trusted and
-   * always shown). Set it explicitly to force the check on or off.
+   * See {@link IEditor.requireAvailable}. Defaults to true, but flips to false
+   * once `command` is overridden (a user-chosen alias is trusted).
    */
   requireAvailable?: boolean;
 }
 
-/**
- * Built-in editor candidates in preference order. The launcher shows the first
- * one whose command resolves on the server's `$PATH`, so Neovim wins over Vim
- * when both are installed. Users override, disable, or extend this list
- * through the `editors` setting; see {@link mergeEditors}.
- */
 const DEFAULTS: IEditor[] = [
   {
     id: 'nvim',
@@ -104,11 +105,8 @@ const DEFAULTS: IEditor[] = [
 ];
 
 /**
- * The built-in editors projected into the JSON settings shape
- * ({@link IEditorSettings}), dropping the runtime-only {@link LabIcon}. Mirrors
- * {@link defaultAgentSettings}: {@link registerLauncherSchemaDefaults} injects
- * this as the `editors` setting's schema default so the Settings Editor shows
- * the shipped list.
+ * The built-in editors projected into the settings shape (no runtime LabIcon),
+ * injected as the `editors` schema default so the Settings Editor shows them.
  */
 export function defaultEditorSettings(): IEditorSettings[] {
   return DEFAULTS.map(editor => ({
@@ -132,13 +130,9 @@ function resolveEditorIcon(id: string, iconSvg: string | undefined): LabIcon {
 }
 
 /**
- * Merge xtralab's built-in editors with the user's `editors` settings. Built-in
- * entries keep their fields unless explicitly overridden; user-only entries are
- * appended. `enabled: false` filters an entry out of the result entirely (so
- * callers don't need to re-check the flag). The result is sorted by rank, which
- * is also the launcher's tile-preference order. Mirrors `mergeAgents`, including
- * turning `requireAvailable` off when the user overrides a built-in's `command`
- * so an aliased editor still shows.
+ * Merge the built-in editors with the user's `editors` settings; the result is
+ * sorted by rank, the tile-preference order. Mirrors `mergeAgents`, including
+ * turning `requireAvailable` off when a built-in's `command` is overridden.
  */
 export function mergeEditors(overrides: IEditorSettings[]): IEditor[] {
   const overrideById = new Map(overrides.map(entry => [entry.id, entry]));
@@ -164,10 +158,6 @@ export function mergeEditors(overrides: IEditorSettings[]): IEditor[] {
         ? resolveEditorIcon(base.id, override.iconSvg)
         : base.icon,
       rank: override.rank ?? base.rank,
-      // See `mergeAgents`: once the user points a built-in editor at their own
-      // command (e.g. a shell alias `which` can't resolve), stop requiring
-      // availability so the tile still shows. The check stays on only while the
-      // command is xtralab's default.
       requireAvailable:
         command === base.command
           ? (override.requireAvailable ?? base.requireAvailable)
@@ -175,9 +165,6 @@ export function mergeEditors(overrides: IEditorSettings[]): IEditor[] {
     });
   }
 
-  // What remains in `overrideById` are ids that don't match a built-in — treat
-  // them as new editors the user is adding. Skip disabled ones; the settings
-  // schema validates the shape, so missing fields just fall back here.
   let nextRank =
     merged.reduce((max, editor) => Math.max(max, editor.rank), -1) + 1;
   for (const entry of overrideById.values()) {
@@ -202,15 +189,9 @@ export function mergeEditors(overrides: IEditorSettings[]): IEditor[] {
 }
 
 /**
- * Pick the single editor tile to show, given the merged editor list and the
- * set of commands known to be on `$PATH` (from the launcher's availability
- * probe). Returns the first candidate, by rank, that is either available or
- * opts out of the check (`requireAvailable: false`) — Neovim before Vim by
- * default — or `null` when none qualifies.
- *
- * When `available` is `null` (the endpoint couldn't be reached), a
- * `requireAvailable` editor is not shown; an entry with
- * `requireAvailable: false` is shown regardless.
+ * Pick the single tile: the first editor, by rank, that is available or opts
+ * out of the check, else `null`. When `available` is `null` (probe failed),
+ * only `requireAvailable: false` entries qualify.
  */
 export function resolveEditor(
   editors: IEditor[],

package/src/launcher/icons.ts

@@ -1,33 +1,11 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 
 /**
- * Brand icons for the agent launcher cards. Most marks are taken verbatim
- * from `jupyter-ai-contrib/jupyter-ai-acp-client`
- * (`jupyter_ai_acp_client/static/*.svg`, BSD-3-Clause); Antigravity post-dates
- * that set, so its mark is the official glyph from `@lobehub/icons-static-svg`
- * (MIT) — we ship the brand-colored `antigravity-color` variant so Antigravity
- * reads as a multi-color Google mark. Pi's mark is the official `logo-auto.svg`
- * from https://pi.dev (MIT, `earendil-works/pi`). Small adjustments are applied
- * to play nicely with JupyterLab themes:
- *   - Monochrome marks (Codex, Copilot, Goose, Pi) use `currentColor` so they
- *     inherit the surrounding launcher card's text color rather than
- *     hard-coding black, which disappears on the dark theme. For Pi this
- *     replaces the upstream `prefers-color-scheme` style block, which follows
- *     the OS scheme rather than the active JupyterLab theme.
- *   - The Goose mark upstream is rendered on a white rounded rect; we drop
- *     the rect so the silhouette can sit on the launcher card directly.
- *   - SVG ids that would collide if two copies of the same artwork ended up
- *     on the page (gradient/mask/filter defs) are namespaced under
- *     `xtralab-…`.
- *
- * Brand-colored icons (Antigravity, Claude, Kiro, Mistral Vibe, OpenCode) keep
- * their upstream colors; the dark/light contrast of the launcher card behind
- * them is the same as on `jupyter-ai-acp-client`.
- *
- * The Vim and Neovim marks belong to the launcher's "Open" editor tile rather
- * than the agent grid. They are the brand silhouettes from Simple Icons
- * (https://simpleicons.org, CC0), each filled with its brand green so the mark
- * reads on both the light and dark themes.
+ * Brand icons for the launcher cards: `jupyter-ai-contrib/jupyter-ai-acp-client`
+ * (BSD-3-Clause), except Antigravity (`@lobehub/icons-static-svg`, MIT),
+ * Pi (pi.dev, MIT) and Vim/Neovim (Simple Icons, CC0). Monochrome marks use
+ * `currentColor` to follow the active theme; svg ids are namespaced under
+ * `xtralab-…` so two copies of one mark on a page don't collide.
  */
 
 const antigravityIcon = new LabIcon({
@@ -204,12 +182,6 @@ const vimIcon = new LabIcon({
 </svg>`
 });
 
-/**
- * Built-in icons keyed by the agent's id, used to resolve the icon for an
- * agent declared without an inline `iconSvg` override (i.e. one of xtralab's
- * defaults). Custom agents added via settings can either supply their own
- * `iconSvg` or fall back to the generic terminal icon.
- */
 export const BUILTIN_AGENT_ICONS: Record<string, LabIcon> = {
   antigravity: antigravityIcon,
   claude: claudeIcon,
@@ -222,12 +194,6 @@ export const BUILTIN_AGENT_ICONS: Record<string, LabIcon> = {
   pi: piIcon
 };
 
-/**
- * Built-in icons keyed by the editor's id, used to resolve the icon for a
- * built-in editor (Neovim, Vim) declared without an inline `iconSvg`. Custom
- * editors added via settings can supply their own `iconSvg` or fall back to
- * the generic text-editor icon.
- */
 export const BUILTIN_EDITOR_ICONS: Record<string, LabIcon> = {
   nvim: neovimIcon,
   vim: vimIcon

package/src/launcher/index.ts

@@ -25,26 +25,10 @@ import { IAgentRegistry } from './tokens';
 const PLUGIN_ID = 'xtralab:launcher';
 
 /**
- * The xtralab launcher plugin. Replaces the stock JupyterLab launcher
- * (which is disabled via `package.json`'s `jupyterlab.disabledExtensions`)
- * with an agent-focused dashboard: an optional initial prompt, a row of
- * agent buttons (Claude, Codex, Antigravity, …), and a collapsible list of
- * changed files (clickable into the diff viewer) below them. Clicking an
- * agent opens a fresh terminal and pipes the agent's command into it; if
- * the prompt textarea is non-empty, the prompt is shell-quoted and
- * spliced into the launch line per the agent's `promptArgs` recipe.
- *
- * The agent list is the merge of xtralab's defaults with the user's
- * `xtralab:launcher` settings, then filtered by a server-side `which`
- * check so users only see agents that are actually installed. Agents with
- * `requireAvailable: false` skip the filter, as does any built-in whose
- * `command` the user has overridden (a user-chosen command — often a shell
- * alias the server can't resolve — is trusted and always shown).
- *
- * The plugin deliberately does NOT provide the `ILauncher` token: other
- * extensions register notebook/console/terminal cards on it as a side
- * effect, which would defeat the point of the agent-only launcher. If an
- * extension needs to surface itself, we'll add it here explicitly.
+ * The xtralab launcher plugin: replaces the stock JupyterLab launcher
+ * (disabled via `jupyterlab.disabledExtensions`) with an agent-focused
+ * dashboard. It deliberately does NOT provide `ILauncher` — other extensions
+ * would register their cards on it and defeat the agent-only design.
  */
 const plugin: JupyterFrontEndPlugin<IAgentRegistry> = {
   id: PLUGIN_ID,
@@ -72,23 +56,13 @@ const plugin: JupyterFrontEndPlugin<IAgentRegistry> = {
     const { commands, shell } = app;
     const trans = (translator ?? nullTranslator).load('jupyterlab');
 
-    // The shared agent registry this plugin provides on `IAgentRegistry`.
-    // It holds the active agent list (updated whenever settings change), so
-    // every freshly-created launcher widget — and any other plugin that
-    // consumes the token, e.g. the terminals panel — renders the latest list.
     const registry = new AgentRegistry();
 
-    // Track command registrations so a settings change can wipe them
-    // before re-registering — without this the command palette would
-    // accumulate stale entries when the agent list shrinks.
     let registered: IDisposable | null = null;
 
     const applyAgents = async (overrides: IAgentSettings[]): Promise<void> => {
       const agents = mergeAgents(overrides);
 
-      // Probe the server's `$PATH` so we only surface agents that are actually
-      // installed. Agents with `requireAvailable: false` opt out (their command
-      // may be a shell alias that `which` can't see) and are kept regardless.
       const probe = Array.from(
         new Set(
           agents
@@ -131,8 +105,6 @@ const plugin: JupyterFrontEndPlugin<IAgentRegistry> = {
         });
       } catch (reason) {
         console.error('xtralab: failed to load launcher settings', reason);
-        // Settings load failed — fall back to defaults so the launcher
-        // still has cards instead of going silent.
         await applyAgents([]);
       }
     } else {
@@ -144,11 +116,8 @@ const plugin: JupyterFrontEndPlugin<IAgentRegistry> = {
       execute: (args: ReadonlyPartialJSONObject) => {
         const id = Private.nextId();
         const onAgentLaunch = (item: Widget): void => {
-          // When an agent command returns a Widget that ends up in the main
-          // area, slot it where this launcher used to sit so opening an
-          // agent feels like the launcher transformed into the terminal.
-          // Disposing the inner ReactWidget cascades to the MainAreaWidget
-          // host via its `content.disposed` connection.
+          // Slot the widget where this launcher sits; disposing the inner
+          // ReactWidget cascades to its MainAreaWidget host via `content.disposed`.
           if (find(shell.widgets('main'), w => w === item)) {
             shell.add(item, 'main', { ref: id });
             launcher.dispose();
@@ -160,9 +129,6 @@ const plugin: JupyterFrontEndPlugin<IAgentRegistry> = {
           editor: editorRegistry?.current ?? null,
           agentSessions,
           onAgentLaunch,
-          // Empty repoPath/cwd matches the JupyterLab convention used by
-          // the git panel and the stock launcher: let the server resolve
-          // the working tree from its root directory.
           repoPath: '',
           cwd: '',
           trans
@@ -171,9 +137,7 @@ const plugin: JupyterFrontEndPlugin<IAgentRegistry> = {
         launcher.title.label = trans.__('Launcher');
 
         const main = new MainAreaWidget({ content: launcher });
-        // Hide the close button when the launcher is the only thing in the
-        // main area: closing it would leave the user staring at an empty
-        // shell with no way back.
+        // Closing the only main-area widget would leave an empty shell.
         main.title.closable = !!Array.from(shell.widgets('main')).length;
         main.id = id;
 
@@ -210,9 +174,7 @@ const plugin: JupyterFrontEndPlugin<IAgentRegistry> = {
         labShell.layoutModified.connect(() => {
           maybeCreate();
         });
-        // Layout has settled by the time `app.restored` resolves; if it's
-        // empty (fresh start, no restored widgets) the connect above won't
-        // fire on its own — kick it off here.
+        // If the restored layout is already empty the connect never fires.
         maybeCreate();
       });
 
@@ -230,14 +192,9 @@ const plugin: JupyterFrontEndPlugin<IAgentRegistry> = {
 };
 
 /**
- * Drop agents whose command isn't on `$PATH`, except entries that opt out via
- * `requireAvailable: false` (e.g. shell aliases the user wants surfaced
- * regardless). `available` is the resolved set from
- * {@link fetchAvailableCommands}.
- *
- * When `available` is `null` (the endpoint couldn't be reached) we fail open
- * and return the input unchanged — better to show an unreachable agent than
- * to hide the entire launcher because the server extension didn't load.
+ * Drop agents whose command isn't on `$PATH`, keeping `requireAvailable:
+ * false` entries. When `available` is `null` (probe failed), fail open and
+ * return the input unchanged.
  */
 function filterAgents(
   agents: IAgent[],
@@ -255,7 +212,7 @@ namespace Private {
   let counter = 0;
 
   /**
-   * Returns the next unique launcher widget id.
+   * Generate a unique id for a launcher widget.
    */
   export function nextId(): string {
     return `launcher-${counter++}`;

package/src/launcher/invocation.ts

@@ -1,18 +1,9 @@
 import type { IAgent } from './agents';
 
 /**
- * Quote a string so it can be safely passed as a single argument on a
- * bash/zsh command line that is *typed into an interactive terminal* —
- * not the usual file-parsing context.
- *
- * The distinction matters: an actual newline byte (0x0A) sent into a PTY
- * is interpreted by the line discipline as Enter regardless of whether
- * it sits inside `'...'` quotes, so the shell never sees the closing
- * quote. We therefore use ANSI-C `$'...'` quoting and emit `\n` (and
- * `\r`) as their two-character escape sequences; the shell expands them
- * to real newlines after the line is submitted, when readline is no
- * longer involved. Backslashes and single quotes are escaped first so
- * the source text round-trips unchanged.
+ * Quote a string for a command line typed into an interactive terminal. A raw
+ * newline sent to a PTY acts as Enter even inside '…' quotes, so ANSI-C
+ * `$'…'` quoting emits `\n`/`\r` as escapes the shell expands after submit.
  */
 function shellQuote(value: string): string {
   const escaped = value
@@ -24,16 +15,10 @@ function shellQuote(value: string): string {
 }
 
 /**
- * Compose the literal command line typed into a fresh terminal for `agent`.
- * When `prompt` is empty (or whitespace-only), this is just `agent.command`.
- * When non-empty, the prompt is shell-quoted and spliced in using the
- * agent's `promptArgs` recipe — see `IAgent.promptArgs` for the encoding.
- *
- * Returns `agent.command` unchanged when the agent declares no prompt
- * support (`promptArgs === undefined`), so a stray prompt typed into the
- * launcher does not silently mutate the launch line for that agent. The
- * launcher UI separately prevents the click in that case so the dropped
- * prompt is never surprising to the user.
+ * Compose the literal command line typed into a fresh terminal for `agent`:
+ * the shell-quoted prompt is spliced in per the `promptArgs` recipe. Returns
+ * bare `agent.command` when the prompt is empty or the agent has no prompt
+ * support.
  */
 export function buildAgentInvocation(agent: IAgent, prompt: string): string {
   const trimmed = prompt.trim();

package/src/launcher/registry.ts

@@ -4,24 +4,26 @@ import type { IAgent } from './agents';
 import type { IAgentRegistry } from './tokens';
 
 /**
- * The concrete {@link IAgentRegistry} the launcher plugin provides on the
- * `IAgentRegistry` token. Holds the active agent list and re-emits `changed`
- * whenever the launcher recomputes it (on a settings change). The launcher
- * is the only writer, so the write side ({@link setAgents}) is kept off the
- * shared token.
+ * Concrete {@link IAgentRegistry} the launcher plugin provides. The launcher
+ * is the only writer, so {@link setAgents} is kept off the shared token.
  */
 export class AgentRegistry implements IAgentRegistry {
+  /**
+   * The current agents, filtered by availability and sorted by rank.
+   */
   get agents(): IAgent[] {
     return this._agents;
   }
 
+  /**
+   * Emitted whenever {@link agents} changes.
+   */
   get changed(): ISignal<IAgentRegistry, void> {
     return this._changed;
   }
 
   /**
-   * Replace the agent list and notify observers. Called by the launcher
-   * after merging the user's settings and filtering by availability.
+   * Replace the agent list and notify observers.
    */
   setAgents(agents: IAgent[]): void {
     this._agents = agents;

package/src/launcher/tokens.ts

@@ -4,35 +4,26 @@ import type { ISignal } from '@lumino/signaling';
 import type { IAgent } from './agents';
 
 /**
- * A read-only, observable view of the launcher's available agents.
- *
- * The launcher plugin owns the agent list — xtralab's defaults merged with
- * the user's `xtralab:launcher` settings, then filtered by a server-side
- * `which` check — and registers an `xtralab:start-agent:<id>` command for
- * each entry. This token shares that list, and (via {@link agentCommandId})
- * the command id that launches each agent, so other plugins can surface the
- * same agents without re-deriving the list or duplicating the icons. The
- * terminals panel uses it to build its "new terminal" dropdown.
+ * A read-only, observable view of the launcher's available agents — the
+ * merged, availability-filtered list the launcher renders — shared so other
+ * plugins (e.g. the terminals panel) can surface the same agents and icons.
  */
 export interface IAgentRegistry {
   /**
-   * The current agents, already filtered by availability and sorted by
-   * rank — the same array the launcher renders.
+   * The current agents, filtered by availability and sorted by rank.
    */
   readonly agents: IAgent[];
 
   /**
-   * Emitted whenever {@link agents} changes (e.g. the user edits the
-   * launcher settings). Consumers that cache the list should re-read it
-   * here; consumers that read it on demand can ignore the signal.
+   * Emitted whenever {@link agents} changes.
    */
   readonly changed: ISignal<IAgentRegistry, void>;
 }
 
 /**
- * DI token for {@link IAgentRegistry}. Provided by `xtralab:launcher` and
- * consumed — optionally, so the panel still works when the launcher is
- * disabled — by `xtralab:terminals`.
+ * DI token for {@link IAgentRegistry}. Provided by `xtralab:launcher`;
+ * consumers depend on it optionally so they survive the launcher being
+ * disabled.
  */
 export const IAgentRegistry = new Token<IAgentRegistry>(
   'xtralab:IAgentRegistry',
@@ -40,11 +31,8 @@ export const IAgentRegistry = new Token<IAgentRegistry>(
 );
 
 /**
- * The JupyterLab command id that launches a given agent in a new terminal.
- * Defined here — in the shared contract module rather than the launcher's
- * command-registration internals — so the launcher (which registers the
- * commands) and any consumer (which references them, e.g. in a menu) agree
- * on the id.
+ * The command id that launches a given agent in a new terminal, defined in
+ * the shared contract module so the launcher and consumers agree on it.
  */
 export function agentCommandId(agentId: string): string {
   return `xtralab:start-agent:${agentId}`;

package/src/menuBar/index.ts

@@ -18,25 +18,15 @@ const OPEN_COMMAND = 'xtralab:open-main-menu';
 const TOGGLE_COMMAND = 'xtralab:toggle-menu-bar';
 
 /**
- * How long after the popup closes a button press still counts as "close
- * only". An open Lumino menu closes itself on any outside press from a
- * document `pointerdown` listener in the capture phase, which runs before
- * the button's own mousedown handler — so without this window, pressing the
- * button while the popup is open would close it and instantly reopen it.
+ * Guard after the popup closes: Lumino menus close on a capture-phase document
+ * pointerdown, before the button's mousedown, which would instantly reopen.
  */
 const REOPEN_GUARD_MS = 250;
 
 /**
- * Collapse the main menu bar into a compact menu button.
- *
- * The menu bar is hidden and a hamburger button in the top bar opens the same
- * menus as a vertical popup. The popup reuses the live `RankedMenu` instances
- * owned by the `MainMenu`, so menus added or removed at runtime are reflected
- * without duplication.
- *
- * Hiding covers the `jp-menu-panel` container too, which has its own
- * `min-height` and would otherwise leave an empty strip. The "Show Menu Bar"
- * toggle restores the classic bar.
+ * Collapse the main menu bar into a hamburger button whose popup reuses the
+ * live `RankedMenu` instances owned by `MainMenu`. Hiding covers the
+ * `jp-menu-panel` container too — its `min-height` would leave an empty strip.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -84,9 +74,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
 
     const openMenu = (): void => {
       if (visible) {
-        // The classic bar is on screen; behave like keyboard menu
-        // activation instead of opening a redundant popup that would
-        // compete with the bar for the same Menu instances.
+        // With the classic bar on screen, act like keyboard menu activation —
+        // a popup would compete with the bar for the same Menu instances.
         mainMenu.activeIndex = 0;
         mainMenu.openActiveMenu();
         return;
@@ -95,13 +84,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
         return;
       }
 
-      // One popup instance, rebuilt from the bar's current menus on every
-      // open so runtime menu changes stay reflected. It is a plain Lumino
-      // Menu rather than a MenuSvg: MenuSvg.insertItem re-wraps each
-      // submenu's renderer and insertItem on every call, which would pile
-      // wrappers onto the shared menus across reopens. The svg renderer and
-      // themed-container class are applied directly instead, matching how
-      // the real menus are constructed in MainMenu.
+      // A plain Menu rebuilt on every open; MenuSvg.insertItem would re-wrap
+      // each submenu's renderer per reopen, piling wrappers onto the shared menus.
       if (popup === null) {
         popup = new Menu({ commands, renderer: MenuSvg.defaultRenderer });
         popup.addClass('jp-ThemedContainer');
@@ -183,9 +167,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
         loaded.changed.connect(update);
       })
       .catch(reason => {
-        // Without settings the collapsed state cannot be managed (and the
-        // button was never added) — reveal the stock bar rather than leave
-        // the app with no reachable menus.
+        // Without settings the collapsed state cannot be managed and the button
+        // was never added; reveal the stock bar so menus stay reachable.
         applyVisibility(true);
         console.error(`Failed to load settings for ${PLUGIN_ID}`, reason);
       });