gloomberb 0.13.2 → 0.14.0

package/src/plugins/builtin/options/chain-integrity.test.tsx

@@ -0,0 +1,251 @@
+import { afterEach, expect, test } from "bun:test";
+import { act } from "react";
+const source = process.env.CHAIN_SOURCE ?? new URL("../../../../", import.meta.url).pathname.replace(/\/$/, "");
+const out = process.env.CHAIN_OUT;
+const { Box } = await import(`${source}/src/ui`);
+const { PaneFooterBar, PaneFooterProvider } = await import(`${source}/src/components/layout/pane/footer`);
+const { testRender, takeSavedTextFile } = await import(`${source}/src/renderers/opentui/test-utils`);
+const { exportPaneTable } = await import(`${source}/src/state/pane-table-export-registry`);
+const { MarketDataCoordinator, setSharedMarketDataCoordinator } = await import(`${source}/src/market-data/coordinator`);
+const { createInitialState } = await import(`${source}/src/state/app/context`);
+const { createTestDataProvider } = await import(`${source}/src/test-support/data-provider`);
+const { createTestPluginRuntime } = await import(`${source}/src/test-support/plugin-runtime`);
+const { TestPaneProvider, createTestTicker, createTestPaneConfig } = await import(`${source}/src/test-support/pane`);
+const { OptionsView } = await import(`${source}/src/plugins/builtin/options/view`);
+const { draftFromParams } = await import(`${source}/src/plugins/builtin/options-calculator/model`);
+const { loadYahooOptionsChain } = await import(`${source}/src/sources/yahoo-finance/options`);
+const { serializeCliResult } = await import(`${source}/src/cli/result`);
+const { marketDataCliCommands } = await import(`${source}/src/cli/commands/market`);
+const EXPIRY = Date.UTC(2028, 0, 21) / 1000;
+const NOW = Date.UTC(2026, 8, 17, 16);
+const PANE = "options:chain-followup";
+let setup: Awaited<ReturnType<typeof testRender>> | undefined;
+let coordinator: InstanceType<typeof MarketDataCoordinator> | undefined;
+const realNow = Date.now;
+afterEach(async () => {
+    if (setup)
+        await act(async () => setup!.renderer.destroy());
+    setup = undefined;
+    coordinator?.destroy();
+    coordinator = undefined;
+    setSharedMarketDataCoordinator(null);
+    Date.now = realNow;
+});
+function strikeRowY(strike: number): number {
+    return setup!.captureCharFrame().split("\n").findIndex(line => new RegExp(`\\s${strike}\\s`).test(line));
+}
+async function settle() {
+    for (let i = 0; i < 4; i++)
+        await act(async () => {
+            await new Promise(r => setTimeout(r, 0));
+            await setup!.renderOnce();
+        });
+}
+async function fixture(strikes: number[], activity: "full" | "missing" | "zero" = "full", width = 120) {
+    Date.now = () => NOW;
+    let rows = strikes;
+    let callsAvailable = true;
+    let failure = false;
+    let contractPrefix = "AAPL";
+    const requests: string[] = [];
+    const launches: any[] = [];
+    const raw = (strike: number, side: "C" | "P") => ({
+        contractSymbol: `${contractPrefix}280121${side}${String(Math.round(strike * 1000)).padStart(8, "0")}`,
+        strike, currency: "USD", lastPrice: 8, bid: 9, ask: 11, impliedVolatility: .25,
+        volume: activity === "missing" && side === "P" ? undefined : activity === "zero" && side === "P" ? 0 : 10,
+        openInterest: activity === "missing" && side === "C" ? undefined : activity === "zero" && side === "P" ? 0 : 20,
+        change: 0, percentChange: 0, inTheMoney: side === "P", expiration: EXPIRY, lastTradeDate: NOW / 1000 - 86400,
+    });
+    const provider = createTestDataProvider({ getOptionsChain: async (symbol, exchange, expirationDate) => loadYahooOptionsChain({
+            ticker: symbol, exchange: exchange ?? "", expirationDate,
+            fetchJsonWithCrumb: async (url: string) => {
+                requests.push(url);
+                if (failure)
+                    throw new Error("Controlled chain outage");
+                return { optionChain: { result: [{ underlyingSymbol: symbol, expirationDates: [EXPIRY], options: [{ calls: callsAvailable ? rows.map(s => raw(s, "C")) : [], puts: rows.map(s => raw(s, "P")) }] }] } } as any;
+            },
+        }) });
+    coordinator = new MarketDataCoordinator(provider);
+    setSharedMarketDataCoordinator(coordinator);
+    const ticker = createTestTicker("AAPL", "Apple", { assetCategory: "STK" });
+    const config = createTestPaneConfig("/tmp/option-chain-controlled", { instanceId: PANE, paneId: "options", settings: { optionColumnIds: ["bid", "ask", "volume", "openInterest", "iv"] }, binding: { kind: "fixed", symbol: "AAPL" } });
+    const state = createInitialState(config);
+    state.focusedPaneId = PANE;
+    state.tickers = new Map([["AAPL", ticker]]);
+    state.financials = new Map([["AAPL", { quote: { symbol: "AAPL", price: strikes[0], currency: "USD", change: 0, changePercent: 0, lastUpdated: NOW, stale: false }, annualStatements: [], quarterlyStatements: [], priceHistory: [] }]]);
+    const runtime = createTestPluginRuntime({ createPaneFromTemplate: (_id: string, options: any) => launches.push(draftFromParams(options?.values)) });
+    await act(async () => {
+        setup = await testRender(<TestPaneProvider state={state} paneId={PANE} pluginId="ticker-research" runtime={runtime}><PaneFooterProvider>{footer => <Box width={width} height={22} flexDirection="column"><Box height={21}><OptionsView width={width} height={21} focused/></Box><PaneFooterBar footer={footer} focused width={width}/></Box>}</PaneFooterProvider></TestPaneProvider>, { width, height: 22 });
+    });
+    await settle();
+    async function key(name: string) {
+        await act(async () => {
+            if (name === "enter")
+                setup!.mockInput.pressEnter();
+            else if (name === "down" || name === "up")
+                setup!.mockInput.pressArrow(name);
+            else
+                setup!.mockInput.pressKey(name);
+        });
+        await act(async () => {
+            await new Promise(r => setTimeout(r, 180));
+        });
+        await settle();
+    }
+    async function capture(name: string) {
+        const n = launches.length;
+        await key("c");
+        await exportPaneTable(PANE, `${name}.csv`);
+        const csv = takeSavedTextFile()?.text ?? "";
+        const frame = setup!.captureCharFrame();
+        const result = { source, launch: launches.length > n ? launches.at(-1) : null, csv, frame, requests: [...requests] };
+        if (out) {
+            await Bun.write(`${out}/${width}-${name}.txt`, frame);
+            await Bun.write(`${out}/${width}-${name}.csv`, csv);
+            await Bun.write(`${out}/${width}-${name}.json`, JSON.stringify(result, null, 2));
+        }
+        return result;
+    }
+    async function refresh(next: number[]) {
+        rows = next;
+        await act(async () => {
+            await coordinator!.loadOptions({ instrument: { symbol: "AAPL", exchange: "NASDAQ" }, expirationDate: EXPIRY }, { forceRefresh: true });
+        });
+        await settle();
+    }
+    async function cli(name: string) {
+        let data: any;
+        let renderedRows: any;
+        let text = "";
+        let json = "";
+        await marketDataCliCommands.find(c => c.name === "options")!.execute(["AAPL", "--expiration", String(EXPIRY)], { cliOptions: {}, initMarketData: async () => ({ dataProvider: provider, destroy() {
+                }, persistence: { close() {
+                    } } }), printResult: (result: any, options: any) => {
+                data = result.data;
+                renderedRows = options.rows(result.data);
+                text = serializeCliResult(result, { format: "text" }, options);
+                json = serializeCliResult(result, { format: "json" }, options);
+            }, fail: (message: string) => {
+                throw new Error(message);
+            } } as any);
+        const value = { data, rows: renderedRows, text, json };
+        if (out) {
+            await Bun.write(`${out}/${width}-${name}-cli.json`, JSON.stringify(value, null, 2));
+            await Bun.write(`${out}/${width}-${name}-cli.txt`, text);
+        }
+        return value;
+    }
+    return { key, capture, refresh, cli, replaceSymbols: () => {
+            contractPrefix = "AAPL1";
+        }, setCalls: (value: boolean) => {
+            callsAvailable = value;
+        }, setFailure: (value: boolean) => {
+            failure = value;
+        } };
+}
+test.each([48, 80, 120])("keeps the selected strike through insertion, removal and recovery at %i columns", async (width) => {
+    const f = await fixture([100, 101, 102], "full", width);
+    await act(async () => {
+        const y = setup!.captureCharFrame().split("\n").findIndex(line => /\s101\s/.test(line));
+        await setup!.mockMouse.click(8, y);
+    });
+    await settle();
+    const picked = await f.capture("strike-selected");
+    expect(picked.launch.strike).toBe(101);
+    await f.refresh([99, 100, 101, 102]);
+    const inserted = await f.capture("strike-inserted");
+    expect(inserted.launch.marketReference.contractSymbol).toBe(picked.launch.marketReference.contractSymbol);
+    expect(inserted.launch).toMatchObject({ side: "call", strike: 101, marketPrice: 10, marketPriceSource: "mid" });
+    await f.refresh([99, 100, 102]);
+    const removed = await f.capture("strike-removed");
+    expect(removed.launch).toBeNull();
+    await f.refresh([99, 100, 101, 102]);
+    const recovered = await f.capture("strike-recovered");
+    expect(recovered.launch.marketReference.contractSymbol).toBe(picked.launch.marketReference.contractSymbol);
+});
+test("preserves call identity across partial chains, and permits an explicit put selection", async () => {
+    const f = await fixture([100]);
+    await act(async () => {
+        await setup!.mockMouse.click(8, strikeRowY(100));
+    });
+    await settle();
+    const picked = await f.capture("call-selected");
+    expect(picked.launch.side).toBe("call");
+    f.setCalls(false);
+    await f.refresh([100]);
+    const removed = await f.capture("call-removed");
+    expect(removed.launch).toBeNull();
+    expect(removed.frame).toContain("Selected 100 call unavailable");
+    await act(async () => {
+        await setup!.mockMouse.click(69, strikeRowY(100));
+    });
+    await settle();
+    const put = await f.capture("put-selected");
+    expect(put.launch.side).toBe("put");
+    f.setCalls(true);
+    await f.refresh([100]);
+    expect((await f.capture("put-after-recovery")).launch.side).toBe("put");
+});
+test("keyboard choice and transient failure retain the same contract through recovery", async () => {
+    const f = await fixture([100, 101, 102]);
+    await f.key("enter");
+    await f.key("down");
+    const picked = await f.capture("keyboard-selected");
+    expect(picked.launch.strike).toBe(101);
+    f.setFailure(true);
+    await f.refresh([99, 100, 101, 102]);
+    const failed = await f.capture("refresh-failed");
+    expect(failed.launch.marketReference.contractSymbol).toBe(picked.launch.marketReference.contractSymbol);
+    expect(failed.frame).toContain("Controlled chain outage");
+    f.setFailure(false);
+    await f.refresh([99, 100, 101, 102]);
+    const recovered = await f.capture("refresh-recovered");
+    expect(recovered.launch.marketReference.contractSymbol).toBe(picked.launch.marketReference.contractSymbol);
+});
+test("keeps distinct fractional strike identity in table, CSV, seed and existing CLI", async () => {
+    const f = await fixture([100.125, 100.126]);
+    const result = await f.capture("fractional");
+    expect(result.launch.strike).toBe(100.125);
+    expect(result.csv).toContain("100.125");
+    expect(result.csv).toContain("100.126");
+    expect(result.frame).toContain("100.125");
+    const cli = await f.cli("fractional");
+    expect(cli.rows.map((row: any) => row.strike)).toEqual([100.125, 100.126, 100.125, 100.126]);
+    expect(cli.text).toContain("100.126");
+});
+test("preserves missing activity through source, summaries, CSV and CLI", async () => {
+    const f = await fixture([100], "missing");
+    const result = await f.capture("missing-activity");
+    const cli = await f.cli("missing-activity");
+    expect(cli.data.calls[0].openInterest).toBeUndefined();
+    expect(cli.data.puts[0].volume).toBeUndefined();
+    expect(result.frame).toMatch(/EXP VOL —\s+P\/C VOL —\s+P\/C OI —/);
+    expect(result.csv).toContain(",—,");
+    expect(cli.rows[0].volume).toBe(10);
+    expect(cli.rows[1].openInterest).toBe(20);
+    expect(cli.text).not.toContain("NaN");
+});
+test("preserves known zero activity and zero put/call ratios", async () => {
+    const f = await fixture([100], "zero");
+    const result = await f.capture("zero-activity");
+    const cli = await f.cli("zero-activity");
+    expect(cli.data.puts[0]).toMatchObject({ volume: 0, openInterest: 0 });
+    expect(result.frame).toMatch(/EXP VOL 10\s+P\/C VOL 0.00\s+P\/C OI 0.00/);
+    expect(result.csv).toContain(",0,");
+    expect(cli.rows[1].volume).toBe(0);
+});
+test("a different source contract at the same strike cannot replace the selected quote reference", async () => {
+    const f = await fixture([100]);
+    await act(async () => {
+        await setup!.mockMouse.click(8, strikeRowY(100));
+    });
+    await settle();
+    const selected = await f.capture("symbol-selected");
+    expect(selected.launch.marketReference.contractSymbol).toBe("AAPL280121C00100000");
+    f.replaceSymbols();
+    await f.refresh([100]);
+    const replaced = await f.capture("symbol-replaced");
+    expect(replaced.launch).toBeNull();
+    expect(replaced.frame).not.toContain("AAPL1280121C00100000");
+    expect(replaced.frame).toContain("Selected 100 call unavailable");
+});

