@gloom-sh/terminal 0.0.0-stage → 0.19.0

package/src/market-data/perpetual-premium.ts

@@ -0,0 +1,32 @@
+import type { Quote } from "../types/financials";
+
+/** What a stock perpetual's premium to its stock is worked out from: its row, as PERP and the lists read it. */
+export interface PerpetualPremiumRow {
+  markPrice?: number | null;
+  priceMultiplier?: number;
+  underlying?: { currency: string } | null;
+  /**
+   * How Gloom Cloud matched the contract to the listing asked about: that very listing, or another of its issuer's
+   * (a GOOGL contract for GOOG, BRK.A's for BRK.B), whose price is not the contract's reference.
+   */
+  equityMatch?: { basis: "listing" | "issuer" } | null;
+  /** Gloom Cloud's figure: against the stock's stored price, or its regular close while its market is shut. */
+  underlyingPremium: number | null;
+}
+
+/**
+ * A stock perpetual's premium to its stock. While the stock's market is open, the stored price Gloom Cloud compares a
+ * streaming mark with is minutes old, so a live quote of the stock, where the screen has one, is the reference
+ * instead, when the contract tracks that very listing. Otherwise (another listing of the issuer, a quote that is
+ * itself a contract's, a delayed quote, a shut market, another currency) the row's own figure stands.
+ */
+export function premiumToUnderlying(row: PerpetualPremiumRow, stock: Quote | null | undefined): number | null {
+  const mark = row.markPrice;
+  if (
+    mark == null || !row.underlying || row.equityMatch?.basis !== "listing" || !stock || stock.instrumentType === "PERP"
+    || stock.stale === true || stock.dataSource !== "live"
+    || stock.marketState !== "REGULAR" || stock.currency !== row.underlying.currency
+    || !Number.isFinite(stock.price) || stock.price <= 0
+  ) return row.underlyingPremium;
+  return mark / (row.priceMultiplier ?? 1) / stock.price - 1;
+}

package/src/market-data/portfolio-financials.ts

@@ -0,0 +1,37 @@
+import type { TickerFinancials } from "../types/financials";
+import type { TickerRecord } from "../types/ticker";
+import { instrumentFromTicker, type TickerInstrumentOptions } from "./request-types";
+
+const withoutPriceCache = new WeakMap<TickerFinancials, TickerFinancials>();
+
+/** The same record without a price, kept stable so row caches still hit. */
+function withoutPrice(financials: TickerFinancials): TickerFinancials {
+  let stripped = withoutPriceCache.get(financials);
+  if (!stripped) {
+    stripped = { ...financials, quote: undefined, priceHistory: [] };
+    withoutPriceCache.set(financials, stripped);
+  }
+  return stripped;
+}
+
+export function buildPortfolioFinancialsMap(
+  portfolioTickers: TickerRecord[],
+  cachedFinancials: Map<string, TickerFinancials>,
+  marketFinancials: Map<string, TickerFinancials>,
+  options: TickerInstrumentOptions = {},
+): Map<string, TickerFinancials> {
+  const result = new Map<string, TickerFinancials>();
+  for (const ticker of portfolioTickers) {
+    const symbol = ticker.metadata.ticker;
+    const cached = cachedFinancials.get(symbol);
+    const instrument = instrumentFromTicker(ticker, symbol, options);
+    if (cached) {
+      // The symbol-only app cache cannot establish a broker price's contract.
+      const ambiguousPrice = options.portfolioId && (!instrument || instrument.brokerId || ticker.metadata.broker_contracts?.length);
+      result.set(symbol, ambiguousPrice ? withoutPrice(cached) : cached);
+    }
+    const scoped = marketFinancials.get(symbol);
+    if (scoped) result.set(symbol, instrument ? scoped : withoutPrice(scoped));
+  }
+  return result;
+}

package/src/market-data/published-apac-sessions.ts

