gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/options-scenario/hedge.ts

@@ -3,7 +3,7 @@ import type { OptionsChain } from "../../../types/financials";
 import type { HeadlessPaneEntry } from "../../../types/headless";
 import { numberErrorMessage } from "../../../utils/decimal-comma";
 import { formatCompact } from "../../../utils/format";
-import { UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
+import { amountUnit, exportPercent, UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
 
 /**
  * Hedge budget sizing (docs/research-data.md#options-scenario-analysis): how
@@ -118,9 +118,10 @@ export interface HedgeQuote { bid: number; ask: number }
 
 /**
  * The bid and ask of each leg a strategy seeded from the chain, by leg id: the
- * chain's, or the leg's streamed quote when the pane follows the market.
+ * chain's, or the leg's streamed quote when the pane follows the market. A
+ * typed leg has none.
  */
-function hedgeLegQuotes(
+export function seededLegQuotes(
   position: ScenarioPosition, chain: OptionsChain | null | undefined, liveQuotes?: ReadonlyMap<string, HedgeQuote>,
 ): Map<string, HedgeQuote> {
   const contracts = new Map([...(chain?.calls ?? []), ...(chain?.puts ?? [])].map((contract) => [contract.contractSymbol, contract]));
@@ -206,7 +207,7 @@ export function scenarioHedgeBudget(
   const inputs = hedgeInputsFromSettings(settings);
   if (!inputs) return null;
   if (!position?.legs.length) throw new Error("A hedge budget needs a position; add --legs or select --strategy.");
-  return sizeHedgeBudget(position, inputs, { quotes: hedgeLegQuotes(position, market?.chain, market?.liveQuotes),
+  return sizeHedgeBudget(position, inputs, { quotes: seededLegQuotes(position, market?.chain, market?.liveQuotes),
     spot: hedgeSpot(position, market?.spot, supplied(settings.spot)) });
 }
 
@@ -246,21 +247,26 @@ function costText(cost: number, sizingPrice: number | null, multiplier: number,
 /** The report's Hedge budget section; `value` keeps full precision, `formatted` is what text output prints. */
 export function hedgeReportEntries(hedge: HedgeBudget): HeadlessPaneEntry[] {
   const unit = hedge.currency && hedge.currency !== UNKNOWN_CURRENCY ? ` ${hedge.currency}` : "";
+  // Each figure's `value` is in its `unit`, a share of NAV in percent, so an export writes the number and its unit.
+  const amount = { unit: amountUnit(hedge.currency) };
   return [
-    { key: "nav", label: "NAV", value: hedge.nav, formatted: `${money(hedge.nav)}${unit}` },
-    { key: "budget", label: "Budget", value: hedge.budget, formatted: `${money(hedge.budget)}${unit} (${formatBps(hedge.budgetBps)} of NAV)` },
-    { key: "sizingPrice", label: "Sizing price", value: hedge.sizingPrice,
+    { key: "nav", label: "NAV", value: hedge.nav, ...amount, formatted: `${money(hedge.nav)}${unit}` },
+    { key: "budget", label: "Budget", value: hedge.budget, ...amount, formatted: `${money(hedge.budget)}${unit} (${formatBps(hedge.budgetBps)} of NAV)` },
+    { key: "sizingPrice", label: "Sizing price", value: hedge.sizingPrice, unit: `${amount.unit} per share`,
       formatted: hedge.sizingPrice == null ? "--" : describePrice(hedge.basis, hedge.singleLeg, hedge.sizingPrice) },
-    { key: "costPerContract", label: "Cost per contract", value: hedge.costPerContract, formatted: costText(hedge.costPerContract, hedge.sizingPrice, hedge.multiplier, unit) },
-    { key: "contracts", label: "Contracts", value: hedge.contracts, formatted: hedge.contracts.toLocaleString("en-US") },
-    { key: "premium", label: "Premium spent", value: hedge.premium, formatted: `${money(hedge.premium)}${unit}` },
-    { key: "premiumBps", label: "Premium / NAV", value: hedge.premiumBps, formatted: `${formatBps(hedge.premiumBps)} (${(hedge.premiumBps / 100).toFixed(2)}% of NAV)` },
-    { key: "notional", label: "Notional protected", value: hedge.notional,
+    { key: "costPerContract", label: "Cost per contract", value: hedge.costPerContract, ...amount,
+      formatted: costText(hedge.costPerContract, hedge.sizingPrice, hedge.multiplier, unit) },
+    { key: "contracts", label: "Contracts", value: hedge.contracts, unit: "contracts", formatted: hedge.contracts.toLocaleString("en-US") },
+    { key: "premium", label: "Premium spent", value: hedge.premium, ...amount, formatted: `${money(hedge.premium)}${unit}` },
+    { key: "premiumBps", label: "Premium / NAV", value: hedge.premiumBps, unit: "bp",
+      formatted: `${formatBps(hedge.premiumBps)} (${(hedge.premiumBps / 100).toFixed(2)}% of NAV)` },
+    { key: "notional", label: "Notional protected", value: hedge.notional, ...amount,
       formatted: `${money(hedge.notional)}${unit} (${hedge.contracts.toLocaleString("en-US")} x ${hedge.multiplier} x ${formatHedgePrice(hedge.spot)})` },
-    { key: "notionalOfNav", label: "Notional / NAV", value: hedge.notionalOfNav, formatted: percent(hedge.notionalOfNav) },
+    { key: "notionalOfNav", label: "Notional / NAV", value: exportPercent(hedge.notionalOfNav), unit: "%", formatted: percent(hedge.notionalOfNav) },
     hedge.coverage == null || hedge.sleeve == null
       ? { key: "coverage", label: "Coverage", value: null, formatted: "No equity sleeve given; add --sleeve <amount> to read notional against it" }
-      : { key: "coverage", label: "Coverage", value: hedge.coverage, formatted: `${percent(hedge.coverage)} of a ${money(hedge.sleeve)}${unit} sleeve` },
+      : { key: "coverage", label: "Coverage", value: exportPercent(hedge.coverage), unit: "%",
+        formatted: `${percent(hedge.coverage)} of a ${money(hedge.sleeve)}${unit} sleeve` },
   ];
 }
 

package/src/plugins/builtin/options-scenario/index.tsx

@@ -2,8 +2,10 @@ import type { PluginModule } from "../plugin-module";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import { OptionsScenarioPane } from "./pane";
 import { optionsScenarioHeadless } from "./headless";
+import { CspScreenPane } from "./csp-screen-pane";
+import { cspScreenHeadless } from "./csp-screen-headless";
 
-const scenarioSettingKeys = ["legs", "strategy", "strike", "putStrike", "callStrike", "shares", "expiration", "spot", "rate", "dividendYield", "currency", "asOf", "date", "volShift",
+const scenarioSettingKeys = ["legs", "strategy", "strike", "delta", "putStrike", "callStrike", "shares", "expiration", "spot", "rate", "dividendYield", "currency", "asOf", "date", "volShift",
   "spotRange", "seedLeg", "nav", "budgetBps", "sleeve"];
 
 export const optionsScenarioModule: PluginModule = {
@@ -23,11 +25,34 @@ export const optionsScenarioModule: PluginModule = {
           description: "The equity the hedge protects, for coverage: notional protected over the sleeve." },
       ],
     },
+  }, {
+    id: "csp-screen", name: "Cash-Secured Put Screen", icon: "V", component: CspScreenPane,
+    defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 144, height: 24 },
+    tableExport: true, headless: cspScreenHeadless,
+    settings: {
+      title: "Cash-Secured Put Screen",
+      fields: [
+        { key: "symbols", label: "Symbols", type: "text", placeholder: "JPM, GS, KO" },
+        { key: "maxSpread", label: "Wide spread over (%)", type: "text", placeholder: "10",
+          description: "A put whose bid/ask spread is over this percent of its mid is marked wide. It is still ranked." },
+      ],
+    },
   }],
-  paneTemplates: [createTickerSurfacePaneTemplate({
+  paneTemplates: [{
+    id: "csp-screen-pane", paneId: "csp-screen", label: "Cash-Secured Put Screen",
+    description: "Cash-secured puts across a list, ranked by annualised yield at the bid, with % OTM, delta, IV rank, spread and an earnings flag.",
+    // The put-selling phrases lead here first, then to OSA for one name.
+    keywords: ["csp", "cash secured put", "cash-secured puts", "put selling", "selling puts", "sell put", "sell puts", "short put", "wheel",
+      "put screen", "premium yield"],
+    shortcut: { prefix: "CSP", argKind: "ticker-list" as const }, headless: cspScreenHeadless,
+    createInstance: (_context, options) => ({
+      title: "CSP", placement: "floating" as const,
+      settings: options?.symbols?.length ? { symbols: options.symbols.join(",") } : {},
+    }),
+  }, createTickerSurfacePaneTemplate({
     id: "options-scenario-pane", paneId: "options-scenario", label: "Options Scenario",
     description: "Build multi-leg positions and compare scenario P&L, payoff and aggregate Greeks.",
-    // OSA owns the phrases; OMON and VCA carry the same words without them, so a put-selling search finds all three, OSA first.
+    // OSA carries the put-selling phrases after CSP, which ranks names on them; OMON and VCA carry the same words, so a search finds all four.
     keywords: ["osa", "options", "scenario", "payoff", "strategy", "greeks", "hedge", "hedging", "collar", "protective put", "put spread",
       "cash secured put", "csp", "put selling", "sell put", "short put", "wheel"],
     shortcut: "OSA", publicShare: true,

package/src/plugins/builtin/options-scenario/model.ts

@@ -160,6 +160,19 @@ export function validateScenarioInputs(position: ScenarioPosition): string | nul
 /** The stored stand-in for a currency nothing names; shown as `currency unknown`. */
 export const UNKNOWN_CURRENCY = "UNKNOWN";
 export const currencyLabel = (currency: string) => currency === UNKNOWN_CURRENCY ? "currency unknown" : currency;
+/** The unit an export names beside an amount: the currency code, or `currency unknown`. */
+export const amountUnit = (currency: string) => currency && currency !== UNKNOWN_CURRENCY ? currency : "currency unknown";
+
+/**
+ * A fraction as the percent an export carries: a rate of 0.041 is 4.1, not
+ * the 4.1000000000000005 the product leaves. Twelve significant digits keep
+ * every digit a figure has; null stays null.
+ */
+export function exportPercent(fraction: number): number;
+export function exportPercent(fraction: number | null | undefined): number | null;
+export function exportPercent(fraction: number | null | undefined): number | null {
+  return fraction == null ? null : Number((fraction * 100).toPrecision(12));
+}
 
 /**
  * The position's currency: the one typed, else the underlying's quote

package/src/plugins/builtin/options-scenario/pane.tsx

@@ -38,8 +38,8 @@ import { buildScenario, currencyLabel, scenarioCurrency, scenarioValueUnit, UNKN
   type ScenarioControls, validatePosition } from "./model";
 import { EMPTY_SAVED_STRATEGIES, restoreSavedStrategies, type SavedScenarioStrategy } from "./state";
 import { useScenarioEvidence } from "./evidence";
-import { hedgeStatItems, scenarioHedgeBudget, type HedgeQuote } from "./hedge";
-import { readOptionExpiration } from "../../../utils/option-expiry";
+import { hedgeStatItems, scenarioHedgeBudget, seededLegQuotes, type HedgeQuote } from "./hedge";
+import { isLiveOptionExpiry, readOptionExpiration } from "../../../utils/option-expiry";
 import { parsePublicTickerKey } from "../../../utils/exchanges";
 
 const EMPTY_ERRORS: string[] = [];
@@ -65,7 +65,9 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   const underlying = listed.symbol;
   const exchange = listed.exchange || target?.effectiveExchange || undefined;
   // A strategy seeded for an expiry (`OSA SPY --strategy put --expiration 2027-01-15`) opens that expiry's chain.
-  const [expiration, setExpiration] = usePluginPaneState<number | null>("chainExpiration", readOptionExpiration(settings.expiration));
+  const [pickedExpiration, setExpiration] = usePluginPaneState<number | null>("chainExpiration", readOptionExpiration(settings.expiration));
+  // A picked expiry that has since lapsed gives way to the nearest live one, as OMON's does.
+  const expiration = pickedExpiration != null && isLiveOptionExpiry(pickedExpiration, Date.now(), exchange) ? pickedExpiration : null;
   const [tab, setTab] = usePluginPaneState("activeTabId", "payoff");
   const [detail, setDetail] = useState<"chain" | "leg" | "save" | "inputs" | null>(null);
   const [editingLeg, setEditingLeg] = useState<ScenarioLeg | null>(null);
@@ -166,9 +168,11 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   const earningsDate = frozenEarnings ? settings.scenarioEarningsDate as string | null : earnings.data;
   // A position following the market is at the live print, which the footer names with its feed.
   const spotBasis = scenario && !live ? scenarioSpotBasis(settings, scenario.position, market) : null;
+  // The put's bid and ask: its streamed quote while the pane follows the market, else the chain's.
   const csp = useMemo(() => cspStrategy && scenario && !earnings.loading
-    ? cashSecuredPut(scenario.position, live?.basis ?? spotBasis ?? "last price", earningsDate) : null,
-  [cspStrategy, scenario, earnings.loading, earningsDate, live?.basis, spotBasis]);
+    ? cashSecuredPut(scenario.position, live?.basis ?? spotBasis ?? "last price", earningsDate,
+      seededLegQuotes(scenario.position, market?.chain, live?.quotes).get(scenario.position.legs[0]?.id ?? "")) : null,
+  [cspStrategy, scenario, earnings.loading, earningsDate, live?.basis, live?.quotes, spotBasis, market?.chain]);
   // A collar seeded, or one typed with the shares it hedges, as the report reads it.
   const collarStrategy = settings.strategy === "collar";
   const collar = useMemo(() => scenario && (collarStrategy || scenario.position.underlying)

package/src/plugins/builtin/perps/equity-row.tsx

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { useCallback, useMemo } from "react";
 import { isAccessDenied } from "../../../api-client/errors";
 import { usePlanAccess } from "../../../api-client/plan-access";
 import type { PerpBoardRow } from "../../../api-client/perps";
@@ -10,7 +10,9 @@ import { perpEquityIdentity } from "./equity-identity";
 import { perpetualListing } from "../../../tickers/perpetual-listing";
 import { loadPerpSelection, loadPerpsEquity } from "./client";
 import { compact, percent, perpDescription, price, readingTime } from "./model";
+import { useLivePerpRows } from "./live-rows";
 import { openPerpLabel, useOpenPerpMarket } from "./open-market";
+import { mergeVenueMarkets } from "./venue-markets";
 
 /**
  * A stock's perpetuals, or for a perpetual market itself its own contract: funding, open interest and when the venue
@@ -34,9 +36,15 @@ export function PerpEquityRow({ symbol, exchange, instrumentType, maxRows = 3, w
     : loadPerpsEquity({ symbol: listingSymbol!, exchange: listingExchange! }, accessKey, force), [marketId, listingSymbol, listingExchange, accessKey]);
   const resource = useAsyncResource(enabled ? loader : null, { clearOnError: isAccessDenied });
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
-  const rows = resource.data?.payload.rows.filter((row) => !row.delisted && (!marketId || row.marketId === marketId)) ?? [];
+  // A stock's contracts one per venue, deepest first, as DES lists them; the ones shown follow the quote stream.
+  const fetched = useMemo(() => {
+    const rows = resource.data?.payload.rows ?? [];
+    return marketId ? rows.filter((row) => !row.delisted && row.marketId === marketId) : mergeVenueMarkets(rows).map((market) => market.primary);
+  }, [marketId, resource.data]);
+  const shown = useMemo(() => fetched.slice(0, maxRows), [fetched, maxRows]);
+  const { rows } = useLivePerpRows(shown, { surface: marketId ? "detail" : "monitor", enabled });
   if (!enabled || !rows.length) return null;
-  return <>{rows.slice(0, maxRows).map((row) => <PerpRow key={row.marketId} row={row} stale={!!resource.data?.stale} width={width} own={!!marketId} />)}</>;
+  return <>{rows.map((row) => <PerpRow key={row.marketId} row={row} stale={!!resource.data?.stale} width={width} own={!!marketId} />)}</>;
 }
 
 /** The parts that fit `width`, dropped from the end; all of them when the width is not known. */

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

@@ -48,18 +48,21 @@ export function fundingNote(rows: readonly Funded[], now = Date.now()): string |
 }
 
 /**
- * How current a view of perpetual markets is: each venue's own newest observation, polled rather than streamed and
- * stale after an hour without a poll, and what the funding figures it shows (`funding`) are. The report, the capture
- * and the pane footer all read this, so they end with the same line.
+ * How current a view of perpetual markets is: each venue's own newest observation, read once a minute (live while
+ * every row followed has a price from its venue's socket within the minute) and stale after an hour without a read, and
+ * what the funding figures it shows (`funding`) are. The report, the capture and the pane footer all read this, so they
+ * end with the same line.
  */
-export function perpFreshness(rows: readonly Dated[], { funding = [], venue = "all", now = Date.now() }: {
+export function perpFreshness(rows: readonly Dated[], { funding = [], venue = "all", now = Date.now(), live = false }: {
   funding?: readonly Funded[]; venue?: string; now?: number;
+  /** Every row followed moves with its venue's socket: the view is a live feed, not the minute's read. */
+  live?: boolean;
 } = {}): HeadlessPaneFreshness {
   const sources = venuesOf(rows).map((id) => ({ source: venueName(id), asOf: new Date(Math.max(...rows.filter((row) => row.venue === id)
     .map((row) => Date.parse(row.observedAt)))).toISOString() }));
   const source = sources.length ? sources.map((entry) => entry.source).join(", ") : venue !== "all" ? venueName(venue) : null;
   const note = fundingNote(funding, now);
-  return { ...(source ? { source } : {}), sources, status: "delayed", maxAgeMinutes: 60, ...(note ? { note } : {}) };
+  return { ...(source ? { source } : {}), sources, status: live ? "live" : "delayed", maxAgeMinutes: 60, ...(note ? { note } : {}) };
 }
 
 /** What a capture reads of a row: when it was observed and whether the venue has stopped answering for it. */

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

@@ -89,8 +89,10 @@ const aprNote = (rows: readonly PerpBoardRow[]) => {
 const requestedOf = (args: HeadlessPaneLoadArgs) => String(Array.isArray(args.argument) ? args.argument.join(" ") : args.argument ?? "").trim();
 // No tab named: a market opens its history, nothing opens the board, as the pane does.
 const tabOf = (args: HeadlessPaneLoadArgs) => PERP_TABS.find((tab) => tab === args.options.tab) ?? openingTab(requestedOf(args));
+// A free account's market opens its latest values under the title, so the title names the function, not the Pro history: a table the free view
+// locks is left out and named on the report's one Pro line (`lockedTable`), never marked on the title over the free ones.
 const TITLES: Record<typeof PERP_TABS[number], string> = { board: "Perpetual markets", rankings: "Perpetual rankings", compare: "Perpetual contracts across venues",
-  history: "Perpetual history (Pro)", evidence: "Perpetual evidence (Pro)" };
+  history: "Perpetuals", evidence: "Perpetual evidence" };
 const copy = (rows: readonly PerpBoardRow[]) => rows.map((row) => ({ ...row }));
 const more = (count: number, noun: string) => `${count.toLocaleString("en-US")} more ${noun} need Gloom Pro`;
 // A table the free view leaves empty is locked: the report leaves it out and its one Pro line says what Pro adds.

package/src/plugins/builtin/perps/list-perpetuals.ts

@@ -8,6 +8,7 @@ import { useResearchCloudSession } from "../shared/research-cloud-session";
 import { perpetualListing } from "../../../tickers/perpetual-listing";
 import { loadPerpSelection, loadPerpsEquities } from "./client";
 import { perpEquityIdentity } from "./equity-identity";
+import { useLivePerpRows } from "./live-rows";
 
 const STOCK_TYPES = new Set(["STK", "EQUITY", "STOCK", "COMMON STOCK"]);
 const listingKey = (listing: PerpEquityListing) => `${listing.symbol}:${listing.exchange}`;
@@ -26,6 +27,7 @@ function rowListing(ticker: TickerRecord): PerpEquityListing | null {
 const rowMarket = (ticker: TickerRecord) => perpetualListing(ticker.metadata.ticker, ticker.metadata.exchange)?.marketId ?? null;
 
 const NO_PERPETUALS: ListPerpetuals = { markets: new Map(), version: 0, stale: false };
+const NO_SYMBOLS: ReadonlySet<string> = new Set();
 
 export interface ListPerpetuals {
   /** Each row's contract by ticker, null for none; a row is missing while its first answer loads. */
@@ -55,7 +57,7 @@ async function loadOwnMarket(marketId: string, access: string, force: boolean):
  * A row's figures never wait on anything else: rows without a stock listing read as no perpetual at once, and a
  * failed or refused lookup leaves every row without one, as DES leaves out its perpetual row.
  */
-export function useListPerpetuals(tickers: readonly TickerRecord[], enabled: boolean): ListPerpetuals {
+export function useListPerpetuals(tickers: readonly TickerRecord[], enabled: boolean, liveSymbols: ReadonlySet<string> = NO_SYMBOLS): ListPerpetuals {
   const session = useResearchCloudSession();
   const plan = usePlanAccess();
   const accessKey = `${session.requestKey}:${plan.hasProAccess ? "pro" : "preview"}`;
@@ -98,7 +100,7 @@ export function useListPerpetuals(tickers: readonly TickerRecord[], enabled: boo
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
   const versionRef = useRef(0);
   const { data, loading } = resource;
-  return useMemo(() => {
+  const fetched = useMemo(() => {
     if (!enabled) return NO_PERPETUALS;
     const byListing = new Map<string, PerpBoardRow | null>();
     data?.listings.forEach((listing, index) => byListing.set(listingKey(listing), data.results[index]?.market ?? null));
@@ -112,7 +114,26 @@ export function useListPerpetuals(tickers: readonly TickerRecord[], enabled: boo
       // Still loading: the row's cell waits. Otherwise there is nothing to show.
       else if ((!key && !market) || !loading) markets.set(ticker.metadata.ticker, null);
     }
-    versionRef.current += 1;
-    return { markets, version: versionRef.current, stale: !!data?.stale };
+    return { markets, version: 0, stale: !!data?.stale };
   }, [data, enabled, loading, tickers]);
+  // The contracts of the rows in view follow the quote stream, as many as useLivePerpRows follows; each is subscribed
+  // once however many rows share it.
+  const liveRows = useMemo(() => {
+    const rows = new Map<string, PerpBoardRow>();
+    for (const symbol of liveSymbols) {
+      const row = fetched.markets.get(symbol);
+      if (row) rows.set(row.marketId, row);
+    }
+    return [...rows.values()];
+  }, [fetched, liveSymbols]);
+  const live = useLivePerpRows(liveRows, { surface: "watchlist", enabled: enabled && liveRows.length > 0 });
+  return useMemo(() => {
+    if (fetched === NO_PERPETUALS) return NO_PERPETUALS;
+    const byMarket = new Map(live.rows.map((row) => [row.marketId, row]));
+    const markets = byMarket.size
+      ? new Map([...fetched.markets].map(([symbol, row]) => [symbol, row ? byMarket.get(row.marketId) ?? row : row]))
+      : fetched.markets;
+    versionRef.current += 1;
+    return { markets, version: versionRef.current, stale: fetched.stale };
+  }, [fetched, live.rows]);
 }

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>
+  );
+}