@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/plugins/builtin/perps/index.tsx

@@ -2,7 +2,7 @@ import type { PaneTemplateInstanceConfig } from "../../../types/plugin";
 import type { PluginModule } from "../plugin-module";
 import { commandRequestParams } from "../shared/command-tab";
 import { PERP_SERIES } from "./series";
-import { perpsCache, perpsHistoryCache, perpsListCache, perpsMarketCache, perpsRankingsCache } from "./client";
+import { perpsCache, perpsDepthCache, perpsHistoryCache, perpsLiquidationsCache, perpsListCache, perpsMarketCache, perpsRankingsCache } from "./client";
 import { perpsHeadless } from "./headless";
 import { PerpsPane } from "./pane";
 
@@ -18,16 +18,18 @@ export function perpsInstance(arg: string | undefined): PaneTemplateInstanceConf
     settings: { market }, params: commandRequestParams({ market }) };
 }
 
+const PERP_CACHES = [perpsCache, perpsHistoryCache, perpsListCache, perpsMarketCache, perpsRankingsCache, perpsLiquidationsCache, perpsDepthCache] as const;
+
 export const perpsModule: PluginModule = {
   series: PERP_SERIES,
   panes: [{ id: "perps", name: "Perpetuals", icon: "P", component: PerpsPane, defaultPosition: "right", defaultMode: "floating",
     defaultFloatingSize: { width: 138, height: 34 }, tableExport: true, headless: perpsHeadless }],
-  paneTemplates: [{ id: "perps-pane", paneId: "perps", label: "Perpetuals", description: "Perpetual funding, open interest and premiums by market and venue, with rankings, a venue comparison and Pro history.",
-    keywords: ["perp", "perpetual", "perpetuals", "funding", "funding rate", "open interest", "hip-3", "stock perps", "basis", "basis trade", "carry", "venue", "funding spread", "long short ratio", "long/short", "positioning"],
+  paneTemplates: [{ id: "perps-pane", paneId: "perps", label: "Perpetuals", description: "Perpetual funding, open interest and premiums by market and venue, with rankings, a venue comparison, liquidations, order book depth and Pro history.",
+    keywords: ["perp", "perpetual", "perpetuals", "funding", "funding rate", "open interest", "hip-3", "stock perps", "basis", "basis trade", "carry", "venue", "funding spread", "long short ratio", "long/short", "positioning", "liquidations", "liquidation", "order book depth", "market depth", "liquidity"],
     shortcut: { prefix: "PERP", argKind: "text", argOptional: true, argPlaceholder: "market" }, headless: perpsHeadless,
     createInstance: (_ctx, options) => perpsInstance(options?.arg) }],
   setup(ctx) {
-    for (const cache of [perpsCache, perpsHistoryCache, perpsListCache, perpsMarketCache, perpsRankingsCache]) cache.attach(ctx.persistence);
+    for (const cache of PERP_CACHES) cache.attach(ctx.persistence);
   },
-  dispose() { for (const cache of [perpsCache, perpsHistoryCache, perpsListCache, perpsMarketCache, perpsRankingsCache]) cache.reset(); },
+  dispose() { for (const cache of PERP_CACHES) cache.reset(); },
 };

package/src/plugins/builtin/perps/model.ts

@@ -6,14 +6,28 @@ import { formatCompact } from "../../../utils/format";
 import { isUsListingExchange, publicTickerKey } from "../../../utils/exchanges";
 import { isRecord } from "../../../utils/guards";
 import type { ThemeColors } from "../../../theme/colors";
-export const PERP_TABS = ["board", "rankings", "compare", "history", "evidence"] as const;
+export const PERP_TABS = ["board", "rankings", "compare", "liquidations", "depth", "history", "evidence"] as const;
 export type PerpTab = typeof PERP_TABS[number];
 /** One market's tabs; the others list many markets. */
 export const isMarketTab = (tab: string) => tab === "history" || tab === "evidence";
-/** A named market opens its history; nothing named opens the board. */
-export const openingTab = (market: string | null | undefined): PerpTab => market?.trim() ? "history" : "board";
+/** One base asset's tabs, across its contracts on every venue; they share the asset. */
+export const isAssetTab = (tab: string) => tab === "compare" || tab === "liquidations" || tab === "depth";
+/**
+ * A named market opens its history, or its latest values (Evidence) where history is Pro's, so a free account
+ * lands on the figures it has and not on a lock; nothing named opens the board.
+ */
+export const openingTab = (market: string | null | undefined, pro = true): PerpTab => market?.trim() ? pro ? "history" : "evidence" : "board";
 export const ASSET_FILTERS = ["all", "stocks", "indices", "energy", "metals", "fx", "crypto"] as const;
-export const VENUES = ["hyperliquid", "binance", "bybit", "okx", "deribit", "coinbase", "kraken", "dydx"] as const;
+/** The venues Gloom collects perpetuals from: what the venue filter and `--venue` take. */
+export const VENUES = ["hyperliquid", "binance", "bybit", "okx"] as const;
+/** Every venue a market identity can name (`kraken:PF_XBTUSD`), collected or not. */
+export const IDENTITY_VENUES = [...VENUES, "deribit", "coinbase", "kraken", "dydx"] as const;
+/** What `--venue` says of a venue Gloom does not collect yet; null for a covered venue and for any other word. */
+export function uncoveredVenueNote(venue: string): string | null {
+  const id = venue.trim().toLowerCase();
+  return (IDENTITY_VENUES as readonly string[]).includes(id) && !(VENUES as readonly string[]).includes(id)
+    ? `Gloom doesn't cover ${venueName(id)} perps yet.` : null;
+}
 export const BOARD_SORTS = ["oi", "funding", "oi-change", "premium", "long-short"] as const;
 export const sortLabel = (sort: string) => ({ oi: "OI", funding: "Funding", "oi-change": "OI change", premium: "Premium", "long-short": "Long %" })[sort] ?? sort;
 export const label = (s: string) => s === "fx" ? "FX" : s.charAt(0).toUpperCase() + s.slice(1);

package/src/plugins/builtin/perps/pane.tsx

@@ -5,13 +5,10 @@ import type { PerpBoardRow, PerpMarketPayload } from "../../../api-client/perps"
 import { buildSectionedRows, ChartTableHeader, DataTableView, EmptyState, KeyValueRow, SectionHeading, PaneStatusBody, QueryBar, StatGrid, useChartTableSelection,
   usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, useQueryBarSearch, type DataTableCell, type KeyValueRowProps, type PaneFooterSegment, type PaneHint, type SectionedRow,
   type StatItem } from "../../../components";
-import { deriveHeadlessFreshness, paneStatusLineVariants } from "../../../cli/pane-functions/freshness";
 import { openFormModal } from "../../../components/form-modal";
 import { tf } from "../../../i18n";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePaneTitle, usePluginAppActions, usePluginPaneState } from "../../../public/react";
-import { useAgeClock } from "../../../react/auto-refresh";
-import { useRemoteUiNode } from "../../../remote/semantic-tree";
 import { useThemeColors } from "../../../theme/theme-context";
 import type { PaneProps } from "../../../types/plugin";
 import { Box, ScrollBox, useRendererHost, useUiCapabilities } from "../../../ui";
@@ -25,9 +22,11 @@ import { isCloudSessionRequired, useResearchCloudSession } from "../shared/resea
 import { boardSearchText, cachedPerpSelection, cachedPerpsBoard, cachedPerpsCompare, cachedPerpsRankings, loadPerpSelection, loadPerpsBoard, loadPerpsCompare,
   loadPerpsHistoryForRange, loadPerpsRankings } from "./client";
 import { perpFreshness } from "./freshness";
+import { Depth, Liquidations } from "./cascade-tabs";
+import { useFreshnessStatusLine } from "./status-line";
 import { useLivePerpRows, useLivePerpTableRows } from "./live-rows";
 import { aprFormula, ASSET_FILTERS, BOARD_SORTS, boardColumns, collectedVenueCount, compact, compareColumns, dayChange, fundingInterval, fundingSpread, historyCaption, historyCell, historyChange, historyColumns,
-  HISTORY_METRICS, historyRows, historySeries, historyValue, inPoints, isMarketTab, label, longShortReason, marketLabel, metricLabel, openingTab, perpCell, perpHistoryProText, PERP_TABS, percent,
+  HISTORY_METRICS, historyRows, historySeries, historyValue, inPoints, isAssetTab, isMarketTab, label, longShortReason, marketLabel, metricLabel, openingTab, perpCell, perpHistoryProText, PERP_TABS, percent,
   positioningFields, price, rankingColumns, rankingRows, RANKINGS, ratioText, share, sortLabel, time, underlyingTicker, venueLabel, venueName, venuesOf, type HistoryMetric,
   type PerpColumnId, type PerpTab, type RankingKey } from "./model";
 
@@ -45,17 +44,8 @@ const withRankedRow = (entry: SectionedRow<Ranked>, row: PerpBoardRow): Sectione
  * same way.
  */
 function usePerpStatusLine(rows: readonly PerpBoardRow[], funding: readonly PerpBoardRow[], since: number | null, live = false): PaneFooterSegment[] {
-  const now = useAgeClock(since);
-  const declared = useMemo(() => rows.length ? perpFreshness(rows, { funding, now, live }) : null, [rows, funding, now, live]);
-  useRemoteUiNode(declared ? { role: "report-freshness", label: "Venue freshness", getMetadata: () => ({ ...declared }) } : null);
-  return useMemo(() => {
-    if (!declared) return [];
-    const freshness = deriveHeadlessFreshness({ shape: "rows" }, { rows: [], freshness: declared }, now);
-    const tone = freshness.status === "stale" ? "warning" as const : "muted" as const;
-    // A footer too narrow beside its keys gives up the funding part before any venue's time.
-    const [line, ...shorter] = paneStatusLineVariants(freshness).map((text) => [{ text, tone }]);
-    return [{ id: "perp-freshness", asOf: true, parts: line!, variants: shorter }];
-  }, [declared, rows, now]);
+  const declare = useCallback((now: number) => rows.length ? perpFreshness(rows, { funding, now, live }) : null, [rows, funding, live]);
+  return useFreshnessStatusLine(declare, since);
 }
 
 type EvidenceField = [label: string, value: string, detail?: string, link?: KeyValueRowProps["link"]];
@@ -378,11 +368,12 @@ export function PerpsPane({ width, height, focused, marketAction }: Pick<PanePro
   const openDescription = useOpenDescription();
   const upgrade = useCloudUpgradeAction("perp");
   const [openingMarket] = usePaneSettingValue("market", "");
-  const [openingTabValue] = usePaneSettingValue("tab", openingTab(openingMarket));
+  const opening = openingTab(openingMarket, access.hasProAccess);
+  const [openingTabValue] = usePaneSettingValue("tab", opening);
   // A market asked for again (a stock's perpetual row, PERP) comes back to it on its opening tab, whatever this pane
   // shows by then.
   const [savedTab, setTab] = useCommandValue<string>("perps", "perps:tab", (params) => params.market ? openingTabValue : null, openingTabValue);
-  const tab = PERP_TABS.includes(savedTab as PerpTab) ? savedTab as PerpTab : openingTab(openingMarket);
+  const tab = PERP_TABS.includes(savedTab as PerpTab) ? savedTab as PerpTab : opening;
   const marketTab = isMarketTab(tab);
   const [search, setSearch] = useCommandValue("perps", "perps:search", (params) => params.market || null, openingMarket);
   const [compareAsset, setCompareAsset] = usePluginPaneState<string>("perps:compare", compareOpening(openingMarket));
@@ -409,13 +400,17 @@ export function PerpsPane({ width, height, focused, marketAction }: Pick<PanePro
   // The market on screen goes with the user: History and Evidence open the row picked on a list, Compare its base asset.
   const current = marketTab ? active : listRow;
   const carried = marketTab ? active : listRow ?? picked;
+  // Liquidations and Depth list no board rows: a market tab after them opens their asset, and they keep Compare's.
+  const assetOnly = tab === "liquidations" || tab === "depth";
   const selectTab = useCallback((next: string) => {
-    if (carried && isMarketTab(next) && !marketTab) setSearch(carried.marketId);
-    if (carried && next === "compare") setCompareAsset(carried.baseAsset);
+    if (assetOnly && isMarketTab(next)) setSearch(compareAsset);
+    else if (carried && isMarketTab(next) && !marketTab) setSearch(carried.marketId);
+    if (carried && isAssetTab(next) && !assetOnly) setCompareAsset(carried.baseAsset);
     setListRow(null);
     setTab(next);
-  }, [carried, marketTab, setSearch, setCompareAsset, setTab]);
-  const openMarket = useCallback((row: PerpBoardRow, next: PerpTab = "history") => { setSearch(row.marketId); setTab(next); }, [setSearch, setTab]);
+  }, [assetOnly, carried, compareAsset, marketTab, setSearch, setCompareAsset, setTab]);
+  const openMarket = useCallback((row: PerpBoardRow, next: PerpTab = openingTab(row.marketId, access.hasProAccess)) => { setSearch(row.marketId); setTab(next); }, [setSearch, setTab, access.hasProAccess]);
+  const openMarketId = useCallback((marketId: string) => { setSearch(marketId); setTab(openingTab(marketId, access.hasProAccess)); }, [setSearch, setTab, access.hasProAccess]);
   const { strip, rows: tabRows } = usePaneTabs({ tabs: PERP_TABS.map((value) => ({ value, label: label(value) })), activeValue: tab, onSelect: selectTab, focused, dense: true });
   const refreshMarket = useCallback(() => { void resource.reload(); }, [resource.reload]);
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
@@ -450,7 +445,9 @@ export function PerpsPane({ width, height, focused, marketAction }: Pick<PanePro
   return <Box width={width} height={height} flexDirection="column">
     {strip}
     {tab === "board" ? <Board {...list} /> : tab === "rankings" ? <Rankings {...list} />
-      : tab === "compare" ? <Compare {...list} asset={compareAsset} onAssetChange={setCompareAsset} /> : <>
+      : tab === "compare" ? <Compare {...list} asset={compareAsset} onAssetChange={setCompareAsset} />
+      : tab === "liquidations" ? <Liquidations accessKey={accessKey} width={width} height={listHeight} focused={focused} asset={compareAsset} onAssetChange={setCompareAsset} onOpenMarket={openMarketId} />
+      : tab === "depth" ? <Depth accessKey={accessKey} width={width} height={listHeight} focused={focused} asset={compareAsset} onAssetChange={setCompareAsset} onOpenMarket={openMarketId} /> : <>
         <QueryBar width={width} search={{ focused, value: search, onChange: setSearch, placeholder: "Market or canonical identity", debounceMs: 300, ...querySearch.searchProps }}
           filters={tab === "history" ? [
             { id: "metric", label: "Series", value: metric, options: HISTORY_METRICS.map((value) => ({ value, label: metricLabel(value) })), onChange: setMetric },

package/src/plugins/builtin/perps/status-line.ts

@@ -0,0 +1,25 @@
+import { useMemo } from "react";
+import { deriveHeadlessFreshness, paneStatusLineVariants } from "../../../cli/pane-functions/freshness";
+import type { PaneFooterSegment } from "../../../components";
+import { useAgeClock } from "../../../react/auto-refresh";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
+import type { HeadlessPaneFreshness } from "../../../types/headless";
+
+/**
+ * The footer line a tab ends with, from the same freshness its text report declares (`declare`, null while there is
+ * nothing to date): the source, its time and how old it is, the line `fn PERP` and `shot PERP` end with. It keeps ageing
+ * while the pane is seen (`since` is when the data loaded), and is published for a capture to date itself the same way.
+ */
+export function useFreshnessStatusLine(declare: ((now: number) => HeadlessPaneFreshness | null) | null, since: number | null): PaneFooterSegment[] {
+  const now = useAgeClock(since);
+  const declared = useMemo(() => declare?.(now) ?? null, [declare, now]);
+  useRemoteUiNode(declared ? { role: "report-freshness", label: "Venue freshness", getMetadata: () => ({ ...declared }) } : null);
+  return useMemo(() => {
+    if (!declared) return [];
+    const freshness = deriveHeadlessFreshness({ shape: "rows" }, { rows: [], freshness: declared }, now);
+    const tone = freshness.status === "stale" ? "warning" as const : "muted" as const;
+    // A footer too narrow beside its keys gives up the note before any venue's time.
+    const [line, ...shorter] = paneStatusLineVariants(freshness).map((text) => [{ text, tone }]);
+    return [{ id: "perp-freshness", asOf: true, parts: line!, variants: shorter }];
+  }, [declared, now]);
+}

package/src/plugins/builtin/plugin-module.ts

@@ -161,7 +161,11 @@ export function composeBuiltinPlugin(options: CompositePluginOptions): GloomPlug
       for (const module of modules) {
         startedModules.push(module);
         try {
-          await module.setup?.(ctx);
+          // Only an async setup is waited for. Awaiting a synchronous one hands
+          // the tick to the panes first: Gloom Cloud restores the saved session
+          // in its second module, and the panes' first requests went out without it.
+          const pending = module.setup?.(ctx);
+          if (pending) await pending;
         } catch (error) {
           // Logged as the plugin, so the failure counts toward its health.
           ctx.log.error("Module setup failed", { error: error instanceof Error ? error.message : String(error) });

package/src/plugins/builtin/portfolio-list/cached-account.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { peekPersistedBrokerAccounts } from "../../../brokers/account-cache";
 import type { AppResourceStorePort } from "../../../core/app-service-ports";
 import type { AppConfig } from "../../../types/config";
@@ -20,8 +21,9 @@ export function peekCachedBrokerAccounts(
     try {
       const accounts = peekPersistedBrokerAccounts(resources, instance);
       if (accounts?.length) brokerAccounts[instance.id] = accounts;
-    } catch {
+    } catch (error) {
       // An unreadable snapshot leaves the portfolio without account figures.
+      logFailure("portfolio-list.cached-account", "Read cached broker accounts failed")(error);
     }
   }
   return brokerAccounts;

package/src/plugins/builtin/portfolio-list/cli/bulk-symbols.ts

@@ -8,6 +8,7 @@ import { splitSymbolArgs, splitSymbolWords, symbolInputKey } from "../../../../c
 import { notASymbolError } from "../../../../cli/symbol-cells";
 import { readSymbolList, SymbolListError } from "../../../../cli/symbol-list";
 import { cliStyles } from "../../../../utils/cli-output";
+import { shellWord } from "../../../../utils/shell-word";
 import { dryRunNote } from "../../../../cli/helpers";
 import {
   addSymbol,
@@ -46,14 +47,7 @@ export const SYMBOL_LIST_HELP = {
   ],
 };
 
-/**
- * One word of a command line as a shell reads it back: as written when it
- * holds nothing a shell treats specially (`NVDA`, `SAN:EPA`, `BRK.B`), else
- * in single quotes (`'Altria Group'`, `'$nvda'`, `'AT&T'`).
- */
-export function shellWord(word: string): string {
-  return /^[\p{L}\p{N}._:@%+,/][\p{L}\p{N}._:@%+,/=-]*$/u.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
-}
+export { shellWord };
 
 /**
  * A row's line, and under it the listing a company's name was read as, the

package/src/plugins/builtin/portfolio-list/cli/portfolio-command.ts

@@ -50,7 +50,7 @@ import { importSource, notionalPositions, rankThirteenFLines, type ThirteenFImpo
 import { importedFromText } from "../imported-from";
 import { savedListingCoinNote } from "../../../../cli/commands/crypto-hints";
 import { findNamedCollection } from "../../../../portfolio/collection-name";
-import { wholeUnitQuantityProblem } from "../../../../portfolio/position-quantity";
+import { ambiguousQuantityProblem } from "../../../../portfolio/position-quantity";
 import {
   CLI_COST_FX_WORDING, loadPurchaseDateCostFx, readCostFxRate, readPurchaseDate, resolvePositionCostFx, type CostFxHistoryClient,
 } from "../../../../portfolio/cost-fx";
@@ -363,8 +363,8 @@ async function setPositionCommand(
       const avgCost = parseAmountArg(avgCostValue, "Average cost");
       // The notes say which listing a bare symbol went to, and that a bare coin ticker is not the coin, as `portfolio add` does.
       const { ticker, notes } = await resolveCliTicker(symbol, store, dataProvider, exchange);
-      // `1.250` on a listing held in whole lots asks which was meant, as `1,250` did above.
-      const lots = wholeUnitQuantityProblem(sharesValue, ticker, { listing: savedListingName(ticker).key });
+      // `1.250` and `1.000` ask which was meant, as `1,250` did above: a dot before three digits is as often thousands.
+      const lots = ambiguousQuantityProblem(sharesValue, ticker, { listing: savedListingName(ticker).key });
       if (lots) throw new PortfolioCliError(lots);
       // A future is held in contracts of the size its terms give, as `quote` states it, and a cost typed as
       // corn is quoted counts cents.
@@ -942,7 +942,7 @@ const AMOUNTS_HELP = {
   lines: [
     "Numbers take either decimal mark: 1.234,5, 1234,5 and 1,234.5 are 1234.5, and 18,50 is 18.5.",
     "Cash and --notional are amounts of a currency (cash in the portfolio's unless named, --notional in USD), so 500,000 and 1.234 are thousands, a third decimal being below a cent. In a currency with three decimals (KWD, BHD, OMR) they could be either, and the command asks which.",
-    "Shares, contracts and average cost read a lone dot as a decimal point (123.456) and ask which a lone comma before three digits meant (1,234). On a listing held in whole lots (shares listed outside the US, a future's contracts) a lone dot before three digits (1.250) asks too.",
+    "Average cost reads a lone dot as a decimal point (123.456). Shares and contracts ask which a lone dot or comma before three digits meant (1.000, 1,234), thousands or a decimal, and name both readings to type.",
   ],
 };
 

package/src/plugins/builtin/portfolio-list/cli/render.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../../utils/log-failure";
 import { createBaseConverter } from "../../../../cli/base-converter";
 import { savedListingName } from "../../../../cli/listing-arg";
 import { currentListingName } from "../../../../tickers/listing-name";
@@ -257,8 +258,9 @@ export async function loadCollectionQuotes(
         const quote = await dataProvider.getQuote(ticker.metadata.ticker, ticker.metadata.exchange,
           datesChangeBasis ? { ...context, datesChangeBasis } : context);
         quotes.set(ticker.metadata.ticker, quote);
-      } catch {
-        // Ignore partial quote failures so the rest of the table still renders.
+      } catch (error) {
+        // A partial quote failure leaves the rest of the table rendering.
+        logFailure("portfolio-list.cli.render", "Load collection quote failed")(error);
       }
     }),
   );
@@ -1269,7 +1271,7 @@ async function loadMarketCapFinancials(
   const targets = needed.map((ticker) => ({ symbol: ticker.metadata.ticker, exchange: ticker.metadata.exchange }));
   if (dataProvider.getTickerFinancialsBatch) {
     await Promise.all(chunked(targets, FINANCIALS_BATCH_SIZE).map(async (batch) => {
-      const results = await dataProvider.getTickerFinancialsBatch!(batch).catch(() => []);
+      const results = await dataProvider.getTickerFinancialsBatch!(batch).catch(logFailure("portfolio-list.cli.render", "Load market cap financials batch failed", []));
       batch.forEach((target, index) => {
         const value = (results.find((result) => result.target === target) ?? results[index])?.financials;
         if (value) financials.set(target.symbol, value);
@@ -1278,7 +1280,7 @@ async function loadMarketCapFinancials(
     return financials;
   }
   await mapWithConcurrency(targets, FINANCIALS_CONCURRENCY, async (target) => {
-    const value = await dataProvider.getTickerFinancials(target.symbol, target.exchange).catch(() => null);
+    const value = await dataProvider.getTickerFinancials(target.symbol, target.exchange).catch(logFailure("portfolio-list.cli.render", "Load market cap financials failed", null));
     if (value) financials.set(target.symbol, value);
   });
   return financials;
@@ -1298,7 +1300,7 @@ async function loadPerpetualFunding(tickers: readonly TickerRecord[]): Promise<M
   });
   const funding = new Map<string, number | null>();
   await mapWithConcurrency(markets, PERPETUAL_CONCURRENCY, async ({ symbol, listing }) => {
-    funding.set(symbol, await loadPerpetualMarket(listing).then((market) => market?.row.fundingRate8h ?? null, () => null));
+    funding.set(symbol, await loadPerpetualMarket(listing).then((market) => market?.row.fundingRate8h ?? null, logFailure("portfolio-list.cli.render", "Load perpetual funding failed", null)));
   });
   return funding;
 }

package/src/plugins/builtin/portfolio-list/pane/futures-front.ts

@@ -0,0 +1,40 @@
+import { useEffect, useMemo } from "react";
+import { getSharedMarketDataCoordinator } from "../../../../market-data/coordinator";
+import { formatMarketPrice, quoteFormatOptions, withCurrencyMinorDigits } from "../../../../market-data/market/format";
+import { buildQuoteKey, instrumentFromQuoteTarget, resolveEntryData } from "../../../../market-data/selectors";
+import type { PortfolioFuturesTerms } from "../../../../portfolio/futures-positions";
+import { useLiveQuoteEntries } from "../../../../state/hooks/quote-streaming";
+import type { QuoteSubscriptionTarget } from "../../../../types/data-provider";
+import { logFailure } from "../../../../utils/log-failure";
+
+/** Front references share one snapshot and stream per contract, independent of each row's own price. */
+export function useFuturesFrontNotes(
+  terms: ReadonlyMap<string, PortfolioFuturesTerms>,
+  { enabled, liveStreaming }: { enabled: boolean; liveStreaming: boolean },
+): ReadonlyMap<string, string> {
+  const symbolsKey = useMemo(() => enabled
+    ? [...new Set([...terms.values()].flatMap((value) => value.front?.contractSymbol ?? []))].sort().join("\u001f") : "", [enabled, terms]);
+  const targets = useMemo<QuoteSubscriptionTarget[]>(() => symbolsKey ? symbolsKey.split("\u001f").map((symbol) => ({
+    symbol, exchange: "", route: "provider", surface: "watchlist", visible: true,
+  })) : [], [symbolsKey]);
+  const instruments = useMemo(() => targets.map(instrumentFromQuoteTarget), [targets]);
+  const coordinator = getSharedMarketDataCoordinator();
+  const { entries } = useLiveQuoteEntries(targets, { liveStreaming });
+  useEffect(() => {
+    // Polling primes its own batch immediately; a stream needs one snapshot while connecting.
+    if (!liveStreaming || !coordinator || !instruments.length) return;
+    void coordinator.loadQuotesBatch(instruments).catch(logFailure("portfolio-futures", "Read front contract quotes failed"));
+  }, [coordinator, instruments, liveStreaming]);
+  return useMemo(() => {
+    const notes = new Map<string, string>();
+    if (!enabled) return notes;
+    for (const [symbol, value] of terms) {
+      if (!value.front) continue;
+      const quote = resolveEntryData(entries.get(buildQuoteKey({ symbol: value.front.contractSymbol, exchange: "" })));
+      if (!quote || !Number.isFinite(quote.price)) continue;
+      const options = withCurrencyMinorDigits(quoteFormatOptions(quote, "FUTURE"), quote.currency);
+      notes.set(symbol, `front ${value.front.contract} ${formatMarketPrice(quote.price, options)}`);
+    }
+    return notes;
+  }, [enabled, entries, terms]);
+}

package/src/plugins/builtin/portfolio-list/pane/index.tsx

@@ -104,6 +104,7 @@ import { hasUnknownOptionMultiplier } from "../../../../portfolio/position-metri
 import { withFuturesContractSizes } from "../../../../portfolio/futures-positions";
 import { withPurchaseDateCostFx } from "../../../../portfolio/cost-fx";
 import { usePortfolioFuturesTerms } from "./futures-terms";
+import { useFuturesFrontNotes } from "./futures-front";
 import { usePurchaseDateCostFx } from "./purchase-date-fx";
 import {
   allocationWeightBase,
@@ -185,7 +186,8 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
     [config.baseCurrency, currentPortfolio],
   );
   // A future counts contracts of the size its terms give, and at the close is valued at its settlement.
-  const futuresTerms = usePortfolioFuturesTerms(collectionTickers, { enabled: isPortfolioTab, settlement: valuationBasis === "regular-close" });
+  const futuresTerms = usePortfolioFuturesTerms(collectionTickers, { enabled: true, settlement: isPortfolioTab && valuationBasis === "regular-close" });
+  const futuresFrontNotes = useFuturesFrontNotes(futuresTerms.terms, { enabled: appActive && viewMode === "table", liveStreaming });
   // A dated lot in another currency costs what its purchase date's FX close says in that currency, as portfolio show values it.
   const purchaseDateFx = usePurchaseDateCostFx(collectionTickers, { enabled: isPortfolioTab, portfolioId: activeCollectionId, into: totalsCurrency });
   const tickers = useMemo(
@@ -796,6 +798,7 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
           onCursorChange={handleCursorChange}
           financialsMap={financialsMap}
           columnContext={columnContext}
+          futuresFrontNotes={futuresFrontNotes}
           flashSymbols={flashSymbols}
           sinceLastSeen={sinceLastSeen}
           onRootKeyDown={handleTableKeyDown}

package/src/plugins/builtin/portfolio-list/pane/streaming.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../../utils/log-failure";
 import { useEffect, useMemo, useRef } from "react";
 import { getSharedMarketDataCoordinator } from "../../../../market-data/coordinator";
 import { instrumentFromTicker, quoteSubscriptionTargetFromTicker } from "../../../../market-data/request-types";
@@ -251,8 +252,9 @@ export function usePortfolioPaneStreaming({
               ? sharedCoordinator.loadSnapshotsBatch(normalSnapshotEntries.map((entry) => entry.instrument))
               : Promise.resolve(),
           ]);
-        } catch {
+        } catch (error) {
           // Best-effort warmup for visible rows only.
+          logFailure("portfolio-list.pane.streaming", "Warm visible portfolio rows failed")(error);
         } finally {
           for (const entry of [...quoteEntries, ...forcedSnapshotEntries, ...normalSnapshotEntries]) {
             warmupInFlightRef.current.delete(entry.key);
@@ -304,8 +306,9 @@ export function usePortfolioPaneStreaming({
 
       try {
         await sharedCoordinator.loadQuotesBatch(quoteEntries.map((entry) => entry.instrument), { forceRefresh: true });
-      } catch {
+      } catch (error) {
         // Best-effort watchdog for visible rows only.
+        logFailure("portfolio-list.pane.streaming", "Refresh visible portfolio quotes failed")(error);
       } finally {
         for (const entry of quoteEntries) {
           warmupInFlightRef.current.delete(entry.key);

package/src/plugins/builtin/portfolio-list/pane/supplemental.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../../utils/log-failure";
 import { useEffect, useMemo, useRef, useState, type Dispatch, type SetStateAction } from "react";
 import type { ColumnConfig } from "../../../../types/config";
 import type { AnalystResearchData, CorporateActionsData, TickerFinancials } from "../../../../types/financials";
@@ -171,7 +172,7 @@ function useAnalystSupplemental(
       }
     })).then((entries) => {
       if (mountedRef.current) setState((current) => setAnalystValues(current, entries));
-    }).catch(() => {});
+    }).catch(logFailure("portfolio-list.pane.supplemental", "Apply analyst research failed"));
   }, [enabled, mountedRef, provider, setState, state.analystResearch, targetsKey]);
 }
 
@@ -211,7 +212,7 @@ function useCorporateSupplemental(
       }
     })).then((entries) => {
       if (mountedRef.current) setState((current) => setCorporateValues(current, entries));
-    }).catch(() => {});
+    }).catch(logFailure("portfolio-list.pane.supplemental", "Apply corporate actions failed"));
   }, [enabled, mountedRef, provider, setState, state.corporateActions, targetsKey]);
 }
 

