gloomberb 0.16.0 → 0.16.2

package/src/tickers/search/index.ts

@@ -184,7 +184,7 @@ function createProviderTickerSearchCandidates(
 }
 
 export async function searchTickerCandidates({
-  query,
+  query: rawQuery,
   tickers,
   dataProvider,
   searchContext,
@@ -203,6 +203,7 @@ export async function searchTickerCandidates({
   /** Called when a slower, richer source improves results already returned. */
   onPartial?: (candidates: TickerSearchCandidate[]) => void;
 }): Promise<TickerSearchCandidate[]> {
+  const query = symbolSearchQuery(rawQuery);
   const assemble = (providerResults: InstrumentSearchResult[]) => buildTickerSearchCandidates({
     query,
     tickers,
@@ -261,17 +262,42 @@ interface ResolveTickerSearchOptions {
   searchContext?: SearchRequestContext;
 }
 
+/** `NET:` asks which NET. `NET:N` narrows that list. `NET:XNYS` already names one. */
+const LISTING_PICKER_QUERY = /^[A-Z0-9][A-Z0-9.\-]{0,20}:$/;
+const LISTING_CHOICE_QUERY = /^([A-Z0-9][A-Z0-9.\-]{0,20}):([A-Z0-9.\-]*)$/;
+
+function isListingPickerQuery(query: string): boolean {
+  return LISTING_PICKER_QUERY.test(query.trim().toUpperCase());
+}
+
+/** `NET:` and `NET:N` name a symbol plus the exchange prefix still being typed. */
+export function listingChoiceQuery(query: string): { symbol: string; suffix: string } | null {
+  const match = LISTING_CHOICE_QUERY.exec(query.trim().toUpperCase());
+  if (!match?.[1]) return null;
+  return { symbol: match[1], suffix: match[2] ?? "" };
+}
+
+/** Search text for a ticker query. A trailing colon searches the symbol it qualifies. */
+export function symbolSearchQuery(query: string): string {
+  const trimmed = query.trim();
+  if (!isListingPickerQuery(trimmed)) return trimmed;
+  return trimmed.slice(0, -1).toUpperCase();
+}
+
 export function resolveTickerSearch(options: ResolveTickerSearchOptions): Promise<ResolvedTickerSearch | null> {
-  const symbol = normalizeTickerInput(options.activeTicker, options.query);
-  if (!symbol) return Promise.resolve(null);
-  const literal = resolveTickerSymbol(symbol, options);
-  const alternatives = dottedVenueQueries(symbol);
+  const requested = normalizeTickerInput(options.activeTicker, options.query);
+  if (!requested) return Promise.resolve(null);
+  // `NET:` lists NET's venues instead of settling on one.
+  const pickListing = isListingPickerQuery(requested);
+  const symbol = symbolSearchQuery(requested);
+  const literal = resolveTickerSymbol(symbol, options, pickListing ? requested : null);
+  const alternatives = pickListing ? [] : dottedVenueQueries(symbol);
   // Most input has no venue code to retry: hand back the literal lookup
   // itself, so it settles no later than it did before the retry existed.
   if (alternatives.length === 0) return literal;
   return literal.then(async (resolved) => {
     for (const alternative of resolved ? [] : alternatives) {
-      const match = await resolveTickerSymbol(alternative, options);
+      const match = await resolveTickerSymbol(alternative, options, null);
       if (match) return match;
     }
     return resolved;
@@ -281,6 +307,8 @@ export function resolveTickerSearch(options: ResolveTickerSearchOptions): Promis
 async function resolveTickerSymbol(
   symbol: string,
   { tickers, dataProvider, searchContext }: ResolveTickerSearchOptions,
+  /** The `NET:` text that asked for every venue, or null to settle on one. */
+  pickerQuery: string | null,
 ): Promise<ResolvedTickerSearch | null> {
   const local = tickers.get(symbol)
     ?? findExactTickerSearchMatch(createLocalTickerSearchCandidates(tickers.values()), symbol)?.ticker
@@ -292,8 +320,10 @@ async function resolveTickerSymbol(
     }));
     if (contracts.size > 1) throw new AmbiguousContractError(symbol,
       [...contracts.values()].map((contract) => tickerInstrumentLabel(local.metadata.ticker, contract)));
-    return { kind: "local", symbol: local.metadata.ticker, ticker: local };
   }
+  // A saved symbol keeps its company. The colon still offers the others.
+  const saved: ResolvedTickerSearch | null = local ? { kind: "local", symbol: local.metadata.ticker, ticker: local } : null;
+  if (saved && !pickerQuery) return saved;
 
   const providerItems = createProviderTickerSearchCandidates(
     await searchProviderResults(dataProvider, symbol, searchContext),
@@ -303,13 +333,18 @@ async function resolveTickerSymbol(
   const matches = literalMatches.length ? literalMatches
     : providerItems.filter((item) => findExactTickerSearchMatch([item], symbol));
   let exactMatch = matches[0];
-  if (!exactMatch?.result) return null;
+  if (!exactMatch?.result) return saved;
 
   const contracts = new Set(matches.map((item) => item.contractKey).filter(Boolean));
   if (contracts.size > 1 || (contracts.size && matches.some((item) => !item.contractKey))) {
     throw new AmbiguousContractError(symbol, matches.map((item) => tickerInstrumentLabel(item.symbol, item.result?.brokerContract)));
   }
   const listings = new Set(matches.map((item) => publicTickerKey(item.symbol, listingExchange(item.result!))));
+  const ambiguity = (query: string) => new AmbiguousTickerError(query, [...listings], Object.fromEntries(matches.map((item) => [
+    publicTickerKey(item.symbol, listingExchange(item.result!)), item.result!.name,
+  ])));
+  if (pickerQuery && listings.size > 1) throw ambiguity(pickerQuery);
+  if (saved) return saved;
   if (listings.size > 1 && !parsePublicTickerKey(symbol).exchange && !tickerHasListingSuffix(symbol)) {
     // Search order is relevance, not a canonical listing identifier. Align bare
     // symbols with the quote source only when it supplies the exact identity.
@@ -336,9 +371,7 @@ async function resolveTickerSymbol(
       // An unavailable quote cannot establish the default listing.
     }
     if (new Set(verified.map((item) => publicTickerKey(item.symbol, listingExchange(item.result!)))).size !== 1) {
-      throw new AmbiguousTickerError(symbol, [...listings], Object.fromEntries(matches.map((item) => [
-        publicTickerKey(item.symbol, listingExchange(item.result!)), item.result!.name,
-      ])));
+      throw ambiguity(symbol);
     }
     exactMatch = verified[0]!;
   }

package/src/tickers/search/ranking.ts

@@ -4,7 +4,7 @@ import type {
 } from "./types";
 import { getListingSymbol, tickerHasListingSuffix } from "../../sources/listing-symbols";
 import { canonicalExchange, parsePublicTickerKey } from "../../utils/exchanges";
-import { assetClassMarketSymbol, instrumentClassCode, parseAssetClassQuery } from "./asset-classes";
+import { assetClassKeeps, assetClassMarketSymbol, instrumentClassCode, parseAssetClassQuery } from "./asset-classes";
 
 const FUND_TYPES = new Set(["ETF", "ETN", "ETP", "FUND", "MUTUALFUND", "CEF", "CLOSEDEND"]);
 const DERIVATIVE_TYPES = new Set(["OPT", "OPTION", "OPTIONS", "FUT", "FUTURE", "FUTURES", "WARRANT", "WARRANTS", "RIGHT", "RIGHTS"]);
@@ -174,12 +174,12 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
   if (!intent.normalizedQuery) return items;
 
   const ranked = (assetClass
-    ? items.filter((item) => instrumentClassCode({
+    ? items.filter((item) => assetClassKeeps(assetClass.code, instrumentClassCode({
       instrumentClass: item.instrumentClass,
       instrumentType: item.instrumentType,
       symbol: item.symbol || item.label,
       exchange: item.exchangeLabel || item.right,
-    }) === assetClass.code)
+    })))
     : items)
     .map((item, index) => {
       // A saved public key replaces its provider row during deduplication.
@@ -259,8 +259,28 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
   promoteMuchMorePopularCompanies(filtered);
 
   type RankedEntry = (typeof ranked)[number];
+  // One exact symbol can name several companies (NET is Cloudflare in New York
+  // and Netcall in London). Saved listings come first, then each company ranks
+  // by its earliest listing position in the returned search order.
+  // Without this, a name that starts with the symbol (Netcall) or the boost for
+  // stocks over funds (GLD) put a thinly traded company first.
+  const exactIssuerRank = new Map<string, number>();
+  const exactIssuerKey = (entry: RankedEntry) => getIssuerGroupKey(entry.item.detail) || `item:${entry.index}`;
+  for (const entry of filtered) {
+    if (entry.symbolMatchRank !== 4 || entry.item.providerRank == null) continue;
+    const key = exactIssuerKey(entry);
+    exactIssuerRank.set(key, Math.min(entry.item.providerRank, exactIssuerRank.get(key) ?? Number.POSITIVE_INFINITY));
+  }
   const compareFallbackEntries = (a: RankedEntry, b: RankedEntry): number => {
     if (b.symbolMatchRank !== a.symbolMatchRank) return b.symbolMatchRank - a.symbolMatchRank;
+    if (a.symbolMatchRank === 4) {
+      const aSaved = isSavedSearchItem(a.item);
+      const bSaved = isSavedSearchItem(b.item);
+      if (aSaved !== bSaved) return aSaved ? -1 : 1;
+      const aIssuerRank = exactIssuerRank.get(exactIssuerKey(a)) ?? Number.POSITIVE_INFINITY;
+      const bIssuerRank = exactIssuerRank.get(exactIssuerKey(b)) ?? Number.POSITIVE_INFINITY;
+      if (aIssuerRank !== bIssuerRank) return aIssuerRank - bIssuerRank;
+    }
     if (b.score !== a.score) return b.score - a.score;
     const aSaved = isSavedSearchItem(a.item);
     const bSaved = isSavedSearchItem(b.item);

package/src/time-series/resolve.ts

@@ -1647,7 +1647,7 @@ async function resolveChartSpecPass(
       || (request.bounds.end !== null && now() - (request.bounds.end + 1) < 60 * 60_000);
     const staleCurrent = (value: LoadedPriceHistory) => currentWindow() && !!value.session
       && isPriceHistoryStaleForCurrentWindow(value.points, now(), {
-        exchange: source.instrument.exchange, session: value.session,
+        symbol: source.instrument.symbol, exchange: source.instrument.exchange, session: value.session,
         ...(value.resolution ? { intervalMs: CHART_RESOLUTION_STEP_MS[value.resolution] } : {}),
       });
     if (staleCurrent(loaded)) {

package/src/time-series/use-chart-resolution.ts

@@ -105,7 +105,7 @@ function freshSeedPoints(
   // Broker contract/session interpretation remains unproven, as at acquisition.
   const session = instrument.instrument ? undefined : result.session;
   if (currentWindow && isIntradayResolution(resolution) && isPriceHistoryStaleForCurrentWindow(points, now, {
-    exchange: target.exchange, intervalMs: CHART_RESOLUTION_STEP_MS[resolution], session,
+    symbol: target.symbol, exchange: target.exchange, intervalMs: CHART_RESOLUTION_STEP_MS[resolution], session,
   })) return null;
   return points.length ? points : null;
 }

package/src/types/context-menu.ts

@@ -80,6 +80,12 @@ export type ContextMenuContext =
     layoutIndex: number;
     layoutName: string;
     active: boolean;
+  }
+  | {
+    /** A person's name or @mention in the chat. */
+    kind: "chat-user";
+    userId: string;
+    username: string | null;
   };
 
 export function hasRunnableContextMenuItem(items: readonly ContextMenuItem[]): boolean {

package/src/types/data-provider.ts

@@ -116,6 +116,8 @@ export interface MarketDataRequestContext {
   historyRequestKey?: string;
   /** Intraday history should include pre-market and after-hours bars where the source has them. */
   historySession?: "extended";
+  /** The listing's company, from its own quote: an SEC lookup for a non-US listing checks the registrant against it. */
+  listingName?: string;
 }
 
 export interface CachedFinancialsTarget {

package/src/types/financials.ts

@@ -41,6 +41,8 @@ export interface QuoteMetadata {
 export interface Quote {
   /** Applies to this price observation; a stored position cannot supply it. */
   priceBasis?: PriceBasis;
+  /** Daily fund net asset value; independent of the units used to format its price. */
+  priceObservation?: "nav";
   symbol: string;
   /** Provider-reported security type, independent of the company profile. */
   instrumentType?: string;
@@ -56,6 +58,9 @@ export interface Quote {
   regularClose?: number;
   /** Exchange-local date of regularClose; separate from the daily previous-close reference. */
   regularCloseSessionDate?: string;
+  /** Move of that completed regular session from the one before it, in this quote's currency; set and cleared together with regularClose. */
+  regularChange?: number;
+  regularChangePercent?: number;
   /** Provider's exchange-local session date for the daily quote reference. */
   changeSessionDate?: string;
   high52w?: number;

package/src/types/headless.ts

@@ -71,7 +71,12 @@ export interface HeadlessPaneContext {
   settings?: Record<string, unknown>;
   capabilities?: CapabilityInvoker;
   /** Read one local portfolio without passing holdings through a remote endpoint. */
-  resolvePortfolio?: (id: string) => Promise<{ portfolio: import("./ticker").Portfolio; tickers: import("./ticker").TickerRecord[] } | null>;
+  resolvePortfolio?: (id: string) => Promise<{
+    portfolio: import("./ticker").Portfolio;
+    tickers: import("./ticker").TickerRecord[];
+    /** The broker account the portfolio was last synced with, as saved on this device. */
+    account?: import("./trading").BrokerAccount | null;
+  } | null>;
   /** Read locally remembered watchlist membership. */
   resolveWatchlist?: (id: string) => Promise<import("./ticker").TickerRecord[] | null>;
   /** Resolve locally remembered exchange identities without coupling plugins to storage. */
@@ -97,6 +102,63 @@ export interface HeadlessPaneEntry {
   formatted?: string;
 }
 
+/**
+ * How current a report's data is (docs/usage.md#how-current-a-report-is):
+ * - `live`: a real-time feed, such as a streaming venue or a real-time quote.
+ * - `delayed`: a feed held back on purpose, by `delayMinutes` when known.
+ * - `stale`: a feed or scheduled release whose newest observation is older
+ *   than that kind of data allows.
+ * - `not-a-feed`: data that is not a feed at all (filings, fundamentals,
+ *   calendars, statistics releases, calculators, local portfolio data). It
+ *   never reads stale just because it is old.
+ */
+export type HeadlessFreshnessStatus = "live" | "delayed" | "stale" | "not-a-feed";
+
+/**
+ * What a report can cite about its data. Every field is optional: the report
+ * fills what is missing from the result itself (quote `dataSource`,
+ * `delayMinutes`, `stale`, `asOf`/`observedAt`/`lastUpdated` fields, the last
+ * point of each series), so a pane declares only what that would get wrong.
+ */
+export interface HeadlessPaneFreshness {
+  /**
+   * Who a reader would cite: the venue, exchange or agency for primary data
+   * ("SEC EDGAR", "Hyperliquid"), "Gloom Cloud" for aggregated market data,
+   * "Local data" or "Your inputs". Never a data vendor or an internal provider id.
+   */
+  source?: string;
+  /** Newest observation in the data. A `YYYY-MM-DD` string reads as a date without a time. */
+  asOf?: string | number | Date | null;
+  /** Oldest observation, mentioned when it is far older than `asOf`; `null` when the rows are a history. */
+  oldest?: string | number | Date | null;
+  /**
+   * The row field that says when each row was observed, when it is not one of
+   * the standard names (`asOf`, `observedAt`, `lastUpdated`...). The report is
+   * then dated by that field alone, not by metadata stamps.
+   */
+  observedKey?: string;
+  status?: HeadlessFreshnessStatus;
+  /** How far a delayed feed is held back, in minutes. */
+  delayMinutes?: number;
+  /** What not-a-feed data is, in a few words: "filed data", "monthly release", "your inputs". */
+  basis?: string;
+  /** The newest observation is stale once it is older than this many minutes. */
+  maxAgeMinutes?: number;
+  /**
+   * The rows' and metadata's own `stale` flags mean something other than "this
+   * value is out of date" (a historical marker, a cache state), so the report
+   * judges staleness from the schedule alone.
+   */
+  ignoreStaleFlags?: boolean;
+  /**
+   * `daily`: one observation per US trading day, stale once more than one
+   * completed session has passed after the newest (a day's lag is allowed).
+   */
+  cadence?: "daily";
+  /** The newest observation is stale once this time (the next scheduled release) has passed by a day. */
+  nextExpectedAt?: string | number | Date | null;
+}
+
 interface HeadlessPaneResultBase {
   /** False when usable output does not fully cover the requested inputs/depth. */
   complete?: boolean;
@@ -104,8 +166,17 @@ interface HeadlessPaneResultBase {
   symbols?: string[];
   /** Missing inputs must remain visible even when other inputs returned rows. */
   unavailableSymbols?: string[];
+  /** Failures: a source that did not answer, or a value that could not be computed. */
   errors?: string[];
+  /**
+   * Caveats about a report that did load: what it leaves out, what it assumes,
+   * how a value was marked. One sentence each. They never make a report fail;
+   * `complete: false` says when the report does not cover what was asked.
+   */
+  notes?: string[];
   metadata?: Record<string, unknown>;
+  /** What this load knows about its data's source and age; overrides the definition's `freshness`. */
+  freshness?: HeadlessPaneFreshness;
 }
 
 export interface HeadlessRowsResult extends HeadlessPaneResultBase {
@@ -185,8 +256,14 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
   description?: string;
   argument: HeadlessPaneArgumentDef;
   options: HeadlessPaneOptionDef[];
+  /** What is true of every load: its source, and whether it is a feed. */
+  freshness?: HeadlessPaneFreshness;
   columns?: HeadlessPaneColumn[];
-  describe?: string | ((args: HeadlessPaneLoadArgs) => string);
+  /**
+   * The report title. A report passes the loaded result, so a title can name
+   * what the load resolved (the view an `auto` query became, a fund's name).
+   */
+  describe?: string | ((args: HeadlessPaneLoadArgs, result?: HeadlessPaneResult) => string);
   load(
     args: HeadlessPaneLoadArgs,
     ctx: HeadlessPaneContext,

package/src/types/plugin.ts

@@ -1,10 +1,11 @@
 import type { ReactNode } from "react";
 import type { AppTickerRepositoryPort } from "../core/app-service-ports";
-import type { HeadlessPaneDefinition } from "./headless";
+import type { HeadlessPaneDefinition, HeadlessPaneFreshness } from "./headless";
 
 export type {
   HeadlessBundleResult,
   HeadlessBundleSection,
+  HeadlessFreshnessStatus,
   HeadlessPaneApiClient,
   HeadlessPaneArgumentDef,
   HeadlessPaneArgumentKind,
@@ -12,6 +13,7 @@ export type {
   HeadlessPaneContext,
   HeadlessPaneDefinition,
   HeadlessPaneEntry,
+  HeadlessPaneFreshness,
   HeadlessPaneLoadArgs,
   HeadlessPaneOptionDef,
   HeadlessPaneOptionType,
@@ -116,27 +118,48 @@ export interface PaneDef {
   tickerSource?: boolean;
   /**
    * Pane shows one ticker read through its binding (`usePaneTicker`, `usePaneTickerIdentity`), so
-   * its pane menu offers "Link to" each visible `tickerSource` pane and it then follows that pane's
-   * selection. A function decides per instance (a chart with one security, not a comparison). A
-   * follower must never write its own `cursorSymbol`: that would win over the binding.
+   * its pane menu offers "Link to" each visible list, scanner, and other single-ticker pane, and
+   * it then follows that pane's selection. A function decides per instance (a chart with one
+   * security, not a comparison). A follower must never write its own `cursorSymbol`: that would
+   * win over the binding.
    */
   tickerFollower?: boolean | ((pane: PaneInstanceConfig) => boolean);
   /** Renderer-neutral data model used by CLI functions, automation, and hosted tools. */
   headless?: HeadlessPaneDefinition;
+  /**
+   * Source and status a rendered-view report (`fn` on a pane without a
+   * `headless` model) cites, when "Gloom Cloud" with the state the footer
+   * shows would be wrong: local data, a calculator, filed records.
+   */
+  reportFreshness?: Pick<HeadlessPaneFreshness, "source" | "status" | "basis">;
   /** Add an Excel-compatible CSV action for the pane's single active DataTable. */
   tableExport?: true;
   settings?: PaneSettingsDef | ((context: PaneSettingsContext) => PaneSettingsDef | null);
   /** Portable sharing is public by default; list the few pane-owned fields that must remain local. */
   portableShare?: PanePortableShareDef;
-  /** Compact controls surfaced next to the pane title. Toggle keys reference toggle fields in settings. */
+  /**
+   * Compact controls surfaced next to the pane title. A key references a
+   * toggle field in settings, or a two-option select field when `onValue` is set.
+   */
   quickSettings?: readonly PaneQuickSettingDef[];
 }
 
 export interface PaneQuickSettingDef {
   type: "toggle";
   key: string;
-  icon: "zap";
+  icon: "zap" | "sqrt";
   label?: string;
+  /**
+   * For a two-option select field: the option the control turns on. Turning
+   * it off picks the field's other option.
+   */
+  onValue?: string;
+  /**
+   * Shows the control only where it changes something, for a setting that
+   * applies to some of what the pane can show. The field stays in the
+   * settings dialog either way.
+   */
+  visible?: (context: PaneSettingsContext) => boolean;
 }
 
 export interface PaneSettingsContext {
@@ -183,11 +206,15 @@ interface PaneSettingSelectField extends PaneSettingFieldBase {
 interface PaneSettingMultiSelectField extends PaneSettingFieldBase {
   type: "multi-select";
   options: PaneSettingOption[];
+  /** A long list: a filter box, each description beside its label. */
+  searchable?: boolean;
 }
 
 interface PaneSettingOrderedMultiSelectField extends PaneSettingFieldBase {
   type: "ordered-multi-select";
   options: PaneSettingOption[];
+  /** A long list: a filter box, each description beside its label and each selection's position. */
+  searchable?: boolean;
 }
 
 export interface PaneSettingActionContext extends PaneSettingsContext {
@@ -251,6 +278,11 @@ interface PaneTemplateShortcut {
   aliases?: readonly string[];
   argPlaceholder?: string;
   argKind?: "text" | "ticker" | "ticker-list";
+  /**
+   * For a ticker list, entries kept as typed instead of resolved as tickers:
+   * CORR keeps map series (`GEO:HORMUZ`) beside its tickers.
+   */
+  keepArgToken?: (token: string) => boolean;
   argOptional?: boolean;
   /**
    * With no argument typed and none to infer from the active ticker, open

package/src/types/ticker.ts

@@ -56,6 +56,21 @@ export interface Portfolio {
   lastSyncedAt?: number;
   /** Set on paper portfolios shared with a team; the server holds the items. */
   teamId?: string;
+  /**
+   * Cash held beside the positions, entered by hand. A broker account that
+   * reports its own cash is shown instead of this.
+   */
+  cash?: PortfolioCash;
+  /**
+   * Target weights in percent of the total value, cash included, keyed by
+   * ticker symbol; `CASH` is the cash line.
+   */
+  targetWeights?: Record<string, number>;
+}
+
+export interface PortfolioCash {
+  amount: number;
+  currency: string;
 }
 
 export interface Watchlist {

package/src/ui/context-menu.tsx

@@ -42,6 +42,7 @@ const MENU_SURFACE_SELECTOR = [
   "[data-gloom-role='pane-header']",
   "[data-gloom-role='pane-action']",
   "[data-gloom-role='pane-close']",
+  "[data-gloom-role='pane-restore']",
   "[data-gloom-role='status-bar']",
   "[data-gloom-role='tab-button']",
 ].join(", ");

package/src/ui/host.tsx

@@ -375,6 +375,8 @@ export interface HostTabsProps {
   addLabel?: string;
   onAdd?: () => void;
   onReorder?: (fromValue: string, toValue: string) => void;
+  /** A press that moves, on a tab that is not reordered. */
+  onDrag?: () => void;
   focused?: boolean;
   palette: HostTabsPalette;
 }
@@ -459,6 +461,20 @@ export interface HostPopoverProps {
   trigger: ReactNode;
   children: ReactNode;
   anchorPoint?: { x: number; y: number } | null;
+  /**
+   * Opens beside this element instead of the trigger, such as a name the
+   * pointer is on: below it with the left edges aligned, above it when there
+   * is no room below, and kept inside the boundary. A Box ref is one. Read
+   * each time the popover places itself, so it follows the element when the
+   * page scrolls.
+   */
+  anchor?: BoxRenderable | null;
+  /** `pane` also keeps the popover inside the pane it opens from. Default `viewport`. */
+  boundary?: "viewport" | "pane";
+  /** The pointer came onto the popover, e.g. to keep a hover card open while it is used. */
+  onPointerEnter?: () => void;
+  /** The pointer left the popover. */
+  onPointerLeave?: () => void;
   placement?: "bottom-start" | "bottom-end";
   minWidth?: number | string;
   maxWidth?: number | string;

package/src/updater/index.ts

@@ -1,7 +1,7 @@
 import { compareSemver } from "../utils/semver";
 import { GITHUB_LATEST_RELEASE_API_URL } from "./github-releases";
 
-function getRuntimeProcess(): Pick<NodeJS.Process, "platform" | "arch" | "argv" | "execPath"> | null {
+function getRuntimeProcess(): Pick<NodeJS.Process, "platform" | "arch" | "argv" | "execPath" | "getBuiltinModule"> | null {
   return (globalThis as { process?: NodeJS.Process }).process ?? null;
 }
 
@@ -17,10 +17,18 @@ export interface ReleaseInfo {
 }
 
 export interface UpdateProgress {
-  phase: "downloading" | "replacing" | "done" | "error";
+  /**
+   * `ready`: the new version is downloaded and waiting. The terminal binary is
+   * already swapped and runs on the next launch; the desktop app applies it
+   * when `canRestart` is set and the user asks. Nothing restarts by itself.
+   * `done` is for a finished action that has nothing left to wait for.
+   */
+  phase: "downloading" | "ready" | "replacing" | "done" | "error";
   percent?: number;
   error?: string;
   message?: string;
+  /** With `ready`: this host can apply the update and relaunch on request. */
+  canRestart?: boolean;
 }
 
 export type UpdateAction =
@@ -43,7 +51,10 @@ export type UpdateCheckResult =
 
 export interface UpdateHost {
   checkForUpdateDetailed(currentVersion: string): Promise<UpdateCheckResult>;
+  /** Downloads and stages the update, ending in `ready` (or `error`). It never relaunches the app. */
   performUpdate(release: ReleaseInfo, onProgress: (p: UpdateProgress) => void): Promise<void>;
+  /** Installs the staged update and relaunches the app. Only runs on an explicit request. */
+  applyUpdate?(onProgress: (p: UpdateProgress) => void): Promise<void>;
 }
 
 let updateHost: UpdateHost | null = null;
@@ -255,6 +266,11 @@ export function canSelfUpdate(release: Pick<ReleaseInfo, "updateAction"> | null
   return release?.updateAction.kind === "self" || release?.updateAction.kind === "desktop";
 }
 
+/** A downloaded update this host can install and relaunch into when the user asks. */
+export function canRestartToApply(progress: UpdateProgress | null | undefined): boolean {
+  return progress?.phase === "ready" && progress.canRestart === true;
+}
+
 export async function checkForUpdateDetailed(
   currentVersion: string,
 ): Promise<UpdateCheckResult> {
@@ -339,6 +355,15 @@ export async function checkForUpdate(
   return result.kind === "available" ? result.release : null;
 }
 
+/** Installs the downloaded update and relaunches. Callers gate it on `canRestartToApply`. */
+export async function applyUpdate(onProgress: (p: UpdateProgress) => void): Promise<void> {
+  if (!updateHost?.applyUpdate) {
+    onProgress({ phase: "error", error: "Restarting to apply an update is unavailable in this runtime." });
+    return;
+  }
+  await updateHost.applyUpdate(onProgress);
+}
+
 export async function performUpdate(
   release: ReleaseInfo,
   onProgress: (p: UpdateProgress) => void,
@@ -389,17 +414,15 @@ export async function performUpdate(
   let unlinkUpdatePath: ((path: string) => void) | null = null;
 
   try {
-    const fsModulePath = "fs";
-    const zlibModulePath = "zlib";
-    const cryptoModulePath = "crypto";
-    const {
-      renameSync,
-      unlinkSync,
-      chmodSync,
-    } = await import(fsModulePath) as typeof import("fs");
+    // Not import(): Bun folds even a specifier held in a variable and bundles
+    // browser polyfills for all three into the web and desktop view builds,
+    // which never reach this path. Self-update only runs in the compiled
+    // terminal binary, where the process is always there.
+    const runtime = getRuntimeProcess()!;
+    const { renameSync, unlinkSync, chmodSync } = runtime.getBuiltinModule("fs");
     unlinkUpdatePath = unlinkSync;
-    const { gunzipSync } = await import(zlibModulePath) as typeof import("zlib");
-    const { createHash } = await import(cryptoModulePath) as typeof import("crypto");
+    const { gunzipSync } = runtime.getBuiltinModule("zlib");
+    const { createHash } = runtime.getBuiltinModule("crypto");
 
     onProgress({ phase: "downloading", percent: 0 });
 
@@ -458,7 +481,9 @@ export async function performUpdate(
       unlinkSync(oldPath);
     } catch {}
 
-    onProgress({ phase: "done" });
+    // The new binary is in place; the running process keeps the old one until
+    // the user restarts it, which this process never does for them.
+    onProgress({ phase: "ready" });
   } catch (err: unknown) {
     // Clean up temp file on failure
     try {

package/src/utils/async-deadline.ts

@@ -58,3 +58,24 @@ export function abortable<T>(promise: Promise<T>, signal: AbortSignal | undefine
     promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
   });
 }
+
+/**
+ * Aborts when the caller's signal does or after `timeoutMs`, whichever comes
+ * first, with that signal's reason. Wired by hand because AbortSignal.any is
+ * missing from the older system WebViews the desktop app runs in.
+ */
+export function signalWithTimeout(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  if (!signal) return timeout;
+  if (signal.aborted) return signal;
+  const controller = new AbortController();
+  const fromCaller = () => controller.abort(signal.reason);
+  const fromTimeout = () => controller.abort(timeout.reason);
+  signal.addEventListener("abort", fromCaller, { once: true });
+  timeout.addEventListener("abort", fromTimeout, { once: true });
+  controller.signal.addEventListener("abort", () => {
+    signal.removeEventListener("abort", fromCaller);
+    timeout.removeEventListener("abort", fromTimeout);
+  }, { once: true });
+  return controller.signal;
+}

package/src/utils/cli-output.ts

@@ -8,6 +8,8 @@ export interface CliTableColumn {
   maxWidth?: number;
   /** Dropped, rightmost first, before other columns are shortened to fit a terminal. */
   optional?: boolean;
+  /** Among optional columns, a higher priority is dropped sooner; equal ones go rightmost first. */
+  dropPriority?: number;
   /** False keeps the column whole when fitting, for identifiers a user types into the next command. */
   shrink?: boolean;
 }
@@ -301,7 +303,9 @@ export function renderTable(columns: CliTableColumn[], rows: string[][], options
   let truncate = false;
   if (available != null && tableWidth(shown.map((entry) => entry.width)) > available) {
     while (tableWidth(shown.map((entry) => entry.width)) > available) {
-      const dropped = shown.findLast((entry) => entry.column.optional);
+      const dropped = shown.reduce<(typeof shown)[number] | undefined>((pick, entry) => (
+        entry.column.optional && (!pick || (entry.column.dropPriority ?? 0) >= (pick.column.dropPriority ?? 0)) ? entry : pick
+      ), undefined);
       if (!dropped) break;
       shown = shown.filter((entry) => entry !== dropped);
     }