gloomberb 0.15.2 → 0.15.4

package/src/components/command-bar/routes/root/plugin-install.ts

@@ -0,0 +1,304 @@
+import { useEffect, useMemo, useState } from "react";
+import type { PluginRegistry } from "../../../../plugins/registry";
+import { findAbsorbedPlugin } from "../../../../plugins/absorbed";
+import { isOfficialPluginRepo } from "../../../../plugins/auto-update";
+import { getCurrentPluginTarget, runsExternalPlugins } from "../../../../plugins/current-target";
+import { activateInstalledPlugin } from "../../../../plugins/builtin/plugin-marketplace/activation";
+import { loadRegistry, registryPluginUrl } from "../../../../plugins/builtin/plugin-marketplace/feed";
+import {
+  installConsent,
+  registryPin,
+  type RegistryPlugin,
+  type RegistryPluginShortcut,
+} from "../../../../plugins/builtin/plugin-marketplace/model";
+import {
+  getMarketplaceHost,
+  getPluginManager,
+  type MarketplaceHost,
+  type PluginManager,
+} from "../../../../plugins/builtin/plugin-marketplace/store";
+import type { PluginTarget } from "../../../../types/plugin";
+import { requiredGloomberb } from "../../../../utils/semver";
+import { getCommandPrefixes, type Command } from "../../commands/registry";
+import { paneTemplateShortcutPrefixes } from "../../pane-templates/items";
+import type { ResultItem } from "../../list/model";
+import type { OpenInlineConfirm } from "../../routing/confirm";
+import { PLUGIN_INSTALL_CATEGORY } from "../../view-model";
+import { openUrl } from "../../../ui/external-link";
+
+/** A typed code that belongs to an official plugin this app does not have. */
+export interface PluginInstallOffer {
+  plugin: RegistryPlugin;
+  shortcut: RegistryPluginShortcut;
+  /** What followed the code, handed to the function once it opens. */
+  argText: string;
+}
+
+/**
+ * Only plugins Gloom publishes. A typed word must never lead to installing
+ * someone else's code, so the repository owner decides, not the feed's tier.
+ * A plugin that is built in now (absorbed.ts) is never offered, whatever the
+ * feed says: its code opens the built-in, and the installer refuses it.
+ */
+function isOfferable(plugin: RegistryPlugin): boolean {
+  return plugin.tier === "official"
+    && plugin.bundled !== true
+    && isOfficialPluginRepo(plugin.repo)
+    && !findAbsorbedPlugin({ id: plugin.id });
+}
+
+/** The feed is read defensively: an entry can come from any registry version. */
+function declaredShortcuts(plugin: RegistryPlugin): RegistryPluginShortcut[] {
+  const shortcuts = plugin.contributes?.shortcuts;
+  if (!Array.isArray(shortcuts)) return [];
+  return shortcuts.filter((shortcut): shortcut is RegistryPluginShortcut => (
+    !!shortcut && typeof shortcut.code === "string" && typeof shortcut.name === "string"
+  ));
+}
+
+/**
+ * Matches the code alone or as the first word, with a ticker or query after
+ * it, case-insensitively. A code the app already answers to (a built-in, or a
+ * plugin that is installed) always wins, and an installed plugin is never
+ * offered again, even when it is switched off or failed to load.
+ */
+export function matchPluginInstallOffer({
+  query,
+  registry,
+  isClaimed,
+  isInstalled,
+}: {
+  query: string;
+  registry: readonly RegistryPlugin[];
+  isClaimed: (code: string) => boolean;
+  isInstalled: (plugin: RegistryPlugin) => boolean;
+}): PluginInstallOffer | null {
+  const trimmed = query.trim();
+  const firstWord = trimmed.split(/\s+/, 1)[0] ?? "";
+  const code = firstWord.toUpperCase();
+  if (!code) return null;
+
+  for (const plugin of registry) {
+    if (!isOfferable(plugin)) continue;
+    const shortcut = declaredShortcuts(plugin).find((entry) => entry.code.trim().toUpperCase() === code);
+    if (!shortcut) continue;
+    // Asked only once a code matched: both walk everything the app has loaded.
+    if (isClaimed(code) || isInstalled(plugin)) return null;
+    return { plugin, shortcut, argText: trimmed.slice(firstWord.length).trim() };
+  }
+  return null;
+}
+
+/**
+ * Every code the app answers to right now: built-in commands, and the pane
+ * templates and commands of every registered plugin, switched off or not.
+ */
+export function collectClaimedShortcutCodes(
+  commands: readonly Command[],
+  pluginRegistry: Pick<PluginRegistry, "paneTemplates" | "commands">,
+): Set<string> {
+  const codes = new Set<string>();
+  for (const command of commands) {
+    for (const prefix of getCommandPrefixes(command)) codes.add(prefix);
+  }
+  for (const template of pluginRegistry.paneTemplates.values()) {
+    for (const prefix of paneTemplateShortcutPrefixes(template)) codes.add(prefix.trim().toUpperCase());
+  }
+  for (const command of pluginRegistry.commands.values()) {
+    const shortcut = command.shortcut?.trim().toUpperCase();
+    if (shortcut) codes.add(shortcut);
+  }
+  return codes;
+}
+
+/** Installed means loaded, listed under its id, or checked out under its repository's folder. */
+export function isRegistryPluginInstalled(
+  plugin: RegistryPlugin,
+  installed: ReadonlyArray<{ id: string; directory?: string }>,
+): boolean {
+  const directory = plugin.repo?.split("/")[1]?.replace(/\.git$/, "").toLowerCase();
+  return installed.some((entry) => (
+    entry.id === plugin.id
+    || (!!directory && entry.directory?.toLowerCase() === directory)
+  ));
+}
+
+/**
+ * The registry as last read; empty until the first answer, and on failure.
+ * Read from the first typed character, and only once a renderer has declared
+ * itself: a command bar rendered by a test stays off the network, and cannot
+ * pick up rows from whatever the live registry holds that day.
+ */
+function useRegistryPlugins(active: boolean): readonly RegistryPlugin[] {
+  const [plugins, setPlugins] = useState<readonly RegistryPlugin[] | null>(null);
+  const load = active && plugins === null && getCurrentPluginTarget() !== "cli";
+  useEffect(() => {
+    if (!load) return;
+    let cancelled = false;
+    void loadRegistry().then((result) => {
+      if (!cancelled) setPlugins(result.plugins);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [load]);
+  return plugins ?? NO_PLUGINS;
+}
+
+const NO_PLUGINS: readonly RegistryPlugin[] = [];
+
+function targetsOf(plugin: RegistryPlugin): PluginTarget[] {
+  return Array.isArray(plugin.targets) ? plugin.targets : [];
+}
+
+/** "the desktop app and the terminal", for a plugin that cannot be installed here. */
+function whereItRuns(plugin: RegistryPlugin): string {
+  const targets = targetsOf(plugin);
+  const desktop = targets.includes("desktop");
+  const terminal = targets.includes("tui") || targets.includes("cli");
+  if (desktop && !terminal) return "the desktop app";
+  if (terminal && !desktop) return "the terminal";
+  return "the desktop app and the terminal";
+}
+
+interface PluginInstallItemContext {
+  target: PluginTarget;
+  /** Null where this renderer cannot install plugins: the web app. */
+  manager: PluginManager | null;
+  host: MarketplaceHost | null;
+  openInlineConfirm: OpenInlineConfirm;
+  /** Submits the typed text again once the plugin is in, exactly as if typed and entered. */
+  runQuery: (query: string) => void;
+  notify: (body: string, type: "info" | "error") => void;
+  openUrl: (url: string) => void;
+}
+
+/**
+ * One row: the function's name and description, then what Enter does. Where
+ * the plugin cannot be installed, Enter opens its page instead of an install
+ * that would fail.
+ */
+function buildPluginInstallItem(
+  offer: PluginInstallOffer,
+  query: string,
+  context: PluginInstallItemContext,
+): ResultItem {
+  const { plugin, shortcut } = offer;
+  const { manager, host } = context;
+  const repo = plugin.repo ?? "";
+  const pageUrl = registryPluginUrl(plugin.id);
+  const installable = !!manager && !!host && !!repo
+    && runsExternalPlugins(context.target)
+    && targetsOf(plugin).includes(context.target);
+  const required = installable ? requiredGloomberb(plugin.minGloomberb) : null;
+
+  const actionLine = !installable
+    ? `Get it in ${whereItRuns(plugin)}: ${pageUrl.replace(/^https:\/\//, "")}`
+    : required
+      ? `Needs Gloomberb ${required}. Update Gloomberb first.`
+      : `Install ${plugin.name}`;
+
+  const install = () => {
+    if (!manager || !host) return;
+    const pin = registryPin({ availableVersion: plugin.ref, availableCommit: plugin.commit });
+    const consent = installConsent({
+      name: plugin.name,
+      tier: plugin.tier,
+      hosts: Array.isArray(plugin.hosts) ? plugin.hosts : [],
+      repo,
+    }, pin);
+    let opens = false;
+    context.openInlineConfirm({
+      confirmId: `install-plugin:${plugin.id}`,
+      title: consent.title,
+      body: consent.body,
+      confirmLabel: "Install",
+      tone: "default",
+      onConfirm: async () => {
+        const result = await manager.install(repo, pin);
+        if (!result.ok) throw new Error(`Could not install ${plugin.name}: ${result.error}`);
+        const activated = await activateInstalledPlugin(result.directory, host, manager);
+        if (!activated.ok) throw new Error(`${plugin.name} installed but did not load: ${activated.error}`);
+        if (activated.restart) {
+          context.notify(`Restart to finish installing ${plugin.name}.`, "info");
+          return;
+        }
+        opens = true;
+      },
+      // After the bar has closed, so the function opens through the same path
+      // as typing its code with the plugin installed, argument and all.
+      onSuccess: () => {
+        if (opens) context.runQuery(query);
+      },
+    });
+  };
+
+  return {
+    id: `plugin-install:${plugin.id}:${shortcut.code}`,
+    label: shortcut.name,
+    detail: shortcut.description,
+    category: PLUGIN_INSTALL_CATEGORY,
+    kind: "action",
+    right: shortcut.code,
+    searchText: [shortcut.code, shortcut.name, plugin.name].join(" "),
+    lines: [
+      ...(shortcut.description ? [{ segments: [{ text: shortcut.description, emphasis: "muted" as const }] }] : []),
+      { segments: [{ text: actionLine, emphasis: required ? "muted" as const : "match" as const }] },
+    ],
+    disabled: !!required,
+    action: installable ? install : () => context.openUrl(pageUrl),
+  };
+}
+
+/**
+ * The install row for the root query, or null. `enabled` is false whenever
+ * something else already claimed the query or the bar shows another route,
+ * such as the install confirmation, so coming back from one re-reads what is
+ * installed.
+ */
+export function useRootPluginInstallItem({
+  enabled,
+  query,
+  commands,
+  pluginRegistry,
+  openInlineConfirm,
+  rerunQuery,
+  closeBar,
+}: {
+  enabled: boolean;
+  query: string;
+  commands: readonly Command[];
+  pluginRegistry: PluginRegistry;
+  openInlineConfirm: OpenInlineConfirm;
+  rerunQuery: (query: string) => void;
+  closeBar: () => void;
+}): ResultItem | null {
+  const registry = useRegistryPlugins(enabled && query.trim().length > 0);
+  const offer = useMemo(() => {
+    if (!enabled || registry.length === 0) return null;
+    return matchPluginInstallOffer({
+      query,
+      registry,
+      isClaimed: (code) => collectClaimedShortcutCodes(commands, pluginRegistry).has(code),
+      isInstalled: (plugin) => isRegistryPluginInstalled(
+        plugin,
+        getMarketplaceHost()?.listInstalled() ?? [...pluginRegistry.allPlugins.keys()].map((id) => ({ id })),
+      ),
+    });
+  }, [commands, enabled, pluginRegistry, query, registry]);
+
+  return useMemo(() => offer
+    ? buildPluginInstallItem(offer, query, {
+      target: getCurrentPluginTarget(),
+      manager: getPluginManager(),
+      host: getMarketplaceHost(),
+      openInlineConfirm,
+      runQuery: rerunQuery,
+      notify: (body, type) => pluginRegistry.notify({ body, type }),
+      openUrl: (url) => {
+        openUrl(url);
+        closeBar();
+      },
+    })
+    : null, [closeBar, offer, openInlineConfirm, pluginRegistry, query, rerunQuery]);
+}

package/src/components/command-bar/routes/root/results.ts

@@ -67,6 +67,11 @@ export interface RootResultModelOptions {
   paneShortcutItems: (options?: PaneShortcutItemsOptions) => ResultItem[];
   pluginCommandItems: () => ResultItem[];
   pluginCommandResultItems: (command: CommandDef, shortcutArg: string) => ResultItem[];
+  /**
+   * The install row for a code only an official plugin the user lacks answers
+   * to. It leads the list but claims nothing: the same text may be a ticker.
+   */
+  pluginInstallItem?: ResultItem | null;
   rootQuery: string;
   rootShortcutIntent: RootShortcutIntent;
   /**
@@ -146,6 +151,7 @@ export function buildRootResultModel(options: RootResultModelOptions): RootResul
     paneShortcutItems,
     pluginCommandItems,
     pluginCommandResultItems,
+    pluginInstallItem,
     rootQuery,
     rootShortcutIntent,
     providerResultItems = [],
@@ -296,5 +302,8 @@ export function buildRootResultModel(options: RootResultModelOptions): RootResul
     ? buildAssistResultItems({ ...assist, query: rootQuery })
     : [];
 
-  return { items: dedupeById([...assistItems, ...items]), initialIdx };
+  // Added last, so everything above is built exactly as it would be without
+  // it; its section sorts ahead of the rest.
+  const installItems = pluginInstallItem ? [pluginInstallItem] : [];
+  return { items: dedupeById([...installItems, ...assistItems, ...items]), initialIdx };
 }

package/src/components/command-bar/routes/root/runtime.ts

@@ -16,10 +16,7 @@ import { buildRootResultModel, type RootResultModel } from "./results";
 import { useRootProviderSearch } from "./provider-search";
 import { buildRootShortcutFeedback } from "./shortcut-feedback";
 import type { ShortcutIntent } from "./shortcuts";
-
-function clampSelectedIdx(index: number, length: number): number {
-  return Math.max(0, Math.min(index, length - 1));
-}
+import { clampIndex } from "../../../../utils/math";
 
 /** A row plain Enter can run, so the untouched selection may rest on it. */
 function isDefaultSelectable(item: ResultItem): boolean {
@@ -65,6 +62,7 @@ interface UseCommandBarRootRuntimeOptions {
   }): ResultItem[];
   pluginCommandItems(): ResultItem[];
   pluginCommandResultItems(command: CommandDef, shortcutArg: string): ResultItem[];
+  pluginInstallItem?: ResultItem | null;
   providerResultItems?: ResultItem[];
   providerCategoryPriorities?: CommandBarCategoryPriorities;
   providerSearching?: boolean;
@@ -119,6 +117,7 @@ export function useCommandBarRootRuntime({
   paneShortcutItems,
   pluginCommandItems,
   pluginCommandResultItems,
+  pluginInstallItem = null,
   providerResultItems = [],
   providerCategoryPriorities,
   providerSearching = false,
@@ -193,6 +192,7 @@ export function useCommandBarRootRuntime({
     paneShortcutItems,
     pluginCommandItems,
     pluginCommandResultItems,
+    pluginInstallItem,
     rootQuery,
     rootShortcutIntent,
     providerResultItems,
@@ -222,6 +222,7 @@ export function useCommandBarRootRuntime({
     paneShortcutItems,
     pluginCommandItems,
     pluginCommandResultItems,
+    pluginInstallItem,
     rootQuery,
     rootShortcutIntent,
     providerResultItems,
@@ -242,13 +243,16 @@ export function useCommandBarRootRuntime({
     const trimmed = rootQuery.trim();
     if (trimmed.length < 2) return null;
     const normalizedQuery = normalizeCommandTickerSearchText(trimmed);
+    // The install row for "TV" is labelled TV, but it leads on purpose and
+    // must not keep Grupo Televisa out of the list.
     const hasExactLocalRow = rootResultModel.items.some((item) => (
-      item.kind !== "ticker"
+      item !== pluginInstallItem
+      && item.kind !== "ticker"
       && item.kind !== "search"
       && normalizeCommandTickerSearchText(item.label) === normalizedQuery
     ));
     return hasExactLocalRow ? null : trimmed;
-  }, [activeMatch, currentRoute, rootQuery, rootResultModel.items, rootShortcutIntent.kind]);
+  }, [activeMatch, currentRoute, pluginInstallItem, rootQuery, rootResultModel.items, rootShortcutIntent.kind]);
   const rootTickerSearchArg = rootSecurityDescriptionArg ?? rootPlainTickerSearchArg;
 
   const {
@@ -298,11 +302,11 @@ export function useCommandBarRootRuntime({
         const selectedId = previousResultIds[current];
         const shiftedIdx = selectedId ? resultIds.indexOf(selectedId) : -1;
         if (shiftedIdx >= 0) return shiftedIdx;
-        return clampSelectedIdx(current, resultIds.length);
+        return clampIndex(current, resultIds.length);
       }
       // Untouched, the selection follows the best row on offer.
       const defaultIdx = orderedRootResults.findIndex(isDefaultSelectable);
-      return clampSelectedIdx(Math.max(rootResultModel.initialIdx, defaultIdx), resultIds.length);
+      return clampIndex(Math.max(rootResultModel.initialIdx, defaultIdx), resultIds.length);
     });
   }, [
     activeMatch?.command.id,

package/src/components/command-bar/routes/root/search-report.ts

@@ -0,0 +1,246 @@
+import { useCallback, useEffect, useRef, type RefObject } from "react";
+import {
+  apiClient,
+  type CommandSearchChoice,
+  type CommandSearchOutcome,
+} from "../../../../api-client";
+import { automationActive } from "../../../../telemetry/usage-counts";
+import { VERSION } from "../../../../version";
+import type { ResultItem } from "../../list/model";
+import type { CommandBarRoute } from "../../workflow/types";
+
+/**
+ * Rows of the command that switches the Usage setting, which also covers the
+ * report: turning it off from the bar must not be the last thing it sends.
+ */
+const USAGE_SETTING_ROW_IDS = new Set(["toggle-usage-counts", "command:toggle-usage-counts"]);
+
+/** A root row the user runs, read before it runs: running a row can rewrite the query. */
+export interface RootRowRun {
+  item: ResultItem;
+  /** The root query at that moment, as typed. */
+  query: string;
+  /** Position in the list on screen; 0 for text that ran before its list rendered. */
+  rank: number;
+  /**
+   * Whether the row is the typed shortcut itself ("DES MSFT" resolving to its
+   * own row), rather than another row shown for it. Read only when the run is
+   * reported.
+   */
+  isShortcut: () => boolean;
+}
+
+/**
+ * Runs a root row as the report sees it. `action` runs the row and may return
+ * false when nothing ran after all.
+ */
+export type RunRootRow = (run: RootRowRun, action: () => boolean | void) => void;
+
+interface PendingChoice {
+  query: string;
+  choice: CommandSearchChoice;
+}
+
+/**
+ * What running a root row is reported as, or null for a placeholder that
+ * answers nothing ("Thinking…", a failed search). `shortcut` means the typed
+ * text itself ran ("DES MSFT"); other rows keep their own kind.
+ */
+function describeRootChoice(run: RootRowRun): CommandSearchChoice | null {
+  const { item, rank } = run;
+  if (item.kind === "info") return null;
+  const base = {
+    label: item.label,
+    rank,
+    ...(item.category ? { category: item.category } : {}),
+  };
+  if (item.searchChoice?.kind === "assist") {
+    return { kind: "assist", ...base, input: item.searchChoice.input, fromAssist: true };
+  }
+  if (item.searchChoice?.kind === "ask-gloom") {
+    return { kind: "ask-gloom", ...base, fromAssist: false };
+  }
+  if (run.isShortcut()) return { kind: "shortcut", ...base, input: run.query.trim(), fromAssist: false };
+  return { kind: item.kind, ...base, fromAssist: false };
+}
+
+interface CommandSearchReportOptions {
+  currentRouteRef: RefObject<CommandBarRoute | null>;
+  /** Whether automation set this query and the user has not edited it since. */
+  isAutomationQuery: (query: string) => boolean;
+  /** The Usage setting, read when a report would go out and again as it is sent. */
+  isEnabled: () => boolean;
+  /**
+   * The text the bar was opened with (a menu opens it on "HELP" or "TH ").
+   * When it changes while the bar is open, a menu or a key reopened it: a new
+   * visit.
+   */
+  openingQuery: string;
+  rootQueryRef: RefObject<string>;
+  /** Whether a route is on screen, to notice the user backing out of one. */
+  routeOpen: boolean;
+  /** The `/assist/command` record the bar kept for this query, answered or not. */
+  searchIdFor: (query: string) => string | undefined;
+}
+
+/**
+ * Reports how one visit to the command bar ended, at most once: the root
+ * query the user finished and the row they ran from the root list, or, when
+ * the bar closes on a root query with nothing run, that they dismissed it.
+ * Keystrokes are never reported, nor an empty query, nor anything typed in a
+ * route (a ticker search, a pane form).
+ *
+ * The first root row that runs is held as the visit's choice until the bar
+ * closes. A row that only rewrites the query ("Change Theme" writes "TH ")
+ * does not count, and backing out of the route a row opened drops it, so the
+ * search goes on. `finish` is the close after something ran: it sends the
+ * held choice, or nothing when what ran was not a root choice (a key-bound
+ * command, a route a menu opened). `dismiss` is any other close (Esc, a click
+ * outside, the bar's own key; unmounting calls it too): it sends the held
+ * choice as it stands, or else a dismissal of the root query, skipped while a
+ * route is open or the query is still the text the bar opened with. `settle`
+ * ends the visit with no report.
+ *
+ * Reports follow the Usage setting and leave out automation: nothing is sent
+ * while remote control is running, nor for a query it typed that the user has
+ * not edited. Each report goes out on a later tick, so it never holds up what
+ * the user ran; signed out, the client sends nothing.
+ */
+export function useCommandSearchReport({
+  currentRouteRef,
+  isAutomationQuery,
+  isEnabled,
+  openingQuery,
+  rootQueryRef,
+  routeOpen,
+  searchIdFor,
+}: CommandSearchReportOptions): {
+  choose: (query: string, choice: CommandSearchChoice) => void;
+  dismiss: () => void;
+  finish: () => void;
+  runRootRow: RunRootRow;
+  settle: () => void;
+} {
+  const settledRef = useRef(false);
+  const pendingRef = useRef<PendingChoice | null>(null);
+  /** The text the bar opened with: menus open it on "HELP" or "TH ", which nobody typed. */
+  const initialQueryRef = useRef(openingQuery);
+  const isEnabledRef = useRef(isEnabled);
+  isEnabledRef.current = isEnabled;
+  const isAutomationQueryRef = useRef(isAutomationQuery);
+  isAutomationQueryRef.current = isAutomationQuery;
+  const searchIdForRef = useRef(searchIdFor);
+  searchIdForRef.current = searchIdFor;
+
+  const send = useCallback((query: string, outcome: CommandSearchOutcome, choice?: CommandSearchChoice) => {
+    try {
+      const allowed = () => (
+        !automationActive() && isEnabledRef.current() && !isAutomationQueryRef.current(query)
+      );
+      if (!query || !allowed()) return;
+      const searchId = searchIdForRef.current(query);
+      const report = {
+        query,
+        ...(searchId ? { searchId } : {}),
+        outcome,
+        ...(choice ? { choice } : {}),
+        appVersion: VERSION,
+      };
+      setTimeout(() => {
+        try {
+          // The setting or automation may have changed since the choice.
+          if (allowed()) apiClient.reportCommandSearch(report);
+        } catch {
+          /* A report must never get in the way of the command bar. */
+        }
+      }, 0);
+    } catch {
+      /* A report must never get in the way of the command bar. */
+    }
+  }, []);
+
+  const runRootRow = useCallback<RunRootRow>((run, action) => {
+    // Checked first: a choice still held from earlier in the visit must not go
+    // out as the user switches reports off.
+    if (USAGE_SETTING_ROW_IDS.has(run.item.id)) {
+      settledRef.current = true;
+      pendingRef.current = null;
+      action();
+      return;
+    }
+    // The first choice of the visit stands; later runs are not reported.
+    if (settledRef.current || pendingRef.current) {
+      action();
+      return;
+    }
+    const choice = describeRootChoice(run);
+    if (!choice) {
+      action();
+      return;
+    }
+    const pending: PendingChoice = { query: run.query.trim(), choice };
+    pendingRef.current = pending;
+    const ran = action();
+    if (settledRef.current || pendingRef.current !== pending) return;
+    // Nothing ran, or the row only rewrote the query: the search goes on.
+    if (ran === false || rootQueryRef.current !== run.query) pendingRef.current = null;
+  }, [rootQueryRef]);
+
+  const choose = useCallback((query: string, choice: CommandSearchChoice) => {
+    if (settledRef.current || pendingRef.current) return;
+    pendingRef.current = { query: query.trim(), choice };
+  }, []);
+
+  const finish = useCallback(() => {
+    if (settledRef.current) return;
+    settledRef.current = true;
+    const pending = pendingRef.current;
+    pendingRef.current = null;
+    if (pending) send(pending.query, "chosen", pending.choice);
+  }, [send]);
+
+  const dismiss = useCallback(() => {
+    if (settledRef.current) return;
+    settledRef.current = true;
+    const pending = pendingRef.current;
+    pendingRef.current = null;
+    if (pending) {
+      send(pending.query, "chosen", pending.choice);
+      return;
+    }
+    if (currentRouteRef.current) return;
+    const query = rootQueryRef.current.trim();
+    if (!query || query === initialQueryRef.current.trim()) return;
+    send(query, "dismissed");
+  }, [currentRouteRef, rootQueryRef, send]);
+
+  const settle = useCallback(() => {
+    settledRef.current = true;
+    pendingRef.current = null;
+  }, []);
+
+  // A menu or a key reopening the open bar on new text starts a new visit.
+  const openingQueryRef = useRef(openingQuery);
+  useEffect(() => {
+    if (openingQueryRef.current === openingQuery) return;
+    openingQueryRef.current = openingQuery;
+    if (currentRouteRef.current) return;
+    initialQueryRef.current = openingQuery;
+    settledRef.current = false;
+    pendingRef.current = null;
+  }, [currentRouteRef, openingQuery]);
+
+  // Backing out of the route a root row opened takes that choice back.
+  const routeOpenRef = useRef(routeOpen);
+  useEffect(() => {
+    const wasOpen = routeOpenRef.current;
+    routeOpenRef.current = routeOpen;
+    if (wasOpen && !routeOpen && !settledRef.current) pendingRef.current = null;
+  }, [routeOpen]);
+
+  // The bar unmounts when it closes, whichever way: Esc, the command-bar key
+  // pressed again, or something outside it closing it.
+  useEffect(() => dismiss, [dismiss]);
+
+  return { choose, dismiss, finish, runRootRow, settle };
+}