gloomberb 0.3.7 → 0.4.0

package/src/plugins/builtin/portfolio-list/mutations.ts

@@ -0,0 +1,226 @@
+import type { AppConfig } from "../../../types/config";
+import type { Portfolio, TickerPosition, TickerRecord } from "../../../types/ticker";
+import { slugifyName } from "../../../utils/slugify";
+
+export interface DeleteManualPortfolioResult {
+  config: AppConfig;
+  portfolio: Portfolio;
+  tickers: TickerRecord[];
+  cleanedTickerCount: number;
+  removedPositionCount: number;
+}
+
+export interface RemoveTickerFromPortfolioResult {
+  changed: boolean;
+  ticker: TickerRecord;
+  removedPositionCount: number;
+}
+
+export interface SetManualPortfolioPositionInput {
+  shares: number;
+  avgCost: number;
+  currency: string;
+}
+
+export interface SetManualPortfolioPositionResult {
+  ticker: TickerRecord;
+  addedMembership: boolean;
+  replacedPositionCount: number;
+}
+
+function clonePortfolio(portfolio: Portfolio): Portfolio {
+  return { ...portfolio };
+}
+
+function normalizePortfolioName(rawName: string): string {
+  return rawName.trim().toLowerCase();
+}
+
+function replaceTickerMetadata(ticker: TickerRecord, metadata: TickerRecord["metadata"]): TickerRecord {
+  return {
+    ...ticker,
+    metadata,
+  };
+}
+
+export function isManualPortfolio(portfolio: Portfolio): boolean {
+  return !portfolio.brokerId && !portfolio.brokerInstanceId;
+}
+
+export function findPortfolio(config: AppConfig, rawName: string): Portfolio | null {
+  const normalized = normalizePortfolioName(rawName);
+  if (!normalized) return null;
+  return config.portfolios.find((portfolio) =>
+    portfolio.id.toLowerCase() === normalized || portfolio.name.toLowerCase() === normalized
+  ) ?? null;
+}
+
+export function getManualPortfolioPosition(ticker: TickerRecord, portfolioId: string): TickerPosition | null {
+  return ticker.metadata.positions.find((position) =>
+    position.portfolio === portfolioId && position.broker === "manual"
+  ) ?? null;
+}
+
+export function resolveManualPositionCurrency(
+  rawCurrency: string | undefined,
+  ticker: TickerRecord,
+  portfolio: Portfolio,
+  baseCurrency: string | undefined,
+): string {
+  return (rawCurrency?.trim() || ticker.metadata.currency || portfolio.currency || baseCurrency || "USD").toUpperCase();
+}
+
+export function createManualPortfolio(
+  config: AppConfig,
+  name: string,
+  baseCurrency: string,
+): { config: AppConfig; portfolio: Portfolio } {
+  const trimmedName = name.trim();
+  if (!trimmedName) {
+    throw new Error("Portfolio name is required.");
+  }
+
+  const id = slugifyName(trimmedName, "portfolio");
+  const normalizedName = trimmedName.toLowerCase();
+  const duplicate = config.portfolios.some((portfolio) =>
+    portfolio.id.toLowerCase() === id || portfolio.name.toLowerCase() === normalizedName
+  );
+  if (duplicate) {
+    throw new Error(`Portfolio "${trimmedName}" already exists.`);
+  }
+
+  const portfolio: Portfolio = {
+    id,
+    name: trimmedName,
+    currency: (baseCurrency || config.baseCurrency || "USD").toUpperCase(),
+  };
+
+  return {
+    config: {
+      ...config,
+      portfolios: [...config.portfolios, portfolio],
+    },
+    portfolio,
+  };
+}
+
+export function addTickerToPortfolio(
+  ticker: TickerRecord,
+  portfolioId: string,
+): { changed: boolean; ticker: TickerRecord } {
+  if (ticker.metadata.portfolios.includes(portfolioId)) {
+    return { changed: false, ticker };
+  }
+
+  return {
+    changed: true,
+    ticker: replaceTickerMetadata(ticker, {
+      ...ticker.metadata,
+      portfolios: [...ticker.metadata.portfolios, portfolioId],
+    }),
+  };
+}
+
+export function removeTickerFromPortfolio(
+  ticker: TickerRecord,
+  portfolioId: string,
+): RemoveTickerFromPortfolioResult {
+  const nextPortfolios = ticker.metadata.portfolios.filter((entry) => entry !== portfolioId);
+  const removedPositionCount = ticker.metadata.positions.filter((position) => position.portfolio === portfolioId).length;
+  const nextPositions = ticker.metadata.positions.filter((position) => position.portfolio !== portfolioId);
+  const changed =
+    nextPortfolios.length !== ticker.metadata.portfolios.length
+    || removedPositionCount > 0;
+
+  if (!changed) {
+    return { changed: false, ticker, removedPositionCount: 0 };
+  }
+
+  return {
+    changed: true,
+    removedPositionCount,
+    ticker: replaceTickerMetadata(ticker, {
+      ...ticker.metadata,
+      portfolios: nextPortfolios,
+      positions: nextPositions,
+    }),
+  };
+}
+
+export function setManualPortfolioPosition(
+  ticker: TickerRecord,
+  portfolioId: string,
+  input: SetManualPortfolioPositionInput,
+): SetManualPortfolioPositionResult {
+  const nextCurrency = input.currency.trim().toUpperCase();
+  if (!Number.isFinite(input.shares) || input.shares <= 0) {
+    throw new Error("Shares must be greater than 0.");
+  }
+  if (!Number.isFinite(input.avgCost)) {
+    throw new Error("Average cost must be a valid number.");
+  }
+  if (!nextCurrency) {
+    throw new Error("Position currency is required.");
+  }
+
+  const replacedPositionCount = ticker.metadata.positions.filter((position) => position.portfolio === portfolioId).length;
+  const nextPositions = ticker.metadata.positions.filter((position) => position.portfolio !== portfolioId);
+  const addedMembership = !ticker.metadata.portfolios.includes(portfolioId);
+
+  nextPositions.push({
+    portfolio: portfolioId,
+    shares: input.shares,
+    avgCost: input.avgCost,
+    currency: nextCurrency,
+    broker: "manual",
+  });
+
+  return {
+    addedMembership,
+    replacedPositionCount,
+    ticker: replaceTickerMetadata(ticker, {
+      ...ticker.metadata,
+      portfolios: addedMembership ? [...ticker.metadata.portfolios, portfolioId] : ticker.metadata.portfolios,
+      positions: nextPositions,
+    }),
+  };
+}
+
+export function deleteManualPortfolio(
+  config: AppConfig,
+  tickers: TickerRecord[],
+  portfolioId: string,
+): DeleteManualPortfolioResult {
+  const portfolio = config.portfolios.find((entry) => entry.id === portfolioId);
+  if (!portfolio) {
+    throw new Error("Portfolio not found.");
+  }
+  if (!isManualPortfolio(portfolio)) {
+    throw new Error(`Portfolio "${portfolio.name}" is broker-managed and cannot be modified manually.`);
+  }
+
+  const nextConfig: AppConfig = {
+    ...config,
+    portfolios: config.portfolios
+      .filter((entry) => entry.id !== portfolioId)
+      .map(clonePortfolio),
+  };
+
+  const changedTickers: TickerRecord[] = [];
+  let removedPositionCount = 0;
+
+  for (const ticker of tickers) {
+    const result = removeTickerFromPortfolio(ticker, portfolioId);
+    if (!result.changed) continue;
+    changedTickers.push(result.ticker);
+    removedPositionCount += result.removedPositionCount;
+  }
+
+  return {
+    config: nextConfig,
+    portfolio: clonePortfolio(portfolio),
+    tickers: changedTickers,
+    cleanedTickerCount: changedTickers.length,
+    removedPositionCount,
+  };
+}

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

