@gloom-sh/terminal 0.0.0-stage → 0.18.5

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

@@ -0,0 +1,71 @@
+import type { PerpBoardRow } from "../../../api-client/perps";
+import type { HeadlessPaneFreshness } from "../../../types/headless";
+import { venueName, venuesOf } from "./model";
+
+type Dated = Pick<PerpBoardRow, "venue" | "observedAt" | "stale">;
+type Funded = Pick<PerpBoardRow, "venue" | "fundingRate" | "fundingRate8h" | "fundingKind" | "nextFundingAt">;
+
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const;
+const KINDS: Array<[PerpBoardRow["fundingKind"], string]> = [["current", "current estimate"], ["last-paid", "last paid"], ["continuous", "accrues continuously"]];
+
+/** `08:00` on the UTC day of `now`, else with its weekday: `Mon 00:00`. */
+function payTime(at: number, now: number): string {
+  const iso = new Date(at).toISOString();
+  return iso.slice(0, 10) === new Date(now).toISOString().slice(0, 10) ? iso.slice(11, 16) : `${WEEKDAYS[new Date(at).getUTCDay()]} ${iso.slice(11, 16)}`;
+}
+
+/**
+ * When current estimates pay: the next funding time when every contract shown pays then, else each time with the
+ * venues that report it (`08:00 UTC (Binance, Bybit)`). A venue that reports no next time is not given one.
+ */
+function paysText(rows: readonly Funded[], now: number): string | null {
+  const venuesAt = new Map<number, Funded[]>();
+  let unknown = false;
+  for (const row of rows) {
+    const at = row.nextFundingAt ? Date.parse(row.nextFundingAt) : Number.NaN;
+    if (!Number.isFinite(at) || at < now) unknown = true;
+    else venuesAt.set(at, [...venuesAt.get(at) ?? [], row]);
+  }
+  const times = [...venuesAt].sort(([a], [b]) => a - b);
+  if (!times.length) return null;
+  if (times.length === 1 && !unknown) return `${payTime(times[0]![0], now)} UTC`;
+  return times.map(([at, group]) => `${payTime(at, now)} UTC (${venuesOf(group).map(venueName).join(", ")})`).join(", ");
+}
+
+/**
+ * What a view's funding figures are, so a reader does not take a venue's current estimate for a settled rate:
+ * `funding = current estimate, pays 08:00 UTC`. With several bases each names its venues. Null when no row shows funding.
+ */
+export function fundingNote(rows: readonly Funded[], now = Date.now()): string | null {
+  const funded = rows.filter((row) => row.fundingRate != null || row.fundingRate8h != null);
+  const kinds = KINDS.filter(([kind]) => funded.some((row) => row.fundingKind === kind));
+  if (!kinds.length) return null;
+  return `funding = ${kinds.map(([kind, text]) => {
+    const group = funded.filter((row) => row.fundingKind === kind);
+    const pays = kind === "current" ? paysText(group, now) : null;
+    return `${text}${kinds.length > 1 ? ` (${venuesOf(group).map(venueName).join(", ")})` : ""}${pays ? `, pays ${pays}` : ""}`;
+  }).join("; ")}`;
+}
+
+/** What a capture reads of a row: when it was observed and whether the venue has stopped answering for it. */
+const perpObservation = (row: Pick<PerpBoardRow, "observedAt" | "stale">) => ({ observedAt: row.observedAt, stale: row.stale });
+
+/**
+ * How current a view of perpetual markets is: each venue's own newest observation, how old the oldest price shown is,
+ * and what the funding figures it shows (`funding`) are. `live` only while every row followed streams from its venue's
+ * socket; otherwise no feed word, since a row off the stream is the venue's own reading from the last pass (about once
+ * a minute), neither streamed nor held back. Stale after an hour without a read, or for a row whose venue stopped
+ * answering. The report, the capture and the pane footer all read this, rows and all, so they end with the same line.
+ */
+export function perpFreshness(rows: readonly Dated[], { funding = [], venue = "all", now = Date.now(), live = false }: {
+  funding?: readonly Funded[]; venue?: string; now?: number;
+  /** Every row followed moves with its venue's socket: the view is a live feed. */
+  live?: boolean;
+} = {}): HeadlessPaneFreshness {
+  const sources = venuesOf(rows).map((id) => ({ source: venueName(id), asOf: new Date(Math.max(...rows.filter((row) => row.venue === id)
+    .map((row) => Date.parse(row.observedAt)))).toISOString() }));
+  const source = sources.length ? sources.map((entry) => entry.source).join(", ") : venue !== "all" ? venueName(venue) : null;
+  const note = fundingNote(funding, now);
+  return { ...(source ? { source } : {}), sources, ...(live ? { status: "live" as const } : {}), ageOnly: true, maxAgeMinutes: 60,
+    observations: rows.map(perpObservation), ...(note ? { note } : {}) };
+}

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

