xtralab 0.14.1 → 0.15.1

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;

package/style/askAgent.css

@@ -1,10 +1,7 @@
 /*
- * Ask-agent surfaces (xtralab:ask-agent): the floating "Ask agent" pill that
- * follows a code selection, the prompt popup it (or the diff gutter "+"
- * button) opens, and the right-sidebar queue panel that reviews queued
- * prompts. The pill and popup are attached to `document.body`, outside the
- * shell, and carry `jp-ThemedContainer` so theme variables resolve; the
- * queue panel lives inside the shell.
+ * Ask-agent surfaces (xtralab:ask-agent): selection pill, prompt popup and
+ * right-sidebar queue panel. The pill and popup attach to `document.body`
+ * and carry `jp-ThemedContainer` so theme variables resolve.
  */
 
 .jp-xtralab-AskAgent-pill {
@@ -97,10 +94,6 @@
   color: var(--jp-ui-font-color2);
 }
 
-/*
- * Target chips: "New terminal" plus one chip per terminal with a running
- * agent. Present only while at least one agent terminal is running.
- */
 .jp-xtralab-AskAgent-targets {
   display: flex;
   flex-wrap: wrap;
@@ -213,14 +206,8 @@
   height: 16px;
 }
 
-/*
- * `margin-left: auto` keeps the action buttons pinned right even when the
- * agent radiogroup is absent (an existing session is the selected target,
- * so the agent choice is implied and the row is not rendered). The
- * "Send to %1" label embeds the session title, which the running agent may
- * grow long via its xterm title escape, so the buttons shrink and ellipsize
- * rather than overflowing the popup.
- */
+/* `margin-left: auto` pins the actions right when the agent radiogroup is absent;
+ * the xterm-growable session title makes the buttons shrink and ellipsize. */
 .jp-xtralab-AskAgent-actions {
   display: flex;
   flex: 0 1 auto;
@@ -256,7 +243,6 @@
   background: var(--jp-layout-color2);
 }
 
-/* The popup's send button and the panel's batch-send button match. */
 .jp-xtralab-AskAgent-submit,
 .jp-xtralab-AskAgentQueue-send {
   flex: 0 1 auto;
@@ -279,8 +265,7 @@
   opacity: 0.5;
 }
 
-/* Inset panel-background ring so keyboard focus stays visible on the
- * brand fill. */
+/* Inset panel-background ring keeps keyboard focus visible on the brand fill. */
 .jp-xtralab-AskAgent-submit:focus-visible,
 .jp-xtralab-AskAgentQueue-send:focus-visible {
   outline: var(--jp-border-width) solid var(--jp-layout-color1);
@@ -292,11 +277,7 @@
   background: var(--jp-brand-color0);
 }
 
-/*
- * Queue panel (right side area): the queued prompts awaiting a batch send,
- * each with a jump-to-code context line, a snippet preview and an editable
- * instruction, above a footer that picks the target and sends everything.
- */
+/* Queue panel (right side area): queued prompts awaiting a batch send. */
 .jp-xtralab-AskAgentQueue {
   display: flex;
   background: var(--jp-layout-color1);
@@ -317,9 +298,6 @@
   color: var(--jp-ui-font-color2);
 }
 
-/* `min-height: 0` lets the list shrink below its content height (a flex
- * item's default min-height is its content), so a long queue scrolls here
- * instead of pushing the footer out of the panel. */
 .jp-xtralab-AskAgentQueue-list {
   display: flex;
   flex: 1 1 auto;
@@ -409,8 +387,6 @@
   height: 14px;
 }
 
-/* Clamped preview of the selected code; the context line above jumps to
- * the real thing. */
 .jp-xtralab-AskAgentQueue-snippet {
   display: -webkit-box;
   margin: 0;
@@ -448,14 +424,10 @@
   color: var(--jp-ui-font-color3);
 }
 
-/* An emptied-out instruction blocks the batch send; make the gap visible. */
 .jp-xtralab-AskAgentQueue-instruction[aria-invalid='true'] {
   border-color: var(--jp-warn-color1);
 }
 
-/* Each prompt's own destination — the agent icon plus a select whose
- * closed text names the action ("Terminal 2 · Claude", "New terminal ·
- * Codex"), so a mixed queue can be scanned without opening dropdowns. */
 .jp-xtralab-AskAgentQueue-itemTargetRow {
   display: flex;
   gap: 6px;
@@ -474,8 +446,6 @@
   height: 16px;
 }
 
-/* The select is core's jp-HTMLSelect (the notebook-toolbar dropdown);
- * these rules only make it fill the row and ellipsize long labels. */
 .jp-xtralab-AskAgentQueue-itemTarget {
   flex: 1 1 auto;
   min-width: 0;
@@ -488,9 +458,7 @@
   white-space: nowrap;
 }
 
