xtralab 0.1.1 → 0.2.0

package/src/statusBar/index.ts

@@ -0,0 +1,115 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { IStatusBar } from '@jupyterlab/statusbar';
+import { ITerminalTracker } from '@jupyterlab/terminal';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { DisposableSet, type IDisposable } from '@lumino/disposable';
+
+import { SessionRegistry, TerminalSessionItem } from './widget';
+
+const PLUGIN_ID = 'xtralab:statusBar';
+
+/**
+ * Surfaces every running terminal session as its own item on the left
+ * side of the status bar. The list is driven by
+ * `serviceManager.terminals.runningChanged`, not by the widget tracker,
+ * so a session that has its tab closed but is still running on the
+ * backend keeps its slot — the typical state for an agent the user has
+ * stepped away from. Clicking an item activates the existing tab if one
+ * is open, or reopens the session in a fresh terminal widget. The
+ * inline `×` button shuts the session down on the server, which
+ * cascades through the widget if it is currently open.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'Surface each running terminal session as its own status bar item so users can jump to (or reopen) backgrounded agents from anywhere in the workspace.',
+  autoStart: true,
+  requires: [IStatusBar, ITerminalTracker],
+  optional: [ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    statusBar: IStatusBar,
+    tracker: ITerminalTracker,
+    translator: ITranslator | null
+  ): void => {
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+    const registry = new SessionRegistry(app.serviceManager, tracker);
+
+    // One DisposableSet per session — registerStatusItem returns an
+    // IDisposable for the registration, and the item widget itself
+    // implements IDisposable. Bundling them lets a single `dispose()`
+    // tear the slot down completely when the session goes away.
+    const items = new Map<string, IDisposable>();
+
+    const onActivate = (name: string): void => {
+      // `terminal:open` is the upstream entry point that handles both
+      // sides of this: if a widget is already attached to the named
+      // session it activates that tab, otherwise it spins up a fresh
+      // widget connected to the live session. Reusing it keeps the
+      // path identical to a click in the running-sessions sidebar.
+      void app.commands.execute('terminal:open', { name });
+    };
+
+    const onShutdown = (name: string): void => {
+      void app.serviceManager.terminals.shutdown(name).catch(reason => {
+        console.error(
+          `xtralab: failed to shut down terminal ${name}: ${reason}`
+        );
+      });
+    };
+
+    const sync = (): void => {
+      const live = new Set(registry.sessionNames());
+
+      // Add items for newly-seen sessions. We register each at its
+      // stable rank from the registry so re-creating an item between
+      // syncs (e.g. if we ever decide to swap representations) lands
+      // in the same slot.
+      for (const name of live) {
+        if (items.has(name)) {
+          continue;
+        }
+        const item = new TerminalSessionItem({
+          registry,
+          sessionName: name,
+          trans,
+          onActivate,
+          onShutdown
+        });
+        const registration = statusBar.registerStatusItem(
+          `${PLUGIN_ID}:${name}`,
+          {
+            item,
+            align: 'left',
+            rank: registry.rankFor(name)
+          }
+        );
+        const set = new DisposableSet();
+        set.add(registration);
+        set.add(item);
+        items.set(name, set);
+      }
+
+      // Remove items for sessions the server no longer knows about.
+      for (const [name, disposable] of Array.from(items.entries())) {
+        if (!live.has(name)) {
+          disposable.dispose();
+          items.delete(name);
+        }
+      }
+    };
+
+    registry.stateChanged.connect(sync);
+    void app.serviceManager.terminals.ready.then(() => {
+      // The first `runningChanged` may have fired before our connect,
+      // depending on how the manager initialises — refresh once after
+      // it is ready so any pre-existing sessions get their items.
+      sync();
+    });
+  }
+};
+
+export default plugin;

package/src/statusBar/widget.tsx

@@ -0,0 +1,318 @@
+import type { MainAreaWidget } from '@jupyterlab/apputils';
+import type { ServiceManager, Terminal } from '@jupyterlab/services';
+import type { ITerminal, ITerminalTracker } from '@jupyterlab/terminal';
+import {
+  type TranslationBundle,
+  nullTranslator
+} from '@jupyterlab/translation';
+import {
+  closeIcon,
+  terminalIcon,
+  VDomModel,
+  VDomRenderer
+} from '@jupyterlab/ui-components';
+import type { Title, Widget } from '@lumino/widgets';
+import * as React from 'react';
+
+/**
+ * The widget shape every entry in `ITerminalTracker` takes — kept here
+ * so the registry's call sites read cleanly.
+ */
+export type TerminalWidget = MainAreaWidget<ITerminal.ITerminal>;
+
+/**
+ * Source-of-truth model for the status bar. Each running terminal
+ * session known to the server is one entry; the registry caches the
+ * last `widget.title.label` we observed so the agent name (or any
+ * xterm-published title) survives the user closing the tab while the
+ * session continues running on the backend.
+ *
+ * Two upstream signals feed the model:
+ *   - `serviceManager.terminals.runningChanged` is the authoritative
+ *     list of live sessions; everything not in it has been shut down
+ *     server-side and we must drop it.
+ *   - `tracker.widgetAdded` plus the per-widget `title.changed` /
+ *     `disposed` signals keep our label cache in sync with whatever
+ *     xterm/the launcher has set on the open tabs.
+ *
+ * `stateChanged` is reused for both kinds of update so consumers
+ * (the per-session status item, the plugin's add/remove sync) can
+ * subscribe once.
+ */
+export class SessionRegistry extends VDomModel {
+  constructor(
+    serviceManager: ServiceManager.IManager,
+    tracker: ITerminalTracker
+  ) {
+    super();
+    this._terminals = serviceManager.terminals;
+    this._tracker = tracker;
+
+    this._terminals.runningChanged.connect(this._onRunningChanged, this);
+    this._tracker.widgetAdded.connect(this._onWidgetAdded, this);
+    this._tracker.forEach(widget => this._trackWidget(widget));
+    this._refreshLive();
+  }
+
+  /**
+   * Names of all live sessions, ordered by their stable rank so the
+   * status bar items keep their slots as new sessions are added.
+   */
+  sessionNames(): string[] {
+    const names = Array.from(this._live);
+    names.sort((a, b) => this.rankFor(a) - this.rankFor(b));
+    return names;
+  }
+
+  /**
+   * True iff the named session is still on the server. Used by the
+   * per-session item to render `null` during the brief window between
+   * the session's shutdown and the plugin disposing the item.
+   */
+  has(name: string): boolean {
+    return this._live.has(name);
+  }
+
+  /**
+   * Display name for the session. The cache wins because it only
+   * holds "real" labels (the launcher's agent name or an xterm escape
+   * sequence — see `_cacheLabel` for the filter); reading it first
+   * prevents the transient `Terminal {name}` an XTerm widget shows
+   * during reconnect from flickering into the status bar. The live
+   * widget title is used when no cache exists, and the
+   * `Terminal {name}` fallback covers sessions we have never seen a
+   * widget for (e.g. surviving a lab reload).
+   */
+  labelFor(name: string): string {
+    const cached = this._labels.get(name);
+    if (cached) {
+      return cached;
+    }
+    const widget = this.widgetFor(name);
+    if (widget && widget.title.label) {
+      return widget.title.label;
+    }
+    return `Terminal ${name}`;
+  }
+
+  /**
+   * Return the open widget for a session, if any. The status item
+   * uses this to switch behaviour between "activate existing tab"
+   * and "open a new tab connected to the live session".
+   */
+  widgetFor(name: string): TerminalWidget | null {
+    return (
+      this._tracker.find(widget => widget.content.session.name === name) ?? null
+    );
+  }
+
+  /**
+   * Stable per-session rank assigned in observation order. Reused
+   * across `registerStatusItem` calls so an item that is briefly
+   * unregistered (e.g. while a widget is being recreated) lands back
+   * in the same slot. Cleaned up when the session is shut down so the
+   * counter does not grow without bound across long sessions.
+   */
+  rankFor(name: string): number {
+    let rank = this._ranks.get(name);
+    if (rank === undefined) {
+      rank = this._nextRank++;
+      this._ranks.set(name, rank);
+    }
+    return rank;
+  }
+
+  dispose(): void {
+    if (this.isDisposed) {
+      return;
+    }
+    this._terminals.runningChanged.disconnect(this._onRunningChanged, this);
+    this._tracker.widgetAdded.disconnect(this._onWidgetAdded, this);
+    this._tracker.forEach(widget => this._untrackWidget(widget));
+    super.dispose();
+  }
+
+  private _refreshLive(): void {
+    const next = new Set<string>();
+    for (const model of this._terminals.running()) {
+      next.add(model.name);
+    }
+    this._live = next;
+    // Drop cache + rank entries for sessions that have been shut down
+    // server-side. Without this prune the rank counter would keep
+    // climbing across long-running labs as terminals come and go.
+    for (const name of Array.from(this._labels.keys())) {
+      if (!next.has(name)) {
+        this._labels.delete(name);
+      }
+    }
+    for (const name of Array.from(this._ranks.keys())) {
+      if (!next.has(name)) {
+        this._ranks.delete(name);
+      }
+    }
+  }
+
+  private _onRunningChanged(_: unknown, sessions: Terminal.IModel[]): void {
+    this._live = new Set(sessions.map(model => model.name));
+    for (const name of Array.from(this._labels.keys())) {
+      if (!this._live.has(name)) {
+        this._labels.delete(name);
+      }
+    }
+    for (const name of Array.from(this._ranks.keys())) {
+      if (!this._live.has(name)) {
+        this._ranks.delete(name);
+      }
+    }
+    this.stateChanged.emit();
+  }
+
+  private _onWidgetAdded(_: unknown, widget: TerminalWidget): void {
+    this._trackWidget(widget);
+    this.stateChanged.emit();
+  }
+
+  private _trackWidget(widget: TerminalWidget): void {
+    const name = widget.content.session.name;
+    this._cacheLabel(name, widget.title.label);
+    widget.title.changed.connect(this._onTitleChanged, this);
+    widget.disposed.connect(this._onWidgetDisposed, this);
+  }
+
+  private _untrackWidget(widget: TerminalWidget): void {
+    widget.title.changed.disconnect(this._onTitleChanged, this);
+    widget.disposed.disconnect(this._onWidgetDisposed, this);
+  }
+
+  private _onTitleChanged(title: Title<Widget>): void {
+    const owner = title.owner as TerminalWidget;
+    const session = owner.content?.session;
+    if (!session) {
+      return;
+    }
+    this._cacheLabel(session.name, title.label);
+    this.stateChanged.emit();
+  }
+
+  /**
+   * Update the cached label for a session, but only when the new
+   * label is "real" — non-empty and not one of the transient defaults
+   * the XTerm widget cycles through during reconnect (`'...'` while
+   * the websocket is opening, `'Terminal {name}'` once
+   * `_initialConnection` fires). Without the filter, briefly
+   * reopening a tab while an agent has yet to re-emit its xterm
+   * title escape sequence would clobber the cached agent name with
+   * `Terminal 1`, which is exactly the regression we are guarding
+   * against. Live widget titles still display whatever the widget
+   * currently holds because `labelFor` consults the widget first;
+   * the filter only affects what survives a tab close.
+   */
+  private _cacheLabel(name: string, label: string): void {
+    if (!label) {
+      return;
+    }
+    if (label === '...' || label === `Terminal ${name}`) {
+      return;
+    }
+    this._labels.set(name, label);
+  }
+
+  private _onWidgetDisposed(widget: Widget): void {
+    // The widget is gone but the session may still be running on the
+    // server — keep the cached label so the status item keeps the
+    // agent's name when the user reopens the tab. We only clean up
+    // our subscriptions here; the cache is purged by `runningChanged`
+    // once the session itself goes away.
+    this._untrackWidget(widget as TerminalWidget);
+    this.stateChanged.emit();
+  }
+
+  private _terminals: Terminal.IManager;
+  private _tracker: ITerminalTracker;
+  private _labels = new Map<string, string>();
+  private _ranks = new Map<string, number>();
+  private _live = new Set<string>();
+  private _nextRank = 100;
+}
+
+/**
+ * One status bar item per live terminal session. Renders a terminal
+ * icon plus the session's label, with an inline shutdown button that
+ * appears on hover/focus. The item delegates click handling to the
+ * plugin so the lifecycle (create/dispose) and the user-facing
+ * behaviour (activate vs. reopen, shutdown) live in one place.
+ */
+export class TerminalSessionItem extends VDomRenderer<SessionRegistry> {
+  constructor(options: TerminalSessionItem.IOptions) {
+    super(options.registry);
+    this._sessionName = options.sessionName;
+    this._trans = options.trans ?? nullTranslator.load('jupyterlab');
+    this._onActivate = options.onActivate;
+    this._onShutdown = options.onShutdown;
+    this.addClass('jp-mod-highlighted');
+    this.addClass('jp-xtralab-StatusBar-Terminal');
+  }
+
+  render(): React.ReactElement | null {
+    if (!this.model || !this.model.has(this._sessionName)) {
+      return null;
+    }
+    const trans = this._trans;
+    const label = this.model.labelFor(this._sessionName);
+    const hasWidget = this.model.widgetFor(this._sessionName) !== null;
+    const tooltip = hasWidget
+      ? trans.__('Activate %1', label)
+      : trans.__('Reopen %1', label);
+    this.node.title = tooltip;
+
+    return (
+      <div className="jp-xtralab-StatusBar-Terminal-Container">
+        <button
+          type="button"
+          className="jp-xtralab-StatusBar-Terminal-Activate"
+          onClick={() => this._onActivate(this._sessionName)}
+          aria-label={tooltip}
+        >
+          <terminalIcon.react
+            tag="span"
+            verticalAlign="middle"
+            stylesheet="statusBar"
+          />
+          <span className="jp-xtralab-StatusBar-Terminal-Label">{label}</span>
+        </button>
+        <button
+          type="button"
+          className="jp-xtralab-StatusBar-Terminal-Close"
+          onClick={event => {
+            event.stopPropagation();
+            this._onShutdown(this._sessionName);
+          }}
+          title={trans.__('Shut down %1', label)}
+          aria-label={trans.__('Shut down %1', label)}
+        >
+          <closeIcon.react
+            tag="span"
+            verticalAlign="middle"
+            stylesheet="statusBar"
+          />
+        </button>
+      </div>
+    );
+  }
+
+  private _sessionName: string;
+  private _trans: TranslationBundle;
+  private _onActivate: (sessionName: string) => void;
+  private _onShutdown: (sessionName: string) => void;
+}
+
+export namespace TerminalSessionItem {
+  export interface IOptions {
+    registry: SessionRegistry;
+    sessionName: string;
+    trans?: TranslationBundle;
+    onActivate: (sessionName: string) => void;
+    onShutdown: (sessionName: string) => void;
+  }
+}

package/style/git.css

@@ -39,14 +39,6 @@
   min-width: 0;
 }
 
-.jp-xtralab-GitPanel-title {
-  font-weight: 600;
-  text-transform: uppercase;
-  font-size: var(--jp-ui-font-size0);
-  letter-spacing: 0.04em;
-  color: var(--jp-ui-font-color2);
-}
-
 .jp-xtralab-GitPanel-repo {
   font-weight: 600;
   white-space: nowrap;
@@ -290,6 +282,10 @@
   color: var(--jp-ui-font-color1);
 }
 
+.lm-TabBar-tab.jp-mod-preview .lm-TabBar-tabLabel {
+  font-style: italic;
+}
+
 /*
  * Flex-column container: an optional toolbar at the top (notebook view
  * mode toggle) plus a body that hosts the scrollable diff and the

package/style/index.css

@@ -1,2 +1,4 @@
 @import url('base.css');
 @import url('git.css');
+@import url('launcher.css');
+@import url('statusBar.css');

package/style/index.js

@@ -1,2 +1,4 @@
 import './base.css';
 import './git.css';
+import './launcher.css';
+import './statusBar.css';