xtralab 0.14.1 → 0.15.1

package/lib/terminals/widget.d.ts

@@ -1,50 +1,88 @@
+import { IMovableSectionDestination, IMovableSectionSource, ISectionEntry } from '@jupyterlab/apputils';
 import { type TranslationBundle } from '@jupyterlab/translation';
-import { LabIcon, ReactWidget } from '@jupyterlab/ui-components';
-import * as React from 'react';
+import { LabIcon, SidePanel } from '@jupyterlab/ui-components';
+import { ISignal } from '@lumino/signaling';
+import { AccordionPanel, Widget } from '@lumino/widgets';
 import { SessionRegistry } from './model';
 /**
- * Left-sidebar panel listing every running terminal session. It is the
- * sidebar counterpart of the launcher's terminal tiles: where the
- * launcher *starts* sessions, this panel surfaces the ones already
- * running so the user can jump back to a backgrounded agent — including
- * sessions whose tab has been closed but which are still alive on the
- * server. Each row is labelled with the session's title and, for a session
- * running a coding agent, a smaller line below it showing the agent's latest
- * line of output (from {@link SessionRegistry.activityFor}).
- *
- * Backed by {@link SessionRegistry}: a `UseSignal` re-renders the list
- * whenever the registry emits `stateChanged`, so it tracks
- * `runningChanged` and the agent-title cache without any local state.
- * Click behavior (activate vs. reopen, shutdown, new terminal) is
- * delegated to plugin-supplied callbacks so the widget never imports
- * `app`.
+ * Left-sidebar panel listing every running terminal session, including the
+ * sessions whose tab is closed but which are still alive on the server. The
+ * list is a single movable "Terminals" section.
  */
