xtralab 0.14.0 → 0.15.0

package/lib/fileBrowser/widget.js

@@ -1,23 +1,28 @@
 import * as React from 'react';
-import { ReactWidget, Toolbar } from '@jupyterlab/ui-components';
+import { AccordionToolbar, PanelWithToolbar, ReactWidget, Toolbar } from '@jupyterlab/ui-components';
 import { Signal } from '@lumino/signaling';
-import { PanelLayout, Widget } from '@lumino/widgets';
+import { AccordionPanel, PanelLayout, Widget } from '@lumino/widgets';
 import { FileBrowserComponent } from './fileBrowser';
 import { xtralabFileBrowserIcon } from './icons';
 export const FILE_BROWSER_ID = 'xtralab:file-browser';
 /**
- * The CSS class added to the xtralab file browser widget. The selectors that
- * bind application context menu items hang off this class, so it must remain
- * specific enough not to clash with other browsers (such as the default
- * `jp-FileBrowser`).
+ * Persisted by the movable-sections plugin, so it must stay stable.
+ */
+const TREE_SECTION_ID = 'xtralab-file-tree-section';
+/**
+ * Context menu selectors hang off this class, so it sits on the section and
+ * keeps matching once the tree moves to another panel.
  */
 const FILE_BROWSER_CSS_CLASS = 'jp-xtralab-FileBrowser';
+const PANEL_CSS_CLASS = 'jp-xtralab-FileBrowserPanel';
 const TOOLBAR_CSS_CLASS = 'jp-xtralab-FileBrowser-toolbar';
 const CONTENT_CSS_CLASS = 'jp-xtralab-FileBrowser-content';
