gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/options-scenario/client.ts

@@ -6,15 +6,19 @@ import type { DataProvider } from "../../../types/data-provider";
 import type { CorporateActionsData, OptionsChain, Quote, TickerFinancials } from "../../../types/financials";
 import { canonicalExchange, parsePublicTickerKey } from "../../../utils/exchanges";
 import { numberErrorMessage } from "../../../utils/decimal-comma";
-import { expiryIsoDate, findListedExpiry, missingExpiryText } from "../../../utils/option-expiry";
+import {
+  expiredExpiryText, expiryChoiceText, expiryDayLabel, expiryIsoDate, findListedExpiry, isLiveOptionExpiry, liveDefaultExpiry, liveOptionExpiries,
+  missingExpiryText, nextLiveExpiry,
+} from "../../../utils/option-expiry";
 import { surfaceTreasuryRate } from "../vol-surface/model";
-import { daysToExpiryFrom, extractImpliedForward, optionMid, solveImpliedVolatility } from "../shared/volatility";
+import { daysToExpiryFrom, extractImpliedForward, optionDelta, optionMid, solveImpliedVolatility, valueOption } from "../shared/volatility";
 import type { YieldPoint } from "../yield-curve/treasury-data";
 import { parseLegs, scenarioCurrency, validatePosition, type ScenarioControls, type ScenarioLeg, type ScenarioPosition } from "./model";
 import { loadModelDividendYield, type ModelDividendYield } from "../../../market-data/model-dividend-yield";
 import { abortable, abortError } from "../../../utils/async-deadline";
 import { extendedSession, modelSpotStamp, modelSpotStampVariants, type OptionModelSpot } from "../options/model-spot";
 import { errorMessage } from "../../../utils/errors";