@@ -0,0 +1,99 @@
+// Published full-day closures (weekend dates omitted) for Asia-Pacific venues, EGX and Wiener
+// Boerse, not a holiday-rule engine. A year a venue has not published is unknown, not
+// open: every weekday of it reads as a session. Half-day sessions (HKEX and
+// SGX eves, ASX's 14:10 closes) are not modelled. Checked 2026-10-09:
+// KRX, also KOSDAQ: http://open.krx.co.kr/contents/MKD/01/0110/01100305/MKD01100305.jsp
+// TWSE, whose closures TPEx shares: https://www.twse.com.tw/en/trading/holiday.html
+//   (2027 not yet published; 12 and 13 Feb 2026 are clearing-only days without trading)
+//   and a day it closed unscheduled: 23 Oct 2026 for Typhoon Champi, announced the evening before
+// BHB closes on the dates its own daily closes skip in 2026, which match the holidays it lists
+//   (some moved, as its list warns), and on National Day, 16 and 17 Dec. Its week is Sunday to Thursday.
+// HKEX: https://www.hkex.com.hk/-/media/HKEX-Market/Services/Circulars-and-Notices/Participant-and-Members-Circulars/SEHK/2025/ce_SEHK_CT_075_2025.pdf
+//   and https://www.hkex.com.hk/-/media/HKEX-Market/Services/Circulars-and-Notices/Participant-and-Members-Circulars/SEHK/2026/ce_SEHK_CT_077_2026.pdf
+// Wiener Boerse closes its main market (VIE) and the Vienna MTF (WBDM) on its stock exchange holidays,
+//   and trades on Austria's other public holidays:
+//   https://www.wienerborse.at/uploads/u/cms/files/trading/stock-exchange-holidays-2026-en.pdf (and -2027-en.pdf)
+// SGX closes on Singapore's gazetted public holidays, one on a Sunday moving to the Monday:
+//   https://www.sgx.com/stock-exchange/trading and https://www.mom.gov.sg/employment-practices/public-holidays
+// MSX closes on the holidays its site lists (msx.om exchange holidays, read 10 Oct 2026).
+//   Its week is Sunday to Thursday.
+// ASX: https://www.asx.com.au/markets/market-resources/trading-hours-calendar/cash-market-trading-hours/trading-calendar
+// EGX closes on Egypt's public holidays, often moved to the Thursday of their
+// week (Armed Forces Day, Tuesday 6 Oct 2026, to Thursday 8 Oct, by the
+// exchange's statement of 5 Oct). Its week is Sunday to Thursday.
+const KRX_CLOSURES: Record<number, readonly string[]> = {
+  2026: [
+    "01-01", "02-16", "02-17", "02-18", "03-02", "05-01", "05-05", "05-25", "06-03",
+    "07-17", "08-17", "09-24", "09-25", "10-05", "10-09", "12-25", "12-31",
+  ],
+  2027: [
+    "01-01", "02-08", "02-09", "03-01", "05-03", "05-05", "05-13", "07-19", "08-16",
+    "09-14", "09-15", "09-16", "10-04", "10-11", "12-27", "12-31",
+  ],
+};
+
+const WIENER_BOERSE_CLOSURES: Record<number, readonly string[]> = {
+  2026: ["01-01", "04-03", "04-06", "05-01", "10-26", "12-24", "12-25", "12-31"],
+  2027: ["01-01", "03-26", "03-29", "10-26", "12-24", "12-31"],
+};
+
+const TWSE_CLOSURES: Record<number, readonly string[]> = {
+  2026: [
+    "01-01", "02-12", "02-13", "02-16", "02-17", "02-18", "02-19", "02-20", "02-27",
+    "04-03", "04-06", "05-01", "06-19", "09-25", "09-28", "10-09", "10-23", "10-26", "12-25",
+  ],
+};
+
+/** Closures by canonical venue code. */
+export const PUBLISHED_APAC_CLOSURES: Readonly<Record<string, Record<number, readonly string[]>>> = {
+  KRX: KRX_CLOSURES,
+  KOSDAQ: KRX_CLOSURES,
+  TWSE: TWSE_CLOSURES,
+  TPEX: TWSE_CLOSURES,
+  BHB: {
+    2026: [
+      "01-01", "03-22", "03-23", "03-24", "05-03", "05-26", "05-27", "05-28", "05-31", "06-16", "06-25", "06-28",
+      "08-25", "12-16", "12-17",
+    ],
+  },
+  HKEX: {
+    2026: [
+      "01-01", "02-17", "02-18", "02-19", "04-03", "04-06", "04-07", "05-01", "05-25",
+      "06-19", "07-01", "10-01", "10-19", "12-25",
+    ],
+    2027: [
+      "01-01", "02-08", "02-09", "03-26", "03-29", "04-05", "05-13", "06-09", "07-01",
+      "09-16", "10-01", "10-08", "12-27",
+    ],
+  },
+  SGX: {
+    2026: ["01-01", "02-17", "02-18", "04-03", "05-01", "05-27", "06-01", "08-10", "11-09", "12-25"],
+    2027: ["01-01", "02-08", "03-10", "03-26", "05-17", "05-20", "08-09", "10-28"],
+  },
+  VIE: WIENER_BOERSE_CLOSURES,
+  WBDM: WIENER_BOERSE_CLOSURES,
+  MSX: {
+    2026: ["01-15", "01-18", "03-19", "03-22", "03-23", "05-26", "05-27", "05-28", "06-18", "08-27", "11-25", "11-26"],
+  },
+  ASX: {
+    2026: ["01-01", "01-26", "04-03", "04-06", "06-08", "12-25", "12-28"],
+    2027: ["01-01", "01-26", "03-26", "03-29", "06-14", "12-27", "12-28"],
+  },
+  EGX: {
+    2026: [
+      "01-01", "01-07", "01-29", "03-19", "03-22", "03-23", "04-12", "04-13", "05-07",
+      "05-26", "05-27", "05-28", "05-31", "06-18", "07-02", "07-23", "08-27", "10-08",
+    ],
+  },
+};
+
+/** True only for a published full-day closure; unpublished years are unknown, not open. */
+export function isPublishedApacClosure(exchange: string, date: string): boolean {
+  if (!Object.hasOwn(PUBLISHED_APAC_CLOSURES, exchange)) return false;
+  return PUBLISHED_APAC_CLOSURES[exchange]![Number(date.slice(0, 4))]?.includes(date.slice(5)) ?? false;
+}
+
+/** True when the venue's closures of that year are published. */
+export function hasPublishedApacCalendar(exchange: string, year: number): boolean {
+  return Object.hasOwn(PUBLISHED_APAC_CLOSURES, exchange) && PUBLISHED_APAC_CLOSURES[exchange]![year] !== undefined;
+}

