gloomberb 0.16.4 → 0.16.6

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

@@ -0,0 +1,118 @@
+import { useCallback, useMemo, useRef } from "react";
+import { isAccessDenied } from "../../../api-client/errors";
+import { usePlanAccess } from "../../../api-client/plan-access";
+import type { PerpBoardRow, PerpEquityListing } from "../../../api-client/perps";
+import { useAsyncResource, useAutoRefresh } from "../../../public/react";
+import type { TickerRecord } from "../../../types/ticker";
+import { useResearchCloudSession } from "../shared/research-cloud-session";
+import { perpetualListing } from "../../../tickers/perpetual-listing";
+import { loadPerpSelection, loadPerpsEquities } from "./client";
+import { perpEquityIdentity } from "./equity-identity";
+
+const STOCK_TYPES = new Set(["STK", "EQUITY", "STOCK", "COMMON STOCK"]);
+const listingKey = (listing: PerpEquityListing) => `${listing.symbol}:${listing.exchange}`;
+
+/**
+ * The listing a row asks about: a stock, or a saved ticker of no known type, on a venue the server can match.
+ * Read from the saved record, not the quote, so quotes arriving never change the request.
+ */
+function rowListing(ticker: TickerRecord): PerpEquityListing | null {
+  const type = ticker.metadata.assetCategory?.trim().toUpperCase();
+  if (type && !STOCK_TYPES.has(type)) return null;
+  return perpEquityIdentity(ticker.metadata.ticker, ticker.metadata.exchange);
+}
+
+/** A row that is a perpetual market itself: its own contract, by market id. */
+const rowMarket = (ticker: TickerRecord) => perpetualListing(ticker.metadata.ticker, ticker.metadata.exchange)?.marketId ?? null;
+
+const NO_PERPETUALS: ListPerpetuals = { markets: new Map(), version: 0, stale: false };
+
+export interface ListPerpetuals {
+  /** Each row's contract by ticker, null for none; a row is missing while its first answer loads. */
+  markets: ReadonlyMap<string, PerpBoardRow | null>;
+  /** Moves whenever `markets` does. */
+  version: number;
+  /** A refresh failed: the contracts shown are the last ones read. */
+  stale: boolean;
+}
+
+interface ListRequest { listings: PerpEquityListing[]; markets: string[] }
+
+/** A perpetual row's own market, as PERP reads one market; none when it cannot be read. */
+async function loadOwnMarket(marketId: string, access: string, force: boolean): Promise<{ row: PerpBoardRow | null; stale: boolean }> {
+  try {
+    const result = await loadPerpSelection(marketId, access, force);
+    return { row: result.payload.rows.find((row) => row.marketId === marketId) ?? null, stale: result.stale };
+  } catch (error) {
+    if (isAccessDenied(error)) throw error;
+    return { row: null, stale: true };
+  }
+}
+
+/**
+ * The perpetual of every row in a watchlist or portfolio, refreshed once a minute: a stock's from one batch request
+ * for the whole list, and a row that is itself a perpetual market its own contract, read as PERP reads one market.
+ * 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 {
+  const session = useResearchCloudSession();
+  const plan = usePlanAccess();
+  const accessKey = `${session.requestKey}:${plan.hasProAccess ? "pro" : "preview"}`;
+  // The list's listings and markets, sorted and unique, as one string: a reorder or a quote keeps the same request.
+  const requestKey = useMemo(() => {
+    if (!enabled) return "";
+    const listings = new Map<string, PerpEquityListing>();
+    const markets = new Set<string>();
+    for (const ticker of tickers) {
+      const market = rowMarket(ticker);
+      if (market) {
+        markets.add(market);
+        continue;
+      }
+      const listing = rowListing(ticker);
+      if (listing) listings.set(listingKey(listing), listing);
+    }
+    if (!listings.size && !markets.size) return "";
+    const request: ListRequest = {
+      listings: [...listings].sort(([a], [b]) => a.localeCompare(b)).map(([, listing]) => listing),
+      markets: [...markets].sort(),
+    };
+    return JSON.stringify(request);
+  }, [enabled, tickers]);
+  const loader = useCallback(async (force: boolean) => {
+    const { listings, markets } = JSON.parse(requestKey) as ListRequest;
+    const [equities, own] = await Promise.all([
+      listings.length ? loadPerpsEquities(listings, accessKey, force) : null,
+      Promise.all(markets.map((marketId) => loadOwnMarket(marketId, accessKey, force))),
+    ]);
+    return {
+      listings,
+      results: equities?.payload.results ?? [],
+      markets: new Map(markets.map((marketId, index) => [marketId, own[index]!.row] as const)),
+      stale: !!equities?.stale || own.some((market) => market.stale),
+    };
+  }, [accessKey, requestKey]);
+  // An added row waits for its own answer while the others keep theirs.
+  const resource = useAsyncResource(requestKey ? loader : null, { clearOnError: isAccessDenied, keepPreviousData: true });
+  useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
+  const versionRef = useRef(0);
+  const { data, loading } = resource;
+  return 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));
+    const markets = new Map<string, PerpBoardRow | null>();
+    for (const ticker of tickers) {
+      const market = rowMarket(ticker);
+      const listing = market ? null : rowListing(ticker);
+      const key = listing ? listingKey(listing) : null;
+      if (market && data?.markets.has(market)) markets.set(ticker.metadata.ticker, data.markets.get(market) ?? null);
+      else if (key && byListing.has(key)) markets.set(ticker.metadata.ticker, byListing.get(key) ?? null);
+      // 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 };
+  }, [data, enabled, loading, tickers]);
+}

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

@@ -3,6 +3,7 @@ import type { DataTableCell, DataTableColumn } from "../../../components";
 import { scalarPoint, staticSeries } from "../../../components/chart/static/series";
 import { getTableWidth } from "../../../components/ui/table-layout";
 import { formatCompact } from "../../../utils/format";
+import { isUsListingExchange, publicTickerKey } from "../../../utils/exchanges";
 import type { ThemeColors } from "../../../theme/colors";
 export const PERP_TABS = ["board", "rankings", "compare", "history", "evidence"] as const;
 export type PerpTab = typeof PERP_TABS[number];
@@ -21,6 +22,18 @@ export const compact = (n: number | null | undefined) => n == null ? "--" : form
 export const time = (s: string | null | undefined) => s ? `${s.slice(0, 10)} ${s.slice(11, 16)} UTC` : "--";
 /** A list row's observation, month to minute: the header names UTC and the footer the full as-of. */
 const observed = (s: string | null | undefined) => s ? `${s.slice(5, 10)} ${s.slice(11, 16)}` : "--";
