gloomberb 0.16.0 → 0.16.2

package/src/plugins/builtin/market-heatmap/model.ts

@@ -0,0 +1,146 @@
+import type { MarketHeatmapAsset } from "../../../api-client/market-discovery";
+
+/**
+ * The board's grouping and move arithmetic, shared by the pane and the `fn HM`
+ * report so a sector reads the same in both. Isomorphic: no React or renderer.
+ */
+
+type HeatmapMoveAsset = Pick<MarketHeatmapAsset, "symbol" | "hasChange" | "changePercent" | "size" | "sector" | "industry"> & {
+  /** Treemap area, when it is not `size` itself. */
+  weight?: number;
+};
+
+/**
+ * The move, or null when there is none: no change data is not a flat session.
+ * A name without the last session's close still has the move of the open
+ * pre-market or after-hours session it streams (`extendedSession`).
+ */
+export function heatmapMove(asset: Pick<MarketHeatmapAsset, "hasChange" | "changePercent"> & { extendedSession?: string }): number | null {
+  return (asset.hasChange || asset.extendedSession != null) && typeof asset.changePercent === "number" && Number.isFinite(asset.changePercent)
+    ? asset.changePercent
+    : null;
+}
+
+export type HeatmapGrouping = "sector-industry" | "sector" | "flat";
+
+/**
+ * Sector and industry blocks when the board knows its sectors. A board where
+ * most of the value has none (ETFs, or a snapshot whose classification
+ * failed) lays out flat rather than as one big unlabeled block.
+ */
+export function resolveHeatmapGrouping(assets: readonly HeatmapMoveAsset[], industries: boolean): HeatmapGrouping {
+  let total = 0;
+  let classified = 0;
+  const sectors = new Set<string>();
+  for (const asset of assets) {
+    const weight = asset.weight ?? asset.size ?? 0;
+    total += weight;
+    if (asset.sector) {
+      classified += weight;
+      sectors.add(asset.sector);
+    }
+  }
+  if (sectors.size < 2 || classified < total / 2) return "flat";
+  return industries ? "sector-industry" : "sector";
+}
+
+/**
+ * The move of a set of names weighted by their size (market cap, an ETF's net
+ * assets, a position's value), over the names that have both. Null when none do.
+ */
+export function sizeWeightedMove(assets: readonly HeatmapMoveAsset[]): number | null {
+  let weight = 0;
+  let weightedMove = 0;
+  for (const asset of assets) {
+    const change = heatmapMove(asset);
+    const size = asset.size ?? 0;
+    if (change == null || !(size > 0)) continue;
+    weight += size;
+    weightedMove += change * size;
+  }
+  return weight > 0 ? weightedMove / weight : null;
+}
+
+export type HeatmapGroupBy = "sector" | "industry";
+
+export interface HeatmapGroupSummary {
+  /** The sector or industry; null for names the snapshot does not classify, or every name on a flat board. */
+  group: string | null;
+  /** The industry's sector, when grouping by industry. */
+  sector: string | null;
+  names: number;
+  /** Total size: market cap, or net assets on the ETF board. */
+  size: number;
+  /** This group's share of the board's total size. */
+  share: number;
+  move: number | null;
+  /** Names with a move, and the size they carry; the rest have no change data yet. */
+  moved: number;
+  up: number;
+  down: number;
+  unchanged: number;
+  best: { symbol: string; move: number } | null;
+  worst: { symbol: string; move: number } | null;
+}
+
+function summarize(group: string | null, sector: string | null, assets: readonly HeatmapMoveAsset[], boardSize: number): HeatmapGroupSummary {
+  let up = 0;
+  let down = 0;
+  let unchanged = 0;
+  let size = 0;
+  let best: HeatmapGroupSummary["best"] = null;
+  let worst: HeatmapGroupSummary["worst"] = null;
+  for (const asset of assets) {
+    size += asset.size ?? 0;
+    const move = heatmapMove(asset);
+    if (move == null) continue;
+    if (move > 0) up += 1;
+    else if (move < 0) down += 1;
+    else unchanged += 1;
+    if (!best || move > best.move) best = { symbol: asset.symbol, move };
+    if (!worst || move < worst.move) worst = { symbol: asset.symbol, move };
+  }
+  return {
+    group,
+    sector,
+    names: assets.length,
+    size,
+    share: boardSize > 0 ? size / boardSize : 0,
+    move: sizeWeightedMove(assets),
+    moved: up + down + unchanged,
+    up,
+    down,
+    unchanged,
+    best,
+    worst,
+  };
+}
+
+/**
+ * One summary per sector or industry, largest first as the board lays them
+ * out. A flat board (ETFs) is one group of every name. Unclassified names form
+ * their own group last.
+ */
+export function summarizeHeatmapGroups(
+  assets: readonly HeatmapMoveAsset[],
+  groupBy: HeatmapGroupBy,
+): { grouping: HeatmapGrouping; groups: HeatmapGroupSummary[]; board: HeatmapGroupSummary } {
+  const grouping = resolveHeatmapGrouping(assets, groupBy === "industry");
+  const boardSize = assets.reduce((sum, asset) => sum + (asset.size ?? 0), 0);
+  const board = summarize(null, null, assets, boardSize);
+  if (grouping === "flat") return { grouping, groups: [board], board };
+  const buckets = new Map<string, { group: string | null; sector: string | null; assets: HeatmapMoveAsset[] }>();
+  for (const asset of assets) {
+    const sector = asset.sector ?? null;
+    const group = sector == null ? null : grouping === "sector-industry" ? asset.industry ?? null : sector;
+    const key = `${sector ?? ""}\u0000${group ?? ""}`;
+    const bucket = buckets.get(key) ?? { group, sector, assets: [] };
+    bucket.assets.push(asset);
+    buckets.set(key, bucket);
+  }
+  const groups = [...buckets.values()]
+    .map((bucket) => summarize(bucket.group, grouping === "sector-industry" ? bucket.sector : null, bucket.assets, boardSize))
+    .sort((left, right) => Number(left.sector == null && left.group == null) - Number(right.sector == null && right.group == null)
+      || right.size - left.size);
+  return { grouping, groups, board };
+}

