gloomberb 0.16.4 → 0.16.6

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

@@ -1,6 +1,6 @@
 import { apiClient } from "../../../api-client";
-import type { PerpBoardPayload, PerpBoardQuery, PerpBoardRow, PerpEquityListing, PerpHistoryPayload, PerpHistoryQuery, PerpLongShortPoint, PerpLongShortRatio, PerpMarketPayload,
-  PerpRankingsPayload } from "../../../api-client/perps";
+import type { PerpBoardPayload, PerpBoardQuery, PerpBoardRow, PerpEquitiesPayload, PerpEquityListing, PerpHistoryPayload, PerpHistoryQuery, PerpLongShortPoint,
+  PerpLongShortRatio, PerpMarketPayload, PerpRankingsPayload } from "../../../api-client/perps";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { cachedCloudResource, loadCloudResource } from "../shared/cloud-resource";
 
@@ -81,15 +81,18 @@ export const loadPerpsRankings = (access: string, force = false) => loadCloudRes
 const compareKey = (baseAsset: string, access: string) => `compare:v1:${baseAsset.toUpperCase()}:${access}`;
 export const cachedPerpsCompare = (baseAsset: string, access: string) => cachedCloudResource(perpsCache, compareKey(baseAsset, access), (data) => validatePerpsCompare(data, baseAsset));
 export const loadPerpsCompare = (baseAsset: string, access: string, force = false) => loadCloudResource(perpsCache, compareKey(baseAsset, access), () => fetchPerpsCompare(baseAsset), { force, validate: (data) => validatePerpsCompare(data, baseAsset) });
+const sameListing = (value: PerpEquityListing | null | undefined, listing: PerpEquityListing) =>
+  value?.symbol === listing.symbol && value.exchange === listing.exchange;
+/** The server's proof that a stock contract belongs to the listing asked about. */
+const provesListing = (row: PerpBoardRow, listing: PerpEquityListing) => {
+  const match = row.equityMatch;
+  return sameListing(match?.listing, listing) && row.assetClass === "stocks" && !!match?.underlying.exchange
+    && match.underlying.symbol === row.underlyingSymbol
+    && (match.basis === "issuer" || match.basis === "listing" && sameListing(match.underlying, listing));
+};
 function validatePerpsEquity(data: PerpBoardPayload, listing: PerpEquityListing): PerpBoardPayload {
   validatePerpsBoard(data);
-  const same = (value: PerpEquityListing | null | undefined) => value?.symbol === listing.symbol && value.exchange === listing.exchange;
-  if (!same(data.listing) || !data.rows.every((row) => {
-    const match = row.equityMatch;
-    return same(match?.listing) && row.assetClass === "stocks" && !!match?.underlying.exchange
-      && match.underlying.symbol === row.underlyingSymbol
-      && (match.basis === "issuer" || match.basis === "listing" && same(match.underlying));
-  })) throw new Error("The server returned perpetuals for another listing");
+  if (!sameListing(data.listing, listing) || !data.rows.every((row) => provesListing(row, listing))) throw new Error("The server returned perpetuals for another listing");
   return data;
 }
 export const loadPerpsEquity = (listing: PerpEquityListing, access: string, force = false) => {
@@ -98,6 +101,38 @@ export const loadPerpsEquity = (listing: PerpEquityListing, access: string, forc
     async () => validate(await apiClient.getCloudPerpsEquity(listing.symbol, listing.exchange)), { force, validate });
 };
 