package/src/market-data/published-cn-sessions.ts

@@ -0,0 +1,25 @@
+// Published SSE and SZSE equity closures (weekend dates omitted), not a holiday-rule engine.
+// Sources (checked 2026-10-04):
+// https://www.sse.com.cn/disclosure/dealinstruc/closed/c/c_20251222_10802510.shtml
+// https://investor.szse.cn/disclosure/notice/general/t20251222_618087.html
+// https://investor.szse.cn/disclosure/notice/general/t20260917_622911.html
+// https://www.gov.cn/zhengce/zhengceku/202511/content_7047091.htm
+// Past dates also match the weekdays missing from Shanghai Composite daily bars.
+// Weekend make-up working days are not exchange trading sessions.
+const CN_CLOSURES: Record<number, readonly string[]> = {
+  2026: [
+    "01-01", "01-02", "02-16", "02-17", "02-18", "02-19", "02-20", "02-23",
+    "04-06", "05-01", "05-04", "05-05", "06-19", "09-25", "10-01", "10-02",
+    "10-05", "10-06", "10-07",
+  ],
+};
+
+/** True only for a published full-day closure; unpublished years are unknown, not open. */
+export function isPublishedCnClosure(date: string): boolean {
+  return CN_CLOSURES[Number(date.slice(0, 4))]?.includes(date.slice(5)) ?? false;
+}
+
+/** True when the closures of that year are published. */
+export function hasPublishedCnCalendar(year: number): boolean {
+  return CN_CLOSURES[year] !== undefined;
+}

package/src/market-data/published-futures-sessions.ts