+/**
+ * The listed security a market tracks, as DES, FA and G take it: a US listing by its symbol, the key a stock is
+ * saved and opened under, and a listing abroad with its venue (`NET:XLON`), so they open the security the premium
+ * is measured against. Null for crypto, indices, commodities and any market without one.
+ */
+export function underlyingTicker(row: Pick<PerpBoardRow, "underlyingSymbol" | "underlying" | "equityMatch">): string | null {
+  const symbol = row.underlyingSymbol?.trim().toUpperCase();
+  if (!symbol) return null;
+  const listing = row.equityMatch?.underlying.symbol.toUpperCase() === symbol ? row.equityMatch.underlying.exchange
+    : row.underlying?.symbol.toUpperCase() === symbol ? row.underlying.listingExchange : undefined;
+  return !listing || isUsListingExchange(listing) ? symbol : publicTickerKey(symbol, listing);
+}
 export const marketLabel = (row: PerpBoardRow) => row.dex && row.dex !== "default" ? `${row.baseAsset} · ${row.dex.toUpperCase()}` : row.baseAsset;
 /** What the contract is, in plain words: perpetual futures never expire and trade around the clock. */
 export const perpDescription = (row: Pick<PerpBoardRow, "venue">) =>
@@ -127,12 +140,14 @@ const PERP_COLUMNS: Record<PerpColumnId, DataTableColumn> = {
 };
 // Columns in reading order, then the order a narrow pane gives them up in.
 export const BOARD_COLUMNS: PerpColumnId[] = ["market", "venue", "markPrice", "fundingRate", "premium", "openInterestUsd", "oiChange24h", "longShare", "fundingApr", "priceChange24h", "observedAt"];
