xtralab 0.10.0 → 0.11.1

package/src/walkthrough/panel.ts

@@ -0,0 +1,152 @@
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import type { TranslationBundle } from '@jupyterlab/translation';
+import { fileIcon } from '@jupyterlab/ui-components';
+import type { CommandRegistry } from '@lumino/commands';
+import type { ReadonlyPartialJSONValue } from '@lumino/coreutils';
+import type { Message } from '@lumino/messaging';
+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 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 namespace WalkthroughPanel {
+  export 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 class WalkthroughPanel extends Panel {
+  constructor(options: WalkthroughPanel.IOptions) {
+    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(): void {
+    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.
+   */
+  protected onCloseRequest(msg: Message): void {
+    super.onCloseRequest(msg);
+    this.dispose();
+  }
+
+  /** Append a step and scroll it into view. */
+  async addStep(step: IWalkthroughStep): Promise<void> {
+    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;
+  }
+
+  private async _render(
+    parent: Panel,
+    mimeType: string,
+    data: ReadonlyPartialJSONValue
+  ): Promise<void> {
+    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 })
+    );
+  }
+
+  private _jumpButton(path: string, line?: number, endLine?: number): Widget {
+    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 });
+  }
+
+  private _rendermime: IRenderMimeRegistry;
+  private _commands: CommandRegistry;
+  private _trans: TranslationBundle;
+}

package/style/commandBar.css