@@ -0,0 +1,69 @@
+// Published trade-date holidays of the futures venues quotes name (weekend
+// dates omitted), not a holiday-rule engine: weekdays with no trade date, on
+// which nothing settles. CME Globex trades an abbreviated session on most of
+// them and books it on the next trade date; ICE Futures U.S. softs do not
+// trade at all. A year a venue has not published is unknown, not open.
+// Checked 2026-10-21:
+// CME Group, one calendar for CME, CBOT, NYMEX and COMEX:
+//   https://www.cmegroup.com/trading-hours.html (2026 and 2027 Globex holiday schedules and notes)
+//   and its clearing advisories, such as
+//   https://www.cmegroup.com/tools-information/holiday-calendar/files/2026/2026-memorial-day-clearing-advisory.pdf
+//   ("Prices will be carried forward from Prior day").
+// ICE Futures U.S. softs (cocoa, coffee, cotton, FCOJ, sugar):
+//   https://www.ice.com/publicdocs/futures_us/exchange_notices/ICE_Futures_US_Exchange_Notice_2026_Holiday_Calendar_20260609.pdf
+//   https://www.ice.com/publicdocs/futures_us/exchange_notices/ICE_Futures_US_Exchange_Notice-2027_Holiday_Calendar_20260604.pdf
+//   Its canola closes on Canada's holidays and its financial contracts trade most US ones; Gloom
+//   Cloud quotes neither (RS=F and DX=F are not tickers), so NYB is its softs.
+// ICE Futures Europe has no listing Gloom Cloud quotes, so no calendar.
+const CME_GROUP_CLOSURES: Record<number, readonly string[]> = {
+  2026: ["01-01", "01-19", "02-16", "04-03", "05-25", "06-19", "07-03", "09-07", "11-26", "12-25"],
+  2027: ["01-01", "01-18", "02-15", "03-26", "05-31", "06-18", "07-05", "09-06", "11-25", "12-24"],
+};
+
+const ICE_US_SOFTS_CLOSURES: Record<number, readonly string[]> = {
+  2026: ["01-01", "01-19", "02-16", "04-03", "05-25", "06-19", "07-03", "09-07", "11-26", "12-25"],
+  2027: ["01-01", "01-18", "02-15", "03-26", "05-31", "06-18", "07-05", "09-06", "11-25", "12-24"],
+};
+
+/** Closures by canonical venue code. */
+export const PUBLISHED_FUTURES_CLOSURES: Readonly<Record<string, Record<number, readonly string[]>>> = {
+  CME: CME_GROUP_CLOSURES,
+  CBT: CME_GROUP_CLOSURES,
+  NYM: CME_GROUP_CLOSURES,
+  CMX: CME_GROUP_CLOSURES,
+  NYB: ICE_US_SOFTS_CLOSURES,
+};
+
+/**
+ * Closures some of a venue's contracts settled on and others did not, which
+ * its calendar cannot say either way. Good Friday 2026 fell on a payrolls
+ * release: CME and CBOT settled their FX, interest rate and crypto contracts
+ * and rolled their equity index and agricultural ones forward from Thursday
+ * (https://www.cmegroup.com/tools-information/holiday-calendar/files/2026/2026-good-friday-clearing-advisory.pdf).
+ * NYMEX and COMEX settled nothing.
+ */
+const PARTIAL_CLOSURES: Readonly<Record<string, readonly string[]>> = {
+  CME: ["2026-04-03"],
+  CBT: ["2026-04-03"],
+};
+
+/** Whether `exchange` (a canonical venue code) is a futures venue with a published calendar. */
+export function isPublishedFuturesVenue(exchange: string): boolean {
+  return Object.hasOwn(PUBLISHED_FUTURES_CLOSURES, exchange);
+}
+
+/** True only for a published trade-date holiday; unpublished years are unknown, not open. */
+export function isPublishedFuturesClosure(exchange: string, date: string): boolean {
+  if (!isPublishedFuturesVenue(exchange)) return false;
+  return PUBLISHED_FUTURES_CLOSURES[exchange]![Number(date.slice(0, 4))]?.includes(date.slice(5)) ?? false;
+}
+
+/**
+ * True when the venue's calendar says whether `date` had a trade date: its
+ * year is published and the day is not one some of its contracts settled and
+ * others did not.
+ */
+export function hasPublishedFuturesCalendar(exchange: string, date: string): boolean {
+  return isPublishedFuturesVenue(exchange) && PUBLISHED_FUTURES_CLOSURES[exchange]![Number(date.slice(0, 4))] !== undefined
+    && !PARTIAL_CLOSURES[exchange]?.includes(date);
+}

package/src/market-data/published-jpx-sessions.ts