-// The venue goes last: the same market trades on several, and only the venue tells those rows apart. The long share
-// is what the board and the comparison are read for, so a 100-column pane keeps it and the annualised funding, which
-// only restates the funding rate, goes first (the 24h OI change next on the board, the per-interval rate on Compare).
-const BOARD_DROPS: PerpColumnId[] = ["observedAt", "fundingApr", "priceChange24h", "oiChange24h", "longShare", "premium", "markPrice", "openInterestUsd", "venue"];
+// The venue goes last: the same market trades on several, and only the venue tells those rows apart. Venues are polled
+// apart, so when each row was observed stays until only the venue is left to give up. The long share is what the board
+// and the comparison are read for, so a 100-column pane keeps it beside the observation time: the annualised funding,
+// which only restates the funding rate, goes first (the 24h OI change next on the board, the per-interval rate on
+// Compare), and the premium before the long share.
+const BOARD_DROPS: PerpColumnId[] = ["fundingApr", "priceChange24h", "oiChange24h", "premium", "longShare", "markPrice", "openInterestUsd", "observedAt", "venue"];
 export const COMPARE_COLUMNS: PerpColumnId[] = ["venue", "symbol", "markPrice", "fundingRate", "fundingRate8h", "premium", "openInterestUsd", "oiChange24h", "longShare", "fundingApr", "observedAt"];
-const COMPARE_DROPS: PerpColumnId[] = ["observedAt", "fundingApr", "oiChange24h", "fundingRate", "longShare", "premium", "markPrice", "openInterestUsd", "symbol"];
+const COMPARE_DROPS: PerpColumnId[] = ["fundingApr", "oiChange24h", "fundingRate", "premium", "longShare", "markPrice", "openInterestUsd", "observedAt", "symbol"];
 export const RANKING_COLUMNS: PerpColumnId[] = ["market", "venue", "value", "openInterestUsd"];
 
 /** The columns that fit the pane, the least read going first; before the last of them goes, a long market name gives up its tail. */

package/src/plugins/builtin/perps/open-market.ts

@@ -0,0 +1,15 @@
+import { useCallback } from "react";
+import type { PerpBoardRow } from "../../../api-client/perps";
+import { tf } from "../../../i18n";
+import { usePluginAppActions } from "../../../public/react";
+import { venueLabel } from "./model";
+
+/** Opens PERP on one market: where a stock's perpetual links from DES, QQ and the watchlist and portfolio columns. */
+export function useOpenPerpMarket(): (marketId: string) => void {
+  const { createPaneFromTemplate } = usePluginAppActions();
+  return useCallback((marketId: string) => createPaneFromTemplate("perps-pane", { arg: marketId }), [createPaneFromTemplate]);
+}
+
+/** The pane menu's entry for a link to one market. */
+export const openPerpLabel = (row: Pick<PerpBoardRow, "baseAsset" | "venue">) =>
+  tf("Open {label}", { label: `PERP ${row.baseAsset} · ${venueLabel(row)}` });

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

@@ -3,31 +3,67 @@ import { isAccessDenied } from "../../../api-client/errors";
 import { usePlanAccess } from "../../../api-client/plan-access";
 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 PaneHint, type SectionedRow, type StatItem } from "../../../components";
+  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";
 import { getSharedRegistry } from "../../registry/shared";
 import { SignInWall } from "../cloud/auth-actions";
 import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
+import { useCommandValue } from "../shared/command-tab";
+import { useOpenDescription } from "../shared/open-description";
 import { UpgradeLabel } from "../shared/locked-rows";
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
 import { cachedPerpSelection, cachedPerpsBoard, cachedPerpsCompare, cachedPerpsRankings, loadPerpSelection, loadPerpsBoard, loadPerpsCompare,
   loadPerpsHistoryForRange, loadPerpsRankings } from "./client";