package/src/plugins/builtin/options/expiry-catalogue.ts

@@ -0,0 +1,43 @@
+import { useState } from "react";
+import type { OptionsChain } from "../../../types/financials";
+import type { QueryEntry } from "../../../market-data/result-types";
+import { resolveEntryValue } from "../../../market-data/coordinator";
+
+type ChainEntry = QueryEntry<OptionsChain> | null;
+interface CatalogueState {
+  targetKey: string;
+  catalogue: ChainEntry;
+}
+
+function newerObservation(entry: QueryEntry<OptionsChain>, previous: QueryEntry<OptionsChain>): boolean {
+  if (entry.responseSequence != null && previous.responseSequence != null) {
+    return entry.responseSequence > previous.responseSequence;
+  }
+  // Hydrated caches may lack runtime order. Attaching one is not a retrieval:
+  // use its recorded time and keep the known observation when times tie.
+  if (entry.fetchedAt !== previous.fetchedAt) return entry.fetchedAt! > previous.fetchedAt!;
+  return entry.responseSequence != null && previous.responseSequence == null;
+}
+
+/** Keep successful catalogue observations across expiry switches and failures. */
+export function useOptionsCatalogue(
+  targetKey: string,
+  initial: ChainEntry,
+  selected: ChainEntry,
+): { chain: OptionsChain | null; expirationDates: number[] } {
+  const [previous, setPrevious] = useState<CatalogueState | null>(null);
+  let catalogue = previous?.targetKey === targetKey ? previous.catalogue : null;
+  for (const entry of [initial, selected]) {
+    // Error/loading projections retain the last successful response and its
+    // order. Idle or never-successful queries have no observation to compare.
+    if (entry?.fetchedAt == null || resolveEntryValue(entry) == null) continue;
+    if (!catalogue || newerObservation(entry, catalogue)) catalogue = entry;
+  }
+  if (!previous || previous.targetKey !== targetKey || previous.catalogue !== catalogue) {
+    // Adjust before children render, preventing transient calculator/CSV seeds
+    // from a catalogue which has already removed the selected expiration.
+    setPrevious({ targetKey, catalogue });
+  }
+  const chain = catalogue ? resolveEntryValue(catalogue) : null;
+  return { chain, expirationDates: chain?.expirationDates ?? [] };
+}

