xtralab 0.14.1 → 0.15.1

package/lib/menuBar/index.js

@@ -10,24 +10,14 @@ const PLUGIN_ID = 'xtralab:menu-bar';
 const OPEN_COMMAND = 'xtralab:open-main-menu';
 const TOGGLE_COMMAND = 'xtralab:toggle-menu-bar';
 /**
- * How long after the popup closes a button press still counts as "close
- * only". An open Lumino menu closes itself on any outside press from a
- * document `pointerdown` listener in the capture phase, which runs before
- * the button's own mousedown handler — so without this window, pressing the
- * button while the popup is open would close it and instantly reopen it.
+ * Guard after the popup closes: Lumino menus close on a capture-phase document
+ * pointerdown, before the button's mousedown, which would instantly reopen.
  */
 const REOPEN_GUARD_MS = 250;
 /**
- * Collapse the main menu bar into a compact menu button.
- *
- * The menu bar is hidden and a hamburger button in the top bar opens the same
- * menus as a vertical popup. The popup reuses the live `RankedMenu` instances
- * owned by the `MainMenu`, so menus added or removed at runtime are reflected
- * without duplication.
- *
- * Hiding covers the `jp-menu-panel` container too, which has its own
- * `min-height` and would otherwise leave an empty strip. The "Show Menu Bar"
- * toggle restores the classic bar.
+ * Collapse the main menu bar into a hamburger button whose popup reuses the
+ * live `RankedMenu` instances owned by `MainMenu`. Hiding covers the
+ * `jp-menu-panel` container too — its `min-height` would leave an empty strip.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -64,9 +54,8 @@ const plugin = {
         const openMenu = () => {
             var _a, _b;
             if (visible) {
-                // The classic bar is on screen; behave like keyboard menu
-                // activation instead of opening a redundant popup that would
-                // compete with the bar for the same Menu instances.
+                // With the classic bar on screen, act like keyboard menu activation —
+                // a popup would compete with the bar for the same Menu instances.
                 mainMenu.activeIndex = 0;
                 mainMenu.openActiveMenu();
                 return;
@@ -74,13 +63,8 @@ const plugin = {
             if (Date.now() - popupClosedAt < REOPEN_GUARD_MS) {
                 return;
             }
-            // One popup instance, rebuilt from the bar's current menus on every
-            // open so runtime menu changes stay reflected. It is a plain Lumino
-            // Menu rather than a MenuSvg: MenuSvg.insertItem re-wraps each
-            // submenu's renderer and insertItem on every call, which would pile
-            // wrappers onto the shared menus across reopens. The svg renderer and
-            // themed-container class are applied directly instead, matching how
-            // the real menus are constructed in MainMenu.
+            // A plain Menu rebuilt on every open; MenuSvg.insertItem would re-wrap
+            // each submenu's renderer per reopen, piling wrappers onto the shared menus.
             if (popup === null) {
                 popup = new Menu({ commands, renderer: MenuSvg.defaultRenderer });
                 popup.addClass('jp-ThemedContainer');
@@ -153,9 +137,8 @@ const plugin = {
             loaded.changed.connect(update);
         })
             .catch(reason => {
-            // Without settings the collapsed state cannot be managed (and the
-            // button was never added) — reveal the stock bar rather than leave
-            // the app with no reachable menus.
+            // Without settings the collapsed state cannot be managed and the button
+            // was never added; reveal the stock bar so menus stay reachable.
             applyVisibility(true);
             console.error(`Failed to load settings for ${PLUGIN_ID}`, reason);
         });

package/lib/menus/index.d.ts

@@ -1,14 +1,8 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Hide the "Run" and "Kernel" top-level menus while no kernel-using widget
- * is open in the main area. The agent-first launcher does not use kernels,
- * so showing those menus on a fresh workspace surfaces commands the user
- * cannot meaningfully invoke; remove them until a notebook or console is
- * opened, then restore them at their original ranks.
- *
- * Detection is duck-typed on `sessionContext`: NotebookPanel and ConsolePanel
- * both expose it, which avoids pulling in `@jupyterlab/notebook` and
- * `@jupyterlab/console` just to identify their widgets.
+ * Hide the Run and Kernel menus while no kernel-using widget is open in the
+ * main area, then restore them at their original ranks — the agent-first
+ * launcher does not use kernels, so a fresh workspace should not surface them.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;

package/lib/menus/index.js

@@ -2,15 +2,9 @@ import { ILabShell } from '@jupyterlab/application';
 import { IMainMenu } from '@jupyterlab/mainmenu';
 const PLUGIN_ID = 'xtralab:menus';
 /**
- * Hide the "Run" and "Kernel" top-level menus while no kernel-using widget
- * is open in the main area. The agent-first launcher does not use kernels,
- * so showing those menus on a fresh workspace surfaces commands the user
- * cannot meaningfully invoke; remove them until a notebook or console is
- * opened, then restore them at their original ranks.
- *
- * Detection is duck-typed on `sessionContext`: NotebookPanel and ConsolePanel
- * both expose it, which avoids pulling in `@jupyterlab/notebook` and
- * `@jupyterlab/console` just to identify their widgets.
+ * Hide the Run and Kernel menus while no kernel-using widget is open in the
+ * main area, then restore them at their original ranks — the agent-first
+ * launcher does not use kernels, so a fresh workspace should not surface them.
  */
 const plugin = {
     id: PLUGIN_ID,
@@ -19,27 +13,21 @@ const plugin = {
     requires: [IMainMenu, ILabShell],
     activate: (app, mainMenu, labShell) => {
         var _a, _b;
-        // The interface types (IRunMenu, IKernelMenu) extend IRankedMenu, but
-        // the concrete instances are RankedMenu/Menu — cast so we can hand them
-        // to MenuBar.removeMenu and IMainMenu.addMenu, which expect a `Menu`.
+        // The interface types extend IRankedMenu but the concrete instances are
+        // RankedMenu/Menu; cast for the MenuBar methods, which expect a `Menu`.
         const menuBar = mainMenu;
         const runMenu = mainMenu.runMenu;
         const kernelMenu = mainMenu.kernelMenu;
-        // Capture the schema-assigned ranks so the menus reappear in their
-        // original slots between View (rank 3) and Tabs (rank 500). Falling
-        // back to the hard-coded defaults from `MainMenu` keeps things sane
-        // if the schema ever omits the rank.
+        // Schema-assigned ranks so the menus reappear in their original slots;
+        // fall back to MainMenu's hard-coded defaults if the schema omits them.
         const runRank = (_a = mainMenu.runMenu.rank) !== null && _a !== void 0 ? _a : 4;
         const kernelRank = (_b = mainMenu.kernelMenu.rank) !== null && _b !== void 0 ? _b : 5;
         const isPresent = (menu) => Array.from(menuBar.menus).indexOf(menu) > -1;
         const update = () => {
             const show = hasKernelWidget(labShell);
             if (show) {
-                // Don't go through `mainMenu.addMenu`: it picks the insertion index
-                // from a private `_items` array that `removeMenu` doesn't update,
-                // so re-adding lands the menu at the wrong position. Insert
-                // directly on the MenuBar by walking current menus and finding
-                // the first sibling with a higher rank.
+                // Not `mainMenu.addMenu`: its insertion index comes from a private
+                // `_items` array that `removeMenu` doesn't update, misplacing re-adds.
                 if (!isPresent(runMenu)) {
                     insertByRank(menuBar, runMenu, runRank);
                 }
@@ -63,11 +51,9 @@ const plugin = {
     }
 };
 /**
- * True iff any widget in the main area exposes a `sessionContext` — the
- * shared marker for NotebookPanel, ConsolePanel, and kernel-attached file
- * editors. We don't import their concrete types because that would drag
- * `@jupyterlab/notebook` and `@jupyterlab/console` into xtralab's bundle
- * just to do an `instanceof` check.
+ * True iff any main-area widget exposes a `sessionContext` (NotebookPanel,
+ * ConsolePanel, kernel-attached editors) — duck-typed to keep
+ * `@jupyterlab/notebook` and `@jupyterlab/console` out of the bundle.
  */
 function hasKernelWidget(labShell) {
     for (const widget of labShell.widgets('main')) {
@@ -82,10 +68,8 @@ function hasSessionContext(widget) {
     return (candidate.sessionContext !== null && candidate.sessionContext !== undefined);
 }
 /**
- * Insert `menu` into `menuBar` at the position dictated by `rank`, using
- * the existing menus' ranks to find the slot. Menus without a numeric
- * rank are treated as +Infinity so they sink to the end (matching the
- * convention in `MenuFactory.createMenus`).
+ * Insert `menu` at the slot dictated by `rank`; rank-less menus count as
+ * +Infinity and sink to the end, matching `MenuFactory.createMenus`.
  */
 function insertByRank(menuBar, menu, rank) {
     const menus = menuBar.menus;

package/lib/omnibox/files.d.ts

@@ -1,7 +1,5 @@
 /**
- * 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 declare function loadWorkspaceFiles(): Promise<string[]>;

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>;
     /**