+const ACCORDION_CSS_CLASS = 'jp-xtralab-FileBrowser-accordion';
+const MOVABLE_SECTION_CLASS = 'jp-movable-section';
 /**
- * Lumino widget that hosts the React-based `@pierre/trees` file browser.
- * The widget is laid out with a JupyterLab `Toolbar` on top and the tree
- * filling the remaining space.
+ * Lumino widget hosting the React-based `@pierre/trees` file browser. The tree
+ * and its toolbar form one movable "Files" section, and sections from other
+ * panels can be moved in below it.
  */
 export class XtralabFileBrowser extends Widget {
     constructor(options) {
@@ -31,26 +36,37 @@ export class XtralabFileBrowser extends Widget {
         this._collapseAllRequested = new Signal(this);
         this._fileFilterVisible = false;
         this._fileFilterVisibleChanged = new Signal(this);
-        const layout = (this.layout = new PanelLayout());
+        this._accordion = null;
+        this._contentChanged = new Signal(this);
+        this._sectionAdded = new Signal(this);
+        const layout = (this._panelLayout = this.layout = new PanelLayout());
         this._contentsManager = options.contentsManager;
         this._docManager = options.docManager;
         this._onOpenFile = options.onOpenFile;
+        this._translator = options.translator;
         this.id = FILE_BROWSER_ID;
         this.title.icon = xtralabFileBrowserIcon;
         this.title.caption = 'xtralab File Browser';
-        this.addClass(FILE_BROWSER_CSS_CLASS);
+        this.addClass(PANEL_CSS_CLASS);
         this._toolbar = new Toolbar();
         this._toolbar.addClass(TOOLBAR_CSS_CLASS);
         this._toolbar.node.setAttribute('aria-label', 'file browser');
-        layout.addWidget(this._toolbar);
         this._content = new XtralabFileTreeContent({
             contentsManager: this._contentsManager,
             docManager: this._docManager,
             onOpenFile: this._onOpenFile,
+            translator: this._translator,
             browser: this
         });
         this._content.addClass(CONTENT_CSS_CLASS);
-        layout.addWidget(this._content);
+        this._section = new PanelWithToolbar({ toolbar: this._toolbar });
+        this._section.id = TREE_SECTION_ID;
+        // Only an accordion host draws this; a plain `PanelLayout` shows no title.
+        this._section.title.label = 'Files';
+        this._section.addClass(FILE_BROWSER_CSS_CLASS);
+        this._section.addWidget(this._toolbar);
+        this._section.addWidget(this._content);
+        layout.addWidget(this._section);
     }
     get contentsManager() {
         return this._contentsManager;
@@ -121,6 +137,129 @@ export class XtralabFileBrowser extends Widget {
     toggleFileFilter() {
         this.setFileFilterVisible(!this._fileFilterVisible);
     }
+    get sectionNode() {
+        return this._section.node;
+    }
+    get isEmpty() {
+        return this._panelLayout.widgets.length === 0;
+    }
+    get contentChanged() {
+        return this._contentChanged;
+    }
+    get sectionAdded() {
+        return this._sectionAdded;
+    }
+    get accordionPanel() {
+        return this._accordion;
+    }
+    get sections() {
+        if (!this._accordion) {
+            return [];
+        }
+        return this._accordion.widgets.filter(w => w !== this._section);
+    }
+    /**
+     * The toolbar is the section's title node: it is the tree's header row at
+     * home, and an accordion host renders it inside the section title.
+     */
+    getSections() {
+        return this._isSectionHome()
+            ? [
+                {
+                    id: TREE_SECTION_ID,
+                    titleNode: this._toolbar.node,
+                    widget: this._section
+                }
+            ]
+            : [];
+    }
+    removeSectionById(sectionId) {
+        if (sectionId !== TREE_SECTION_ID || !this._isSectionHome()) {
+            return null;
+        }
+        this._section.parent = null;
+        if (this._accordion && this._accordion.widgets.length === 0) {
+            this._accordion.dispose();
+            this._accordion = null;
+        }
+        // Away from home the toolbar must not offer "Move to …" as well;
+        // `getSections` re-marks it on the way back.
+        this._toolbar.node.classList.remove(MOVABLE_SECTION_CLASS);
+        this._contentChanged.emit();
+        return this._section;
+    }
+    reinsertSection(widget) {
+        if (this._accordion) {
+            this._accordion.insertWidget(0, widget);
+        }
+        else {
+            this._panelLayout.addWidget(widget);
+            this._restoreToolbar();
+        }
+        this._contentChanged.emit();
+    }
+    /**
+     * The move plugin reconciles persisted moves only against sections announced
+     * after `registerSource`, and this panel builds its section in the constructor.
+     */
+    announceSections() {
+        for (const entry of this.getSections()) {
+            this._sectionAdded.emit(entry);
+        }
+    }
+    /**
+     * The first hosted section moves the tree into an accordion.
+     */
+    addSection(widget) {
+        if (!this._accordion) {
+            const accordion = new AccordionPanel({
+                layout: AccordionToolbar.createLayout({})
+            });
+            accordion.addClass(ACCORDION_CSS_CLASS);
+            if (this._section.parent === this) {
+                accordion.addWidget(this._section);
+            }
+            accordion.addWidget(widget);
+            this._accordion = accordion;
+            this._panelLayout.addWidget(accordion);
+        }
+        else {
+            this._accordion.addWidget(widget);
+        }
+        this._contentChanged.emit();
+    }
+    removeSectionWidget(widget) {
+        if (!this._accordion || widget.parent !== this._accordion) {
+            return;
+        }
+        widget.parent = null;
+        const remaining = this._accordion.widgets;
+        const treeOnly = remaining.length === 1 && remaining[0] === this._section;
+        if (treeOnly || remaining.length === 0) {
+            if (treeOnly) {
+                if (this._section.isHidden) {
+                    this._section.show();
+                }
+                this._panelLayout.addWidget(this._section);
+                this._restoreToolbar();
+            }
+            this._accordion.dispose();
+            this._accordion = null;
+        }
+        this._contentChanged.emit();
+    }
+    _isSectionHome() {
+        const parent = this._section.parent;
+        return parent === this || (!!this._accordion && parent === this._accordion);
+    }
+    /**
+     * An accordion host moves the toolbar node into the section title and leaves
+     * it orphaned on detach; re-parenting makes the layout attach it again.
+     */
+    _restoreToolbar() {
+        this._toolbar.parent = null;
+        this._section.insertWidget(0, this._toolbar);
+    }
 }
 /**
  * The React-rendered region of the file browser. Lives inside the host
@@ -132,6 +271,6 @@ class XtralabFileTreeContent extends ReactWidget {
         this._options = options;
     }
     render() {
-        return (React.createElement(FileBrowserComponent, { contentsManager: this._options.contentsManager, docManager: this._options.docManager, onOpenFile: this._options.onOpenFile, widget: this._options.browser }));
+        return (React.createElement(FileBrowserComponent, { contentsManager: this._options.contentsManager, docManager: this._options.docManager, onOpenFile: this._options.onOpenFile, translator: this._options.translator, widget: this._options.browser }));
     }
 }

package/lib/index.js

@@ -2,6 +2,7 @@ import aboutPlugin from './about';
 import agentSessionsPlugin from './agentSessions';
 import askAgentPlugin from './askAgent';
 import commandBarPlugin from './commandBar';
+import customPanelPlugin from './customPanel';
 import fileBrowserPlugin from './fileBrowser';
 import fileTypeIconsPlugin from './fileTypeIcons';
 import editorBreadcrumbsPlugin from './editorBreadcrumbs';
@@ -9,6 +10,7 @@ import editorIndentPlugin from './editorIndent';
 import gitPlugins from './git';
 import highlightPlugin from './highlight';
 import launcherPlugins from './launcher';
+import menuBarPlugin from './menuBar';
 import menusPlugin from './menus';
 import omniboxPlugin from './omnibox';
 import searchReplacePlugin from './searchReplace';
@@ -32,6 +34,7 @@ const plugins = [
     agentSessionsPlugin,
     askAgentPlugin,
     commandBarPlugin,
+    customPanelPlugin,
     editorBreadcrumbsPlugin,
     editorIndentPlugin,
     fileBrowserPlugin,
@@ -39,6 +42,7 @@ const plugins = [
     ...gitPlugins,
     highlightPlugin,
     ...launcherPlugins,
+    menuBarPlugin,
     menusPlugin,
     omniboxPlugin,
     searchReplacePlugin,

package/lib/launcher/agents.d.ts

@@ -23,7 +23,7 @@ export interface IAgent {
      * the user types one into the launcher's prompt box. The semantics:
      *
      *   - `[]` → prompt is appended as a positional argument:
-     *     `<command> 'PROMPT'`. (Used by claude, codex, vibe.)
+     *     `<command> 'PROMPT'`. (Used by claude, codex, vibe, pi.)
      *   - `['-i']` / `['--prompt']` → the prompt is preceded by a flag:
      *     `<command> -i 'PROMPT'`. (Used by copilot, opencode.)
      *   - `undefined` → the agent does not accept an initial prompt. The

package/lib/launcher/agents.js

@@ -7,8 +7,9 @@ import { BUILTIN_AGENT_ICONS } from './icons';
  * icons come from), but use the bare CLI names a user would type in a
  * terminal rather than the ACP wrapper binaries that project spawns.
  * Antigravity (Google's agent-first IDE/CLI, `agy`) is the Google agent.
- * Anything not on the user's `$PATH` is filtered out at activation time, so
- * the wider list is harmless.
+ * Pi (https://pi.dev, `earendil-works/pi`) is a minimal extensible coding
+ * agent; its mark comes straight from its site. Anything not on the user's
+ * `$PATH` is filtered out at activation time, so the wider list is harmless.
  */
 const DEFAULTS = [
     {
@@ -100,6 +101,18 @@ const DEFAULTS = [
         rank: 7,
         requireAvailable: true,
         promptArgs: []
+    },
+    {
+        id: 'pi',
+        label: 'Pi',
+        caption: 'Start Pi in a new terminal.',
+        command: 'pi',
+        icon: BUILTIN_AGENT_ICONS.pi,
+        rank: 8,
+        requireAvailable: true,
+        // `pi [messages...]` starts the interactive TUI and sends the messages
+        // as the first user prompt, so the positional form applies.
+        promptArgs: []
     }
 ];
 /**

package/lib/launcher/icons.js

@@ -5,11 +5,14 @@ import { LabIcon } from '@jupyterlab/ui-components';
  * (`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. Small adjustments are applied
+ * 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) use `currentColor` so they
+ *   - 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.
+ *     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
@@ -169,6 +172,13 @@ const opencodeIcon = new LabIcon({
   <path fill-rule="evenodd" clip-rule="evenodd" d="M384 416H128V96H384V416ZM320 160H192V352H320V160Z" fill="white"/>
 </svg>`
 });
+const piIcon = new LabIcon({
+    name: 'xtralab:agent-pi',
+    svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 800" fill="currentColor">
+  <path fill-rule="evenodd" d="M165.29 165.29H517.36V400H400V517.36H282.65V634.72H165.29ZM282.65 282.65V400H400V282.65Z"/>
+  <path d="M517.36 400H634.72V634.72H517.36Z"/>
+</svg>`
+});
 const neovimIcon = new LabIcon({
     name: 'xtralab:editor-neovim',
     svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#57A143">
@@ -195,7 +205,8 @@ export const BUILTIN_AGENT_ICONS = {
     goose: gooseIcon,
     kiro: kiroIcon,
     'mistral-vibe': mistralVibeIcon,
-    opencode: opencodeIcon
+    opencode: opencodeIcon,
+    pi: piIcon
 };
 /**
  * Built-in icons keyed by the editor's id, used to resolve the icon for a

package/lib/launcher/schemaDefaults.d.ts

@@ -4,14 +4,7 @@ import type { ISettingRegistry } from '@jupyterlab/settingregistry';
  */
 export declare const LAUNCHER_PLUGIN_ID = "xtralab:launcher";
 /**
- * Register a `fetch` transform that injects xtralab's built-in agent and
- * editor lists as the schema defaults for the `xtralab:launcher` settings, so
- * the Settings Editor shows the shipped list.
- *
- * The schema declares `jupyter.lab.transform: true`, so the registry defers
- * loading the plugin until a transform is registered: callers must invoke this
- * before their first `settingRegistry.load(LAUNCHER_PLUGIN_ID)`. Idempotent, so
- * the two plugins that load these settings can both call it regardless of
- * activation order.
+ * Must run before the first `load(LAUNCHER_PLUGIN_ID)` (the schema sets
+ * `jupyter.lab.transform: true`); idempotent across callers.
  */
 export declare function registerLauncherSchemaDefaults(settingRegistry: ISettingRegistry): void;

package/lib/launcher/schemaDefaults.js

@@ -5,20 +5,38 @@ import { defaultEditorSettings } from './editors';
  */
 export const LAUNCHER_PLUGIN_ID = 'xtralab:launcher';
 /**
- * Setting registries that already have the transform, so both callers skip
- * re-registering (the registry rejects a duplicate transformer).
+ * Registries that already have the transform (duplicates are rejected).
  */
 const registered = new WeakSet();
 /**
- * Register a `fetch` transform that injects xtralab's built-in agent and
- * editor lists as the schema defaults for the `xtralab:launcher` settings, so
- * the Settings Editor shows the shipped list.
- *
- * The schema declares `jupyter.lab.transform: true`, so the registry defers
- * loading the plugin until a transform is registered: callers must invoke this
- * before their first `settingRegistry.load(LAUNCHER_PLUGIN_ID)`. Idempotent, so
- * the two plugins that load these settings can both call it regardless of
- * activation order.
+ * Merge sparse user entries over the built-in defaults, keyed by `id`.
+ */
+function mergeSettingsById(defaults, user) {
+    const entries = Array.isArray(user) ? user : [];
+    const overrideById = new Map(entries.map(entry => [entry.id, entry]));
+    const merged = defaults.map(base => {
+        const override = overrideById.get(base.id);
+        if (!override) {
+            return base;
+        }
+        overrideById.delete(base.id);
+        return { ...base, ...override };
+    });
+    merged.push(...overrideById.values());
+    // Item schema defaults are applied before this transform runs; without the
+    // refill, sparse entries render with unchecked boxes.
+    return merged.map(entry => {
+        var _a, _b;
+        return ({
+            ...entry,
+            enabled: (_a = entry.enabled) !== null && _a !== void 0 ? _a : true,
+            requireAvailable: (_b = entry.requireAvailable) !== null && _b !== void 0 ? _b : true
+        });
+    });
+}
+/**
+ * Must run before the first `load(LAUNCHER_PLUGIN_ID)` (the schema sets
+ * `jupyter.lab.transform: true`); idempotent across callers.
  */
 export function registerLauncherSchemaDefaults(settingRegistry) {
     if (registered.has(settingRegistry)) {
@@ -26,11 +44,17 @@ export function registerLauncherSchemaDefaults(settingRegistry) {
     }
     registered.add(settingRegistry);
     settingRegistry.transform(LAUNCHER_PLUGIN_ID, {
+        compose: plugin => {
+            const { user } = plugin.data;
+            const composite = { ...plugin.data.composite };
+            composite.agents = mergeSettingsById(defaultAgentSettings(), user.agents);
+            composite.editors = mergeSettingsById(defaultEditorSettings(), user.editors);
+            plugin.data = { composite, user };
+            return plugin;
+        },
         fetch: plugin => {
             const properties = plugin.schema.properties;
             if (properties) {
-                // The settings shapes are plain JSON by construction, but their named
-                // interfaces lack an index signature, so cast at this TS→JSON boundary.
                 if (properties.agents) {
                     properties.agents.default =
                         defaultAgentSettings();

package/lib/menuBar/icons.d.ts

@@ -0,0 +1,6 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+/**
+ * Hamburger mark for the collapsed main-menu button, matching the sidebar
+ * toggles in ../topBar/icons.ts.
+ */
+export declare const mainMenuIcon: LabIcon;

package/lib/menuBar/icons.js

@@ -0,0 +1,13 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+/**
+ * Hamburger mark for the collapsed main-menu button, matching the sidebar
+ * toggles in ../topBar/icons.ts.
+ */
+export const mainMenuIcon = new LabIcon({
+    name: 'xtralab:main-menu',
+    svgstr: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <line x1="4.5" y1="7" x2="19.5" y2="7" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>
+  <line x1="4.5" y1="12" x2="19.5" y2="12" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>
+  <line x1="4.5" y1="17" x2="19.5" y2="17" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>
+</svg>`
+});

package/lib/menuBar/index.d.ts

@@ -0,0 +1,15 @@
+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.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/menuBar/index.js

@@ -0,0 +1,164 @@
+import { ILabShell } from '@jupyterlab/application';
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { IMainMenu, MainMenu } from '@jupyterlab/mainmenu';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { CommandToolbarButton, MenuSvg } from '@jupyterlab/ui-components';
+import { Menu } from '@lumino/widgets';
+import { mainMenuIcon } from './icons';
+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.
+ */
+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.
+ */
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Collapse the main menu bar into a compact menu button.',
+    autoStart: true,
+    requires: [IMainMenu, ILabShell, ISettingRegistry],
+    optional: [ICommandPalette, ITranslator],
+    activate: (app, mainMenu, labShell, settingRegistry, palette, translator) => {
+        var _a;
+        const { commands } = app;
+        const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
+        if (!(mainMenu instanceof MainMenu)) {
+            return;
+        }
+        const menuPanel = () => {
+            var _a, _b;
+            return (_b = (_a = mainMenu.parent) !== null && _a !== void 0 ? _a : Array.from(labShell.widgets('top')).find(w => w.id === 'jp-menu-panel')) !== null && _b !== void 0 ? _b : null;
+        };
+        let visible = false;
+        let button = null;
+        let settings = null;
+        const applyVisibility = (value) => {
+            var _a;
+            visible = value;
+            mainMenu.setHidden(!value);
+            (_a = menuPanel()) === null || _a === void 0 ? void 0 : _a.setHidden(!value);
+            button === null || button === void 0 ? void 0 : button.setHidden(value);
+            commands.notifyCommandChanged(TOGGLE_COMMAND);
+        };
+        mainMenu.hide();
+        (_a = menuPanel()) === null || _a === void 0 ? void 0 : _a.hide();
+        let popup = null;
+        let popupClosedAt = 0;
+        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.
+                mainMenu.activeIndex = 0;
+                mainMenu.openActiveMenu();
+                return;
+            }
+            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.
+            if (popup === null) {
+                popup = new Menu({ commands, renderer: MenuSvg.defaultRenderer });
+                popup.addClass('jp-ThemedContainer');
+                popup.addClass('jp-xtralab-MainMenuPopup');
+                popup.aboutToClose.connect(() => {
+                    popupClosedAt = Date.now();
+                });
+            }
+            else {
+                popup.clearItems();
+            }
+            // Skip empty menus: MenuBar disables their headings, but submenu items
+            // have no such affordance and would open a blank panel.
+            for (const menu of mainMenu.menus) {
+                if (menu.items.length > 0) {
+                    popup.addItem({ type: 'submenu', submenu: menu });
+                }
+            }
+            const anchor = button === null || button === void 0 ? void 0 : button.node.getBoundingClientRect();
+            // The 3px gap matches the detached-dropdown offset chrome.css gives
+            // the real menu bar's dropdowns (.lm-Menu.lm-MenuBar-menu).
+            popup.open((_a = anchor === null || anchor === void 0 ? void 0 : anchor.left) !== null && _a !== void 0 ? _a : 0, ((_b = anchor === null || anchor === void 0 ? void 0 : anchor.bottom) !== null && _b !== void 0 ? _b : 0) + 3);
+        };
+        commands.addCommand(OPEN_COMMAND, {
+            label: trans.__('Open Menu'),
+            caption: trans.__('Open the main menu'),
+            icon: mainMenuIcon,
+            execute: openMenu
+        });
+        commands.addCommand(TOGGLE_COMMAND, {
+            label: trans.__('Show Menu Bar'),
+            caption: trans.__('Toggle the visibility of the main menu bar'),
+            isToggled: () => visible,
+            execute: async () => {
+                applyVisibility(!visible);
+                if (settings !== null) {
+                    try {
+                        await settings.set('visible', visible);
+                    }
+                    catch (reason) {
+                        console.error('xtralab: failed to persist menu bar visibility', reason);
+                    }
+                }
+            }
+        });
+        if (palette) {
+            const category = trans.__('Other');
+            palette.addItem({ command: OPEN_COMMAND, category });
+            palette.addItem({ command: TOGGLE_COMMAND, category });
+        }
+        Promise.all([settingRegistry.load(PLUGIN_ID), app.restored])
+            .then(([loaded]) => {
+            settings = loaded;
+            button = new CommandToolbarButton({
+                commands,
+                id: OPEN_COMMAND,
+                icon: mainMenuIcon,
+                label: '',
+                caption: trans.__('Menu'),
+                noFocusOnClick: true,
+                'aria-haspopup': 'menu'
+            });
+            button.id = 'xtralab-main-menu-button';
+            button.addClass('jp-xtralab-TopBarButton');
+            labShell.add(button, 'top', { rank: 0 });
+            const update = () => {
+                applyVisibility(loaded.get('visible').composite);
+            };
+            update();
+            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.
+            applyVisibility(true);
+            console.error(`Failed to load settings for ${PLUGIN_ID}`, reason);
+        });
+    }
+};
+export default plugin;

package/lib/sidebar/index.d.ts

@@ -1,18 +1,12 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Lets the user toggle individual left-sidebar tabs from
- * View > Appearance > Left Sidebar. Removing a widget from a `LabShell`
- * side area is done by setting `widget.parent = null`: the StackedPanel
- * emits `widgetRemoved`, which the SideBarHandler responds to by removing
- * the matching tab. The widget instance is preserved, so we can re-add it
- * later via `labShell.add` with its original rank.
- *
- * The menu placement is contributed declaratively in
- * `schema/sidebar.json`, so this plugin only registers commands and
- * applies state — it does not touch `IMainMenu` directly.
- *
- * The preference is persisted to `xtralab:sidebar` settings so the choice
- * survives reloads.
+ * Toggles individual sidebar tabs from View > Appearance > Sidebars,
+ * whichever side a tab currently lives on. Hiding detaches the widget
+ * (`widget.parent = null`) while keeping the instance for a later
+ * re-add; the preference persists in this plugin's settings. Which side
+ * a hidden tab came from is only tracked in-memory, so after a reload a
+ * re-shown tab lands on the left. The menu placement is contributed
+ * declaratively in `schema/sidebar.json`.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;