xtralab 0.10.0 → 0.11.1

package/lib/walkthrough/index.js

@@ -0,0 +1,162 @@
+import { ILabShell } from '@jupyterlab/application';
+import { ICommandPalette } from '@jupyterlab/apputils';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { tocIcon } from '@jupyterlab/ui-components';
+import { 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) {
+    if (value &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        typeof value.mimeType === 'string') {
+        const media = value;
+        return { mimeType: media.mimeType, data: media.data };
+    }
+    return undefined;
+}
+function toLine(value) {
+    const n = Math.trunc(Number(value));
+    return Number.isFinite(n) && n >= 1 ? n : 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.
+ */
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Build a read-only guided walkthrough in the side panel.',
+    autoStart: true,
+    requires: [IRenderMimeRegistry, ILabShell],
+    optional: [ICommandPalette, ITranslator],
+    activate: (app, rendermime, labShell, palette, translator) => {
+        const { commands } = app;
+        const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
+        let panel = null;
+        const ensurePanel = () => {
+            if (!panel || panel.isDisposed) {
+                panel = new WalkthroughPanel({ rendermime, commands, trans });
+                panel.id = PANEL_ID;
+                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.
+                panel.title.closable = true;
+                labShell.add(panel, 'right', { rank: 1000, type: 'Walkthrough' });
+                const created = panel;
+                created.disposed.connect(() => {
+                    if (panel === created) {
+                        panel = null;
+                    }
+                });
+            }
+            return panel;
+        };
+        commands.addCommand(WALKTHROUGH_COMMAND, {
+            label: trans.__('Add Walkthrough Step'),
+            caption: trans.__('Append a step to the read-only walkthrough panel'),
+            describedBy: {
+                args: {
+                    type: 'object',
+                    properties: {
+                        title: {
+                            type: 'string',
+                            description: 'Optional heading for the step.'
+                        },
+                        body: {
+                            type: 'string',
+                            description: 'Markdown for the step. Renders code snippets, lists, math, and Mermaid diagrams from a ```mermaid fenced block.'
+                        },
+                        path: {
+                            type: 'string',
+                            description: 'Optional file the step is about, relative to the server root. The editor opens it (full width, no split) and highlights the lines, and the step keeps a button to jump back.'
+                        },
+                        line: {
+                            type: 'number',
+                            description: 'First line to highlight (1-indexed).'
+                        },
+                        endLine: {
+                            type: 'number',
+                            description: 'Last line to highlight (1-indexed, inclusive).'
+                        },
+                        media: {
+                            type: 'object',
+                            description: 'Optional embedded visual, e.g. { "mimeType": "application/vnd.vegalite.v5+json", "data": <spec> }.',
+                            properties: {
+                                mimeType: { type: 'string' },
+                                data: {}
+                            },
+                            required: ['mimeType', 'data']
+                        },
+                        reveal: {
+                            type: 'boolean',
+                            description: 'Whether to navigate and highlight the code as the step is added. Defaults to true.'
+                        },
+                        reset: {
+                            type: 'boolean',
+                            description: 'Clear the existing walkthrough before adding this step (start a new tour).'
+                        }
+                    }
+                }
+            },
+            execute: async (args) => {
+                const current = ensurePanel();
+                if (args['reset'] === true) {
+                    current.clear();
+                }
+                const path = typeof args['path'] === 'string' ? args['path'] : undefined;
+                const line = toLine(args['line']);
+                const endLine = toLine(args['endLine']);
+                const media = readMedia(args['media']);
+                const step = {
+                    title: typeof args['title'] === 'string' ? args['title'] : undefined,
+                    body: typeof args['body'] === 'string' ? args['body'] : undefined,
+                    media,
+                    path,
+                    line,
+                    endLine
+                };
+                if (!step.title &&
+                    !step.body &&
+                    !step.media &&
+                    !step.path &&
+                    args['reset'] !== true) {
+                    throw new Error('xtralab:walkthrough needs at least one of: title, body, media, path');
+                }
+                // 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,
+                        line,
+                        endLine
+                    });
+                }
+                return trans.__('Added walkthrough step');
+            }
+        });
+        if (palette) {
+            palette.addItem({
+                command: WALKTHROUGH_COMMAND,
+                category: trans.__('Other')
+            });
+        }
+    }
+};
+export default plugin;

package/lib/walkthrough/panel.d.ts

