gloomberb 0.18.2 → 0.18.4

package/src/plugins/builtin/perps/live-rows.ts

@@ -0,0 +1,161 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import type { PerpBoardRow } from "../../../api-client/perps";
+import { getServerClockOffsetMs } from "../../../market-data/quotes/clock";
+import { buildQuoteKey, instrumentFromQuoteTarget } from "../../../market-data/selectors";
+import { useLiveQuoteEntries } from "../../../state/hooks/quote-streaming";
+import { perpetualListingOfMarket } from "../../../tickers/perpetual-listing";
+import type { QuoteSubscriptionTarget } from "../../../types/data-provider";
+import type { Quote } from "../../../types/financials";
+
+/**
+ * Perpetual markets move with the app's quote stream like any listing: a
+ * market is quoted as the listing it is saved under (`BTC:HYPERLIQUID`), and
+ * its quote carries the market's whole row, live while Gloom Cloud follows the
+ * venue's own socket. A view that fetched rows (PERP's board, DES, a list's
+ * perpetual columns) lays each quote's newer row over its own, so the one
+ * subscription a watchlist row already holds feeds every view of the market.
+ */
+
+type Surface = NonNullable<QuoteSubscriptionTarget["surface"]>;
+
+/** The quote target of a market, as its saved listing is quoted; null for a venue the app has no listing for. */
+function perpQuoteTarget(marketId: string, surface: Surface = "detail", visible = true): QuoteSubscriptionTarget | null {
+  const listing = perpetualListingOfMarket(marketId);
+  return listing ? { symbol: listing.key, exchange: listing.exchange, route: "auto", surface, ...(visible ? { visible: true } : {}) } : null;
+}
+
+/** A fetched row with the newer reading a quote of its market brought; the row itself when the quote has none newer. */
+export function withLiveReading(row: PerpBoardRow, quote: Quote | null | undefined): PerpBoardRow {
+  const live = quote?.perpetual;
+  if (!live || live.marketId.toLowerCase() !== row.marketId.toLowerCase()) return row;
+  return Date.parse(live.observedAt) > Date.parse(row.observedAt) ? { ...row, ...live, marketId: row.marketId } : row;
+}
+
+/** As Gloom Cloud rules it: a market with no mark from its venue for a minute is no longer live. */
+const LIVE_FOR_MS = 60_000;
+
+/**
+ * Whether a quote of a market is fed by its venue's socket now, not the minute's read: streamed live, not stale, and
+ * marked within the last minute by the server's clock. The server says so too, but a socket that went quiet says
+ * nothing, so the app keeps its own count.
+ */
+export function isLivePerpQuote(quote: Quote | null | undefined, now = Date.now() + (getServerClockOffsetMs() ?? 0)): boolean {
+  return quote?.dataSource === "live" && quote.stale !== true && Number.isFinite(quote.lastUpdated)
+    && now - quote.lastUpdated <= LIVE_FOR_MS;
+}
+
+/**
+ * How long until a view looks again at whether its live rows still are: when the first one's minute runs out, a beat
+ * after, never more than a minute away. A reading stamped ahead of the clock would otherwise ask for a timer past what
+ * `setTimeout` holds, which fires at once, again and again.
+ */
+export function liveRecheckMs(expiresInMs: number): number {
+  return Math.min(LIVE_FOR_MS, Math.max(0, expiresInMs) + 250);
+}
+
+/** The most rows one view follows on the quote stream at once: as many as the app streams (the socket's budget). */
+const LIVE_ROW_LIMIT = 60;
+
+/** The markets of the rows a view follows on the quote stream: the first LIVE_ROW_LIMIT. */
+export const followedPerpMarkets = (rows: readonly Pick<PerpBoardRow, "marketId">[]) =>
+  rows.slice(0, LIVE_ROW_LIMIT).map((row) => row.marketId);
+
+export interface LivePerpRows {
+  rows: readonly PerpBoardRow[];
+  /** Every row followed is fed by its venue's socket now: the view may call itself live. */
+  live: boolean;
+  /** The markets fed by their venue's socket; the others are the minute's read. */
+  liveMarkets: ReadonlySet<string>;
+}
+
+const NONE: ReadonlySet<string> = new Set();
+
+/**
+ * Fetched rows with the quote stream's newer readings laid over them. Only the
+ * first LIVE_ROW_LIMIT rows are subscribed: a list passes the rows in view.
+ */
+export function useLivePerpRows(
+  rows: readonly PerpBoardRow[],
+  { surface = "detail", visible = true, enabled = true }: { surface?: Surface; visible?: boolean; enabled?: boolean } = {},
+): LivePerpRows {
+  const marketKey = enabled ? followedPerpMarkets(rows).join("\u001f") : "";
+  const targets = useMemo(() => marketKey ? marketKey.split("\u001f").flatMap((marketId) => {
+    const target = perpQuoteTarget(marketId, surface, visible);
+    return target ? [target] : [];
+  }) : [], [marketKey, surface, visible]);
+  const { entries } = useLiveQuoteEntries(targets);
+  // Ticks when a live row's minute runs out, so a feed that went quiet stops calling itself live.
+  const [expired, setExpired] = useState(0);
+  const result = useMemo(() => {
+    if (!targets.length) return { rows, live: false, liveMarkets: NONE, expiresAt: null };
+    const now = Date.now() + (getServerClockOffsetMs() ?? 0);
+    const followed = new Set(targets.map((target) => buildQuoteKey(instrumentFromQuoteTarget(target))));
+    const followedMarkets = new Set(marketKey.split("\u001f").filter((marketId) => perpQuoteTarget(marketId, surface, visible)));
+    const quoteOf = (marketId: string) => {
+      const target = perpQuoteTarget(marketId, surface, visible);
+      if (!target) return null;
+      const key = buildQuoteKey(instrumentFromQuoteTarget(target));
+      const entry = followed.has(key) ? entries.get(key) : undefined;
+      return entry?.data ?? entry?.lastGoodData ?? null;
+    };
+    const liveMarkets = new Set<string>();
+    let expiresAt: number | null = null;
+    const next = rows.map((row) => {
+      const quote = quoteOf(row.marketId);
+      if (quote && isLivePerpQuote(quote, now)) {
+        liveMarkets.add(row.marketId);
+        expiresAt = Math.min(expiresAt ?? Number.POSITIVE_INFINITY, quote.lastUpdated + LIVE_FOR_MS - now);
+      }
+      return withLiveReading(row, quote);
+    });
+    const live = [...followedMarkets].every((marketId) => liveMarkets.has(marketId));
+    return { rows: next, live, liveMarkets, expiresAt };
+    // `expired` is the clock that ends a quiet row's minute.
+  }, [entries, expired, marketKey, rows, surface, targets, visible]);
+  useEffect(() => {
+    if (result.expiresAt == null) return;
+    const timer = setTimeout(() => setExpired((count) => count + 1), liveRecheckMs(result.expiresAt));
+    return () => clearTimeout(timer);
+  }, [result]);
+  return result;
+}
+
+interface Range { start: number; end: number }
+/** Rows a table starts with before it measures its viewport: a pane's height of them. */
+const FIRST_VIEW: Range = { start: 0, end: 40 };
+
+/**
+ * A table's rows with the quote stream laid over the ones in view: pass
+ * `onVisibleRangeChange` to the table, and its rows in view (and the row
+ * `pinned`, the one other tabs follow) are subscribed as it scrolls.
+ */
+export function useLivePerpTableRows<T>(
+  items: readonly T[],
+  rowOf: (item: T) => PerpBoardRow | null,
+  withRow: (item: T, row: PerpBoardRow) => T,
+  { surface = "screener", pinned = null }: { surface?: Surface; pinned?: PerpBoardRow | null } = {},
+): { items: T[]; live: boolean; onVisibleRangeChange: (range: Range) => void } {
+  const [range, setRange] = useState<Range>(FIRST_VIEW);
+  const onVisibleRangeChange = useCallback((next: Range) => {
+    setRange((current) => current.start === next.start && current.end === next.end ? current : next);
+  }, []);
+  const inView = useMemo(() => {
+    const rows = new Map<string, PerpBoardRow>();
+    if (pinned) rows.set(pinned.marketId, pinned);
+    for (const item of items.slice(range.start, range.end)) {
+      const row = rowOf(item);
+      if (row) rows.set(row.marketId, row);
+    }
+    return [...rows.values()];
+  }, [items, pinned, range, rowOf]);
+  const live = useLivePerpRows(inView, { surface });
+  const next = useMemo(() => {
+    const byMarket = new Map(live.rows.map((row) => [row.marketId, row]));
+    return items.map((item) => {
+      const row = rowOf(item);
+      const fresh = row ? byMarket.get(row.marketId) : undefined;
+      return row && fresh && fresh !== row ? withRow(item, fresh) : item;
+    });
+  }, [items, live.rows, rowOf, withRow]);
+  return { items: next, live: live.live, onVisibleRangeChange };
+}