+import { perpFreshness, perpObservation } from "./freshness";
 import { ASSET_FILTERS, BOARD_SORTS, boardColumns, compact, compareColumns, dayChange, fundingInterval, fundingSpread, historyCaption, historyCell, historyChange, historyColumns,
   HISTORY_METRICS, historyRows, historySeries, historyValue, inPoints, isMarketTab, label, longShortReason, marketLabel, metricLabel, openingTab, perpCell, PERP_TABS, percent,
-  positioningFields, price, rankingColumns, rankingRows, RANKINGS, ratioText, share, sortLabel, time, venueLabel, venueName, venuesOf, type HistoryMetric, type PerpColumnId,
-  type PerpTab, type RankingKey } from "./model";
+  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[] = [];
+
+/**
+ * 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[] {
+  const now = useAgeClock(since);
+  const declared = useMemo(() => rows.length ? perpFreshness(rows, { funding, now }) : null, [rows, funding, now]);
+  useRemoteUiNode(declared ? { role: "report-freshness", label: "Venue freshness", getMetadata: () => ({ ...declared, observations: rows.map(perpObservation) }) } : null);
+  return useMemo(() => {
+    if (!declared) return [];
+    const freshness = deriveHeadlessFreshness({ shape: "rows" }, { rows: rows.map(perpObservation), 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]);
+}
+
+type EvidenceField = [label: string, value: string, detail?: string, link?: KeyValueRowProps["link"]];
 
 function MarketEvidence({ row, data, width, height }: { row: PerpBoardRow; data: PerpMarketPayload; width: number; height: number }) {
   const desktop = !!useUiCapabilities().nativePaneChrome;
   const upgrade = useCloudUpgradeAction("perp");
+  const openDescription = useOpenDescription();
   const positioning = positioningFields(row);
+  // The security the premium is measured against opens its DES, as the `d` key does.
+  const security = underlyingTicker(row);
+  const listed: EvidenceField[] = security && row.underlying ? [["Ticker", row.underlying.symbol, row.underlying.listingExchange,
+    { label: tf("Open {ticker}", { ticker: row.underlying.symbol }), onOpen: () => openDescription(security) }]] : [];
   // Grouped as a trader reads a contract; a stock reference only for a market that has one.
-  const groups: Array<[string, Array<[string, string, string?]>]> = [
+  const groups: Array<[string, EvidenceField[]]> = [
     ["Market", [["Venue", venueLabel(row)], ["Contract symbol", row.symbol], ["Observed", time(row.observedAt)], ["Source as of", time(row.sourceAsOf)],
       ["Mark", `${price(row.markPrice)} ${row.quoteCurrency}`], ["Oracle", `${price(row.oraclePrice)} ${row.quoteCurrency}`], ["Premium vs oracle", percent(row.premium)]]],
     ["Funding", [["Funding", `${percent(row.fundingRate, 5)} / ${fundingInterval(row)}`, row.fundingKind === "last-paid" ? "Last paid" : row.fundingKind === "continuous" ? "Continuous rate" : "Current rate"],
@@ -36,16 +72,17 @@ function MarketEvidence({ row, data, width, height }: { row: PerpBoardRow; data:
       ...(row.nextFundingAt ? [["Next funding", time(row.nextFundingAt)] as [string, string]] : [])]],
     ["Open Interest", [["Open interest", `${compact(row.openInterestBase)} ${row.baseAsset} · ${compact(row.openInterestUsd)} USD`],
       ["OI change 1h / 24h", row.oiChange1h == null && row.oiChange24h == null ? "Collecting" : `${percent(row.oiChange1h, 2)} / ${percent(row.oiChange24h, 2)}`, "own snapshots"]]],
-    ...(positioning ? [["Positioning", positioning.map((field) => [field.label, field.text, field.detail])] as [string, Array<[string, string, string?]>]] : []),
-    ...(row.underlying ? [["Underlying", [["Underlying last", `${price(row.underlying.price)} ${row.underlying.currency}`, time(row.underlying.asOf)], ["Underlying session", row.underlying.marketState ?? "Unknown"],
-      ["Premium vs underlying", percent(row.underlyingPremium)], ["Closed-market premium", percent(row.closedMarketPremium)]]] as [string, Array<[string, string, string?]>]] : []),
+    ...(positioning ? [["Positioning", positioning.map((field) => [field.label, field.text, field.detail])] as [string, EvidenceField[]]] : []),
+    ...(row.underlying ? [["Underlying", [...listed, ["Underlying last", `${price(row.underlying.price)} ${row.underlying.currency}`, time(row.underlying.asOf)], ["Underlying session", row.underlying.marketState ?? "Unknown"],
+      ["Premium vs underlying", percent(row.underlyingPremium)], ["Closed-market premium", percent(row.closedMarketPremium)]]] as [string, EvidenceField[]]] : []),
     ["Contract", [["Contract", `${label(row.contractType)} · ${row.priceMultiplier}× price`], ["Margin", row.marginCurrency], ["Max leverage", row.maxLeverage == null ? "--" : `${row.maxLeverage}×`],
       ["Margin mode", row.isolatedOnly === null ? "Unspecified" : row.isolatedOnly ? "Isolated only" : "Cross / isolated"], ["Listing", row.delisted ? "Delisted" : "Active"], ["Confidence", label(row.confidence)]]],
   ];
+  // The ticker's link is not listed in the pane menu again: `d` there opens the same DES.
   return <ScrollBox scrollY width={width} height={desktop ? undefined : height} flexGrow={1} flexBasis={0} minHeight={0} contentOptions={{ paddingX: 1 }}>
     {groups.map(([title, fields]) => <Fragment key={title}>
       <SectionHeading title={title} />
-      {fields.map(([name, value, detail]) => <KeyValueRow key={name} labelWidth={25} label={name} value={value} detail={detail} />)}
+      {fields.map(([name, value, detail, link]) => <KeyValueRow key={name} labelWidth={25} label={name} value={value} detail={detail} link={link} />)}
     </Fragment>)}
     {data.evidence.length ? <SectionHeading title="Observation Revisions" /> : null}
     {data.evidence.map((entry) => {
@@ -86,8 +123,11 @@ function History({ market, accessKey, width, height, focused, range, metric, ref
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
   usePaneRefreshKey(() => { refreshMarket(); void resource.reload(); }, { focused });
   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);
   usePaneStatusFooter({ registrationId: "perps:history", loading: resource.loading, error: resource.error, stale: resource.data?.stale,
-    info: lastTime ? [{ id: "history-asof", parts: [{ text: `${historyCaption(data, metric)} · ${time(lastTime)}`, tone: "muted" }] }] : [] });
+    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,
     data?.truncated ? "History reached the 5,000-observation limit. Narrow the range for all observations." : null].filter((value): value is string => !!value) });
   const periodChange = rows.length > 1 && rows[0]!.value != null && rows.at(-1)!.value != null ? rows.at(-1)!.value! - rows[0]!.value! : null;
@@ -155,7 +195,6 @@ interface ListTabProps {
   onOpen: (row: PerpBoardRow) => void;
 }
 
-const asOfInfo = (id: string, asOf: string | null | undefined) => asOf ? [{ id, parts: [{ text: time(asOf), tone: "muted" as const }] }] : [];
 const moreText = (count: number, noun: string) => `Upgrade for ${count.toLocaleString("en-US")} more ${noun}`;
 
 /** The preview's lock: under the rows it shows, or in place of the rows when none of the preview matches. */
