xtralab 0.15.0 → 0.15.1

package/src/searchReplace/index.ts

@@ -11,34 +11,16 @@ const PLUGIN_ID = 'xtralab:search-replace';
 const COMMAND_ID = 'xtralab:activate-search-replace';
 
 /**
- * Widget id of the panel contributed by `jupyterlab-search-replace`. The
- * extension adds it to the left sidebar but registers no command of its own,
- * so there is nothing to bind a shortcut to out of the box — this plugin adds
- * the missing command.
+ * Widget id of the `jupyterlab-search-replace` left-sidebar panel; the
+ * extension registers no command of its own to bind a shortcut to.
  */
 const SEARCH_REPLACE_WIDGET_ID = 'jp-search-replace';
 
 /**
- * Bind Accel+Shift+F (Cmd+Shift+F on macOS, Ctrl+Shift+F elsewhere) to the
- * project-wide Search and Replace panel, matching the equivalent shortcut in
- * editors like VS Code.
- *
- * Two pieces are needed because that chord is already taken: JupyterLab core
- * binds Accel+Shift+F to `filebrowser:toggle-main`.
- *
- * 1. The chord is freed declaratively. `SettingRegistry.reconcileShortcuts`
- *    keys collisions and disables on (keys, selector) — not on command — so the
- *    `@jupyterlab/shortcuts-extension:shortcuts` override in
- *    `default_setting_overrides.d/00-xtralab.json` disables the file-browser
- *    binding. The file browser stays reachable from its sidebar tab and the
- *    View menu; only the keyboard shortcut moves.
- *
- * 2. The new binding is added imperatively below rather than as another shipped
- *    default. A `disabled` default and a re-binding default land on the same
- *    (keys, selector) slot, and the disable suppresses every default on that
- *    slot — including the re-binding. `commands.addKeyBinding` runs outside the
- *    reconcile pass, so it is unaffected and wins cleanly once the file-browser
- *    binding is gone.
+ * Bind Accel+Shift+F to the Search and Replace panel (VS Code parity). Core
+ * binds the chord to `filebrowser:toggle-main`; a `default_setting_overrides.d`
+ * override disables it. The re-binding is imperative: `reconcileShortcuts` keys
+ * on (keys, selector), so the disable would suppress a shipped default too.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -60,9 +42,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
       label: trans.__('Search and Replace'),
       caption: trans.__('Show the Search and Replace panel'),
       execute: () => {
-        // `activateById` expands the left sidebar when collapsed, selects the
-        // tab, and the widget focuses its search input from `onAfterShow`, so
-        // the user can start typing a query immediately. It no-ops if
+        // The widget focuses its search input from `onAfterShow`; no-ops if
         // `jupyterlab-search-replace` is unavailable.
         labShell.activateById(SEARCH_REPLACE_WIDGET_ID);
       }

package/src/showOutput/index.ts

@@ -12,24 +12,12 @@ import { coerceData } from '../mimeData';
 
 const PLUGIN_ID = 'xtralab:show-output';
 
-/**
- * Render arbitrary rich content into a panel, with no notebook and no kernel.
- */
 const SHOW_COMMAND = 'xtralab:show';
 
 /**
- * Contribute `xtralab:show`: render a single MIME bundle into a main-area
- * panel using the application's render-mime registry.
- *
- * This is the kernel-free counterpart to running a notebook. A coding agent
- * generates the content itself (a Vega-Lite spec, a Markdown explainer, an
- * HTML fragment, an SVG, a base64 image) and hands it to this command, which
- * renders it with the same renderers JupyterLab uses for cell output and docks
- * the result beside the code. Nothing is written to disk and no kernel is
- * required, so it works even where the kernel has no plotting libraries.
- *
- * Repeated calls with the same `id` reuse one panel, so a walkthrough can
- * refresh the view in place instead of piling up tabs.
+ * Contributes `xtralab:show`: render a single MIME bundle into a panel with
+ * the same renderers JupyterLab uses for cell output — no kernel, no file on
+ * disk. Repeated calls with the same `id` reuse one panel.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -48,7 +36,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
     const { commands } = app;
     const trans = (translator ?? nullTranslator).load('jupyterlab');
 
-    // One reusable panel per `id`, so repeated shows refresh in place.
     const panels = new Map<string, Panel>();
 
     commands.addCommand(SHOW_COMMAND, {
@@ -120,9 +107,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
 
         const model = rendermime.createModel({ data: bundle, trusted: true });
         const renderer = rendermime.createRenderer(chosen);
-        // A scrollable Panel, not a MainAreaWidget: MainAreaWidget does not lay
-        // out its content in the side area, and the panel needs to scroll when
-        // the content is taller than it (style/showOutput.css).
+        // Not a MainAreaWidget: it does not lay out its content in the side
+        // area; the panel scrolls via style/showOutput.css.
         const widget = new Panel();
         widget.addClass('jp-xtralab-ShowPanel');
         widget.id = `xtralab-show-${id}`;
@@ -130,7 +116,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
         widget.title.closable = true;
         widget.addWidget(renderer);
 
-        // Replace any existing panel with this id so shows refresh in place.
         const existing = panels.get(id);
         if (existing && !existing.isDisposed) {
           existing.dispose();
@@ -143,8 +128,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
         });
 
         // Attach before rendering so renderers that need layout (Vega) size
-        // correctly. Default to the side area so the editor keeps full width;
-        // only split the document area when `area` is "main".
+        // correctly.
         if (area === 'main') {
           labShell.add(widget, 'main', {
             mode,

package/src/sidebar/index.ts

@@ -15,8 +15,17 @@ const PLUGIN_ID = 'xtralab:sidebar';
  * per-widget options over the ones passed in.
  */
 interface ITarget {
+  /**
+   * The shell widget id of the sidebar tab.
+   */
   id: string;
+  /**
+   * The sidebar rank used when re-adding the hidden tab.
+   */
   rank: number;
+  /**
+   * The boolean plugin setting controlling the tab's visibility.
+   */
   settingKey:
     | 'showTerminals'
     | 'showFileBrowser'
@@ -24,7 +33,13 @@ interface ITarget {
     | 'showDefaultFileBrowser'
     | 'showRunningSessions'
     | 'showSearchReplace';
+  /**
+   * The id of the toggle command registered for the tab.
+   */
   command: string;
+  /**
+   * The localized label of the toggle command.
+   */
   label: (trans: ReturnType<ITranslator['load']>) => string;
 }
 
@@ -74,13 +89,10 @@ const TARGETS: ITarget[] = [
 ];
 
 /**
- * Toggles individual sidebar tabs from View > Appearance > Sidebars,
- * whichever side a tab currently lives on. Hiding detaches the widget
- * (`widget.parent = null`) while keeping the instance for a later
- * re-add; the preference persists in this plugin's settings. Which side
- * a hidden tab came from is only tracked in-memory, so after a reload a
- * re-shown tab lands on the left. The menu placement is contributed
- * declaratively in `schema/sidebar.json`.
+ * Toggles individual sidebar tabs from View > Appearance > Sidebars. Hiding
+ * detaches the widget while keeping the instance for a later re-add; which
+ * side it came from is only tracked in-memory, so after a reload a re-shown
+ * tab lands on the left. Menu placement is declared in schema/sidebar.json.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -102,8 +114,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
     // instances here so hidden tabs can be re-added.
     const widgetCache = new Map<string, Widget>();
 
-    // Side each hidden widget was removed from, so re-showing restores it
-    // there.
     const hiddenFrom = new Map<string, 'left' | 'right'>();
 
     const findInSidebars = (
@@ -147,7 +157,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
     const apply = (target: ITarget): void => {
       const widget = captureWidget(target.id);
       if (!widget) {
-        // Not seen yet (extension disabled or not added) — nothing to do.
         return;
       }
       const area = locate(target.id);
@@ -202,8 +211,7 @@ const plugin: JupyterFrontEndPlugin<void> = {
               );
             }
           }
-          // No settings registry (or the write failed): apply in-memory
-          // for the current session only.
+          // No settings (or the write failed): apply in-memory for this session.
           apply(target);
           commands.notifyCommandChanged(target.command);
         }

package/src/terminalNotifications/index.ts

@@ -22,16 +22,28 @@ const OSC_RXVT_NOTIFY = 777;
 
 const MAX_TEXT_LENGTH = 256;
 
-// The bits of an xterm.js `Terminal` we reach into. JupyterLab's terminal
-// widget keeps its xterm in a private `_term` field and does not expose these
-// hooks, so a structural type uses them without depending on `@xterm/xterm`. If
-// the field is ever renamed, `_term` is `undefined` and notifications stop, with
-// a console warning per terminal.
+// JupyterLab's terminal keeps its xterm in a private `_term` field; structural
+// types use its hooks without `@xterm/xterm`, going inert (warning) if renamed.
+/**
+ * A handle returned by an xterm listener registration.
+ */
 interface IXtermDisposable {
+  /**
+   * Unregister the listener.
+   */
   dispose(): void;
 }
+/**
+ * The subset of the xterm.js API used to observe bells and OSC sequences.
+ */
 interface IXtermTerminal {
+  /**
+   * Register a handler invoked when the terminal bell rings.
+   */
   onBell(handler: () => void): IXtermDisposable;
+  /**
+   * The escape-sequence parser used to register OSC handlers.
+   */
   parser: {
     registerOscHandler(
       ident: number,
@@ -39,8 +51,17 @@ interface IXtermTerminal {
     ): IXtermDisposable;
   };
 }
+/**
+ * A JupyterLab terminal widget content with its private xterm exposed.
+ */
 interface ITerminalContentInternals extends ITerminal.ITerminal {
+  /**
+   * A promise resolving once the underlying xterm exists.
+   */
   ready: Promise<void>;
+  /**
+   * The private xterm instance; `undefined` if upstream renames the field.
+   */
   _term?: IXtermTerminal;
 }
 
@@ -48,26 +69,30 @@ type TerminalWidget = MainAreaWidget<ITerminal.ITerminal>;
 
 // The renderer→main bridge the desktop shell injects on the lab window. Absent
 // for pip-install users in a browser, who fall back to web Notifications.
+/**
+ * The desktop notification API exposed on `window.xtralab`.
+ */
 interface IDesktopBridge {
+  /**
+   * Show a native notification, tagged with the emitting terminal session.
+   */
   notify?: (
     title: string,
     body: string,
     session?: string
   ) => Promise<void> | void;
+  /**
+   * Register a callback invoked with the tagged terminal session name when
+   * the user clicks a notification.
+   */
   onFocusTerminal?: (callback: (session: string) => void) => void;
 }
 
 /**
- * Turns the notifications coding agents already emit (OSC 9, OSC 777, the bell)
- * into desktop notifications. JupyterLab's xterm renders these sequences but
- * never forwards them to the OS, so this plugin hooks each terminal and bridges
- * them through `window.xtralab.notify` (desktop) or the web Notifications API.
- *
- * A notification is suppressed while its terminal is the focused, active tab,
- * and throttled per terminal. The desktop shell advertises
- * `TERM_PROGRAM=iTerm.app` so agents emit OSC 9 in the first place, and the
- * session name is forwarded so clicking a notification focuses the terminal
- * that fired it.
+ * Turns the OSC 9 / OSC 777 / bell sequences agents emit into desktop
+ * notifications via `window.xtralab.notify` (desktop) or the web Notifications
+ * API — JupyterLab's xterm renders them but never forwards them to the OS.
+ * The desktop shell advertises `TERM_PROGRAM=iTerm.app` so agents emit OSC 9.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -87,13 +112,9 @@ const plugin: JupyterFrontEndPlugin<void> = {
     let enabled = true;
     let notifyOnBell = true;
 
-    // Per-widget throttle timestamps and xterm hooks. WeakMaps let disposed
-    // widgets be collected; hooks are torn down when a tab closes.
     const lastNotified = new WeakMap<TerminalWidget, number>();
     const hooks = new WeakMap<TerminalWidget, IXtermDisposable[]>();
 
-    // True when the user is already looking at this terminal, so a banner would
-    // just be noise.
     const isActivelyViewing = (widget: TerminalWidget): boolean =>
       document.hasFocus() && app.shell.currentWidget === widget;
 
@@ -107,7 +128,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
         );
         return;
       }
-      // Plain-browser fallback (pip install): the Web Notifications API.
       if (typeof Notification === 'undefined') {
         return;
       }
@@ -146,9 +166,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
       widget.title.label || trans.__('Terminal');
 
     const onOsc9 = (widget: TerminalWidget, data: string): boolean => {
-      // OSC 9 is overloaded: ConEmu/Windows Terminal use `9 ; <n> ; …`
-      // subcommands (e.g. `9 ; 4` progress), so skip a numeric-subcommand
-      // payload and leave it unconsumed rather than treat it as a notification.
+      // OSC 9 is overloaded: ConEmu/Windows Terminal use numeric subcommands
+      // (e.g. `9 ; 4` progress); leave those unconsumed.
       if (/^\d+(;|$)/.test(data)) {
         return false;
       }
@@ -197,8 +216,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
             );
             return;
           }
-          // Handlers are wrapped so a parse slip cannot break xterm's parser; an
-          // OSC handler returns whether it consumed the sequence.
           const disposables: IXtermDisposable[] = [
             term.onBell(() => guard(() => onBell(widget))),
             term.parser.registerOscHandler(OSC_ITERM2_GROWL, data =>

package/src/terminals/agentTerminals.ts

@@ -8,35 +8,23 @@ import type { SessionRegistry, TerminalWidget } from './model';
 import type { IAgentTerminalSession, IAgentTerminals } from './tokens';
 
 /**
- * Pause between pasting the prompt and pressing Enter, so the two reach the
- * agent as separate PTY reads — the same shape as a human pasting and then
- * submitting. Sent back to back, the server can coalesce both websocket
- * messages into one read and the TUI would have to split the paste from the
- * trailing Enter inside a single chunk.
+ * Pause between pasting the prompt and pressing Enter so the server cannot
+ * coalesce both websocket messages into one PTY read.
  */
 const PASTE_SUBMIT_DELAY_MS = 150;
 
 /**
- * Bracketed-paste markers (`CSI 200~` / `CSI 201~`). The prompt is wrapped
- * in these so the agent's TUI treats it as one pasted block — newlines
- * insert into its input box instead of submitting the message at each line
- * break. Every send target is a terminal where detection just confirmed a
- * running coding agent, and the agent TUIs keep bracketed-paste mode on.
+ * Bracketed-paste markers (`CSI 200~` / `CSI 201~`): a wrapped prompt arrives
+ * as one pasted block, so newlines insert instead of submitting at each break.
  */
 const PASTE_OPEN = '\x1b[200~';
 const PASTE_CLOSE = '\x1b[201~';
 
-/**
- * How long to wait for the session's websocket to reach `connected` before
- * failing the send, so a server hiccup surfaces as an error notification
- * rather than a silent hang.
- */
 const CONNECT_TIMEOUT_MS = 10_000;
 
 /**
  * Resolve once `session` reports `connected`; reject with `timeoutMessage`
- * after {@link CONNECT_TIMEOUT_MS}. Matches how the launcher waits before
- * typing into a fresh terminal — writes sent while the websocket is still
+ * after {@link CONNECT_TIMEOUT_MS} — writes sent while the websocket is still
  * connecting disappear silently.
  */
 function waitUntilConnected(
@@ -67,11 +55,8 @@ function waitUntilConnected(
 
 /**
  * The {@link IAgentTerminals} implementation: a read-only view over the
- * terminals panel's {@link SessionRegistry} narrowed to sessions with a
- * detection-confirmed coding agent, plus the "send a prompt into one"
- * action. Lives in the `xtralab:terminals` plugin so the ask-agent popup
- * (and any future caller) can target running agents without duplicating the
- * detection plumbing.
+ * panel's {@link SessionRegistry} narrowed to sessions with a
+ * detection-confirmed coding agent, plus the "send a prompt into one" action.
  */
 export class AgentTerminals implements IAgentTerminals {
   constructor(options: AgentTerminals.IOptions) {
@@ -84,6 +69,9 @@ export class AgentTerminals implements IAgentTerminals {
     this._registry.stateChanged.connect(this._onRegistryStateChanged, this);
   }
 
+  /**
+   * Snapshot of the sessions with a detection-confirmed running agent.
+   */
   sessions(): IAgentTerminalSession[] {
     const result: IAgentTerminalSession[] = [];
     for (const name of this._registry.sessionNames()) {
@@ -101,15 +89,20 @@ export class AgentTerminals implements IAgentTerminals {
     return result;
   }
 
+  /**
+   * A signal emitted whenever the {@link sessions} snapshot may have changed.
+   */
   get changed(): ISignal<IAgentTerminals, void> {
     return this._changed;
   }
 
+  /**
+   * Paste the prompt into the named session and press Enter, re-validating
+   * with the server first that an agent still runs there.
+   */
   async sendPrompt(name: string, prompt: string): Promise<void> {
-    // Re-validate against the server rather than trusting the caller's
-    // (possibly seconds-old) snapshot: the prompt is prose, and prose pasted
-    // into the shell prompt left behind by an exited agent would be
-    // *executed* on the Enter below.
+    // Re-validate against the server: prose pasted into the shell prompt an
+    // exited agent left behind would be *executed* on the Enter below.
     await this._terminals.refreshRunning();
     const alive = Array.from(this._terminals.running()).some(
       model => model.name === name
@@ -119,9 +112,8 @@ export class AgentTerminals implements IAgentTerminals {
     }
     const detected = await fetchRunningAgents(this._detectCommands());
     if (detected === null) {
-      // Detection being unavailable (older server, transient failure) is
-      // not proof the agent is gone; refuse the write with a message that
-      // invites the retry that would succeed.
+      // Detection unavailable (older server, transient failure) is not proof
+      // the agent is gone; refuse the write and invite a retry.
       throw new Error(
         this._trans.__('Could not verify the terminal — try sending again.')
       );
@@ -133,11 +125,6 @@ export class AgentTerminals implements IAgentTerminals {
       );
     }
 
-    // Deliver in the background: write straight to the session over its
-    // websocket instead of revealing its tab, so focus stays wherever the
-    // user is asking from. An open tab's live connection is reused; a
-    // closed tab gets a short-lived client connection to the running server
-    // session, without creating any widget.
     const widget = this._findWidget(name);
     const session =
       widget !== null
@@ -148,12 +135,8 @@ export class AgentTerminals implements IAgentTerminals {
         session,
         this._trans.__('Timed out connecting to the terminal.')
       );
-      // Wrapped and newline-normalised exactly like xterm's own paste
-      // handling. Writing the markers directly (rather than through an open
-      // tab's `Terminal.paste`) also sidesteps the one case paste() gets
-      // wrong: a freshly reconnected xterm whose replayed scrollback no
-      // longer holds the agent's original mode-setting escape, which makes
-      // paste() skip the wrapping the application still expects.
+      // Writing the markers directly (not `Terminal.paste`) sidesteps paste()
+      // skipping them on a reconnected xterm that lost the mode-setting escape.
       session.send({
         type: 'stdin',
         content: [PASTE_OPEN + prompt.replace(/\r?\n/g, '\r') + PASTE_CLOSE]
@@ -162,16 +145,14 @@ export class AgentTerminals implements IAgentTerminals {
         window.setTimeout(resolve, PASTE_SUBMIT_DELAY_MS)
       );
       if (session.isDisposed) {
-        // The tab closed during the pause; the pasted text already reached
-        // the agent's input box but Enter can no longer be delivered here.
         throw new Error(
           this._trans.__('The terminal closed before the prompt was submitted.')
         );
       }
       session.send({ type: 'stdin', content: ['\r'] });
     } finally {
-      // Close a connection we opened just for this send. Disposing the
-      // client connection leaves the server session (and its agent) running.
+      // Disposing an ad-hoc client connection leaves the server session
+      // (and its agent) running.
       if (widget === null && !session.isDisposed) {
         session.dispose();
       }
@@ -209,27 +190,22 @@ export namespace AgentTerminals {
      * The panel's session registry — the source of the session snapshot.
      */
     registry: SessionRegistry;
-
     /**
      * Tracker of open terminal widgets, to reuse an open tab's connection.
      */
     tracker: ITerminalTracker;
-
     /**
      * The terminal session manager, for validation and ad-hoc connections.
      */
     terminals: Terminal.IManager;
-
     /**
      * Names to detect — same list the registry polls with.
      */
     detectCommands: () => string[];
-
     /**
      * Whether a detected command belongs to a coding agent (not an editor).
      */
     isAgentCommand: (command: string) => boolean;
-
     /**
      * Translation bundle for the error messages thrown to callers.
      */

package/src/terminals/detection.ts

@@ -2,14 +2,10 @@ import { URLExt } from '@jupyterlab/coreutils';
 import { ServerConnection } from '@jupyterlab/services';
 
 /**
- * Ask the xtralab server which of `commands` is currently running inside each
- * open terminal session. Resolves to a map from session name to the matched
- * agent command, or `null` for a session sitting at its prompt.
- *
- * On any failure (endpoint missing on an older server, network error,
- * malformed response) the whole result is `null` — callers should treat that
- * as "detection unavailable" and fall back to the optimistic launch tags
- * rather than clearing any badges.
+ * Ask the xtralab server which of `commands` runs in each open terminal
+ * session: a map from session name to matched command (`null` = idle). Any
+ * failure resolves the whole result to `null` — "detection unavailable",
+ * not "no agents"; callers must not clear badges on it.
  */
 export async function fetchRunningAgents(
   commands: string[]