package/src/plugins/builtin/perps/markets-section.tsx

@@ -0,0 +1,154 @@
+import { useCallback, useMemo, useState } from "react";
+import { isAccessDenied } from "../../../api-client/errors";
+import { usePlanAccess } from "../../../api-client/plan-access";
+import type { PerpBoardRow } from "../../../api-client/perps";
+import { ActionRow, ColumnGrid, SectionHeading, type ColumnGridCell, type ColumnGridColumn } from "../../../components";
+import { t, tf } from "../../../i18n";
+import { useAsyncResource, useAutoRefresh } from "../../../public/react";
+import { useThemeColors } from "../../../theme/theme-context";
+import { perpetualListing } from "../../../tickers/perpetual-listing";
+import { premiumToUnderlying } from "../../../market-data/perpetual-premium";
+import type { Quote } from "../../../types/financials";
+import { Box, Text } from "../../../ui";
+import { isRoundTheClockCoin } from "../../../utils/crypto-pair";
+import { displayWidth } from "../../../utils/format";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
+import { useResearchCloudSession } from "../shared/research-cloud-session";
+import { loadPerpsCompare, loadPerpsEquity } from "./client";
+import { perpEquityIdentity } from "./equity-identity";
+import { useLivePerpRows } from "./live-rows";
+import { compact, perpCell, percent, price, readingTime, venueName } from "./model";
+import { useOpenPerpMarket } from "./open-market";
+import { contractText, foldSmallMarkets, mergeVenueMarkets, type PerpVenueMarket } from "./venue-markets";
+
+const STOCK_TYPES = new Set(["STK", "EQUITY", "STOCK", "COMMON STOCK"]);
+const COIN_PAIR = /^([A-Z0-9]{1,15})[-/](?:USD|USDT|USDC)$/;
+
+/** What an asset's contracts are looked up by: a stock's listing, or a coin's base asset. Null for a contract itself. */
+function perpAsset(symbol: string, exchange: string | undefined, instrumentType: string | undefined):
+  { kind: "stock"; symbol: string; exchange: string } | { kind: "coin"; base: string } | null {
+  if (perpetualListing(symbol, exchange)) return null;
+  if (isRoundTheClockCoin(symbol, exchange)) {
+    const bare = parsePublicTickerKey(symbol).symbol.toUpperCase();
+    const base = COIN_PAIR.exec(bare)?.[1] ?? (/^[A-Z0-9]{1,15}$/.test(bare) ? bare : null);
+    return base ? { kind: "coin", base } : null;
+  }
+  const identity = perpEquityIdentity(symbol, exchange);
+  return identity && STOCK_TYPES.has(instrumentType?.toUpperCase() ?? "") ? { kind: "stock", ...identity } : null;
+}
+
+const VENUE_MIN_WIDTH = 11;
+/** Coinbase International, in full. */
+const VENUE_MAX_WIDTH = 22;
+
+interface Column { id: "venue" | "contract" | "mark" | "premium" | "funding" | "oi" | "volume"; label: string; width: number; align?: "right" }
+// Reading order.
+const COLUMNS: readonly Column[] = [
+  { id: "venue", label: "Venue", width: VENUE_MIN_WIDTH },
+  { id: "contract", label: "Contract", width: 11 },
+  { id: "mark", label: "Mark", width: 11, align: "right" },
+  { id: "premium", label: "Premium", width: 8, align: "right" },
+  { id: "funding", label: "Fund 8h", width: 9, align: "right" },
+  { id: "oi", label: "OI USD", width: 7, align: "right" },
+  { id: "volume", label: "Vol 24h", width: 7, align: "right" },
+];
+/** What a narrow overview gives up first: the volume, then the contract, then the premium. */
+const DROP_ORDER: readonly Column["id"][] = ["volume", "contract", "premium"];
+const GAP = 2;
+const span = (columns: readonly Column[]) => columns.reduce((sum, column) => sum + column.width, 0) + GAP * (columns.length - 1);
+
+function fitColumns(width: number, venueWidth: number): Column[] {
+  let columns = COLUMNS.map((column) => column.id === "venue" ? { ...column, width: venueWidth } : column);
+  for (const id of DROP_ORDER) {
+    if (span(columns) <= width) break;
+    columns = columns.filter((column) => column.id !== id);
+  }
+  return columns;
+}
+
+/**
+ * DES's perpetual markets on a stock or a coin: one row per venue (its contracts merged, `venue-markets.ts`), the
+ * deepest first, markets with a small share of the open interest folded behind a row that shows them. A row opens
+ * PERP on its venue's deepest contract. The figures move with the quote stream while the venue streams; otherwise
+ * the section says when the venues were read.
+ */
+export function PerpMarketsSection({ symbol, exchange, instrumentType, quote, width }: {
+  symbol: string;
+  exchange?: string;
+  instrumentType?: string;
+  /** The security's own quote: a stock's contracts are priced against it while it streams. */
+  quote?: Quote | null;
+  width: number;
+}) {
+  const colors = useThemeColors();
+  const session = useResearchCloudSession();
+  const plan = usePlanAccess();
+  const openMarket = useOpenPerpMarket();
+  const [expanded, setExpanded] = useState(false);
+  const asset = perpAsset(symbol, exchange, instrumentType);
+  const assetKey = asset ? asset.kind === "coin" ? `coin:${asset.base}` : `stock:${asset.symbol}:${asset.exchange}` : null;
+  const accessKey = `${session.requestKey}:${plan.hasProAccess ? "pro" : "preview"}`;
+  const loader = useCallback((force: boolean) => {
+    const [kind, first, second] = assetKey!.split(":");
+    return kind === "coin" ? loadPerpsCompare(first!, accessKey, force) : loadPerpsEquity({ symbol: first!, exchange: second! }, accessKey, force);
+  }, [assetKey, accessKey]);
+  const resource = useAsyncResource(assetKey ? loader : null, { clearOnError: isAccessDenied });
+  useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
+  const markets = useMemo(() => mergeVenueMarkets(resource.data?.payload.rows ?? []), [resource.data]);
+  const { shown, folded } = useMemo(() => foldSmallMarkets(markets), [markets]);
+  const visible = expanded ? markets : shown;
+  // The deepest contract of each row on screen follows the quote stream.
+  const primaries = useMemo(() => visible.map((market) => market.primary), [visible]);
+  const live = useLivePerpRows(primaries, { surface: "detail" });
+  if (!assetKey || !markets.length) return null;
+  const rows = visible.map((market, index) => ({ market, row: live.rows[index] ?? market.primary }));
+  const premiumLabel = asset?.kind === "stock" ? "vs last" : "Premium";
+  // The venue column fits the longest venue name shown.
+  const venueWidth = Math.min(VENUE_MAX_WIDTH, Math.max(VENUE_MIN_WIDTH, ...visible.map((market) => displayWidth(venueName(market.venue)))));
+  const columns = fitColumns(width, venueWidth);
+  const fixed = span(columns);
+  // The last text column takes what the figures leave, on the desktop too, so a venue keeps its contract beside it.
+  const growing = columns.some((column) => column.id === "contract") ? "contract" : "venue";
+  const gridColumns: ColumnGridColumn[] = columns.map((column, index) => ({
+    width: column.id === growing ? Math.max(column.width, width - fixed + column.width) : column.width,
+    align: column.align,
+    gapBefore: index > 0 ? GAP : 0,
+    ...(column.id === growing ? { growFrom: column.width } : {}),
+  }));
+  const header: ColumnGridCell[] = columns.map((column) => ({ text: t(column.id === "premium" ? premiumLabel : column.label), color: colors.textDim }));
+  const cell = (column: Column, market: PerpVenueMarket, row: PerpBoardRow): ColumnGridCell => {
+    if (column.id === "venue") {
+      return { text: venueName(market.venue), color: row.stale ? colors.textDim : colors.textBright,
+        link: { label: tf("Open {label}", { label: `PERP ${row.baseAsset} · ${venueName(market.venue)}` }), onOpen: () => openMarket(row.marketId) } };
+    }
+    if (column.id === "contract") return { text: contractText(market), color: colors.textMuted };
+    if (column.id === "mark") return { text: price(row.markPrice ?? row.lastPrice), color: colors.text };
+    if (column.id === "premium") {
+      const value = asset?.kind === "stock" ? premiumToUnderlying(row, quote) : row.premium;
+      return { text: percent(value, 2), color: value == null || value === 0 ? colors.textMuted : value > 0 ? colors.positive : colors.negative };
+    }
+    if (column.id === "funding") {
+      const { text, color } = perpCell(row, "fundingRate8h", colors);
+      return { text, color };
+    }
+    // A venue's open interest and volume are its contracts' together.
+    return { text: compact(column.id === "oi" ? market.openInterestUsd : market.volume24hUsd), color: colors.text };
+  };
+  const body = rows.map(({ market, row }) => columns.map((column) => cell(column, market, row)));
+  // Streaming figures date themselves; the rows from the minute's read say when it was.
+  const read = rows.filter(({ row }) => !live.liveMarkets.has(row.marketId));
+  const readAt = read.length ? readingTime(read.reduce<string | null>((latest, { row }) => !latest || row.observedAt > latest ? row.observedAt : latest, null)) : null;
+  const stale = read.length > 0 && (!!resource.data?.stale || read.some(({ row }) => row.stale));
+  return (
+    <Box flexDirection="column" data-gloom-role="perp-markets">
+      <SectionHeading title={t("Perpetuals")} />
+      <ColumnGrid columns={gridColumns} rows={[header, ...body]} width={width} role="perp-markets-grid" />
+      {folded.length > 0 && (
+        <ActionRow expanded={expanded} width={width}
+          label={expanded ? t("Fewer markets") : folded.length === 1 ? t("1 smaller market") : tf("{count} smaller markets", { count: String(folded.length) })}
+          onPress={() => setExpanded((value) => !value)} />
+      )}
+      {readAt && <Text fg={stale ? colors.warning : colors.textDim}>{`${read.length < rows.length ? `${[...new Set(read.map(({ market }) => venueName(market.venue)))].join(", ")} ` : ""}${t("as of")} ${readAt}${stale ? ` · ${t("stale")}` : ""}`}</Text>}
+    </Box>
+  );
+}

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