@@ -0,0 +1,54 @@
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import type { TranslationBundle } from '@jupyterlab/translation';
+import type { CommandRegistry } from '@lumino/commands';
+import type { ReadonlyPartialJSONValue } from '@lumino/coreutils';
+import type { Message } from '@lumino/messaging';
+import { Panel } from '@lumino/widgets';
+/** A rich visual embedded in a step (rendered through the rendermime registry). */
+export interface IWalkthroughMedia {
+    mimeType: string;
+    data: ReadonlyPartialJSONValue;
+}
+/** One step of a walkthrough. Every field is optional, but a step needs at least one. */
+export interface IWalkthroughStep {
+    title?: string;
+    body?: string;
+    media?: IWalkthroughMedia;
+    path?: string;
+    line?: number;
+    endLine?: number;
+}
+export declare namespace WalkthroughPanel {
+    interface IOptions {
+        rendermime: IRenderMimeRegistry;
+        commands: CommandRegistry;
+        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.
+ */
+export declare class WalkthroughPanel extends Panel {
+    constructor(options: WalkthroughPanel.IOptions);
+    /** Remove every step, leaving an empty 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.
+     */
+    protected onCloseRequest(msg: Message): void;
+    /** Append a step and scroll it into view. */
+    addStep(step: IWalkthroughStep): Promise<void>;
+    private _render;
+    private _jumpButton;
+    private _rendermime;
+    private _commands;
+    private _trans;
+}

package/lib/walkthrough/panel.js

@@ -0,0 +1,98 @@
+import { fileIcon } from '@jupyterlab/ui-components';
+import { Panel, Widget } from '@lumino/widgets';
+/** Command the jump links dispatch; keeps the panel decoupled from the plugin. */
+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.
+ */
+export class WalkthroughPanel extends Panel {
+    constructor(options) {
+        super();
+        this._rendermime = options.rendermime;
+        this._commands = options.commands;
+        this._trans = options.trans;
+        this.addClass('jp-xtralab-Walkthrough');
+    }
+    /** Remove every step, leaving an empty panel. */
+    clear() {
+        while (this.widgets.length > 0) {
+            this.widgets[0].dispose();
+        }
+    }
+    /**
+     * 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.
+     */
+    onCloseRequest(msg) {
+        super.onCloseRequest(msg);
+        this.dispose();
+    }
+    /** Append a step and scroll it into view. */
+    async addStep(step) {
+        const card = new Panel();
+        card.addClass('jp-xtralab-Walkthrough-step');
+        this.addWidget(card);
+        if (step.title) {
+            const heading = new Widget({ node: document.createElement('h3') });
+            heading.addClass('jp-xtralab-Walkthrough-stepTitle');
+            heading.node.textContent = step.title;
+            card.addWidget(heading);
+        }
+        if (step.body) {
+            await this._render(card, 'text/markdown', step.body);
+        }
+        if (step.media && typeof step.media.mimeType === 'string') {
+            await this._render(card, step.media.mimeType, step.media.data);
+        }
+        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) {
+        const bundle = { [mimeType]: data };
+        const chosen = this._rendermime.preferredMimeType(bundle, 'any');
+        if (!chosen) {
+            return;
+        }
+        const renderer = this._rendermime.createRenderer(chosen);
+        renderer.addClass('jp-xtralab-Walkthrough-content');
+        parent.addWidget(renderer);
+        await renderer.renderModel(this._rendermime.createModel({ data: bundle, trusted: true }));
+    }
+    _jumpButton(path, line, endLine) {
+        const node = document.createElement('div');
+        node.className = 'jp-xtralab-Walkthrough-jumpRow';
+        const where = line ? `${path}:${line}` : path;
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'jp-xtralab-Walkthrough-jump';
+        button.title = this._trans.__('Open %1 in the editor', where);
+        const icon = fileIcon.element({
+            tag: 'span',
+            className: 'jp-xtralab-Walkthrough-jumpIcon'
+        });
+        const label = document.createElement('span');
+        label.className = 'jp-xtralab-Walkthrough-jumpLabel';
+        label.textContent = where;
+        button.appendChild(icon);
+        button.appendChild(label);
+        node.appendChild(button);
+        button.addEventListener('click', () => {
+            void this._commands.execute(HIGHLIGHT_LINES_COMMAND, {
+                path,
+                line,
+                endLine
+            });
+        });
+        return new Widget({ node });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xtralab",
-    "version": "0.10.0",
+    "version": "0.11.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",

package/schema/launcher.json

@@ -2,12 +2,13 @@
   "title": "xtralab launcher",
   "description": "Settings for the xtralab agent launcher.",
   "jupyter.lab.shortcuts": [],
+  "jupyter.lab.transform": true,
   "type": "object",
   "additionalProperties": false,
   "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. Set `requireAvailable: false` for shell aliases that should always show even though they aren't on PATH.",
+      "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.",
       "type": "array",
       "default": [],
       "items": {
@@ -53,7 +54,7 @@
           },
           "requireAvailable": {
             "title": "Require available",
-            "description": "When false, the launcher skips the availability check for this entry (useful for shell aliases that aren't on PATH but resolve in an interactive shell).",
+            "description": "When false, the launcher skips the availability check for this entry (useful for shell aliases that aren't on PATH but resolve in an interactive shell). Overriding a built-in agent's command turns this off automatically, so an aliased command still shows; set it explicitly to force the check on or off.",
             "type": "boolean",
             "default": true
           },
@@ -68,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. Set `requireAvailable: false` for a shell alias that should show even though it isn't on PATH.",
+      "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.",
       "type": "array",
       "default": [],
       "items": {
@@ -114,7 +115,7 @@
           },
           "requireAvailable": {
             "title": "Require available",
-            "description": "When false, the launcher skips the availability check for this entry (useful for a shell alias that isn't on PATH but resolves in an interactive shell).",
+            "description": "When false, the launcher skips the availability check for this entry (useful for a shell alias that isn't on PATH but resolves in an interactive shell). Overriding a built-in editor's command turns this off automatically, so an aliased command still shows; set it explicitly to force the check on or off.",
             "type": "boolean",
             "default": true
           }

package/schema/terminals.json

@@ -0,0 +1,15 @@
+{
+  "title": "xtralab Terminals panel",
+  "description": "The left-sidebar panel that lists running terminal sessions.",
+  "jupyter.lab.shortcuts": [],
+  "type": "object",
+  "properties": {
+    "showAgentActivity": {
+      "type": "boolean",
+      "title": "Show agent activity under each terminal",
+      "description": "When true, every terminal running a coding agent shows a smaller line below its title with the agent's latest line of output, so you can see what a backgrounded agent is doing without switching to it. Turn this off to list terminals by title alone.",
+      "default": true
+    }
+  },
+  "additionalProperties": false
+}

package/src/commandBar/index.ts

@@ -0,0 +1,165 @@
+import {
+  ILabShell,
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { searchIcon } from '@jupyterlab/ui-components';
+import { CommandRegistry } from '@lumino/commands';
+import { Widget } from '@lumino/widgets';
+
+import { IOmnibox, OMNIBOX_OPEN_COMMAND } from '../omnibox/tokens';
+
+const PLUGIN_ID = 'xtralab:command-bar';
+
+/**
+ * A search-bar-styled launcher for the `top` area. It holds no text input of
+ * its own: clicking the pill (or pressing Enter/Space while it is focused)
+ * runs `onActivate`, which opens the omnibox.
+ *
+ * The widget's root is a transparent, full-height wrapper centered as an
+ * overlay over the whole top panel (style/commandBar.css). The wrapper
+ * ignores pointer events so only the inner pill is clickable and the empty
+ * strips above and below it let clicks fall through to whatever sits beneath
+ * the overlay, such as the menu bar.
+ */
+class CommandBar extends Widget {
+  constructor(options: CommandBar.IOptions) {
+    super({
+      node: CommandBar.createNode(
+        options.label,
+        options.caption,
+        options.shortcut
+      )
+    });
+    this.addClass('jp-xtralab-CommandBar');
+    this._onActivate = options.onActivate;
+  }
+
+  handleEvent(event: Event): void {
+    if (event.type === 'click') {
+      this._onActivate();
+    }
+  }
+
+  protected onAfterAttach(): void {
+    // The pill restores `pointer-events: auto`, so the click bubbles from it
+    // up to the root node listened on here; keyboard Enter/Space on the
+    // focused button raises the same synthetic click.
+    this.node.addEventListener('click', this);
+  }
+
+  protected onBeforeDetach(): void {
+    this.node.removeEventListener('click', this);
+  }
+
+  private _onActivate: () => void;
+}
+
+namespace CommandBar {
+  export interface IOptions {
+    /** Placeholder-style text shown inside the pill. */
+    label: string;
+    /** Tooltip and accessible name for the button. */
+    caption: string;
+    /** Formatted keyboard shortcut shown as a trailing hint, if any. */
+    shortcut?: string;
+    /** Runs on click or keyboard activation. */
+    onActivate: () => void;
+  }
+
+  export function createNode(
+    label: string,
+    caption: string,
+    shortcut?: string
+  ): HTMLElement {
+    const wrapper = document.createElement('div');
+
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'jp-xtralab-CommandBar-button';
+    button.title = caption;
+    button.setAttribute('aria-label', caption);
+
+    const icon = searchIcon.element({
+      tag: 'span',
+      className: 'jp-xtralab-CommandBar-icon'
+    });
+
+    const text = document.createElement('span');
+    text.className = 'jp-xtralab-CommandBar-label';
+    text.textContent = label;
+
+    button.appendChild(icon);
+    button.appendChild(text);
+
+    if (shortcut) {
+      const hint = document.createElement('span');
+      hint.className = 'jp-xtralab-CommandBar-shortcut';
+      hint.textContent = shortcut;
+      // Decorative: the button's aria-label already names the action.
+      hint.setAttribute('aria-hidden', 'true');
+      button.appendChild(hint);
+    }
+
+    wrapper.appendChild(button);
+    return wrapper;
+  }
+}
+
+/**
+ * Add a centered, search-bar-styled command bar to the top area. Clicking it
+ * opens the omnibox — a launcher overlay that fuzzy-searches files and
+ * commands and routes a typed prompt to an agent (the leading sidebar toggle
+ * and the menu bar sit to its left, the trailing sidebar toggle to its right;
+ * the bar is centered over the whole panel as an overlay, so it stays put
+ * regardless of their widths).
+ *
+ * The bar is only added when the omnibox is available — the `IOmnibox` token
+ * is provided by `xtralab:omnibox` — so it never appears with nothing to open.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'Add a centered command bar to the top area that opens the omnibox.',
+  autoStart: true,
+  requires: [ILabShell],
+  optional: [IOmnibox, ITranslator],
+  activate: (
+    app: JupyterFrontEnd,
+    labShell: ILabShell,
+    omnibox: IOmnibox | null,
+    translator: ITranslator | null
+  ): void => {
+    if (!omnibox) {
+      return;
+    }
+
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+
+    // Show the omnibox's keyboard shortcut as a hint in the pill, derived from
+    // the live binding (registered by xtralab:omnibox, which activates first as
+    // the IOmnibox provider) so it stays correct and uses the platform's
+    // modifier symbols. Empty when no binding is registered.
+    const binding = app.commands.keyBindings.find(
+      keyBinding => keyBinding.command === OMNIBOX_OPEN_COMMAND
+    );
+    const shortcut = binding
+      ? CommandRegistry.formatKeystroke(binding.keys)
+      : '';
+
+    const widget = new CommandBar({
+      label: trans.__('Search…'),
+      caption: trans.__('Search files and commands, or ask an agent'),
+      shortcut,
+      onActivate: () => {
+        omnibox.open();
+      }
+    });
+    widget.id = 'xtralab-command-bar';
+
+    labShell.add(widget, 'top', { rank: 500 });
+  }
+};
+
+export default plugin;

package/src/fileBrowser/fileBrowser.tsx

@@ -93,6 +93,12 @@ const GIT_REPO_PATH = '';
  */
 const FILE_TREE_TAG = 'file-tree-container';
 
+const FILE_TREE_UNSAFE_CSS =
+  '[data-type="item"][data-item-selected="true"] ' +
+  '[data-item-section="spacing-item"] {' +
+  'border-left-color: transparent;' +
+  '}';
+
 export interface IFileBrowserProps {
   contentsManager: Contents.IManager;
   docManager: IDocumentManager;
@@ -123,7 +129,8 @@ export function FileBrowserComponent(
     initialExpansion: 'closed',
     search: true,
     icons: FILE_BROWSER_ICONS,
-    itemHeight: 24
+    itemHeight: 24,
+    unsafeCSS: FILE_TREE_UNSAFE_CSS
   });
 
   React.useEffect(() => {