xtralab 0.15.0 → 0.15.2

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

@@ -25,15 +25,10 @@ import * as React from 'react';
 
 import { SessionRegistry } from './model';
 
-/**
- * Id of the panel widget. Used for layout restoration and as the handle
- * the sidebar visibility toggle would target.
- */
 const RUNNING_TERMINALS_ID = 'xtralab-running-terminals';
 
 /**
- * Id of the accordion section holding the terminals list. Persisted by the
- * movable-sections plugin, so it must stay stable across releases.
+ * Persisted by the movable-sections plugin — must stay stable across releases.
  */
 const TERMINALS_SECTION_ID = 'xtralab-terminals-section';
 
@@ -75,8 +70,6 @@ export class RunningTerminals
     const newTerminal = new ToolbarButton({
       icon: addIcon,
       onClick: () => {
-        // Anchor whatever the plugin shows (usually an agent menu) to the
-        // button's bottom-left, in the viewport coordinates `Menu.open` wants.
         const rect = newTerminal.node.getBoundingClientRect();
         options.onCreate({ x: rect.left, y: rect.bottom });
       },
@@ -97,23 +90,39 @@ export class RunningTerminals
     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 ||
@@ -125,14 +134,23 @@ export class RunningTerminals
     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;
@@ -162,12 +180,14 @@ export class RunningTerminals
     }
   }
 
+  /**
+   * 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();
   }
@@ -192,19 +212,25 @@ export class RunningTerminals
 }
 
 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;
     /**
@@ -212,16 +238,12 @@ 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;
   }
@@ -243,6 +265,9 @@ class TerminalsListing extends ReactWidget {
     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}>
@@ -277,9 +302,6 @@ function RunningTerminalsComponent(props: {
 }): React.ReactElement {
   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 (
@@ -296,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;

package/src/walkthrough/index.ts

@@ -14,18 +14,12 @@ import { IWalkthroughMedia, IWalkthroughStep, 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: unknown): IWalkthroughMedia | undefined {
   if (
     value &&
@@ -54,15 +48,10 @@ function toLine(value: unknown): number | 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: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -89,9 +78,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
         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;
@@ -188,11 +176,9 @@ const plugin: JupyterFrontEndPlugin<void> = {
           );
         }
 
-        // 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,

package/src/walkthrough/panel.ts

@@ -15,7 +15,13 @@ const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
  * A rich visual embedded in a step (rendered through the rendermime registry).
  */
 export interface IWalkthroughMedia {
+  /**
+   * The MIME type of the media payload.
+   */
   mimeType: string;
+  /**
+   * The payload handed to the renderer for the MIME type.
+   */
   data: ReadonlyPartialJSONValue;
 }
 
@@ -23,30 +29,56 @@ export interface IWalkthroughMedia {
  * One step of a walkthrough. Every field is optional, but a step needs at least one.
  */
 export interface IWalkthroughStep {
+  /**
+   * A heading rendered above the step content.
+   */
   title?: string;
+  /**
+   * The body of the step, rendered as Markdown.
+   */
   body?: string;
+  /**
+   * A rich visual rendered after the body.
+   */
   media?: IWalkthroughMedia;
+  /**
+   * The file the step points at; when set, the step renders a jump link.
+   */
   path?: string;
+  /**
+   * The first line to highlight when the jump link is followed.
+   */
   line?: number;
+  /**
+   * The last line of the highlighted range.
+   */
   endLine?: number;
 }
 
 export namespace WalkthroughPanel {
+  /**
+   * The instantiation options for a walkthrough panel.
+   */
   export interface IOptions {
+    /**
+     * The rendermime registry used to render step bodies and media.
+     */
     rendermime: IRenderMimeRegistry;
+    /**
+     * The command registry used to execute the jump-to-line command.
+     */
     commands: CommandRegistry;
+    /**
+     * The translation bundle for UI strings.
+     */
     trans: TranslationBundle;
   }
 }
 
 /**
  * A read-only, scrollable column of walkthrough steps for the side area.
- *
- * The agent appends steps as it narrates, so the explanation lives beside the
- * code the user is looking at and persists for them to read at their own pace,
- * rather than scrolling away in the chat. Each step renders Markdown (with code
- * snippets, Mermaid, math), can embed a rich visual, and can offer a button
- * that opens the referenced file and highlights its lines.
+ * The agent appends steps as it narrates, so the explanation persists beside
+ * the code instead of scrolling away in the chat.
  */
 export class WalkthroughPanel extends Panel {
   constructor(options: WalkthroughPanel.IOptions) {
@@ -67,9 +99,8 @@ export class WalkthroughPanel extends Panel {
   }
 
   /**
-   * Dispose on close (e.g. the close button when the panel has been dragged to
-   * the main area) rather than leaving a detached, reusable widget behind. The
-   * next `xtralab:walkthrough` call recreates the panel in the side area.
+   * Dispose on close (e.g. after a drag to the main area) instead of leaving a
+   * detached widget; the next `xtralab:walkthrough` call recreates the panel.
    */
   protected onCloseRequest(msg: Message): void {
     super.onCloseRequest(msg);
@@ -103,7 +134,6 @@ export class WalkthroughPanel extends Panel {
       card.addWidget(this._jumpButton(step.path, step.line, step.endLine));
     }
 
-    // Bring the newest step into view.
     this.node.scrollTop = this.node.scrollHeight;
   }
 

package/style/about.css

@@ -1,10 +1,5 @@
-/*
- * About dialog (xtralab:about). The header block is the dialog title, so it
- * inherits the jp-Dialog-header type (size2/600 under chrome.css) — the
- * wordmark scales up from there and the version line drops back to body
- * size, weight and a muted color.
- */
-
+/* The header block is the dialog title, so it inherits the jp-Dialog-header
+ * type (size2/600 under chrome.css). */
 .jp-xtralab-About-header {
   display: flex;
   align-items: center;