gloomberb 0.10.2 → 0.10.4

package/src/plugins/builtin/options/live-quotes.ts

@@ -7,14 +7,11 @@ import type { OptionTableRow } from "./types";
 export const OPTIONS_QUOTE_EXCHANGE = "OPTIONS";
 export const OPTIONS_CHAIN_REFRESH_INTERVAL_MS = 10 * 60_000;
 export const OPTIONS_STREAM_FRESHNESS_MS = 2 * 60_000;
+export const OPTIONS_STREAM_CONNECTING_GRACE_MS = 15_000;
 
-const OPTIONS_STREAM_MAX_TARGETS = 16;
-const OPTIONS_STREAM_MAX_ROWS = OPTIONS_STREAM_MAX_TARGETS / 2;
 const OPTIONS_STREAM_OVERSCAN_ROWS = 4;
 
 export interface OptionsQuoteFreshness {
-  chainAsOf?: string;
-  chainDataSource?: "live" | "delayed";
   now: number;
   subscriptionStartedAt: number;
 }
@@ -23,35 +20,64 @@ function isFiniteNumber(value: number | undefined): value is number {
   return typeof value === "number" && Number.isFinite(value);
 }
 
-function optionStreamRowCount(height: number): number {
-  const visibleRows = Math.max(1, Math.floor(height) - 3);
-  return Math.min(
-    OPTIONS_STREAM_MAX_ROWS,
-    visibleRows + OPTIONS_STREAM_OVERSCAN_ROWS,
-  );
+export interface OptionQuoteTargetWindow {
+  fallbackHeight: number;
+  selectedIndex: number;
+  visibleRange: { start: number; end: number } | null;
+}
+
+export type OptionQuoteCoverageStatus = "live" | "mixed" | "connecting" | "delayed";
+
+export interface OptionQuoteCoverage {
+  fallbackCount: number;
+  liveCount: number;
+  status: OptionQuoteCoverageStatus;
+  totalCount: number;
 }
 
-function optionStreamWindow(totalRows: number, selectedIndex: number, height: number): [number, number] {
-  const count = Math.min(totalRows, optionStreamRowCount(height));
+function fallbackVisibleRange(
+  totalRows: number,
+  selectedIndex: number,
+  height: number,
+): { start: number; end: number } {
+  const count = Math.min(totalRows, Math.max(1, Math.floor(height) - 3));
   const clampedIndex = Math.max(0, Math.min(selectedIndex, Math.max(0, totalRows - 1)));
   const start = Math.max(0, Math.min(clampedIndex - Math.floor(count / 2), totalRows - count));
-  return [start, start + count];
+  return { start, end: start + count };
+}
+
+function normalizeVisibleRange(
+  totalRows: number,
+  window: OptionQuoteTargetWindow,
+): { start: number; end: number } {
+  if (!window.visibleRange) {
+    return fallbackVisibleRange(totalRows, window.selectedIndex, window.fallbackHeight);
+  }
+  const start = Math.max(0, Math.min(totalRows, Math.floor(window.visibleRange.start)));
+  const end = Math.max(start, Math.min(totalRows, Math.ceil(window.visibleRange.end)));
+  return { start, end };
 }
 
 export function buildOptionQuoteTargets(
   rows: readonly OptionTableRow[],
-  selectedIndex: number,
-  height: number,
+  window: OptionQuoteTargetWindow,
 ): QuoteSubscriptionTarget[] {
   if (rows.length === 0) return [];
-  const [start, end] = optionStreamWindow(rows.length, selectedIndex, height);
+  const visibleRange = normalizeVisibleRange(rows.length, window);
+  const start = Math.max(0, visibleRange.start - OPTIONS_STREAM_OVERSCAN_ROWS);
+  const end = Math.min(rows.length, visibleRange.end + OPTIONS_STREAM_OVERSCAN_ROWS);
   const targets = new Map<string, QuoteSubscriptionTarget>();
 
-  for (let index = start; index < end; index += 1) {
+  const addRow = (index: number) => {
     const row = rows[index];
-    if (!row) continue;
-    const selected = index === selectedIndex;
-    const distance = Math.abs(index - selectedIndex);
+    if (!row) return;
+    const selected = index === window.selectedIndex;
+    const visible = index >= visibleRange.start && index < visibleRange.end;
+    const distance = visible
+      ? 0
+      : index < visibleRange.start
+        ? visibleRange.start - index
+        : index - visibleRange.end + 1;
     for (const contract of [row.call, row.put]) {
       const symbol = contract?.contractSymbol.trim().toUpperCase();
       if (!symbol) continue;
@@ -59,11 +85,18 @@ export function buildOptionQuoteTargets(
         symbol,
         exchange: OPTIONS_QUOTE_EXCHANGE,
         surface: "options",
-        visible: true,
+        visible,
         selected,
-        weight: Math.max(50, 100 - distance),
+        weight: selected ? 100 : visible ? 80 : Math.max(50, 70 - distance),
       });
     }
+  };
+
+  for (let index = start; index < end; index += 1) {
+    addRow(index);
+  }
+  if (window.selectedIndex < start || window.selectedIndex >= end) {
+    addRow(window.selectedIndex);
   }
 
   return [...targets.values()];
@@ -99,21 +132,11 @@ function freshOptionQuote(entry: QueryEntry<Quote> | undefined, freshness: Optio
   const receivedAt = quote.receivedAt ?? 0;
   if (
     !Number.isFinite(receivedAt) ||
-    receivedAt <= freshness.subscriptionStartedAt ||
+    receivedAt < freshness.subscriptionStartedAt ||
     freshness.now - receivedAt > OPTIONS_STREAM_FRESHNESS_MS
   ) {
     return null;
   }
-  const chainAsOf = freshness.chainAsOf ? Date.parse(freshness.chainAsOf) : Number.NaN;
-  if (
-    freshness.chainDataSource === "live" &&
-    quote.dataSource === "live" &&
-    Number.isFinite(chainAsOf) &&
-    Number.isFinite(quote.lastUpdated) &&
-    quote.lastUpdated < chainAsOf
-  ) {
-    return null;
-  }
   return quote;
 }
 
@@ -135,13 +158,44 @@ export function overlayOptionRowQuotes(
   }));
 }
 