@@ -189,7 +228,8 @@ function Board({ accessKey, width, height, focused, onPick, onOpen }: ListTabPro
   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 });
-  usePaneStatusFooter({ registrationId: "perps:board", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale, info: asOfInfo("board-asof", data?.asOf) });
+  const line = usePerpStatusLine(rows, rows, resource.updatedAt);
+  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} />;
   const narrow = (apply: () => void) => { apply(); setSelected(null); };
@@ -232,7 +272,11 @@ function Rankings({ accessKey, width, height, focused, onPick, onOpen }: ListTab
   const columns = useMemo(() => rankingColumns(width), [width]);
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
   usePaneRefreshKey(() => { void resource.reload(); }, { focused });
-  usePaneStatusFooter({ registrationId: "perps:rankings", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale, info: asOfInfo("rankings-asof", data?.asOf) });
+  // 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);
+  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} />;
   const renderCell = (entry: SectionedRow<Ranked>, column: { id: string }): DataTableCell => {
@@ -266,15 +310,16 @@ 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 = data?.rows ?? [];
+  const rows = useMemo(() => data?.rows ?? [], [data]);
   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 spread = useMemo(() => fundingSpread(rows), [rows]);
   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 });
-  usePaneStatusFooter({ registrationId: "perps:compare", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale, info: asOfInfo("compare-asof", data?.asOf) });
+  usePaneStatusFooter({ registrationId: "perps:compare", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale, info: line });
   usePaneNoticeFooter({ registrationId: "perps:compare-notice", focused, notices: resource.data?.refreshError ? [resource.data.refreshError] : [] });
   if (!data && isCloudSessionRequired(resource.error)) return <SignInWall placement="perps-signin" action="compare perpetual venues" needsVerification={session.needsVerification} />;
   const figures: StatItem[] = spread ? [{ id: "spread", label: "Funding spread 8h", value: spread.text, detail: spread.detail }] : [];