-export declare class RunningTerminals extends ReactWidget {
+export declare class RunningTerminals extends SidePanel implements IMovableSectionSource, IMovableSectionDestination {
     constructor(options: RunningTerminals.IOptions);
+    /**
+     * The accordion panel hosting the sections; read by the move plugin.
+     */
+    get accordionPanel(): AccordionPanel;
+    /**
+     * A signal emitted when a section is announced to the move plugin.
+     */
+    get sectionAdded(): ISignal<this, ISectionEntry>;
+    /**
+     * The hosted section widgets, excluding the panel's own Terminals section.
+     */
+    get sections(): ReadonlyArray<Widget>;
+    /**
+     * Get the movable sections: just the Terminals section, while attached here.
+     */
+    getSections(): ReadonlyArray<ISectionEntry>;
+    /**
+     * Detach the Terminals section for the move plugin and return it; `null`
+     * for an unknown id or when the section is already hosted elsewhere.
+     */
+    removeSectionById(sectionId: string): Widget | null;
+    /**
+     * Re-attach the Terminals section after it moves back to this panel.
+     */
+    reinsertSection(widget: Widget): void;
+    /**
+     * Host a section moved in from another sidebar panel.
+     */
+    addSection(widget: Widget): void;
+    /**
+     * Detach a hosted section when it moves back to its own panel.
+     */
+    removeSectionWidget(widget: Widget): void;
+    /**
+     * The layout restorer stores a section as collapsed whenever its panel is off
+     * screen at save time, so it can come back collapsed without the user asking.
+     */
+    expandOwnSection(): void;
+    /**
+     * The move plugin reconciles persisted moves only against sections announced
+     * after `registerSource`, and this panel builds its section in the constructor.
+     */
+    announceSections(): void;
+    /**
+     * Dispose of the panel and the registry it owns.
+     */
     dispose(): void;
-    protected render(): React.ReactElement;
+    private _sectionEntry;
     private _registry;
-    private _trans;
-    private _iconForCommand;
-    private _onActivate;
-    private _onShutdown;
-    private _onShutdownAll;
-    private _onCreate;
+    private _section;
+    private _sectionAdded;
 }
 export declare namespace RunningTerminals {
+    /**
+     * The instantiation options for a {@link RunningTerminals} panel.
+     */
     interface IOptions {
+        /**
+         * The session registry the panel renders and takes ownership of.
+         */
         registry: SessionRegistry;
+        /**
+         * The translation bundle for the panel's labels; untranslated if omitted.
+         */
         trans?: TranslationBundle;
         /**
-         * Resolve the running-agent command for a row (from
-         * `registry.agentCommandFor`) to the icon to show before its label —
-         * the agent's logo, or the plain terminal icon. Supplied by the plugin
-         * so the widget never imports the agent list.
+         * Resolve a row's running-agent command to its icon; supplied by the
+         * plugin so the widget never imports the agent list.
          */
         iconForCommand: (command: string | null) => LabIcon;
         /**
-         * Activate the named session's open tab, or reopen it in a fresh
-         * terminal widget if no tab is currently attached.
+         * Activate the named session's open tab, or reopen it in a fresh widget.
          */
         onActivate: (sessionName: string) => void;
         /**
@@ -52,16 +90,12 @@ export declare namespace RunningTerminals {
          */
         onShutdown: (sessionName: string) => void;
         /**
-         * Shut down every running terminal at once. The plugin is expected to
-         * confirm with the user first, since it tears down all live sessions.
+         * Shut down every running terminal; the plugin confirms with the user first.
          */
         onShutdownAll: () => void;
         /**
-         * Activate the "+" button, anchored at the given viewport coordinates
-         * (the bottom-left of the button). The plugin decides what to show
-         * there — a menu of agents plus a plain terminal, or just a new
-         * terminal when no agents are available — so the panel only reports
-         * where the button is and never imports the command/menu machinery.
+         * Handle the "+" button, anchored at its bottom-left in viewport
+         * coordinates; the plugin decides what to show there.
          */
         onCreate: (anchor: {
             x: number;

package/lib/terminals/widget.js

@@ -1,101 +1,201 @@
 import { nullTranslator } from '@jupyterlab/translation';
-import { addIcon, closeIcon, ReactWidget, stopIcon, terminalIcon, UseSignal } from '@jupyterlab/ui-components';
+import { addIcon, closeIcon, PanelWithToolbar, ReactWidget, SidePanel, stopIcon, terminalIcon, ToolbarButton, UseSignal } from '@jupyterlab/ui-components';
+import { Signal } from '@lumino/signaling';
 import * as React from 'react';
+const RUNNING_TERMINALS_ID = 'xtralab-running-terminals';
 /**
- * Id of the panel widget. Used for layout restoration and as the handle
- * the sidebar visibility toggle would target.
+ * Persisted by the movable-sections plugin — must stay stable across releases.
  */
-const RUNNING_TERMINALS_ID = 'xtralab-running-terminals';
+const TERMINALS_SECTION_ID = 'xtralab-terminals-section';
 /**
- * Left-sidebar panel listing every running terminal session. It is the
- * sidebar counterpart of the launcher's terminal tiles: where the
- * launcher *starts* sessions, this panel surfaces the ones already
- * running so the user can jump back to a backgrounded agent — including
- * sessions whose tab has been closed but which are still alive on the
- * server. Each row is labelled with the session's title and, for a session
- * running a coding agent, a smaller line below it showing the agent's latest
- * line of output (from {@link SessionRegistry.activityFor}).
- *
- * Backed by {@link SessionRegistry}: a `UseSignal` re-renders the list
- * whenever the registry emits `stateChanged`, so it tracks
- * `runningChanged` and the agent-title cache without any local state.
- * Click behavior (activate vs. reopen, shutdown, new terminal) is
- * delegated to plugin-supplied callbacks so the widget never imports
- * `app`.
+ * Left-sidebar panel listing every running terminal session, including the
+ * sessions whose tab is closed but which are still alive on the server. The
+ * list is a single movable "Terminals" section.
  */
-export class RunningTerminals extends ReactWidget {
+export class RunningTerminals extends SidePanel {
     constructor(options) {
         var _a;
         super();
+        this._sectionAdded = new Signal(this);
         this._registry = options.registry;
-        this._trans = (_a = options.trans) !== null && _a !== void 0 ? _a : nullTranslator.load('jupyterlab');
-        this._iconForCommand = options.iconForCommand;
-        this._onActivate = options.onActivate;
-        this._onShutdown = options.onShutdown;
-        this._onShutdownAll = options.onShutdownAll;
-        this._onCreate = options.onCreate;
+        const trans = (_a = options.trans) !== null && _a !== void 0 ? _a : nullTranslator.load('jupyterlab');
         this.id = RUNNING_TERMINALS_ID;
         this.title.icon = terminalIcon;
-        this.title.caption = this._trans.__('Running Terminals');
+        this.title.caption = trans.__('Running Terminals');
         this.addClass('jp-xtralab-Terminals');
+        const section = (this._section = new PanelWithToolbar());
+        section.id = TERMINALS_SECTION_ID;
+        section.title.label = trans.__('Terminals');
+        section.addClass('jp-xtralab-Terminals-section');
+        const shutdownAll = new ToolbarButton({
+            icon: stopIcon,
+            onClick: options.onShutdownAll,
+            tooltip: trans.__('Shut Down All Terminals'),
+            enabled: this._registry.sessionNames().length > 0
+        });
+        this._registry.stateChanged.connect(() => {
+            shutdownAll.enabled = this._registry.sessionNames().length > 0;
+        });
+        section.toolbar.addItem('shutdown-all', shutdownAll);
+        const newTerminal = new ToolbarButton({
+            icon: addIcon,
+            onClick: () => {
+                const rect = newTerminal.node.getBoundingClientRect();
+                options.onCreate({ x: rect.left, y: rect.bottom });
+            },
+            tooltip: trans.__('New Terminal')
+        });
+        section.toolbar.addItem('new-terminal', newTerminal);
+        section.addWidget(new TerminalsListing({
+            registry: this._registry,
+            trans,
+            iconForCommand: options.iconForCommand,
+            onActivate: options.onActivate,
+            onShutdown: options.onShutdown
+        }));
+        this.addWidget(section);
+    }
+    /**
+     * The accordion panel hosting the sections; read by the move plugin.
+     */
+    get accordionPanel() {
+        return this.content;
+    }
+    /**
+     * A signal emitted when a section is announced to the move plugin.
+     */
+    get sectionAdded() {
+        return this._sectionAdded;
+    }
+    /**
+     * The hosted section widgets, excluding the panel's own Terminals section.
+     */
+    get sections() {
+        return this.accordionPanel.widgets.filter(w => w !== this._section);
+    }
+    /**
+     * Get the movable sections: just the Terminals section, while attached here.
+     */
+    getSections() {
+        const entry = this._sectionEntry();
+        return entry ? [entry] : [];
+    }
+    /**
+     * Detach the Terminals section for the move plugin and return it; `null`
+     * for an unknown id or when the section is already hosted elsewhere.
+     */
+    removeSectionById(sectionId) {
+        if (sectionId !== TERMINALS_SECTION_ID ||
+            this._section.parent !== this.content) {
+            return null;
+        }
+        this._section.parent = null;
+        return this._section;
+    }
+    /**
+     * Re-attach the Terminals section after it moves back to this panel.
+     */
+    reinsertSection(widget) {
+        this.addWidget(widget);
+    }
+    /**
+     * Host a section moved in from another sidebar panel.
+     */
+    addSection(widget) {
+        this.addWidget(widget);
+    }
+    /**
+     * Detach a hosted section when it moves back to its own panel.
+     */
+    removeSectionWidget(widget) {
+        if (widget.parent === this.content) {
+            widget.parent = null;
+        }
     }
+    /**
+     * The layout restorer stores a section as collapsed whenever its panel is off
+     * screen at save time, so it can come back collapsed without the user asking.
+     */
+    expandOwnSection() {
+        const accordion = this.accordionPanel;
+        const index = Array.from(accordion.widgets).indexOf(this._section);
+        if (index >= 0) {
+            accordion.expand(index);
+        }
+    }
+    /**
+     * The move plugin reconciles persisted moves only against sections announced
+     * after `registerSource`, and this panel builds its section in the constructor.
+     */
+    announceSections() {
+        const entry = this._sectionEntry();
+        if (entry) {
+            this._sectionAdded.emit(entry);
+        }
+    }
+    /**
+     * Dispose of the panel and the registry it owns.
+     */
     dispose() {
         if (this.isDisposed) {
             return;
         }
-        // The panel owns the registry, so tear down its upstream
-        // subscriptions before the React tree goes away.
+        // The panel owns the registry; tear down its subscriptions first.
         this._registry.dispose();
         super.dispose();
     }
+    _sectionEntry() {
+        const accordion = this.accordionPanel;
+        const index = Array.from(accordion.widgets).indexOf(this._section);
+        const titleNode = accordion.titles[index];
+        if (index < 0 || !titleNode) {
+            return null;
+        }
+        return {
+            id: TERMINALS_SECTION_ID,
+            titleNode,
+            widget: this._section
+        };
+    }
+}
+/**
+ * The body of the Terminals section.
+ */
+class TerminalsListing extends ReactWidget {
+    constructor(options) {
+        super();
+        this._options = options;
+        this.addClass('jp-xtralab-Terminals-listing');
+    }
+    /**
+     * Render the listing, re-rendering on every registry state change.
+     */
     render() {
-        return (React.createElement(UseSignal, { signal: this._registry.stateChanged }, () => (React.createElement(RunningTerminalsComponent, { registry: this._registry, trans: this._trans, iconForCommand: this._iconForCommand, onActivate: this._onActivate, onShutdown: this._onShutdown, onShutdownAll: this._onShutdownAll, onCreate: this._onCreate }))));
+        return (React.createElement(UseSignal, { signal: this._options.registry.stateChanged }, () => (React.createElement(RunningTerminalsComponent, { registry: this._options.registry, trans: this._options.trans, iconForCommand: this._options.iconForCommand, onActivate: this._options.onActivate, onShutdown: this._options.onShutdown }))));
     }
 }
 function RunningTerminalsComponent(props) {
-    const { registry, trans, iconForCommand, onActivate, onShutdown, onShutdownAll, onCreate } = props;
+    const { registry, trans, iconForCommand, onActivate, onShutdown } = props;
     const names = registry.sessionNames();
-    // The session whose terminal is the current widget in the main area, so its
-    // row can be highlighted. `null` when the current tab is a notebook or any
-    // other non-terminal widget.
     const currentName = registry.currentSessionName();
-    return (React.createElement("div", { className: "jp-xtralab-Terminals-body" },
-        React.createElement("div", { className: "jp-xtralab-Terminals-header" },
-            React.createElement("h2", { className: "jp-xtralab-Terminals-title" }, trans.__('Terminals')),
-            React.createElement("div", { className: "jp-xtralab-Terminals-actions" },
-                React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-action jp-xtralab-Terminals-shutdown-all", onClick: onShutdownAll, disabled: names.length === 0, title: trans.__('Shut Down All Terminals'), "aria-label": trans.__('Shut Down All Terminals') },
-                    React.createElement(stopIcon.react, { tag: "span", verticalAlign: "middle" })),
-                React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-action jp-xtralab-Terminals-new", onClick: event => {
-                        // Anchor whatever the plugin shows (usually an agent menu) to
-                        // the button's bottom-left, in viewport coordinates — what
-                        // `Menu.open(x, y)` expects.
-                        const rect = event.currentTarget.getBoundingClientRect();
-                        onCreate({ x: rect.left, y: rect.bottom });
-                    }, title: trans.__('New Terminal'), "aria-label": trans.__('New Terminal'), "aria-haspopup": "menu" },
-                    React.createElement(addIcon.react, { tag: "span", verticalAlign: "middle" })))),
-        names.length === 0 ? (React.createElement("p", { className: "jp-xtralab-Terminals-empty" }, trans.__('No running terminals.'))) : (React.createElement("ul", { className: "jp-xtralab-Terminals-list" }, names.map(name => {
-            const label = registry.labelFor(name);
-            const hasWidget = registry.widgetFor(name) !== null;
-            const tooltip = hasWidget
-                ? trans.__('Activate %1', label)
-                : trans.__('Reopen %1', label);
-            // The running agent's logo (e.g. Claude), or the plain terminal
-            // icon when nothing recognised is running in the session.
-            const RowIcon = iconForCommand(registry.agentCommandFor(name)).react;
-            const isCurrent = name === currentName;
-            // The latest line of output from the session's agent, shown as a
-            // smaller line under the title; `null` for rows with nothing to
-            // surface (no agent running, or no open tab to read a live buffer).
-            const activity = registry.activityFor(name);
-            return (React.createElement("li", { key: name, className: isCurrent
-                    ? 'jp-xtralab-Terminals-item jp-mod-current'
-                    : 'jp-xtralab-Terminals-item' },
-                React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-item-activate", onClick: () => onActivate(name), title: tooltip, "aria-label": tooltip, "aria-current": isCurrent || undefined },
-                    React.createElement(RowIcon, { tag: "span", className: "jp-xtralab-Terminals-item-icon", verticalAlign: "middle" }),
-                    React.createElement("span", { className: "jp-xtralab-Terminals-item-text" },
-                        React.createElement("span", { className: "jp-xtralab-Terminals-item-label" }, label),
-                        activity ? (React.createElement("span", { className: "jp-xtralab-Terminals-item-detail" }, activity)) : null)),
-                React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-item-close", onClick: () => onShutdown(name), title: trans.__('Shut down %1', label), "aria-label": trans.__('Shut down %1', label) },
-                    React.createElement(closeIcon.react, { tag: "span", verticalAlign: "middle" }))));
-        })))));
+    return (React.createElement("div", { className: "jp-xtralab-Terminals-body" }, names.length === 0 ? (React.createElement("p", { className: "jp-xtralab-Terminals-empty" }, trans.__('No running terminals.'))) : (React.createElement("ul", { className: "jp-xtralab-Terminals-list" }, names.map(name => {
+        const label = registry.labelFor(name);
+        const hasWidget = registry.widgetFor(name) !== null;
+        const tooltip = hasWidget
+            ? trans.__('Activate %1', label)
+            : trans.__('Reopen %1', label);
+        const RowIcon = iconForCommand(registry.agentCommandFor(name)).react;
+        const isCurrent = name === currentName;
+        const activity = registry.activityFor(name);
+        return (React.createElement("li", { key: name, className: isCurrent
+                ? 'jp-xtralab-Terminals-item jp-mod-current'
+                : 'jp-xtralab-Terminals-item' },
+            React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-item-activate", onClick: () => onActivate(name), title: tooltip, "aria-label": tooltip, "aria-current": isCurrent || undefined },
+                React.createElement(RowIcon, { tag: "span", className: "jp-xtralab-Terminals-item-icon", verticalAlign: "middle" }),
+                React.createElement("span", { className: "jp-xtralab-Terminals-item-text" },
+                    React.createElement("span", { className: "jp-xtralab-Terminals-item-label" }, label),
+                    activity ? (React.createElement("span", { className: "jp-xtralab-Terminals-item-detail" }, activity)) : null)),
+            React.createElement("button", { type: "button", className: "jp-xtralab-Terminals-item-close", onClick: () => onShutdown(name), title: trans.__('Shut down %1', label), "aria-label": trans.__('Shut down %1', label) },
+                React.createElement(closeIcon.react, { tag: "span", verticalAlign: "middle" }))));
+    })))));
 }

