gloomberb 0.16.0 → 0.16.2

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

@@ -4,19 +4,21 @@ import { usePlanAccess } from "../../../api-client/plan-access";
 import { ActionRow } from "../../../components";
 import { useAsyncResource, useAutoRefresh, usePluginAppActions } from "../../../public/react";
 import { useResearchCloudSession } from "../shared/research-cloud-session";
-import { listingIdentity } from "../shared/ticker-request";
+import { perpEquityIdentity } from "./equity-identity";
 import { loadPerpsEquity } from "./client";
 import { compact, marketLabel, percent, price } from "./model";
 
 /** A failed optional market comparison never blocks a stock's quote. */
-export function PerpEquityRow({ symbol, instrumentType, maxRows = 3 }: { symbol: string; instrumentType?: string; maxRows?: number }) {
+export function PerpEquityRow({ symbol, exchange, instrumentType, maxRows = 3 }: { symbol: string; exchange?: string; instrumentType?: string; maxRows?: number }) {
   const session = useResearchCloudSession();
   const plan = usePlanAccess();
   const { createPaneFromTemplate } = usePluginAppActions();
-  const identity = listingIdentity(symbol)?.symbol;
+  const identity = perpEquityIdentity(symbol, exchange);
+  const listingSymbol = identity?.symbol;
+  const listingExchange = identity?.exchange;
   const enabled = !!identity && ["STK", "EQUITY", "STOCK", "COMMON STOCK"].includes(instrumentType?.toUpperCase() ?? "");
   const accessKey = `${session.requestKey}:${plan.hasProAccess ? "pro" : "preview"}`;
-  const loader = useCallback((force: boolean) => loadPerpsEquity(identity!, accessKey, force), [identity, accessKey]);
+  const loader = useCallback((force: boolean) => loadPerpsEquity({ symbol: listingSymbol!, exchange: listingExchange! }, accessKey, force), [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) ?? [];

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

@@ -1,32 +1,160 @@
+import type { PerpBoardPayload, PerpBoardRow } from "../../../api-client/perps";
+import type { HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneLoadArgs, HeadlessPaneRow } from "../../../types/headless";
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
-import { fetchPerpSelection, fetchPerpsHistory } from "./client";
-import { PERP_TABS } from "./model";
+import { fetchPerpSelection, fetchPerpsBoard, fetchPerpsCompare, fetchPerpsHistory, fetchPerpsRankings } from "./client";
+import { ASSET_FILTERS, BOARD_COLUMNS, BOARD_SORTS, COMPARE_COLUMNS, compact, fundingSpread, HISTORY_METRICS, label, openingTab, PERP_TABS, perpCellText, perpColumnLabel, percent,
+  positioningFields, price, RANKING_COLUMNS, rankingRows, RANKINGS, ratioText, share, time, VENUES, venueLabel, venueName, venuesOf, type PerpColumnId } from "./model";
+
+// Text columns only: the text report shows these, JSON keeps every field of every row. Rates, premiums and
+// changes stay fractions in the rows; `percent` multiplies by 100 so the text agrees with the desktop pane.
+const num = (value: unknown) => typeof value === "number" && Number.isFinite(value) ? value : null;
+const text = (value: unknown) => typeof value === "string" ? value : null;
+const pct = (digits: number): HeadlessPaneColumn["format"] => (value) => percent(num(value), digits);
+const rateOver = (rate: unknown, interval: string | null, digits = 5) => num(rate) === null ? "--" : `${percent(num(rate), digits)} /${interval ?? "--"}`;
+const hours = (value: unknown) => num(value) ? `${num(value)}h` : null;
+const timeColumn = (key: string, header: string): HeadlessPaneColumn => ({ key, header, format: (value) => time(text(value)) });
+const right = (key: string, header: string, format: HeadlessPaneColumn["format"]): HeadlessPaneColumn => ({ key, header, align: "right", format });
+const priceColumn = (key: string, header: string) => right(key, header, (value) => price(num(value)));
+const oiColumn = right("openInterestUsd", "OI USD", (value) => compact(num(value)));
+
+const asMarket = (row: HeadlessPaneRow) => row as unknown as PerpBoardRow;
+// The board, comparison and ranking columns print what the pane's cells show, through the same formatter.
+const RIGHT = new Set<PerpColumnId>(["markPrice", "fundingRate", "fundingRate8h", "fundingApr", "premium", "openInterestUsd", "oiChange24h", "longShare", "priceChange24h", "value"]);
+const KEYS: Partial<Record<PerpColumnId, string>> = { market: "baseAsset", longShare: "longShortRatio" };
+const DESCRIPTIONS: Partial<Record<PerpColumnId, string>> = { longShare: "Share of accounts net long on the contract, by each venue's own definition and hourly bucket" };
+const perpColumn = (id: PerpColumnId): HeadlessPaneColumn => ({ key: KEYS[id] ?? id, header: perpColumnLabel(id), ...(RIGHT.has(id) ? { align: "right" as const } : {}),
+  ...(DESCRIPTIONS[id] ? { description: DESCRIPTIONS[id] } : {}), format: (_, row) => perpCellText(asMarket(row), id) });
+// One market's row keeps its full observation time, as it always printed.
+const MARKET_COLUMNS: HeadlessPaneColumn[] = BOARD_COLUMNS.filter((id) => id !== "oiChange24h").map((id) => id === "observedAt" ? timeColumn("observedAt", "Observed") : perpColumn(id));
+const BOARD_TEXT_COLUMNS = BOARD_COLUMNS.map(perpColumn);
+const COMPARE_TEXT_COLUMNS = COMPARE_COLUMNS.map(perpColumn);
+const rankingTextColumns = (ranking: typeof RANKINGS[number]): HeadlessPaneColumn[] => RANKING_COLUMNS.map((id) => id === "value"
+  ? right(ranking.field, ranking.header, pct(ranking.digits)) : perpColumn(id));
+const observationColumns = (currency: string): HeadlessPaneColumn[] => [
+  timeColumn("time", "Time"),
+  { key: "resolution", header: "Resolution", format: (value) => text(value) ?? "--" },
+  priceColumn("markPrice", `Mark ${currency}`),
+  right("premium", "Premium %", pct(3)),
+  right("fundingRate", "Funding %/int", (value, row) => rateOver(value, hours(row.fundingIntervalHours))),
+  oiColumn,
+  right("sampleCount", "Samples", (value) => `${num(value) ?? "--"}`),
+];
+const FUNDING_COLUMNS: HeadlessPaneColumn[] = [
+  timeColumn("time", "Time"),
+  right("rate", "Paid %/int", (value, row) => rateOver(value, hours(row.intervalHours))),
+  right("rate", "Funding 8h %", (value, row) => num(value) !== null && num(row.intervalHours) ? percent(num(value)! * 8 / num(row.intervalHours)!, 4) : "--"),
+  right("premium", "Premium %", pct(3)),
+  timeColumn("observedAt", "Observed"),
+];
+const candleColumns = (currency: string): HeadlessPaneColumn[] => [
+  timeColumn("time", "Time"),
+  priceColumn("open", "Open"), priceColumn("high", "High"), priceColumn("low", "Low"), priceColumn("close", `Close ${currency}`),
+  right("volumeBase", "Volume (base)", (value) => compact(num(value))),
+  right("trades", "Trades", (value) => num(value)?.toLocaleString("en-US") ?? "--"),
+];
+const LONG_SHORT_COLUMNS: HeadlessPaneColumn[] = [
+  timeColumn("time", "Bucket"),
+  right("longShare", "Long %", (value) => share(num(value), 2)),
+  right("shortShare", "Short %", (value) => share(num(value), 2)),
+  right("ratio", "Ratio", (value) => ratioText(num(value))),
+  { key: "derived", header: "Shares", format: (value) => value === true ? "From ratio" : "Published" },
+  timeColumn("observedAt", "Observed"),
+];
+const REVISION_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "kind", header: "Kind", format: (value) => text(value) ? label(text(value)!) : "--" },
+  timeColumn("period_at", "Period"),
+  timeColumn("received_at", "Received"),
+  { key: "superseded_at", header: "Status", format: (value) => text(value) ? `Superseded ${time(text(value))}` : "Current" },
+  { key: "fingerprint", header: "Fingerprint", format: (value) => text(value)?.slice(0, 8) || "--" },
+];
+
+// With no market the report shows the first; a market nothing matches names the others as examples.
+const EXAMPLE_MARKETS = ["BTC", "ETH", "SOL"] as const;
+const DEFAULT_MARKET = EXAMPLE_MARKETS[0];
+
+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));
+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)" };
+const copy = (rows: readonly PerpBoardRow[]) => rows.map((row) => ({ ...row }));
+const more = (count: number, noun: string) => `${count.toLocaleString("en-US")} more ${noun} need Gloom Pro`;
+// Many venues' markets, each as last polled: cited by venue, stale after an hour without a poll.
+const listFreshness = (rows: readonly PerpBoardRow[], asOf: string | null, venue = "all") => {
+  const source = rows.length ? venuesOf(rows).map(venueName).join(", ") : venue !== "all" ? venueName(venue) : null;
+  return { ...(source ? { source } : {}), status: "delayed" as const, asOf, maxAgeMinutes: 60 };
+};
+const listMetadata = (data: Pick<PerpBoardPayload, "asOf" | "access" | "status"> & { locked: number | boolean }) => ({ asOf: data.asOf, access: data.access, locked: data.locked, status: data.status, rates: "fraction", oiCurrency: "USD" });
 
 export const perpsHeadless: HeadlessPaneDefinition<"bundle"> = {
-  shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "market", description: "Underlying or canonical market identity, such as BTC or hyperliquid:xyz:TSLA." },
+  shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "market",
+    description: "A base asset, underlying or canonical market identity, such as BTC or hyperliquid:xyz:TSLA. Opens its history; with --tab board it searches the board, with --tab compare it is the base asset. Without one, the board." },
   options: [
-    { key: "tab", type: "enum", settingKey: "tab", values: PERP_TABS.map((value) => ({ value })), defaultValue: "history", description: "Per-market history or evidence." },
+    { key: "tab", type: "enum", settingKey: "tab", values: PERP_TABS.map((value) => ({ value })), description: "Board, rankings, compare, history or evidence. Board without a market, history with one." },
+    { key: "asset-class", type: "enum", settingKey: "assetClass", values: ASSET_FILTERS.map((value) => ({ value })), defaultValue: "all", description: "Board asset class." },
+    { key: "venue", type: "enum", settingKey: "venue", values: ["all", ...VENUES].map((value) => ({ value })), defaultValue: "all", description: "Board venue." },
+    { key: "sort", type: "enum", settingKey: "sort", values: BOARD_SORTS.map((value) => ({ value })), defaultValue: "oi", description: "Board order: open interest, funding, open-interest change, premium or long share of accounts." },
     { key: "days", type: "enum", settingKey: "days", values: ["1", "7", "30", "90", "365"].map((value) => ({ value })), defaultValue: "7", description: "History lookback in days." },
-    { key: "metric", type: "enum", settingKey: "metric", values: ["funding", "oi", "premium", "price"].map((value) => ({ value })), defaultValue: "funding", description: "Displayed history chart; JSON retains every series." },
+    { key: "metric", type: "enum", settingKey: "metric", values: HISTORY_METRICS.map((value) => ({ value })), defaultValue: "funding", description: "Displayed history chart; JSON retains every series." },
   ],