@@ -311,13 +356,16 @@ export function PerpsPane({ width, height, focused, marketAction }: Pick<PanePro
   const access = usePlanAccess();
   const accessKey = `${session.requestKey}:${access.hasProAccess ? "pro" : "preview"}`;
   const { createPaneFromTemplate, notify } = usePluginAppActions();
+  const openDescription = useOpenDescription();
   const upgrade = useCloudUpgradeAction("perp");
   const [openingMarket] = usePaneSettingValue("market", "");
   const [openingTabValue] = usePaneSettingValue("tab", openingTab(openingMarket));
-  const [savedTab, setTab] = usePluginPaneState<string>("perps:tab", openingTabValue);
+  // 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 marketTab = isMarketTab(tab);
-  const [search, setSearch] = usePluginPaneState<string>("perps:search", openingMarket);
+  const [search, setSearch] = useCommandValue("perps", "perps:search", (params) => params.market || null, openingMarket);
   const [compareAsset, setCompareAsset] = usePluginPaneState<string>("perps:compare", compareOpening(openingMarket));
   // The row under a list's cursor, and the last one any list had: an empty list keeps the market it was given.
   const [listRow, setListRow] = useState<PerpBoardRow | null>(null);
@@ -349,7 +397,9 @@ export function PerpsPane({ width, height, focused, marketAction }: Pick<PanePro
   const refreshMarket = useCallback(() => { void resource.reload(); }, [resource.reload]);
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
   usePaneRefreshKey(refreshMarket, { focused: focused && marketTab && !querySearch.active && (tab !== "history" || !active) });
-  const navigate = (template: string) => { if (current?.underlyingSymbol) createPaneFromTemplate(template, { symbol: current.underlyingSymbol, arg: current.underlyingSymbol }); };
+  // The listed stock or fund a market tracks opens the way a ticker link does, on the DES already open for that
+  // listing when there is one; crypto, indices and commodities have none.
+  const underlying = current ? underlyingTicker(current) : null;
   const preview = marketTab ? data?.access === "preview" : !access.hasProAccess;
   const hints: PaneHint[] = [
     ...(current && marketAction ? [{ id: marketAction.id, key: marketAction.key, label: marketAction.label, onPress: () => marketAction.onPress(current) }] : []),
@@ -358,11 +408,17 @@ export function PerpsPane({ width, height, focused, marketAction }: Pick<PanePro
     } }] : []),
     ...(current && tab !== "evidence" ? [{ id: "evidence", key: "e", label: "vidence", onPress: () => marketTab ? setTab("evidence") : openMarket(current, "evidence") }] : []),
     ...(current ? [{ id: "source", key: "o", label: "pen source", onPress: () => void host.openExternal(current.sourceUrl) }] : []),
-    ...(current?.underlyingSymbol ? [{ id: "description", key: "d", label: "es", onPress: () => navigate("new-ticker-detail-pane") }, { id: "financials", key: "f", label: "a", onPress: () => navigate("financial-analysis-pane") }, { id: "graph", key: "g", label: "raph", onPress: () => navigate("chart-composer-pane") }] : []),
+    ...(underlying ? [{ id: "description", key: "d", label: "es", title: "Description (DES)", onPress: () => openDescription(underlying) },
+      // A fund has no statements to analyse.
+      ...(current?.assetClass === "stocks" ? [{ id: "financials", key: "f", label: "a", title: "Financial analysis (FA)", onPress: () => createPaneFromTemplate("financial-analysis-pane", { symbol: underlying }) }] : []),
+      { id: "graph", key: "g", label: "raph", title: "Price chart (G)", onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: underlying }) }] : []),
     ...(preview ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: upgrade }] : []),
   ];
-  usePaneStatusFooter({ registrationId: "perps", loading: marketTab && resource.loading, error: data ? resource.error : null, stale: marketTab && (resource.data?.stale || !!active?.stale),
-    info: active && (tab === "evidence" || data?.access === "preview") ? [{ id: "asof", parts: [{ text: time(active.observedAt), tone: "muted" }] }] : [], hints });
+  // 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);
+  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,
     ...(active?.qualityFlags.map((flag) => flag.replaceAll("_", " ").replaceAll("-", " ")) ?? [])].filter((s): s is string => !!s) : [] });
   if (marketTab && !data && isCloudSessionRequired(resource.error)) return <SignInWall placement="perps-signin" action="view perpetual history" needsVerification={session.needsVerification} />;

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