@@ -0,0 +1,207 @@
+import type { PerpBoardPayload, PerpBoardRow } from "../../../api-client/perps";
+import type { HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneLoadArgs, HeadlessPaneRow } from "../../../types/headless";
+import type { HeadlessPaneDefinition } from "../../../types/plugin";
+import { boardSearchText, fetchPerpSelection, fetchPerpsBoard, fetchPerpsCompare, fetchPerpsHistory, fetchPerpsRankings, marketQuery, nearestPerpMarkets } from "./client";
+import { perpFreshness } from "./freshness";
+import { aprFootnote, ASSET_FILTERS, BOARD_COLUMNS, BOARD_SORTS, collectedVenueCount, COMPARE_COLUMNS, compact, fundingSpread, HISTORY_METRICS, label, marketLabel, openingTab, PERP_TABS, perpCellText,
+  perpColumnLabel, percent, perpHistoryProText, positioningFields, price, RANKING_COLUMNS, rankingRows, RANKINGS, ratioText, share, time, VENUES, venueName, type PerpColumnId } from "./model";
+import { freePreviewNote } from "../shared/free-preview";
+import { basisSpotSymbol } from "../futures-curve/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 ones that work, a builder dex's among them.
+const EXAMPLE_MARKETS = ["BTC", "ETH", "SOL"] as const;
+const DEFAULT_MARKET = EXAMPLE_MARKETS[0];
+const EXAMPLE_NAMES = ["BTC", "ETH", "SP500", "xyz:SP500"];
+// The names nearest what was typed when the board has some, else the examples.
+const noMarket = (input: string, nearest: readonly string[] = []) => new Error(`No perpetual market matches "${input}". Try ${(nearest.length ? nearest : EXAMPLE_NAMES).join(", ")}.`);
+/** A pair or plain name read as the market it stands for says so, and names the other contracts that fit it. */
+const readAs = (shown: string, requested: string, others: readonly string[] = []) =>
+  [`Showing ${shown} for "${requested}".${others.length ? ` Also on the board: ${others.join(", ")}.` : ""}`];
+// The APR % column is the current rate carried forward a year at each market's own interval, so a table that shows it says how.
+const aprNote = (rows: readonly PerpBoardRow[]) => {
+  const note = aprFootnote(rows);
+  return note ? { notes: [note] } : {};
+};
+
+const requestedOf = (args: HeadlessPaneLoadArgs) => String(Array.isArray(args.argument) ? args.argument.join(" ") : args.argument ?? "").trim();
+// No tab named: a market opens its history, nothing opens the board, as the pane does.
+const tabOf = (args: HeadlessPaneLoadArgs) => PERP_TABS.find((tab) => tab === args.options.tab) ?? openingTab(requestedOf(args));
+// A free account's market opens its latest values under the title, so the title names the function, not the Pro history: a table the free view
+// locks is left out and named on the report's one Pro line (`lockedTable`), never marked on the title over the free ones.
+const TITLES: Record<typeof PERP_TABS[number], string> = { board: "Perpetual markets", rankings: "Perpetual rankings", compare: "Perpetual contracts across venues",
+  history: "Perpetuals", evidence: "Perpetual evidence" };
+const copy = (rows: readonly PerpBoardRow[]) => rows.map((row) => ({ ...row }));
+const more = (count: number, noun: string) => `${count.toLocaleString("en-US")} more ${noun} need Gloom Pro`;
+// A table the free view leaves empty is locked: the report leaves it out and its one Pro line says what Pro adds.
+const lockedTable = (locked: unknown) => locked ? { locked: true } : {};
+// A free account's history line: what free shows of a market (its latest row, and the futures basis where CTM has
+// a curve for the asset), then what Pro adds.
+const historyLock = (selected: PerpBoardRow, venues: number | null) => {
+  const base = selected.baseAsset.toUpperCase();
+  const basis = basisSpotSymbol(base) ? ` (basis: fn CTM ${base})` : "";
+  return freePreviewNote({ shows: `the latest funding, OI and premium${basis}`, adds: perpHistoryProText(selected, venues) });
+};
+// A venue filter the report cannot honour is said, not ignored.
+const venueNotice = (venue: string, selected: PerpBoardRow, requested: string, access: string) => {
+  if (venue === "all" || selected.venue === venue) return [];
+  const [wanted, shown] = [venueName(venue), venueName(selected.venue)];
+  return [VENUES.some((id) => requested.startsWith(`${id}:`)) ? `${requested} is a ${shown} market, so the ${wanted} filter does not apply.`
+    : `${wanted} has no ${selected.baseAsset} contract${access === "pro" ? "" : " in the free preview"}; showing ${shown}.`];
+};
+const venueUnused = (venue: string, tab: string) => venue === "all" ? [] : [`The ${venueName(venue)} filter applies to the board, not ${tab}; showing every venue.`];
+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: "A base asset, underlying, canonical market identity or Market column label, such as BTC, hyperliquid:xyz:TSLA or SP500 · XYZ. 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 })), 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; with a market, opens that venue's contract when the board lists it." },
+    { 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: HISTORY_METRICS.map((value) => ({ value })), defaultValue: "funding", description: "Displayed history chart; JSON retains every series." },
+  ],
+  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 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: boardSearchText(requested) } : {}), sort }, ctx.apiClient);
+      const rows = venue === "all" ? board.rows : board.rows.filter((row) => row.venue === venue);
+      // The server counts what the free view hides across every venue; a venue's own share of it is not known, so a venue filter names no count.
+      const lock = venue === "all" ? more(board.locked, "markets") : `${venueName(venue)} markets beyond the free preview need Gloom Pro`;
+      return { sections: [{ title: "Markets", columns: BOARD_TEXT_COLUMNS, rows: copy(rows), ...lockedTable(board.locked && !rows.length) }], complete: !board.locked && board.status === "ok",
+        errors: board.locked ? [lock] : [], ...aprNote(rows), freshness: perpFreshness(rows, { funding: rows, venue }),
+        metadata: { ...listMetadata(board), total: board.total, assetClass, venue, sort, ...(requested ? { search: requested } : {}) } };
+    }
+    if (tab === "rankings") {
+      const rankings = await fetchPerpsRankings(ctx.apiClient);
+      // A ranking the free view leaves empty is locked, left out and said on the Pro line; one that has none to rank says so.
+      const sections: HeadlessBundleSection[] = RANKINGS.map((ranking) => {
+        const rows = copy(rankingRows(rankings, ranking.key));
+        return { title: ranking.label, columns: rankingTextColumns(ranking), rows, ...lockedTable(rankings.locked && !rows.length) };
+      });
+      const notices = venueUnused(String(args.options.venue ?? "all"), "rankings");
+      // Only the funding lists show funding.
+      const funding = RANKINGS.filter((ranking) => ranking.field === "fundingRate8h").flatMap((ranking) => rankingRows(rankings, ranking.key));
+      return { sections, complete: !rankings.locked && rankings.status === "ok", errors: rankings.locked ? ["Full rankings need Gloom Pro"] : [],
+        freshness: perpFreshness(RANKINGS.flatMap((ranking) => rankingRows(rankings, ranking.key)), { funding }), metadata: { ...(notices.length ? { notices } : {}), ...listMetadata(rankings) } };
+    }
+    if (tab === "compare") {
+      // A canonical identity names one contract; its base asset is what the venues share.
+      const identity = marketQuery(requested);
+      const asked = identity.includes(":") ? (await fetchPerpSelection(identity, ctx.apiClient)).rows[0]?.baseAsset ?? identity : (requested || DEFAULT_MARKET).toUpperCase();
+      // A pair or plain name (BTC-USD, bitcoin) compares the base asset it stands for; the rows say which.
+      const compare = await fetchPerpsCompare(asked, ctx.apiClient);
+      if (!compare.rows.length && !compare.locked) throw noMarket(requested || asked, await nearestPerpMarkets(requested || asked, ctx.apiClient));
+      const base = compare.rows[0]?.baseAsset ?? asked;
+      const spread = fundingSpread(compare.rows);
+      const notices = [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]} --tab compare.`]),
+        ...requested && !identity.includes(":") && base.toUpperCase() !== asked ? readAs(base, requested) : [], ...venueUnused(String(args.options.venue ?? "all"), "compare")];
+      return { sections: [{ title: "Contracts", columns: COMPARE_TEXT_COLUMNS, rows: copy(compare.rows), ...lockedTable(compare.locked) },
+        ...(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")] : [],
+        ...aprNote(compare.rows), freshness: perpFreshness(compare.rows, { funding: compare.rows }),
+        metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(notices.length ? { notices } : {}),
+          ...listMetadata(compare), total: compare.total, baseAsset: base,
+          ...(spread ? { fundingSpread8h: spread.value, fundingSpreadHigh: spread.high.marketId, fundingSpreadLow: spread.low.marketId } : {}) } };
+    }
+    const search = requested || DEFAULT_MARKET, venue = String(args.options.venue ?? "all");
+    const market = await fetchPerpSelection(search, ctx.apiClient, venue !== "all" ? venue : undefined);
+    const selected = market.rows[0];
+    if (!selected) throw noMarket(search, market.suggestions);
+    const notices = [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]}.`]),
+      ...market.resolved ? readAs(marketLabel(selected), requested, market.resolved.others) : [], ...venueNotice(venue, selected, requested, market.access)];
+    const metadata = { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(notices.length ? { notices } : {}), marketId: selected.marketId, sourceUrl: selected.sourceUrl, observedAt: selected.observedAt, sourceAsOf: selected.sourceAsOf,
+      rates: "fraction", quoteCurrency: selected.quoteCurrency, oiCurrency: "USD", fundingIntervalHours: selected.fundingIntervalHours };
+    // The venue's market as last polled, with the funding its latest row shows.
+    const freshness = perpFreshness([selected], { funding: [selected] });
+    // 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 })), ...lockedTable(market.access !== "pro") }],
+      complete: market.access === "pro" && market.status === "ok", ...aprNote(market.rows), freshness,
+      errors: market.access !== "pro" ? [freePreviewNote({ shows: `${marketLabel(selected)}'s latest evidence and positioning`, adds: "its observation revisions" })] : [],
+      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);
+    const locked = lockedTable(history.locked);
+    return { sections: [{ title: "Latest market", columns: MARKET_COLUMNS, rows: [{ ...selected }] }, { title: "Own observations", columns: observationColumns(selected.quoteCurrency), rows: history.rows.map((row) => ({ ...row })), ...locked },
+      { title: "Paid funding", columns: FUNDING_COLUMNS, rows: history.funding.map((row) => ({ ...row })), ...locked }, { title: "Hourly candles", columns: candleColumns(selected.quoteCurrency), rows: history.candles.map((row) => ({ ...row })), ...locked },
+      { title: "Long/short history", columns: LONG_SHORT_COLUMNS, rows: (history.longShortRatio ?? []).map((row) => ({ ...row })), ...locked }],
+      complete: !history.locked && !history.truncated && history.status === "ok", ...aprNote([selected]), freshness,
+      errors: history.locked ? [historyLock(selected, collectedVenueCount(market.sources))] : 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

@@ -0,0 +1,33 @@
+import type { PaneTemplateInstanceConfig } from "../../../types/plugin";
+import type { PluginModule } from "../plugin-module";
+import { commandRequestParams } from "../shared/command-tab";
+import { PERP_SERIES } from "./series";
+import { perpsCache, perpsHistoryCache, perpsListCache, perpsMarketCache, perpsRankingsCache } from "./client";
+import { perpsHeadless } from "./headless";
+import { PerpsPane } from "./pane";
+
+/**
+ * A named market has its own pane, and asking for it again (PERP, a stock's perpetual row in DES or QQ) brings that
+ * pane back to the market's history, whatever it was showing: the request is stamped onto the instance, so the pane
+ * sees it even when nothing else about the instance changed. Without a market, the board.
+ */
+export function perpsInstance(arg: string | undefined): PaneTemplateInstanceConfig {
+  const market = arg?.trim() ?? "";
+  if (!market) return { placement: "floating", settings: { market } };
+  return { instanceId: `perps:${encodeURIComponent(market.toUpperCase()).replace(/%/g, "~")}`, placement: "floating",
+    settings: { market }, params: commandRequestParams({ market }) };
+}
+
+export const perpsModule: PluginModule = {
+  series: PERP_SERIES,
+  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: "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", "basis trade", "carry", "venue", "funding spread", "long short ratio", "long/short", "positioning"],
+    shortcut: { prefix: "PERP", argKind: "text", argOptional: true, argPlaceholder: "market" }, headless: perpsHeadless,
+    createInstance: (_ctx, options) => perpsInstance(options?.arg) }],
+  setup(ctx) {
+    for (const cache of [perpsCache, perpsHistoryCache, perpsListCache, perpsMarketCache, perpsRankingsCache]) cache.attach(ctx.persistence);
+  },
+  dispose() { for (const cache of [perpsCache, perpsHistoryCache, perpsListCache, perpsMarketCache, perpsRankingsCache]) cache.reset(); },
+};

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