-  discovery: { aliases: ["PERP"], dataRequirements: ["Perpetual market observations"], limitations: ["Pro history with latest-value free previews", "Rates, premiums and changes are fractions in JSON", "Open-interest history begins at first collection", "Funding APR is a simple annualization, not a forecast"] },
-  describe: "Perpetual history and evidence (Pro)",
+  discovery: { aliases: ["PERP"], dataRequirements: ["Perpetual market observations"], limitations: ["Free accounts see a fixed preview of the board, rankings and comparisons, and latest values for one market", "Pro unlocks every market, full rankings and history", "Rankings list up to ten markets each", "Rates, premiums and changes are fractions in JSON", "Open-interest history begins at first collection", "Funding APR is a simple annualization, not a forecast",
+    "Long/short account shares: venue definitions differ; history begins at first collection"] },
+  describe: (args) => TITLES[tabOf(args)],
   async load(args, ctx) {
-    const search = String(Array.isArray(args.argument) ? args.argument.join(" ") : args.argument ?? "BTC");
+    const requested = requestedOf(args);
+    const tab = tabOf(args);
+    if (tab === "board") {
+      const assetClass = String(args.options["asset-class"] ?? "all"), venue = String(args.options.venue ?? "all"), sort = String(args.options.sort ?? "oi");
+      const board = await fetchPerpsBoard({ ...(assetClass !== "all" ? { assetClass } : {}), ...(requested ? { search: requested } : {}), sort }, ctx.apiClient);
+      const rows = venue === "all" ? board.rows : board.rows.filter((row) => row.venue === venue);
+      return { sections: [{ title: "Markets", columns: BOARD_TEXT_COLUMNS, rows: copy(rows) }], complete: !board.locked && board.status === "ok",
+        errors: board.locked ? [more(board.locked, "markets")] : [], freshness: listFreshness(rows, board.asOf, venue),
+        metadata: { ...listMetadata(board), total: board.total, assetClass, venue, sort, ...(requested ? { search: requested } : {}) } };
+    }
+    if (tab === "rankings") {
+      const rankings = await fetchPerpsRankings(ctx.apiClient);
+      const sections: HeadlessBundleSection[] = RANKINGS.map((ranking) => ({ title: ranking.label, columns: rankingTextColumns(ranking), rows: copy(rankingRows(rankings, ranking.key)) }));
+      return { sections, complete: !rankings.locked && rankings.status === "ok", errors: rankings.locked ? ["Full rankings need Gloom Pro"] : [],
+        freshness: listFreshness(RANKINGS.flatMap((ranking) => rankingRows(rankings, ranking.key)), rankings.asOf), metadata: listMetadata(rankings) };
+    }
+    if (tab === "compare") {
+      // A canonical identity names one contract; its base asset is what the venues share.
+      const base = requested.includes(":") ? (await fetchPerpSelection(requested, ctx.apiClient)).rows[0]?.baseAsset ?? requested : (requested || DEFAULT_MARKET).toUpperCase();
+      const compare = await fetchPerpsCompare(base, ctx.apiClient);
+      if (!compare.rows.length && !compare.locked) throw new Error(`No perpetual market matches "${requested || base}". Try ${EXAMPLE_MARKETS.join(", ")}.`);
+      const spread = fundingSpread(compare.rows);
+      return { sections: [{ title: "Contracts", columns: COMPARE_TEXT_COLUMNS, rows: copy(compare.rows) },
+        ...(spread ? [{ title: "Funding spread", entries: [{ key: "fundingSpread8h", label: "Funding spread 8h", value: spread.value, formatted: `${spread.text} ${spread.detail}` }] }] : [])],
+        complete: !compare.locked && compare.status === "ok", errors: compare.locked ? [more(compare.locked, compare.locked === 1 ? "contract" : "contracts")] : [],
+        freshness: listFreshness(compare.rows, compare.asOf),
+        metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET, notices: [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]} --tab compare.`] }),
+          ...listMetadata(compare), total: compare.total, baseAsset: base,
+          ...(spread ? { fundingSpread8h: spread.value, fundingSpreadHigh: spread.high.marketId, fundingSpreadLow: spread.low.marketId } : {}) } };
+    }
+    const search = requested || DEFAULT_MARKET;
     const market = await fetchPerpSelection(search, ctx.apiClient);
     const selected = market.rows[0];
-    if (!selected) return { sections: [{ title: "Market", rows: [] }], errors: ["No market matches the selection"], complete: false };
-    const metadata = { marketId: selected.marketId, sourceUrl: selected.sourceUrl, observedAt: selected.observedAt, sourceAsOf: selected.sourceAsOf,
+    if (!selected) throw new Error(`No perpetual market matches "${search}". Try ${EXAMPLE_MARKETS.join(", ")}.`);
+    const defaulted = requested ? {} : { defaultArgument: DEFAULT_MARKET, notices: [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]}.`] };
+    const metadata = { ...defaulted, marketId: selected.marketId, sourceUrl: selected.sourceUrl, observedAt: selected.observedAt, sourceAsOf: selected.sourceAsOf,
       rates: "fraction", quoteCurrency: selected.quoteCurrency, oiCurrency: "USD", fundingIntervalHours: selected.fundingIntervalHours };
