xtralab 0.13.1 → 0.14.1

package/lib/omnibox/recents.js

@@ -1,3 +1,11 @@
+/**
+ * Identity of an entry: two uses only match when kind, id and args all do,
+ * so runs of one command with different args stay distinct entries.
+ */
+function entryKey(entry) {
+    var _a;
+    return `${entry.kind}\0${entry.id}\0${JSON.stringify((_a = entry.args) !== null && _a !== void 0 ? _a : null)}`;
+}
 /**
  * State database key the recents list is persisted under.
  */
@@ -45,11 +53,14 @@ export class OmniboxRecents {
             : [...this._entries];
     }
     /**
-     * Record a use of `id`, moving it to the front of its kind's list.
+     * Record a use of `id` (with the args it ran with, if any), moving it to
+     * the front of its kind's list.
      */
-    touch(kind, id) {
-        const rest = this._entries.filter(entry => !(entry.kind === kind && entry.id === id));
-        this._entries = this._trim([{ kind, id }, ...rest]);
+    touch(kind, id, args) {
+        const entry = args === undefined ? { kind, id } : { kind, id, args };
+        const key = entryKey(entry);
+        const rest = this._entries.filter(existing => entryKey(existing) !== key);
+        this._entries = this._trim([entry, ...rest]);
         this._save();
     }
     /**
@@ -68,16 +79,31 @@ export class OmniboxRecents {
             return;
         }
         const persisted = Array.isArray(fetched)
-            ? fetched.filter((entry) => !!entry &&
-                typeof entry === 'object' &&
-                (entry.kind === 'command' ||
-                    entry.kind === 'file') &&
-                typeof entry.id === 'string')
+            ? fetched.filter((entry) => {
+                if (!entry || typeof entry !== 'object') {
+                    return false;
+                }
+                const candidate = entry;
+                if (candidate.kind !== 'command' && candidate.kind !== 'file') {
+                    return false;
+                }
+                if (typeof candidate.id !== 'string') {
+                    return false;
+                }
+                const args = candidate.args;
+                return (args === undefined ||
+                    (typeof args === 'object' && args !== null && !Array.isArray(args)));
+            })
             : [];
+        const known = new Set(this._entries.map(entryKey));
         const merged = [...this._entries];
         for (const entry of persisted) {
-            if (!merged.some(existing => existing.kind === entry.kind && existing.id === entry.id)) {
-                merged.push({ kind: entry.kind, id: entry.id });
+            const key = entryKey(entry);
+            if (!known.has(key)) {
+                known.add(key);
+                merged.push(entry.args === undefined
+                    ? { kind: entry.kind, id: entry.id }
+                    : { kind: entry.kind, id: entry.id, args: entry.args });
             }
         }
         this._entries = this._trim(merged);
@@ -98,10 +124,9 @@ export class OmniboxRecents {
         if (!this._state) {
             return;
         }
-        const value = this._entries.map(entry => ({
-            kind: entry.kind,
-            id: entry.id
-        }));
+        const value = this._entries.map(entry => entry.args === undefined
+            ? { kind: entry.kind, id: entry.id }
+            : { kind: entry.kind, id: entry.id, args: entry.args });
         this._state.save(STATE_KEY, value).catch(reason => {
             console.error('xtralab omnibox: failed to save recents', reason);
         });

package/lib/omnibox/widget.d.ts

@@ -2,6 +2,7 @@ import type { DocumentRegistry } from '@jupyterlab/docregistry';
 import type { TranslationBundle } from '@jupyterlab/translation';
 import { ReactWidget } from '@jupyterlab/ui-components';
 import type { CommandRegistry } from '@lumino/commands';
+import type { CommandPalette } from '@lumino/widgets';
 import type { IAgent } from '../launcher/agents';
 import type { OmniboxRecents } from './recents';
 /**
@@ -24,6 +25,11 @@ export declare namespace OmniboxWidget {
      */
     interface IOptions {
         commands: CommandRegistry;
+        /**
+         * Snapshot of the command palette's items, read once when the overlay
+         * opens; empty when the palette isn't available.
+         */
+        paletteItems: ReadonlyArray<CommandPalette.IItem>;
         docRegistry: DocumentRegistry;
         /**
          * Snapshot of the available agents, read once when the overlay opens.

package/lib/omnibox/widget.js

@@ -39,7 +39,7 @@ function renderIcon(icon) {
     return icon ? (React.createElement(icon.react, { tag: "span", className: "jp-xtralab-Omnibox-itemIcon" })) : (React.createElement("span", { className: "jp-xtralab-Omnibox-itemIcon" }));
 }
 function OmniboxComponent(props) {
-    const { commands, docRegistry, agents, placeholder, initialQuery, recents, trans, onClose } = props;
+    const { commands, paletteItems, docRegistry, agents, placeholder, initialQuery, recents, trans, onClose } = props;
     const [query, setQuery] = React.useState(initialQuery);
     const [files, setFiles] = React.useState([]);
     const [active, setActive] = React.useState(0);
@@ -63,12 +63,13 @@ function OmniboxComponent(props) {
     const sections = React.useMemo(() => computeSections({
         query,
         commands,
+        paletteItems,
         docRegistry,
         agents,
         files,
         recents,
         trans
-    }), [query, commands, docRegistry, agents, files, recents, trans]);
+    }), [query, commands, paletteItems, docRegistry, agents, files, recents, trans]);
     const flat = React.useMemo(() => [
         ...sections.recent,
         ...sections.commands,

package/logo.svg

@@ -0,0 +1,63 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-5 -3 194 272" role="img" aria-labelledby="jp-xtralab-logo-title jp-xtralab-logo-desc">
+  <title id="jp-xtralab-logo-title">XtraLab flask icon</title>
+  <desc id="jp-xtralab-logo-desc">A clean, slightly tilted laboratory flask with a symmetrical constant-width dark frame, blue-to-pink liquid, bubbles, and rising pixel blocks.</desc>
+
+  <defs>
+    <linearGradient id="jp-xtralab-logo-liquid" x1="20" y1="154" x2="151" y2="231" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#00a6ed"/>
+      <stop offset=".29" stop-color="#0879ed"/>
+      <stop offset=".58" stop-color="#6548d2"/>
+      <stop offset=".8" stop-color="#b43baa"/>
+      <stop offset="1" stop-color="#f1357e"/>
+    </linearGradient>
+    <radialGradient id="jp-xtralab-logo-liquid-glow" cx="0" cy="0" r="1"
+                    gradientTransform="translate(49 169) rotate(34) scale(75 49)"
+                    gradientUnits="userSpaceOnUse">
+      <stop stop-color="#18b9ef" stop-opacity=".78"/>
+      <stop offset=".58" stop-color="#1688ef" stop-opacity=".2"/>
+      <stop offset="1" stop-color="#1688ef" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="jp-xtralab-logo-pixel-blue" x1="137" y1="13" x2="156" y2="32" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#05aae9"/>
+      <stop offset="1" stop-color="#008be0"/>
+    </linearGradient>
+    <linearGradient id="jp-xtralab-logo-pixel-purple" x1="154" y1="39" x2="178" y2="61" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#6242c0"/>
+      <stop offset="1" stop-color="#923ba8"/>
+    </linearGradient>
+    <linearGradient id="jp-xtralab-logo-pixel-pink" x1="166" y1="0" x2="183" y2="17" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#8040bd"/>
+      <stop offset="1" stop-color="#ad3c9b"/>
+    </linearGradient>
+    <clipPath id="jp-xtralab-logo-chamber" clipPathUnits="userSpaceOnUse">
+      <path d="M64 61h36v43c0 10 2 18 8 27l42 73c5 8 5 18 0 26-5 8-13 12-23 13H37c-10-1-18-5-23-13-5-8-5-18 0-26l42-73c6-9 8-17 8-27Z"/>
+    </clipPath>
+  </defs>
+
+  <!-- The flask is constructed symmetrically around x=82, then given a slight logo-matching tilt. -->
+  <g transform="rotate(9 82 232)">
+    <g clip-path="url(#jp-xtralab-logo-chamber)">
+      <path fill="url(#jp-xtralab-logo-liquid)"
+            d="M8 207c17-25 34-52 55-60 16-6 29-2 42 5 14 8 27 8 43-4l13 65c4 18-8 35-27 37H30c-20-2-30-23-22-43Z"/>
+      <path fill="url(#jp-xtralab-logo-liquid-glow)"
+            d="M8 207c17-25 34-52 55-60 16-6 29-2 42 5 14 8 27 8 43-4l13 65c4 18-8 35-27 37H30c-20-2-30-23-22-43Z"/>
+    </g>
+
+    <!-- A straight integrated mouth joins the widened chimney without a separate rim element. -->
+    <path d="M56 55v49c0 12-2 21-8 31L9 201c-7 10-7 23-1 33s16 15 28 16h92c12-1 22-6 28-16s6-23-1-33l-39-66c-6-10-8-19-8-31V55H56Z"
+          fill="none" stroke="#07111d" stroke-width="16" stroke-linejoin="round" stroke-linecap="round"/>
+    <path d="M56 55v49c0 12-2 21-8 31L9 201c-7 10-7 23-1 33s16 15 28 16h92c12-1 22-6 28-16s6-23-1-33l-39-66c-6-10-8-19-8-31V55H56Z"
+          fill="none" stroke="#263b57" stroke-width="12" stroke-linejoin="round" stroke-linecap="round"/>
+
+    <circle cx="82" cy="80" r="4.7" fill="#009fe9" stroke="#0b1d35" stroke-width=".7"/>
+    <circle cx="82" cy="104" r="6.2" fill="#078ae9" stroke="#0b1d35" stroke-width=".7"/>
+    <circle cx="82" cy="128" r="7.2" fill="#3256d9" stroke="#0b1d35" stroke-width=".7"/>
+  </g>
+
+  <g stroke="#17233c" stroke-width=".75">
+    <rect x="116" y="22" width="13" height="13" rx="2" fill="#7342bd"/>
+    <rect x="137" y="13" width="19" height="19" rx="1.5" fill="url(#jp-xtralab-logo-pixel-blue)"/>
+    <rect x="154" y="39" width="24" height="22" rx="1.5" fill="url(#jp-xtralab-logo-pixel-purple)"/>
+    <rect x="166" y=".5" width="17" height="17" rx="1.5" fill="url(#jp-xtralab-logo-pixel-pink)"/>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xtralab",
-    "version": "0.13.1",
+    "version": "0.14.1",
     "description": "An opinionated JupyterLab meta-package that bundles a curated set of extensions, ships a path-first file browser, renders jupyterlab-git's text, notebook and image diffs with its own viewers, and applies a quieter default workspace configuration.",
     "keywords": [
         "jupyter",
@@ -21,7 +21,8 @@
         "lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}",
         "style/**/*.{css,js,eot,gif,html,jpg,json,png,svg,woff2,ttf}",
         "src/**/*.{ts,tsx}",
-        "schema/*.json"
+        "schema/*.json",
+        "logo.svg"
     ],
     "main": "lib/index.js",
     "types": "lib/index.d.ts",
@@ -141,6 +142,7 @@
             "@jupyterlab/git:notebook-diff",
             "@jupyterlab/git:plain-text-diff",
             "@jupyterlab/git:image-diff",
+            "@jupyterlab/help-extension:about",
             "@jupyterlab/launcher-extension"
         ]
     },

