xtralab 0.15.0 → 0.15.2

package/lib/launcher/icons.js

@@ -1,32 +1,10 @@
 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({
     name: 'xtralab:agent-antigravity',
@@ -191,12 +169,6 @@ const vimIcon = new LabIcon({
   <path d="M24 11.986h-.027l-4.318-4.318 4.303-4.414V1.461l-.649-.648h-8.198l-.66.605v1.045L12.015.027V0L12 .014 11.986 0v.027l-1.29 1.291-.538-.539H2.035l-.638.692v1.885l.616.616h.72v5.31L.027 11.987H0L.014 12 0 12.014h.027l2.706 2.706v6.467l.907.523h2.322l1.857-1.904 4.166 4.166V24l.015-.014.014.014v-.028l2.51-2.509h.485c.111 0 .211-.07.25-.179l.146-.426c.028-.084.012-.172-.037-.239l1.462-1.462-.612 1.962c-.043.141.036.289.177.332.025.008.052.012.078.012h1.824c.106-.001.201-.064.243-.163l.165-.394c.025-.065.024-.138-.004-.203-.027-.065-.08-.116-.146-.142-.029-.012-.062-.019-.097-.02h-.075l.84-2.644h1.232l-1.016 3.221c-.043.141.036.289.176.332.025.008.052.012.079.012h2.002c.11 0 .207-.066.248-.17l.164-.428c.051-.138-.021-.29-.158-.341-.029-.011-.06-.017-.091-.017h-.145l1.131-3.673c.027-.082.012-.173-.039-.24l-.375-.504-.003-.005c-.051-.064-.127-.102-.209-.102h-1.436c-.071 0-.141.03-.19.081l-.4.439h-.624l-.042-.046 4.445-4.445H24L23.986 12l.014-.014zM9.838 21.139l1.579-4.509h-.501l.297-.304h1.659l-1.563 4.555h.623l-.079.258H9.838zm3.695-7.516l.15.151-.269.922-.225.226h-.969l-.181-.181.311-.871.288-.247h.895zM5.59 20.829H3.877l-.262-.15V3.091H2.379l-.1-.1V1.815l.143-.154h7.371l.213.214v1.108l-.142.173H8.785v8.688l8.807-8.688h-2.086l-.175-.188V1.805l.121-.111h7.49l.132.133v1.07L12.979 13.25h-.373c-.015-.001-.028 0-.042.001l-.02.003c-.045.01-.086.03-.119.06l-.343.295-.004.003c-.033.031-.059.069-.073.111l-.296.83-6.119 6.276zm14.768-3.952l.474-.519h1.334l.309.415-1.265 4.107h.493l-.08.209H19.84l1.124-3.564h-2.015l-1.077 3.391h.424l-.073.174h-1.605l1.107-3.548h-2.096l-1.062 3.339h.436l-.072.209H13.27l1.514-4.46H14.198l.091-.271h1.65l.519.537h.906l.491-.554h1.061l.489.535h.953z"/>
 </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 = {
     antigravity: antigravityIcon,
     claude: claudeIcon,
@@ -208,12 +180,6 @@ export const BUILTIN_AGENT_ICONS = {
     opencode: opencodeIcon,
     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 = {
     nvim: neovimIcon,
     vim: vimIcon

package/lib/launcher/index.js

@@ -15,26 +15,10 @@ import { registerLauncherSchemaDefaults } from './schemaDefaults';
 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 = {
     id: PLUGIN_ID,
@@ -52,20 +36,10 @@ const plugin = {
     activate: async (app, labShell, palette, settingRegistry, translator, agentSessions, editorRegistry) => {
         const { commands, shell } = app;
         const trans = (translator !== null && translator !== void 0 ? 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 = null;
         const applyAgents = async (overrides) => {
             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
                 .filter(agent => agent.requireAvailable)
                 .map(agent => agent.command)));
@@ -97,8 +71,6 @@ const plugin = {
             }
             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([]);
             }
         }
@@ -111,11 +83,8 @@ const plugin = {
                 var _a;
                 const id = Private.nextId();
                 const onAgentLaunch = (item) => {
-                    // 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();
@@ -127,9 +96,6 @@ const plugin = {
                     editor: (_a = editorRegistry === null || editorRegistry === void 0 ? void 0 : editorRegistry.current) !== null && _a !== void 0 ? _a : 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
@@ -137,9 +103,7 @@ const plugin = {
                 launcher.title.icon = launcherIcon;
                 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;
                 shell.add(main, 'main', {
@@ -171,9 +135,7 @@ const plugin = {
                 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();
             });
             labShell.addButtonEnabled = true;
@@ -188,14 +150,9 @@ const plugin = {
     }
 };
 /**
- * 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, available) {
     if (!available) {
@@ -207,7 +164,7 @@ var Private;
 (function (Private) {
     let counter = 0;
     /**
-     * Returns the next unique launcher widget id.
+     * Generate a unique id for a launcher widget.
      */
     function nextId() {
         return `launcher-${counter++}`;

package/lib/launcher/invocation.d.ts

@@ -1,14 +1,8 @@
 import type { IAgent } from './agents';
 /**
- * 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 declare function buildAgentInvocation(agent: IAgent, prompt: string): string;

package/lib/launcher/invocation.js

@@ -1,16 +1,7 @@
 /**
- * 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) {
     const escaped = value
@@ -21,16 +12,10 @@ function shellQuote(value) {
     return `$'${escaped}'`;
 }
 /**
- * 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, prompt) {
     const trimmed = prompt.trim();

package/lib/launcher/registry.d.ts

@@ -2,18 +2,20 @@ import { ISignal } from '@lumino/signaling';
 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 declare class AgentRegistry implements IAgentRegistry {
+    /**
+     * The current agents, filtered by availability and sorted by rank.
+     */
     get agents(): IAgent[];
+    /**
+     * Emitted whenever {@link agents} changes.
+     */
     get changed(): ISignal<IAgentRegistry, void>;
     /**
-     * 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;
     private _agents;

package/lib/launcher/registry.js

@@ -1,25 +1,27 @@
 import { Signal } from '@lumino/signaling';
 /**
- * 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 {
     constructor() {
         this._agents = [];
         this._changed = new Signal(this);
     }
+    /**
+     * The current agents, filtered by availability and sorted by rank.
+     */
     get agents() {
         return this._agents;
     }
+    /**
+     * Emitted whenever {@link agents} changes.
+     */
     get changed() {
         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) {
         this._agents = agents;

package/lib/launcher/tokens.d.ts

@@ -2,40 +2,28 @@ import { Token } from '@lumino/coreutils';
 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 declare const IAgentRegistry: 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 declare function agentCommandId(agentId: string): string;

package/lib/launcher/tokens.js

@@ -1,16 +1,13 @@
 import { Token } from '@lumino/coreutils';
 /**
- * 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('xtralab:IAgentRegistry', 'A read-only, observable view of the launcher agents, shared so other plugins can offer the same agent list and icons.');
 /**
- * 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) {
     return `xtralab:start-agent:${agentId}`;

package/lib/menuBar/index.d.ts

@@ -1,15 +1,8 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * 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.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/menuBar/index.js

@@ -10,24 +10,14 @@ const PLUGIN_ID = 'xtralab:menu-bar';
 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 = {
     id: PLUGIN_ID,
@@ -64,9 +54,8 @@ const plugin = {
         const openMenu = () => {
             var _a, _b;
             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;
@@ -74,13 +63,8 @@ const plugin = {
             if (Date.now() - popupClosedAt < REOPEN_GUARD_MS) {
                 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');
@@ -153,9 +137,8 @@ const plugin = {
             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);
         });

package/lib/menus/index.d.ts

@@ -1,14 +1,8 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Hide the "Run" and "Kernel" top-level menus while no kernel-using widget
- * is open in the main area. The agent-first launcher does not use kernels,
- * so showing those menus on a fresh workspace surfaces commands the user
- * cannot meaningfully invoke; remove them until a notebook or console is
- * opened, then restore them at their original ranks.
- *
- * Detection is duck-typed on `sessionContext`: NotebookPanel and ConsolePanel
- * both expose it, which avoids pulling in `@jupyterlab/notebook` and
- * `@jupyterlab/console` just to identify their widgets.
+ * Hide the Run and Kernel menus while no kernel-using widget is open in the
+ * main area, then restore them at their original ranks — the agent-first
+ * launcher does not use kernels, so a fresh workspace should not surface them.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/menus/index.js

@@ -2,15 +2,9 @@ import { ILabShell } from '@jupyterlab/application';
 import { IMainMenu } from '@jupyterlab/mainmenu';
 const PLUGIN_ID = 'xtralab:menus';
 /**
- * Hide the "Run" and "Kernel" top-level menus while no kernel-using widget
- * is open in the main area. The agent-first launcher does not use kernels,
- * so showing those menus on a fresh workspace surfaces commands the user
- * cannot meaningfully invoke; remove them until a notebook or console is
- * opened, then restore them at their original ranks.
- *
- * Detection is duck-typed on `sessionContext`: NotebookPanel and ConsolePanel
- * both expose it, which avoids pulling in `@jupyterlab/notebook` and
- * `@jupyterlab/console` just to identify their widgets.
+ * Hide the Run and Kernel menus while no kernel-using widget is open in the
+ * main area, then restore them at their original ranks — the agent-first
+ * launcher does not use kernels, so a fresh workspace should not surface them.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -19,27 +13,21 @@ const plugin = {
     requires: [IMainMenu, ILabShell],
     activate: (app, mainMenu, labShell) => {
         var _a, _b;
-        // The interface types (IRunMenu, IKernelMenu) extend IRankedMenu, but
-        // the concrete instances are RankedMenu/Menu — cast so we can hand them
-        // to MenuBar.removeMenu and IMainMenu.addMenu, which expect a `Menu`.
+        // The interface types extend IRankedMenu but the concrete instances are
+        // RankedMenu/Menu; cast for the MenuBar methods, which expect a `Menu`.
         const menuBar = mainMenu;
         const runMenu = mainMenu.runMenu;
         const kernelMenu = mainMenu.kernelMenu;
-        // Capture the schema-assigned ranks so the menus reappear in their
-        // original slots between View (rank 3) and Tabs (rank 500). Falling
-        // back to the hard-coded defaults from `MainMenu` keeps things sane
-        // if the schema ever omits the rank.
+        // Schema-assigned ranks so the menus reappear in their original slots;
+        // fall back to MainMenu's hard-coded defaults if the schema omits them.
         const runRank = (_a = mainMenu.runMenu.rank) !== null && _a !== void 0 ? _a : 4;
         const kernelRank = (_b = mainMenu.kernelMenu.rank) !== null && _b !== void 0 ? _b : 5;
         const isPresent = (menu) => Array.from(menuBar.menus).indexOf(menu) > -1;
         const update = () => {
             const show = hasKernelWidget(labShell);
             if (show) {
-                // Don't go through `mainMenu.addMenu`: it picks the insertion index
-                // from a private `_items` array that `removeMenu` doesn't update,
-                // so re-adding lands the menu at the wrong position. Insert
-                // directly on the MenuBar by walking current menus and finding
-                // the first sibling with a higher rank.
+                // Not `mainMenu.addMenu`: its insertion index comes from a private
+                // `_items` array that `removeMenu` doesn't update, misplacing re-adds.
                 if (!isPresent(runMenu)) {
                     insertByRank(menuBar, runMenu, runRank);
                 }
@@ -63,11 +51,9 @@ const plugin = {
     }
 };
 /**
- * True iff any widget in the main area exposes a `sessionContext` — the
- * shared marker for NotebookPanel, ConsolePanel, and kernel-attached file
- * editors. We don't import their concrete types because that would drag
- * `@jupyterlab/notebook` and `@jupyterlab/console` into xtralab's bundle
- * just to do an `instanceof` check.
+ * True iff any main-area widget exposes a `sessionContext` (NotebookPanel,
+ * ConsolePanel, kernel-attached editors) — duck-typed to keep
+ * `@jupyterlab/notebook` and `@jupyterlab/console` out of the bundle.
  */
 function hasKernelWidget(labShell) {
     for (const widget of labShell.widgets('main')) {
@@ -82,10 +68,8 @@ function hasSessionContext(widget) {
     return (candidate.sessionContext !== null && candidate.sessionContext !== undefined);
 }
 /**
- * Insert `menu` into `menuBar` at the position dictated by `rank`, using
- * the existing menus' ranks to find the slot. Menus without a numeric
- * rank are treated as +Infinity so they sink to the end (matching the
- * convention in `MenuFactory.createMenus`).
+ * Insert `menu` at the slot dictated by `rank`; rank-less menus count as
+ * +Infinity and sink to the end, matching `MenuFactory.createMenus`.
  */
 function insertByRank(menuBar, menu, rank) {
     const menus = menuBar.menus;

package/lib/omnibox/files.d.ts

@@ -1,7 +1,5 @@
 /**
- * The workspace file list, cached briefly so reopening the omnibox in quick
- * succession reuses one scan. A failed fetch (e.g. quickopen's server
- * extension is absent) resolves to an empty list so file search degrades to
- * "no results" instead of surfacing an error.
+ * The workspace file list, cached briefly so reopening the omnibox reuses one
+ * scan. A failed fetch resolves to an empty list.
  */
 export declare function loadWorkspaceFiles(): Promise<string[]>;