@@ -0,0 +1,22 @@
+// Published JPX cash-market closures (weekend dates omitted), not a holiday-rule engine.
+// Source: https://www.jpx.co.jp/english/corporate/about-jpx/calendar/index.html (checked 2026-09-23).
+const JPX_CLOSURES: Record<number, readonly string[]> = {
+  2026: [
+    "01-01", "01-02", "01-12", "02-11", "02-23", "03-20", "04-29", "05-04", "05-05", "05-06",
+    "07-20", "08-11", "09-21", "09-22", "09-23", "10-12", "11-03", "11-23", "12-31",
+  ],
+  2027: [
+    "01-01", "01-11", "02-11", "02-23", "03-22", "04-29", "05-03", "05-04", "05-05",
+    "07-19", "08-11", "09-20", "09-23", "10-11", "11-03", "11-23", "12-31",
+  ],
+};
+
+/** True only for a published full-day closure; unpublished years are unknown, not open. */
+export function isPublishedJpxClosure(date: string): boolean {
+  return JPX_CLOSURES[Number(date.slice(0, 4))]?.includes(date.slice(5)) ?? false;
+}
+
+/** True when the closures of that year are published. */
+export function hasPublishedJpxCalendar(year: number): boolean {
+  return JPX_CLOSURES[year] !== undefined;
+}

package/src/market-data/published-nse-sessions.ts

@@ -0,0 +1,20 @@
+// Published NSE equity closures (weekend dates omitted), not a holiday-rule engine.
+// BSE closes on the same days. Source: https://www.nseindia.com/resources/exchange-communication-holidays
+// (checked 2026-10-04; past dates match the days missing from NSE bhavcopy).
+// The Diwali Muhurat session falls on a weekend and is not modelled.
+const NSE_CLOSURES: Record<number, readonly string[]> = {
+  2026: [
+    "01-15", "01-26", "03-03", "03-26", "03-31", "04-03", "04-14", "05-01",
+    "05-28", "06-26", "09-14", "10-02", "10-20", "11-10", "11-24", "12-25",
+  ],
+};
+
+/** True only for a published full-day closure; unpublished years are unknown, not open. */
+export function isPublishedNseClosure(date: string): boolean {
+  return NSE_CLOSURES[Number(date.slice(0, 4))]?.includes(date.slice(5)) ?? false;
+}
+
+/** True when the closures of that year are published. */
+export function hasPublishedNseCalendar(year: number): boolean {
+  return NSE_CLOSURES[year] !== undefined;
+}

package/src/market-data/published-us-sessions.ts