package/src/plugins/builtin/options/expiry-selection.test.tsx

@@ -0,0 +1,317 @@
+import { afterEach, expect, test } from "bun:test";
+import { act, useState } from "react";
+import { CachedQuery } from "../../../data/cached-query";
+import type { DataProvider } from "../../../types/data-provider";
+import { Box } from "../../../ui";
+import { PaneFooterBar, PaneFooterProvider } from "../../../components/layout/pane/footer";
+import { takeSavedTextFile, testRender } from "../../../renderers/opentui/test-utils";
+import { exportPaneTable } from "../../../state/pane-table-export-registry";
+import { MarketDataCoordinator, setSharedMarketDataCoordinator } from "../../../market-data/coordinator";
+import { createInitialState } from "../../../state/app/context";
+import { createTestDataProvider } from "../../../test-support/data-provider";
+import { createTestPluginRuntime } from "../../../test-support/plugin-runtime";
+import { TestPaneProvider, createTestTicker, createTestPaneConfig } from "../../../test-support/pane";
+import type { OptionContract, OptionsChain, TickerFinancials } from "../../../types/financials";
+import type { TickerRecord } from "../../../types/ticker";
+import { OptionsView } from "./view";
+import { draftFromParams } from "../options-calculator/model";
+
+const PANE_ID = "options:expiry-selection";
+const EXPIRIES = [Date.UTC(2026, 8, 18), Date.UTC(2026, 9, 16), Date.UTC(2026, 10, 20)].map((ms) => ms / 1000);
+const EXPIRY_CODES = ["260918", "261016", "261120"];
+let setup: Awaited<ReturnType<typeof testRender>> | undefined;
+const realNow = Date.now;
+
+afterEach(async () => {
+  if (setup) await act(async () => setup!.renderer.destroy());
+  setup = undefined;
+  setSharedMarketDataCoordinator(null);
+  Date.now = realNow;
+});
+
+async function settle() {
+  for (let i = 0; i < 4; i += 1) await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await setup!.renderOnce();
+  });
+}
+
+async function fixture(width = 80, heldExpiry = 0, cached = false) {
+  let now = Date.UTC(2026, 8, 17, 16);
+  Date.now = () => now;
+  let catalogue = [...EXPIRIES];
+  const requests: Array<{ symbol: string; expiration: number | undefined }> = [];
+  const launches: ReturnType<typeof draftFromParams>[] = [];
+  const pending = new Map<number, Promise<OptionsChain>>();
+  let wrongExpiry: number | undefined;
+  let failure = false;
+  const makeContract = (symbol: string, expiration: number, side: "C" | "P"): OptionContract => {
+    const index = EXPIRIES.indexOf(expiration);
+    return {
+      contractSymbol: `${symbol}${EXPIRY_CODES[index]}${side}00340000`, strike: 340, currency: "USD",
+      lastPrice: 10 + index * 10, change: 0, percentChange: 0, volume: 123, openInterest: 456,
+      bid: 9 + index * 10, ask: 11 + index * 10, impliedVolatility: 0.25,
+      inTheMoney: side === "P", expiration, lastTradeDate: now / 1000, lastUpdated: now,
+    };
+  };
+  const chain = (symbol: string, expiration: number): OptionsChain => ({
+    underlyingSymbol: symbol, expirationDates: [...catalogue],
+    calls: [makeContract(symbol, expiration, "C")], puts: [makeContract(symbol, expiration, "P")],
+  });
+  const financials = (symbol: string): TickerFinancials => ({
+    quote: { symbol, price: 330, currency: "USD", change: 0, changePercent: 0, lastUpdated: now, stale: false },
+    annualStatements: [], quarterlyStatements: [], priceHistory: [],
+  });
+  const provider = createTestDataProvider({
+    getTickerFinancials: async (symbol) => financials(symbol),
+    getQuote: async (symbol) => financials(symbol).quote!,
+    getOptionsChain: async (symbol, _exchange, expiration) => {
+      requests.push({ symbol, expiration });
+      if (failure) throw new Error("Options source offline");
+      return expiration != null && pending.has(expiration)
+        ? pending.get(expiration)! : chain(symbol, wrongExpiry ?? expiration ?? catalogue[0]!);
+    },
+  });
+  if (cached) {
+    const queries = new Map<string, CachedQuery<OptionsChain>>();
+    provider.getCachedQuery = ((method, args) => {
+      if (method !== "getOptionsChain") return undefined;
+      const [symbol, exchange, expiration] = args as [string, string, number | undefined];
+      const key = `${symbol}:${expiration ?? "default"}`;
+      if (!queries.has(key)) queries.set(key, new CachedQuery({ read: () => null, fetch: async () => ({
+        value: await provider.getOptionsChain!(symbol, exchange, expiration), fetchedAt: now,
+        staleAt: now + 600_000, expiresAt: now + 3_600_000, source: "test-cache",
+      }) }));
+      return queries.get(key);
+    }) as DataProvider["getCachedQuery"];
+  }
+  const coordinator = new MarketDataCoordinator(provider);
+  setSharedMarketDataCoordinator(coordinator);
+  const ticker = (symbol: string, expiry: number) => createTestTicker(`${symbol} ${EXPIRY_CODES[expiry]}C00340000`, symbol, {
+    assetCategory: "OPT", positions: [{ portfolio: "fixture", shares: 1, side: "short", avgCost: 5, broker: "manual", multiplier: 100 }],
+  });
+  await coordinator.loadSnapshot({ symbol: "AAPL", exchange: "" });
+  let switchTicker: (ticker: TickerRecord) => void = () => {};
+  const runtime = createTestPluginRuntime({
+    createPaneFromTemplate: (_id, options) => { launches.push(draftFromParams(options?.values)); },
+  });
+  function Harness() {
+    const [selected, setSelected] = useState(ticker("AAPL", heldExpiry));
+    switchTicker = setSelected;
+    const config = createTestPaneConfig("/tmp/options-expiry-test", {
+      instanceId: PANE_ID, paneId: "options", binding: { kind: "fixed", symbol: selected.metadata.ticker },
+    });
+    const state = createInitialState(config);
+    state.focusedPaneId = PANE_ID;
+    state.tickers = new Map([[selected.metadata.ticker, selected]]);
+    return <TestPaneProvider state={state} paneId={PANE_ID} pluginId="ticker-research" runtime={runtime}>
+      <PaneFooterProvider>{(footer) => <Box width={width} height={18} flexDirection="column">
+        <Box width={width} height={17}><OptionsView width={width} height={17} focused /></Box>
+        <PaneFooterBar footer={footer} focused width={width} />
+      </Box>}</PaneFooterProvider>
+    </TestPaneProvider>;
+  }
+  await act(async () => { setup = await testRender(<Harness />, { width, height: 18 }); });
+  await settle();
+  async function key(key: "enter" | "left" | "right" | "c") {
+    await act(async () => {
+      if (key === "enter") setup!.mockInput.pressEnter();
+      else if (key === "left" || key === "right") setup!.mockInput.pressArrow(key);
+      else setup!.mockInput.pressKey(key);
+    });
+    await settle();
+  }
+  async function capture(label: string) {
+    const count = launches.length;
+    await key("c");
+    await exportPaneTable(PANE_ID, `${label}.csv`);
+    const csv = takeSavedTextFile()?.text ?? "";
+    const frame = setup!.captureCharFrame();
+    const result = { frame, csv, launch: launches.length > count ? launches.at(-1) : undefined, requests: [...requests] };
+    const evidence = process.env.OPTIONS_EXPIRY_EVIDENCE;
+    if (evidence) {
+      await Bun.write(`${evidence}/${width}-${label}.txt`, frame);
+      await Bun.write(`${evidence}/${width}-${label}.csv`, csv);
+      await Bun.write(`${evidence}/${width}-${label}.json`, JSON.stringify(result, null, 2));
+    }
+    return result;
+  }
+  async function refresh(dates: number[], expiration?: number, advanceClock = true) {
+    catalogue = dates;
+    if (advanceClock) now += 1_000;
+    await act(async () => { await coordinator.loadOptions({ instrument: { symbol: "AAPL", exchange: "" }, expirationDate: expiration }, { forceRefresh: true }); });
+    await settle();
+  }
+  const request = (expiration?: number) => ({ instrument: { symbol: "AAPL", exchange: "" }, expirationDate: expiration });
+  return { capture, key, refresh, pending, chain, requests,
+    setFailure: (value: boolean) => { failure = value; },
+    async reread(expiration?: number) {
+      await act(async () => { await coordinator.loadOptions(request(expiration)); }); await settle();
+    },
+    async batch(selected: number[], initial: number[]) {
+      await act(async () => {
+        catalogue = selected;
+        await coordinator.loadOptions(request(EXPIRIES[1]), { forceRefresh: true });
+        catalogue = initial;
+        await coordinator.loadOptions(request(), { forceRefresh: true });
+      }); await settle();
+    },
+    async remount() {
+      await act(async () => setup!.renderer.destroy());
+      await act(async () => { setup = await testRender(<Harness />, { width, height: 18 }); }); await settle();
+    },
+    setWrongExpiry: (expiration: number | undefined) => { wrongExpiry = expiration; },
+    async switchUnderlying() {
+      await coordinator.loadSnapshot({ symbol: "MSFT", exchange: "" });
+      await act(async () => switchTicker(ticker("MSFT", 1)));
+      await settle();
+    },
+  };
+}
+
+test.each([48, 80, 120])("retains a chosen expiry across unchanged, reordered and shortened catalogues at %i columns", async (width) => {
+  const f = await fixture(width);
+  await f.key("enter"); await f.key("right");
+  for (const [label, catalogue] of [
+    ["chosen", EXPIRIES], ["reordered", [EXPIRIES[2]!, EXPIRIES[0]!, EXPIRIES[1]!]], ["prior-removed", EXPIRIES.slice(1)],
+  ] as const) {
+    await f.refresh([...catalogue]);
+    const result = await f.capture(label);
+    expect(result.launch?.marketReference?.expiration).toBe(EXPIRIES[1]);
+    expect(result.launch?.marketPrice).toBe(20);
+    expect(result.csv).toContain("19,21,10.0%,20");
+    expect(result.frame).not.toContain("AAPL261120");
+  }
+});
+
+test("selected-chain refresh uses the same date identities for the catalogue, table and navigation", async () => {
+  const f = await fixture(); await f.key("enter"); await f.key("right");
+  await f.refresh(EXPIRIES.slice(1), EXPIRIES[1]);
+  const selected = await f.capture("selected-query-refresh");
+  expect(selected.launch?.marketReference?.expiration).toBe(EXPIRIES[1]);
+  await f.key("right");
+  expect((await f.capture("next-after-refresh")).launch?.marketReference?.expiration).toBe(EXPIRIES[2]);
+});
+
+test.each([48, 80, 120])("a removed selected expiry cannot seed another contract and can recover at %i columns", async (width) => {
+  const f = await fixture(width); await f.key("enter"); await f.key("right");
+  await f.refresh([EXPIRIES[0]!, EXPIRIES[2]!]);
+  const missing = await f.capture("selected-removed");
+  expect(missing.launch).toBeUndefined();
+  expect(missing.frame).toContain("Selected expiration unavailable.");
+  expect(missing.csv.split("\n")).toHaveLength(1);
+  await f.refresh(EXPIRIES);
+  const recovered = await f.capture("selected-recovered");
+  expect(recovered.launch?.marketReference?.expiration).toBe(EXPIRIES[1]);
+  expect(recovered.frame).not.toContain("Selected expiration unavailable.");
+});
+
+test("a new underlying initializes its held expiry after a researcher chose another date", async () => {
+  const f = await fixture(80, 1);
+  expect((await f.capture("held-initial")).launch?.marketReference?.expiration).toBe(EXPIRIES[1]);
+  await f.key("enter"); await f.key("right");
+  expect((await f.capture("held-roll")).launch?.marketReference?.expiration).toBe(EXPIRIES[2]);
+  await f.switchUnderlying();
+  const changed = await f.capture("new-underlying");
+  expect(changed.launch?.symbol).toBe("MSFT");
+  expect(changed.launch?.marketReference?.expiration).toBe(EXPIRIES[1]);
+  expect(changed.frame).not.toContain("AAPL");
+});
+
+test("late and wrong-expiry responses cannot replace a newly selected contract", async () => {
+  const f = await fixture();
+  let finish: (chain: OptionsChain) => void = () => {};
+  f.pending.set(EXPIRIES[1]!, new Promise((resolve) => { finish = resolve; }));
+  await f.key("enter"); await f.key("right");
+  const loading = await f.capture("cold-expiry");
+  expect(loading.launch).toBeUndefined();
+  expect(loading.csv.split("\n")).toHaveLength(1);
+  await f.key("right");
+  expect((await f.capture("newer-selection")).launch?.marketReference?.expiration).toBe(EXPIRIES[2]);
+  await act(async () => finish(f.chain("AAPL", EXPIRIES[1]!))); await settle();
+  expect((await f.capture("late-response")).launch?.marketReference?.expiration).toBe(EXPIRIES[2]);
+  f.setWrongExpiry(EXPIRIES[1]);
+  await f.refresh(EXPIRIES, EXPIRIES[2]);
+  const wrong = await f.capture("wrong-expiry");
+  expect(wrong.launch).toBeUndefined();
+  expect(wrong.frame).toContain("Selected expiration unavailable.");
+  expect(wrong.csv.split("\n")).toHaveLength(1);
+});
+
+
+test("same-millisecond catalogue refresh retains a removed selection as unavailable", async () => {
+  const f = await fixture(); await f.key("enter"); await f.key("right");
+  await f.refresh([EXPIRIES[0]!, EXPIRIES[2]!], undefined, false);
+  const removed = await f.capture("equal-time-removal");
+  expect(removed.launch).toBeUndefined();
+  expect(removed.frame).toContain("Selected expiration unavailable.");
+  await f.refresh(EXPIRIES, undefined, false);
+  expect((await f.capture("equal-time-recovery")).launch?.marketReference?.expiration).toBe(EXPIRIES[1]);
+});
+
+test("visiting a cached expiry cannot restore an older catalogue, and an empty refresh disables the selected contract", async () => {
+  const f = await fixture(); await f.key("enter"); await f.key("right"); await f.key("right");
+  await f.key("left");
+  await f.refresh(EXPIRIES.slice(1), EXPIRIES[1]);
+  await f.key("right");
+  const cached = await f.capture("cached-expiry");
+  expect(cached.launch?.marketReference?.expiration).toBe(EXPIRIES[2]);
+  expect(cached.frame).not.toContain("Sep 18 '26");
+  await f.refresh([], EXPIRIES[2]);
+  const empty = await f.capture("empty-catalogue");
+  expect(empty.launch).toBeUndefined();
+  expect(empty.frame).toContain("Selected expiration unavailable.");
+  expect(empty.csv.split("\n")).toHaveLength(1);
+});
+
+
+test("the existing expiry selector can leave an unavailable date for an explicitly chosen contract", async () => {
+  const f = await fixture(); await f.key("enter"); await f.key("right");
+  await f.refresh([EXPIRIES[0]!, EXPIRIES[2]!]);
+  expect((await f.capture("explicit-selection-before")).launch).toBeUndefined();
+  await f.key("right");
+  const selected = await f.capture("explicit-selection-after");
+  expect(selected.launch?.marketReference?.expiration).toBe(EXPIRIES[2]);
+  expect(selected.launch?.marketPrice).toBe(30);
+  expect(selected.frame).not.toContain("Selected expiration unavailable.");
+});
+
+
+test("an ordinary CachedQuery read cannot revive an expiry removed by a later same-time response", async () => {
+  const f = await fixture(80, 0, true); await f.key("enter"); await f.key("right");
+  await f.refresh([EXPIRIES[0]!, EXPIRIES[2]!], undefined, false);
+  expect((await f.capture("cached-read-removed")).launch).toBeUndefined();
+  const calls = f.requests.length;
+  await f.reread(EXPIRIES[1]);
+  const read = await f.capture("cached-read-retained");
+  expect(f.requests).toHaveLength(calls);
+  expect(read.launch).toBeUndefined();
+  expect(read.csv.split("\n")).toHaveLength(1);
+});
+
+test.each([false, true])("batched equal-time responses honor completion order with cached provider %s", async (cached) => {
+  const f = await fixture(80, 0, cached); await f.key("enter"); await f.key("right");
+  await f.batch(EXPIRIES, [EXPIRIES[0]!, EXPIRIES[2]!]);
+  const removed = await f.capture(`batch-${cached}`);
+  expect(removed.launch).toBeUndefined();
+  expect(removed.csv.split("\n")).toHaveLength(1);
+  await f.refresh(EXPIRIES, EXPIRIES[1], false);
+  expect((await f.capture(`batch-recovered-${cached}`)).launch?.marketReference?.expiration).toBe(EXPIRIES[1]);
+});
+
+test.each([false, true])("empty and removed catalogues survive failed refreshes and remount with cached provider %s", async (cached) => {
+  const f = await fixture(80, 1, cached);
+  expect((await f.capture(`remount-chosen-${cached}`)).launch?.marketReference?.expiration).toBe(EXPIRIES[1]);
+  for (const [label, dates] of [["removed", [EXPIRIES[0]!, EXPIRIES[2]!]], ["empty", []]] as const) {
+    f.setFailure(false);
+    await f.refresh([...dates], EXPIRIES[1]);
+    f.setFailure(true);
+    await f.refresh(EXPIRIES, EXPIRIES[1]);
+    await f.refresh(EXPIRIES);
+    await f.remount();
+    const remounted = await f.capture(`remount-${label}-${cached}`);
+    expect(remounted.launch).toBeUndefined();
+    expect(remounted.csv.split("\n")).toHaveLength(1);
+    expect(remounted.frame).toContain("Selected expiration unavailable.");
+  }
+});