+import { dateOptionError, dateOptionFormatsOr, readCalendarDate } from "../../../utils/calendar-date";
 
 export interface ScenarioMarketSnapshot {
   symbol: string;
@@ -86,10 +90,13 @@ export async function loadScenarioMarket(
   const symbol = request.instrument.symbol.trim().toUpperCase();
   const options = { forceRefresh: request.forceRefresh };
   const warnings: string[] = [];
+  const exchange = request.instrument.exchange;
+  // An expiry whose last session has closed has no chain: the default one lists the live expiries to name instead.
+  const expired = request.expiration != null && !isLiveOptionExpiry(request.expiration, now, exchange);
   const settled = await abortable(Promise.allSettled([
     dependencies.loadQuote(request.instrument, options),
     dependencies.loadSnapshot(request.instrument, options),
-    dependencies.loadOptions({ instrument: request.instrument, expirationDate: request.expiration }, options),
+    dependencies.loadOptions({ instrument: request.instrument, expirationDate: expired ? undefined : request.expiration }, options),
     dependencies.loadYieldCurve(),
   ]), request.signal, CANCELLED);
   if (request.signal?.aborted) throw abortError(CANCELLED);
@@ -125,31 +132,41 @@ export async function loadScenarioMarket(
   if (chain && !symbolMatches(chain.underlyingSymbol, symbol)) {
     warnings.push("Options chain does not match the requested ticker"); chain = null;
   }
-  const expirationDates = [...new Set((chain?.expirationDates ?? []).filter((expiration) =>
-    positive(expiration) && daysToExpiryFrom(expiration, now) > 0))].sort((a, b) => a - b);
+  const expirationDates = liveOptionExpiries(chain?.expirationDates ?? [], now, exchange);
   // A typed date is that day's UTC midnight; the chain's own stamp for the
   // expiry is matched by calendar date, as OMON matches it.
-  const listedExpiration = request.expiration == null ? undefined : findListedExpiry(request.expiration, expirationDates);
+  const listedExpiration = request.expiration == null || expired ? undefined : findListedExpiry(request.expiration, expirationDates);
   const onExpiry = (value: OptionsChain, expiration: number) => [...value.calls, ...value.puts]
     .every((contract) => expiryIsoDate(contract.expiration) === expiryIsoDate(expiration));
-  if (chain && listedExpiration != null && listedExpiration !== request.expiration && !chain.calls.length && !chain.puts.length) {
-    // A source that keys chains by its exact stamp answered the midnight request empty.
-    chainEntry = await abortable(dependencies.loadOptions({ instrument: request.instrument, expirationDate: listedExpiration }, options)
+  // A default chain on the expiry that lapsed at the last close gives way to the nearest live one.
+  const liveDefault = request.expiration == null && chain ? liveDefaultExpiry(chain, now, exchange) : undefined;
+  const reload = liveDefault ?? (chain && listedExpiration != null && listedExpiration !== request.expiration
+    && !chain.calls.length && !chain.puts.length ? listedExpiration : undefined);
+  if (reload != null) {
+    // Or a source that keys chains by its exact stamp answered the midnight request empty.
+    chainEntry = await abortable(dependencies.loadOptions({ instrument: request.instrument, expirationDate: reload }, options)
       .catch((error: unknown) => { warnings.push(`Options chain: ${errorMessage(error)}`); return null; }), request.signal, CANCELLED);
     if (request.signal?.aborted) throw abortError(CANCELLED);
     if (chainEntry?.error) warnings.push(`Options chain: ${chainEntry.error.message}`);
     chain = chainEntry ? resolveEntryValue(chainEntry) : null;
   }
   let missingExpiry: string | undefined;
-  if (chain && request.expiration != null && listedExpiration == null) {
+  if (expired) {
+    missingExpiry = sentence(`expiry ${expiryIsoDate(request.expiration!)} for ${symbol} `
+      + expiredExpiryText(request.expiration!, expirationDates, now, { exchange, flag: "expiration" }));
+    warnings.push(missingExpiry); chain = null;
+  } else if (chain && request.expiration != null && listedExpiration == null) {
     missingExpiry = sentence(missingExpiryText(request.expiration, expirationDates, symbol));
     warnings.push(missingExpiry); chain = null;
-  } else if (chain && listedExpiration != null && !onExpiry(chain, listedExpiration)) {
+  } else if (liveDefault === null) {
+    missingExpiry = `No live expiry listed for ${symbol}`;
+    warnings.push(missingExpiry); chain = null;
+  } else if (chain && (listedExpiration ?? liveDefault) != null && !onExpiry(chain, (listedExpiration ?? liveDefault)!)) {
     warnings.push("Selected expiration unavailable in the returned options chain"); chain = null;
   }
   if (!chain) warnings.push("Options chain unavailable");
   else if (chainEntry?.error || (chainEntry?.staleAt != null && chainEntry.staleAt <= now)) warnings.push("Options chain is stale");
-  const rateExpiration = request.rateExpiration ?? request.expiration ?? expirationDates[0];
+  const rateExpiration = request.rateExpiration ?? (expired ? undefined : request.expiration) ?? expirationDates[0];
   const curve = curveResult.status === "fulfilled" ? curveResult.value : [];
   if (curveResult.status === "rejected") warnings.push(`Treasury: ${errorMessage(curveResult.reason)}`);
   const rate = surfaceTreasuryRate(curve, rateExpiration == null ? NaN : daysToExpiryFrom(rateExpiration, now) / 365);
@@ -225,13 +242,17 @@ function numericSetting(settings: Record<string, unknown>, key: string): number
   return Number(value);
 }
 
-/** Dates are explicit UTC ISO timestamps or UTC calendar dates. Milliseconds are accepted in persisted state. */
+/** Dates are explicit UTC ISO timestamps or UTC calendar dates, written as a date option takes them. Milliseconds are accepted in persisted state. */
 function dateSetting(settings: Record<string, unknown>, key: string): number | undefined {
   const value = settings[key];
   if (!supplied(value)) return undefined;
   if (typeof value === "number" && positive(value) && Number.isFinite(new Date(value).getTime())) return value;
+  const day = typeof value === "string" ? readCalendarDate(value) : null;
+  if (day) return Date.parse(`${day}T00:00:00Z`);
   if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?Z)?$/.test(value)) {
-    throw new Error(`${key} must be YYYY-MM-DD or an ISO timestamp ending in Z`);
+    throw new Error(dateOptionError(String(value), key === "asOf" ? "--as-of" : `--${key}`, {
+      subject: key === "asOf" ? "a valuation date" : "a scenario date", formats: dateOptionFormatsOr("an ISO timestamp ending in Z"),
+    }));
   }
   const date = Date.parse(value);
   if (!positive(date) || new Date(date).toISOString().slice(0, 10) !== value.slice(0, 10)) throw new Error(`${key} is not a valid date`);
@@ -266,6 +287,8 @@ export function scenarioPositionFromSettings(
   const strike = numericSetting(settings, "strike");
   if (strike != null && !(strike > 0)) throw new Error("strike must be positive");
   if (strike != null && !supplied(settings.strategy)) throw new Error("strike picks the strike of --strategy; add --strategy put, csp, vertical or straddle");
+  const delta = putDeltaSetting(settings);
+  if (delta != null && strike != null) throw new Error("delta and strike each pick the put; give one of them");
   const collarStrikes = { put: numericSetting(settings, "putStrike"), call: numericSetting(settings, "callStrike") };
   if ((collarStrikes.put != null || collarStrikes.call != null) && settings.strategy !== "collar") {
     throw new Error("put-strike and call-strike pick a collar's strikes; add --strategy collar");
@@ -288,8 +311,10 @@ export function scenarioPositionFromSettings(
     }
     if (spot == null) throw new Error("A current underlying price or explicit --spot is required");
     // Leg IVs are solved at the market's own spot and time, never at a what-if override.
-    const pricing = market.spot != null && rate != null ? { spot: market.spot, asOf: market.asOf, rate } : null;
-    const seeded = scenarioStrategyLegs(market.chain, spot, settings.strategy, pricing, strike, collarStrikes);
+    const pricing = market.spot != null && rate != null ? { spot: market.spot, asOf: market.asOf, rate, dividendYield: dividendYield ?? 0 } : null;
+    if (delta != null && !pricing) throw new Error("Choosing the put by delta needs the Treasury rate; supply --rate, or pick it with --strike");
+    const seeded = scenarioStrategyLegs(market.chain, spot, settings.strategy, pricing, strike, collarStrikes, delta,
+      unusableChainText(market, exchange));
     legs = seeded.legs;
     shareEntry = market.spot;
     // Mids priced off the parity forward are worth their cost only at the spot
@@ -326,6 +351,19 @@ export function scenarioPositionFromSettings(
   return position;
 }
 
+/**
+ * `--delta`: the put a csp or put seed sells or buys, by the absolute delta it
+ * is nearest (0.30, or -0.30 as a put's own sign reads it); undefined when not set.
+ */
+function putDeltaSetting(settings: Record<string, unknown>): number | undefined {
+  const value = numericSetting(settings, "delta");
+  if (value == null) return undefined;
+  if (settings.strategy !== "csp" && settings.strategy !== "put") throw new Error("delta picks the put of --strategy csp or put");
+  const delta = Math.abs(value);
+  if (!(delta > 0 && delta < 1)) throw new Error(`delta must be a put's delta between 0 and 1, such as 0.30; got ${String(settings.delta)}`);
+  return delta;
+}
+
 /** `--shares`: a signed whole number of shares of the underlying, or undefined when not set. */
 function sharesSetting(settings: Record<string, unknown>): number | undefined {
   const value = settings.shares;
@@ -346,7 +384,7 @@ export const SCENARIO_STRATEGIES = ["vertical", "straddle", "put", "csp", "colla
 type ScenarioStrategy = typeof SCENARIO_STRATEGIES[number];
 const isScenarioStrategy = (value: unknown): value is ScenarioStrategy => SCENARIO_STRATEGIES.includes(value as ScenarioStrategy);
 
-interface StrategyPricing { spot: number; asOf: number; rate: number }
+interface StrategyPricing { spot: number; asOf: number; rate: number; dividendYield: number }
 
 const usableVolatility = (value: unknown): value is number => positive(value) && value <= 5;
 
@@ -357,8 +395,8 @@ interface StrategyParity { forward: number; daysToExpiry: number }
  * at its quote midpoint, so each leg takes the IV that midpoint implies against
  * the expiry's put-call parity forward, with the time left at the market
  * timestamp OSA values at. This holds even when the chain carries a provider
- * IV measured at another time (a same-day IV solved when the chain was served,
- * hours after the after-hours print OSA values at). The forward comes from the
+ * IV measured at another time (a same-day IV solved at the close's quotes,
+ * hours before the after-hours print OSA values at). The forward comes from the
  * same quotes, so a spot that moved after they were taken (an after-hours or
  * pre-market print against the close's chain) does not skew the call against
  * the put. A leg whose midpoint cannot be solved (a spot too far from every
@@ -373,10 +411,12 @@ interface StrategyParity { forward: number; daysToExpiry: number }
  * to the next listed strike up, or a straddle at the anchor. A collar buys
  * the put at `collar.put` and sells the call at `collar.call` on the put's
  * expiry, each the quoted strike nearest 10% out of the money when omitted.
+ * A put or csp seed given a `delta` takes the put whose spot delta, valued at
+ * the IV its own midpoint implies, is nearest that delta's negative.
  */
 function scenarioStrategyLegs(
   chain: OptionsChain, spot: number, strategy: ScenarioStrategy, pricing: StrategyPricing | null, strike?: number,
-  collar: { put?: number; call?: number } = {},
+  collar: { put?: number; call?: number } = {}, delta?: number, unusable: UnusableChainText = defaultUnusableChainText,
 ): { legs: ScenarioLeg[]; parity: StrategyParity | null } {
   const parity = new Map<number, StrategyParity | null>();
   const parityFor = (expiration: number) => {
@@ -406,15 +446,16 @@ function scenarioStrategyLegs(
   const calls = quoted(chain.calls, "call").sort(nearest);
   const puts = quoted(chain.puts, "put").sort(nearest);
   const missing = (candidates: { contract: { strike: number } }[], at = strike, what: string = strategy === "csp" ? "put to sell" : strategy) => {
-    if (at == null) return new Error("The selected chain has no complete quoted strategy with usable IV");
+    if (at == null) return new Error(unusable("strategy"));
     const listed = [...new Set(candidates.map(({ contract }) => contract.strike))]
       .sort((a, b) => Math.abs(a - at) - Math.abs(b - at)).slice(0, 4).sort((a, b) => a - b);
-    return new Error(`The selected chain has no complete quoted ${what} at strike ${at} with usable IV`
-      + (listed.length ? `; nearest quoted strikes: ${listed.join(", ")}` : ""));
+    // Another strike on this expiry is the nearer fix; with none quoted, the next expiry is.
+    return new Error(listed.length ? `${unusable(`${what} at strike ${at}`, false)}; nearest quoted strikes: ${listed.join(", ")}`
+      : unusable(`${what} at strike ${at}`));
   };
-  if (strategy === "collar") return collarLegs(calls, puts, spot, collar, missing, parityFor);
+  if (strategy === "collar") return collarLegs(calls, puts, spot, collar, missing, parityFor, unusable);
   if (strategy === "put" || strategy === "csp") {
-    const put = puts.find(anchored);
+    const put = delta == null ? puts.find(anchored) : nearestDelta(puts, -delta, spot, pricing, parityFor);
     if (!put) throw missing(puts);
     return { legs: [{ id: put.contract.contractSymbol, side: "put", quantity: strategy === "csp" ? -1 : 1, strike: put.contract.strike,
       expiration: put.contract.expiration, price: put.mid, priceSource: "mid", volatility: put.volatility, multiplier: 100,
@@ -441,6 +482,60 @@ function scenarioStrategyLegs(
 
 interface QuotedContract { contract: OptionsChain["calls"][number]; mid: number; volatility: number; solved: boolean }
 
+/** Why a chain seeds nothing: `what` it has no usable quote for, then the next live expiry to try unless `next` is false. */
+type UnusableChainText = (what: string, next?: boolean) => string;
+const defaultUnusableChainText: UnusableChainText = (what) => `The selected chain has no complete quoted ${what} with usable IV`;
+
+/**
+ * The seed failure naming the expiry the chain is on and the next live one to
+ * ask for: `The 30 Oct chain has no complete quoted strategy with usable IV;
+ * try the next expiry, 6 Nov (--expiration 2026-11-06)`.
+ */
+function unusableChainText(market: ScenarioMarketSnapshot, exchange: string | undefined): UnusableChainText {
+  const contracts = market.chain ? [...market.chain.calls, ...market.chain.puts] : [];
+  const tried = contracts[0]?.expiration;
+  if (tried == null) return defaultUnusableChainText;
+  const now = market.asOf;
+  const next = nextLiveExpiry(tried, market.expirationDates, now, exchange ?? market.exchange);
+  return (what, withNext = true) => `The ${expiryDayLabel(tried, now)} chain has no complete quoted ${what} with usable IV`
+    + (withNext && next != null ? `; try the next expiry, ${expiryChoiceText(next, now, "expiration")}` : "");
+}
+
+/**
+ * A put's spot delta at the IV it trades at: against the parity forward its
+ * IV was solved on when it was (forward delta, carried to spot), else at the
+ * seed's spot. Null when it cannot be valued.
+ */
+function quotedPutDelta(quoted: QuotedContract, spot: number, pricing: StrategyPricing | null, parity: StrategyParity | null): number | null {
+  const { contract, volatility, solved } = quoted;
+  if (!pricing) return null;
+  if (solved && parity) {
+    // On the forward, with the dividend yield set to the rate so it carries no drift, as the IV was solved.
+    const forwardDelta = valueOption({ side: "put", spot: parity.forward, strike: contract.strike, daysToExpiry: parity.daysToExpiry,
+      rate: pricing.rate, dividendYield: pricing.rate, volatility }).delta;
+    return Number.isFinite(forwardDelta) ? forwardDelta * Math.exp((pricing.rate - pricing.dividendYield) * parity.daysToExpiry / 365) : null;
+  }
+  const years = daysToExpiryFrom(contract.expiration, pricing.asOf) / 365;
+  return optionDelta({ spot, years, volatility, rate: pricing.rate, dividendYield: pricing.dividendYield }, contract.strike, "put");
+}
+
+/** The put whose delta is nearest `target` (negative, as a put's delta reads), the lower strike on a tie; null when none can be valued. */
+function nearestDelta(
+  puts: readonly QuotedContract[], target: number, spot: number, pricing: StrategyPricing | null,
+  parityFor: (expiration: number) => StrategyParity | null,
+): QuotedContract | null {
+  let best: { put: QuotedContract; distance: number } | null = null;
+  for (const put of puts) {
+    const delta = quotedPutDelta(put, spot, pricing, put.solved ? parityFor(put.contract.expiration) : null);
+    if (delta == null) continue;
+    const distance = Math.abs(delta - target);
+    if (!best || distance < best.distance - 1e-12 || (Math.abs(distance - best.distance) <= 1e-12 && put.contract.strike < best.put.contract.strike)) {
+      best = { put, distance };
+    }
+  }
+  return best?.put ?? null;
+}
+
 /** How far out of the money a collar's put and call sit when their strikes are not given. */
 const COLLAR_DEFAULT_DISTANCE = 0.1;
 
@@ -448,18 +543,18 @@ const COLLAR_DEFAULT_DISTANCE = 0.1;
 function collarLegs(
   calls: QuotedContract[], puts: QuotedContract[], spot: number, strikes: { put?: number; call?: number },
   missing: (candidates: QuotedContract[], at: number | undefined, what: string) => Error,
-  parityFor: (expiration: number) => StrategyParity | null,
+  parityFor: (expiration: number) => StrategyParity | null, unusable: UnusableChainText,
 ): { legs: ScenarioLeg[]; parity: StrategyParity | null } {
   const closest = (candidates: QuotedContract[], target: number) => candidates.toSorted((a, b) =>
     Math.abs(a.contract.strike - target) - Math.abs(b.contract.strike - target) || a.contract.strike - b.contract.strike);
   const at = (candidates: QuotedContract[], value: number) => candidates.filter(({ contract }) => Math.abs(contract.strike - value) < 1e-9);
   const put = strikes.put != null ? at(puts, strikes.put)[0]
     : closest(puts.filter(({ contract }) => strikes.call == null || contract.strike < strikes.call), spot * (1 - COLLAR_DEFAULT_DISTANCE))[0];
-  if (!put) throw strikes.put != null ? missing(puts, strikes.put, "put to buy") : new Error("The selected chain has no complete quoted put to buy with usable IV");
+  if (!put) throw strikes.put != null ? missing(puts, strikes.put, "put to buy") : new Error(unusable("put to buy"));
   const sameExpiry = calls.filter(({ contract }) => contract.expiration === put.contract.expiration);
   const call = strikes.call != null ? at(sameExpiry, strikes.call)[0]
     : closest(sameExpiry.filter(({ contract }) => contract.strike > put.contract.strike), spot * (1 + COLLAR_DEFAULT_DISTANCE))[0];
-  if (!call) throw strikes.call != null ? missing(sameExpiry, strikes.call, "call to sell") : new Error("The selected chain has no complete quoted call to sell above the put with usable IV");
+  if (!call) throw strikes.call != null ? missing(sameExpiry, strikes.call, "call to sell") : new Error(unusable("call to sell above the put"));
   if (call.contract.strike <= put.contract.strike) throw new Error("A collar's put strike must be below its call strike");
   if (put.contract.currency !== call.contract.currency) throw new Error("Strategy quote currencies differ");
   const legs = [[put, "put", 1], [call, "call", -1]] as const;

package/src/plugins/builtin/options-scenario/collar.ts

@@ -1,7 +1,7 @@
 import type { StatItem } from "../../../components";
 import type { HeadlessPaneEntry } from "../../../types/headless";
 import { formatHedgePrice } from "./hedge";
-import { UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
+import { amountUnit, UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
 
 /**
  * A collar (docs/research-data.md#collar): one long put and one short call on
@@ -104,17 +104,19 @@ function boundText(collar: Collar, value: number | null, side: "put" | "call"):
 export function collarReportEntries(collar: Collar): HeadlessPaneEntry[] {
   const unit = unitOf(collar);
   const premium = Math.abs(collar.netPremium);
+  // Every figure is per share, so an export writes the number with that unit.
+  const perShare = { unit: `${amountUnit(collar.currency)} per share` };
   return [
-    { key: "putBought", label: "Put bought", value: collar.put.price,
+    { key: "putBought", label: "Put bought", value: collar.put.price, ...perShare,
       formatted: `${strikeText(collar.put.strike)} put at ${formatHedgePrice(collar.put.price)} per share (${priceWord(collar.put)})` },
-    { key: "callSold", label: "Call sold", value: collar.call.price,
+    { key: "callSold", label: "Call sold", value: collar.call.price, ...perShare,
       formatted: `${strikeText(collar.call.strike)} call at ${formatHedgePrice(collar.call.price)} per share (${priceWord(collar.call)})` },
-    { key: "netPremium", label: "Net premium", value: collar.netPremium,
+    { key: "netPremium", label: "Net premium", value: collar.netPremium, ...perShare,
       formatted: collar.netPremium === 0 ? `0.00 per share (zero cost)`
         : `${formatHedgePrice(premium)} per share ${premiumWord(collar)} (${money(Math.abs(collar.netPremiumTotal))}${unit} `
           + `for ${collar.contracts.toLocaleString("en-US")} ${collar.contracts === 1 ? "contract" : "contracts"} each)` },
-    { key: "floor", label: "Floor", value: collar.floor, formatted: boundText(collar, collar.floor, "put") },
-    { key: "cap", label: "Cap", value: collar.cap, formatted: boundText(collar, collar.cap, "call") },
+    { key: "floor", label: "Floor", value: collar.floor, ...perShare, formatted: boundText(collar, collar.floor, "put") },
+    { key: "cap", label: "Cap", value: collar.cap, ...perShare, formatted: boundText(collar, collar.cap, "call") },
   ];
 }
 

package/src/plugins/builtin/options-scenario/csp-screen-headless.ts

@@ -0,0 +1,127 @@
+import type { HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/plugin";
+import { expirationOptionSeconds, OPTION_EXPIRATION_FORMAT, OPTION_EXPIRATION_PLACEHOLDER } from "../../../utils/option-expiry";
+import { resolveHeadlessInstrument } from "../shared/headless-market-data";
+import { createScenarioDependencies } from "./client";
+import { formatHedgePrice } from "./hedge";
+import { exportPercent } from "./model";
+import {
+  CSP_SCREEN_DEFAULTS, CSP_SCREEN_LIMIT, cspEarningsText, cspScreenCriteriaText, loadCspScreen, readCspScreenCriteria,
+  type CspScreen, type CspScreenRow,
+} from "./csp-screen";
+
+const percentCell = (digits: number) => (value: unknown) => typeof value === "number" ? `${value.toFixed(digits)}%` : "--";
+const priceCell = (value: unknown) => typeof value === "number" ? formatHedgePrice(value) : "--";
+const strikeCell = (value: unknown) => typeof value === "number" ? String(value) : "--";
+
+/** One name's row, flat, every percent in percent. */
+export type CspScreenReportRow = {
+  rank: number | null; symbol: string; expiry: string | null; days: number | null; strike: number | null;
+  bid: number | null; ask: number | null; spread: number | null; wide: boolean | null; delta: number | null; otm: number | null;
+  midYield: number | null; bidYield: number | null; ivRank: number | null;
+  earnings: string; earningsBeforeExpiry: boolean | null; earningsDate: string | null; spot: number | null; note: string | null;
+};
+
+export function cspScreenReportRow(row: CspScreenRow): CspScreenReportRow {
+  const { csp } = row;
+  return {
+    rank: row.rank, symbol: row.symbol,
+    expiry: csp?.expiry ?? null, days: csp?.daysToExpiry ?? null, strike: csp?.strike ?? null,
+    bid: csp?.quote?.bid ?? null, ask: csp?.quote?.ask ?? null, spread: exportPercent(csp?.quote?.spreadOfMid), wide: csp?.quote ? row.wideSpread : null,
+    delta: row.delta, otm: exportPercent(csp?.outOfTheMoney), midYield: exportPercent(csp?.annualizedYield),
+    bidYield: exportPercent(csp?.quote?.bidAnnualizedYield), ivRank: row.ivRank,
+    earnings: cspEarningsText(csp), earningsBeforeExpiry: csp ? csp.earnings.beforeExpiry : null, earningsDate: csp?.earnings.date ?? null,
+    spot: csp?.spot ?? null, note: row.note,
+  };
+}
+
+const COLUMNS: HeadlessPaneColumn[] = [
+  { key: "rank", header: "#", align: "right", format: (value) => typeof value === "number" ? String(value) : "" },
+  { key: "symbol", header: "Symbol" },
+  { key: "expiry", header: "Expiry" },
+  { key: "days", header: "DTE", align: "right" },
+  { key: "strike", header: "Strike", align: "right", format: strikeCell },
+  { key: "bid", header: "Bid", align: "right", format: priceCell },
+  { key: "ask", header: "Ask", align: "right", format: priceCell },
+  // The text view marks a wide spread in its cell; exports keep the number and say so in Wide.
+  { key: "spread", header: "Spread", align: "right", format: percentCell(1),
+    textFormat: (value, row) => `${percentCell(1)(value)}${row.wide ? " wide" : ""}` },
+  { key: "delta", header: "Delta", align: "right", format: (value) => typeof value === "number" ? value.toFixed(2) : "--" },
+  { key: "otm", header: "OTM", align: "right", format: percentCell(1) },
+  { key: "midYield", header: "Mid yield/yr", align: "right", format: percentCell(2) },
+  { key: "bidYield", header: "Bid yield/yr", align: "right", format: percentCell(2) },
+  { key: "ivRank", header: "IVR", align: "right", format: (value) => typeof value === "number" ? value.toFixed(0) : "--" },
+  { key: "earnings", header: "Earnings" },
+];
+const NOTE: HeadlessPaneColumn = { key: "note", header: "Note", underRow: true };
+const EXPORT_ONLY: HeadlessPaneColumn[] = [
+  { key: "wide", header: "Wide spread", format: (value) => value === true ? "yes" : value === false ? "no" : "" },
+  { key: "earningsBeforeExpiry", header: "Earnings before expiry", format: (value) => value === true ? "yes" : value === false ? "no" : "unknown" },
+  { key: "earningsDate", header: "Earnings date" },
+  { key: "spot", header: "Spot", format: priceCell },
+];
+
+/** `A`, `A and B`, `A, B and C`. */
+const listText = (items: readonly string[]) => items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+
+/**
+ * The ranking basis and the wide flag's limit, then the names IV history has no
+ * rank for: those with a reason say it (`No IV rank: BBB (fewer than 120
+ * sessions).`), and a bare symbol, which has none to give, is just not ranked
+ * yet (`No IV rank for DAL yet.`).
+ */
+export function cspScreenNotes(screen: Pick<CspScreen, "criteria" | "missingRanks">): string[] {
+  const reasoned = screen.missingRanks.filter((entry) => entry.includes(" "));
+  const bare = screen.missingRanks.filter((entry) => !entry.includes(" "));
+  return [
+    `Ranked by annualised yield at the bid. Wide is a spread over ${screen.criteria.maxSpreadPercent}% of the mid (--max-spread).`,
+    ...(reasoned.length ? [`No IV rank: ${reasoned.join(", ")}.`] : []),
+    ...(bare.length ? [`No IV rank for ${listText(bare)} yet.`] : []),
+  ];
+}
+
+export const cspScreenHeadless: HeadlessPaneDefinition<"rows"> = {
+  shape: "rows",
+  argument: { kind: "tickers", maximum: CSP_SCREEN_LIMIT, description: "US option underlyings to rank" },
+  usListingsOnly: "Options data",
+  failsWithoutData: true,
+  description: "Cash-secured puts across a list, ranked by annualised yield on cash at the bid: for each name, the put nearest a delta "
+    + "(0.30) on the listed expiry nearest a date or a number of days out (30), with its strike, bid, ask, spread (flagged wide over "
+    + "--max-spread, never left out), delta, distance out of the money, yield at the mid and at the bid, IV rank and whether earnings fall before expiry.",
+  discovery: { screenshotReadiness: "live-dom", dataRequirements: ["Current option chains", "Cloud stored implied volatility", "Earnings calendar"],
+    limitations: ["Assignment, margin and the interest the cash earns are not modelled."] },
+  describe: (_args, result) => {
+    const criteria = (result?.metadata as { criteria?: CspScreen["criteria"] } | undefined)?.criteria;
+    return ["Cash-secured puts", ...(criteria ? [cspScreenCriteriaText(criteria, Date.now())] : [])].join(" · ");
+  },
+  options: [
+    { key: "delta", type: "string", placeholder: "0.30", example: "--delta 0.20",
+      description: `Each name's put is the one whose delta is nearest this, as a put's delta reads without its sign. Default ${CSP_SCREEN_DEFAULTS.delta.toFixed(2)}` },
+    { key: "days", type: "string", placeholder: "days", example: "--days 45",
+      description: `Each name's expiry is its listed one nearest this many calendar days out. Default ${CSP_SCREEN_DEFAULTS.days}` },
+    { key: "expiration", type: "string", placeholder: OPTION_EXPIRATION_PLACEHOLDER, example: "--expiration 2026-11-20",
+      description: `Each name's expiry is its listed one nearest this date, in place of --days, as ${OPTION_EXPIRATION_FORMAT}`,
+      normalize: (value) => expirationOptionSeconds(value) },
+    { key: "maxSpread", aliases: ["max-spread"], type: "string", placeholder: "percent", example: "--max-spread 15",
+      description: `A put whose bid/ask spread is over this percent of its mid is marked wide; it is still ranked. Default ${CSP_SCREEN_DEFAULTS.maxSpreadPercent}` },
+  ],
+  async load(args, ctx) {
+    const criteria = readCspScreenCriteria(args.options);
+    const instruments = await Promise.all(args.symbols.map((symbol) => resolveHeadlessInstrument(ctx, symbol)));
+    const screen = await loadCspScreen(instruments, criteria, {
+      scenario: createScenarioDependencies(ctx.marketData, ctx.apiClient), earnings: ctx.marketData, ivApi: ctx.apiClient,
+    }, ctx.signal);
+    const unavailable = screen.rows.filter((row) => !row.csp);
+    return {
+      freshness: screen.freshness,
+      columns: [...COLUMNS, ...EXPORT_ONLY, NOTE],
+      textColumns: [...COLUMNS, NOTE],
+      rows: screen.rows.map(cspScreenReportRow),
+      complete: unavailable.length === 0 && !screen.ivRankError,
+      unavailableSymbols: unavailable.map((row) => row.symbol),
+      errors: screen.ivRankError ? [`IV rank unavailable: ${screen.ivRankError}`] : [],
+      notes: cspScreenNotes(screen),
+      metadata: { criteria: screen.criteria, rankedBy: "annualized yield on cash at the bid", unit: "percent; prices per share",
+        methodology: "docs/research-data.md#cash-secured-put-screen" },
+    };
+  },
+};

package/src/plugins/builtin/options-scenario/csp-screen-pane.tsx

@@ -0,0 +1,165 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { DataTableView, PaneStatusBody, QueryBar, usePaneFooter, usePaneNoticeFooter, type DataTableColumn, type DataTableKeyEvent } from "../../../components";
+import { useAsyncResource } from "../../../react/async-resource";
+import { useAutoRefresh } from "../../../react/auto-refresh";
+import { usePaneSettingValue, usePluginAppActions } from "../../../public/react";
+import { useThemeColors } from "../../../theme/theme-context";
+import type { PaneProps } from "../../../types/plugin";
+import { Box } from "../../../ui";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
+import { compareSortValues, nextHeaderSort, type SortDirection } from "../../../utils/sort-values";
+import { useAssetData } from "../../runtime";
+import { createScenarioDependencies } from "./client";
+import { cspScreenNotes, cspScreenReportRow, type CspScreenReportRow } from "./csp-screen-headless";
+import { CSP_SCREEN_DEFAULTS, CSP_SCREEN_LIMIT, cspScreenCriteriaText, cspTargetDate, loadCspScreen, readCspScreenCriteria, type CspScreenRow } from "./csp-screen";
+import { formatHedgePrice } from "./hedge";
+
+type ScreenRow = CspScreenReportRow & { source: CspScreenRow };
+
+const COLUMNS: DataTableColumn[] = [
+  { id: "rank", label: "#", width: 3, align: "right" },
+  { id: "symbol", label: "Symbol", width: 7, align: "left" },
+  { id: "expiry", label: "Expiry", width: 10, align: "right" },
+  { id: "days", label: "DTE", width: 4, align: "right" },
+  { id: "strike", label: "Strike", width: 8, align: "right" },
+  { id: "bid", label: "Bid", width: 7, align: "right" },
+  { id: "ask", label: "Ask", width: 7, align: "right" },
+  { id: "spread", label: "Spread", width: 11, align: "right" },
+  { id: "delta", label: "Delta", width: 6, align: "right" },
+  { id: "otm", label: "OTM", width: 6, align: "right" },
+  { id: "midYield", label: "Mid yield/yr", width: 12, align: "right" },
+  { id: "bidYield", label: "Bid yield/yr", width: 12, align: "right" },
+  { id: "ivRank", label: "IVR", width: 4, align: "right" },
+  { id: "earnings", label: "Earnings", width: 17, align: "left" },
+];
+
+const DELTA_OPTIONS = ["0.10", "0.15", "0.20", "0.25", "0.30", "0.35", "0.40", "0.50"];
+const DAYS_OPTIONS = ["7", "14", "21", "30", "45", "60", "90"];
+const SYMBOLS_FIELD_WIDTH = 24;
+/** Symbols apply once typing pauses, so a half-typed ticker does not start a screen. */
+const SYMBOLS_DEBOUNCE_MS = 700;
+
+const symbolList = (text: string) => [...new Set(text.split(/[\s,;]+/).map((symbol) => symbol.trim().toUpperCase()).filter(Boolean))];
+const percentText = (value: unknown, digits: number) => typeof value === "number" ? `${value.toFixed(digits)}%` : "--";
+const priceText = (value: unknown) => typeof value === "number" ? formatHedgePrice(value) : "--";
+/** A column's value to sort on: earnings by date, a flag as a number. */
+function sortValue(row: CspScreenReportRow, columnId: string): string | number | null {
+  if (columnId === "earnings") return row.earningsDate;
+  const value = row[columnId as keyof CspScreenReportRow];
+  return typeof value === "boolean" ? Number(value) : value;
+}
+/** A select's options with the current value kept when it is not a preset (a delta typed on the command line). */
+const withCurrent = (presets: readonly string[], current: string, label: (value: string) => string) =>
+  [...new Set([...presets, current])].sort((a, b) => Number(a) - Number(b)).map((value) => ({ value, label: label(value) }));
+
+export function CspScreenPane({ width, height, focused }: PaneProps) {
+  const colors = useThemeColors();
+  const [symbolsText, setSymbolsText] = usePaneSettingValue<string>("symbols", "");
+  const [delta, setDelta] = usePaneSettingValue<string | number>("delta", "");
+  const [days, setDays] = usePaneSettingValue<string | number>("days", "");
+  const [expiration, setExpiration] = usePaneSettingValue<string | number>("expiration", "");
+  const [maxSpread] = usePaneSettingValue<string | number>("maxSpread", "");
+  const [symbolsActive, setSymbolsActive] = useState(false);
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const assetData = useAssetData();
+  const typed = useMemo(() => symbolList(String(symbolsText ?? "")), [symbolsText]);
+  // The screen reads the first names it can rank; the footer names the rest.
+  const symbols = useMemo(() => typed.slice(0, CSP_SCREEN_LIMIT), [typed]);
+  const leftOut = typed.slice(CSP_SCREEN_LIMIT);
+  const criteria = useMemo(() => {
+    try { return { value: readCspScreenCriteria({ delta, days, expiration, maxSpread }), error: null }; }
+    catch (error) { return { value: null, error: error instanceof Error ? error.message : String(error) }; }
+  }, [delta, days, expiration, maxSpread]);
+  const controller = useRef<AbortController | null>(null);
+  const key = JSON.stringify([symbols, criteria.value]);
+  const loader = useCallback(async () => {
+    controller.current?.abort();
+    const current = new AbortController();
+    controller.current = current;
+    return loadCspScreen(symbols.map((symbol) => parsePublicTickerKey(symbol)), criteria.value!,
+      { scenario: createScenarioDependencies(), earnings: assetData }, current.signal);
+  }, [key, assetData]);
+  const resource = useAsyncResource(symbols.length && criteria.value ? loader : null);
+  useEffect(() => () => controller.current?.abort(), [loader]);
+  useAutoRefresh(resource.updatedAt, resource.load);
+  const [sort, setSort] = useState<{ columnId: string; direction: SortDirection }>({ columnId: "rank", direction: "asc" });
+  const rows = useMemo<ScreenRow[]>(() => {
+    const flat = (resource.data?.rows ?? []).map((row) => ({ ...cspScreenReportRow(row), source: row }));
+    // Unranked names stay under the ranked ones whichever way rank sorts.
+    return flat.sort((left, right) => sort.columnId === "rank"
+      ? compareSortValues(left.rank ?? Number.POSITIVE_INFINITY, right.rank ?? Number.POSITIVE_INFINITY, sort.direction)
+      : compareSortValues(sortValue(left, sort.columnId), sortValue(right, sort.columnId), sort.direction));
+  }, [resource.data, sort]);
+  const [selected, setSelected] = useState<string | null>(null);
+  const screen = resource.data;
+  const notices = [criteria.error, resource.data ? null : resource.error,
+    leftOut.length ? `Ranks the first ${CSP_SCREEN_LIMIT} symbols; ${leftOut.length} left out: ${leftOut.join(", ")}` : null,
+    ...(screen?.ivRankError ? [`IV rank unavailable: ${screen.ivRankError}`] : []),
+    ...(screen?.rows ?? []).flatMap((row) => row.note ? [`${row.symbol}: ${row.note}`] : []),
+    ...(screen ? cspScreenNotes(screen).slice(1) : [])].filter((value): value is string => !!value);
+  usePaneNoticeFooter({ registrationId: "csp-screen-notices", notices, focused });
+  // The bar names the delta and the expiry; the footer says only what changes.
+  usePaneFooter("csp-screen", () => ({ info: [
+    ...(resource.loading ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }] : []),
+  ] }), [resource.loading]);
+  const criteriaText = criteria.value ? cspScreenCriteriaText(criteria.value, Date.now()) : "";
+  // Enter opens the name's put in OSA, at the strike and expiry the screen read.
+  const openScenario = (row: ScreenRow) => {
+    const csp = row.source.csp;
+    if (!csp) return;
+    createPaneFromTemplate("options-scenario-pane", { symbol: row.symbol, values: { strategy: "csp", strike: String(csp.strike), expiration: csp.expiry } });
+  };
+  const handleKey = (event: DataTableKeyEvent): boolean => {
+    if (event.ctrl || event.alt || event.meta || event.name !== "r") return false;
+    void resource.reload();
+    event.preventDefault?.(); event.stopPropagation?.(); return true;
+  };
+  const cell = (row: ScreenRow, id: string): { text: string; color?: string } => {
+    switch (id) {
+      case "rank": return { text: row.rank == null ? "" : String(row.rank), color: colors.textDim };
+      case "symbol": return { text: row.symbol, color: colors.textBright };
+      case "expiry": return { text: String(row.expiry ?? "--"), color: colors.textDim };
+      case "days": return { text: row.days == null ? "--" : String(row.days) };
+      case "strike": return { text: row.strike == null ? "--" : String(row.strike) };
+      case "bid": return { text: priceText(row.bid) };
+      case "ask": return { text: priceText(row.ask) };
+      case "spread": return { text: `${percentText(row.spread, 1)}${row.wide ? " wide" : ""}`, color: row.wide ? colors.warning : undefined };
+      case "delta": return { text: typeof row.delta === "number" ? row.delta.toFixed(2) : "--" };
+      case "otm": return { text: percentText(row.otm, 1) };
+      case "midYield": return { text: percentText(row.midYield, 2), color: colors.textDim };
+      case "bidYield": return { text: percentText(row.bidYield, 2), color: colors.positive };
+      case "ivRank": return { text: typeof row.ivRank === "number" ? row.ivRank.toFixed(0) : "--" };
+      case "earnings": return { text: String(row.earnings), color: row.earningsBeforeExpiry === true ? colors.warning : colors.textDim };
+      default: return { text: "" };
+    }
+  };
+  const deltaValue = criteria.value ? criteria.value.delta.toFixed(2) : CSP_SCREEN_DEFAULTS.delta.toFixed(2);
+  const daysValue = String(criteria.value?.days ?? CSP_SCREEN_DEFAULTS.days);
+  // A date typed on the command line is the expiry's choice until a number of days is picked.
+  const typedDate = criteria.value?.expiration != null ? cspTargetDate(criteria.value, Date.now()) : null;
+  return <Box width={width} height={height} flexDirection="column" overflow="hidden">
+    <QueryBar width={width} filters={[
+      { id: "symbols", kind: "text" as const, label: "Symbols", value: String(symbolsText ?? ""), placeholder: "JPM, GS, KO",
+        width: SYMBOLS_FIELD_WIDTH, debounceMs: SYMBOLS_DEBOUNCE_MS, focused, active: symbolsActive, onActiveChange: setSymbolsActive,
+        onChange: setSymbolsText },
+      { id: "delta", label: "Delta", value: deltaValue, defaultValue: CSP_SCREEN_DEFAULTS.delta.toFixed(2),
+        options: withCurrent(DELTA_OPTIONS, deltaValue, (value) => value), onChange: (value: string) => setDelta(value) },
+      { id: "expiry", label: "Expiry", value: typedDate ?? daysValue, defaultValue: String(CSP_SCREEN_DEFAULTS.days),
+        options: [...withCurrent(DAYS_OPTIONS, daysValue, (value) => `${value} days`), ...(typedDate ? [{ value: typedDate, label: typedDate }] : [])],
+        onChange: (value: string) => { if (value === typedDate) return; setExpiration(""); setDays(value); } },
+    ]} />
+    <PaneStatusBody subject="cash-secured puts" loading={resource.loading && !resource.data}
+      error={criteria.error && !criteria.value ? criteria.error : !resource.data ? resource.error : null}>
+      <DataTableView<ScreenRow> focused={focused && !symbolsActive} columns={COLUMNS} items={rows} rootWidth={width}
+        rootHeight={Math.max(2, height - 1)}
+        getItemKey={(row) => row.symbol} sortColumnId={sort.columnId} sortDirection={sort.direction}
+        emptyStateTitle={symbols.length ? "No puts to rank." : "Type symbols to rank their cash-secured puts."}
+        onHeaderClick={(id) => setSort((current) => nextHeaderSort(current, id, { firstDirection: id === "rank" || id === "symbol" ? "asc" : "desc" }))}
+        selection={{ kind: "id", selectedId: selected ?? rows[0]?.symbol ?? "", getId: (row) => row.symbol, onChange: (id) => setSelected(id) }}
+        onActivate={openScenario} onRootKeyDown={handleKey}
+        getExportMetadata={() => [["puts", criteriaText || undefined], ["ranked by", "annualised yield on cash at the bid"],
+          ["wide", criteria.value ? `spread over ${criteria.value.maxSpreadPercent}% of the mid` : undefined]]}
+        renderCell={(row, column) => cell(row, column.id)} />
+    </PaneStatusBody>
+  </Box>;
+}