@@ -0,0 +1,87 @@
+import { canonicalExchange } from "../utils/exchanges";
+import { zonedWallClockToUtcMs } from "../utils/zoned-date-time";
+
+// Cboe's US equity exchanges (BZX/BATS) close on the same published US equity holidays and early closes.
+const NYSE_VENUES = new Set(["NYSE", "AMEX", "ARCA", "NYSE NATIONAL", "NYSE CHICAGO", "NYSE TEXAS", "BATS", "CBOE"]);
+const NYSE_EARLY_CLOSES = new Set([
+  "2025-07-03", "2025-11-28", "2025-12-24", "2026-11-27", "2026-12-24",
+  "2027-11-26", "2028-07-03", "2028-11-24",
+]);
+// Published full closures, not a holiday-rule engine. Early closes are sessions.
+const CLOSURES: Record<number, readonly string[]> = {
+  2025: ["01-01", "01-09", "01-20", "02-17", "04-18", "05-26", "06-19", "07-04", "09-01", "11-27", "12-25"],
+  2026: ["01-01", "01-19", "02-16", "04-03", "05-25", "06-19", "07-03", "09-07", "11-26", "12-25"],
+  2027: ["01-01", "01-18", "02-15", "03-26", "05-31", "06-18", "07-05", "09-06", "11-25", "12-24"],
+  2028: ["01-17", "02-21", "04-14", "05-29", "06-19", "07-04", "09-04", "11-23", "12-25"],
+};
+
+export const PUBLISHED_US_EQUITY_SESSION_BASIS = {
+  checkedAt: "2026-09-12",
+  nyse: {
+    years: [2025, 2026, 2027, 2028],
+    sources: [
+      "https://ir.theice.com/press/news-details/2024/NYSE-Group-Announces-2025-2026-and-2027-Holiday-and-Early-Closings-Calendar/default.aspx",
+      "https://www.nyse.com/trade/hours-calendars",
+      "https://www.cboe.com/about/hours/us-equities/",
+      "https://ir.theice.com/press/news-details/2024/The-New-York-Stock-Exchange-Will-Close-Markets-on-January-9-to-Honor-the-Passing-of-Former-President-Jimmy-Carter-on-National-Day-of-Mourning/default.aspx",
+    ],
+  },
+  // Nasdaq publishes the same full closures and 13:00 early closes as NYSE.
+  nasdaq: {
+    years: [2025, 2026, 2027, 2028],
+    sources: [
+      "https://www.nasdaq.com/docs/2025/01/06/2025holidayandtradinghours.pdf",
+      "https://www.nasdaqtrader.com/Trader.aspx?id=Calendar",
+      "https://www.nasdaqtrader.com/TraderNews.aspx?id=ETA2024-87",
+    ],
+  },
+  limitation: "Published schedules only; no live exceptional-closure feed or coverage for other venues/years.",
+  actualCloseCoverage: "NYSE venues and Nasdaq 2025 to 2028. Regular close 16:00 and listed early close 13:00 New York time.",
+} as const;
+
+/** Calendar-day coverage is broader than verified actual-close coverage. */
+export function getPublishedUsEquityCalendarYears(exchange: string): readonly number[] | null {
+  const venue = canonicalExchange(exchange);
+  return venue === "NASDAQ" ? PUBLISHED_US_EQUITY_SESSION_BASIS.nasdaq.years
+    : NYSE_VENUES.has(venue) ? PUBLISHED_US_EQUITY_SESSION_BASIS.nyse.years : null;
+}
+
+function calendarDate(value: string): Date | null {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return null;
+  const time = Date.parse(`${value}T00:00:00Z`);
+  return Number.isFinite(time) && new Date(time).toISOString().slice(0, 10) === value ? new Date(time) : null;
+}
+
+/** A covered trading date does not by itself establish that date's close time. */
+export function getPublishedUsEquityCalendarDay(exchange: string, date: string): "session" | "closed" | null {
+  const day = calendarDate(date);
+  if (!day || !getPublishedUsEquityCalendarYears(exchange)?.includes(day.getUTCFullYear())) return null;
+  const weekday = day.getUTCDay();
+  return weekday === 0 || weekday === 6 || CLOSURES[day.getUTCFullYear()]!.includes(date.slice(5)) ? "closed" : "session";
+}
+
+export type PublishedUsEquitySession = { kind: "session"; open: number; close: number } | { kind: "closed" };
+
+const sessionCache = new Map<string, PublishedUsEquitySession | null>();
+
+/** Published regular equity hours only; unknown venue/date/close coverage is null. */
+export function getPublishedUsEquitySession(exchange: string, date: string): PublishedUsEquitySession | null {
+  const venue = canonicalExchange(exchange);
+  const key = `${venue}:${date}`;
+  if (sessionCache.has(key)) return sessionCache.get(key)!;
+  const session = publishedSession(venue, date);
+  // The calendar is static, and callers look up the same few dates per bar.
+  if (sessionCache.size < 4096) sessionCache.set(key, session);
+  return session;
+}
+
+function publishedSession(venue: string, date: string): PublishedUsEquitySession | null {
+  const day = calendarDate(date);
+  if (!day) return null;
+  const kind = getPublishedUsEquityCalendarDay(venue, date);
+  if (!kind) return null;
+  if (kind === "closed") return Object.freeze({ kind });
+  const at = (hour: number, minute = 0) => zonedWallClockToUtcMs("America/New_York",
+    day.getUTCFullYear(), day.getUTCMonth() + 1, day.getUTCDate(), hour, minute, 0);
+  return Object.freeze({ kind, open: at(9, 30), close: at(NYSE_EARLY_CLOSES.has(date) ? 13 : 16) });
+}

package/src/market-data/query-store.ts