@@ -25,21 +25,27 @@ import { isCloudSessionRequired, useResearchCloudSession } from "../shared/resea
 import { boardSearchText, cachedPerpSelection, cachedPerpsBoard, cachedPerpsCompare, cachedPerpsRankings, loadPerpSelection, loadPerpsBoard, loadPerpsCompare,
   loadPerpsHistoryForRange, loadPerpsRankings } from "./client";
 import { perpFreshness, perpObservation } from "./freshness";
+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,
   positioningFields, price, rankingColumns, rankingRows, RANKINGS, ratioText, share, sortLabel, time, underlyingTicker, venueLabel, venueName, venuesOf, type HistoryMetric,
   type PerpColumnId, type PerpTab, type RankingKey } from "./model";
 
 const NO_ROWS: readonly PerpBoardRow[] = [];
+const rowItself = (row: PerpBoardRow) => row;
+const replaced = (_: PerpBoardRow, row: PerpBoardRow) => row;
+const rankedRow = (entry: SectionedRow<Ranked>) => entry.kind === "item" ? entry.item.row : null;
+const withRankedRow = (entry: SectionedRow<Ranked>, row: PerpBoardRow): SectionedRow<Ranked> =>
+  entry.kind === "item" ? { ...entry, item: { ...entry.item, row } } : entry;
 
 /**
  * The footer line for the rows on screen: each venue's own observation time, how old the oldest is, the delay state
  * and what the funding figures are, the line `fn PERP` and `shot PERP` end with. It keeps ageing while the pane is
  * seen (`since` is when the rows loaded), and is published for a capture to date itself the same way.
  */