@@ -0,0 +1,76 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { fetchPerpSelection, fetchPerpsCompare, fetchPerpsHistory } from "./client";
+import { historyRows, type HistoryMetric } from "./model";
+
+/** The coin a pair names: BTC-USD charts the BTC perpetual. */
+function baseAsset(ticker: string): string {
+  return ticker.trim().toUpperCase().split(/[-/]/)[0] ?? ticker;
+}
+
+/** What the perps pane says where the free preview leaves history out. */
+const PRO_HISTORY = "Full history requires Gloom Pro.";
+
+const METRICS: ReadonlyArray<{ metric: HistoryMetric; name: string; unit: string; scale: number; tags: readonly string[] }> = [
+  { metric: "funding", name: "Perpetual funding rate (8h)", unit: "%", scale: 100, tags: ["funding", "carry"] },
+  { metric: "oi", name: "Perpetual open interest", unit: "USD", scale: 1, tags: ["open interest", "OI", "leverage"] },
+  { metric: "premium", name: "Perpetual premium to index", unit: "%", scale: 100, tags: ["premium", "basis"] },
+];
+
+const historyStart = (start: Date | undefined) => (start ?? new Date(Date.now() - 90 * 86_400_000)).toISOString();
+
+/**
+ * A coin's main perpetual contract, as the perps pane picks it, by the
+ * history its detail charts: funding, open interest and premium.
+ */
+const METRIC_SERIES: readonly SeriesDefinition[] = METRICS.map(({ metric, name, unit, scale, tags }): SeriesDefinition => ({
+  id: `perps:${metric}`,
+  name,
+  unit,
+  frequency: "intraday",
+  group: "Crypto",
+  tags: ["perpetual", "perps", ...tags],
+  input: "crypto",
+  load: async ({ ticker, start }) => {
+    const market = await fetchPerpSelection(baseAsset(ticker!));
+    const marketId = market.rows[0]?.marketId;
+    if (!marketId) throw new Error(`No perpetual contract for ${baseAsset(ticker!)}.`);
+    const history = await fetchPerpsHistory({
+      marketId,
+      from: historyStart(start),
+      resolution: "auto",
+      limit: 5000,
+    });
+    if (history.locked) throw new Error(PRO_HISTORY);
+    return historyRows(history, metric).map((row) => ({ date: row.time, value: row.value == null ? null : row.value * scale }));
+  },
+}));
+
+/**
+ * The share of accounts long a coin's perpetual, as the perps pane charts it
+ * for a contract whose venue publishes one. Venues count accounts their own
+ * way and only some publish a ratio, so the series reads the coin's largest
+ * contract that does. History is Pro's.
+ */
+const LONG_SHORT_SERIES: SeriesDefinition = {
+  id: "perps:long-accounts",
+  name: "Perpetual long account share",
+  unit: "%",
+  frequency: "intraday",
+  group: "Crypto",
+  tags: ["perpetual", "perps", "long/short", "long short ratio", "accounts", "positioning"],
+  description: "Share of accounts long the coin's largest perpetual contract whose venue publishes a long/short account ratio, hour by hour, as PERP charts it. Needs Pro.",
+  input: "crypto",
+  load: async ({ ticker, start }) => {
+    const base = baseAsset(ticker!);
+    const contracts = await fetchPerpsCompare(base);
+    if (contracts.access === "preview") throw new Error(PRO_HISTORY);
+    // The server lists a coin's contracts by open interest, largest first.
+    const market = contracts.rows.find((row) => !row.delisted && row.longShortRatio);
+    if (!market) throw new Error(`No ${base} perpetual contract publishes a long/short account ratio.`);
+    const history = await fetchPerpsHistory({ marketId: market.marketId, from: historyStart(start), resolution: "auto", limit: 5000 });
+    if (history.locked) throw new Error(PRO_HISTORY);
+    return historyRows(history, "long-short").map((row) => ({ date: row.time, value: row.value == null ? null : row.value * 100 }));
+  },
+};
+
+export const PERP_SERIES: readonly SeriesDefinition[] = [...METRIC_SERIES, LONG_SHORT_SERIES];

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

@@ -1,6 +1,6 @@
 import { PLUGIN_AUTO_UPDATE_SETTING } from "../../auto-update";
 import type { PluginModule } from "../plugin-module";
-import { PLUGIN_MARKETPLACE_PANE_ID } from "./ids";
+import { PLUGIN_MARKETPLACE_PANE_ID } from "../../marketplace/ids";
 import { PluginMarketplacePane } from "./pane";
 
 export const pluginMarketplaceModule: PluginModule = {