-/* A destination that has gone away (closed terminal, removed agent)
- * blocks the send; make the gap visible despite the borderless default.
- * The doubled-up class outweighs core's `.jp-HTMLSelect.jp-DefaultStyle
+/* The doubled-up class outweighs core's `.jp-HTMLSelect.jp-DefaultStyle
  * select` border reset regardless of stylesheet order. */
 .jp-xtralab-AskAgentQueue-itemTarget.jp-HTMLSelect select[aria-invalid='true'] {
   border: var(--jp-border-width) solid var(--jp-warn-color1);

package/style/base.css

@@ -1,22 +1,22 @@
-/*
-    See the JupyterLab Developer Guide for useful CSS Patterns:
-
-    https://jupyterlab.readthedocs.io/en/stable/developer/css.html
-*/
+/* Rules live on the section class below, so they travel when the tree moves. */
+.jp-xtralab-FileBrowserPanel {
+  display: flex;
+  flex-direction: column;
+  min-width: 200px;
+  overflow: hidden;
+}
 
 .jp-xtralab-FileBrowser {
   display: flex;
+  flex: 1 1 auto;
   flex-direction: column;
   min-width: 200px;
+  min-height: 0;
   overflow: hidden;
   background-color: var(--jp-layout-color1);
 
-  /*
-   * Map @pierre/trees CSS variables to the active JupyterLab theme. The
-   * `*-override` variants take precedence over the library's defaults, so
-   * these values track the JupyterLab theme automatically — no JS needed
-   * when the theme switches.
-   */
+  /* Map @pierre/trees variables to the JupyterLab theme; the `*-override`
+     variants beat the library defaults, so theme switches need no JS. */
   --trees-bg-override: var(--jp-layout-color1);
   --trees-bg-muted-override: var(--jp-layout-color2);
   --trees-fg-override: var(--jp-ui-font-color1);
@@ -35,32 +35,16 @@
   --trees-font-family-override: var(--jp-ui-font-family);
   --trees-font-size-override: var(--jp-ui-font-size1);
 
-  /*
-   * Push the search box, the scroll wrapper, and every row inside the
-   * tree away from the sidebar edge. `--trees-padding-inline` is the
-   * outer gutter the @pierre/trees host uses for the search box and the
-   * scroll container, and the row strip sits inside that gutter — so
-   * matching the 12px the JupyterLab toolbar uses on its sides keeps
-   * the toolbar buttons, the search bar, and the row hover/selection
-   * highlights vertically aligned. Row content padding stays at the
-   * default 4px so the icon → text rhythm doesn't change.
-   */
+  /* 12px matches the JupyterLab toolbar's side padding, so the search box,
+     row highlights and toolbar buttons align; row content keeps the 4px default. */
   --trees-padding-inline-override: 12px;
   --trees-item-padding-x-override: 4px;
 
-  /* Must carry a length unit. The library subtracts this from
-     `--trees-padding-inline` inside a `calc()`; a unitless `0` makes the
-     subtraction type-invalid, the whole padding-inline rule drops out,
-     and the rows snap back to the sidebar edge. */
+  /* Must carry a unit: the library subtracts this inside a `calc()`, and a
+     unitless `0` makes the whole padding-inline rule drop out. */
   --trees-item-margin-x-override: 0px;
 }
 
-/*
- * Match the spacing the default file browser uses around its top toolbar
- * (8px above, 12px on each side, flush with the content below). Without
- * this, the toolbar inherits jp-Toolbar's default border + padding which
- * looks heavier than the rest of the JupyterLab sidebar.
- */
 .jp-xtralab-FileBrowser-toolbar.jp-Toolbar {
   flex: 0 0 auto;
   height: auto;
@@ -85,12 +69,8 @@
   width: 28px;
 }
 
-/*
- * Promote the "new launcher" button to the same blue, wider call-to-action
- * the default file browser uses for `launcher:create`. The selectors mirror
- * the rules in `@jupyterlab/launcher-extension/style/base.css`, but target
- * our own command id and toolbar wrapper class.
- */
+/* Same blue call-to-action the default file browser gives `launcher:create`;
+ * selectors mirror `@jupyterlab/launcher-extension/style/base.css`. */
 .jp-xtralab-FileBrowser-toolbar
   > .jp-Toolbar-item
   .jp-ToolbarButtonComponent[data-command='xtralab:new-launcher'] {
@@ -129,46 +109,18 @@
   min-height: 0;
 }
 
-.jp-xtralab-FileBrowser file-tree-container {
+.jp-xtralab-FileBrowser-accordion {
   flex: 1 1 auto;
   min-height: 0;
 }
 
-/*
- * Drag image shown next to the cursor while dragging files out of the
- * tree. Mirrors the visual weight of the default file browser's drag
- * preview without depending on its DOM.
- */
-.jp-xtralab-DragImage {
-  position: absolute;
-  display: flex;
-  align-items: center;
-  gap: 4px;
-  padding: 2px 6px;
-  background-color: var(--jp-layout-color1);
-  border: 1px solid var(--jp-border-color2);
-  border-radius: 6px;
-  color: var(--jp-ui-font-color1);
-  font-family: var(--jp-ui-font-family);
-  font-size: var(--jp-ui-font-size1);
-  pointer-events: none;
-}
-
-.jp-xtralab-DragImage-icon {
-  display: inline-flex;
-  align-items: center;
+.jp-AccordionPanel-title > .jp-xtralab-FileBrowser-toolbar {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
 }
 
-.jp-xtralab-DragImage-count {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  min-width: 16px;
-  height: 16px;
-  padding: 0 4px;
-  background-color: var(--jp-brand-color1);
-  border-radius: 8px;
-  color: var(--jp-ui-inverse-font-color1);
-  font-size: var(--jp-ui-font-size0);
-  line-height: 1;
+.jp-xtralab-FileBrowser file-tree-container {
+  flex: 1 1 auto;
+  min-height: 0;
 }