xtralab 0.14.1 → 0.15.1

package/lib/walkthrough/panel.d.ts

@@ -8,35 +8,67 @@ import { Panel } from '@lumino/widgets';
  * 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;
 }
 /**
  * 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 declare namespace WalkthroughPanel {
+    /**
+     * The instantiation options for a walkthrough panel.
+     */
     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 declare class WalkthroughPanel extends Panel {
     constructor(options: WalkthroughPanel.IOptions);
@@ -45,9 +77,8 @@ export declare class WalkthroughPanel extends Panel {
      */
     clear(): void;
     /**
-     * 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;
     /**

package/lib/walkthrough/panel.js

@@ -6,12 +6,8 @@ import { Panel, Widget } from '@lumino/widgets';
 const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
 /**
  * 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) {
@@ -30,9 +26,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.
      */
     onCloseRequest(msg) {
         super.onCloseRequest(msg);
@@ -60,7 +55,6 @@ export class WalkthroughPanel extends Panel {
         if (step.path) {
             card.addWidget(this._jumpButton(step.path, step.line, step.endLine));
         }
-        // Bring the newest step into view.
         this.node.scrollTop = this.node.scrollHeight;
     }
     async _render(parent, mimeType, data) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xtralab",
-    "version": "0.14.1",
+    "version": "0.15.1",
     "description": "An opinionated JupyterLab meta-package that bundles a curated set of extensions, ships a path-first file browser, renders jupyterlab-git's text, notebook and image diffs with its own viewers, and applies a quieter default workspace configuration.",
     "keywords": [
         "jupyter",
@@ -90,7 +90,7 @@
         "@lumino/polling": "^2.1.5",
         "@lumino/signaling": "^2.1.5",
         "@lumino/widgets": "^2.8.0",
-        "@pierre/diffs": "^1.2.11",
+        "@pierre/diffs": "^1.4.1",
         "@pierre/trees": "1.0.0-beta.4",
         "detect-indent": "^7.0.2",
         "ignore": "^5.3.2",

package/schema/launcher.json

@@ -8,7 +8,7 @@
   "properties": {
     "agents": {
       "title": "Agents",
-      "description": "Override or extend the built-in list of agents shown on the launcher. Each entry must include an `id`. When the id matches a built-in (claude, codex, antigravity, copilot, goose, opencode, kiro, mistral-vibe), the fields you set override the corresponding defaults; leave a field out to keep the default. New ids define brand-new cards. Set `enabled: false` to hide a default. Changing a built-in's `command` (for example to a shell alias like `ccm`) keeps the card visible even though the alias isn't on PATH; use `requireAvailable: false` only when you want to skip the check without changing the command. The full built-in list is shown as the default below, so you can copy an entry and tweak it in place.",
+      "description": "Override or extend the built-in list of agents shown on the launcher. Each entry must include an `id`. When the id matches a built-in (claude, codex, antigravity, copilot, goose, opencode, kiro, mistral-vibe, pi), the fields you set override the corresponding defaults; leave a field out to keep the default. New ids define brand-new cards. Set `enabled: false` to hide a default. Changing a built-in's `command` (for example to a shell alias like `ccm`) keeps the card visible even though the alias isn't on PATH; use `requireAvailable: false` only when you want to skip the check without changing the command. The full built-in list is shown as the default below, so you can copy an entry and tweak it in place. Saved entries are merged into the built-in list by id, so this settings view always shows every built-in agent alongside your overrides.",
       "type": "array",
       "default": [],
       "items": {
@@ -69,7 +69,7 @@
     },
     "editors": {
       "title": "Editors",
-      "description": "Override or extend the terminal editors offered in the launcher's Open section (and recognized in the Terminals panel). Each entry must include an `id`. When the id matches a built-in (nvim, vim), the fields you set override the corresponding defaults; leave a field out to keep the default. New ids define additional editors. The launcher shows a single tile — the first editor, by `rank`, whose `command` is on PATH (Neovim before Vim by default). Set `enabled: false` to hide a built-in; disable both to remove the tile entirely. Changing a built-in's `command` (for example to a shell alias) keeps the tile visible even though the alias isn't on PATH; use `requireAvailable: false` only when you want to skip the check without changing the command. The full built-in list is shown as the default below, so you can copy an entry and tweak it in place.",
+      "description": "Override or extend the terminal editors offered in the launcher's Open section (and recognized in the Terminals panel). Each entry must include an `id`. When the id matches a built-in (nvim, vim), the fields you set override the corresponding defaults; leave a field out to keep the default. New ids define additional editors. The launcher shows a single tile — the first editor, by `rank`, whose `command` is on PATH (Neovim before Vim by default). Set `enabled: false` to hide a built-in; disable both to remove the tile entirely. Changing a built-in's `command` (for example to a shell alias) keeps the tile visible even though the alias isn't on PATH; use `requireAvailable: false` only when you want to skip the check without changing the command. The full built-in list is shown as the default below, so you can copy an entry and tweak it in place. Saved entries are merged into the built-in list by id, so this settings view always shows every built-in editor alongside your overrides.",
       "type": "array",
       "default": [],
       "items": {

package/schema/sidebar.json

@@ -1,6 +1,6 @@
 {
   "title": "xtralab sidebar",
-  "description": "Visibility of selected JupyterLab sidebar tabs.",
+  "description": "Visibility of individual sidebar tabs.",
   "jupyter.lab.shortcuts": [],
   "jupyter.lab.menus": {
     "main": [
@@ -17,16 +17,32 @@
                   "type": "submenu",
                   "rank": 12.5,
                   "submenu": {
-                    "id": "jp-mainmenu-view-appearance-left-sidebar",
-                    "label": "Left Sidebar",
+                    "id": "jp-mainmenu-view-appearance-sidebars",
+                    "label": "Sidebars",
                     "items": [
                       {
-                        "command": "xtralab:toggle-default-filebrowser",
+                        "command": "xtralab:toggle-terminals",
                         "rank": 1
                       },
                       {
-                        "command": "xtralab:toggle-running-sessions",
+                        "command": "xtralab:toggle-file-browser",
                         "rank": 2
+                      },
+                      {
+                        "command": "xtralab:toggle-git-panel",
+                        "rank": 3
+                      },
+                      {
+                        "command": "xtralab:toggle-default-filebrowser",
+                        "rank": 4
+                      },
+                      {
+                        "command": "xtralab:toggle-running-sessions",
+                        "rank": 5
+                      },
+                      {
+                        "command": "xtralab:toggle-search-replace",
+                        "rank": 6
                       }
                     ]
                   }
@@ -40,16 +56,40 @@
   },
   "type": "object",
   "properties": {
+    "showTerminals": {
+      "type": "boolean",
+      "title": "Show the terminals panel",
+      "description": "When false, hides the xtralab Terminals (`xtralab-running-terminals`) tab from the sidebar.",
+      "default": true
+    },
+    "showFileBrowser": {
+      "type": "boolean",
+      "title": "Show the xtralab file browser",
+      "description": "When false, hides the xtralab file browser (`xtralab:file-browser`) tab from the sidebar. The default JupyterLab file browser is unaffected.",
+      "default": true
+    },
+    "showGitPanel": {
+      "type": "boolean",
+      "title": "Show the Git panel",
+      "description": "When false, hides the `jp-git-sessions` (Git) tab from the sidebar.",
+      "default": true
+    },
     "showDefaultFileBrowser": {
       "type": "boolean",
       "title": "Show the default JupyterLab file browser",
-      "description": "When false, hides the default `filebrowser` tab from the left sidebar. The xtralab file browser is unaffected.",
+      "description": "When false, hides the default `filebrowser` tab from the sidebar. The xtralab file browser is unaffected.",
       "default": true
     },
     "showRunningSessions": {
       "type": "boolean",
       "title": "Show running terminals and kernels",
-      "description": "When false, hides the `jp-running-sessions` (Running Terminals and Kernels) tab from the left sidebar.",
+      "description": "When false, hides the `jp-running-sessions` (Running Terminals and Kernels) tab from the sidebar.",
+      "default": true
+    },
+    "showSearchReplace": {
+      "type": "boolean",
+      "title": "Show search and replace",
+      "description": "When false, hides the `jp-search-replace` (Search and Replace) tab from the sidebar.",
       "default": true
     }
   },

package/src/about/icons.ts

@@ -2,11 +2,6 @@ import { LabIcon } from '@jupyterlab/ui-components';
 
 import logoSvgstr from '../../logo.svg';
 
-/**
- * The project logo mark — `logo.svg` at the repository root, the same file
- * the README and the docs site use. The labextension build inlines it as a
- * raw string, so the dialog always shows the current artwork.
- */
 export const aboutLogoIcon = new LabIcon({
   name: 'xtralab:about-logo',
   svgstr: logoSvgstr

package/src/about/index.tsx

@@ -11,11 +11,6 @@ import { aboutLogoIcon } from './icons';
 
 const PLUGIN_ID = 'xtralab:about';
 
-/**
- * Upstream command id. Reusing it keeps the Help menu entry (contributed by
- * `schema/about.json` at the same rank as upstream), the command palette
- * muscle memory, and any external caller of `help:about` working.
- */
 const CommandIDs = {
   about: 'help:about'
 };
@@ -23,14 +18,10 @@ const CommandIDs = {
 const REPO_URL = 'https://github.com/jtpio/xtralab';
 
 /**
- * An "About xtralab" dialog replacing the stock "About JupyterLab" one.
- *
- * The upstream `@jupyterlab/help-extension:about` plugin is disabled via
- * `jupyterlab.disabledExtensions` (package.json), which removes both its
- * `help:about` command and its Help menu contribution; this plugin registers
- * the same command id and restores the menu entry through its own schema.
- * The dialog leads with the xtralab version and keeps the underlying
- * JupyterLab version visible underneath.
+ * An "About xtralab" dialog replacing the stock "About JupyterLab" one. The
+ * upstream plugin is disabled via `jupyterlab.disabledExtensions`, which also
+ * removes its Help menu entry; this plugin re-registers `help:about` and
+ * restores the menu entry through its own schema.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,
@@ -56,10 +47,8 @@ const plugin: JupyterFrontEndPlugin<void> = {
         }
       },
       execute: async () => {
-        // The settings payload carries the version of the installed
-        // labextension (read server-side from its package.json), which is
-        // the release actually running — the page config only knows the
-        // JupyterLab version. 'N/A' is jupyterlab_server's not-found value.
+        // The settings payload carries the installed labextension's version
+        // (page config only knows JupyterLab's); 'N/A' is jupyterlab_server's not-found value.
         const version = await settingRegistry
           .load(PLUGIN_ID)
           .then(settings =>

package/src/agentSessions.ts

@@ -3,28 +3,14 @@ import { Token } from '@lumino/coreutils';
 import { ISignal, Signal } from '@lumino/signaling';
 
 /**
- * A shared map from a terminal session name to the agent command it was
- * *launched* with (e.g. `claude`).
- *
- * This is the optimistic half of the running-agent badge: when the launcher
- * (or the terminals panel's `+` menu) starts an agent via a
- * `xtralab:start-agent:<id>` command, it records the session here so the
- * panel can show the agent's logo immediately, before the server-side
- * process detection has had a chance to confirm it. Server detection is the
- * authoritative source once it reports on a session; this tag only fills the
- * gap right after launch (and serves as a fallback if detection is
- * unavailable).
- *
- * It exists as its own token, provided by a tiny dependency-free plugin,
- * specifically so the launcher (the writer) and the terminals panel (the
- * reader) can share it without depending on each other — a direct
- * launcher↔terminals token pair would form an activation cycle.
+ * Shared map from terminal session name to the agent command it was launched
+ * with — the optimistic half of the running-agent badge, shown until server
+ * detection confirms. Its own token so the launcher (writer) and terminals
+ * panel (reader) can share it without an activation cycle.
  */
 export interface IAgentSessions {
   /**
-   * The agent command a session was launched with, or `null` if we never
-   * launched an agent into it (e.g. a plain terminal, or one started before
-   * this ran).
+   * The agent command a session was launched with, or `null` if unknown.
    */
   get(sessionName: string): string | null;
 
@@ -34,21 +20,16 @@ export interface IAgentSessions {
   set(sessionName: string, command: string): void;
 
   /**
-   * Forget a session — called when it shuts down so the map stays bounded.
+   * Forget a session so the map stays bounded.
    */
   delete(sessionName: string): void;
 
   /**
-   * Emitted with the affected session name whenever a record is added or
-   * removed, so readers can re-render.
+   * Emitted with the session name whenever a record is added or removed.
    */
   readonly changed: ISignal<IAgentSessions, string>;
 }
 
-/**
- * DI token for {@link IAgentSessions}. Provided by `xtralab:agent-sessions`;
- * consumed (optionally) by both `xtralab:launcher` and `xtralab:terminals`.
- */
 export const IAgentSessions = new Token<IAgentSessions>(
   'xtralab:IAgentSessions',
   'A shared map from terminal session name to the agent command it was launched with.'
@@ -82,9 +63,8 @@ class AgentSessions implements IAgentSessions {
 }
 
 /**
- * Provides {@link IAgentSessions}. Deliberately has no dependencies so it can
- * sit underneath both the launcher and the terminals panel without creating
- * a dependency cycle between them.
+ * Provides {@link IAgentSessions}; dependency-free so it can sit underneath
+ * both the launcher and the terminals panel.
  */
 const plugin: JupyterFrontEndPlugin<IAgentSessions> = {
   id: 'xtralab:agent-sessions',

package/src/askAgent/editorSelection.ts

@@ -8,13 +8,21 @@ import type { Widget } from '@lumino/widgets';
 import type { IAskAgentContext, IAskAgentRequest } from './tokens';
 
 /**
- * A CodeMirror view a selection can be asked about, plus the context needed
- * to describe it to an agent: the document path and, for notebooks, which
- * cell the view belongs to.
+ * A CodeMirror view a selection can be asked about, plus the document path
+ * and, for notebooks, the owning cell.
  */
 interface IEditorTarget {
+  /**
+   * The CodeMirror view holding the selection.
+   */
   view: EditorView;
+  /**
+   * The path of the document the view belongs to.
+   */
   path: string;
+  /**
+   * The index and type of the owning notebook cell; absent for file editors.
+   */
   cell?: {
     index: number;
     type: string;
@@ -22,19 +30,10 @@ interface IEditorTarget {
 }
 
 /**
- * Resolve the CodeMirror view a selection in `widget` would live in, or
- * `null` when the widget holds no such editor. Two widget shapes are
- * recognized:
- *
- * - a notebook panel, where the active cell carries the editor and
- *   `activeCellIndex` names its 0-based position in the nbformat `cells`
- *   array. A rendered markdown cell keeps its (hidden) editor, but a
- *   selection in the rendered HTML never passes {@link domSelectionInView},
- *   so no pill appears there; and
- * - a document widget whose content is a `FileEditor`. The wrapper is not
- *   checked with `instanceof DocumentWidget`: `@jupyterlab/docregistry` is
- *   not a core singleton, so another copy of the class could be in play.
- *   `FileEditor` and `NotebookPanel` come from singleton packages.
+ * Resolve the CodeMirror view a selection in `widget` would live in — the
+ * active notebook cell or a `FileEditor` document — or `null`. The wrapper is
+ * duck-typed, not `instanceof DocumentWidget`: `@jupyterlab/docregistry` is
+ * not a core singleton, unlike `FileEditor` and `NotebookPanel`.
  */
 export function resolveEditorTarget(
   widget: Widget | null
@@ -63,10 +62,8 @@ export function resolveEditorTarget(
 }
 
 /**
- * Whether the current DOM selection lives inside `view`. Guards the
- * selection-change listener against selections made elsewhere (a terminal,
- * a sidebar, another notebook cell) while the widget owning `view` happens
- * to be the shell's current widget.
+ * Whether the current DOM selection lives inside `view`; guards against
+ * selections made elsewhere while the owning widget is current.
  */
 export function domSelectionInView(
   view: EditorView,
@@ -80,12 +77,9 @@ export function domSelectionInView(
 
 /**
  * Build an ask-agent request from the current selection in the shell's
- * current widget — a file editor or the active notebook cell — or return
- * `null` when that widget holds no CodeMirror document editor.
- *
- * With `allowEmpty`, a collapsed selection falls back to the cursor's line
- * (used by the command/shortcut path so it works without a mouse
- * selection); otherwise an empty selection yields `null`.
+ * current widget, or `null` when it holds no CodeMirror document editor.
+ * With `allowEmpty`, a collapsed selection falls back to the cursor's line;
+ * otherwise it yields `null`.
  */
 export function editorAskRequest(
   app: JupyterFrontEnd,
@@ -110,15 +104,14 @@ export function editorAskRequest(
     endLine = startLine;
     text = state.doc.lineAt(main.from).text;
   } else {
-    // A selection that ends exactly at the start of a line (the common
-    // "drag over whole lines" gesture) should not count that line.
+    // A selection ending exactly at a line start (the whole-line drag
+    // gesture) should not count that line.
     const endPos =
       main.to === state.doc.lineAt(main.to).from ? main.to - 1 : main.to;
     endLine = state.doc.lineAt(endPos).number;
     text = state.sliceDoc(main.from, main.to);
   }
 
-  // Anchor the popup at the selection head (where the cursor ended up).
   // `coordsAtPos` returns `null` for positions scrolled out of view.
   const coords = view.coordsAtPos(main.head);
   const anchor = coords

package/src/askAgent/icons.ts

@@ -1,9 +1,8 @@
 import { LabIcon } from '@jupyterlab/ui-components';
 
 /**
- * Four-point sparkle used by the ask-agent affordances (selection pill,
- * command palette entry). Drawn in-repo; the `jp-icon3` class lets the
- * active theme recolor the glyph like other JupyterLab UI icons.
+ * Four-point sparkle used by the ask-agent affordances; the `jp-icon3`
+ * class lets the active theme recolor the glyph.
  */
 export const askAgentIcon = new LabIcon({
   name: 'xtralab:ask-agent',