+/** The most listings the server looks up in one request; a longer list asks in pages of this size. */
+const PERP_EQUITIES_PAGE = 100;
+export const perpsListCache = createPluginCache<PerpEquitiesPayload>({ kind: "perps-equities", source: "gloom-cloud", schemaVersion: 1,
+  policy: { staleMs: 60_000, expireMs: 86_400_000 } });
+/** One answer per listing asked about, in its order; a contract only with its proof for that listing. */
+export function validatePerpsEquities(data: PerpEquitiesPayload, listings: readonly PerpEquityListing[]): PerpEquitiesPayload {
+  if (!envelope(data) || !Array.isArray(data.results) || data.results.length !== listings.length
+    || !data.results.every((result, index) => !!result && (result.market === null
+      || sameListing(result.listing, listings[index]!) && validRow(result.market) && provesListing(result.market, listings[index]!))))
+    throw new Error("The server returned perpetuals for another listing");
+  return data;
+}
+async function fetchPerpsEquities(listings: readonly PerpEquityListing[], client: Pick<typeof apiClient, "getCloudPerpsEquities"> = apiClient): Promise<PerpEquitiesPayload> {
+  const pages: PerpEquityListing[][] = [];
+  for (let start = 0; start < listings.length; start += PERP_EQUITIES_PAGE) pages.push(listings.slice(start, start + PERP_EQUITIES_PAGE));
+  const answers = await Promise.all(pages.map(async (page) => validatePerpsEquities(await client.getCloudPerpsEquities(page), page)));
+  const [first] = answers;
+  if (!first) return { status: "ok", asOf: null, access: "preview", locked: 0, results: [] };
+  return { ...first, locked: answers.reduce((sum, answer) => sum + answer.locked, 0), results: answers.flatMap((answer) => answer.results) };
+}
+/**
+ * The perpetual of every listing in a watchlist or portfolio, from one request (one per hundred listings): the
+ * rows share one lookup instead of asking for each stock. `listings` come sorted and unique, so a list keeps its
+ * cache entry whatever its order; cached per account and plan like the other perps loaders, and a failed refresh
+ * keeps the last answer, marked stale.
+ */
+export const loadPerpsEquities = (listings: readonly PerpEquityListing[], access: string, force = false) => {
+  const validate = (data: PerpEquitiesPayload) => validatePerpsEquities(data, listings);
+  return loadCloudResource(perpsListCache, `equities:v1:${listings.map((listing) => `${listing.symbol}:${listing.exchange}`).join(",")}:${access}`,
+    () => fetchPerpsEquities(listings), { force, validate });
+};
+
 function validatePerpsMarket(data: PerpMarketPayload): PerpMarketPayload {
   validatePerpsBoard(data);
   if (!Array.isArray(data.evidence) || !data.evidence.every((row) => date(row.period_at) && date(row.received_at) && typeof row.fingerprint === "string" && (row.superseded_at === null || date(row.superseded_at)))) throw new Error("The server returned unreadable market evidence");
@@ -105,16 +140,55 @@ function validatePerpsMarket(data: PerpMarketPayload): PerpMarketPayload {
 }
 const fetchPerpsMarket = async (marketId: string, client: Pick<typeof apiClient, "getCloudPerpsMarket"> = apiClient) => validatePerpsMarket(await client.getCloudPerpsMarket(marketId));
 
-export async function fetchPerpSelection(input: string, client: Pick<typeof apiClient, "getCloudPerpsBoard" | "getCloudPerpsMarket"> = apiClient): Promise<PerpMarketPayload> {
-  const query = input.trim() || "BTC";
-  if (/^(hyperliquid|binance|bybit|okx|deribit|coinbase|kraken|dydx):/.test(query)) return fetchPerpsMarket(query, client);
+/**
+ * The Market column's label for a market on a Hyperliquid builder dex (`SP500 · XYZ`) read back as the `xyz:SP500`
+ * identity the board search and the venue know it by; anything else is returned as typed.
+ */
+export const marketQuery = (input: string) => {
+  const label = /^([^\s·]+)\s*·\s*([^\s·]+)$/.exec(input.trim());
+  return label ? `${label[2]!.toLowerCase()}:${label[1]}` : input.trim();
+};
+// An identity or symbol, never free text: a market id the server rejects as malformed would surface as raw JSON.
+const SAFE_MARKET_ID = /^[\w.:-]+$/;
+// A venue's usual contract for a base asset, by the identity a market lookup fetches without the board (the free
+// board preview lists a few markets per asset class, an individual market is shown whole). Only the venues
+// Gloom Cloud collects are listed; another venue has no contract to open.
+const VENUE_CONTRACTS: Record<string, (base: string) => string[]> = {
+  hyperliquid: (base) => [`hyperliquid:default:${base}`, `hyperliquid:xyz:${base}`],
+  binance: (base) => [`binance:${base}USDT`],
+  bybit: (base) => [`bybit:${base}USDT`],
+  okx: (base) => [`okx:${base}-USDT-SWAP`, `okx:${base}-USD-SWAP`],
+};
+/**
+ * One market by base asset, underlying, symbol, canonical identity or the Market column's label (`SP500 · XYZ`).
+ * A `venue` opens that venue's contract, from the board's matches or by its own identity; when the venue has none
+ * the usual market comes back and the caller sees its venue differ.
+ */
+export async function fetchPerpSelection(input: string, client: Pick<typeof apiClient, "getCloudPerpsBoard" | "getCloudPerpsMarket"> = apiClient, venue?: string): Promise<PerpMarketPayload> {
+  const query = marketQuery(input) || "BTC";
+  if (/^(hyperliquid|binance|bybit|okx|deribit|coinbase|kraken|dydx):/.test(query)) {
+    const result = await fetchPerpsMarket(query, client);
+    // A watchlist row is saved upper case; Hyperliquid writes its thousand-unit coins with a small k (kPEPE).
+    const kCoin = /^hyperliquid:default:K([A-Z0-9]+)$/.exec(query);
+    return result.rows.length || !kCoin ? result : fetchPerpsMarket(`hyperliquid:default:k${kCoin[1]}`, client);
+  }
   const board = validatePerpsBoard(await client.getCloudPerpsBoard({ search: query }));
-  const exact = board.rows.filter((row) => !row.delisted && [row.baseAsset, row.symbol, row.underlyingSymbol].some((value) => value?.toUpperCase() === query.toUpperCase()));
+  const matches = board.rows.filter((row) => !row.delisted && [row.baseAsset, row.symbol, row.underlyingSymbol].some((value) => value?.toUpperCase() === query.toUpperCase()));
+  const exact = venue && matches.some((row) => row.venue === venue) ? matches.filter((row) => row.venue === venue) : matches;
   const market = exact.find((row) => row.dex === "default") ?? exact.find((row) => row.dex === "xyz") ?? exact[0];
+  if (venue && market?.venue !== venue && /^[A-Za-z0-9]+$/.test(query)) {
+    for (const id of VENUE_CONTRACTS[venue]?.(matches[0]?.baseAsset ?? query.toUpperCase()) ?? []) {
+      const result = await fetchPerpsMarket(id, client);
+      if (result.rows.length) return result;
+    }
+  }
   if (market) return fetchPerpsMarket(market.marketId, client);
-  // Individual latest-value previews are intentionally broader than the fixed board preview.
-  for (const dex of ["default", "xyz"]) {
-    const result = await fetchPerpsMarket(`hyperliquid:${dex}:${query.toUpperCase()}`, client);
+  // Individual latest-value previews are intentionally broader than the fixed board preview. A builder dex's own
+  // identity (`xyz:SP500`) names its Hyperliquid market; a bare symbol is tried on the default dex, then xyz.
+  const builder = /^([a-z0-9]+):(.+)$/i.exec(query);
+  for (const id of builder ? [`hyperliquid:${builder[1]!.toLowerCase()}:${builder[2]}`] : ["default", "xyz"].map((dex) => `hyperliquid:${dex}:${query.toUpperCase()}`)) {
+    if (!SAFE_MARKET_ID.test(id)) continue;
+    const result = await fetchPerpsMarket(id, client);
     if (result.rows.length) return result;
   }
   return { ...board, rows: [], evidence: [], methodologyUrl: "https://gloom.sh/docs/perpetuals" };

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

@@ -1,33 +1,68 @@
 import { useCallback } from "react";
 import { isAccessDenied } from "../../../api-client/errors";
 import { usePlanAccess } from "../../../api-client/plan-access";
-import { ActionRow } from "../../../components";
-import { useAsyncResource, useAutoRefresh, usePluginAppActions } from "../../../public/react";
+import type { PerpBoardRow } from "../../../api-client/perps";
+import { ActionRow, usePaneLinkMenuEntry } from "../../../components";
+import { displayWidth } from "../../../utils/format";
+import { useAsyncResource, useAutoRefresh } from "../../../public/react";
 import { useResearchCloudSession } from "../shared/research-cloud-session";
 import { perpEquityIdentity } from "./equity-identity";
-import { loadPerpsEquity } from "./client";
+import { perpetualListing } from "../../../tickers/perpetual-listing";
+import { loadPerpSelection, loadPerpsEquity } from "./client";
 import { compact, percent, perpDescription, price, readingTime } from "./model";
+import { openPerpLabel, useOpenPerpMarket } from "./open-market";
 
-/** A failed optional market comparison never blocks a stock's quote. */
-export function PerpEquityRow({ symbol, exchange, instrumentType, maxRows = 3 }: { symbol: string; exchange?: string; instrumentType?: string; maxRows?: number }) {
+/**
+ * A stock's perpetuals, or for a perpetual market itself its own contract: funding, open interest and when the venue
+ * was read, beside the quote. A failed optional market comparison never blocks a stock's quote.
+ */
+export function PerpEquityRow({ symbol, exchange, instrumentType, maxRows = 3, width }: {
+  symbol: string; exchange?: string; instrumentType?: string; maxRows?: number;
+  /** Columns the row has, in a narrow card: the contract gets its short name and the least read figures go first. */
+  width?: number;
+}) {
   const session = useResearchCloudSession();
   const plan = usePlanAccess();
-  const { createPaneFromTemplate } = usePluginAppActions();
-  const identity = perpEquityIdentity(symbol, exchange);
+  const marketId = perpetualListing(symbol, exchange)?.marketId ?? null;
+  const identity = marketId ? null : perpEquityIdentity(symbol, exchange);
   const listingSymbol = identity?.symbol;
   const listingExchange = identity?.exchange;
-  const enabled = !!identity && ["STK", "EQUITY", "STOCK", "COMMON STOCK"].includes(instrumentType?.toUpperCase() ?? "");
+  const enabled = !!marketId || !!identity && ["STK", "EQUITY", "STOCK", "COMMON STOCK"].includes(instrumentType?.toUpperCase() ?? "");
   const accessKey = `${session.requestKey}:${plan.hasProAccess ? "pro" : "preview"}`;
-  const loader = useCallback((force: boolean) => loadPerpsEquity({ symbol: listingSymbol!, exchange: listingExchange! }, accessKey, force), [listingSymbol, listingExchange, accessKey]);
+  const loader = useCallback((force: boolean) => marketId
+    ? loadPerpSelection(marketId, accessKey, force)
+    : loadPerpsEquity({ symbol: listingSymbol!, exchange: listingExchange! }, accessKey, force), [marketId, listingSymbol, listingExchange, accessKey]);
   const resource = useAsyncResource(enabled ? loader : null, { clearOnError: isAccessDenied });
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
-  const rows = resource.data?.payload.rows.filter((row) => !row.delisted) ?? [];
+  const rows = resource.data?.payload.rows.filter((row) => !row.delisted && (!marketId || row.marketId === marketId)) ?? [];
   if (!enabled || !rows.length) return null;
-  return <>{rows.slice(0, maxRows).map((row) => {
-    const read = readingTime(row.observedAt);
-    return <ActionRow key={row.marketId} height={2}
-      // Funding reads per 8h here as it does in PERP, whatever interval the venue pays on.
-      label={`${row.baseAsset} · ${perpDescription(row)}  ${price(row.markPrice)} ${row.quoteCurrency}  ${percent(row.underlyingPremium, 2)} vs last${row.stale || resource.data?.stale ? " · stale" : ""}\nFunding ${percent(row.fundingRate8h, 4)} per 8 h · OI ${compact(row.openInterestUsd)} USD · oracle ${percent(row.premium, 2)}${read ? ` · as of ${read}` : ""}`}
-      onPress={() => createPaneFromTemplate("perps-pane", { arg: row.marketId })} />;
-  })}</>;
+  return <>{rows.slice(0, maxRows).map((row) => <PerpRow key={row.marketId} row={row} stale={!!resource.data?.stale} width={width} own={!!marketId} />)}</>;
+}
+
+/** The parts that fit `width`, dropped from the end; all of them when the width is not known. */
+function fitParts(parts: string[], separator: string, width: number | undefined): string {
+  let kept = parts;
+  while (width !== undefined && kept.length > 1 && displayWidth(kept.join(separator)) > width) kept = kept.slice(0, -1);
+  return kept.join(separator);
+}
+
+/**
+ * One contract on the stock, or the market the quote is of (`own`, whose mark the quote already shows): a click, or
+ * its entry in the pane menu, opens PERP on that market.
+ */
+function PerpRow({ row, stale, width, own = false }: { row: PerpBoardRow; stale: boolean; width?: number; own?: boolean }) {
+  const openMarket = useOpenPerpMarket();
+  const open = () => openMarket(row.marketId);
+  usePaneLinkMenuEntry(`function:perps-pane:${row.marketId}`, openPerpLabel(row), open);
+  const read = readingTime(row.observedAt);
+  const staleText = row.stale || stale ? " · stale" : "";
+  const figures = own
+    ? row.underlyingPremium != null ? [`${percent(row.underlyingPremium, 2)} vs ${row.underlyingSymbol ?? "underlying"} last${staleText}`] : staleText ? ["stale"] : []
+    : [`${price(row.markPrice)} ${row.quoteCurrency}`, `${percent(row.underlyingPremium, 2)} vs last${staleText}`];
+  const named = [`${row.baseAsset} · ${perpDescription(row)}`, ...figures].join("  ");
+  const first = width === undefined || displayWidth(named) <= width ? named : [`${row.baseAsset} perpetual`, ...figures].join("  ");
+  // Funding reads per 8h here as it does in PERP, whatever interval the venue pays on.
+  const second = fitParts([`Funding ${percent(row.fundingRate8h, 4)} per 8 h`, `OI ${compact(row.openInterestUsd)} USD`, `oracle ${percent(row.premium, 2)}`,
+    ...(read ? [`as of ${read}`] : [])], " · ", width);
+  return <ActionRow height={2} label={`${first}\n${second}`} onPress={open} />;
 }

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

@@ -0,0 +1,66 @@
+import type { PerpBoardRow } from "../../../api-client/perps";
+import type { HeadlessPaneFreshness } from "../../../types/headless";
+import { venueName, venuesOf } from "./model";
+
+type Dated = Pick<PerpBoardRow, "venue" | "observedAt">;
+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("; ")}`;
+}
+
+/**
+ * How current a view of perpetual markets is: each venue's own newest observation, polled rather than streamed and
+ * stale after an hour without a poll, and what the funding figures it shows (`funding`) are. The report, the capture
+ * and the pane footer all read this, so they end with the same line.
+ */
+export function perpFreshness(rows: readonly Dated[], { funding = [], venue = "all", now = Date.now() }: {
+  funding?: readonly Funded[]; venue?: string; now?: number;
+} = {}): HeadlessPaneFreshness {
+  const sources = venuesOf(rows).map((id) => ({ source: venueName(id), asOf: new Date(Math.max(...rows.filter((row) => row.venue === id)
+    .map((row) => Date.parse(row.observedAt)))).toISOString() }));
+  const source = sources.length ? sources.map((entry) => entry.source).join(", ") : venue !== "all" ? venueName(venue) : null;
+  const note = fundingNote(funding, now);
+  return { ...(source ? { source } : {}), sources, status: "delayed", maxAgeMinutes: 60, ...(note ? { note } : {}) };
+}
+
+/** What a capture reads of a row: when it was observed and whether the venue has stopped answering for it. */
+export const perpObservation = (row: Pick<PerpBoardRow, "observedAt" | "stale">) => ({ observedAt: row.observedAt, stale: row.stale });

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

@@ -1,9 +1,10 @@
 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, fetchPerpsBoard, fetchPerpsCompare, fetchPerpsHistory, fetchPerpsRankings } from "./client";
+import { fetchPerpSelection, fetchPerpsBoard, fetchPerpsCompare, fetchPerpsHistory, fetchPerpsRankings, marketQuery } from "./client";
+import { perpFreshness } from "./freshness";
 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";
+  positioningFields, price, RANKING_COLUMNS, rankingRows, RANKINGS, ratioText, share, time, VENUES, venueName, 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.
@@ -68,9 +69,10 @@ const REVISION_COLUMNS: HeadlessPaneColumn[] = [
   { 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.
+// 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 noMarket = (input: string) => new Error(`No perpetual market matches "${input}". Try BTC, ETH, SP500, xyz:SP500.`);
 
 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.
@@ -79,81 +81,94 @@ const TITLES: Record<typeof PERP_TABS[number], string> = { board: "Perpetual mar
   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 };
+// What a table the free view leaves empty says in place of "No data."; the report's Pro lines say what Pro adds.
+const lockedEmpty = (locked: unknown) => locked ? { empty: "Locked: Gloom Pro" } : {};
+// 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 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." },
+    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." },
+    { 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"] },
+  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: requested } : {}), sort }, ctx.apiClient);
+      const board = await fetchPerpsBoard({ ...(assetClass !== "all" ? { assetClass } : {}), ...(requested ? { search: marketQuery(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),
+      // 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), ...lockedEmpty(board.locked && !rows.length) }], complete: !board.locked && board.status === "ok",
+        errors: board.locked ? [lock] : [], 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);
-      const sections: HeadlessBundleSection[] = RANKINGS.map((ranking) => ({ title: ranking.label, columns: rankingTextColumns(ranking), rows: copy(rankingRows(rankings, ranking.key)) }));
+      const sections: HeadlessBundleSection[] = RANKINGS.map((ranking) => ({ title: ranking.label, columns: rankingTextColumns(ranking), rows: copy(rankingRows(rankings, ranking.key)), ...lockedEmpty(rankings.locked) }));
+      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: listFreshness(RANKINGS.flatMap((ranking) => rankingRows(rankings, ranking.key)), rankings.asOf), metadata: listMetadata(rankings) };
+        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 base = requested.includes(":") ? (await fetchPerpSelection(requested, ctx.apiClient)).rows[0]?.baseAsset ?? requested : (requested || DEFAULT_MARKET).toUpperCase();
+      const identity = marketQuery(requested);
+      const base = identity.includes(":") ? (await fetchPerpSelection(identity, ctx.apiClient)).rows[0]?.baseAsset ?? identity : (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(", ")}.`);
+      if (!compare.rows.length && !compare.locked) throw noMarket(requested || base);
       const spread = fundingSpread(compare.rows);
-      return { sections: [{ title: "Contracts", columns: COMPARE_TEXT_COLUMNS, rows: copy(compare.rows) },
+      const notices = [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]} --tab compare.`]), ...venueUnused(String(args.options.venue ?? "all"), "compare")];
+      return { sections: [{ title: "Contracts", columns: COMPARE_TEXT_COLUMNS, rows: copy(compare.rows), ...lockedEmpty(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")] : [],
-        freshness: listFreshness(compare.rows, compare.asOf),
-        metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET, notices: [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]} --tab compare.`] }),
+        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;
-    const market = await fetchPerpSelection(search, ctx.apiClient);
+    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 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,
+    if (!selected) throw noMarket(search);
+    const notices = [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]}.`]), ...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: 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 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 })) }],
+        { title: "Observation revisions", columns: REVISION_COLUMNS, rows: market.evidence.map((row) => ({ ...row })), ...lockedEmpty(market.access !== "pro") }],
       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", 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 })) }],
+    const locked = lockedEmpty(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", 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,33 @@
+import type { PaneTemplateInstanceConfig } from "../../../types/plugin";
 import type { PluginModule } from "../plugin-module";
-import { perpsCache, perpsHistoryCache, perpsMarketCache, perpsRankingsCache } from "./client";
+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", "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); perpsRankingsCache.attach(ctx.persistence); },
-  dispose() { perpsCache.reset(); perpsHistoryCache.reset(); perpsMarketCache.reset(); perpsRankingsCache.reset(); },
+    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(); },
 };