@@ -0,0 +1,104 @@
+/* Centered command bar in the top area (xtralab:command-bar). */
+
+/*
+ * The bar is an overlay centered over the whole top panel rather than a flex
+ * item, so its position does not shift with the (variable) width of the menu
+ * bar on its left or the sidebar toggle button on its right. `#jp-top-panel`
+ * is a `.lm-Widget`, which Lumino renders `position: relative`, so this
+ * absolute box is centered against the full width of the top bar.
+ *
+ * `pointer-events: none` here (with `auto` restored on the pill below) keeps
+ * only the pill clickable: the transparent strips above and below it let
+ * clicks fall through to whatever sits beneath the overlay.
+ *
+ * The `z-index` must clear JupyterLab core's settings-driven "Topbar toolbar"
+ * (`#jp-top-bar`, added to the top area at rank 900), which is a `.jp-Toolbar`
+ * at `z-index: 8` that grows to fill the center and paints an opaque
+ * `--jp-toolbar-background`. Sitting one above it lets the centered pill show
+ * through; that toolbar is empty by default, so the overlay covers blank
+ * space rather than hiding any toolbar items.
+ */
+.jp-xtralab-CommandBar {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 50%;
+  z-index: 9;
+  display: flex;
+  align-items: center;
+  transform: translateX(-50%);
+  pointer-events: none;
+}
+
+.jp-xtralab-CommandBar-button {
+  display: flex;
+  flex: 0 0 auto;
+  gap: 6px;
+  align-items: center;
+  width: clamp(160px, 16vw, 220px);
+  height: 20px;
+  padding: 0 8px;
+  margin: 0;
+  overflow: hidden;
+  font-family: var(--jp-ui-font-family);
+  font-size: var(--jp-ui-font-size1);
+  color: var(--jp-ui-font-color2);
+  text-align: left;
+  cursor: pointer;
+
+  /* The theme's input-field fill, so the pill reads as a search box and tracks
+     each theme's input styling across light and dark (a flat layout color is
+     near-black in some dark themes). */
+  background: var(--jp-input-background);
+  border: var(--jp-border-width) solid var(--jp-border-color1);
+  border-radius: 10px;
+  appearance: none;
+  pointer-events: auto;
+}
+
+.jp-xtralab-CommandBar-button:hover {
+  color: var(--jp-ui-font-color1);
+  border-color: var(--jp-border-color0);
+}
+
+.jp-xtralab-CommandBar-button:focus-visible {
+  outline: var(--jp-border-width) solid var(--jp-brand-color1);
+  outline-offset: 1px;
+}
+
+.jp-xtralab-CommandBar-icon {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+}
+
+.jp-xtralab-CommandBar-icon svg {
+  width: 14px;
+  height: 14px;
+}
+
+/* The built-in JupyterLab search icon (@jupyterlab/ui-components) paints with a
+   fixed `jp-icon3` theme gray; override it to currentColor so the magnifier
+   tracks the pill's text color and brightens with the label on hover. */
+.jp-xtralab-CommandBar-button .jp-icon3[fill] {
+  fill: currentcolor;
+}
+
+.jp-xtralab-CommandBar-label {
+  flex: 1 1 auto;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Keyboard-shortcut hint, pushed to the trailing edge by the growing label. */
+.jp-xtralab-CommandBar-shortcut {
+  flex: 0 0 auto;
+  margin-left: 6px;
+  padding: 1px 4px;
+  font-size: var(--jp-ui-font-size0);
+  line-height: 1.2;
+  color: var(--jp-ui-font-color3);
+  border: var(--jp-border-width) solid var(--jp-border-color1);
+  border-radius: 4px;
+}

package/style/highlight.css

@@ -0,0 +1,11 @@
+/*
+ * Line highlight applied by `xtralab:highlight-lines`. The class lands on the
+ * CodeMirror line wrapper (`.cm-line`), so the tint spans the full editor width
+ * and a left accent bar marks the run. The translucent background keeps the
+ * code legible on both light and dark themes.
+ */
+
+.jp-xtralab-highlightLine {
+  background-color: rgb(250 204 21 / 18%);
+  box-shadow: inset 2px 0 0 0 var(--jp-brand-color1);
+}

package/style/index.css

@@ -1,8 +1,13 @@
 @import url('base.css');
+@import url('commandBar.css');
 @import url('editorBreadcrumbs.css');
 @import url('git.css');
+@import url('highlight.css');
 @import url('launcher.css');
+@import url('omnibox.css');
+@import url('showOutput.css');
 @import url('sidebar.css');
 @import url('tabs.css');
 @import url('terminals.css');
 @import url('topBar.css');
+@import url('walkthrough.css');

package/style/index.js

@@ -1,7 +1,12 @@
 import './base.css';
+import './commandBar.css';
 import './git.css';
+import './highlight.css';
 import './launcher.css';
+import './omnibox.css';
+import './showOutput.css';
 import './sidebar.css';
 import './tabs.css';
 import './terminals.css';
 import './topBar.css';
+import './walkthrough.css';

package/style/omnibox.css

@@ -0,0 +1,120 @@
+/* Omnibox overlay (xtralab:omnibox): a centered search box over the shell. */
+
+/*
+ * The widget node is attached to `document.body` (outside the shell) and only
+ * carries theme variables via `jp-ThemedContainer`; the React tree renders the
+ * fixed full-screen overlay below it.
+ */
+.jp-xtralab-Omnibox {
+  position: absolute;
+}
+
+/* Transparent full-viewport layer that centers the panel and catches
+   click-outside to dismiss. */
+.jp-xtralab-Omnibox-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 10001;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+}
+
+.jp-xtralab-Omnibox-panel {
+  display: flex;
+  flex-direction: column;
+  width: min(640px, 92vw);
+  max-height: 60vh;
+  overflow: hidden;
+
+  /* Drop just below the top bar so it reads as a command-center dropdown. */
+  margin-top: calc(var(--jp-private-menubar-height, 28px) + 4px);
+  background: var(--jp-layout-color1);
+  border: var(--jp-border-width) solid var(--jp-border-color1);
+  border-radius: 4px;
+  box-shadow: var(--jp-elevation-z6);
+}
+
+.jp-xtralab-Omnibox-input {
+  padding: 11px 14px;
+  font-family: var(--jp-ui-font-family);
+  font-size: var(--jp-ui-font-size2);
+  color: var(--jp-ui-font-color0);
+  background: transparent;
+  border: none;
+  border-bottom: var(--jp-border-width) solid var(--jp-border-color2);
+  outline: none;
+}
+
+.jp-xtralab-Omnibox-input::placeholder {
+  color: var(--jp-ui-font-color3);
+}
+
+.jp-xtralab-Omnibox-results {
+  padding: 4px 0;
+  overflow-y: auto;
+}
+
+.jp-xtralab-Omnibox-sectionHeader {
+  padding: 6px 14px 2px;
+  font-size: var(--jp-ui-font-size0);
+  font-weight: 600;
+  color: var(--jp-ui-font-color2);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.jp-xtralab-Omnibox-item {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  padding: 5px 14px;
+  font-size: var(--jp-ui-font-size1);
+  color: var(--jp-ui-font-color1);
+  cursor: pointer;
+}
+
+.jp-xtralab-Omnibox-item.jp-mod-active {
+  background: var(--jp-layout-color2);
+}
+
+.jp-xtralab-Omnibox-itemIcon {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  width: 16px;
+  height: 16px;
+}
+
+.jp-xtralab-Omnibox-itemIcon svg {
+  width: 16px;
+  height: 16px;
+}
+
+.jp-xtralab-Omnibox-itemLabel {
+  flex: 1 1 auto;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.jp-xtralab-Omnibox-match {
+  font-weight: 600;
+  color: var(--jp-ui-font-color0);
+}
+
+.jp-xtralab-Omnibox-itemCaption {
+  flex: 0 1 auto;
+  max-width: 45%;
+  overflow: hidden;
+  font-size: var(--jp-ui-font-size0);
+  color: var(--jp-ui-font-color3);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.jp-xtralab-Omnibox-empty {
+  padding: 14px;
+  font-size: var(--jp-ui-font-size1);
+  color: var(--jp-ui-font-color2);
+}

package/style/showOutput.css

@@ -0,0 +1,11 @@
+/*
+ * The panel `xtralab:show` renders into. It holds a single rendered output and
+ * scrolls when that output is taller (or wider) than the panel, which matters
+ * most in the narrow side area.
+ */
+
+.jp-xtralab-ShowPanel {
+  overflow: auto;
+  padding: 8px;
+  background: var(--jp-layout-color1);
+}

package/style/terminals.css

@@ -1,9 +1,11 @@
 /*
  * Left-sidebar panel listing running terminal sessions. Each row shows
- * the session's real (program-published) title and an inline shutdown
- * button that fades in on hover; the header carries the panel title and
- * a "new terminal" button. Colors and spacing pull from `--jp-*` custom
- * properties so the panel tracks the active JupyterLab theme.
+ * the session's real (program-published) title, a smaller line below it
+ * with the latest output from a running coding agent, and an inline
+ * shutdown button that fades in on hover; the header carries the panel
+ * title and a "new terminal" button. Colors and spacing pull from
+ * `--jp-*` custom properties so the panel tracks the active JupyterLab
+ * theme.
  */
 
 .jp-xtralab-Terminals {
@@ -105,7 +107,7 @@
 .jp-xtralab-Terminals-item {
   display: flex;
   align-items: stretch;
-  height: 28px;
+  min-height: 28px;
 }
 
 .jp-xtralab-Terminals-item:hover {
@@ -113,17 +115,19 @@
 }
 
 /*
- * The main click target: terminal icon + label, filling the row so the
- * whole strip activates the session. The close button sits to its right
- * and intercepts its own clicks via the React handler.
+ * The main click target: terminal icon + the title/activity text block,
+ * filling the row so the whole strip activates the session. The close button
+ * sits to its right and intercepts its own clicks via the React handler.
+ * Top-aligned so the icon sits on the title line when an activity line wraps
+ * the row to a second line.
  */
 .jp-xtralab-Terminals-item-activate {
   display: flex;
   flex: 1 1 auto;
-  align-items: center;
+  align-items: flex-start;
   gap: 6px;
   min-width: 0;
-  padding: 0 4px 0 12px;
+  padding: 5px 4px 5px 12px;
   background: transparent;
   border: none;
   color: inherit;
@@ -137,12 +141,44 @@
   outline-offset: -2px;
 }
 
+/* Nudge the 16px icon down a touch so it lines up with the title's cap
+ * height rather than the very top of the text block. */
+.jp-xtralab-Terminals-item-icon {
+  margin-top: 1px;
+}
+
+/* The title + activity column, between the icon and the close button. */
+.jp-xtralab-Terminals-item-text {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  gap: 1px;
+  min-width: 0;
+}
+
 .jp-xtralab-Terminals-item-label {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
+/*
+ * The latest line of agent output, shown under the title. Smaller and dimmer
+ * than the title so it reads as secondary, and clamped to two lines with an
+ * ellipsis so a long line can't stretch the row indefinitely.
+ */
+.jp-xtralab-Terminals-item-detail {
+  display: -webkit-box;
+  overflow: hidden;
+  font-size: var(--jp-ui-font-size0);
+  line-height: 1.3;
+  color: var(--jp-ui-font-color3);
+  text-overflow: ellipsis;
+  overflow-wrap: anywhere;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+}
+
 /*
  * Close button. Hidden by default so the row reads as plain text; fades
  * in when the row is hovered or the button itself takes focus.
@@ -205,6 +241,14 @@
   background-color: var(--jp-brand-color1);
 }
 
+/* Keep the activity line legible on the brand background: swap the dim
+ * neutral for the inverse font color, held a touch lighter than the title so
+ * it still reads as secondary. */
+.jp-xtralab-Terminals-item.jp-mod-current .jp-xtralab-Terminals-item-detail {
+  color: var(--jp-ui-inverse-font-color1);
+  opacity: 0.85;
+}
+
 /*
  * Invert the monochrome terminal glyph against the brand background, exactly
  * as the file listing does for its selected rows. Colored agent logos carry

package/style/walkthrough.css

@@ -0,0 +1,80 @@
+/*
+ * The read-only walkthrough panel (`xtralab:walkthrough`) in the side area. A
+ * scrollable column of step cards, each holding rendered Markdown, an optional
+ * embedded visual, and an optional "jump to code" button.
+ */
+
+.jp-xtralab-Walkthrough {
+  overflow-y: auto;
+  padding: 4px 0;
+  background: var(--jp-layout-color1);
+  color: var(--jp-ui-font-color1);
+  font-size: var(--jp-ui-font-size1);
+}
+
+.jp-xtralab-Walkthrough-step {
+  padding: 10px 12px 14px;
+  border-bottom: 1px solid var(--jp-border-color2);
+}
+
+.jp-xtralab-Walkthrough-stepTitle {
+  margin: 0 0 6px;
+  font-size: var(--jp-ui-font-size2);
+  font-weight: 600;
+  color: var(--jp-ui-font-color0);
+}
+
+.jp-xtralab-Walkthrough-content {
+  overflow-x: auto;
+}
+
+.jp-xtralab-Walkthrough-jumpRow {
+  margin-top: 8px;
+}
+
+/* A subtle native-feeling button: UI font and neutral colors, like the rest of
+   the JupyterLab chrome, with a leading file icon and a hover background. */
+.jp-xtralab-Walkthrough-jump {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  max-width: 100%;
+  box-sizing: border-box;
+  padding: 2px 8px 2px 5px;
+  border: var(--jp-border-width) solid var(--jp-border-color2);
+  border-radius: var(--jp-border-radius);
+  background: none;
+  color: var(--jp-ui-font-color1);
+  font-family: var(--jp-ui-font-family);
+  font-size: var(--jp-ui-font-size1);
+  line-height: 1.5;
+  cursor: pointer;
+}
+
+.jp-xtralab-Walkthrough-jump:hover {
+  background-color: var(--jp-layout-color2);
+  border-color: var(--jp-border-color1);
+}
+
+.jp-xtralab-Walkthrough-jump:focus-visible {
+  outline: none;
+  border-color: var(--jp-brand-color1);
+  box-shadow: inset 0 0 0 1px var(--jp-brand-color1);
+}
+
+.jp-xtralab-Walkthrough-jumpIcon {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+}
+
+.jp-xtralab-Walkthrough-jumpIcon svg {
+  width: 14px;
+  height: 14px;
+}
+
+.jp-xtralab-Walkthrough-jumpLabel {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}