package/schema/about.json

@@ -0,0 +1,24 @@
+{
+  "jupyter.lab.menus": {
+    "main": [
+      {
+        "id": "jp-mainmenu-help",
+        "items": [
+          {
+            "command": "help:about",
+            "rank": 0
+          },
+          {
+            "type": "separator",
+            "rank": 0
+          }
+        ]
+      }
+    ]
+  },
+  "title": "xtralab About",
+  "description": "The About dialog showing the running xtralab and JupyterLab versions.",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}

package/schema/menu-bar.json

@@ -0,0 +1,37 @@
+{
+  "title": "xtralab menu bar",
+  "description": "Visibility of the main menu bar.",
+  "jupyter.lab.shortcuts": [],
+  "jupyter.lab.menus": {
+    "main": [
+      {
+        "id": "jp-mainmenu-view",
+        "items": [
+          {
+            "type": "submenu",
+            "rank": 1,
+            "submenu": {
+              "id": "jp-mainmenu-view-appearance",
+              "items": [
+                {
+                  "command": "xtralab:toggle-menu-bar",
+                  "rank": 14
+                }
+              ]
+            }
+          }
+        ]
+      }
+    ]
+  },
+  "type": "object",
+  "properties": {
+    "visible": {
+      "type": "boolean",
+      "title": "Show the menu bar",
+      "description": "When false, hides the main menu bar. Its menus stay available from the menu button at the leading edge of the top bar and the bar can be restored from View → Appearance → Show Menu Bar.",
+      "default": false
+    }
+  },
+  "additionalProperties": false
+}