@@ -0,0 +1,95 @@
+import type { QueryEntry } from "./result-types";
+import { createIdleEntry } from "./result-types";
+
+/** How many entries a store keeps once nothing is watching them. */
+export interface QueryStoreRetention {
+  /**
+   * Entries to keep once nothing on screen is watching them, on top of the
+   * watched ones. Browsing a ticker adds an entry to every store its panes
+   * touch, and nothing used to remove one, so a session that researched a few
+   * hundred symbols held every price history, statement set and filing it had
+   * ever shown until exit (#452).
+   */
+  maxRetainedEntries?: number;
+  /** True while a mounted pane is subscribed to this key, so it must be kept. */
+  isWatched?: (key: string) => boolean;
+  /** Called for each evicted key, for anything derived from it and keyed alike. */
+  onEvict?: (key: string) => void;
+}
+
+export interface QueryStoreOptions<T> extends QueryStoreRetention {
+  /**
+   * Sees every entry before it is stored, so a store can overlay a newer
+   * source (a streamed FX rate over a loaded one) on whatever writes it.
+   */
+  project?: (key: string, entry: QueryEntry<T>) => QueryEntry<T>;
+}
+
+export class QueryStore<T> {
+  private readonly entries = new Map<string, QueryEntry<T>>();
+  /** Stored keys no pane is watching, least recently used first. */
+  private readonly unwatched = new Set<string>();
+
+  constructor(
+    private readonly onChange: (key: string) => void,
+    private readonly options: QueryStoreOptions<T> = {},
+  ) {}
+
+  get(key: string): QueryEntry<T> {
+    return this.entries.get(key) ?? createIdleEntry<T>();
+  }
+
+  set(key: string, entry: QueryEntry<T>): void {
+    this.store(key, entry);
+    this.onChange(key);
+  }
+
+  update(key: string, updater: (current: QueryEntry<T>) => QueryEntry<T>): QueryEntry<T> {
+    const next = this.store(key, updater(this.get(key)));
+    this.onChange(key);
+    return next;
+  }
+
+  /** A pane started watching `key`, so it is kept until released. */
+  watch(key: string): void {
+    this.unwatched.delete(key);
+  }
+
+  /** The last pane watching `key` let go: it is now the most recently used entry. */
+  release(key: string): void {
+    if (this.entries.has(key)) this.retain(key);
+  }
+
+  /** Entries held right now. */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  private store(key: string, entry: QueryEntry<T>): QueryEntry<T> {
+    const next = this.options.project ? this.options.project(key, entry) : entry;
+    this.entries.set(key, next);
+    this.retain(key);
+    return next;
+  }
+
+  /**
+   * Marks an unwatched key as the most recently used and drops the least
+   * recently used unwatched entries past the ceiling. A watched key is never
+   * evicted and does not count, so a pane cannot blank and a large portfolio
+   * still leaves room to go back to the tickers just browsed. An evicted key
+   * returns to idle and refetches the next time something asks for it.
+   */
+  private retain(key: string): void {
+    const limit = this.options.maxRetainedEntries;
+    if (limit === undefined) return;
+    this.unwatched.delete(key);
+    if (this.options.isWatched?.(key)) return;
+    this.unwatched.add(key);
+    for (const oldest of this.unwatched) {
+      if (this.unwatched.size <= limit) return;
+      this.unwatched.delete(oldest);
+      this.entries.delete(oldest);
+      this.options.onEvict?.(oldest);
+    }
+  }
+}

package/src/market-data/quote-subscription-target.ts

@@ -0,0 +1,79 @@
+export interface QuoteSubscriptionPriorityTarget {
+  route?: "auto" | "provider" | "broker";
+  surface?: "portfolio" | "watchlist" | "detail" | "monitor" | "inline" | "options" | "screener" | "unknown";
+  visible?: boolean;
+  selected?: boolean;
+  weight?: number;
+}
+
+function quoteSubscriptionPriorityScore(target: QuoteSubscriptionPriorityTarget): number {
+  let score = Number.isFinite(target.weight) ? Math.max(0, target.weight ?? 0) : 0;
+  if (target.selected) score += 10_000;
+  if (target.visible) score += 5_000;
+  if (target.surface === "detail" || target.surface === "monitor" || target.surface === "options") score += 4_000;
+  if (target.surface === "portfolio" || target.surface === "watchlist") score += 1_000;
+  if (target.surface === "screener") score += 700;
+  if (target.surface === "inline") score += 200;
+  return score;
+}
+
+const ROUTE_PRECEDENCE: Record<NonNullable<QuoteSubscriptionPriorityTarget["route"]>, number> = {
+  auto: 0,
+  provider: 1,
+  broker: 2,
+};
+
+/**
+ * Merges every pane's request for one instrument. Priority fields come from
+ * the most important request, but the route does not: a broker request wins
+ * whenever any pane makes it, and the router decides whether that broker can
+ * stream. A cursor or focus change therefore never moves an instrument
+ * between sources.
+ */
+export function mergeQuoteSubscriptionTargets<T extends QuoteSubscriptionPriorityTarget>(
+  targets: Iterable<T>,
+): T | null {
+  let selectedTarget: T | null = null;
+  let route: QuoteSubscriptionPriorityTarget["route"];
+  let selectedScore = -1;
+  let visible = false;
+  let selected = false;
+  let weight = 0;
+  let hasVisible = false;
+  let hasSelected = false;
+  let hasWeight = false;
+
+  for (const target of targets) {
+    const score = quoteSubscriptionPriorityScore(target);
+    if (!selectedTarget || score > selectedScore) {
+      selectedTarget = target;
+      selectedScore = score;
+    }
+    if (target.route && (!route || ROUTE_PRECEDENCE[target.route] > ROUTE_PRECEDENCE[route])) {
+      route = target.route;
+    }
+    if (target.visible !== undefined) {
+      hasVisible = true;
+      visible ||= target.visible;
+    }
+    if (target.selected !== undefined) {
+      hasSelected = true;
+      selected ||= target.selected;
+    }
+    if (Number.isFinite(target.weight)) {
+      hasWeight = true;
+      weight = Math.max(weight, Math.max(0, target.weight ?? 0));
+    }
+  }
+
+  if (!selectedTarget) return null;
+  const merged = { ...selectedTarget };
+  if (route) (merged as QuoteSubscriptionPriorityTarget).route = route;
+  if (hasVisible) merged.visible = visible;
+  else delete merged.visible;
+  if (hasSelected) merged.selected = selected;
+  else delete merged.selected;
+  if (hasWeight) merged.weight = weight;
+  else delete merged.weight;
+  return merged;
+}