package/src/plugins/builtin/options/footer.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { resolveOptionsDelayLabel } from "./footer";
+import { optionContractFooterSegments, resolveOptionsDelayLabel } from "./footer";
 
 describe("options delay label", () => {
   test("prefers the chain delay and falls back to the cloud default", () => {
@@ -21,3 +21,40 @@ describe("options delay label", () => {
     expect(resolveOptionsDelayLabel(null)).toBe("15m");
   });
 });
+
+describe("selected contract status", () => {
+  const reference = (bid: number, ask: number) => ({
+    contractSymbol: "AAPL260619C00101000",
+    expiration: 1_782_345_600,
+    currency: "USD",
+    bid,
+    ask,
+    lastPrice: 10.1,
+    lastTradeDate: 1_782_000_000,
+  });
+  // One hour after the contract last printed.
+  const NOW = 1_782_000_000_000 + 3_600_000;
+  const texts = (...args: Parameters<typeof optionContractFooterSegments>) =>
+    optionContractFooterSegments(...args).map((segment) => segment.parts.map((part) => part.text).join(" "));
+
+  test("yields the spread to a visible SPRD column, but never the reason one is missing", () => {
+    expect(texts(reference(10.05, 10.15), false, NOW)).toContain("spread 0.1 (1.0% of mid)");
+    expect(texts(reference(10.05, 10.15), true, NOW)).not.toContain("spread 0.1 (1.0% of mid)");
+    // The column renders every degenerate quote as one dash, so the status bar
+    // keeps naming them whether or not it is shown.
+    for (const visible of [false, true]) {
+      expect(texts(reference(10.15, 10.05), visible, NOW)).toContain("crossed quote");
+      expect(texts(reference(0, 10.05), visible, NOW)).toContain("one-sided quote");
+      expect(texts(reference(0, 0), visible, NOW)).toContain("no bid/ask");
+    }
+  });
+
+  test("identity and staleness survive either column layout", () => {
+    for (const visible of [false, true]) {
+      const parts = texts(reference(10.05, 10.15), visible, NOW);
+      expect(parts).toContain("AAPL260619C00101000");
+      expect(parts).toContain("trade 1h");
+    }
+    expect(optionContractFooterSegments(undefined, false, NOW)).toEqual([]);
+  });
+});