gloomberb 0.18.2 → 0.18.4

package/src/plugins/builtin/options-positioning/pane.tsx

@@ -57,6 +57,7 @@ import {
   formatDistance,
   formatGamma,
   formatLevel,
+  positioningSpotDetail,
   formatPayout,
   formatRatio,
   formatStrike,
@@ -204,6 +205,7 @@ function OptionsPositioningView({ width, height, focused, symbol }: PaneProps &
   const openInterest = useAsyncResource<OpenInterestPayload>(openInterestLoader, { keepPreviousData: true });
   const data = openInterest.data;
   const spot = data?.spot ?? null;
+  const spotStamp = useMemo(() => positioningSpotDetail(spot, data?.spotAsOf), [spot, data?.spotAsOf]);
   const expiries = data?.expiries ?? [];
   const shownExpiry = data?.expiry ?? requestedExpiry;
   const changes = data?.previousOiDate != null;
@@ -264,9 +266,7 @@ function OptionsPositioningView({ width, height, focused, symbol }: PaneProps &
       enabled: expiryIndex < expiryDates.length - 1, onSelect: () => stepExpiry(1) },
   ], [expiryDates.length, expiryIndex, stepExpiry, tab]);
 
-  const { strip: tabStrip, rows: tabRows } = usePaneTabs(data?.expiries.length
-    ? { tabs, activeValue: tab, onSelect: (value: string) => setTab(value), focused, dense: true }
-    : null);
+  const { strip: tabStrip, rows: tabRows } = usePaneTabs({ tabs, activeValue: tab, onSelect: (value: string) => setTab(value), focused, dense: true });
   const bodyHeight = Math.max(3, height - tabRows);
 
   // Footer: what the data is (delayed or real time, the OI session), and its gaps.
@@ -335,13 +335,13 @@ function OptionsPositioningView({ width, height, focused, symbol }: PaneProps &
   const strikeFigures = useMemo<StatItem[]>(() => !callTotal ? [] : [
     { id: "max-pain", label: "Max pain", value: maxPain == null ? "--" : formatStrike(maxPain), color: colors.warning,
       detail: maxPain == null ? undefined : `${formatDistance(maxPain, spot)} vs spot` },
-    { id: "spot", label: "Spot", value: formatLevel(spot) },
+    { id: "spot", label: "Spot", value: formatLevel(spot), ...spotStamp },
     { id: "pc", label: "P/C OI", value: formatRatio(callTotal.putCallRatio) },
     { id: "calls", label: "Call OI", value: formatCompact(callTotal.callOI), color: colors.positive,
       detail: callTotal.callChange == null ? undefined : formatCountChange(callTotal.callChange) },
     { id: "puts", label: "Put OI", value: formatCompact(callTotal.putOI), color: colors.negative,
       detail: callTotal.putChange == null ? undefined : formatCountChange(callTotal.putChange) },
-  ], [callTotal, colors.negative, colors.positive, colors.warning, maxPain, spot]);
+  ], [callTotal, colors.negative, colors.positive, colors.warning, maxPain, spot, spotStamp]);
   const selectedStrikeRow = strikes.find((row) => strikeKey(row) === strikeSelectedId) ?? null;
   const strikeStrip = useMemo<ChartStripSpec | null>(() => strikeWindow.length < 3 ? null : {
     label: "Open interest by strike",
@@ -404,9 +404,9 @@ function OptionsPositioningView({ width, height, focused, symbol }: PaneProps &
         split: [{ id: "calls", value: calls, color: colors.positive }, { id: "puts", value: puts, color: colors.negative }] },
       { id: "pc", label: "P/C OI", value: formatRatio(calls > 0 ? puts / calls : null) },
       { id: "largest", label: "Largest expiry", value: expiryLabel(largest.date), detail: formatCompact(expirySize(largest)) },
-      { id: "spot", label: "Spot", value: formatLevel(spot) },
+      { id: "spot", label: "Spot", value: formatLevel(spot), ...spotStamp },
     ];
-  }, [changes, colors.negative, colors.positive, expiries, spot]);
+  }, [changes, colors.negative, colors.positive, expiries, spot, spotStamp]);
   const selectedExpiryRow = expiries.find((row) => row.date === expirySelectedId) ?? null;
   const expiryStrip = useMemo<ChartStripSpec | null>(() => expiries.length < 3 ? null : {
     label: "Open interest by expiry",
@@ -479,7 +479,7 @@ function OptionsPositioningView({ width, height, focused, symbol }: PaneProps &
     })),
     ...(band ? [{ id: "band", label: "Dealer range", value: `${formatGamma(band.low)} to ${formatGamma(band.high)}`,
       detail: `${shares} with dealers${gammaData.boxes?.length ? ", boxes out" : ""}` }] : []),
-    { id: "spot", label: "Spot", value: formatLevel(gammaSpot) },
+    { id: "spot", label: "Spot", value: formatLevel(gammaSpot), ...positioningSpotDetail(gammaSpot, gammaData.spotAsOf) },
   ], [band, colors.negative, colors.positive, gammaData, gammaSpot, shares, walls]);
   // The assumption rides in the legend, where the numbers it changes are read; the
   // dealer range figure names its own share. It gives way before the series name does.
@@ -610,13 +610,11 @@ function OptionsPositioningView({ width, height, focused, symbol }: PaneProps &
   }
 
   return <Box width={width} height={height} flexDirection="column">
+    {tabStrip}
     <PaneStatusBody loading={openInterest.loading && !data} error={!data ? openInterest.error : null}
       empty={!!data && !data.expiries.length} subject="open interest"
       emptyTitle={`No listed options for ${parsePublicTickerKey(symbol).symbol.replace(/^\^/, "")}.`}>
-      {data?.expiries.length ? <>
-        {tabStrip}
-        {content}
-      </> : null}
+      {data?.expiries.length ? content : null}
     </PaneStatusBody>
   </Box>;
 }

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 } from "../options/model-spot";
+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);
@@ -191,6 +208,24 @@ export function scenarioSpotBasis(
   return (market?.underlyingQuote ? extendedSession(market.underlyingQuote) : null) ?? "last price";
 }
 
+const EXTENDED_BASES: readonly string[] = ["pre-market", "after hours", "overnight"];
+
+/**
+ * A spot basis as the pane and report name it: an extended-session print with
+ * its time, stamped as every options pane stamps its spot (`modelSpotStamp`),
+ * `pre-market Wed 21 Oct 09:42 UTC`; any other basis as it is.
+ */
+export function scenarioSpotStamp(basis: string, observedAt: number): string {
+  if (!EXTENDED_BASES.includes(basis)) return basis;
+  return modelSpotStamp({ basis: "last", session: basis as OptionModelSpot["session"], observedAt }) ?? basis;
+}
+
+/** That stamp's shorter forms, longest first (`modelSpotStampVariants`): `pre-market 09:42 UTC`, `pre-market`. */
+export function scenarioSpotStampVariants(basis: string, observedAt: number): string[] {
+  if (!EXTENDED_BASES.includes(basis)) return [];
+  return modelSpotStampVariants({ basis: "last", session: basis as OptionModelSpot["session"], observedAt });
+}
+
 function supplied(value: unknown): boolean { return value != null && value !== ""; }
 
 /** A position typed whole: its legs and the spot, rate and dividend yield they are valued at, so no market data is read. */
@@ -207,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`);
@@ -248,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");
@@ -270,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
@@ -308,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;
@@ -328,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;
 
@@ -339,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
@@ -355,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) => {
@@ -388,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,
@@ -423,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;
 
@@ -430,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" },
+    };
+  },
+};