gloomberb 0.16.3 → 0.16.5

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,7 +22,29 @@ 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">) =>
+  `Perpetual futures (24/7 ${row.venue === "hyperliquid" || row.venue === "dydx" ? "on-chain" : venueName(row.venue)} market)`;
+/** When the venue's figures were read, in UTC: the time alone for today, with the date for an older reading. */
+export function readingTime(observedAt: string | null | undefined, now = Date.now()): string | null {
+  const read = observedAt ? Date.parse(observedAt) : Number.NaN;
+  if (!Number.isFinite(read)) return null;
+  const iso = new Date(read).toISOString();
+  return `${iso.slice(0, 10) === new Date(now).toISOString().slice(0, 10) ? "" : `${iso.slice(0, 10)} `}${iso.slice(11, 16)} UTC`;
+}
 export const fundingInterval = (row: Pick<PerpBoardRow, "fundingIntervalHours" | "fundingKind">) => row.fundingIntervalHours ? `${row.fundingIntervalHours}h${row.fundingKind === "last-paid" ? " paid" : row.fundingKind === "continuous" ? " continuous" : ""}` : "--";
 export const HISTORY_METRICS = ["funding", "oi", "premium", "price", "long-short"] as const;
 export type HistoryMetric = typeof HISTORY_METRICS[number];
@@ -116,12 +139,15 @@ const PERP_COLUMNS: Record<PerpColumnId, DataTableColumn> = {
   value: { id: "value", label: "Value %", width: 10, align: "right" },
 };
 // Columns in reading order, then the order a narrow pane gives them up in.