package/lib/topBar/icons.d.ts

@@ -1,13 +1,8 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 /**
- * Mirror-symmetric "toggle sidebar" marks for the top-bar buttons, in the
- * same visual language as the macOS / VS Code / svgrepo sidebar icons
- * (https://www.svgrepo.com/vectors/sidebar/): a rounded window outline split
- * by a divider, with the controlled side shaded so left vs. right reads at a
- * glance. The artwork is hand-authored from basic geometry (rounded rect +
- * divider + a shaded panel) so there is no third-party licensing to track,
- * and every stroke/fill uses `currentColor` so the icons inherit the top
- * bar's text color across the light and dark themes.
+ * Mirror-symmetric "toggle sidebar" marks in the macOS / VS Code visual
+ * language. Hand-authored from basic geometry (no third-party licensing);
+ * every stroke/fill uses `currentColor` to follow the top bar's text color.
  */
 export declare const leftSidebarIcon: LabIcon;
 export declare const rightSidebarIcon: LabIcon;

package/lib/topBar/icons.js

@@ -1,13 +1,8 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 /**
- * Mirror-symmetric "toggle sidebar" marks for the top-bar buttons, in the
- * same visual language as the macOS / VS Code / svgrepo sidebar icons
- * (https://www.svgrepo.com/vectors/sidebar/): a rounded window outline split
- * by a divider, with the controlled side shaded so left vs. right reads at a
- * glance. The artwork is hand-authored from basic geometry (rounded rect +
- * divider + a shaded panel) so there is no third-party licensing to track,
- * and every stroke/fill uses `currentColor` so the icons inherit the top
- * bar's text color across the light and dark themes.
+ * Mirror-symmetric "toggle sidebar" marks in the macOS / VS Code visual
+ * language. Hand-authored from basic geometry (no third-party licensing);
+ * every stroke/fill uses `currentColor` to follow the top bar's text color.
  */
 export const leftSidebarIcon = new LabIcon({
     name: 'xtralab:sidebar-left',

package/lib/topBar/index.d.ts

@@ -1,16 +1,9 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Add two icon buttons to the top bar that toggle the left and right side
- * areas, mirroring the macOS-style sidebar buttons: a left-sidebar button at
- * the leading edge and a right-sidebar button at the far edge.
- *
- * Each is a `CommandToolbarButton` wrapping an existing
- * `application:toggle-{left,right}-area` command, so clicking it runs the
- * same toggle as the View menu and the button reflects the command's state —
- * pressed while the matching sidebar is open, and disabled when the area is
- * empty. Note xtralab ships nothing in the right area by default (the
- * property inspector, table of contents and debugger are all disabled), so
- * the right button stays disabled until a widget is moved or added there.
+ * Add macOS-style sidebar toggle buttons to the top bar: left at the leading
+ * edge, right at the far edge. Each wraps the upstream toggle command and
+ * reflects its state — pressed while the sidebar is open, disabled while the
+ * area is empty (as the right area is by default).
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/topBar/index.js

@@ -3,13 +3,6 @@ import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { CommandToolbarButton } from '@jupyterlab/ui-components';
 import { leftSidebarIcon, rightSidebarIcon } from './icons';
 const PLUGIN_ID = 'xtralab:top-bar';
-/**
- * Upstream commands from `@jupyterlab/application-extension` that collapse or
- * expand the side areas. We bind the buttons to these rather than
- * reimplementing the toggle, so behavior (and the `isToggled`/`isEnabled`
- * state the buttons reflect) stays in lockstep with the View menu entries
- * and their keyboard shortcuts.
- */
 const TOGGLE_LEFT_AREA = 'application:toggle-left-area';
 const TOGGLE_RIGHT_AREA = 'application:toggle-right-area';
 const BUTTONS = [
@@ -31,17 +24,10 @@ const BUTTONS = [
     }
 ];
 /**
- * Add two icon buttons to the top bar that toggle the left and right side
- * areas, mirroring the macOS-style sidebar buttons: a left-sidebar button at
- * the leading edge and a right-sidebar button at the far edge.
- *
- * Each is a `CommandToolbarButton` wrapping an existing
- * `application:toggle-{left,right}-area` command, so clicking it runs the
- * same toggle as the View menu and the button reflects the command's state —
- * pressed while the matching sidebar is open, and disabled when the area is
- * empty. Note xtralab ships nothing in the right area by default (the
- * property inspector, table of contents and debugger are all disabled), so
- * the right button stays disabled until a widget is moved or added there.
+ * Add macOS-style sidebar toggle buttons to the top bar: left at the leading
+ * edge, right at the far edge. Each wraps the upstream toggle command and
+ * reflects its state — pressed while the sidebar is open, disabled while the
+ * area is empty (as the right area is by default).
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -52,39 +38,25 @@ const plugin = {
     activate: (app, labShell, translator) => {
         const { commands } = app;
         const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
-        // The upstream toggle-{left,right}-area commands derive `isEnabled` from
-        // `!labShell.isEmpty(side)` but don't fire `commandChanged` when widgets
-        // move in or out of a side area. `CommandToolbarButton` only re-renders on
-        // `commandChanged` for its own id, so the buttons need an explicit notify
-        // whenever the shell layout shifts — `layoutModified` covers each side
-        // handler's `_updated` (add/remove, expand/collapse), keeping both
-        // `isEnabled` and `isToggled` in sync.
+        // The upstream toggle commands don't fire `commandChanged` on layout
+        // shifts, and `CommandToolbarButton` only re-renders on that signal.
         labShell.layoutModified.connect(() => {
             for (const spec of BUTTONS) {
                 commands.notifyCommandChanged(spec.command);
             }
         });
-        // Defer to `app.restored` so the upstream toggle commands are already in
-        // the registry: `CommandToolbarButton` renders nothing until its command
-        // exists and only re-renders on `commandChanged` of type `changed` /
-        // `many-changed` (not `added`), so mounting earlier could leave a button
-        // blank until the next unrelated command change.
+        // Defer to `app.restored`: `CommandToolbarButton` renders nothing until
+        // its command exists and doesn't re-render on the `added` change type.
         void app.restored.then(() => {
             for (const spec of BUTTONS) {
                 const button = new CommandToolbarButton({
                     commands,
                     id: spec.command,
                     icon: spec.icon,
-                    // Empty label keeps the button icon-only: the override is forwarded
-                    // verbatim and the component skips the label span when it is falsy.
                     label: '',
                     caption: spec.caption(trans),
-                    // Toggle on mousedown without focusing the button. Otherwise
-                    // ToolbarButtonComponent calls `event.target.focus()` on click,
-                    // leaving the stealth button showing a focus fill/outline (the
-                    // stray "border") until you click elsewhere — unwanted chrome for a
-                    // title-bar control. Keyboard Tab focus still works, so this stays
-                    // accessible.
+                    // ToolbarButtonComponent otherwise focuses the button on click,
+                    // leaving a stray focus fill on this title-bar control; Tab still works.
                     noFocusOnClick: true
                 });
                 button.id = spec.id;

package/lib/walkthrough/index.d.ts

@@ -1,14 +1,9 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Contribute `xtralab:walkthrough`: build a persistent, read-only walkthrough
- * in the right side area instead of narrating only in the agent's chat.
- *
- * Each call appends a step (Markdown prose, an optional embedded visual, and an
- * optional code reference). When a step names a file, the editor follows along
- * (opening it full-width in the main area, no split) and its lines are
- * highlighted; the step also keeps a button so the user can jump back to it
- * later. The panel accumulates the whole tour beside the code, so the user can
- * read at their own pace rather than chasing the chat.
+ * Contributes `xtralab:walkthrough`: each call appends a step (Markdown prose,
+ * optional visual, optional code reference) to a persistent read-only panel in
+ * the right side area, so the tour accumulates beside the code instead of
+ * scrolling away in the agent's chat.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/walkthrough/index.js

@@ -6,15 +6,9 @@ import { tocIcon } from '@jupyterlab/ui-components';
 import { coerceData } from '../mimeData';
 import { WalkthroughPanel } from './panel';
 const PLUGIN_ID = 'xtralab:walkthrough';
-/**
- * Append a step to the read-only walkthrough panel.
- */
 const WALKTHROUGH_COMMAND = 'xtralab:walkthrough';
 const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
 const PANEL_ID = 'xtralab-walkthrough';
-/**
- * Pull a `{ mimeType, data }` media object out of a JSON command argument.
- */
 function readMedia(value) {
     if (value &&
         typeof value === 'object' &&
@@ -36,15 +30,10 @@ function toLine(value) {
     return Number.isFinite(n) && n >= 1 ? n : undefined;
 }
 /**
- * Contribute `xtralab:walkthrough`: build a persistent, read-only walkthrough
- * in the right side area instead of narrating only in the agent's chat.
- *
- * Each call appends a step (Markdown prose, an optional embedded visual, and an
- * optional code reference). When a step names a file, the editor follows along
- * (opening it full-width in the main area, no split) and its lines are
- * highlighted; the step also keeps a button so the user can jump back to it
- * later. The panel accumulates the whole tour beside the code, so the user can
- * read at their own pace rather than chasing the chat.
+ * Contributes `xtralab:walkthrough`: each call appends a step (Markdown prose,
+ * optional visual, optional code reference) to a persistent read-only panel in
+ * the right side area, so the tour accumulates beside the code instead of
+ * scrolling away in the agent's chat.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -63,9 +52,8 @@ const plugin = {
                 panel.title.icon = tocIcon;
                 panel.title.label = trans.__('Walkthrough');
                 panel.title.caption = trans.__('Walkthrough');
-                // Closable so it gets a close button if the user drags it out of the
-                // side area into the main document area. Closing disposes it; the next
-                // xtralab:walkthrough call recreates it back in the side area.
+                // Closable so a drag into the main area gets a close button; closing
+                // disposes, and the next call recreates the panel in the side area.
                 panel.title.closable = true;
                 labShell.add(panel, 'right', { rank: 1000, type: 'Walkthrough' });
                 const created = panel;
@@ -148,10 +136,8 @@ const plugin = {
                     args['reset'] !== true) {
                     throw new Error('xtralab:walkthrough needs at least one of: title, body, media, path');
                 }
-                // Reveal the panel, then render the step into it.
                 labShell.activateById(current.id);
                 await current.addStep(step);
-                // Let the editor follow the newest step.
                 if (path && args['reveal'] !== false) {
                     await commands.execute(HIGHLIGHT_LINES_COMMAND, {
                         path,