package/src/plugins/builtin/portfolio-list/quick-add/resolution.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../../utils/log-failure";
 import { getSharedRegistry } from "../../../registry";
 import {
   AmbiguousContractError,
@@ -178,7 +179,8 @@ export async function resolveQuickAddValidation({
           exchangeFromResolved(resolved),
           quoteContextFromResolved(resolved),
         );
-      } catch {
+      } catch (error) {
+        logFailure("portfolio-list.quick-add.resolution", "Read quick-add quote failed")(error);
         quote = null;
       }
     }

package/src/plugins/builtin/portfolio-list/table.tsx

@@ -111,6 +111,7 @@ export function PortfolioTickerTable({
   onCursorChange,
   financialsMap,
   columnContext,
+  futuresFrontNotes,
   flashSymbols,
   sinceLastSeen,
   onRootKeyDown,
@@ -134,6 +135,7 @@ export function PortfolioTickerTable({
   onCursorChange?: (ticker: TickerRecord, index: number) => void;
   financialsMap: Map<string, TickerFinancials>;
   columnContext: ColumnContext;
+  futuresFrontNotes?: ReadonlyMap<string, string>;
   flashSymbols: Map<string, QuoteFlashDirection>;
   /** For a few seconds after coming back to the pane, LAST is tinted by each row's move since the user left. */
   sinceLastSeen?: SinceLastSeenRecap | null;
@@ -155,21 +157,26 @@ export function PortfolioTickerTable({
   openPerpetualRef.current = onOpenPerpetual;
   const sparklineVisible = columns.some((column) => column.id === PRICE_SPARKLINE_COLUMN_ID);
   const tableFinancialsMap = useLiveSparklineFinancials(financialsMap, sortedTickers, sparklineVisible);
+  const noteColumnId = columns.some((column) => column.id === "name") ? "name" : "ticker";
+  const hasFrontReference = useMemo(() => sortedTickers.some((ticker) => columnContext.futuresTerms?.get(ticker.metadata.ticker)?.front),
+    [columnContext.futuresTerms, sortedTickers]);
   const resolveCell = useCallback(
     (column: ColumnConfig, ticker: TickerRecord, financials: TickerFinancials | undefined) => {
       const key = `${ticker.metadata.ticker}:${column.id}`;
       const version = buildCellVersion(column, ticker, financials, columnContext);
-      const cell = cellCacheRef.current.get(key, version, () => {
+      const cached = cellCacheRef.current.get(key, version, () => {
         const cell = getColumnValue(column, ticker, financials, columnContext);
         const marketId = PERPETUAL_COLUMN_IDS.has(column.id) ? columnContext.perpetuals?.get(ticker.metadata.ticker)?.marketId : undefined;
         return marketId ? { ...cell, onPress: () => openPerpetualRef.current?.(marketId) } : cell;
       });
+      const note = column.id === noteColumnId ? futuresFrontNotes?.get(ticker.metadata.ticker) : undefined;
+      const cell = note ? { ...cached, note } : cached;
       // LAST keeps its price: a move since the user last looked only tints the cell.
       if (column.id !== "price" || !sinceLastSeen) return cell;
       const move = sinceLastSeen.moves.get(ticker.metadata.ticker);
       return move == null ? cell : { ...cell, backgroundColor: sinceLastSeenTint(move, sinceLastSeen.fading) };
     },
-    [columnContext, sinceLastSeen],
+    [columnContext, futuresFrontNotes, noteColumnId, sinceLastSeen],
   );
   const pnlColumn = columns.find((column) => column.id === "pnl" || column.id === "pnl_pct");
   // Reads the same cached P&L cells the rows show; only changed rows recompute.
@@ -202,7 +209,8 @@ export function PortfolioTickerTable({
     : pnlLabel !== "P&L" && (column.id === "pnl" || column.id === "pnl_pct") ? {
     ...column,
     label: column.id === "pnl_pct" ? pnlLabel.replace("P&L", "%") : pnlLabel,
-  } : column), [columns, grossWeights, hasNonShareQuantity, pnlLabel, sharesWidth, tickerWidth]);
+  } : column).map((column) => hasFrontReference && column.id === noteColumnId ? { ...column, flexGrow: 1 } : column),
+  [columns, grossWeights, hasFrontReference, hasNonShareQuantity, noteColumnId, pnlLabel, sharesWidth, tickerWidth]);
   // The table offers "Sort by…" while it has a sort column. A watchlist starts
   // unsorted and a third header click turns sorting off, so the unsorted state
   // needs its own entry until TickerListTableView takes `sortable`.

package/src/plugins/builtin/primary-dealers/client.ts

@@ -1,3 +1,4 @@
+import { createTtlCache } from "../../../data/ttl-cache";
 import { httpFetch } from "../../../utils/http-transport";
 import { isoDateOrNull, numericOrNull, recordOrNull, textOrNull } from "../../../utils/guards";
 import {
@@ -84,20 +85,14 @@ async function readJson(url: string): Promise<unknown> {
 }
 
 /** The series break changes about every two years; one read serves the session. */
-let seriesBreakRead: Promise<string> | null = null;
+const seriesBreaks = createTtlCache<string>({ ttlMs: Infinity });
 
 function currentSeriesBreak(force: boolean): Promise<string> {
-  if (!seriesBreakRead || force) {
-    const read = readJson(`${API}/list/seriesbreaks.json`).then((payload) => {
-      const seriesBreak = newestSeriesBreak(parseSeriesBreaks(payload));
-      if (!seriesBreak) throw new Error("No series break was listed.");
-      return seriesBreak;
-    });
-    seriesBreakRead = read;
-    // A failed read is not kept, so the next one asks again.
-    read.catch(() => { if (seriesBreakRead === read) seriesBreakRead = null; });
-  }
-  return seriesBreakRead;
+  return seriesBreaks.load("current", async () => {
+    const seriesBreak = newestSeriesBreak(parseSeriesBreaks(await readJson(`${API}/list/seriesbreaks.json`)));
+    if (!seriesBreak) throw new Error("No series break was listed.");
+    return seriesBreak;
+  }, { force });
 }
 
 /**
@@ -117,31 +112,11 @@ export async function fetchPrimaryDealers(): Promise<DealerBoard> {
   };
 }
 
-interface SeriesRead {
-  at: number;
-  read: Promise<SeriesPoint[]>;
-  points: SeriesPoint[] | null;
-}
-
-const seriesReads = new Map<string, SeriesRead>();
+const seriesReads = createTtlCache<SeriesPoint[]>({ ttlMs: HISTORY_TTL_MS });
 
 function seriesRead(seriesBreak: string, key: string, force: boolean): Promise<SeriesPoint[]> {
-  const id = `${seriesBreak}:${key}`;
-  const known = seriesReads.get(id);
-  if (known && !force && Date.now() - known.at < HISTORY_TTL_MS) return known.read;
   const url = `${API}/get/${encodeURIComponent(seriesBreak)}/timeseries/${encodeURIComponent(key)}.json`;
-  const entry: SeriesRead = {
-    at: Date.now(),
-    points: null,
-    read: readJson(url).then((payload) => {
-      entry.points = parseSeriesPoints(payload);
-      return entry.points;
-    }),
-  };
-  seriesReads.set(id, entry);
-  // A failed read is not kept, so the next one asks again.
-  entry.read.catch(() => { if (seriesReads.get(id) === entry) seriesReads.delete(id); });
-  return entry.read;
+  return seriesReads.load(`${seriesBreak}:${key}`, async () => parseSeriesPoints(await readJson(url)), { force });
 }
 
 /** A row's history, one read per series behind it, each kept for the session. */
@@ -158,9 +133,9 @@ export async function loadDealerHistory(
 function heldSeries(seriesBreak: string, row: Pick<DealerRow, "keys">): SeriesPoint[][] | null {
   const series: SeriesPoint[][] = [];
   for (const key of row.keys) {
-    const known = seriesReads.get(`${seriesBreak}:${key}`);
-    if (!known?.points || Date.now() - known.at >= HISTORY_TTL_MS) return null;
-    series.push(known.points);
+    const points = seriesReads.peek(`${seriesBreak}:${key}`);
+    if (!points) return null;
+    series.push(points);
   }
   return series;
 }
@@ -178,6 +153,6 @@ export function cachedDealerHistory(seriesBreak: string, row: Pick<DealerRow, "i
 
 /** Forgets what was read, for a test or a refresh that must see the release again. */
 export function resetPrimaryDealersCache(): void {
-  seriesBreakRead = null;
+  seriesBreaks.clear();
   seriesReads.clear();
 }

package/src/plugins/builtin/realized-vol/index.tsx

@@ -21,13 +21,13 @@ export const realizedVolModule: PluginModule = {
     { ...createTickerSurfacePaneTemplate({
       id: "realized-vol-graph-pane", paneId: "realized-vol", label: "Realized Volatility Graph",
       description: "Rolling realized volatility, price and a dated current ATM IV reference.",
-      keywords: ["hvg", "realized", "historical", "volatility", "gv"], shortcut: "HVG", publicShare: true,
+      keywords: ["hvg", "realized", "historical", "volatility", "vol", "gv"], shortcut: "HVG", publicShare: true,
       viewKey: "graph", settings: () => ({ initialView: "graph" }),
     }), headless: realizedVolHeadless("graph") },
     { ...createTickerSurfacePaneTemplate({
       id: "realized-vol-table-pane", paneId: "realized-vol", label: "Realized Volatility Cone",
       description: "Current realized volatility against its historical range and percentile.",
-      keywords: ["hvt", "volatility", "cone", "percentile"], shortcut: "HVT", publicShare: true,
+      keywords: ["hvt", "volatility", "vol", "cone", "percentile"], shortcut: "HVT", publicShare: true,
       viewKey: "cone", settings: () => ({ initialView: "cone" }),
     }), headless: realizedVolHeadless("cone") },
   ],