xtralab 0.15.0 → 0.15.2

package/lib/omnibox/files.js

@@ -2,13 +2,9 @@ import { URLExt } from '@jupyterlab/coreutils';
 import { ServerConnection } from '@jupyterlab/services';
 /**
  * Fetch and flatten the workspace file list from `jupyterlab-quickopen`'s
- * server endpoint (`GET {base}/jupyterlab-quickopen/api/files`).
- *
- * We reuse quickopen's endpoint rather than walking the contents API so the
- * listing honors the same server-side `.gitignore` filtering quickopen does
- * (xtralab ships `respectGitignore: true`) in a single request. The endpoint
- * only exists when quickopen's server extension is installed and the server
- * reads a local filesystem; callers treat a rejection as "no file results".
+ * server endpoint, which applies server-side `.gitignore` filtering in one
+ * request. Rejects when the server extension is absent; callers treat that as
+ * "no file results".
  */
 async function fetchWorkspaceFiles(respectGitignore = true) {
     const settings = ServerConnection.makeSettings();
@@ -36,10 +32,8 @@ async function fetchWorkspaceFiles(respectGitignore = true) {
 const CACHE_TTL_MS = 15000;
 let cache = null;
 /**
- * The workspace file list, cached briefly so reopening the omnibox in quick
- * succession reuses one scan. A failed fetch (e.g. quickopen's server
- * extension is absent) resolves to an empty list so file search degrades to
- * "no results" instead of surfacing an error.
+ * The workspace file list, cached briefly so reopening the omnibox reuses one
+ * scan. A failed fetch resolves to an empty list.
  */
 export function loadWorkspaceFiles() {
     const now = Date.now();

package/lib/omnibox/index.d.ts

@@ -1,20 +1,10 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { IOmnibox } from './tokens';
 /**
- * The omnibox: a single launcher overlay that fuzzy-searches workspace files
- * (via jupyterlab-quickopen's gitignore-aware endpoint) and JupyterLab
- * commands (the command palette's entries plus registry commands the palette
- * doesn't list), and routes a typed prompt to one of the configured agents
- * (running it in a fresh terminal through the launcher's
- * `xtralab:start-agent:<id>` commands). It is opened by the top-bar command
- * bar.
- *
- * Commands run and files opened through the overlay are remembered (persisted
- * in the state database) and offered again at the top while the query is
- * empty; the `maxNumberRecents` setting caps how many of each are kept.
- *
- * The agent rows come from the launcher's `IAgentRegistry`; when the launcher
- * is disabled the omnibox still searches files and commands.
+ * The omnibox: a launcher overlay that fuzzy-searches workspace files and
+ * commands and routes a typed prompt to a configured agent in a fresh
+ * terminal. Recently used commands and files persist in the state database;
+ * without the launcher it still searches files and commands.
  */
 declare const plugin: JupyterFrontEndPlugin<IOmnibox>;
 export default plugin;

package/lib/omnibox/index.js

@@ -9,20 +9,10 @@ import { IOmnibox, OMNIBOX_OPEN_COMMAND } from './tokens';
 import { OmniboxWidget } from './widget';
 const PLUGIN_ID = 'xtralab:omnibox';
 /**
- * The omnibox: a single launcher overlay that fuzzy-searches workspace files
- * (via jupyterlab-quickopen's gitignore-aware endpoint) and JupyterLab
- * commands (the command palette's entries plus registry commands the palette
- * doesn't list), and routes a typed prompt to one of the configured agents
- * (running it in a fresh terminal through the launcher's
- * `xtralab:start-agent:<id>` commands). It is opened by the top-bar command
- * bar.
- *
- * Commands run and files opened through the overlay are remembered (persisted
- * in the state database) and offered again at the top while the query is
- * empty; the `maxNumberRecents` setting caps how many of each are kept.
- *
- * The agent rows come from the launcher's `IAgentRegistry`; when the launcher
- * is disabled the omnibox still searches files and commands.
+ * The omnibox: a launcher overlay that fuzzy-searches workspace files and
+ * commands and routes a typed prompt to a configured agent in a fresh
+ * terminal. Recently used commands and files persist in the state database;
+ * without the launcher it still searches files and commands.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -40,21 +30,15 @@ const plugin = {
         const { commands, docRegistry } = app;
         const trans = (translator !== null && translator !== void 0 ? translator : nullTranslator).load('jupyterlab');
         const placeholder = trans.__('Search files and commands, or ask an agent…');
-        // The palette's items carry per-item args (e.g. one "Use Theme: …" per
-        // theme) that a raw command-registry scan can't see, but `ICommandPalette`
-        // exposes no item list and the widget itself is unreachable through the
-        // shell (`LabShell.add` defers it until layout restore, after which the
-        // modal setting re-parents it out of the left area). The wrapper's
-        // `_palette` field is private in TypeScript only, so read it guarded.
+        // `ICommandPalette` exposes no item list and the palette widget is
+        // unreachable through the shell; duck-read the wrapper's TS-only-private `_palette`.
         const paletteItems = () => {
             const widget = palette === null || palette === void 0 ? void 0 : palette._palette;
             return widget instanceof CommandPalette ? [...widget.items] : [];
         };
         const recents = new OmniboxRecents({ state });
-        // Restore the persisted recents only after the configured cap is known:
-        // `restore` trims to `maxItems`, so restoring at the constructor default
-        // would permanently drop entries beyond it whenever the user configured a
-        // larger cap and the state fetch won the race against the settings load.
+        // Restore only after the configured cap is known: `restore` trims to
+        // `maxItems`, so restoring at the default could permanently drop entries.
         if (settingRegistry) {
             void settingRegistry
                 .load(PLUGIN_ID)
@@ -85,7 +69,7 @@ const plugin = {
         };
         const open = (query) => {
             // Reopen fresh each time so the input resets and the agent snapshot is
-            // current; the file list is cached separately (see files.ts).
+            // current; the file list stays cached (files.ts).
             close();
             const widget = new OmniboxWidget({
                 commands,
@@ -110,7 +94,6 @@ const plugin = {
             label: trans.__('Search…'),
             caption: trans.__('Search files and commands, or ask an agent'),
             execute: args => {
-                // Toggle: a second press (e.g. of the keyboard shortcut) closes it.
                 if (current && !current.isDisposed) {
                     close();
                     return;
@@ -119,7 +102,6 @@ const plugin = {
                 open(typeof query === 'string' ? query : undefined);
             }
         });
-        // Open the omnibox with Cmd/Ctrl+K, the common "command center" chord.
         commands.addKeyBinding({
             command: OMNIBOX_OPEN_COMMAND,
             keys: ['Accel K'],

package/lib/omnibox/model.d.ts

@@ -5,14 +5,14 @@ import type { CommandRegistry } from '@lumino/commands';
 import type { CommandPalette } from '@lumino/widgets';
 import type { IAgent } from '../launcher/agents';
 import type { OmniboxRecents } from './recents';
-/**
- * The source a result row came from, used to group rows under a header.
- */
 type OmniboxItemKind = 'command' | 'file' | 'agent';
 /**
  * A single result row, with the action it runs when chosen.
  */
 export interface IOmniboxItem {
+    /**
+     * The source category of the row: command, file, or agent.
+     */
     kind: OmniboxItemKind;
     /**
      * Stable React key.
@@ -47,34 +47,62 @@ interface IOmniboxSections {
      * Recently used commands and files, shown while the term is empty.
      */
     recent: IOmniboxItem[];
+    /**
+     * Commands matching the term.
+     */
     commands: IOmniboxItem[];
+    /**
+     * Workspace files matching the term.
+     */
     files: IOmniboxItem[];
+    /**
+     * Per-agent "Ask" rows carrying the term as a prompt.
+     */
     agents: IOmniboxItem[];
 }
+/**
+ * Inputs for {@link computeSections}.
+ */
 interface IComputeOptions {
+    /**
+     * Raw query text from the input.
+     */
     query: string;
+    /**
+     * The command registry used to look up and execute commands.
+     */
     commands: CommandRegistry;
     /**
-     * The command palette's items, whose labels are computed with each item's
-     * args — the only form in which entries like "Use Theme: …" exist.
+     * Palette items, whose labels are computed with each item's args — the only
+     * form in which entries like "Use Theme: …" exist.
      */
     paletteItems: ReadonlyArray<CommandPalette.IItem>;
+    /**
+     * The document registry used to pick file icons.
+     */
     docRegistry: DocumentRegistry;
+    /**
+     * The available agents; prompt-capable ones get "Ask" rows.
+     */
     agents: IAgent[];
+    /**
+     * Workspace-relative file paths to match against.
+     */
     files: string[];
     /**
      * Recently-used tracker; `null` disables the recent rows and recording.
      */
     recents: OmniboxRecents | null;
+    /**
+     * Translation bundle for row labels.
+     */
     trans: TranslationBundle;
 }
 /**
  * Build the grouped result set for a query. A leading `>` searches only
- * commands and a leading `/` only files; otherwise commands and files are
- * fuzzy-matched and every prompt-capable agent is offered an "Ask" row
- * carrying the query as its prompt. An empty term yields the recently used
- * rows for the active mode instead (and the widget shows a hint when there
- * are none).
+ * commands, `/` only files; otherwise every prompt-capable agent also gets an
+ * "Ask" row carrying the query as its prompt. An empty term yields the
+ * recently used rows for the active mode.
  */
 export declare function computeSections(options: IComputeOptions): IOmniboxSections;
 export {};

package/lib/omnibox/model.js

@@ -3,20 +3,14 @@ import { StringExt } from '@lumino/algorithm';
 import { agentCommandId } from '../launcher/tokens';
 const COMMAND_LIMIT = 7;
 const FILE_LIMIT = 10;
-/**
- * Prefixes that narrow the search to a single source: a leading `>` to
- * commands, a leading `/` to files (relative paths never start with `/`, so it
- * is unambiguous). Without a prefix, every source is searched.
- */
 const COMMAND_PREFIX = '>';
+// Unambiguous: workspace-relative paths never start with '/'.
 const FILE_PREFIX = '/';
 /**
  * Build the grouped result set for a query. A leading `>` searches only
- * commands and a leading `/` only files; otherwise commands and files are
- * fuzzy-matched and every prompt-capable agent is offered an "Ask" row
- * carrying the query as its prompt. An empty term yields the recently used
- * rows for the active mode instead (and the widget shows a hint when there
- * are none).
+ * commands, `/` only files; otherwise every prompt-capable agent also gets an
+ * "Ask" row carrying the query as its prompt. An empty term yields the
+ * recently used rows for the active mode.
  */
 export function computeSections(options) {
     const { query, commands, agents, trans } = options;
@@ -43,13 +37,11 @@ export function computeSections(options) {
         recent: [],
         commands: mode === 'files' ? [] : matchCommands(options, term),
         files: mode === 'commands' ? [] : matchFiles(options, term),
-        // Agents only in the unprefixed view; the prompt is the full typed query.
         agents: mode === 'all' ? buildAgentItems(commands, agents, term, trans) : []
     };
 }
 /**
- * Run a command and record the use on success, so failed commands never enter
- * the recents list.
+ * Run a command and record the use on success, so failures never enter the recents.
  */
 function executeCommand(commands, recents, id, args) {
     void commands
@@ -61,9 +53,6 @@ function executeCommand(commands, recents, id, args) {
         console.error(`xtralab omnibox: command "${id}" failed`, reason);
     });
 }
-/**
- * Open a file and record the use on success.
- */
 function openFile(commands, recents, path) {
     void commands
         .execute('docmanager:open', { path })
@@ -76,9 +65,8 @@ function openFile(commands, recents, path) {
 }
 /**
  * Read a command's label, visibility and caption, or `null` when the command
- * is missing, hidden, label-less, or its accessors throw (a command's
- * accessors can assume a context — e.g. an active notebook — the omnibox
- * doesn't provide).
+ * is missing, hidden, label-less, or its accessors throw (they can assume a
+ * context the omnibox doesn't provide).
  */
 function commandDisplay(commands, id, args) {
     if (!commands.hasCommand(id)) {
@@ -97,10 +85,9 @@ function commandDisplay(commands, id, args) {
 }
 /**
  * The recently used rows for the empty term: both kinds interleaved by
- * recency in the unprefixed view, or only the mode's kind under a bare `>` or
- * `/`. Commands that no longer resolve are dropped, as are files missing from
- * the loaded workspace listing (while the listing is still loading — or
- * unavailable — file entries are shown as recorded).
+ * recency, or only the mode's kind under a bare `>` or `/`. Unresolvable
+ * commands are dropped, as are files absent from the workspace listing once
+ * it loads.
  */
 function buildRecentItems(options, mode) {
     var _a;
@@ -147,11 +134,10 @@ function buildRecentItems(options, mode) {
     return items;
 }
 /**
- * Match the query against the palette's items first — their labels carry each
- * item's args (one "Use Theme: …" per theme, one row per font-size key), which
- * a raw registry scan can never produce — then against registry commands the
- * palette doesn't present. Palette-covered ids are skipped in the registry
- * pass so a command never also surfaces under its argless label.
+ * Match palette items first — their labels carry per-item args (one "Use
+ * Theme: …" per theme), which a registry scan can never produce — then
+ * registry commands the palette doesn't present, skipping palette-covered ids
+ * so a command never also surfaces under its argless label.
  */
 function matchCommands(options, term) {
     const { commands, paletteItems, recents } = options;
@@ -166,8 +152,6 @@ function matchCommands(options, term) {
         let visible = true;
         let caption = '';
         try {
-            // An item's accessors can throw if the command assumes a context (e.g.
-            // an active notebook) the omnibox doesn't provide; skip those.
             label = item.label;
             visible = item.isVisible;
             caption = item.caption;
@@ -209,8 +193,6 @@ function matchCommands(options, term) {
         let visible = true;
         let caption = '';
         try {
-            // A command's accessors can throw if they assume a context (e.g. an
-            // active notebook) the omnibox doesn't provide; skip those.
             label = commands.label(id);
             visible = commands.isVisible(id);
             caption = commands.caption(id);
@@ -276,7 +258,7 @@ function buildAgentItems(commands, agents, prompt, trans) {
     const items = [];
     for (const agent of agents) {
         // Agents without `promptArgs` can't take an inline prompt (the launcher
-        // would drop it), so they don't belong in an "Ask …" row.
+        // would drop it).
         if (agent.promptArgs === undefined) {
             continue;
         }

package/lib/omnibox/recents.d.ts

@@ -1,52 +1,50 @@
 import type { IStateDB } from '@jupyterlab/statedb';
 import type { ReadonlyPartialJSONObject } from '@lumino/coreutils';
-/**
- * Kinds of omnibox results whose uses are recorded.
- */
 export type RecentKind = 'command' | 'file';
 /**
  * A single recorded use: a command that was run or a file that was opened.
  */
 interface IRecentEntry {
+    /**
+     * Whether the entry records a command run or a file opened.
+     */
     kind: RecentKind;
     /**
      * The command id, or the workspace-relative file path.
      */
     id: string;
     /**
-     * Arguments the command ran with, for palette-style entries whose label
-     * and behavior depend on them (e.g. one "Use Theme: …" per theme).
+     * Arguments the command ran with, for palette-style entries whose label and
+     * behavior depend on them.
      */
     args?: ReadonlyPartialJSONObject;
 }
 /**
- * A most-recently-used list of omnibox results, generic over the result kind
- * so commands and files (and future kinds) share one store. Entries are kept
- * most-recent-first, capped at `maxItems` per kind, and persisted through the
- * state database so they survive reloads. Without a state database the list
- * still works for the lifetime of the page.
+ * A most-recently-used list of omnibox results, most-recent-first, capped at
+ * `maxItems` per kind and persisted through the state database. Without a
+ * state database it still works for the lifetime of the page.
  */
 export declare class OmniboxRecents {
     constructor(options?: OmniboxRecents.IOptions);
     /**
-     * Maximum number of entries remembered per kind. Lowering it trims the list
-     * immediately; `0` disables recents entirely.
+     * Maximum entries kept per kind; lowering trims immediately, `0` disables recents.
      */
     get maxItems(): number;
+    /**
+     * Set the maximum entries kept per kind.
+     */
     set maxItems(value: number);
     /**
-     * The recorded entries, most recent first — all of them, or only those of
-     * one kind.
+     * The recorded entries, most recent first, optionally filtered to one kind.
      */
     entries(kind?: RecentKind): IRecentEntry[];
     /**
-     * Record a use of `id` (with the args it ran with, if any), moving it to
-     * the front of its kind's list.
+     * Record a use, moving the entry to the front of its kind's list.
      */
     touch(kind: RecentKind, id: string, args?: ReadonlyPartialJSONObject): void;
     /**
      * Load the persisted list. Entries recorded before the load completes stay
-     * at the front, ahead of the restored history.
+     * ahead of the restored history.
      */
     restore(): Promise<void>;
     /**

package/lib/omnibox/recents.js

@@ -1,21 +1,16 @@
 /**
- * Identity of an entry: two uses only match when kind, id and args all do,
- * so runs of one command with different args stay distinct entries.
+ * Identity of an entry: two uses only match when kind, id and args all do, so
+ * runs of one command with different args stay distinct.
  */
 function entryKey(entry) {
     var _a;
     return `${entry.kind}\0${entry.id}\0${JSON.stringify((_a = entry.args) !== null && _a !== void 0 ? _a : null)}`;
 }
-/**
- * State database key the recents list is persisted under.
- */
 const STATE_KEY = 'xtralab:omnibox:recents';
 /**
- * A most-recently-used list of omnibox results, generic over the result kind
- * so commands and files (and future kinds) share one store. Entries are kept
- * most-recent-first, capped at `maxItems` per kind, and persisted through the
- * state database so they survive reloads. Without a state database the list
- * still works for the lifetime of the page.
+ * A most-recently-used list of omnibox results, most-recent-first, capped at
+ * `maxItems` per kind and persisted through the state database. Without a
+ * state database it still works for the lifetime of the page.
  */
 export class OmniboxRecents {
     constructor(options = {}) {
@@ -25,12 +20,14 @@ export class OmniboxRecents {
         this._state = (_a = options.state) !== null && _a !== void 0 ? _a : null;
     }
     /**
-     * Maximum number of entries remembered per kind. Lowering it trims the list
-     * immediately; `0` disables recents entirely.
+     * Maximum entries kept per kind; lowering trims immediately, `0` disables recents.
      */
     get maxItems() {
         return this._maxItems;
     }
+    /**
+     * Set the maximum entries kept per kind.
+     */
     set maxItems(value) {
         const normalized = Math.max(0, Math.floor(value));
         if (normalized === this._maxItems) {
@@ -44,8 +41,7 @@ export class OmniboxRecents {
         }
     }
     /**
-     * The recorded entries, most recent first — all of them, or only those of
-     * one kind.
+     * The recorded entries, most recent first, optionally filtered to one kind.
      */
     entries(kind) {
         return kind
@@ -53,8 +49,7 @@ export class OmniboxRecents {
             : [...this._entries];
     }
     /**
-     * Record a use of `id` (with the args it ran with, if any), moving it to
-     * the front of its kind's list.
+     * Record a use, moving the entry to the front of its kind's list.
      */
     touch(kind, id, args) {
         const entry = args === undefined ? { kind, id } : { kind, id, args };
@@ -65,7 +60,7 @@ export class OmniboxRecents {
     }
     /**
      * Load the persisted list. Entries recorded before the load completes stay
-     * at the front, ahead of the restored history.
+     * ahead of the restored history.
      */
     async restore() {
         if (!this._state) {

package/lib/omnibox/tokens.d.ts

@@ -1,9 +1,8 @@
 import { Token } from '@lumino/coreutils';
 /**
- * A launcher overlay that fuzzy-searches across multiple sources — workspace
- * files, JupyterLab commands — and routes a typed prompt to one of the
- * configured agents. Provided by `xtralab:omnibox` and consumed (optionally)
- * by the top-bar command bar, which opens it on click.
+ * A launcher overlay that fuzzy-searches workspace files and commands and
+ * routes a typed prompt to a configured agent. Provided by `xtralab:omnibox`;
+ * opened by the top-bar command bar.
  */
 export interface IOmnibox {
     /**
@@ -15,13 +14,9 @@ export interface IOmnibox {
      */
     close(): void;
 }
-/**
- * DI token for {@link IOmnibox}. Provided by `xtralab:omnibox`; consumed by
- * `xtralab:command-bar` so the top-bar pill opens the omnibox.
- */
 export declare const IOmnibox: Token<IOmnibox>;
 /**
- * Command id that opens the omnibox (registered by `xtralab:omnibox`). Shared
- * here so the command bar can look up its keybinding and show a shortcut hint.
+ * Command id that opens the omnibox, shared so the command bar can look up
+ * its keybinding for the shortcut hint.
  */
 export declare const OMNIBOX_OPEN_COMMAND = "xtralab:omnibox:open";

package/lib/omnibox/tokens.js

@@ -1,11 +1,7 @@
 import { Token } from '@lumino/coreutils';
-/**
- * DI token for {@link IOmnibox}. Provided by `xtralab:omnibox`; consumed by
- * `xtralab:command-bar` so the top-bar pill opens the omnibox.
- */
 export const IOmnibox = new Token('xtralab:IOmnibox', 'Opens the omnibox overlay that searches files and commands and prompts agents.');
 /**
- * Command id that opens the omnibox (registered by `xtralab:omnibox`). Shared
- * here so the command bar can look up its keybinding and show a shortcut hint.
+ * Command id that opens the omnibox, shared so the command bar can look up
+ * its keybinding for the shortcut hint.
  */
 export const OMNIBOX_OPEN_COMMAND = 'xtralab:omnibox:open';

package/lib/omnibox/widget.d.ts

@@ -6,30 +6,34 @@ import type { CommandPalette } from '@lumino/widgets';
 import type { IAgent } from '../launcher/agents';
 import type { OmniboxRecents } from './recents';
 /**
- * The omnibox overlay widget. Hosts {@link OmniboxComponent} in a React root
- * attached to `document.body`. It carries `jp-ThemedContainer` so JupyterLab's
- * theme CSS variables resolve outside the shell, and its own `jp-xtralab-Omnibox`
- * class for the overlay/panel styling (style/omnibox.css).
+ * The omnibox overlay widget, attached to `document.body`; `jp-ThemedContainer`
+ * makes JupyterLab's theme CSS variables resolve outside the shell.
  */
 export declare class OmniboxWidget extends ReactWidget {
     constructor(options: OmniboxWidget.IOptions);
+    /**
+     * Render the omnibox overlay content.
+     */
     render(): JSX.Element;
     private _options;
 }
-/**
- * A namespace for `OmniboxWidget` statics.
- */
 export declare namespace OmniboxWidget {
     /**
      * Construction options for {@link OmniboxWidget}.
      */
     interface IOptions {
+        /**
+         * The command registry used to look up and execute commands.
+         */
         commands: CommandRegistry;
         /**
          * Snapshot of the command palette's items, read once when the overlay
          * opens; empty when the palette isn't available.
          */
         paletteItems: ReadonlyArray<CommandPalette.IItem>;
+        /**
+         * The document registry used to pick file icons.
+         */
         docRegistry: DocumentRegistry;
         /**
          * Snapshot of the available agents, read once when the overlay opens.

package/lib/omnibox/widget.js

@@ -2,19 +2,13 @@ import { ReactWidget } from '@jupyterlab/ui-components';
 import * as React from 'react';
 import { computeSections } from './model';
 import { loadWorkspaceFiles } from './files';
-/**
- * DOM id of the results listbox, referenced by the input's `aria-controls`.
- */
 const LIST_ID = 'jp-xtralab-Omnibox-list';
-/**
- * Stable DOM id for the result row at `index`, for `aria-activedescendant`.
- */
 function optionId(index) {
     return `jp-xtralab-Omnibox-option-${index}`;
 }
 /**
  * Render `text` with the fuzzy-matched characters at `indices` wrapped in a
- * highlight span, leaving the rest as plain text.
+ * highlight span.
  */
 function renderHighlight(text, indices) {
     if (indices.length === 0) {
@@ -77,19 +71,16 @@ function OmniboxComponent(props) {
         ...sections.agents
     ], [sections]);
     const hasResults = flat.length > 0;
-    // Reset the highlighted row whenever the result set changes, and keep the
-    // index in range when results shrink.
     React.useEffect(() => {
         setActive(current => (current < flat.length ? current : 0));
     }, [flat]);
-    // Keep the highlighted row scrolled into view as it moves.
     React.useEffect(() => {
         var _a, _b;
         (_b = (_a = listRef.current) === null || _a === void 0 ? void 0 : _a.querySelector('.jp-mod-active')) === null || _b === void 0 ? void 0 : _b.scrollIntoView({ block: 'nearest' });
     }, [active, flat]);
     const dismiss = React.useCallback(() => {
-        // Defer so unmounting this React root (via onClose) never happens
-        // synchronously inside the event handler that triggered it.
+        // Defer so unmounting this React root never happens synchronously inside
+        // the event handler that triggered it.
         window.setTimeout(onClose, 0);
     }, [onClose]);
     const run = React.useCallback((item) => {
@@ -162,10 +153,8 @@ function OmniboxComponent(props) {
                 : trans.__('Search files and commands, or type a prompt and pick an agent. Prefix with > for commands or / for files.')))))));
 }
 /**
- * The omnibox overlay widget. Hosts {@link OmniboxComponent} in a React root
- * attached to `document.body`. It carries `jp-ThemedContainer` so JupyterLab's
- * theme CSS variables resolve outside the shell, and its own `jp-xtralab-Omnibox`
- * class for the overlay/panel styling (style/omnibox.css).
+ * The omnibox overlay widget, attached to `document.body`; `jp-ThemedContainer`
+ * makes JupyterLab's theme CSS variables resolve outside the shell.
  */
 export class OmniboxWidget extends ReactWidget {
     constructor(options) {
@@ -175,6 +164,9 @@ export class OmniboxWidget extends ReactWidget {
         this.addClass('jp-xtralab-Omnibox');
         this.addClass('jp-ThemedContainer');
     }
+    /**
+     * Render the omnibox overlay content.
+     */
     render() {
         return React.createElement(OmniboxComponent, { ...this._options });
     }