-export const BOARD_COLUMNS: PerpColumnId[] = ["market", "venue", "markPrice", "fundingRate", "fundingApr", "premium", "openInterestUsd", "oiChange24h", "longShare", "priceChange24h", "observedAt"];
-// The venue goes last: the same market trades on several, and only the venue tells those rows apart. The long share
-// gives way before every figure a 100-column pane already showed, so it never pushes one of those off.
-const BOARD_DROPS: PerpColumnId[] = ["observedAt", "priceChange24h", "fundingApr", "longShare", "oiChange24h", "premium", "markPrice", "openInterestUsd", "venue"];
-export const COMPARE_COLUMNS: PerpColumnId[] = ["venue", "symbol", "markPrice", "fundingRate", "fundingRate8h", "fundingApr", "premium", "openInterestUsd", "oiChange24h", "longShare", "observedAt"];
-const COMPARE_DROPS: PerpColumnId[] = ["observedAt", "oiChange24h", "fundingApr", "longShare", "fundingRate", "premium", "markPrice", "openInterestUsd", "symbol"];
+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. 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[] = ["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/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/model.ts

@@ -1,6 +1,10 @@
 import type { PluginTarget } from "../../../types/plugin";
 import { compareSemver, formatVersion, requiredGloomberb } from "../../../utils/semver";
 import { runsExternalPlugins } from "../../current-target";
+import { BUILTIN_EDITORIAL } from "../../builtin-editorial";
+import { builtinPluginGroupMembers } from "../../ownership";
+import type { FunctionAccess } from "../../../cli/pane-functions/function-help";
+import { PACK_PLUGIN_IDS } from "./packs";
 
 type PluginTier = "official" | "verified" | "community";
 
@@ -9,6 +13,8 @@ export interface RegistryPluginShortcut {
   code: string;
   name: string;
   description: string;
+  /** Built-ins only: what Free gets of it. */
+  access?: FunctionAccess;
 }
 
 /** One record from https://plugins.gloom.sh/registry.json. */
@@ -28,7 +34,7 @@ export interface RegistryPlugin {
     panes: string[];
     capabilities: string[];
     broker: boolean;
-    /** Declared in the plugin's gloom.json; absent from older feeds and from built-ins. */
+    /** Declared in the plugin's gloom.json, or listed for a built-in; absent from older feeds. */
     shortcuts?: RegistryPluginShortcut[];
   };
   minGloomberb?: string;
@@ -78,7 +84,11 @@ export interface InstalledPlugin {
   needsRestart?: boolean;
 }
 
-export type MarketplaceSection = "installed" | "available" | "builtin";
+/**
+ * `research` holds the built-ins starter packs switch, so a pack's reach is
+ * the section above the others; `builtin` the other built-ins.
+ */
+export type MarketplaceSection = "research" | "builtin" | "installed" | "available";
 
 export interface MarketplaceEntry {
   id: string;
@@ -131,8 +141,8 @@ export interface MarketplaceEntry {
 
 const TIER_RANK: Record<PluginTier, number> = { official: 0, verified: 1, community: 2 };
 
-function sectionOf(entry: { installed: boolean; bundled: boolean }): MarketplaceSection {
-  if (entry.bundled) return "builtin";
+function sectionOf(entry: { id: string; installed: boolean; bundled: boolean }): MarketplaceSection {
+  if (entry.bundled) return PACK_PLUGIN_IDS.includes(entry.id) ? "research" : "builtin";
   return entry.installed ? "installed" : "available";
 }
 
@@ -151,6 +161,11 @@ function repoDirectory(repo: string | undefined): string | null {
   return name ? name.toLowerCase() : null;
 }
 
+/** The short line a built-in's row reads: its editorial tagline, else its description. */
+function builtinTagline(local: InstalledPlugin): string {
+  return BUILTIN_EDITORIAL[local.id]?.tagline ?? local.description ?? "";
+}
+
 export function mergeCatalog(options: {
   registry: readonly RegistryPlugin[];
   /** Remote default-branch heads by plugin folder, from `PluginManager.remoteHeads`. */
@@ -158,7 +173,11 @@ export function mergeCatalog(options: {
   installed: readonly InstalledPlugin[];
   target: PluginTarget;
 }): MarketplaceEntry[] {
-  const { registry, installed, target, remoteHeads } = options;
+  const { installed, target, remoteHeads } = options;
+  // A built-in this build split into several, which a feed generated before
+  // the split still lists. Its id now only switches its successors together,
+  // and they have rows of their own.
+  const registry = options.registry.filter((plugin) => !(plugin.bundled && builtinPluginGroupMembers(plugin.id)));
   const remoteHeadFor = (local: InstalledPlugin | undefined) => (
     local?.directory ? remoteHeads?.[local.directory] : undefined
   );
@@ -193,6 +212,9 @@ export function mergeCatalog(options: {
 
   for (const plugin of registry) {
     const local = localFor.get(plugin.id);
+    // The feed lags the app: a built-in this build renamed or redescribed
+    // reads the way the running app has it.
+    const builtin = local?.source === "builtin" ? local : null;
 
     const base = {
       // A bundled plugin is present whether or not the local catalog reports it,
@@ -205,10 +227,10 @@ export function mergeCatalog(options: {
     };
     entries.push({
       id: plugin.id,
-      name: plugin.name,
-      tagline: plugin.tagline,
-      description: plugin.description,
-      categories: plugin.categories,
+      name: builtin?.name ?? plugin.name,
+      tagline: builtin ? builtinTagline(builtin) : plugin.tagline,
+      description: builtin?.description ?? plugin.description,
+      categories: builtin ? BUILTIN_EDITORIAL[plugin.id]?.categories ?? plugin.categories : plugin.categories,
       tier: plugin.tier,
       targets: plugin.targets,
       hosts: plugin.hosts,
@@ -246,7 +268,7 @@ export function mergeCatalog(options: {
         : plugin.bundled
           ? !plugin.targets.includes(target)
           : !runsExternalPlugins(target) || !plugin.targets.includes(target),
-      section: sectionOf(base),
+      section: sectionOf({ id: plugin.id, ...base }),
     });
   }
 
@@ -257,10 +279,13 @@ export function mergeCatalog(options: {
     entries.push({
       id: local.id,
       name: local.name,
-      tagline: local.description ?? (local.linked ? "Linked from a local checkout" : "Installed outside the registry"),
+      tagline: local.source === "builtin"
+        ? builtinTagline(local)
+        : local.description ?? (local.linked ? "Linked from a local checkout" : "Installed outside the registry"),
       description: local.description,
-      categories: local.source === "builtin" ? [] : ["unlisted"],
-      tier: "community",
+      categories: local.source === "builtin" ? [...BUILTIN_EDITORIAL[local.id]?.categories ?? []] : ["unlisted"],
+      // Shipped by Gloom like every built-in, whether or not the feed lists it.
+      tier: local.source === "builtin" ? "official" : "community",
       targets: local.unsupportedTarget ? [] : [target],
       hosts: [],
       stars: 0,
@@ -282,7 +307,7 @@ export function mergeCatalog(options: {
       lastError: local.lastError,
       needsRestart: local.needsRestart === true,
       unsupportedHere: !!local.unsupportedTarget,
-      section: sectionOf(base),
+      section: sectionOf({ id: local.id, ...base }),
     });
   }
 
@@ -366,6 +391,12 @@ export interface MarketplaceStatus {
   text: string;
 }
 
+/**
+ * The built-in the research pane, DES and the G charts come from. It can be
+ * switched off, after a confirmation, and every starter pack keeps it on.
+ */
+export const CORE_PLUGIN_ID = "ticker-core";
+
 /**
  * One word for "what should I do about this row". Health outranks state:
  * a plugin that is enabled but failed to load is `failed`, not `enabled`.
@@ -383,21 +414,32 @@ export function statusOf(entry: MarketplaceEntry): MarketplaceStatus {
   const required = requiredGloomberb(entry.minGloomberb);
   const needsGloomberb: MarketplaceStatus | null = required ? { kind: "needs-gloomberb", text: `needs ${required}` } : null;
   if (!entry.installed) return needsGloomberb ?? { kind: "none", text: "" };
-  if (!entry.enabled) return { kind: "disabled", text: "disabled" };
+  if (!entry.enabled) return { kind: "disabled", text: "off" };
+  if (entry.id === CORE_PLUGIN_ID && entry.bundled) return { kind: "enabled", text: "core" };
   if (entry.needsSetup) return { kind: "needs-setup", text: "needs setup" };
   if (hasUpdate(entry)) return needsGloomberb ?? { kind: "update", text: "update" };
   if (entry.errorCount > 0) return { kind: "errors", text: `errors (${entry.errorCount})` };
-  return { kind: "enabled", text: "enabled" };
+  return { kind: "enabled", text: "on" };
+}
+
+/** Whether a section lists plugins that ship inside Gloomberb. */
+function isBuiltinSection(section: MarketplaceSection): boolean {
+  return section === "research" || section === "builtin";
 }
 
 /**
- * Sorted for a sectioned list: installed, then available, then built in;
- * within a section the curated order: featured, then tier, then stars.
+ * Sorted for a sectioned list: the research built-ins in pack order, the
+ * other built-ins, then installed, then available; within the last two the
+ * curated order: featured, then tier, then stars.
  */
 export function sortEntries(entries: readonly MarketplaceEntry[]): MarketplaceEntry[] {
-  const SECTION_RANK: Record<MarketplaceSection, number> = { installed: 0, available: 1, builtin: 2 };
+  const SECTION_RANK: Record<MarketplaceSection, number> = { research: 0, builtin: 1, installed: 2, available: 3 };
   return [...entries].sort((a, b) => {
     if (a.section !== b.section) return SECTION_RANK[a.section] - SECTION_RANK[b.section];
+    if (a.section === "research") return PACK_PLUGIN_IDS.indexOf(a.id) - PACK_PLUGIN_IDS.indexOf(b.id);
+    // The other built-ins read alphabetically after the featured one: a
+    // repository's stars say nothing about something built in.
+    if (a.section === "builtin" && a.featured === b.featured) return a.name.localeCompare(b.name);
     if (a.featured !== b.featured) return a.featured ? -1 : 1;
     if (a.tier !== b.tier) return TIER_RANK[a.tier] - TIER_RANK[b.tier];
     if (a.stars !== b.stars) return b.stars - a.stars;
@@ -413,8 +455,8 @@ export function filterEntries(
 
   return entries.filter((entry) => {
     // Core modules with no switch are not something the user manages; a
-    // toggleable built-in is, but only on request.
-    if (entry.section === "builtin" && (!entry.toggleable || !options.showBuiltin)) return false;
+    // toggleable built-in is, unless the built-in filter is off.
+    if (isBuiltinSection(entry.section) && (!entry.toggleable || !options.showBuiltin)) return false;
     if (options.category && !entry.categories.includes(options.category)) return false;
     if (!query) return true;
     return [entry.name, entry.id, entry.tagline, entry.description, ...entry.categories]
@@ -435,6 +477,7 @@ export type MarketplaceRow =
   | { type: "entry"; entry: MarketplaceEntry };
 
 export const SECTION_LABELS: Record<MarketplaceSection, string> = {
+  research: "Research and markets",
   installed: "Installed",
   available: "Available",
   builtin: "Built in",