package/src/plugins/builtin/market-heatmap/portfolio.ts

@@ -3,10 +3,28 @@ import type { MarketHeatmapAsset, MarketHeatmapUniverseId } from "../../../api-c
 import { useAppSelector, usePaneStateValue } from "../../../state/app/context";
 import type { ColumnConfig } from "../../../types/config";
 import type { TickerFinancials } from "../../../types/financials";
+import { getSessionMoveDisplay, type ExtendedSession } from "../../../market-data/market/status";
 import type { TickerRecord } from "../../../types/ticker";
 import { getSortValue, type ColumnContext } from "../portfolio-list/metrics";
 
 export const PORTFOLIO_HEATMAP_TAB = "portfolio";
+
+/**
+ * How a market board's tile area follows size. The square root, the default,
+ * gives mid-size names room next to the largest; groups still sum their
+ * tiles, so a sector's block stays the sum of its transformed names.
+ * Portfolio holdings always take their position value as it is.
+ */
+export type HeatmapSizeBy = "market-cap" | "sqrt-market-cap";
+
+/** A saved choice wins; a pane that never chose gets the square root. */
+export function heatmapSizeBy(value: unknown): HeatmapSizeBy {
+  return value === "market-cap" ? "market-cap" : "sqrt-market-cap";
+}
+
+export function heatmapSizeWeight(size: number, sizeBy: HeatmapSizeBy): number {
+  return sizeBy === "sqrt-market-cap" ? Math.sqrt(size) : size;
+}
 const MAX_PORTFOLIO_TILES = 160;
 
 export type HeatmapTabId = MarketHeatmapUniverseId | typeof PORTFOLIO_HEATMAP_TAB;
