xtralab 0.14.1 → 0.15.1

package/src/terminals/tokens.ts

@@ -12,16 +12,13 @@ export interface IAgentTerminalSession {
   name: string;
 
   /**
-   * The agent identifier server-side detection reported for the session:
-   * the configured `command`, or the canonical agent `id` when the command
-   * is an alias (e.g. `ccm` spawning `claude`). Matches an `IAgent` by
-   * either field.
+   * The agent identifier detection reported: the configured `command`, or the
+   * canonical `id` when the command is an alias (e.g. `ccm` spawning `claude`).
    */
   command: string;
 
   /**
-   * Display label — the session's real title (the launcher's agent name, or
-   * whatever the running program published via an xterm escape sequence).
+   * Display label — the session's real (program-published) title.
    */
   label: string;
 
@@ -35,12 +32,9 @@ export interface IAgentTerminalSession {
 /**
  * Running agent terminals, and a way to send a prompt into one.
  *
- * `sessions` only lists sessions where server-side process detection has
- * *confirmed* a running coding agent (editors and plain shells are excluded,
- * as are optimistic just-launched tags): every listed session is one whose
- * TUI can meaningfully receive pasted prompt text. `sendPrompt` re-validates
- * against the server before writing, since pasting prose into a shell prompt
- * would execute it.
+ * Only sessions with a detection-*confirmed* running agent are listed — never
+ * optimistic launch tags: pasted prompt text must land in an agent's TUI, not
+ * a shell prompt where it would be executed.
  */
 export interface IAgentTerminals {
   /**
@@ -54,22 +48,17 @@ export interface IAgentTerminals {
   readonly changed: ISignal<IAgentTerminals, void>;
 
   /**
-   * Paste `prompt` into the named session's terminal and press Enter.
-   *
-   * Delivery is deliberately background: the text is written straight to
-   * the session's websocket, bracketed-paste-wrapped so a multi-line prompt
-   * arrives as one block in the agent's input box, without revealing or
-   * focusing the terminal's tab — the user keeps working where they are,
-   * and the agent CLIs queue the prompt themselves when they are busy.
-   * Rejects when the session is gone or no agent is running in it anymore.
+   * Paste `prompt` (bracketed-paste-wrapped) into the named session and press
+   * Enter, writing straight to its websocket without revealing or focusing
+   * its tab. Rejects when the session is gone or no agent runs in it anymore.
    */
   sendPrompt(name: string, prompt: string): Promise<void>;
 }
 
 /**
  * DI token for {@link IAgentTerminals}. Provided by `xtralab:terminals`;
- * consumed — optionally, so each side works without the other — by
- * `xtralab:ask-agent` to offer running agent terminals as prompt targets.
+ * consumed optionally by `xtralab:ask-agent`, so each side works without
+ * the other.
  */
 export const IAgentTerminals = new Token<IAgentTerminals>(
   'xtralab:IAgentTerminals',

package/src/terminals/widget.tsx

@@ -1,3 +1,8 @@
+import {
+  IMovableSectionDestination,
+  IMovableSectionSource,
+  ISectionEntry
+} from '@jupyterlab/apputils';
 import {
   type TranslationBundle,
   nullTranslator
@@ -6,106 +11,226 @@ import {
   addIcon,
   closeIcon,
   LabIcon,
+  PanelWithToolbar,
   ReactWidget,
+  SidePanel,
   stopIcon,
   terminalIcon,
+  ToolbarButton,
   UseSignal
 } from '@jupyterlab/ui-components';
+import { ISignal, Signal } from '@lumino/signaling';
+import { AccordionPanel, Widget } from '@lumino/widgets';
 import * as React from 'react';
 
 import { SessionRegistry } from './model';
 
+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
+  implements IMovableSectionSource, IMovableSectionDestination
+{
   constructor(options: RunningTerminals.IOptions) {
     super();
     this._registry = options.registry;
-    this._trans = options.trans ?? 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 = options.trans ?? 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(): AccordionPanel {
+    return this.content as AccordionPanel;
+  }
+
+  /**
+   * A signal emitted when a section is announced to the move plugin.
+   */
+  get sectionAdded(): ISignal<this, ISectionEntry> {
+    return this._sectionAdded;
+  }
+
+  /**
+   * The hosted section widgets, excluding the panel's own Terminals section.
+   */
+  get sections(): ReadonlyArray<Widget> {
+    return this.accordionPanel.widgets.filter(w => w !== this._section);
+  }
+
+  /**
+   * Get the movable sections: just the Terminals section, while attached here.
+   */
+  getSections(): ReadonlyArray<ISectionEntry> {
+    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: string): Widget | null {
+    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: Widget): void {
+    this.addWidget(widget);
+  }
+
+  /**
+   * Host a section moved in from another sidebar panel.
+   */
+  addSection(widget: Widget): void {
+    this.addWidget(widget);
+  }
+
+  /**
+   * Detach a hosted section when it moves back to its own panel.
+   */
+  removeSectionWidget(widget: Widget): void {
+    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(): void {
+    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(): void {
+    const entry = this._sectionEntry();
+    if (entry) {
+      this._sectionAdded.emit(entry);
+    }
+  }
+
+  /**
+   * Dispose of the panel and the registry it owns.
+   */
   dispose(): void {
     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();
   }
 
-  protected render(): React.ReactElement {
-    return (
-      <UseSignal signal={this._registry.stateChanged}>
-        {() => (
-          <RunningTerminalsComponent
-            registry={this._registry}
-            trans={this._trans}
-            iconForCommand={this._iconForCommand}
-            onActivate={this._onActivate}
-            onShutdown={this._onShutdown}
-            onShutdownAll={this._onShutdownAll}
-            onCreate={this._onCreate}
-          />
-        )}
-      </UseSignal>
-    );
+  private _sectionEntry(): ISectionEntry | null {
+    const accordion = this.accordionPanel;
+    const index = Array.from(accordion.widgets).indexOf(this._section);
+    const titleNode = accordion.titles[index] as HTMLElement | undefined;
+    if (index < 0 || !titleNode) {
+      return null;
+    }
+    return {
+      id: TERMINALS_SECTION_ID,
+      titleNode,
+      widget: this._section
+    };
   }
 
   private _registry: SessionRegistry;
-  private _trans: TranslationBundle;
-  private _iconForCommand: (command: string | null) => LabIcon;
-  private _onActivate: (sessionName: string) => void;
-  private _onShutdown: (sessionName: string) => void;
-  private _onShutdownAll: () => void;
-  private _onCreate: (anchor: { x: number; y: number }) => void;
+  private _section: PanelWithToolbar;
+  private _sectionAdded = new Signal<this, ISectionEntry>(this);
 }
 
 export namespace RunningTerminals {
+  /**
+   * The instantiation options for a {@link RunningTerminals} panel.
+   */
   export 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;
     /**
@@ -113,78 +238,74 @@ export 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; y: number }) => void;
   }
 }
 
+/**
+ * The body of the Terminals section.
+ */
+class TerminalsListing extends ReactWidget {
+  constructor(options: {
+    registry: SessionRegistry;
+    trans: TranslationBundle;
+    iconForCommand: (command: string | null) => LabIcon;
+    onActivate: (sessionName: string) => void;
+    onShutdown: (sessionName: string) => void;
+  }) {
+    super();
+    this._options = options;
+    this.addClass('jp-xtralab-Terminals-listing');
+  }
+
+  /**
+   * Render the listing, re-rendering on every registry state change.
+   */
+  protected render(): React.ReactElement {
+    return (
+      <UseSignal signal={this._options.registry.stateChanged}>
+        {() => (
+          <RunningTerminalsComponent
+            registry={this._options.registry}
+            trans={this._options.trans}
+            iconForCommand={this._options.iconForCommand}
+            onActivate={this._options.onActivate}
+            onShutdown={this._options.onShutdown}
+          />
+        )}
+      </UseSignal>
+    );
+  }
+
+  private _options: {
+    registry: SessionRegistry;
+    trans: TranslationBundle;
+    iconForCommand: (command: string | null) => LabIcon;
+    onActivate: (sessionName: string) => void;
+    onShutdown: (sessionName: string) => void;
+  };
+}
+
 function RunningTerminalsComponent(props: {
   registry: SessionRegistry;
   trans: TranslationBundle;
   iconForCommand: (command: string | null) => LabIcon;
   onActivate: (sessionName: string) => void;
   onShutdown: (sessionName: string) => void;
-  onShutdownAll: () => void;
-  onCreate: (anchor: { x: number; y: number }) => void;
 }): React.ReactElement {
-  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 (
     <div className="jp-xtralab-Terminals-body">
-      <div className="jp-xtralab-Terminals-header">
-        <h2 className="jp-xtralab-Terminals-title">{trans.__('Terminals')}</h2>
-        <div className="jp-xtralab-Terminals-actions">
-          <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')}
-          >
-            <stopIcon.react tag="span" verticalAlign="middle" />
-          </button>
-          <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"
-          >
-            <addIcon.react tag="span" verticalAlign="middle" />
-          </button>
-        </div>
-      </div>
       {names.length === 0 ? (
         <p className="jp-xtralab-Terminals-empty">
           {trans.__('No running terminals.')}
@@ -197,15 +318,10 @@ function RunningTerminalsComponent(props: {
             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 (
               <li

package/src/topBar/icons.ts

@@ -1,14 +1,9 @@
 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({

package/src/topBar/index.ts

@@ -10,16 +10,12 @@ 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';
 
+/**
+ * A specification for one sidebar toggle button in the top area.
+ */
 interface IButtonSpec {
   /**
    * Stable widget id (required by `LabShell.add`).
@@ -29,15 +25,17 @@ interface IButtonSpec {
    * Command the button triggers and mirrors the state of.
    */
   command: string;
+  /**
+   * The icon rendered on the button.
+   */
   icon: LabIcon;
+  /**
+   * The localized tooltip of the button.
+   */
   caption: (trans: ReturnType<ITranslator['load']>) => string;
   /**
-   * Rank within the `top` area. The main menu bar is added at rank 100, so a
-   * negative rank lands the left button at the leading edge before it; a large
-   * rank puts the right button after the menu, where `margin-left: auto`
-   * (style/topBar.css) floats it to the far edge. xtralab's shipped config
-   * disables the upstream Jupyter logo that otherwise occupies rank 0, so the
-   * leading edge is free.
+   * Rank in the `top` area: the menu bar sits at 100 and the rank-0 upstream
+   * logo is disabled; `margin-left: auto` (topBar.css) floats the right button.
    */
   rank: number;
   /**
@@ -66,17 +64,10 @@ const BUTTONS: IButtonSpec[] = [
 ];
 
 /**
- * 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: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -92,40 +83,26 @@ const plugin: JupyterFrontEndPlugin<void> = {
     const { commands } = app;
     const trans = (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;