@@ -39,6 +39,7 @@ import {
   resolveVisibleColumns,
 } from "./settings";
 import { PortfolioTickerTable, type QuoteFlashDirection } from "./table";
+import { useThrottledCursorSymbol } from "./use-throttled-cursor-symbol";
 
 const VISIBLE_FINANCIAL_REFRESH_COOLDOWN_MS = 5 * 60_000;
 
@@ -52,7 +53,6 @@ function needsVisibleFinancialWarmup(ticker: TickerRecord, financials: TickerFin
 function selectStreamTickers(
   tickers: TickerRecord[],
   _visibleRange: { start: number; end: number },
-  _cursorSymbol: string | null,
 ) {
   return tickers;
 }
@@ -129,7 +129,7 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
   const paneCollection = usePaneCollection();
 
   const [currentCollectionId, setCurrentCollectionId] = usePaneStateValue<string>("collectionId", paneCollection.collectionId ?? "");
-  const [cursorSymbol, setCursorSymbol] = usePaneStateValue<string | null>("cursorSymbol", null);
+  const [committedCursorSymbol, setCommittedCursorSymbol] = usePaneStateValue<string | null>("cursorSymbol", null);
   const [collectionSorts, setCollectionSorts] = usePaneStateValue<Record<string, CollectionSortPreference>>("collectionSorts", {});
   const [cashDrawerExpanded, setCashDrawerExpanded] = usePaneStateValue<boolean>("cashDrawerExpanded", false);
 
@@ -144,6 +144,12 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
   const warmupAttemptRef = useRef(new Map<string, number>());
   const scrollRef = useRef<ScrollBoxRenderable>(null);
   const headerScrollRef = useRef<ScrollBoxRenderable>(null);
+  const {
+    cursorSymbol,
+    setCursorSymbol,
+    flushCursorSymbol,
+    cancelPendingCursorSymbol,
+  } = useThrottledCursorSymbol(committedCursorSymbol, setCommittedCursorSymbol);
 
   const paneSettings = useMemo(
     () => getPortfolioPaneSettings(paneInstance?.settings),
@@ -159,11 +165,16 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
   );
   const activeCollectionId = resolveActiveCollectionId(currentCollectionId, visibleCollections, paneSettings);
   const isPortfolioTab = getCollectionType(state, activeCollectionId) === "portfolio";
-  const currentPortfolio = isPortfolioTab
-    ? state.config.portfolios.find((portfolio) => portfolio.id === activeCollectionId) ?? null
-    : null;
-
-  const tickers = getCollectionTickers(state, activeCollectionId);
+  const currentPortfolio = useMemo(() => (
+    isPortfolioTab
+      ? state.config.portfolios.find((portfolio) => portfolio.id === activeCollectionId) ?? null
+      : null
+  ), [activeCollectionId, isPortfolioTab, state.config.portfolios]);
+
+  const tickers = useMemo(
+    () => getCollectionTickers(state, activeCollectionId),
+    [activeCollectionId, state.config.portfolios, state.config.watchlists, state.tickers],
+  );
   const marketFinancialsMap = useTickerFinancialsMap(tickers);
   const sharedCoordinator = getSharedMarketDataCoordinator();
   const financialsMap = useMemo(() => {
@@ -240,6 +251,11 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
     updateStreamWindow();
   }, [syncHeaderScroll, updateStreamWindow]);
 
+  const handleCollectionSelect = useCallback((collectionId: string) => {
+    cancelPendingCursorSymbol();
+    setCurrentCollectionId(collectionId);
+  }, [cancelPendingCursorSymbol, setCurrentCollectionId]);
+
   const setSortPreference = useCallback((preference: CollectionSortPreference) => {
     if (!activeCollectionId) return;
     setCollectionSorts({
@@ -293,18 +309,20 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
 
     if (!paneSettings.hideTabs && (key === "h" || key === "left")) {
       const previousCollection = visibleCollections[Math.max(currentTabIdx - 1, 0)];
-      if (previousCollection) setCurrentCollectionId(previousCollection.id);
+      if (previousCollection) handleCollectionSelect(previousCollection.id);
       return;
     }
 
     if (!paneSettings.hideTabs && (key === "l" || key === "right")) {
       const nextCollection = visibleCollections[Math.min(currentTabIdx + 1, visibleCollections.length - 1)];
-      if (nextCollection) setCurrentCollectionId(nextCollection.id);
+      if (nextCollection) handleCollectionSelect(nextCollection.id);
       return;
     }
 
     if (!isEnter) return;
 
+    flushCursorSymbol(cursorSymbol);
+
     const follower = state.config.layout.instances.find((instance) =>
       instance.paneId === "ticker-detail"
       && instance.binding?.kind === "follow"
@@ -325,7 +343,8 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
     safeSelectedIdx,
     setCashDrawerExpanded,
     setCursorSymbol,
-    setCurrentCollectionId,
+    flushCursorSymbol,
+    handleCollectionSelect,
     showCashDrawer,
     sortedTickers,
     state.config.layout.instances,
@@ -336,9 +355,10 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
 
   useEffect(() => {
     if (activeCollectionId !== currentCollectionId) {
+      cancelPendingCursorSymbol();
       setCurrentCollectionId(activeCollectionId);
     }
-  }, [activeCollectionId, currentCollectionId, setCurrentCollectionId]);
+  }, [activeCollectionId, cancelPendingCursorSymbol, currentCollectionId, setCurrentCollectionId]);
 
   useEffect(() => {
     return () => {
@@ -402,19 +422,19 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
 
   useEffect(() => {
     if (sortedTickers.length === 0) {
-      if (cursorSymbol !== null) setCursorSymbol(null);
+      if (cursorSymbol !== null) setCursorSymbol(null, { immediate: true });
       return;
     }
 
     const hasSelection = cursorSymbol && sortedTickers.some((ticker) => ticker.metadata.ticker === cursorSymbol);
     if (!hasSelection) {
-      setCursorSymbol(sortedTickers[0]!.metadata.ticker);
+      setCursorSymbol(sortedTickers[0]!.metadata.ticker, { immediate: true });
     }
   }, [cursorSymbol, setCursorSymbol, sortedTickers]);
 
   const streamTickers = useMemo(
-    () => selectStreamTickers(sortedTickers, streamWindow, cursorSymbol),
-    [cursorSymbol, sortedTickers, streamWindow],
+    () => selectStreamTickers(sortedTickers, streamWindow),
+    [sortedTickers, streamWindow],
   );
   const streamTargets = useMemo(() => (
     streamTickers
@@ -477,7 +497,7 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
               <TabBar
                 tabs={visibleCollections.map((collection) => ({ label: collection.name, value: collection.id }))}
                 activeValue={activeCollectionId}
-                onSelect={setCurrentCollectionId}
+                onSelect={handleCollectionSelect}
                 compact
               />
             </box>
@@ -488,7 +508,9 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
             <PortfolioSummaryBar
               tickers={sortedTickers}
               financialsMap={financialsMap}
-              state={state}
+              baseCurrency={state.config.baseCurrency}
+              exchangeRates={effectiveExchangeRates}
+              refreshingCount={state.refreshing.size}
               isPortfolio={isPortfolioTab}
               collectionId={activeCollectionId}
               width={Math.max(0, width)}

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

@@ -1,4 +1,4 @@
-import type { RefObject } from "react";
+import { useCallback, type RefObject } from "react";
 import type { ScrollBoxRenderable } from "@opentui/core";
 import { TickerListTable, type QuoteFlashDirection } from "../../../components/ticker-list-table";
 import type { ColumnConfig } from "../../../types/config";
@@ -6,6 +6,8 @@ import type { TickerFinancials } from "../../../types/financials";
 import type { TickerRecord } from "../../../types/ticker";
 import { getColumnValue, type ColumnContext } from "./metrics";
 
+export type { QuoteFlashDirection };
+
 export function PortfolioTickerTable({
   columns,
   sortColumnId,
@@ -41,6 +43,13 @@ export function PortfolioTickerTable({
   columnContext: ColumnContext;
   flashSymbols: Map<string, QuoteFlashDirection>;
 }) {
+  const resolveCell = useCallback(
+    (column: ColumnConfig, ticker: TickerRecord, financials: TickerFinancials | undefined) => (
+      getColumnValue(column, ticker, financials, columnContext)
+    ),
+    [columnContext],
+  );
+
   return (
     <TickerListTable
       columns={columns}
@@ -49,7 +58,7 @@ export function PortfolioTickerTable({
       hoveredIdx={hoveredIdx}
       setHoveredIdx={setHoveredIdx}
       setCursorSymbol={setCursorSymbol}
-      resolveCell={(column, ticker, financials) => getColumnValue(column, ticker, financials, columnContext)}
+      resolveCell={resolveCell}
       financialsMap={financialsMap}
       headerScrollRef={headerScrollRef}
       scrollRef={scrollRef}

package/src/plugins/builtin/portfolio-list/use-throttled-cursor-symbol.test.tsx

@@ -0,0 +1,163 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { act, useState } from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { useThrottledCursorSymbol } from "./use-throttled-cursor-symbol";
+
+let testSetup: Awaited<ReturnType<typeof testRender>> | undefined;
+let setHarnessCursorSymbol: ((symbol: string | null, options?: { immediate?: boolean }) => void) | null = null;
+let flushHarnessCursorSymbol: ((symbol?: string | null) => void) | null = null;
+let latestCursorSymbol: string | null = null;
+let latestCommittedCursorSymbol: string | null = null;
+
+const TEST_THROTTLE_MS = 80;
+
+function ThrottledCursorHarness() {
+  const [committedCursorSymbol, setCommittedCursorSymbol] = useState<string | null>("AAPL");
+  const {
+    cursorSymbol,
+    setCursorSymbol,
+    flushCursorSymbol,
+  } = useThrottledCursorSymbol(committedCursorSymbol, setCommittedCursorSymbol, TEST_THROTTLE_MS);
+
+  latestCursorSymbol = cursorSymbol;
+  latestCommittedCursorSymbol = committedCursorSymbol;
+  setHarnessCursorSymbol = setCursorSymbol;
+  flushHarnessCursorSymbol = flushCursorSymbol;
+
+  return <text>{cursorSymbol ?? "none"}|{committedCursorSymbol ?? "none"}</text>;
+}
+
+afterEach(async () => {
+  if (testSetup) {
+    await act(async () => {
+      testSetup!.renderer.destroy();
+    });
+    testSetup = undefined;
+  }
+  setHarnessCursorSymbol = null;
+  flushHarnessCursorSymbol = null;
+  latestCursorSymbol = null;
+  latestCommittedCursorSymbol = null;
+});
+
+describe("useThrottledCursorSymbol", () => {
+  test("keeps the highlighted row immediate while settling the committed cursor", async () => {
+    testSetup = await testRender(<ThrottledCursorHarness />, {
+      width: 24,
+      height: 1,
+    });
+
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    await act(async () => {
+      setHarnessCursorSymbol?.("MSFT");
+      await Promise.resolve();
+    });
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    expect(latestCursorSymbol).toBe("MSFT");
+    expect(latestCommittedCursorSymbol).toBe("AAPL");
+
+    await act(async () => {
+      setHarnessCursorSymbol?.("NVDA");
+      await Promise.resolve();
+    });
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    expect(latestCursorSymbol).toBe("NVDA");
+    expect(latestCommittedCursorSymbol).toBe("AAPL");
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, TEST_THROTTLE_MS + 20));
+    });
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    expect(latestCommittedCursorSymbol).toBe("NVDA");
+  });
+
+  test("coalesces repeated cursor moves into the final committed symbol", async () => {
+    testSetup = await testRender(<ThrottledCursorHarness />, {
+      width: 24,
+      height: 1,
+    });
+
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    await act(async () => {
+      setHarnessCursorSymbol?.("MSFT");
+      await Promise.resolve();
+    });
+    await act(async () => {
+      setHarnessCursorSymbol?.("NVDA");
+      await Promise.resolve();
+    });
+    await act(async () => {
+      setHarnessCursorSymbol?.("AMD");
+      await Promise.resolve();
+    });
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    expect(latestCursorSymbol).toBe("AMD");
+    expect(latestCommittedCursorSymbol).toBe("AAPL");
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, TEST_THROTTLE_MS + 20));
+    });
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    expect(latestCommittedCursorSymbol).toBe("AMD");
+  });
+
+  test("can flush a pending cursor immediately", async () => {
+    testSetup = await testRender(<ThrottledCursorHarness />, {
+      width: 24,
+      height: 1,
+    });
+
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    await act(async () => {
+      setHarnessCursorSymbol?.("MSFT");
+      await Promise.resolve();
+    });
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    await act(async () => {
+      setHarnessCursorSymbol?.("NVDA");
+      await Promise.resolve();
+    });
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    expect(latestCommittedCursorSymbol).toBe("AAPL");
+
+    await act(async () => {
+      flushHarnessCursorSymbol?.("NVDA");
+      await Promise.resolve();
+    });
+    await act(async () => {
+      await testSetup!.renderOnce();
+    });
+
+    expect(latestCommittedCursorSymbol).toBe("NVDA");
+  });
+});

package/src/plugins/builtin/portfolio-list/use-throttled-cursor-symbol.ts

@@ -0,0 +1,81 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export const FOLLOW_CURSOR_THROTTLE_MS = 80;
+
+export function useThrottledCursorSymbol(
+  committedCursorSymbol: string | null,
+  setCommittedCursorSymbol: (symbol: string | null) => void,
+  throttleMs = FOLLOW_CURSOR_THROTTLE_MS,
+) {
+  const [cursorSymbol, setCursorSymbolState] = useState<string | null>(committedCursorSymbol);
+  const commitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const hasPendingCommitRef = useRef(false);
+  const pendingCursorSymbolRef = useRef<string | null>(committedCursorSymbol);
+  const appliedCursorSymbolRef = useRef<string | null>(committedCursorSymbol);
+
+  const clearPendingCursorCommit = useCallback(() => {
+    if (commitTimerRef.current) {
+      clearTimeout(commitTimerRef.current);
+      commitTimerRef.current = null;
+    }
+    hasPendingCommitRef.current = false;
+  }, []);
+
+  const commitCursorSymbol = useCallback((nextCursorSymbol?: string | null) => {
+    const targetCursorSymbol = nextCursorSymbol ?? pendingCursorSymbolRef.current;
+    clearPendingCursorCommit();
+    pendingCursorSymbolRef.current = targetCursorSymbol;
+
+    if (Object.is(appliedCursorSymbolRef.current, targetCursorSymbol)) {
+      return;
+    }
+
+    appliedCursorSymbolRef.current = targetCursorSymbol;
+    setCommittedCursorSymbol(targetCursorSymbol);
+  }, [clearPendingCursorCommit, setCommittedCursorSymbol]);
+
+  const scheduleCursorSymbol = useCallback((nextCursorSymbol: string | null, options?: { immediate?: boolean }) => {
+    setCursorSymbolState((current) => (Object.is(current, nextCursorSymbol) ? current : nextCursorSymbol));
+    pendingCursorSymbolRef.current = nextCursorSymbol;
+
+    if (options?.immediate) {
+      commitCursorSymbol(nextCursorSymbol);
+      return;
+    }
+
+    clearPendingCursorCommit();
+
+    if (Object.is(appliedCursorSymbolRef.current, nextCursorSymbol)) {
+      return;
+    }
+
+    hasPendingCommitRef.current = true;
+    commitTimerRef.current = setTimeout(() => {
+      commitCursorSymbol();
+    }, throttleMs);
+  }, [clearPendingCursorCommit, commitCursorSymbol, throttleMs]);
+
+  useEffect(() => {
+    if (hasPendingCommitRef.current && Object.is(committedCursorSymbol, pendingCursorSymbolRef.current)) {
+      clearPendingCursorCommit();
+    }
+
+    if (!hasPendingCommitRef.current) {
+      appliedCursorSymbolRef.current = committedCursorSymbol;
+      setCursorSymbolState((current) => (Object.is(current, committedCursorSymbol) ? current : committedCursorSymbol));
+    }
+  }, [clearPendingCursorCommit, committedCursorSymbol]);
+
+  useEffect(() => () => {
+    if (commitTimerRef.current) {
+      clearTimeout(commitTimerRef.current);
+    }
+  }, []);
+
+  return {
+    cursorSymbol,
+    setCursorSymbol: scheduleCursorSymbol,
+    flushCursorSymbol: commitCursorSymbol,
+    cancelPendingCursorSymbol: clearPendingCursorCommit,
+  };
+}