@@ -19,6 +37,8 @@ export interface HeatmapBoardAsset extends MarketHeatmapAsset {
   sizeCurrency?: string;
   /** Treemap area, when it is not `size` itself. */
   weight?: number;
+  /** The price and move are this open pre-market or after-hours session's, from the regular close. */
+  extendedSession?: ExtendedSession;
 }
 
 export interface HeatmapPortfolioPane {
@@ -31,6 +51,19 @@ export function heatmapTabId(value: string | null | undefined): HeatmapTabId {
   return "us-equity";
 }
 
+/** Pane state where the pane says which kind of list its portfolio tab shows, for the header to read. */
+export const HEATMAP_COLLECTION_KIND_STATE_KEY = "collectionKind";
+
+/**
+ * Whether Size by changes the board: the market boards and a watchlist, never
+ * a portfolio, whose holdings are always sized by position value. Until the
+ * pane has said which list its tab shows, the control stays away.
+ */
+export function heatmapSizeByApplies(universe: unknown, collectionKind: unknown): boolean {
+  return heatmapTabId(typeof universe === "string" ? universe : null) !== PORTFOLIO_HEATMAP_TAB
+    || collectionKind === "watchlist";
+}
+
 export function isRemoteHeatmapUniverse(value: HeatmapTabId): value is MarketHeatmapUniverseId {
   return value !== PORTFOLIO_HEATMAP_TAB;
 }
@@ -147,11 +180,12 @@ function positiveNumber(value: number | string | null): number | null {
 /**
  * A portfolio's holdings are sized by market value, read as the portfolio pane
  * reads its MKT VALUE column: lots, contract multipliers and price basis, in
- * the portfolio's currency. A watchlist's names are sized by the square root
- * of market cap in the base currency, so a mega-cap does not hide the rest of
- * a short list. A name with no size (no position, no quote, no cap, no FX
- * rate) gets the smallest tile and no caption. Past `MAX_PORTFOLIO_TILES`,
- * the smallest names are left out and counted in `omitted`.
+ * the portfolio's currency, which a holder reads linearly whatever `sizeBy`
+ * says. A watchlist's names are sized by market cap in the base currency, by
+ * default its square root (`sizeBy`). A name with no
+ * size (no position, no quote, no cap, no FX rate) gets the smallest tile and
+ * no caption. Past `MAX_PORTFOLIO_TILES`, the smallest names are left out and
+ * counted in `omitted`.
  */
 export function buildPortfolioHeatmapAssets({
   tickers,
@@ -160,6 +194,7 @@ export function buildPortfolioHeatmapAssets({
   kind,
   currency,
   exchangeRates,
+  sizeBy = "sqrt-market-cap",
 }: {
   tickers: readonly TickerRecord[];
   financials: ReadonlyMap<string, TickerFinancials>;
@@ -168,6 +203,7 @@ export function buildPortfolioHeatmapAssets({
   /** The portfolio's totals currency, or the base currency for a watchlist. */
   currency: string;
   exchangeRates: Map<string, number>;
+  sizeBy?: HeatmapSizeBy;
 }): { assets: HeatmapBoardAsset[]; omitted: number } {
   const context: ColumnContext = {
     activeTab: kind === "portfolio" ? collectionId : undefined,
@@ -180,18 +216,21 @@ export function buildPortfolioHeatmapAssets({
     const symbol = ticker.metadata.ticker;
     const snapshot = financials.get(symbol);
     const quote = snapshot?.quote;
-    const price = quote != null && Number.isFinite(quote.price) ? quote.price : null;
+    // Colored like the market boards: an open extended session's move, else the regular session's.
+    const display = getSessionMoveDisplay(quote);
+    const price = display != null && Number.isFinite(display.price) ? display.price : null;
     const size = positiveNumber(getSortValue(sizeColumn, ticker, snapshot, context));
-    const hasChange = quote != null && Number.isFinite(quote.changePercent);
+    const hasChange = display?.changePercent != null && Number.isFinite(display.changePercent);
     return {
       symbol,
       name: quote?.name?.trim() || ticker.metadata.name || symbol,
       price: price ?? 0,
-      change: quote != null && Number.isFinite(quote.change) ? quote.change : 0,
-      changePercent: hasChange ? quote.changePercent : 0,
+      change: display?.change != null && Number.isFinite(display.change) ? display.change : 0,
+      changePercent: hasChange ? display.changePercent! : 0,
       hasChange,
+      ...(display?.session ? { extendedSession: display.session } : {}),
       size,
-      weight: size == null ? undefined : kind === "portfolio" ? size : Math.sqrt(size),
+      weight: size == null ? undefined : kind === "portfolio" ? size : heatmapSizeWeight(size, sizeBy),
       sizeKind: "market-cap",
       sizeCaption: kind === "portfolio" ? "Value" : undefined,
       sizeCurrency: currency,
@@ -212,7 +251,7 @@ export function buildPortfolioHeatmapAssets({
   const kept = measured.slice(0, MAX_PORTFOLIO_TILES);
   const sizes = kept.flatMap((asset) => (asset.size != null ? [asset.size] : []));
   const floor = sizes.length > 0 ? Math.min(...sizes) : 1;
-  const floorWeight = kind === "portfolio" ? floor : Math.sqrt(floor);
+  const floorWeight = kind === "portfolio" ? floor : heatmapSizeWeight(floor, sizeBy);
   return {
     assets: kept.map((asset) => (asset.size != null ? asset : { ...asset, weight: floorWeight })),
     omitted: measured.length - kept.length,

package/src/plugins/builtin/market-movers/client.ts

@@ -10,6 +10,7 @@ import {
   fetchPreferredMarketMovers,
   fetchTrending,
   type MarketMoversResult,
+  type PreferredMoversOptions,
   type ScreenerQuote,
   type TrendingSymbol,
 } from "./screener";
@@ -22,7 +23,7 @@ export interface MarketMoverTabDependencies {
   fetchPreferred(
     category: "day_gainers" | "day_losers" | "most_actives",
     count: number,
-    options?: { forceRefresh?: boolean },
+    options?: PreferredMoversOptions,
   ): Promise<MarketMoversResult>;
   fetchTrending(count: number, options?: { forceRefresh?: boolean }): Promise<TrendingSymbol[]>;
 }
@@ -65,7 +66,7 @@ async function hydrateTrending(
 export async function loadMarketMoverTab(
   tab: ScreenerTabId,
   provider: DataProvider | null,
-  options?: { forceRefresh?: boolean },
+  options?: Pick<PreferredMoversOptions, "forceRefresh" | "metadataWaitMs">,
   dependencies: MarketMoverTabDependencies = defaultDependencies,
 ): Promise<MarketMoverTabResult> {
   if (tab === "trending") {

package/src/plugins/builtin/market-movers/headless.ts

@@ -64,8 +64,15 @@ export interface MarketMoversHeadlessDependencies {
   ): Promise<CloudSessionMoversPayload>;
 }
 
+/**
+ * Headless reads, including VIEW sources, wait for average volumes rather
+ * than returning a partial first paint. Keep that wait bounded by the usual
+ * market request timeout; interactive MOST retains its shorter cutoff.
+ */
+const ONE_SHOT_METADATA_WAIT_MS = 10_000;
+
 const defaultDependencies: MarketMoversHeadlessDependencies = {
-  load: (_args, tab, provider) => loadMarketMoverTab(tab, provider),
+  load: (_args, tab, provider) => loadMarketMoverTab(tab, provider, { metadataWaitMs: ONE_SHOT_METADATA_WAIT_MS }),
   loadSession: (view, side) => loadSessionMovers(view, side),
 };
 
@@ -74,6 +81,8 @@ export function createMarketMoversHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    // A screener snapshot, not a real-time feed; rows keep the time of their own last price.
+    freshness: { status: "delayed" },
     argument: { kind: "none" },
     options: [{
       key: "list",

package/src/plugins/builtin/market-movers/screener.ts

@@ -18,6 +18,7 @@ const CACHE_POLICY = {
   staleMs: 5 * 60 * 1000,
   expireMs: 60 * 60 * 1000,
 } as const;
+/** A pane shows the live ranking first; the backend's average volumes follow if they are quick. */
 const MARKET_METADATA_WAIT_MS = 1_500;
 
 export interface MarketScreenerApi {
@@ -30,6 +31,14 @@ export interface FetchCacheOptions {
   forceRefresh?: boolean;
 }
 
+export interface PreferredMoversOptions extends FetchCacheOptions {
+  /**
+   * How long a Cloud list waits for the backend's average volumes and market
+   * caps, which it borrows by symbol: without them every row has no ratio.
+   */
+  metadataWaitMs?: number;
+}
+
 let marketMoversPersistence: PluginPersistence | null = null;
 const activeFetches = new Map<string, Promise<unknown>>();
 const failedFetches = new Set<string>();
@@ -243,6 +252,8 @@ function mergeCloudScreenerItem(
   metadata?: ScreenerQuote,
 ): ScreenerQuote {
   const currency = typeof item.currency === "string" ? item.currency.trim() : "";
+  const directAverage = screenerNumber(item.avgVolume);
+  const avgVolume = directAverage != null && directAverage > 0 ? directAverage : metadata?.avgVolume ?? null;
   const metadataPrice = (value: number | undefined) => convertScreenerPriceUnit(value, metadata?.currency ?? "", currency);
   return {
     symbol: item.symbol,
@@ -253,8 +264,8 @@ function mergeCloudScreenerItem(
     change: screenerNumber(item.change),
     changePercent: screenerNumber(item.changePercent),
     volume: screenerVolume(item.volume),
-    avgVolume: metadata?.avgVolume ?? null,
-    volumeRatio: screenerVolumeRatio(screenerVolume(item.volume), metadata?.avgVolume ?? null),
+    avgVolume,
+    volumeRatio: screenerVolumeRatio(screenerVolume(item.volume), avgVolume),
     marketCap: metadata?.marketCap,
     currency,
     fiftyTwoWeekHigh: screenerNumber(item.high52w) ?? metadataPrice(metadata?.fiftyTwoWeekHigh),
@@ -268,13 +279,14 @@ function mergeCloudScreenerItem(
 
 async function bestEffortMarketMetadata(
   request: Promise<CachedResult<ScreenerQuote[]>>,
+  waitMs: number,
 ): Promise<ScreenerQuote[]> {
   let timeout: ReturnType<typeof setTimeout> | undefined;
   try {
     return await Promise.race([
       request.then((result) => result.data).catch(() => []),
       new Promise<ScreenerQuote[]>((resolve) => {
-        timeout = setTimeout(() => resolve([]), MARKET_METADATA_WAIT_MS);
+        timeout = setTimeout(() => resolve([]), waitMs);
       }),
     ]);
   } finally {
@@ -303,9 +315,10 @@ export function rankScreenerQuotes(category: ScreenerCategory, quotes: ScreenerQ
 export async function fetchPreferredMarketMovers(
   category: ScreenerCategory,
   count = 25,
-  options?: FetchCacheOptions,
+  preferredOptions?: PreferredMoversOptions,
   sources: PreferredMarketMoverSources = defaultPreferredMarketMoverSources,
 ): Promise<MarketMoversResult> {
+  const { metadataWaitMs = MARKET_METADATA_WAIT_MS, ...options } = preferredOptions ?? {};
   if (!sources.isCloudEligible()) {
     const result = await sources.fetchMarket(category, count, options);
     return { quotes: rankScreenerQuotes(category, result.data), source: "gloom", stale: result.stale };
@@ -327,7 +340,7 @@ export async function fetchPreferredMarketMovers(
       && response.data
       && response.data.items.length > 0
     ) {
-      const metadata = await bestEffortMarketMetadata(marketMetadata);
+      const metadata = await bestEffortMarketMetadata(marketMetadata, metadataWaitMs);
       const metadataBySymbol = new Map(metadata.map((quote) => [quote.symbol, quote]));
       return {
         quotes: rankScreenerQuotes(category, response.data.items.map((item) => (

package/src/plugins/builtin/market-valuation/headless.ts

@@ -120,6 +120,8 @@ function projectValuationHeadlessBundle(
 
 export const marketValuationHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  // Each indicator row checks its own release schedule and says when it is stale.
+  freshness: { status: "not-a-feed", basis: "published statistics" },
   argument: {
     kind: "free-text",
     placeholder: "indicator",

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

@@ -0,0 +1,53 @@
+import { apiClient } from "../../../api-client";
+import { ApiRequestError } from "../../../api-client/errors";
+import type { FundMembersPayload, FundChangesPayload, MemberFundsPayload } from "../../../api-client/members";
+import { createPluginCache } from "../../../data/plugin-cache";
+import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
+import { coveredFund, notCoveredMessage } from "./model";
+const policy = { staleMs: 60_000, expireMs: 2 * 60 * 60_000 };
+export const fundListCache = createPluginCache<MemberFundsPayload>({ kind: "member-funds", source: "gloom-cloud", schemaVersion: 1, policy });
+export const fundMembersCache = createPluginCache<FundMembersPayload>({ kind: "fund-members", source: "gloom-cloud", schemaVersion: 1, policy });
+export const fundChangesCache = createPluginCache<FundChangesPayload>({ kind: "fund-changes", source: "gloom-cloud", schemaVersion: 1, policy });
+type Client = Pick<typeof apiClient, "getMemberFunds" | "getFundMembers" | "getFundChanges">;
+const number = (value: unknown) => value === null || typeof value === "number" && Number.isFinite(value);
+function validateMembers(data: FundMembersPayload) {
+  if (!data?.fund?.ticker || !Number.isFinite(Date.parse(data.asOf)) || !Array.isArray(data.members)
+    || !data.members.every((row) => typeof row.id === "string" && typeof row.name === "string" && [row.weight, row.price, row.changePercent, row.return1WPercent, row.return1MPercent, row.returnYtdPercent, row.contribution].every(number))
+    || !data.aggregate || !number(data.aggregate.sum)) throw new Error("Unreadable fund holdings response");
+  return data;
+}
+function validateChanges(data: FundChangesPayload) {
+  if (!data?.fund?.ticker || !Array.isArray(data.changes) || !data.changes.every((row) => typeof row.id === "string" && typeof row.reason === "string" && Array.isArray(row.estimates))) throw new Error("Unreadable fund changes response");
+  return data;
+}
+function validateFunds(data: MemberFundsPayload) {
+  if (!data || !Array.isArray(data.funds) || !data.funds.every((fund) => typeof fund.ticker === "string" && typeof fund.name === "string")) throw new Error("Unreadable covered funds response");
+  return data;
+}
+const UNAVAILABLE = "Fund members are not available on this server yet.";
+async function fetchPayload<T>(fetcher: () => Promise<T>, validate: (data: T) => T) {
+  try { return validate(await fetcher()); } catch (error) { throw unavailableOnServer(error, UNAVAILABLE); }
+}
+/**
+ * A 404 for one fund means either an uncovered fund or a server without the route, and the two read the
+ * same. The covered list tells them apart: a fund missing from a readable list is not covered; a list
+ * that cannot be read, or that holds the fund, leaves the server-side message.
+ */
+async function fetchFundPayload<T>(fund: string, fetcher: () => Promise<T>, validate: (data: T) => T, client: Client) {
+  try { return validate(await fetcher()); } catch (error) {
+    if (error instanceof ApiRequestError && error.status === 404) {
+      const funds = await fetchFunds(client).then((payload) => payload.funds, () => []);
+      if (funds.length && !coveredFund(funds, fund)) throw new Error(notCoveredMessage(fund, funds));
+    }
+    throw unavailableOnServer(error, UNAVAILABLE);
+  }
+}
+export const fetchFunds = (client: Client = apiClient) => fetchPayload(() => client.getMemberFunds(), validateFunds);
+export const fetchMembers = (fund: string, client: Client = apiClient) => fetchFundPayload(fund, () => client.getFundMembers(fund), validateMembers, client);
+export const fetchChanges = (fund: string, client: Client = apiClient) => fetchFundPayload(fund, () => client.getFundChanges(fund), validateChanges, client);
+export const cachedFunds = () => cachedCloudResource(fundListCache, "list", validateFunds);
+export const loadFunds = (force = false) => loadCloudResource(fundListCache, "list", () => fetchFunds(), { force, validate: validateFunds });
+export const cachedMembers = (fund: string) => cachedCloudResource(fundMembersCache, fund, validateMembers);
+export const loadMembers = (fund: string, force = false) => loadCloudResource(fundMembersCache, fund, () => fetchMembers(fund), { force, validate: validateMembers });
+export const cachedChanges = (fund: string) => cachedCloudResource(fundChangesCache, fund, validateChanges);
+export const loadChanges = (fund: string, force = false) => loadCloudResource(fundChangesCache, fund, () => fetchChanges(fund), { force, validate: validateChanges });

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

@@ -0,0 +1,35 @@
+import type { HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/plugin";
+import { fetchChanges, fetchFunds, fetchMembers } from "./client";
+import { canonicalFund, changeReason, decimal, DEFAULT_SORT, memberRows, percent } from "./model";
+const columns: HeadlessPaneColumn[] = [
+  { key: "symbol", header: "Ticker" }, { key: "name", header: "Name" },
+  { key: "weight", header: "Weight %", align: "right", format: (value) => value == null ? "--" : decimal(Number(value) * 100) },
+  { key: "shares", header: "Shares", align: "right", format: (value) => decimal(value as number | null, 0) },
+  { key: "price", header: "Price $", align: "right", format: (value) => decimal(value as number | null) },
+  ...["changePercent", "return1WPercent", "return1MPercent", "returnYtdPercent"].map((key, i) => ({ key, header: ["1D", "1W", "1M", "YTD"][i]!, align: "right" as const, format: (value: unknown) => percent(value as number | null) })),
+];
+export const membersHeadless: HeadlessPaneDefinition<"rows"> = {
+  shape: "rows", argument: { kind: "ticker", optional: true, placeholder: "fund", description: "Covered fund or index alias; omit for the fund list." },
+  options: [{ key: "tab", type: "enum", values: [{ value: "members" }, { value: "movers" }, { value: "changes" }], defaultValue: "members", description: "Members, movers or changes." }],
+  discovery: { aliases: ["MEMB", "MRR", "IMOV"], limitations: ["ETF holdings, with file dates", "Partial delayed member return coverage", "Nasdaq-100 is not covered"] },
+  describe: (args) => args.rawArgument ? `MEMB ${args.rawArgument}` : "Index and ETF members",
+  async load(args, context) {
+    const input = args.symbols[0] ?? args.rawArgument ?? "";
+    if (!input) return { freshness: { status: "not-a-feed", basis: "fund holdings files" }, rows: (await fetchFunds(context.apiClient)).funds.map((fund) => ({ ...fund })), columns: [{ key: "ticker", header: "Fund" }, { key: "name", header: "Index" }, { key: "asOf", header: "Holdings as of" }] };
+    const fund = canonicalFund(input);
+    if (args.options.tab === "changes") {
+      const data = await fetchChanges(fund, context.apiClient);
+      return { freshness: { status: "not-a-feed", basis: "index changes" }, rows: data.changes.map((row) => ({ ...row, reason: changeReason(row) })), columns: [{ key: "effectiveDate", header: "Effective" }, { key: "added", header: "Added" }, { key: "removed", header: "Removed" }, { key: "daysToGo", header: "In days", align: "right" }, { key: "reason", header: "Reason" }],
+        complete: data.available && !data.stale, metadata: { ...data, changes: undefined } };
+    }
+    const data = await fetchMembers(fund, context.apiClient);
+    const movers = args.options.tab === "movers";
+    const rows = memberRows(data.members, movers ? "movers" : "members", "", DEFAULT_SORT).flatMap((row) => row.kind === "item" ? [{ ...row.item }] : []);
+    // Member prices are the pane's 15-minute delayed quotes. As in the pane, the fund's snapshot says
+    // whether it is stale; the members' own flags are not what the pane reads.
+    return { freshness: { status: data.stale ? "stale" : "delayed", delayMinutes: 15, ignoreStaleFlags: true }, rows, columns: movers ? [...columns.slice(0, 3), { key: "contribution", header: "Contrib. pp", align: "right", format: (value) => percent(value as number | null, "", 3) }] : columns,
+      complete: !data.stale && data.aggregate.fresh1D === data.aggregate.total,
+      unavailableSymbols: data.members.flatMap((row) => row.symbol && row.changePercent === null ? [row.symbol] : []),
+      metadata: { fund: data.fund, asOf: data.asOf, snapshotAsOf: data.snapshotAsOf, aggregate: data.aggregate, stale: data.stale } };
+  },
+};

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

@@ -0,0 +1,20 @@
+import type { GloomPlugin } from "../../../types/plugin";
+import { fundChangesCache, fundListCache, fundMembersCache } from "./client";
+import { membersHeadless } from "./headless";
+import { MembersPane } from "./pane";
+import { membersTitle } from "./model";
+export const membersPlugin: GloomPlugin = {
+  id: "members", name: "Index and ETF members", version: "1.0.0", description: "ETF holdings, member returns, contributions and index changes", toggleable: true,
+  setup(ctx) { fundListCache.attach(ctx.persistence); fundMembersCache.attach(ctx.persistence); fundChangesCache.attach(ctx.persistence); },
+  dispose() { fundListCache.reset(); fundMembersCache.reset(); fundChangesCache.reset(); },
+  panes: [{ id: "members", name: "Index and ETF members", icon: "M", component: MembersPane, tickerFollower: true,
+    defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 132, height: 32 }, tableExport: true,
+    settings: { fields: [{ key: "tab", label: "View", type: "select", options: [{ value: "members", label: "Members" }, { value: "movers", label: "Movers" }, { value: "changes", label: "Changes" }] }] } }],
+  paneTemplates: [{ id: "members-pane", paneId: "members", label: "Index and ETF members", description: "ETF holdings, member returns, daily contributions and index changes.",
+    keywords: ["members", "index", "ETF", "holdings", "weights", "rebalance", "MRR", "IMOV"],
+    shortcut: { prefix: "MEMB", argKind: "ticker", argPlaceholder: "fund", argOptional: true, openWithoutArg: true }, headless: membersHeadless,
+    createInstance: (_context, options) => { const symbol = (options?.arg ?? options?.symbol)?.trim().toUpperCase();
+      return { placement: "floating", title: membersTitle(symbol ?? ""),
+        ...(symbol ? { binding: { kind: "fixed", symbol } } : {}), settings: { tab: options?.values?.tab ?? "members" } }; },
+  }],
+};

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

@@ -0,0 +1,68 @@
+import type { FundChange, FundMember, MemberFundsPayload } from "../../../api-client/members";
+import type { DataTableColumn } from "../../../components";
+import { buildSectionedRows, type SectionedRow } from "../../../components/data-table/sections";
+import { getTableWidth } from "../../../components/ui/table-layout";
+import { compareSortValues, type SortPreference } from "../../../utils/sort-values";
+export type MembersTab = "members" | "movers" | "changes";
+export const TABS = [{ value: "members", label: "Members" }, { value: "movers", label: "Movers" }, { value: "changes", label: "Changes" }];
+export const isTab = (value: unknown): value is MembersTab => TABS.some((tab) => tab.value === value);
+const COVERED = [{ ticker: "IVV", name: "S&P 500" }, { ticker: "IJH", name: "S&P 400" }, { ticker: "IJR", name: "S&P 600" }, { ticker: "IWM", name: "Russell 2000" }, { ticker: "IWB", name: "Russell 1000" }];
+export function canonicalFund(input: string) { const symbol = input.split(":")[0]!.trim().toUpperCase(); return ["SPX", "SPY", "^GSPC"].includes(symbol) ? "IVV" : symbol; }
+/** The covered fund the user asked for, by ticker or by an alias such as SPX, or undefined when it is not covered. */
+export function coveredFund(funds: MemberFundsPayload["funds"], input: string) {
+  const symbol = canonicalFund(input);
+  return funds.find((fund) => fund.ticker === symbol || fund.aliases.some((alias) => alias.toUpperCase() === symbol));
+}
+export function notCoveredMessage(input: string, funds: MemberFundsPayload["funds"]) {
+  return `${input.split(":")[0]!.trim().toUpperCase()} is not a covered fund. Covered: ${funds.map((fund) => fund.ticker).join(", ")}.`;
+}
+export function membersTitle(input: string) {
+  const requested = input.split(":")[0]!.trim().toUpperCase();
+  const fund = canonicalFund(requested);
+  const definition = COVERED.find((item) => item.ticker === fund);
+  return definition ? `${definition.name}, ${fund} holdings${requested !== fund ? ` (${requested})` : ""}`
+    : requested ? `MEMB ${requested}` : "Index and ETF members";
+}
+export const DEFAULT_SORT: SortPreference<string> = { columnId: "weight", direction: "desc" };
+export const percent = (value: number | null, suffix = "%", digits = 2) => value == null || !Number.isFinite(value) ? "--" : `${value > 0 ? "+" : ""}${value.toFixed(digits)}${suffix}`;
+export const decimal = (value: number | null, digits = 2) => value == null || !Number.isFinite(value) ? "--" : value.toLocaleString("en-US", { minimumFractionDigits: digits, maximumFractionDigits: digits });
+export function sortMembers(rows: readonly FundMember[], sort: SortPreference<string>) {
+  return [...rows].sort((a, b) => compareSortValues(a[sort.columnId as keyof FundMember] as number | string | null,
+    b[sort.columnId as keyof FundMember] as number | string | null, sort.direction) || a.id.localeCompare(b.id));
+}
+export function memberRows(rows: readonly FundMember[], tab: MembersTab, query: string, sort: SortPreference<string>): SectionedRow<FundMember>[] {
+  const needle = query.trim().toLowerCase();
+  const filtered = rows.filter((row) => `${row.symbol ?? ""} ${row.name} ${row.sector ?? ""}`.toLowerCase().includes(needle));
+  if (tab !== "movers") return sortMembers(filtered, sort).map((item) => ({ kind: "item", key: item.id, item }));
+  const ranked = sortMembers(filtered.filter((row) => row.contribution !== null), { columnId: "contribution", direction: "desc" });
+  return buildSectionedRows([
+    { label: "Contributors", items: ranked.filter((row) => row.contribution! > 0).slice(0, 10) },
+    { label: "Detractors", items: ranked.filter((row) => row.contribution! < 0).reverse().slice(0, 10) },
+  ], (row) => row.id);
+}
+const column = (id: string, label: string, width: number, align: "left" | "right" = "right"): DataTableColumn => ({ id, label, width, align });
+function fit(columns: DataTableColumn[], width: number, drops: string[]) {
+  for (const id of drops) { if (getTableWidth(columns) <= width) break; columns = columns.filter((col) => col.id !== id); }
+  const flexible = columns.find((col) => col.id === "name" || col.id === "reason") ?? columns[0]!;
+  flexible.width = Math.max(6, flexible.width + Math.max(0, width - getTableWidth(columns)));
+  flexible.flexGrow = 1;
+  return columns;
+}
+export function memberColumns(width: number, movers = false): DataTableColumn[] {
+  const compact = width < 50;
+  return fit([column("symbol", "Ticker", 8, "left"), column("name", "Name", 22, "left"),
+    column("weight", compact ? "Wt. %" : "Weight %", compact ? 7 : 10), ...(movers ? [column("contribution", compact ? "pp" : "Contrib. pp", compact ? 7 : 13)] : []),
+    ...(!movers ? [column("shares", "Shares", 14), column("price", "Price $", 11)] : []),
+    column("changePercent", "1D", compact ? 8 : 9), ...(!movers ? [column("return1WPercent", "1W", 9), column("return1MPercent", "1M", 9), column("returnYtdPercent", "YTD", 9), column("sector", "Sector", 22, "left")] : [])], width,
+    ["sector", "shares", "returnYtdPercent", "return1MPercent", "return1WPercent", "price", "name"]);
+}
+export function changeColumns(width: number) {
+  const compact = width < 50;
+  return fit([column("effectiveDate", compact ? "Date" : "Effective", compact ? 10 : 12, "left"), column("daysToGo", compact ? "In" : "In days", compact ? 4 : 9), column("added", "Added", compact ? 7 : 8, "left"), column("removed", "Removed", 9, "left"), column("estimate", "Est. ADV days", 15), column("reason", "Reason", 28, "left")], width, ["estimate", "reason"]);
+}
+export const changeLabel = (row: FundChange) => row.added && row.removed ? `${row.added} replaces ${row.removed}`
+  : row.added ? `${row.added} added` : row.removed ? `${row.removed} removed` : "Index announcement";
+export function changeReason(row: FundChange) {
+  if (row.kind !== "announcement" || row.reason !== row.headline || !row.added && !row.removed) return row.reason;
+  return row.added && row.removed ? "Index replacement" : row.added ? "Index addition" : "Index deletion";
+}