-    if (args.options.tab === "evidence") return {
-      sections: [{ title: "Market evidence", rows: market.rows.map((row) => ({ ...row })) }, { title: "Observation revisions", rows: market.evidence.map((row) => ({ ...row })) }],
-      complete: market.access === "pro" && market.status === "ok", errors: market.access !== "pro" ? ["Full evidence requires Gloom Pro"] : [],
+    // The venue's market, as last polled: not a stream, and a venue trading around the clock is stale after an hour without a poll.
+    const freshness = { source: venueLabel(selected), status: "delayed" as const, asOf: selected.observedAt, maxAgeMinutes: 60 };
+    // The same Positioning lines the pane's Evidence shows; JSON keeps the raw reading on the market row.
+    const positioning = positioningFields(selected);
+    if (tab === "evidence") return {
+      sections: [{ title: "Market evidence", columns: MARKET_COLUMNS, rows: market.rows.map((row) => ({ ...row })) },
+        ...(positioning ? [{ title: "Positioning", entries: positioning.map((field) => ({ key: field.key, label: field.label, value: field.value,
+          formatted: field.detail ? `${field.text} · ${field.detail}` : field.text })) }] : []),
+        { title: "Observation revisions", columns: REVISION_COLUMNS, rows: market.evidence.map((row) => ({ ...row })) }],
+      complete: market.access === "pro" && market.status === "ok", errors: market.access !== "pro" ? ["Full evidence requires Gloom Pro"] : [], freshness,
       metadata: { ...metadata, asOf: market.asOf, access: market.access, locked: market.locked, status: market.status },
     };
     const history = await fetchPerpsHistory({ marketId: selected.marketId, from: new Date(Date.now() - Number(args.options.days ?? 7) * 86_400_000).toISOString(), resolution: "auto", limit: 5000 }, ctx.apiClient);
-    return { sections: [{ title: "Latest market", rows: [{ ...selected }] }, { title: "Own observations", rows: history.rows.map((row) => ({ ...row })) },
-      { title: "Paid funding", rows: history.funding.map((row) => ({ ...row })) }, { title: "Hourly candles", rows: history.candles.map((row) => ({ ...row })) }],
-      complete: !history.locked && !history.truncated && history.status === "ok",
+    return { sections: [{ title: "Latest market", columns: MARKET_COLUMNS, rows: [{ ...selected }] }, { title: "Own observations", columns: observationColumns(selected.quoteCurrency), rows: history.rows.map((row) => ({ ...row })) },
+      { title: "Paid funding", columns: FUNDING_COLUMNS, rows: history.funding.map((row) => ({ ...row })) }, { title: "Hourly candles", columns: candleColumns(selected.quoteCurrency), rows: history.candles.map((row) => ({ ...row })) },
+      { title: "Long/short history", columns: LONG_SHORT_COLUMNS, rows: (history.longShortRatio ?? []).map((row) => ({ ...row })) }],
+      complete: !history.locked && !history.truncated && history.status === "ok", freshness,
       errors: history.locked ? ["Full history requires Gloom Pro"] : history.truncated ? ["History reached the 5,000-observation limit; narrow the range"] : [],
       metadata: { ...metadata, asOf: history.asOf, access: history.access, locked: history.locked, status: history.status, from: history.from, to: history.to, resolution: history.resolution, truncated: history.truncated ?? false },
     };

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

@@ -1,14 +1,14 @@
 import type { PluginModule } from "../plugin-module";
-import { perpsCache, perpsHistoryCache, perpsMarketCache } from "./client";
+import { perpsCache, perpsHistoryCache, perpsMarketCache, perpsRankingsCache } from "./client";
 import { perpsHeadless } from "./headless";
 import { PerpsPane } from "./pane";
 export const perpsModule: PluginModule = {
-  panes: [{ id: "perps", name: "Perpetual History", icon: "P", component: PerpsPane, defaultPosition: "right", defaultMode: "floating",
+  panes: [{ id: "perps", name: "Perpetuals", icon: "P", component: PerpsPane, defaultPosition: "right", defaultMode: "floating",
     defaultFloatingSize: { width: 138, height: 34 }, tableExport: true, headless: perpsHeadless }],
-  paneTemplates: [{ id: "perps-pane", paneId: "perps", label: "Perpetual History", description: "Pro per-market funding, open interest, premium history and evidence.",
-    keywords: ["perp", "perpetual", "funding", "open interest", "hip-3", "stock perps"],
+  paneTemplates: [{ id: "perps-pane", paneId: "perps", label: "Perpetuals", description: "Perpetual funding, open interest and premiums by market and venue, with rankings, a venue comparison and Pro history.",
+    keywords: ["perp", "perpetual", "perpetuals", "funding", "funding rate", "open interest", "hip-3", "stock perps", "basis", "venue", "funding spread", "long short ratio", "long/short", "positioning"],
     shortcut: { prefix: "PERP", argKind: "text", argOptional: true, argPlaceholder: "market" }, headless: perpsHeadless,
     createInstance: (_ctx, options) => ({ placement: "floating", settings: { market: options?.arg?.trim() ?? "" } }) }],
-  setup(ctx) { perpsCache.attach(ctx.persistence); perpsHistoryCache.attach(ctx.persistence); perpsMarketCache.attach(ctx.persistence); },
-  dispose() { perpsCache.reset(); perpsHistoryCache.reset(); perpsMarketCache.reset(); },
+  setup(ctx) { perpsCache.attach(ctx.persistence); perpsHistoryCache.attach(ctx.persistence); perpsMarketCache.attach(ctx.persistence); perpsRankingsCache.attach(ctx.persistence); },
+  dispose() { perpsCache.reset(); perpsHistoryCache.reset(); perpsMarketCache.reset(); perpsRankingsCache.reset(); },
 };

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

@@ -1,21 +1,38 @@
-import type { PerpBoardRow, PerpHistoryPayload } from "../../../api-client/perps";
+import type { PerpBoardRow, PerpHistoryPayload, PerpLongShortRatio, PerpRankingsPayload } from "../../../api-client/perps";
 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 type { ThemeColors } from "../../../theme/colors";
-export const PERP_TABS = ["history", "evidence"] as const;
+export const PERP_TABS = ["board", "rankings", "compare", "history", "evidence"] as const;
 export type PerpTab = typeof PERP_TABS[number];
+/** One market's tabs; the others list many markets. */
+export const isMarketTab = (tab: string) => tab === "history" || tab === "evidence";
+/** A named market opens its history; nothing named opens the board. */
+export const openingTab = (market: string | null | undefined): PerpTab => market?.trim() ? "history" : "board";
+export const ASSET_FILTERS = ["all", "stocks", "indices", "energy", "metals", "fx", "crypto"] as const;
+export const VENUES = ["hyperliquid", "binance", "bybit", "okx", "deribit", "coinbase", "kraken", "dydx"] as const;
+export const BOARD_SORTS = ["oi", "funding", "oi-change", "premium", "long-short"] as const;
+export const sortLabel = (sort: string) => ({ oi: "OI", funding: "Funding", "oi-change": "OI change", premium: "Premium", "long-short": "Long %" })[sort] ?? sort;
 export const label = (s: string) => s === "fx" ? "FX" : s.charAt(0).toUpperCase() + s.slice(1);
 export const percent = (n: number | null | undefined, digits = 3) => n == null ? "--" : `${n > 0 ? "+" : ""}${(n * 100).toFixed(digits)}%`;
 export const price = (n: number | null | undefined) => n == null ? "--" : n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: n < 1 ? 6 : 2 });
 export const compact = (n: number | null | undefined) => n == null ? "--" : formatCompact(n, { fixedDecimals: true });
 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)}` : "--";
 export const marketLabel = (row: PerpBoardRow) => row.dex && row.dex !== "default" ? `${row.baseAsset} · ${row.dex.toUpperCase()}` : row.baseAsset;
 export const fundingInterval = (row: Pick<PerpBoardRow, "fundingIntervalHours" | "fundingKind">) => row.fundingIntervalHours ? `${row.fundingIntervalHours}h${row.fundingKind === "last-paid" ? " paid" : row.fundingKind === "continuous" ? " continuous" : ""}` : "--";
-export type HistoryMetric = "funding" | "oi" | "premium" | "price";
-export function historyRows(data: PerpHistoryPayload | null | undefined, metric: HistoryMetric) {
+export const HISTORY_METRICS = ["funding", "oi", "premium", "price", "long-short"] as const;
+export type HistoryMetric = typeof HISTORY_METRICS[number];
+export const metricLabel = (metric: HistoryMetric) => metric === "oi" ? "OI" : metric === "long-short" ? "L/S" : label(metric);
+/** One point of a history series; a long/short point also carries the short share and the ratio. */
+export interface HistoryRow { time: string; value: number | null; basis: string; change: number | null; shortShare?: number; ratio?: number | null }
+export function historyRows(data: PerpHistoryPayload | null | undefined, metric: HistoryMetric): HistoryRow[] {
   if (!data) return [];
-  const points = metric === "funding" && data.funding.length ? data.funding.map((row) => ({ time: row.time, value: row.rate * 8 / row.intervalHours, basis: `Paid · ${row.intervalHours}h → 8h` }))
+  const points: Array<Omit<HistoryRow, "change">> = metric === "long-short" ? (data.longShortRatio ?? []).map((row) => ({ time: row.time, value: row.longShare,
+    shortShare: row.shortShare, ratio: row.ratio, basis: row.derived ? "1h bucket · shares from ratio" : "1h bucket" }))
+    : metric === "funding" && data.funding.length ? data.funding.map((row) => ({ time: row.time, value: row.rate * 8 / row.intervalHours, basis: `Paid · ${row.intervalHours}h → 8h` }))
     : metric === "price" && data.candles.length ? data.candles.map((row) => ({ time: row.time, value: row.close, basis: "1h close" }))
       : data.rows.map((row) => ({ time: row.time,
         value: metric === "oi" ? row.openInterestUsd : metric === "premium" ? row.premium : metric === "price" ? row.markPrice
@@ -24,35 +41,195 @@ export function historyRows(data: PerpHistoryPayload | null | undefined, metric:
   return points.sort((a, b) => a.time.localeCompare(b.time)).map((row, i, all) => ({ ...row,
     change: i && row.value !== null && all[i - 1]!.value !== null ? row.value - all[i - 1]!.value! : null }));
 }
-export const historyValue = (n: number | null | undefined, metric: HistoryMetric) => metric === "oi" ? compact(n) : metric === "price" ? price(n) : percent(n, metric === "funding" ? 4 : 3);
+/** The move since the newest point a day or more before the latest; null until history reaches back that far. */
+export function dayChange(rows: readonly HistoryRow[]) {
+  const last = rows.at(-1);
+  if (last?.value == null) return null;
+  const before = rows.findLast((row) => row.value != null && Date.parse(row.time) <= Date.parse(last.time) - 86_400_000);
+  return before ? last.value - before.value! : null;
+}
+export const historyValue = (n: number | null | undefined, metric: HistoryMetric) => metric === "oi" ? compact(n) : metric === "price" ? price(n) : metric === "long-short" ? share(n, 2) : percent(n, metric === "funding" ? 4 : 3);
 export function historySeries(data: PerpHistoryPayload | null | undefined, metric: HistoryMetric, name: string, color: string) {
   const rows = historyRows(data, metric);
   return [staticSeries(rows.map((row) => scalarPoint(new Date(row.time), row.value)), { id: `perp-${metric}`, label: `${name} · ${historyCaption(data, metric)}`, color, calendarSpaced: true })];
 }
 
-export const venueLabel = (row: PerpBoardRow) => ({ hyperliquid: "Hyperliquid", binance: "Binance", bybit: "Bybit", okx: "OKX", deribit: "Deribit", coinbase: "Coinbase International", kraken: "Kraken", dydx: "dYdX" })[row.venue] ?? row.venue;
+export const venueName = (venue: string) => ({ hyperliquid: "Hyperliquid", binance: "Binance", bybit: "Bybit", okx: "OKX", deribit: "Deribit", coinbase: "Coinbase International", kraken: "Kraken", dydx: "dYdX" } as Record<string, string>)[venue] ?? venue;
+export const venueLabel = (row: Pick<PerpBoardRow, "venue">) => venueName(row.venue);
+/** The venues behind some rows, in a stable order: the citation for a report over many markets. */
+export const venuesOf = (rows: readonly Pick<PerpBoardRow, "venue">[]): string[] => [...new Set<string>(rows.map((row) => row.venue))].sort((a, b) => venueName(a).localeCompare(venueName(b)));
+
+/** A share of accounts, unsigned: 0.6183 reads 61.8%. */
+export const share = (n: number | null | undefined, digits = 1) => n == null ? "--" : `${(n * 100).toFixed(digits)}%`;
+/** Long accounts per short account, as the venue publishes it. */
+export const ratioText = (n: number | null | undefined, digits = 2) => n == null ? "--" : n.toFixed(digits);
+/** What a long/short reading counts, short enough for a legend; `definitionText` says it in full. */
+const longShortDefinition = (definition: string | null | undefined) => definition === "accounts_all" || !definition ? "All accounts" : label(definition.replaceAll("_", " "));
+const LONG_SHORT_REASONS: Record<string, string> = { unsupported: "This venue publishes no per-contract account ratio", off: "Not collected yet", collecting: "Collecting" };
+/** Why a row has no long/short reading, in words; null when it has one, or the server predates the series. */
+export function longShortReason(row: Pick<PerpBoardRow, "longShortRatio" | "longShortRatioReason">) {
+  if (row.longShortRatio || !row.longShortRatioReason) return null;
+  return LONG_SHORT_REASONS[row.longShortRatioReason] ?? "Not available";
+}
+/**
+ * The long/short reading as Evidence lists it, shared by the pane and the text report. The Market group already
+ * names the venue, so the bucket row carries the venue's period instead of a second Venue row.
+ */
+export interface PositioningField { key: string; label: string; /** The raw value JSON keeps. */ value: unknown; text: string; detail?: string }
+export function positioningFields(row: Pick<PerpBoardRow, "longShortRatio" | "longShortRatioReason">): PositioningField[] | null {
+  const reading: PerpLongShortRatio | null = row.longShortRatio ?? null;
+  const reason = longShortReason(row);
+  if (!reading) return reason ? [{ key: "longShortRatioReason", label: "Long accounts", value: row.longShortRatioReason, text: reason }] : null;
+  return [
+    { key: "longShare", label: "Long accounts", value: reading.longShare, text: share(reading.longShare, 2) },
+    { key: "shortShare", label: "Short accounts", value: reading.shortShare, text: share(reading.shortShare, 2) },
+    { key: "ratio", label: "Long / short ratio", value: reading.ratio, text: ratioText(reading.ratio, 4) },
+    ...(reading.derived ? [{ key: "derived", label: "Shares", value: true, text: "Derived from the published ratio" }] : []),
+    { key: "definition", label: "Definition", value: reading.definition, text: reading.definitionText || longShortDefinition(reading.definition) },
+    { key: "bucketAt", label: "Bucket", value: reading.bucketAt, text: time(reading.bucketAt), detail: `${venueName(reading.venue)} ${reading.period}${reading.stale ? " · stale" : ""}` },
+    { key: "observedAt", label: "Observed", value: reading.observedAt, text: time(reading.observedAt) },
+  ];
+}
+
+// One text per figure, shared by the pane cells and the text report so the two always agree.
+const markText = (row: Pick<PerpBoardRow, "markPrice" | "quoteCurrency">) => row.markPrice == null ? "--" : `${price(row.markPrice)} ${row.quoteCurrency}`;
+const fundingPerInterval = (row: Pick<PerpBoardRow, "fundingRate" | "fundingIntervalHours" | "fundingKind">) => row.fundingRate == null ? "--" : `${percent(row.fundingRate, 5)} /${fundingInterval(row)}`;
+/** Percentage points between two fractions: 0.00003 reads 0.0030pp. */
+const points = (n: number | null | undefined, digits = 4) => n == null ? "--" : `${(n * 100).toFixed(digits)}pp`;
+
+export type PerpColumnId = "market" | "venue" | "symbol" | "markPrice" | "fundingRate" | "fundingRate8h" | "fundingApr" | "premium"
+  | "openInterestUsd" | "oiChange24h" | "longShare" | "priceChange24h" | "observedAt" | "value";
+const PERP_COLUMNS: Record<PerpColumnId, DataTableColumn> = {
+  market: { id: "market", label: "Market", width: 14, align: "left" },
+  venue: { id: "venue", label: "Venue", width: 11, align: "left" },
+  symbol: { id: "symbol", label: "Contract", width: 14, align: "left" },
+  markPrice: { id: "markPrice", label: "Mark", width: 16, align: "right" },
+  fundingRate: { id: "fundingRate", label: "Funding %/int", width: 14, align: "right" },
+  fundingRate8h: { id: "fundingRate8h", label: "Funding 8h %", width: 12, align: "right" },
+  fundingApr: { id: "fundingApr", label: "APR %", width: 9, align: "right" },
+  premium: { id: "premium", label: "Premium %", width: 9, align: "right" },
+  openInterestUsd: { id: "openInterestUsd", label: "OI USD", width: 8, align: "right" },
+  oiChange24h: { id: "oiChange24h", label: "OI 24h %", width: 8, align: "right" },
+  longShare: { id: "longShare", label: "Long %", width: 6, align: "right" },
+  priceChange24h: { id: "priceChange24h", label: "24h %", width: 7, align: "right" },
+  observedAt: { id: "observedAt", label: "Observed UTC", width: 12, align: "left" },
+  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 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. */
+function fitPerpColumns(ids: readonly PerpColumnId[], drops: readonly PerpColumnId[], width: number): DataTableColumn[] {
+  let kept = ids.map((id) => PERP_COLUMNS[id]);
+  const fits = () => getTableWidth(kept) <= width;
+  for (const [index, drop] of drops.entries()) {
+    if (fits()) break;
+    if (index === drops.length - 1) {
+      kept = kept.map((column) => column.id === "market" ? { ...column, width: 10 } : column);
+      if (fits()) break;
+    }
+    kept = kept.filter((column) => column.id !== drop);
+  }
+  return kept;
+}
+export const boardColumns = (width: number) => fitPerpColumns(BOARD_COLUMNS, BOARD_DROPS, width);
+export const compareColumns = (width: number) => fitPerpColumns(COMPARE_COLUMNS, COMPARE_DROPS, width);
+export const rankingColumns = (width: number) => fitPerpColumns(RANKING_COLUMNS, ["openInterestUsd", "venue"], width);
+export const perpColumnLabel = (id: PerpColumnId) => PERP_COLUMNS[id].label;
+
+const SIGNED: Partial<Record<PerpColumnId, number>> = { fundingRate8h: 4, fundingApr: 2, premium: 3, oiChange24h: 2, priceChange24h: 2 };
+/** A board or comparison cell: the text the report prints, the number CSV exports, and the sign's tone. */
+export function perpCellText(row: PerpBoardRow, id: PerpColumnId): string {
+  if (id === "market") return marketLabel(row);
+  if (id === "venue") return venueLabel(row);
+  if (id === "symbol") return row.symbol;
+  if (id === "markPrice") return markText(row);
+  if (id === "fundingRate") return fundingPerInterval(row);
+  if (id === "openInterestUsd") return compact(row.openInterestUsd);
+  if (id === "observedAt") return observed(row.observedAt);
+  if (id === "longShare") return share(row.longShortRatio?.longShare);
+  const digits = SIGNED[id];
+  return digits === undefined ? "--" : percent(row[id as keyof PerpBoardRow] as number | null, digits);
+}
+export function perpCell(row: PerpBoardRow, id: PerpColumnId, colors: Pick<ThemeColors, "positive" | "negative" | "text" | "textBright" | "textMuted" | "textDim">): DataTableCell {
+  const text = perpCellText(row, id);
+  if (id === "market") return { text, color: row.stale ? colors.textDim : colors.textBright };
+  if (id === "venue" || id === "symbol") return { text, color: colors.textMuted };
+  if (id === "observedAt") return { text, value: row.observedAt, color: row.stale ? colors.textMuted : colors.textDim };
+  if (id === "markPrice") return { text, value: row.markPrice };
+  if (id === "openInterestUsd") return { text, value: row.openInterestUsd };
+  // A share, not a signed move: no tone, dimmed like a stale market when its bucket is old.
+  if (id === "longShare") {
+    const reading = row.longShortRatio;
+    return { text, value: reading ? reading.longShare * 100 : null, color: !reading ? colors.textMuted : reading.stale ? colors.textDim : colors.text };
+  }
+  const value = id === "fundingRate" ? row.fundingRate : row[id as keyof PerpBoardRow] as number | null;
+  return { text, value: value == null ? null : value * 100, color: value == null || value === 0 ? colors.textMuted : value > 0 ? colors.positive : colors.negative };
+}
+
+/** The five ranked lists, each with the figure it ranks by. */
+export type RankingKey = Exclude<keyof PerpRankingsPayload, "status" | "asOf" | "access" | "locked">;
+export const RANKINGS: Array<{ key: RankingKey; label: string; header: string; field: "fundingRate8h" | "oiChange24h" | "premium" | "closedMarketPremium"; digits: number }> = [
+  { key: "fundingPositive", label: "Highest Funding 8h", header: "Funding 8h %", field: "fundingRate8h", digits: 4 },
+  { key: "fundingNegative", label: "Lowest Funding 8h", header: "Funding 8h %", field: "fundingRate8h", digits: 4 },
+  { key: "oiSurges", label: "OI Surges 24h", header: "OI 24h %", field: "oiChange24h", digits: 2 },
+  { key: "premiumDislocations", label: "Premium Dislocations", header: "Premium %", field: "premium", digits: 3 },
+  { key: "closedMarketDislocations", label: "Closed-Market Dislocations", header: "Closed-market premium %", field: "closedMarketPremium", digits: 3 },
+];
+/** Rows per list: the preview's three, or the first ten of the full ranking. */
+const RANKING_ROWS = 10;
+export const rankingRows = (data: PerpRankingsPayload | null | undefined, key: RankingKey) => (data?.[key] ?? []).slice(0, RANKING_ROWS);
+
+/**
+ * Highest minus lowest 8h funding across the shown contracts, in percentage points. Each end is named by its
+ * venue, with the contract symbol when that venue lists more than one.
+ */
+export function fundingSpread(rows: readonly PerpBoardRow[]) {
+  const rated = rows.filter((row) => row.fundingRate8h != null);
+  if (rated.length < 2) return null;
+  const high = rated.reduce((best, row) => row.fundingRate8h! > best.fundingRate8h! ? row : best);
+  const low = rated.reduce((best, row) => row.fundingRate8h! < best.fundingRate8h! ? row : best);
+  const name = (row: PerpBoardRow) => rated.filter((other) => other.venue === row.venue).length > 1 ? `${venueLabel(row)} ${row.symbol}` : venueLabel(row);
+  return { value: high.fundingRate8h! - low.fundingRate8h!, high, low, text: points(high.fundingRate8h! - low.fundingRate8h!), detail: `${name(high)} over ${name(low)}` };
+}
 
 
+/** Series read in percent, whose changes are percentage points. */
+export const inPoints = (metric: HistoryMetric) => metric === "funding" || metric === "premium" || metric === "long-short";
 export function historyColumns(metric: HistoryMetric, currency: string, hasCandles = true): DataTableColumn[] {
   return [
     { id: "time", label: "Time (UTC)", width: 19, flexGrow: 1, align: "left" },
-    { id: "value", label: metric === "funding" ? "Funding 8h %" : metric === "premium" ? "Oracle premium %" : metric === "oi" ? "OI USD" : `${hasCandles ? "Close" : "Mark"} ${currency}`, width: 17, align: "right" },
-    { id: "change", label: metric === "funding" || metric === "premium" ? "Change pp" : `Change ${metric === "oi" ? "USD" : currency}`, width: 17, align: "right" },
+    { id: "value", label: metric === "funding" ? "Funding 8h %" : metric === "premium" ? "Oracle premium %" : metric === "oi" ? "OI USD" : metric === "long-short" ? "Long %" : `${hasCandles ? "Close" : "Mark"} ${currency}`, width: 17, align: "right" },
+    { id: "change", label: inPoints(metric) ? "Change pp" : `Change ${metric === "oi" ? "USD" : currency}`, width: 17, align: "right" },
+    ...(metric === "long-short" ? [{ id: "short", label: "Short %", width: 9, align: "right" as const }, { id: "ratio", label: "Ratio", width: 7, align: "right" as const }] : []),
     { id: "basis", label: "Observation basis", width: 25, align: "left" },
   ];
 }
-export const historyChange = (value: number | null | undefined, metric: HistoryMetric) => value == null ? "--" : metric === "funding" || metric === "premium" ? `${value > 0 ? "+" : ""}${(value * 100).toFixed(metric === "funding" ? 4 : 3)}pp` : historyValue(value, metric);
+export const historyChange = (value: number | null | undefined, metric: HistoryMetric) => value == null ? "--"
+  : inPoints(metric) ? `${value > 0 ? "+" : ""}${(value * 100).toFixed(metric === "funding" ? 4 : metric === "long-short" ? 2 : 3)}pp` : historyValue(value, metric);
 export function historyCaption(data: PerpHistoryPayload | null | undefined, metric: HistoryMetric) {
+  if (metric === "long-short") {
+    const points = data?.longShortRatio ?? [];
+    return `${longShortDefinition(points.at(-1)?.definition)} net long${points.length && points.every((point) => point.derived) ? ", from ratio" : ""}`;
+  }
   return metric === "funding" ? data?.funding.length ? "Paid funding / 8h" : "Observed funding / 8h"
     : metric === "price" && data?.candles.length ? "Hourly trade closes" : metric === "oi" ? "Collected open interest" : metric === "premium" ? "Collected oracle premium" : "Collected mark";
 }
 
-export function historyCell(row: ReturnType<typeof historyRows>[number], column: string, metric: HistoryMetric, colors?: Pick<ThemeColors, "positive" | "negative" | "textMuted" | "textDim" | "textBright">): DataTableCell {
+export function historyCell(row: HistoryRow, column: string, metric: HistoryMetric, colors?: Pick<ThemeColors, "positive" | "negative" | "text" | "textMuted" | "textDim" | "textBright">): DataTableCell {
   // The header says UTC; each row only needs the day and the hour.
   if (column === "time") return { text: row.time.slice(0, 16).replace("T", " "), value: row.time };
   if (column === "basis") return { text: row.basis, color: colors?.textDim };
+  if (column === "short") return { text: share(row.shortShare, 2), value: row.shortShare == null ? null : row.shortShare * 100, color: colors?.text };
+  if (column === "ratio") return { text: ratioText(row.ratio), value: row.ratio ?? null, color: colors?.text };
   const value = column === "change" ? row.change : row.value;
   return { text: column === "change" ? historyChange(value, metric) : historyValue(value, metric),
-    value: value === null ? null : value * (metric === "funding" || metric === "premium" ? 100 : 1),
+    value: value === null ? null : value * (inPoints(metric) ? 100 : 1),
     color: !colors ? undefined : column === "change" ? value == null || value === 0 ? colors.textMuted : value > 0 ? colors.positive : colors.negative : colors.textBright };
 }