package/src/market-data/quotes/clock.ts

@@ -0,0 +1,56 @@
+/**
+ * Quote timestamps are stamped by the exchange and the server; the freshness
+ * gates compare them with this machine's clock. A clock running a little
+ * behind would otherwise make every fresh tick look like it came from the
+ * future and drop it, so a bounded amount of future time is tolerated. The
+ * bound grows with the server offset measured from socket frames.
+ */
+const MIN_FUTURE_TOLERANCE_MS = 2_000;
+const OFFSET_MARGIN_MS = 1_000;
+// Far-future stamps are still malformed data, whatever the measured offset.
+const MAX_FUTURE_TOLERANCE_MS = 60 * 60_000;
+const OFFSET_SAMPLE_LIMIT = 32;
+
+const samples: number[] = [];
+let measuredOffsetMs: number | null = null;
+let forwardedOffsetMs: number | null = null;
+
+/**
+ * Records one server-stamped frame. Network delay can only make the sample
+ * smaller than the true offset, so the largest recent sample is the best
+ * estimate of how far the server clock runs ahead of this one.
+ */
+export function recordServerClockSample(serverTimeMs: unknown, receivedAtMs = Date.now()): void {
+  if (typeof serverTimeMs !== "number" || !Number.isFinite(serverTimeMs) || serverTimeMs <= 0) return;
+  if (!Number.isFinite(receivedAtMs)) return;
+  samples.push(serverTimeMs - receivedAtMs);
+  if (samples.length > OFFSET_SAMPLE_LIMIT) samples.shift();
+  let max = Number.NEGATIVE_INFINITY;
+  for (const sample of samples) max = Math.max(max, sample);
+  measuredOffsetMs = max;
+}
+
+/** An offset measured by another process on this machine (the desktop backend owns the socket). */
+export function setForwardedServerClockOffset(offsetMs: unknown): void {
+  forwardedOffsetMs = typeof offsetMs === "number" && Number.isFinite(offsetMs) ? offsetMs : null;
+}
+
+/** Server clock minus local clock in ms, or null before any server-stamped frame. */
+export function getServerClockOffsetMs(): number | null {
+  if (measuredOffsetMs == null) return forwardedOffsetMs;
+  if (forwardedOffsetMs == null) return measuredOffsetMs;
+  return Math.max(measuredOffsetMs, forwardedOffsetMs);
+}
+
+/** How far ahead of local time a quote timestamp may be and still count as observed. */
+export function quoteFutureToleranceMs(): number {
+  const offset = getServerClockOffsetMs();
+  const tolerance = offset == null ? MIN_FUTURE_TOLERANCE_MS : Math.max(MIN_FUTURE_TOLERANCE_MS, offset + OFFSET_MARGIN_MS);
+  return Math.min(tolerance, MAX_FUTURE_TOLERANCE_MS);
+}
+
+export function resetServerClockForTests(): void {
+  samples.length = 0;
+  measuredOffsetMs = null;
+  forwardedOffsetMs = null;
+}