xtralab 0.15.0 → 0.15.2

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',