-function usePerpStatusLine(rows: readonly PerpBoardRow[], funding: readonly PerpBoardRow[], since: number | null): PaneFooterSegment[] {
+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 }) : null, [rows, funding, now]);
+  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, observations: rows.map(perpObservation) }) } : null);
   return useMemo(() => {
     if (!declared) return [];
@@ -104,8 +110,8 @@ function MarketEvidence({ row, data, width, height }: { row: PerpBoardRow; data:
   </ScrollBox>;
 }
 
-function History({ market, venues, accessKey, width, height, focused, range, metric, refreshMarket }: {
-  market: PerpBoardRow; venues: number | null; accessKey: string; width: number; height: number; focused: boolean; range: string; metric: HistoryMetric; refreshMarket: () => void;
+function History({ market, live = false, venues, accessKey, width, height, focused, range, metric, refreshMarket }: {
+  market: PerpBoardRow; live?: boolean; venues: number | null; accessKey: string; width: number; height: number; focused: boolean; range: string; metric: HistoryMetric; refreshMarket: () => void;
 }) {
   const colors = useThemeColors();
   const loader = useCallback((force: boolean) => loadPerpsHistoryForRange(market.marketId, Number(range), accessKey, force), [market.marketId, range, accessKey]);
@@ -125,7 +131,7 @@ function History({ market, venues, accessKey, width, height, focused, range, met
   const lastTime = rows.at(-1)?.time;
   // The market row dates the figures beside the series. Its funding is the current estimate, unless the series is paid funding.
   const marketRows = useMemo(() => [market], [market]);
-  const line = usePerpStatusLine(marketRows, metric === "funding" && !data?.funding.length ? marketRows : NO_ROWS, resource.updatedAt);
+  const line = usePerpStatusLine(marketRows, metric === "funding" && !data?.funding.length ? marketRows : NO_ROWS, resource.updatedAt, live);
   usePaneStatusFooter({ registrationId: "perps:history", loading: resource.loading, error: resource.error, stale: resource.data?.stale,
     info: [...line, ...(lastTime ? [{ id: "history-asof", parts: [{ text: `${historyCaption(data, metric)} · ${time(lastTime)}`, tone: "muted" as const }] }] : [])] });
   usePaneNoticeFooter({ registrationId: "perps:history-notice", focused, notices: [resource.data?.refreshError,
@@ -221,14 +227,18 @@ function Board({ accessKey, width, height, focused, onPick, onOpen }: ListTabPro
   const resource = useAsyncResource(loader, { initialData: () => cachedPerpsBoard(query, accessKey), clearOnError: isAccessDenied, keepPreviousData: true });
   const data = resource.data?.payload;
   const venues = useMemo(() => venuesOf(data?.rows ?? []), [data]);
-  const rows = useMemo(() => venue === "all" ? data?.rows ?? [] : (data?.rows ?? []).filter((row) => row.venue === venue), [data, venue]);
+  const fetchedRows = useMemo(() => venue === "all" ? data?.rows ?? [] : (data?.rows ?? []).filter((row) => row.venue === venue), [data, venue]);
+  // The rows in view move with the quote stream.
+  const pinned = fetchedRows.find((row) => row.marketId === selectedId) ?? null;
+  const stream = useLivePerpTableRows(fetchedRows, rowItself, replaced, { pinned });
+  const rows = stream.items;
   const selected = rows.find((row) => row.marketId === selectedId) ?? rows[0] ?? null;
   useEffect(() => { onPick(selected); }, [selected, onPick]);
   const columns = useMemo(() => boardColumns(width), [width]);
   const locked = typeof data?.locked === "number" ? data.locked : 0;
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
   usePaneRefreshKey(() => { void resource.reload(); }, { focused: focused && !querySearch.active });
-  const line = usePerpStatusLine(rows, rows, resource.updatedAt);
+  const line = usePerpStatusLine(rows, rows, resource.updatedAt, stream.live);
   usePaneStatusFooter({ registrationId: "perps:board", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale, info: line });
   usePaneNoticeFooter({ registrationId: "perps:board-notice", focused, notices: resource.data?.refreshError ? [resource.data.refreshError] : [] });
   if (!data && isCloudSessionRequired(resource.error)) return <SignInWall placement="perps-signin" action="view perpetual markets" needsVerification={session.needsVerification} />;
@@ -244,7 +254,7 @@ function Board({ accessKey, width, height, focused, onPick, onOpen }: ListTabPro
     ]} />;
   return <PaneStatusBody loading={!data && resource.loading} error={!data ? resource.error : null} subject="perpetual markets">
     <DataTableView<PerpBoardRow> columns={columns} items={rows} focused={focused && !querySearch.active} rootWidth={width} rootHeight={height} rootBefore={queryBar}
-      getItemKey={(row) => row.marketId} sortColumnId={null} sortDirection="desc" resetScrollKey={`${JSON.stringify(query)}:${venue}`}
+      getItemKey={(row) => row.marketId} sortColumnId={null} sortDirection="desc" resetScrollKey={`${JSON.stringify(query)}:${venue}`} onVisibleRangeChange={stream.onVisibleRangeChange}
       selection={{ kind: "id", selectedId: selected?.marketId ?? null, getId: (row) => row.marketId, onChange: setSelected }} onActivate={(row) => onOpen(row)}
       renderCell={(row, column) => perpCell(row, column.id as PerpColumnId, colors)} selectedTextOverridesCellColor
       emptyStateTitle="No markets match these filters." emptyContent={lock && <Box paddingX={1} paddingY={1}><EmptyState title="No preview markets match." actions={<UpgradeLabel text={moreText(locked, "markets")} onPress={upgrade} role="perps-board-upgrade" />} /></Box>}
@@ -264,8 +274,11 @@ function Rankings({ accessKey, width, height, focused, onPick, onOpen }: ListTab
   const loader = useCallback((force: boolean) => loadPerpsRankings(accessKey, force), [accessKey]);
   const resource = useAsyncResource(loader, { initialData: () => cachedPerpsRankings(accessKey), clearOnError: isAccessDenied });
   const data = resource.data?.payload;
-  const items = useMemo(() => buildSectionedRows(RANKINGS.map((ranking) => ({ label: ranking.label, emptyLabel: "None",
+  const fetchedItems = useMemo(() => buildSectionedRows(RANKINGS.map((ranking) => ({ label: ranking.label, emptyLabel: "None",
     items: rankingRows(data, ranking.key).map((row): Ranked => ({ list: ranking.key, row })) })), rankedKey), [data]);
+  // The ranked rows in view move with the quote stream; the lists keep the order they were ranked in.
+  const stream = useLivePerpTableRows(fetchedItems, rankedRow, withRankedRow);
+  const items = stream.items;
   const ranked = items.flatMap((item) => item.kind === "item" ? [item.item] : []);
   const selected = ranked.find((item) => rankedKey(item) === selectedId) ?? ranked[0] ?? null;
   useEffect(() => { onPick(selected?.row ?? null); }, [selected, onPick]);
@@ -275,7 +288,7 @@ function Rankings({ accessKey, width, height, focused, onPick, onOpen }: ListTab
   // Every ranked row is dated; only the funding lists show funding.
   const rankedRows = useMemo(() => RANKINGS.flatMap((ranking) => rankingRows(data, ranking.key)), [data]);
   const fundingRows = useMemo(() => RANKINGS.filter((ranking) => ranking.field === "fundingRate8h").flatMap((ranking) => rankingRows(data, ranking.key)), [data]);
-  const line = usePerpStatusLine(rankedRows, fundingRows, resource.updatedAt);
+  const line = usePerpStatusLine(rankedRows, fundingRows, resource.updatedAt, stream.live);
   usePaneStatusFooter({ registrationId: "perps:rankings", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale, info: line });
   usePaneNoticeFooter({ registrationId: "perps:rankings-notice", focused, notices: resource.data?.refreshError ? [resource.data.refreshError] : [] });
   if (!data && isCloudSessionRequired(resource.error)) return <SignInWall placement="perps-signin" action="view perpetual rankings" needsVerification={session.needsVerification} />;
@@ -290,7 +303,7 @@ function Rankings({ accessKey, width, height, focused, onPick, onOpen }: ListTab
   };
   return <PaneStatusBody loading={!data && resource.loading} error={!data ? resource.error : null} subject="perpetual rankings">
     <DataTableView<SectionedRow<Ranked>> columns={columns} items={items} focused={focused} rootWidth={width} rootHeight={height}
-      getItemKey={(entry) => entry.key} sortColumnId={null} sortDirection="desc" isNavigable={(entry) => entry.kind === "item"}
+      getItemKey={(entry) => entry.key} sortColumnId={null} sortDirection="desc" isNavigable={(entry) => entry.kind === "item"} onVisibleRangeChange={stream.onVisibleRangeChange}
       renderSectionHeader={(entry) => entry.kind === "section" ? { text: entry.label } : null}
       selection={{ kind: "id", selectedId: selected ? rankedKey(selected) : null, getId: (entry) => entry.key, onChange: (id) => { if (ranked.some((item) => rankedKey(item) === id)) setSelected(id); } }}
       onActivate={(entry) => { if (entry.kind === "item") onOpen(entry.item.row); }}
@@ -310,11 +323,13 @@ function Compare({ asset, onAssetChange, accessKey, width, height, focused, onPi
   const loader = useCallback((force: boolean) => loadPerpsCompare(base, accessKey, force), [base, accessKey]);
   const resource = useAsyncResource(loader, { initialData: () => cachedPerpsCompare(base, accessKey), clearOnError: isAccessDenied, keepPreviousData: true });
   const data = resource.data?.payload;
-  const rows = useMemo(() => data?.rows ?? [], [data]);
+  const fetchedRows = useMemo(() => data?.rows ?? [], [data]);
+  const stream = useLivePerpTableRows(fetchedRows, rowItself, replaced, { pinned: fetchedRows.find((row) => row.marketId === selectedId) ?? null });
+  const rows = stream.items;
   const selected = rows.find((row) => row.marketId === selectedId) ?? rows[0] ?? null;
   useEffect(() => { onPick(selected); }, [selected, onPick]);
   const columns = useMemo(() => compareColumns(width), [width]);
-  const line = usePerpStatusLine(rows, rows, resource.updatedAt);
+  const line = usePerpStatusLine(rows, rows, resource.updatedAt, stream.live);
   const spread = useMemo(() => fundingSpread(rows), [rows]);
   const locked = typeof data?.locked === "number" ? data.locked : 0;
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
@@ -330,7 +345,7 @@ function Compare({ asset, onAssetChange, accessKey, width, height, focused, onPi
   </>;
   return <PaneStatusBody loading={!data && resource.loading} error={!data ? resource.error : null} subject="perpetual contracts">
     <DataTableView<PerpBoardRow> columns={columns} items={rows} focused={focused && !querySearch.active} rootWidth={width} rootHeight={height} rootBefore={before}
-      getItemKey={(row) => row.marketId} sortColumnId={null} sortDirection="desc" resetScrollKey={base}
+      getItemKey={(row) => row.marketId} sortColumnId={null} sortDirection="desc" resetScrollKey={base} onVisibleRangeChange={stream.onVisibleRangeChange}
       selection={{ kind: "id", selectedId: selected?.marketId ?? null, getId: (row) => row.marketId, onChange: setSelected }} onActivate={(row) => onOpen(row)}
       renderCell={(row, column) => perpCell(row, column.id as PerpColumnId, colors)} selectedTextOverridesCellColor
       emptyStateTitle={`No perpetual contracts for ${base}.`} emptyContent={lock && <Box paddingX={1} paddingY={1}><EmptyState title={`No preview contracts for ${base}.`} actions={<UpgradeLabel text={moreText(locked, locked === 1 ? "contract" : "contracts")} onPress={upgrade} role="perps-compare-upgrade" />} /></Box>}
@@ -380,7 +395,11 @@ export function PerpsPane({ width, height, focused, marketAction }: Pick<PanePro
   const loader = useCallback((force: boolean) => loadPerpSelection(search, accessKey, force), [search, accessKey]);
   const resource = useAsyncResource(marketTab ? loader : null, { initialData: () => cachedPerpSelection(search, accessKey), clearOnError: isAccessDenied });
   const data = marketTab ? resource.data?.payload : undefined;
-  const active = data?.rows[0] ?? null;
+  const fetchedActive = data?.rows[0] ?? null;
+  // The market on screen moves with the quote stream, as its listing's quote does everywhere else.
+  const activeRows = useMemo(() => fetchedActive ? [fetchedActive] : NO_ROWS, [fetchedActive]);
+  const activeStream = useLivePerpRows(activeRows, { surface: "detail", enabled: marketTab });
+  const active = activeStream.rows[0] ?? null;
   usePaneTitle(active ? `PERP ${marketLabel(active)} · ${venueLabel(active)}` : "PERP");
   const querySearch = useQueryBarSearch();
   // The market on screen goes with the user: History and Evidence open the row picked on a list, Compare its base asset.
@@ -416,7 +435,7 @@ export function PerpsPane({ width, height, focused, marketAction }: Pick<PanePro
   ];
   // History dates its own market beside its series; Evidence is dated here.
   const evidenceRows = useMemo(() => tab === "evidence" && active ? [active] : NO_ROWS, [tab, active]);
-  const evidenceLine = usePerpStatusLine(evidenceRows, evidenceRows, resource.updatedAt);
+  const evidenceLine = usePerpStatusLine(evidenceRows, evidenceRows, resource.updatedAt, activeStream.live);
   usePaneStatusFooter({ registrationId: "perps", loading: marketTab && resource.loading, error: data ? resource.error : null, stale: marketTab && resource.data?.stale,
     info: evidenceLine, hints });
   usePaneNoticeFooter({ registrationId: "perps:notices", focused, notices: marketTab ? [resource.data?.refreshError,
@@ -434,7 +453,7 @@ export function PerpsPane({ width, height, focused, marketAction }: Pick<PanePro
             { id: "range", label: "Range", value: range, options: ["1", "7", "30", "90", "365"].map((value) => ({ value, label: `${value}D` })), onChange: setRange },
           ] : []} />
         <PaneStatusBody loading={!data && resource.loading} error={!data ? resource.error : null} subject="perpetual market">
-          {active ? tab === "history" ? <History key={active.marketId} market={active} venues={collectedVenueCount(data?.sources)} accessKey={accessKey} width={width} height={listHeight - 1} focused={focused && !querySearch.active} range={range} metric={metric} refreshMarket={refreshMarket} />
+          {active ? tab === "history" ? <History key={active.marketId} market={active} live={activeStream.live} venues={collectedVenueCount(data?.sources)} accessKey={accessKey} width={width} height={listHeight - 1} focused={focused && !querySearch.active} range={range} metric={metric} refreshMarket={refreshMarket} />
             : <MarketEvidence row={active} data={data!} width={width} height={listHeight - 1} />
             : <EmptyState title="No market matches." message={data?.suggestions?.length ? `Try ${data.suggestions.join(", ")}.` : undefined} />}
         </PaneStatusBody>

package/src/plugins/builtin/perps/venue-markets.ts

@@ -0,0 +1,96 @@
+import type { PerpBoardRow } from "../../../api-client/perps";
+import { venueName } from "./model";
+
+/**
+ * An asset's perpetual markets as DES lists them: one row per venue.
+ *
+ * A venue often lists one asset several times: Bybit's BTC settles in USDT,
+ * in USDC and inversely in BTC, and on Hyperliquid each builder dex (xyz, flx,
+ * km...) deploys its own NVDA. Listed contract by contract they read as the
+ * same line over and over, so each venue's contracts are one market here: the
+ * deepest contract gives the row its mark, funding and premium, and the open
+ * interest and volume are the venue's whole. A row reached twice (the same
+ * market id in two cases, or answered by two reads) is one contract.
+ */
+export interface PerpVenueMarket {
+  /** `hyperliquid:BTC`: the venue and the asset, whatever the contract. */
+  key: string;
+  venue: string;
+  /** The deepest contract, which a click opens. */
+  primary: PerpBoardRow;
+  /** Every contract on the venue, deepest first; the primary is the first. */
+  contracts: PerpBoardRow[];
+  /** Open interest across the contracts, in USD; null when no contract states it. */
+  openInterestUsd: number | null;
+  volume24hUsd: number | null;
+}
+
+const sumOrNull = (values: Array<number | null | undefined>) => {
+  const known = values.filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+  return known.length ? known.reduce((sum, value) => sum + value, 0) : null;
+};
+const depth = (value: number | null | undefined) => typeof value === "number" && Number.isFinite(value) ? value : -1;
+const deeper = (a: { openInterestUsd: number | null; volume24hUsd: number | null }, b: typeof a) =>
+  depth(b.openInterestUsd) - depth(a.openInterestUsd) || depth(b.volume24hUsd) - depth(a.volume24hUsd);
+
+/** Rows merged into one row per venue and asset, the deepest first (open interest, then volume). Delisted contracts are left out. */
+export function mergeVenueMarkets(rows: readonly PerpBoardRow[]): PerpVenueMarket[] {
+  const contracts = new Map<string, PerpBoardRow>();
+  for (const row of rows) {
+    if (row.delisted) continue;
+    const id = row.marketId.toLowerCase();
+    const seen = contracts.get(id);
+    if (!seen || Date.parse(row.observedAt) > Date.parse(seen.observedAt)) contracts.set(id, row);
+  }
+  const venues = new Map<string, PerpBoardRow[]>();
+  for (const row of contracts.values()) {
+    const key = `${row.venue}:${row.baseAsset.toUpperCase()}`;
+    venues.set(key, [...venues.get(key) ?? [], row]);
+  }
+  return [...venues].map(([key, group]): PerpVenueMarket => {
+    const sorted = [...group].sort((a, b) => deeper(a, b) || a.marketId.localeCompare(b.marketId));
+    return {
+      key,
+      venue: sorted[0]!.venue,
+      primary: sorted[0]!,
+      contracts: sorted,
+      openInterestUsd: sumOrNull(sorted.map((row) => row.openInterestUsd)),
+      volume24hUsd: sumOrNull(sorted.map((row) => row.volume24hUsd)),
+    };
+  }).sort((a, b) => deeper(a, b) || venueName(a.venue).localeCompare(venueName(b.venue)) || a.key.localeCompare(b.key));
+}
+
+/** A market under this share of the asset's open interest is folded behind "more". */
+const SMALL_MARKET_SHARE = 0.02;
+
+/**
+ * The markets shown and those folded behind "more": a market holding less than
+ * `minShare` of the asset's open interest across venues, or past `maxShown`,
+ * is folded. The deepest market always shows, and one with no open interest
+ * stated shows only while no market states any.
+ */
+export function foldSmallMarkets(markets: readonly PerpVenueMarket[], { minShare = SMALL_MARKET_SHARE, maxShown = 4 }: { minShare?: number; maxShown?: number } = {}): {
+  shown: PerpVenueMarket[]; folded: PerpVenueMarket[];
+} {
+  const total = sumOrNull(markets.map((market) => market.openInterestUsd));
+  const shown: PerpVenueMarket[] = [];
+  const folded: PerpVenueMarket[] = [];
+  for (const market of markets) {
+    const share = total && market.openInterestUsd != null ? market.openInterestUsd / total : total ? 0 : 1;
+    if (shown.length === 0 || (shown.length < maxShown && share >= minShare)) shown.push(market);
+    else folded.push(market);
+  }
+  return { shown, folded };
+}
+
+/**
+ * The contract a venue's row reads from, as the venue settles it (`USDT`, `USD inverse`, a Hyperliquid builder dex
+ * such as `xyz`), and how many more it stands for: `USDT +2`.
+ */
+export function contractText(market: PerpVenueMarket): string {
+  const row = market.primary;
+  const own = row.venue === "hyperliquid" && row.dex && row.dex !== "default" ? row.dex
+    : row.contractType === "inverse" ? `${row.quoteCurrency} inverse` : row.quoteCurrency;
+  const others = market.contracts.length - 1;
+  return others > 0 ? `${own} +${others}` : own;
+}

package/src/plugins/builtin/plugin-marketplace/index.tsx

@@ -10,6 +10,7 @@ export const pluginMarketplaceModule: PluginModule = {
       name: "Plugins",
       icon: "P",
       component: PluginMarketplacePane,
+      reportFreshness: { status: "not-a-feed", basis: "plugin listings" },
       defaultPosition: "right",
       defaultMode: "floating",
       defaultFloatingSize: { width: 118, height: 34 },
@@ -34,7 +35,7 @@ export const pluginMarketplaceModule: PluginModule = {
       id: "plugin-marketplace-pane",
       paneId: PLUGIN_MARKETPLACE_PANE_ID,
       label: "Plugins",
-      description: "Browse and install Gloomberb plugins, and enable or disable the ones you have.",
+      description: "Browse and install Gloom plugins, and enable or disable the ones you have.",
       keywords: ["plugin", "plugins", "marketplace", "install", "extend", "addon", "extension"],
       shortcut: { prefix: "PL" },
       createInstance: () => ({ placement: "floating" }),