package/src/about/icons.ts

@@ -0,0 +1,13 @@
+import { LabIcon } from '@jupyterlab/ui-components';
+
+import logoSvgstr from '../../logo.svg';
+
+/**
+ * The project logo mark — `logo.svg` at the repository root, the same file
+ * the README and the docs site use. The labextension build inlines it as a
+ * raw string, so the dialog always shows the current artwork.
+ */
+export const aboutLogoIcon = new LabIcon({
+  name: 'xtralab:about-logo',
+  svgstr: logoSvgstr
+});

package/src/about/index.tsx

@@ -0,0 +1,125 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { Dialog, ICommandPalette, showDialog } from '@jupyterlab/apputils';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import * as React from 'react';
+
+import { aboutLogoIcon } from './icons';
+
+const PLUGIN_ID = 'xtralab:about';
+
+/**
+ * Upstream command id. Reusing it keeps the Help menu entry (contributed by
+ * `schema/about.json` at the same rank as upstream), the command palette
+ * muscle memory, and any external caller of `help:about` working.
+ */
+const CommandIDs = {
+  about: 'help:about'
+};
+
+const REPO_URL = 'https://github.com/jtpio/xtralab';
+
+/**
+ * An "About xtralab" dialog replacing the stock "About JupyterLab" one.
+ *
+ * The upstream `@jupyterlab/help-extension:about` plugin is disabled via
+ * `jupyterlab.disabledExtensions` (package.json), which removes both its
+ * `help:about` command and its Help menu contribution; this plugin registers
+ * the same command id and restores the menu entry through its own schema.
+ * The dialog leads with the xtralab version and keeps the underlying
+ * JupyterLab version visible underneath.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description: 'Show an About dialog with the xtralab and JupyterLab versions.',
+  autoStart: true,
+  requires: [ISettingRegistry],
+  optional: [ICommandPalette, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    settingRegistry: ISettingRegistry,
+    palette: ICommandPalette | null,
+    translator: ITranslator | null
+  ): void => {
+    const { commands } = app;
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+
+    commands.addCommand(CommandIDs.about, {
+      label: trans.__('About %1', 'xtralab'),
+      describedBy: {
+        args: {
+          type: 'object',
+          properties: {}
+        }
+      },
+      execute: async () => {
+        // The settings payload carries the version of the installed
+        // labextension (read server-side from its package.json), which is
+        // the release actually running — the page config only knows the
+        // JupyterLab version. 'N/A' is jupyterlab_server's not-found value.
+        const version = await settingRegistry
+          .load(PLUGIN_ID)
+          .then(settings =>
+            settings.version === 'N/A' ? '' : settings.version
+          )
+          .catch(() => '');
+
+        const title = (
+          <span className="jp-xtralab-About-header">
+            <aboutLogoIcon.react
+              className="jp-xtralab-About-logo"
+              height="56px"
+              width="56px"
+            />
+            <div className="jp-xtralab-About-header-info">
+              <span className="jp-xtralab-About-wordmark">xtralab</span>
+              {version ? (
+                <span className="jp-xtralab-About-version">
+                  {trans.__('Version %1', version)}
+                </span>
+              ) : null}
+            </div>
+          </span>
+        );
+
+        const body = (
+          <div className="jp-xtralab-About-body">
+            <span className="jp-xtralab-About-basedOn">
+              {trans.__('Based on JupyterLab %1', app.version)}
+            </span>
+            <span className="jp-xtralab-About-externalLinks">
+              <a href={REPO_URL} target="_blank" rel="noopener noreferrer">
+                {trans.__('xtralab on GitHub')}
+              </a>
+            </span>
+            <span className="jp-xtralab-About-copyright">
+              {trans.__('© %1 Jeremy Tuloup', 2026)}
+            </span>
+          </div>
+        );
+
+        return showDialog({
+          title,
+          body,
+          buttons: [
+            Dialog.cancelButton({
+              label: trans.__('Close')
+            })
+          ]
+        });
+      }
+    });
+
+    if (palette) {
+      palette.addItem({
+        command: CommandIDs.about,
+        category: trans.__('Help')
+      });
+    }
+  }
+};
+
+export default plugin;

package/src/index.ts

@@ -1,5 +1,6 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 
+import aboutPlugin from './about';
 import agentSessionsPlugin from './agentSessions';
 import askAgentPlugin from './askAgent';
 import commandBarPlugin from './commandBar';
@@ -10,6 +11,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';
@@ -30,6 +32,7 @@ import walkthroughPlugin from './walkthrough';
  * they are spread in.
  */
 const plugins: JupyterFrontEndPlugin<unknown>[] = [
+  aboutPlugin,
   agentSessionsPlugin,
   askAgentPlugin,
   commandBarPlugin,
@@ -40,6 +43,7 @@ const plugins: JupyterFrontEndPlugin<unknown>[] = [
   ...gitPlugins,
   highlightPlugin,
   ...launcherPlugins,
+  menuBarPlugin,
   menusPlugin,
   omniboxPlugin,
   searchReplacePlugin,

package/src/menuBar/icons.ts

@@ -0,0 +1,14 @@
+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/src/menuBar/index.ts

@@ -0,0 +1,195 @@
+import {
+  ILabShell,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} 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, Widget } 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: JupyterFrontEndPlugin<void> = {
+  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: JupyterFrontEnd,
+    mainMenu: IMainMenu,
+    labShell: ILabShell,
+    settingRegistry: ISettingRegistry,
+    palette: ICommandPalette | null,
+    translator: ITranslator | null
+  ): void => {
+    const { commands } = app;
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+
+    if (!(mainMenu instanceof MainMenu)) {
+      return;
+    }
+
+    const menuPanel = (): Widget | null =>
+      mainMenu.parent ??
+      Array.from(labShell.widgets('top')).find(w => w.id === 'jp-menu-panel') ??
+      null;
+
+    let visible = false;
+    let button: CommandToolbarButton | null = null;
+    let settings: ISettingRegistry.ISettings | null = null;
+
+    const applyVisibility = (value: boolean): void => {
+      visible = value;
+      mainMenu.setHidden(!value);
+      menuPanel()?.setHidden(!value);
+      button?.setHidden(value);
+      commands.notifyCommandChanged(TOGGLE_COMMAND);
+    };
+
+    mainMenu.hide();
+    menuPanel()?.hide();
+
+    let popup: Menu | null = null;
+    let popupClosedAt = 0;
+
+    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.
+        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?.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(anchor?.left ?? 0, (anchor?.bottom ?? 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 = (): void => {
+          applyVisibility(loaded.get('visible').composite as boolean);
+        };
+        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;