@@ -0,0 +1,139 @@
+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";
+import { useLivePerpRows } from "./live-rows";
+
+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 };
+const NO_SYMBOLS: ReadonlySet<string> = new Set();
+
+export interface ListPerpetuals {
+  /** Each row's contract by ticker, null for none; a row is missing while its first answer loads. */
+  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, liveSymbols: ReadonlySet<string> = NO_SYMBOLS): 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;
+  const fetched = useMemo(() => {
+    if (!enabled) return NO_PERPETUALS;
+    const byListing = new Map<string, PerpBoardRow | null>();
+    data?.listings.forEach((listing, index) => byListing.set(listingKey(listing), data.results[index]?.market ?? null));
+    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);
+    }
+    return { markets, version: 0, stale: !!data?.stale };
+  }, [data, enabled, loading, tickers]);
+  // The contracts of the rows in view follow the quote stream, as many as useLivePerpRows follows; each is subscribed
+  // once however many rows share it.
+  const liveRows = useMemo(() => {
+    const rows = new Map<string, PerpBoardRow>();
+    for (const symbol of liveSymbols) {
+      const row = fetched.markets.get(symbol);
+      if (row) rows.set(row.marketId, row);
+    }
+    return [...rows.values()];
+  }, [fetched, liveSymbols]);
+  const live = useLivePerpRows(liveRows, { surface: "watchlist", enabled: enabled && liveRows.length > 0 });
+  return useMemo(() => {
+    if (fetched === NO_PERPETUALS) return NO_PERPETUALS;
+    const byMarket = new Map(live.rows.map((row) => [row.marketId, row]));
+    const markets = byMarket.size
+      ? new Map([...fetched.markets].map(([symbol, row]) => [symbol, row ? byMarket.get(row.marketId) ?? row : row]))
+      : fetched.markets;
+    versionRef.current += 1;
+    return { markets, version: versionRef.current, stale: fetched.stale };
+  }, [fetched, live.rows]);
+}

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

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