-export function hasLiveOptionQuote(
+export function resolveOptionQuoteCoverage(
+  targets: readonly QuoteSubscriptionTarget[],
   quoteEntries: ReadonlyMap<string, QueryEntry<Quote>>,
   freshness: OptionsQuoteFreshness,
-): boolean {
-  for (const entry of quoteEntries.values()) {
-    const quote = freshOptionQuote(entry, freshness);
-    if (quote?.dataSource === "live" && quote.delivery === "stream") return true;
+): OptionQuoteCoverage {
+  const visibleSymbols = new Set(
+    targets
+      .filter((target) => target.visible === true)
+      .map((target) => target.symbol.trim().toUpperCase())
+      .filter(Boolean),
+  );
+  let liveCount = 0;
+  let fallbackCount = 0;
+  for (const symbol of visibleSymbols) {
+    const quote = freshOptionQuote(
+      quoteEntries.get(buildOptionQuoteKey(symbol)),
+      freshness,
+    );
+    if (
+      quote?.dataSource === "live"
+      && quote.delivery === "stream"
+      && quote.stale === false
+    ) {
+      liveCount += 1;
+    } else if (quote) {
+      fallbackCount += 1;
+    }
   }
-  return false;
+
+  const totalCount = visibleSymbols.size;
+  const status: OptionQuoteCoverageStatus = totalCount > 0 && liveCount === totalCount
+    ? "live"
+    : liveCount > 0
+      ? "mixed"
+      : fallbackCount === 0
+        && totalCount > 0
+        && freshness.now - freshness.subscriptionStartedAt < OPTIONS_STREAM_CONNECTING_GRACE_MS
+        ? "connecting"
+        : "delayed";
+  return { fallbackCount, liveCount, status, totalCount };
 }

package/src/plugins/builtin/options/view.test.tsx

@@ -164,7 +164,7 @@ test("defaults the table around the nearest strike to the current quote", async
   expect(frame).not.toContain(" 50 ");
 });
 
-test("streams a bounded options window and overlays live contract quotes", async () => {
+test("streams every visible option row and overlays live contract quotes", async () => {
   const strikes = Array.from({ length: 100 }, (_, index) => 50 + index);
   const subscriptions: QuoteSubscriptionTarget[][] = [];
   let emitQuote:
@@ -193,8 +193,9 @@ test("streams a bounded options window and overlays live contract quotes", async
   await renderSettled();
 
   const targets = subscriptions.at(-1) ?? [];
-  expect(targets.length).toBeGreaterThan(0);
+  expect(targets.length).toBeGreaterThan(16);
   expect(targets.length).toBeLessThanOrEqual(80);
+  expect(targets.filter((target) => target.visible === true).length).toBeGreaterThan(16);
   expect(
     targets.every(
       (target) => target.exchange === "OPTIONS" && target.surface === "options",
@@ -218,6 +219,8 @@ test("streams a bounded options window and overlays live contract quotes", async
       changePercent: 0,
       lastUpdated: Date.now(),
       dataSource: "live",
+      delivery: "stream",
+      stale: false,
     });
     await Promise.resolve();
     await testSetup!.renderOnce();

package/src/plugins/builtin/options/view.tsx

@@ -5,7 +5,13 @@ import { colors } from "../../../theme/colors";
 import { isPlainKey } from "../../../utils/keyboard";
 import { formatExpDate, resolveOptionsTarget } from "../../../utils/options";
 import { useOptionsQuery, useResolvedEntryValue } from "../../../market-data/hooks";
-import { DataTableView, Spinner, Tabs, type DataTableKeyEvent } from "../../../components";
+import {
+  DataTableView,
+  Spinner,
+  Tabs,
+  type DataTableKeyEvent,
+  type DataTableVisibleRange,
+} from "../../../components";
 import { useShortcut } from "../../../react/input";
 import { useLiveQuoteEntries } from "../../../state/hooks/quote-streaming";
 import {
@@ -19,18 +25,24 @@ import {
 import type { OptionColumn, OptionTableRow, OptionsViewProps } from "./types";
 import {
   buildOptionQuoteTargets,
-  hasLiveOptionQuote,
   OPTIONS_CHAIN_REFRESH_INTERVAL_MS,
   overlayOptionRowQuotes,
+  resolveOptionQuoteCoverage,
 } from "./live-quotes";
 import { useOptionsAccessFooter } from "./footer";
+import { useLiveStreamingSetting } from "../shared/live-streaming";
 
 export function OptionsView({ width, height, focused, onCapture = () => {} }: OptionsViewProps) {
   const { ticker, financials } = usePaneTicker();
+  const liveStreaming = useLiveStreamingSetting();
   const [expIdx, setExpIdx] = useState(0);
   const [strikeIdx, setStrikeIdx] = useState(0);
   const [autoScrollVersion, setAutoScrollVersion] = useState(0);
   const [scrollToIndexAlign, setScrollToIndexAlign] = useState<"nearest" | "center">("nearest");
+  const [visibleStrikeViewport, setVisibleStrikeViewport] = useState<{
+    key: string;
+    range: DataTableVisibleRange;
+  } | null>(null);
   const [interactive, setInteractive] = useState(false);
   const userSelectedStrikeRef = useRef(false);
   const onCaptureRef = useRef(onCapture);
@@ -54,6 +66,7 @@ export function OptionsView({ width, height, focused, onCapture = () => {} }: Op
   const initialChainEntry = useOptionsQuery(baseRequest);
   const initialChain = useResolvedEntryValue(initialChainEntry);
   const selectedExpiration = initialChain?.expirationDates[expIdx];
+  const viewportKey = `${effectiveTicker}:${selectedExpiration ?? "initial"}`;
   const expirationChainEntry = useOptionsQuery(
     baseRequest && selectedExpiration != null
       ? { ...baseRequest, expirationDate: selectedExpiration }
@@ -131,28 +144,53 @@ export function OptionsView({ width, height, focused, onCapture = () => {} }: Op
     put: putsByStrike.get(strike),
     isPositionStrike: !!parsed && Math.abs(strike - parsed.strike) < 0.01,
   })), [callsByStrike, parsed, putsByStrike, strikes]);
+  const visibleStrikeRange = visibleStrikeViewport?.key === viewportKey
+    ? visibleStrikeViewport.range
+    : null;
+  const handleVisibleStrikeRangeChange = useCallback((range: DataTableVisibleRange) => {
+    setVisibleStrikeViewport((current) => (
+      current?.key === viewportKey
+      && current.range.start === range.start
+      && current.range.end === range.end
+        ? current
+        : { key: viewportKey, range }
+    ));
+  }, [viewportKey]);
   const optionQuoteTargets = useMemo(
-    () => buildOptionQuoteTargets(snapshotRows, strikeIdx, height),
-    [height, snapshotRows, strikeIdx],
+    () => buildOptionQuoteTargets(snapshotRows, {
+      fallbackHeight: height,
+      selectedIndex: strikeIdx,
+      visibleRange: visibleStrikeRange,
+    }),
+    [height, snapshotRows, strikeIdx, visibleStrikeRange],
   );
   const {
     entries: optionQuoteEntries,
     freshnessNow,
     subscriptionStartedAt,
-  } = useLiveQuoteEntries(optionQuoteTargets);
+  } = useLiveQuoteEntries(optionQuoteTargets, {
+    freshnessScopeKey: viewportKey,
+    liveStreaming,
+  });
   const optionQuoteFreshness = useMemo(
     () => ({
-      chainAsOf: chain?.asOf,
-      chainDataSource: chain?.dataSource,
       now: freshnessNow,
       subscriptionStartedAt,
     }),
-    [chain?.asOf, chain?.dataSource, freshnessNow, subscriptionStartedAt],
+    [freshnessNow, subscriptionStartedAt],
   );
   const rows = useMemo(
     () => overlayOptionRowQuotes(snapshotRows, optionQuoteEntries, optionQuoteFreshness),
     [optionQuoteEntries, optionQuoteFreshness, snapshotRows],
   );
+  const optionQuoteCoverage = useMemo(
+    () => resolveOptionQuoteCoverage(
+      optionQuoteTargets,
+      optionQuoteEntries,
+      optionQuoteFreshness,
+    ),
+    [optionQuoteEntries, optionQuoteFreshness, optionQuoteTargets],
+  );
   const optionColumns: OptionColumn[] = OPTION_COLUMNS.map((column) => ({
     ...column,
     headerColor: optionColumnColor(column.id, colors.panel),
@@ -162,8 +200,8 @@ export function OptionsView({ width, height, focused, onCapture = () => {} }: Op
     chain,
     error,
     focused,
-    hasLiveQuote: hasLiveOptionQuote(optionQuoteEntries, optionQuoteFreshness),
     loading,
+    quoteCoverage: optionQuoteCoverage,
   });
 
   useEffect(() => {
@@ -333,6 +371,8 @@ export function OptionsView({ width, height, focused, onCapture = () => {} }: Op
         sortDirection="asc"
         onHeaderClick={() => {}}
         onTableMouseDown={enterInteractive}
+        visibleRangeKey={viewportKey}
+        onVisibleRangeChange={handleVisibleStrikeRangeChange}
         getItemKey={(row) => String(row.strike)}
         renderCell={renderOptionCell}
         emptyStateTitle="No strikes available."

package/src/plugins/builtin/portfolio-list/index.tsx

@@ -9,6 +9,10 @@ import {
 } from "./settings";
 import { portfolioCliCommand } from "./cli/portfolio-command";
 import { watchlistCliCommand } from "./cli/watchlist-command";
+import {
+  LIVE_STREAMING_QUICK_SETTING,
+  withLiveStreamingSetting,
+} from "../shared/live-streaming";
 
 export { shouldToggleCashMarginDrawer };
 
@@ -43,10 +47,14 @@ export const portfolioListModule: PluginModule = {
       defaultPosition: "left",
       defaultMode: "floating",
       defaultWidth: "40%",
-      settings: (context) => buildPortfolioPaneSettingsDef(
-        context.config,
-        getPortfolioPaneSettings(context.settings),
-        context.activeCollectionId,
+      quickSettings: [LIVE_STREAMING_QUICK_SETTING],
+      settings: (context) => withLiveStreamingSetting(
+        buildPortfolioPaneSettingsDef(
+          context.config,
+          getPortfolioPaneSettings(context.settings),
+          context.activeCollectionId,
+        ),
+        context.settings,
       ),
     },
   ],

package/src/plugins/builtin/portfolio-list/pane/index.tsx

@@ -51,6 +51,8 @@ import {
 } from "./data";
 import { usePortfolioPaneStreaming } from "./streaming";
 import { usePortfolioSupplementalData } from "./supplemental";
+import { useLiveStreamingSetting } from "../../shared/live-streaming";
+import { useThrottledTickerOrder } from "../use-throttled-ticker-order";
 
 export function PortfolioListPane({ focused, width, height }: PaneProps) {
   const { pinTicker } = usePluginTickerActions();
@@ -63,6 +65,7 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
   const brokerAccounts = useAppSelector((state) => state.brokerAccounts);
   const refreshingSize = useAppSelector((state) => state.refreshing.size);
   const paneCollection = usePaneCollection();
+  const liveStreaming = useLiveStreamingSetting();
 
   const [currentCollectionId, setCurrentCollectionId] = usePaneStateValue<string>("collectionId", paneCollection.collectionId ?? "");
   const [committedCursorSymbol, setCommittedCursorSymbol] = usePaneStateValue<string | null>("cursorSymbol", null);
@@ -169,10 +172,27 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
   ]);
 
   const activeSort = resolveCollectionSortPreference(activeCollectionId, isPortfolioTab, collectionSorts);
-  const sortedTickers = useMemo(
+  const candidateSortedTickers = useMemo(
     () => sortTickers(tickers, financialsMap, activeSort, columnContext, columns),
     [tickers, financialsMap, activeSort, columnContext, columns],
   );
+  const candidateSymbols = useMemo(
+    () => candidateSortedTickers.map((ticker) => ticker.metadata.ticker),
+    [candidateSortedTickers],
+  );
+  const orderResetKey = `${activeCollectionId}|${activeSort.columnId ?? ""}|${activeSort.direction}`;
+  const orderedSymbols = useThrottledTickerOrder(candidateSymbols, orderResetKey);
+  const tickerBySymbol = useMemo(
+    () => new Map(candidateSortedTickers.map((ticker) => [ticker.metadata.ticker, ticker])),
+    [candidateSortedTickers],
+  );
+  const sortedTickers = useMemo(
+    () => orderedSymbols.flatMap((symbol) => {
+      const ticker = tickerBySymbol.get(symbol);
+      return ticker ? [ticker] : [];
+    }),
+    [orderedSymbols, tickerBySymbol],
+  );
 
   const selectedIdx = sortedTickers.findIndex((ticker) => ticker.metadata.ticker === cursorSymbol);
   const safeSelectedIdx = selectedIdx >= 0 ? selectedIdx : 0;
@@ -322,6 +342,7 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
     activeSort,
     financialsMap,
     visibleWarmupRequirements,
+    liveStreaming,
   });
 
   const summaryFooterInfo = useMemo(() => buildPortfolioFooterSegments({

package/src/plugins/builtin/portfolio-list/pane/streaming.ts

@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useRef } from "react";
 import { getSharedMarketDataCoordinator } from "../../../../market-data/coordinator";
 import { instrumentFromTicker, quoteSubscriptionTargetFromTicker } from "../../../../market-data/request-types";
-import { useQuoteStreaming } from "../../../../state/hooks/quote-streaming";
+import { useQuoteUpdates } from "../../../../state/hooks/quote-streaming";
 import type { TickerFinancials } from "../../../../types/financials";
 import type { TickerRecord } from "../../../../types/ticker";
 import type { CollectionSortPreference } from "../../../../state/app/context";
@@ -32,6 +32,7 @@ export function usePortfolioPaneStreaming({
   activeSort,
   financialsMap,
   visibleWarmupRequirements,
+  liveStreaming,
 }: {
   appActive: boolean;
   activeCollectionId?: string;
@@ -42,6 +43,7 @@ export function usePortfolioPaneStreaming({
   activeSort: CollectionSortPreference;
   financialsMap: Map<string, TickerFinancials>;
   visibleWarmupRequirements: VisibleWarmupRequirements;
+  liveStreaming: boolean;
 }) {
   const sharedCoordinator = getSharedMarketDataCoordinator();
   const mountedRef = useRef(true);
@@ -110,14 +112,16 @@ export function usePortfolioPaneStreaming({
     const quoteSnapshotQueue: TickerRecord[] = [];
     const snapshotQueue: TickerRecord[] = [];
     const snapshotQueueSymbols = new Set<string>();
-    const useSnapshotForQuoteWarmup = sortPreferenceUsesQuote(activeSort);
-    const quoteWarmupTickers = selectQuoteWarmupTickers(
-      sortedTickers,
-      streamWindow,
-      financialsMap,
-      activeSort,
-      nowTimestamp,
-    );
+    const useSnapshotForQuoteWarmup = liveStreaming && sortPreferenceUsesQuote(activeSort);
+    const quoteWarmupTickers = liveStreaming
+      ? selectQuoteWarmupTickers(
+        sortedTickers,
+        streamWindow,
+        financialsMap,
+        activeSort,
+        nowTimestamp,
+      )
+      : [];
     for (const ticker of quoteWarmupTickers) {
       const financials = financialsMap.get(ticker.metadata.ticker);
       const quoteKey = visibleWarmupKey("quote", ticker);
@@ -210,10 +214,10 @@ export function usePortfolioPaneStreaming({
       cancelled = true;
       clearTimeout(timeoutId);
     };
-  }, [activeSort, appActive, financialsMap, instrumentOptions, sharedCoordinator, sortedTickers, streamWindow, visibleFinancialTickers, visibleWarmupRequirements]);
+  }, [activeSort, appActive, financialsMap, instrumentOptions, liveStreaming, sharedCoordinator, sortedTickers, streamWindow, visibleFinancialTickers, visibleWarmupRequirements]);
 
   useEffect(() => {
-    if (!appActive) return;
+    if (!liveStreaming || !appActive) return;
     if (!sharedCoordinator) return;
 
     let cancelled = false;
@@ -262,7 +266,7 @@ export function usePortfolioPaneStreaming({
       cancelled = true;
       clearInterval(intervalId);
     };
-  }, [appActive, sharedCoordinator]);
+  }, [appActive, liveStreaming, sharedCoordinator]);
 
-  useQuoteStreaming(streamTargets);
+  useQuoteUpdates(streamTargets, { liveStreaming });
 }

package/src/plugins/builtin/portfolio-list/use-throttled-ticker-order.test.tsx

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { act, useState } from "react";
+import { testRender } from "../../../renderers/opentui/test-utils";
+import { useThrottledTickerOrder } from "./use-throttled-ticker-order";
+
+const TEST_THROTTLE_MS = 80;
+let testSetup: Awaited<ReturnType<typeof testRender>> | undefined;
+let updateCandidates: ((symbols: string[]) => void) | null = null;
+let updateResetKey: ((key: string) => void) | null = null;
+let latestOrder: string[] = [];
+
+function ThrottledOrderHarness() {
+  const [candidates, setCandidates] = useState(["AAPL", "MSFT", "NVDA"]);
+  const [resetKey, setResetKey] = useState("price:desc");
+  latestOrder = useThrottledTickerOrder(candidates, resetKey, TEST_THROTTLE_MS);
+  updateCandidates = setCandidates;
+  updateResetKey = setResetKey;
+  return <text>{latestOrder.join(",")}</text>;
+}
+
+afterEach(async () => {
+  if (testSetup) {
+    await act(async () => testSetup!.renderer.destroy());
+    testSetup = undefined;
+  }
+  updateCandidates = null;
+  updateResetKey = null;
+  latestOrder = [];
+});
+
+describe("useThrottledTickerOrder", () => {
+  test("coalesces rapid market-driven reorders into the latest trailing order", async () => {
+    testSetup = await testRender(<ThrottledOrderHarness />, { width: 32, height: 1 });
+    await act(async () => testSetup!.renderOnce());
+
+    await act(async () => {
+      updateCandidates?.(["MSFT", "AAPL", "NVDA"]);
+      await Promise.resolve();
+    });
+    await act(async () => testSetup!.renderOnce());
+    expect(latestOrder).toEqual(["MSFT", "AAPL", "NVDA"]);
+
+    await act(async () => {
+      updateCandidates?.(["NVDA", "MSFT", "AAPL"]);
+      await Promise.resolve();
+    });
+    await act(async () => testSetup!.renderOnce());
+    expect(latestOrder).toEqual(["MSFT", "AAPL", "NVDA"]);
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, TEST_THROTTLE_MS + 20));
+    });
+    await act(async () => testSetup!.renderOnce());
+    expect(latestOrder).toEqual(["NVDA", "MSFT", "AAPL"]);
+  });
+
+  test("applies user sort changes and ticker membership changes immediately", async () => {
+    testSetup = await testRender(<ThrottledOrderHarness />, { width: 32, height: 1 });
+    await act(async () => testSetup!.renderOnce());
+
+    await act(async () => {
+      updateCandidates?.(["NVDA", "MSFT", "AAPL"]);
+      updateResetKey?.("price:asc");
+      await Promise.resolve();
+    });
+    await act(async () => testSetup!.renderOnce());
+    expect(latestOrder).toEqual(["NVDA", "MSFT", "AAPL"]);
+
+    await act(async () => {
+      updateCandidates?.(["AMD", "NVDA", "MSFT", "AAPL"]);
+      await Promise.resolve();
+    });
+    await act(async () => testSetup!.renderOnce());
+    expect(latestOrder).toEqual(["AMD", "NVDA", "MSFT", "AAPL"]);
+  });
+});

package/src/plugins/builtin/portfolio-list/use-throttled-ticker-order.ts

@@ -0,0 +1,78 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+
+export const PORTFOLIO_REORDER_THROTTLE_MS = 5_000;
+
+function hasSameOrder(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((symbol, index) => symbol === right[index]);
+}
+
+function hasSameMembership(left: readonly string[], right: readonly string[]): boolean {
+  if (left.length !== right.length) return false;
+  const symbols = new Set(left);
+  return right.every((symbol) => symbols.has(symbol));
+}
+
+export function useThrottledTickerOrder(
+  candidateSymbols: string[],
+  resetKey: string,
+  throttleMs = PORTFOLIO_REORDER_THROTTLE_MS,
+): string[] {
+  const [committedSymbols, setCommittedSymbols] = useState(candidateSymbols);
+  const committedRef = useRef(candidateSymbols);
+  const latestCandidateRef = useRef(candidateSymbols);
+  const resetKeyRef = useRef(resetKey);
+  const lastCommitAtRef = useRef(0);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const candidateKey = JSON.stringify(candidateSymbols);
+
+  useEffect(() => {
+    latestCandidateRef.current = candidateSymbols;
+    const current = committedRef.current;
+    const resetChanged = resetKeyRef.current !== resetKey;
+    const membershipChanged = !hasSameMembership(current, candidateSymbols);
+    resetKeyRef.current = resetKey;
+
+    const commit = (nextSymbols: string[]) => {
+      committedRef.current = nextSymbols;
+      lastCommitAtRef.current = Date.now();
+      setCommittedSymbols(nextSymbols);
+    };
+
+    if (resetChanged || membershipChanged) {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = null;
+      if (!hasSameOrder(current, candidateSymbols)) commit(candidateSymbols);
+      return;
+    }
+    if (hasSameOrder(current, candidateSymbols)) return;
+
+    const elapsed = Date.now() - lastCommitAtRef.current;
+    const remaining = Math.max(0, throttleMs - elapsed);
+    if (remaining === 0) {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = null;
+      commit(candidateSymbols);
+      return;
+    }
+    if (timerRef.current) return;
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null;
+      const latest = latestCandidateRef.current;
+      if (!hasSameOrder(committedRef.current, latest)) commit(latest);
+    }, remaining);
+  }, [candidateKey, resetKey, throttleMs]);
+
+  useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
+
+  return useMemo(() => {
+    const currentSymbols = new Set(candidateSymbols);
+    const ordered = committedSymbols.filter((symbol) => currentSymbols.has(symbol));
+    const orderedSet = new Set(ordered);
+    for (const symbol of candidateSymbols) {
+      if (!orderedSet.has(symbol)) ordered.push(symbol);
+    }
+    return ordered;
+  }, [candidateKey, committedSymbols]);
+}