gloomberb 0.18.2 → 0.18.4

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

@@ -1,20 +1,22 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { parsePublicTickerKey } from "../../../utils/exchanges";
+import { DATE_OPTION_EXAMPLES } from "../../../utils/calendar-date";
 import {
   expirationOptionSeconds, OPTION_EXPIRATION_FORMAT, OPTION_EXPIRATION_PLACEHOLDER, readOptionExpiration,
 } from "../../../utils/option-expiry";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import {
   createScenarioDependencies, loadScenarioMarket, SCENARIO_STRATEGIES, scenarioControlsFromSettings, scenarioPositionFromSettings,
-  scenarioSpotBasis, suppliedScenarioInputs, type ScenarioMarketSnapshot,
+  scenarioSpotBasis, scenarioSpotStamp, suppliedScenarioInputs, type ScenarioMarketSnapshot,
 } from "./client";
 import { scenarioFreshness } from "./freshness";
 import { cashSecuredPut, cspReportEntries, loadNextEarningsDate } from "./csp";
 import { formatSpotTime } from "../options/model-spot";
-import { buildScenario, currencyLabel, parseLegs, scenarioValueUnit } from "./model";
-import { hedgeInputsFromSettings, hedgeReportEntries, scenarioHedgeBudget } from "./hedge";
+import { amountUnit, buildScenario, currencyLabel, exportPercent, parseLegs, scenarioValueUnit } from "./model";
+import { hedgeInputsFromSettings, hedgeReportEntries, scenarioHedgeBudget, seededLegQuotes } from "./hedge";
 import { collarReportEntries, scenarioCollar } from "./collar";
 import { modelDividendYieldNote } from "../../../market-data/model-dividend-yield";
+import { listingFateEmpty, loadListingFate } from "../../../tickers/listing-fate";
 
 // Float noise at a flat origin or a breakeven prints as 0.00, not -0.00.
 const money = (value: unknown) => typeof value === "number" ? (Math.abs(value) < 0.005 ? 0 : value).toFixed(2) : "--";
@@ -31,6 +33,12 @@ const VALUATION_LABELS: Record<string, (currency: string) => string> = {
   thetaPerDay: (currency) => `Theta (${currency} per day)`, vegaPerPoint: (currency) => `Vega (${currency} per vol point)`,
   rhoPerPoint: (currency) => `Rho (${currency} per rate point)`,
 };
+/** The unit an export names beside each Valuation figure: `per` is the currency for the position (`USD per contract`). */
+const VALUATION_UNITS: Record<string, (currency: string, per: string) => string> = {
+  price: (_currency, per) => per, pnl: (_currency, per) => per, delta: () => "shares", gamma: () => "shares per 1.00 move",
+  thetaPerDay: (currency) => `${currency} per day`, vegaPerPoint: (currency) => `${currency} per vol point`,
+  rhoPerPoint: (currency) => `${currency} per rate point`,
+};
 
 export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Underlying ticker" },
@@ -39,7 +47,8 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
   description: "A typed or chain-seeded options position valued across spot, date and volatility: its legs, value and Greeks, expiry risk and a "
     + "scenario P&L grid. With --nav and --budget-bps, how many contracts a hedge budget buys, the premium spent, the notional protected and "
     + "coverage of an equity sleeve. --strategy csp sells a cash-secured put: cash secured, premium, yield on cash, annualised yield, "
-    + "distance out of the money, break-even, days to expiry and whether earnings fall before expiry. --strategy collar buys a put and sells "
+    + "the bid, ask and spread with the yield at the bid, distance out of the money, break-even, days to expiry and whether earnings fall "
+    + "before expiry; CSP ranks the same put across several names. --strategy collar buys a put and sells "
     + "a call against the shares they cover: net premium, floor, cap and breakevens of the hedged position.",
   discovery: { screenshotReadiness: "ready", limitations: ["European scenario values do not model early assignment or exercise."] },
   options: [
@@ -52,6 +61,8 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
         + "csp, one short put sold at its midpoint with the cash to buy the shares set aside (a cash-secured put), "
         + "or collar, one long put and one short call on the same expiry with the shares they cover" },
     { key: "strike", type: "string", description: "The --strategy strike: the put, the vertical's long call or the straddle. Nearest the money when omitted" },
+    { key: "delta", type: "string", placeholder: "0.30", example: "--strategy csp --delta 0.30 --expiration 2026-11-20",
+      description: "The --strategy csp or put put by its delta instead of --strike: the one whose delta is nearest this, as a put's delta reads without its sign" },
     { key: "putStrike", aliases: ["put-strike"], type: "string",
       description: "The --strategy collar put bought. The quoted strike nearest 10% below spot when omitted" },
     { key: "callStrike", aliases: ["call-strike"], type: "string",
@@ -66,8 +77,8 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
     { key: "rate", type: "string", description: "Continuously compounded annual risk-free rate, percent" },
     { key: "dividendYield", aliases: ["dividend-yield"], type: "string", description: "Continuous annual dividend yield, percent" },
     { key: "currency", type: "string", description: "Currency of the inputs, such as USD; the underlying's when omitted" },
-    { key: "asOf", aliases: ["as-of"], type: "string", description: "Position valuation timestamp: UTC ISO or YYYY-MM-DD" },
-    { key: "date", type: "string", description: "Scenario date: UTC ISO or YYYY-MM-DD" },
+    { key: "asOf", aliases: ["as-of"], type: "string", description: `Position valuation date, as ${DATE_OPTION_EXAMPLES}, or a UTC ISO timestamp` },
+    { key: "date", type: "string", description: `Scenario date, as ${DATE_OPTION_EXAMPLES}, or a UTC ISO timestamp` },
     { key: "volShift", aliases: ["vol-shift"], type: "string", defaultValue: "0", description: "Parallel volatility shift, percentage points" },
     { key: "spotRange", aliases: ["spot-range"], type: "string", defaultValue: "30", description: "Spot grid range above and below current spot, percent" },
     { key: "nav", type: "string", description: "Portfolio NAV for a hedge budget, such as 100m, 2.5bn, 250k, 1,000,000 or $100m. Needs --budget-bps" },
@@ -77,17 +88,23 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
   ],
   async load(args, ctx) {
     const symbol = args.symbols[0]!;
+    // Several names to sell puts on are a screen, not one scenario.
+    const names = args.rawArgument.split(/[\s,;]+/).filter(Boolean);
+    if (names.length > 1 && args.options.strategy === "csp") {
+      throw new Error(`OSA values one underlying. To rank cash-secured puts across ${names.join(", ")}: gloom fn CSP ${names.join(" ")}`);
+    }
     const settings: Record<string, unknown> = { ...ctx.settings, ...args.options, symbol };
     // Bad hedge inputs fail before any market request.
     hedgeInputsFromSettings(settings);
     const suppliedInputs = suppliedScenarioInputs(settings);
     let market: ScenarioMarketSnapshot;
+    let instrument: Awaited<ReturnType<typeof resolveHeadlessInstrument>> | null = null;
     if (suppliedInputs) {
       // An explicit position can be valued offline and must never depend on unrelated market requests.
       market = { ...parsePublicTickerKey(symbol), spot: null, currency: "", asOf: Date.now(), chain: null, expirationDates: [], rate: null,
         dividendYield: null, source: null, underlyingQuote: null, rateAsOf: [], warnings: [] };
     } else {
-      const instrument = await resolveHeadlessInstrument(ctx, symbol);
+      instrument = await resolveHeadlessInstrument(ctx, symbol);
       const typedExpiries = typeof settings.legs === "string" && settings.legs.trim() ? parseLegs(settings.legs).map((leg) => leg.expiration) : [];
       const expiration = readOptionExpiration(args.options.expiration);
       market = await loadScenarioMarket({ instrument, expiration: expiration ?? undefined,
@@ -104,14 +121,20 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
     // A typed rate or yield stands in for the source that could not supply one.
     const marketWarnings = market.warnings.filter((warning) => !(supplied(settings.dividendYield) && warning.startsWith("Dividend yield unavailable"))
       && !(supplied(settings.rate) && warning.startsWith("Treasury")));
-    const errors = scenario ? [...new Set([...marketWarnings, ...scenario.warnings])]
+    const loadErrors = scenario ? [...new Set([...marketWarnings, ...scenario.warnings])]
       : [...marketWarnings, "No position supplied; add --legs or select --strategy"];
+    // A symbol with no option chain at all says what became of it when something did (TWTR stopped
+    // trading, FB is a fund now) in place of the chain's errors.
+    const fate = instrument && !market.chain && !scenario
+      ? listingFateEmpty(await loadListingFate(instrument, ctx.marketData, market.underlyingQuote ? { quote: market.underlyingQuote } : {}), loadErrors) : null;
+    const errors = fate?.errors ?? loadErrors;
     const midVolatility = !!position?.legs.some((leg) => leg.volatilitySource === "mid");
     // A seeded strategy starts at the spot its quote mids imply; the last print is reported beside it.
     const lastPrint = midVolatility && !supplied(settings.spot) && market.spot != null && money(market.spot) !== money(position!.spot)
       ? market.spot : null;
     const spotBasis = position ? scenarioSpotBasis(settings, position, market) : null;
-    const csp = position && settings.strategy === "csp" ? cashSecuredPut(position, spotBasis!, earningsDate) : null;
+    const csp = position && settings.strategy === "csp"
+      ? cashSecuredPut(position, spotBasis!, earningsDate, seededLegQuotes(position, market.chain).get(position.legs[0]?.id ?? "")) : null;
     // A collar seeded, or one typed with the shares it hedges.
     const collar = position && (settings.strategy === "collar" || position.underlying) ? scenarioCollar(position, spotBasis!) : null;
     const lastSession = market.underlyingQuote && spotBasis === "implied by option quotes"
@@ -122,6 +145,10 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
     // Value, P&L, risk and the grid add every contract; entry prices and spot are per share.
     const valueUnit = position ? scenarioValueUnit(position) : null;
     const per = `${currency} ${valueUnit}`;
+    // What an export names beside each number: the currency (or `currency unknown`) and what it is for.
+    const exportCurrency = position ? amountUnit(position.currency) : "";
+    const exportPer = `${exportCurrency} ${valueUnit}`;
+    const perShare = `${exportCurrency} ${PRICE_UNIT}`;
     return {
       freshness: scenarioFreshness(market, suppliedInputs),
       sections: scenario ? [
@@ -134,16 +161,16 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
         ], rows: position!.legs.map((leg) => ({ ...leg, expiry: new Date(leg.expiration * 1000).toISOString().slice(0, 10),
           ...(midVolatility ? { volatilityFrom: leg.volatilitySource === "mid" ? "quote mid" : "provider" } : {}) })) },
         { title: "Inputs", entries: [
-          { key: "spot", label: lastPrint != null ? "Spot implied by option quotes" : "Spot", value: position!.spot,
-            formatted: `${money(position!.spot)} ${PRICE_UNIT}${lastPrint == null && spotBasis !== "last price" ? ` (${spotBasis})` : ""}` },
-          ...(lastPrint != null ? [{ key: "last", label: "Last price", value: lastPrint,
-            formatted: `${money(lastPrint)} ${PRICE_UNIT}${lastSession && lastSession !== "last price" ? ` (${lastSession})` : ""}` }] : []),
-          ...(position!.underlying ? [{ key: "shares", label: "Shares held", value: position!.underlying.quantity,
+          { key: "spot", label: lastPrint != null ? "Spot implied by option quotes" : "Spot", value: position!.spot, unit: perShare,
+            formatted: `${money(position!.spot)} ${PRICE_UNIT}${lastPrint == null && spotBasis !== "last price" ? ` (${scenarioSpotStamp(spotBasis!, position!.asOf)})` : ""}` },
+          ...(lastPrint != null ? [{ key: "last", label: "Last price", value: lastPrint, unit: perShare,
+            formatted: `${money(lastPrint)} ${PRICE_UNIT}${lastSession && lastSession !== "last price" ? ` (${scenarioSpotStamp(lastSession, market.asOf)})` : ""}` }] : []),
+          ...(position!.underlying ? [{ key: "shares", label: "Shares held", value: position!.underlying.quantity, unit: "shares",
             formatted: `${position!.underlying.quantity.toLocaleString("en-US")} at ${money(position!.underlying.price)} ${PRICE_UNIT}` }] : []),
           { key: "asOf", label: "Valued at", value: new Date(position!.asOf).toISOString(), formatted: formatSpotTime(position!.asOf) },
-          { key: "rate", label: "Rate", value: position!.rate, formatted: percent(position!.rate) },
+          { key: "rate", label: "Rate", value: exportPercent(position!.rate), unit: "%", formatted: percent(position!.rate) },
           // A yield read as 0 because no dividend was paid, or the dividend stopped, says so; a stated or typed one is the figure alone.
-          { key: "dividendYield", label: "Dividend yield", value: position!.dividendYield, formatted: percent(position!.dividendYield)
+          { key: "dividendYield", label: "Dividend yield", value: exportPercent(position!.dividendYield), unit: "%", formatted: percent(position!.dividendYield)
             + (dividendNote ? ` (${dividendNote})` : "") },
           { key: "currency", label: "Currency", value: position!.currency, formatted: currency! },
         ] },
@@ -151,12 +178,13 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
         ...(csp ? [{ title: "Cash-secured put", entries: cspReportEntries(csp) }] : []),
         ...(collar ? [{ title: "Collar", entries: collarReportEntries(collar) }] : []),
         { title: `Valuation (${per})`, entries: Object.entries(scenario.valuation).map(([key, value]) => ({ key,
-          label: VALUATION_LABELS[key]?.(currency!) ?? key, value, formatted: money(value) })) },
+          label: VALUATION_LABELS[key]?.(currency!) ?? key, value, formatted: money(value),
+          ...(VALUATION_UNITS[key] ? { unit: VALUATION_UNITS[key]!(exportCurrency, exportPer) } : {}) })) },
         { title: `Expiry risk (${per})`, entries: [
-          { key: "breakevens", label: "Breakevens (spot)", value: scenario.expiryRisk.breakevens,
+          { key: "breakevens", label: "Breakevens (spot)", value: scenario.expiryRisk.breakevens, unit: perShare,
             formatted: scenario.expiryRisk.breakevens.map(money).join(", ") || "none" },
-          { key: "maxProfit", label: "Max profit", value: scenario.expiryRisk.maxProfit, formatted: scenario.expiryRisk.unlimitedProfit ? "Unlimited" : money(scenario.expiryRisk.maxProfit) },
-          { key: "maxLoss", label: "Max loss", value: scenario.expiryRisk.maxLoss, formatted: scenario.expiryRisk.unlimitedLoss ? "Unlimited" : money(scenario.expiryRisk.maxLoss) },
+          { key: "maxProfit", label: "Max profit", value: scenario.expiryRisk.maxProfit, unit: exportPer, formatted: scenario.expiryRisk.unlimitedProfit ? "Unlimited" : money(scenario.expiryRisk.maxProfit) },
+          { key: "maxLoss", label: "Max loss", value: scenario.expiryRisk.maxLoss, unit: exportPer, formatted: scenario.expiryRisk.unlimitedLoss ? "Unlimited" : money(scenario.expiryRisk.maxLoss) },
           ...(scenario.expiryRisk.reason ? [{ key: "limitation", label: "Limitation", value: scenario.expiryRisk.reason }] : []),
         ] },
         { title: `Scenario grid (P&L, ${per})`, columns: [
@@ -167,7 +195,7 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
           ...Object.fromEntries(row.values.map((value, index) => [`date${index}`, value])) })) },
       ] : [],
       complete: scenario != null && errors.length === 0,
-      unavailableSymbols: scenario ? [] : [symbol], errors,
+      unavailableSymbols: scenario ? [] : [symbol], errors, ...(fate?.empty ? { empty: fate.empty } : {}),
       metadata: { scenario, position, controls, market, ...(hedge ? { hedge } : {}), ...(csp ? { csp } : {}), ...(collar ? { collar } : {}),
         ...(position ? { spot: { price: position.spot, basis: spotBasis, valuedAt: new Date(position.asOf).toISOString() } } : {}),
         inputSource: suppliedInputs ? "user" : "market",

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

@@ -3,7 +3,7 @@ import type { OptionsChain } from "../../../types/financials";
 import type { HeadlessPaneEntry } from "../../../types/headless";
 import { numberErrorMessage } from "../../../utils/decimal-comma";
 import { formatCompact } from "../../../utils/format";
-import { UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
+import { amountUnit, exportPercent, UNKNOWN_CURRENCY, type ScenarioPosition } from "./model";
 
 /**
  * Hedge budget sizing (docs/research-data.md#options-scenario-analysis): how
@@ -118,9 +118,10 @@ export interface HedgeQuote { bid: number; ask: number }
 
 /**
  * The bid and ask of each leg a strategy seeded from the chain, by leg id: the
- * chain's, or the leg's streamed quote when the pane follows the market.
+ * chain's, or the leg's streamed quote when the pane follows the market. A
+ * typed leg has none.
  */
-function hedgeLegQuotes(
+export function seededLegQuotes(
   position: ScenarioPosition, chain: OptionsChain | null | undefined, liveQuotes?: ReadonlyMap<string, HedgeQuote>,
 ): Map<string, HedgeQuote> {
   const contracts = new Map([...(chain?.calls ?? []), ...(chain?.puts ?? [])].map((contract) => [contract.contractSymbol, contract]));
@@ -206,7 +207,7 @@ export function scenarioHedgeBudget(
   const inputs = hedgeInputsFromSettings(settings);
   if (!inputs) return null;
   if (!position?.legs.length) throw new Error("A hedge budget needs a position; add --legs or select --strategy.");
-  return sizeHedgeBudget(position, inputs, { quotes: hedgeLegQuotes(position, market?.chain, market?.liveQuotes),
+  return sizeHedgeBudget(position, inputs, { quotes: seededLegQuotes(position, market?.chain, market?.liveQuotes),
     spot: hedgeSpot(position, market?.spot, supplied(settings.spot)) });
 }
 
@@ -246,21 +247,26 @@ function costText(cost: number, sizingPrice: number | null, multiplier: number,
 /** The report's Hedge budget section; `value` keeps full precision, `formatted` is what text output prints. */
 export function hedgeReportEntries(hedge: HedgeBudget): HeadlessPaneEntry[] {
   const unit = hedge.currency && hedge.currency !== UNKNOWN_CURRENCY ? ` ${hedge.currency}` : "";
+  // Each figure's `value` is in its `unit`, a share of NAV in percent, so an export writes the number and its unit.
+  const amount = { unit: amountUnit(hedge.currency) };
   return [
-    { key: "nav", label: "NAV", value: hedge.nav, formatted: `${money(hedge.nav)}${unit}` },
-    { key: "budget", label: "Budget", value: hedge.budget, formatted: `${money(hedge.budget)}${unit} (${formatBps(hedge.budgetBps)} of NAV)` },
-    { key: "sizingPrice", label: "Sizing price", value: hedge.sizingPrice,
+    { key: "nav", label: "NAV", value: hedge.nav, ...amount, formatted: `${money(hedge.nav)}${unit}` },
+    { key: "budget", label: "Budget", value: hedge.budget, ...amount, formatted: `${money(hedge.budget)}${unit} (${formatBps(hedge.budgetBps)} of NAV)` },
+    { key: "sizingPrice", label: "Sizing price", value: hedge.sizingPrice, unit: `${amount.unit} per share`,
       formatted: hedge.sizingPrice == null ? "--" : describePrice(hedge.basis, hedge.singleLeg, hedge.sizingPrice) },
-    { key: "costPerContract", label: "Cost per contract", value: hedge.costPerContract, formatted: costText(hedge.costPerContract, hedge.sizingPrice, hedge.multiplier, unit) },
-    { key: "contracts", label: "Contracts", value: hedge.contracts, formatted: hedge.contracts.toLocaleString("en-US") },
-    { key: "premium", label: "Premium spent", value: hedge.premium, formatted: `${money(hedge.premium)}${unit}` },
-    { key: "premiumBps", label: "Premium / NAV", value: hedge.premiumBps, formatted: `${formatBps(hedge.premiumBps)} (${(hedge.premiumBps / 100).toFixed(2)}% of NAV)` },
-    { key: "notional", label: "Notional protected", value: hedge.notional,
+    { key: "costPerContract", label: "Cost per contract", value: hedge.costPerContract, ...amount,
+      formatted: costText(hedge.costPerContract, hedge.sizingPrice, hedge.multiplier, unit) },
+    { key: "contracts", label: "Contracts", value: hedge.contracts, unit: "contracts", formatted: hedge.contracts.toLocaleString("en-US") },
+    { key: "premium", label: "Premium spent", value: hedge.premium, ...amount, formatted: `${money(hedge.premium)}${unit}` },
+    { key: "premiumBps", label: "Premium / NAV", value: hedge.premiumBps, unit: "bp",
+      formatted: `${formatBps(hedge.premiumBps)} (${(hedge.premiumBps / 100).toFixed(2)}% of NAV)` },
+    { key: "notional", label: "Notional protected", value: hedge.notional, ...amount,
       formatted: `${money(hedge.notional)}${unit} (${hedge.contracts.toLocaleString("en-US")} x ${hedge.multiplier} x ${formatHedgePrice(hedge.spot)})` },
-    { key: "notionalOfNav", label: "Notional / NAV", value: hedge.notionalOfNav, formatted: percent(hedge.notionalOfNav) },
+    { key: "notionalOfNav", label: "Notional / NAV", value: exportPercent(hedge.notionalOfNav), unit: "%", formatted: percent(hedge.notionalOfNav) },
     hedge.coverage == null || hedge.sleeve == null
       ? { key: "coverage", label: "Coverage", value: null, formatted: "No equity sleeve given; add --sleeve <amount> to read notional against it" }
-      : { key: "coverage", label: "Coverage", value: hedge.coverage, formatted: `${percent(hedge.coverage)} of a ${money(hedge.sleeve)}${unit} sleeve` },
+      : { key: "coverage", label: "Coverage", value: exportPercent(hedge.coverage), unit: "%",
+        formatted: `${percent(hedge.coverage)} of a ${money(hedge.sleeve)}${unit} sleeve` },
   ];
 }
 

package/src/plugins/builtin/options-scenario/index.tsx

@@ -2,8 +2,10 @@ import type { PluginModule } from "../plugin-module";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import { OptionsScenarioPane } from "./pane";
 import { optionsScenarioHeadless } from "./headless";
+import { CspScreenPane } from "./csp-screen-pane";
+import { cspScreenHeadless } from "./csp-screen-headless";
 
-const scenarioSettingKeys = ["legs", "strategy", "strike", "putStrike", "callStrike", "shares", "expiration", "spot", "rate", "dividendYield", "currency", "asOf", "date", "volShift",
+const scenarioSettingKeys = ["legs", "strategy", "strike", "delta", "putStrike", "callStrike", "shares", "expiration", "spot", "rate", "dividendYield", "currency", "asOf", "date", "volShift",
   "spotRange", "seedLeg", "nav", "budgetBps", "sleeve"];
 
 export const optionsScenarioModule: PluginModule = {
@@ -23,11 +25,34 @@ export const optionsScenarioModule: PluginModule = {
           description: "The equity the hedge protects, for coverage: notional protected over the sleeve." },
       ],
     },
+  }, {
+    id: "csp-screen", name: "Cash-Secured Put Screen", icon: "V", component: CspScreenPane,
+    defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 144, height: 24 },
+    tableExport: true, headless: cspScreenHeadless,
+    settings: {
+      title: "Cash-Secured Put Screen",
+      fields: [
+        { key: "symbols", label: "Symbols", type: "text", placeholder: "JPM, GS, KO" },
+        { key: "maxSpread", label: "Wide spread over (%)", type: "text", placeholder: "10",
+          description: "A put whose bid/ask spread is over this percent of its mid is marked wide. It is still ranked." },
+      ],
+    },
   }],
-  paneTemplates: [createTickerSurfacePaneTemplate({
+  paneTemplates: [{
+    id: "csp-screen-pane", paneId: "csp-screen", label: "Cash-Secured Put Screen",
+    description: "Cash-secured puts across a list, ranked by annualised yield at the bid, with % OTM, delta, IV rank, spread and an earnings flag.",
+    // The put-selling phrases lead here first, then to OSA for one name.
+    keywords: ["csp", "cash secured put", "cash-secured puts", "put selling", "selling puts", "sell put", "sell puts", "short put", "wheel",
+      "put screen", "premium yield"],
+    shortcut: { prefix: "CSP", argKind: "ticker-list" as const }, headless: cspScreenHeadless,
+    createInstance: (_context, options) => ({
+      title: "CSP", placement: "floating" as const,
+      settings: options?.symbols?.length ? { symbols: options.symbols.join(",") } : {},
+    }),
+  }, createTickerSurfacePaneTemplate({
     id: "options-scenario-pane", paneId: "options-scenario", label: "Options Scenario",
     description: "Build multi-leg positions and compare scenario P&L, payoff and aggregate Greeks.",
-    // OSA owns the phrases; OMON and VCA carry the same words without them, so a put-selling search finds all three, OSA first.
+    // OSA carries the put-selling phrases after CSP, which ranks names on them; OMON and VCA carry the same words, so a search finds all four.
     keywords: ["osa", "options", "scenario", "payoff", "strategy", "greeks", "hedge", "hedging", "collar", "protective put", "put spread",
       "cash secured put", "csp", "put selling", "sell put", "short put", "wheel"],
     shortcut: "OSA", publicShare: true,

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

@@ -160,6 +160,19 @@ export function validateScenarioInputs(position: ScenarioPosition): string | nul
 /** The stored stand-in for a currency nothing names; shown as `currency unknown`. */
 export const UNKNOWN_CURRENCY = "UNKNOWN";
 export const currencyLabel = (currency: string) => currency === UNKNOWN_CURRENCY ? "currency unknown" : currency;
+/** The unit an export names beside an amount: the currency code, or `currency unknown`. */
+export const amountUnit = (currency: string) => currency && currency !== UNKNOWN_CURRENCY ? currency : "currency unknown";
+
+/**
+ * A fraction as the percent an export carries: a rate of 0.041 is 4.1, not
+ * the 4.1000000000000005 the product leaves. Twelve significant digits keep
+ * every digit a figure has; null stays null.
+ */
+export function exportPercent(fraction: number): number;
+export function exportPercent(fraction: number | null | undefined): number | null;
+export function exportPercent(fraction: number | null | undefined): number | null {
+  return fraction == null ? null : Number((fraction * 100).toPrecision(12));
+}
 
 /**
  * The position's currency: the one typed, else the underlying's quote

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

@@ -26,7 +26,7 @@ import { buildOptionQuoteKey, freshOptionQuote, OPTIONS_QUOTE_EXCHANGE } from ".
 import { liveScenarioPosition, scenarioLegContractSymbol } from "./live";
 import { ScenarioPayoffChart } from "./charts";
 import { ScenarioLegEditor, ScenarioSaveForm, ScenarioInputsForm } from "./editor";
-import { loadScenarioMarket, scenarioControlsFromSettings, scenarioPositionFromSettings, scenarioSpotBasis, suppliedScenarioInputs,
+import { loadScenarioMarket, scenarioControlsFromSettings, scenarioPositionFromSettings, scenarioSpotBasis, scenarioSpotStamp, scenarioSpotStampVariants, suppliedScenarioInputs,
   type ScenarioMarketSnapshot } from "./client";
 import { scenarioFreshness } from "./freshness";
 import { cashSecuredPut, cspStatItems, loadNextEarningsDate } from "./csp";
@@ -38,8 +38,8 @@ import { buildScenario, currencyLabel, scenarioCurrency, scenarioValueUnit, UNKN
   type ScenarioControls, validatePosition } from "./model";
 import { EMPTY_SAVED_STRATEGIES, restoreSavedStrategies, type SavedScenarioStrategy } from "./state";
 import { useScenarioEvidence } from "./evidence";
-import { hedgeStatItems, scenarioHedgeBudget, type HedgeQuote } from "./hedge";
-import { readOptionExpiration } from "../../../utils/option-expiry";
+import { hedgeStatItems, scenarioHedgeBudget, seededLegQuotes, type HedgeQuote } from "./hedge";
+import { isLiveOptionExpiry, readOptionExpiration } from "../../../utils/option-expiry";
 import { parsePublicTickerKey } from "../../../utils/exchanges";
 
 const EMPTY_ERRORS: string[] = [];
@@ -65,7 +65,9 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   const underlying = listed.symbol;
   const exchange = listed.exchange || target?.effectiveExchange || undefined;
   // A strategy seeded for an expiry (`OSA SPY --strategy put --expiration 2027-01-15`) opens that expiry's chain.
-  const [expiration, setExpiration] = usePluginPaneState<number | null>("chainExpiration", readOptionExpiration(settings.expiration));
+  const [pickedExpiration, setExpiration] = usePluginPaneState<number | null>("chainExpiration", readOptionExpiration(settings.expiration));
+  // A picked expiry that has since lapsed gives way to the nearest live one, as OMON's does.
+  const expiration = pickedExpiration != null && isLiveOptionExpiry(pickedExpiration, Date.now(), exchange) ? pickedExpiration : null;
   const [tab, setTab] = usePluginPaneState("activeTabId", "payoff");
   const [detail, setDetail] = useState<"chain" | "leg" | "save" | "inputs" | null>(null);
   const [editingLeg, setEditingLeg] = useState<ScenarioLeg | null>(null);
@@ -166,9 +168,11 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   const earningsDate = frozenEarnings ? settings.scenarioEarningsDate as string | null : earnings.data;
   // A position following the market is at the live print, which the footer names with its feed.
   const spotBasis = scenario && !live ? scenarioSpotBasis(settings, scenario.position, market) : null;
+  // The put's bid and ask: its streamed quote while the pane follows the market, else the chain's.
   const csp = useMemo(() => cspStrategy && scenario && !earnings.loading
-    ? cashSecuredPut(scenario.position, live?.basis ?? spotBasis ?? "last price", earningsDate) : null,
-  [cspStrategy, scenario, earnings.loading, earningsDate, live?.basis, spotBasis]);
+    ? cashSecuredPut(scenario.position, live?.basis ?? spotBasis ?? "last price", earningsDate,
+      seededLegQuotes(scenario.position, market?.chain, live?.quotes).get(scenario.position.legs[0]?.id ?? "")) : null,
+  [cspStrategy, scenario, earnings.loading, earningsDate, live?.basis, live?.quotes, spotBasis, market?.chain]);
   // A collar seeded, or one typed with the shares it hedges, as the report reads it.
   const collarStrategy = settings.strategy === "collar";
   const collar = useMemo(() => scenario && (collarStrategy || scenario.position.underlying)
@@ -294,11 +298,15 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   const midLegs = live || !position ? 0 : position.legs.filter((leg) => leg.volatilitySource === "mid").length;
   // A seed starts at the spot its quote mids imply, so name the last print when it differs.
   const lastPrint = midLegs && (settings.spot == null || settings.spot === "") && market?.spot != null
-    && money(market.spot) !== money(position!.spot) ? ` · last ${money(market.spot)}` : "";
+    && money(market.spot) !== money(position!.spot)
+    ? ` · ${(market.underlyingQuote ? extendedSession(market.underlyingQuote) : null) ?? "last"} ${money(market.spot)}` : "";
   const midVolatility = !midLegs ? "" : (midLegs === position!.legs.length ? " · IV from quote mid"
     : ` · IV from quote mid on ${midLegs} of ${position!.legs.length} legs`) + lastPrint;
   // The spot every figure is valued at, and when: the live print, the spot the quote mids imply, a typed what-if or the last price.
-  const spotText = position ? `spot ${money(position.spot)}${spotBasis && spotBasis !== "last price" ? ` ${spotBasis}` : ""}` : "";
+  // An extended-session print carries its own time in the stamp.
+  const spotStamp = position && spotBasis && spotBasis !== "last price" ? scenarioSpotStamp(spotBasis, position.asOf) : null;
+  const spotText = position ? `spot ${money(position.spot)}${spotStamp ? ` ${spotStamp}` : ""}` : "";
+  const spotTimed = !!spotStamp && spotStamp !== spotBasis;
   // A narrow row keeps the spot and its time before the rest.
   const shortSpotText = position ? `spot ${money(position.spot)} · ${formatSpotTime(live?.observedAt ?? position.asOf)}` : "";
   usePaneFooter("osa", () => ({ info: [
@@ -307,7 +315,7 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
     ...(hedge.error ? [{ id: "hedge-error", parts: [{ text: hedge.error, tone: "warning" as const }] }] : []),
     ...(live ? splitDelayedStatus({ id: "asof", parts: [{ text: `${live.basis} · ${spotText} · ${new Date(live.observedAt).toISOString().slice(11, 19)} UTC`, tone: "muted" }],
       variants: [[{ text: shortSpotText, tone: "muted" }]] })
-      : position ? [{ id: "asof", parts: [{ text: `${spotText} · ${formatSpotTime(position.asOf)} · ${market?.source ? "market" : "input assumptions"}${midVolatility}`, tone: "muted" as const }],
+      : position ? [{ id: "asof", parts: [{ text: `${spotText}${spotTimed ? "" : ` · ${formatSpotTime(position.asOf)}`} · ${market?.source ? "market" : "input assumptions"}${midVolatility}`, tone: "muted" as const }],
         variants: [[{ text: shortSpotText, tone: "muted" as const }]] }] : []),
   ], hints }), [hints, position, market?.source, resource.loading, error, hedge.error, live?.basis, live?.observedAt, midVolatility, spotText, shortSpotText]);
   useScenarioEvidence({ scenario, view: tab, loading: !!resource.loading && !scenario, error: error ?? (snapshotErrors.join("; ") || null), notices });
@@ -337,7 +345,11 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
       tone: cents(scenario.valuation.pnl) >= 0 ? "positive" : "negative" },
     // A spot other than the last price says what it is: the one the quote mids imply, or a typed what-if.
     { id: "spot", label: "Spot", value: money(scenario.position.spot),
-      detail: spotBasis === "implied by option quotes" ? "per share, implied" : spotBasis === "typed" ? "per share, typed" : "per share" },
+      detail: spotBasis === "implied by option quotes" ? "per share, implied" : spotBasis === "typed" ? "per share, typed"
+        : spotTimed ? `per share, ${spotStamp}` : "per share",
+      // The band keeps its columns: the stamp's day, its time, then the stamp give way first.
+      ...(spotTimed ? { detailVariants: [...scenarioSpotStampVariants(spotBasis!, scenario.position.asOf)
+        .map((form) => `per share, ${form}`), "per share"] } : {}) },
     { id: "value", label: "Value", value: money(scenario.valuation.price), detail: valueUnit },
     { id: "max-profit", label: "Max profit", value: risk?.unlimitedProfit ? "Unlimited" : money(risk?.maxProfit ?? null) },
     { id: "max-loss", label: "Max loss", value: risk?.unlimitedLoss ? "Unlimited" : money(risk?.maxLoss ?? null) },

package/src/plugins/builtin/perps/equity-row.tsx

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { useCallback, useMemo } from "react";
 import { isAccessDenied } from "../../../api-client/errors";
 import { usePlanAccess } from "../../../api-client/plan-access";
 import type { PerpBoardRow } from "../../../api-client/perps";
@@ -10,7 +10,9 @@ import { perpEquityIdentity } from "./equity-identity";
 import { perpetualListing } from "../../../tickers/perpetual-listing";
 import { loadPerpSelection, loadPerpsEquity } from "./client";
 import { compact, percent, perpDescription, price, readingTime } from "./model";
+import { useLivePerpRows } from "./live-rows";
 import { openPerpLabel, useOpenPerpMarket } from "./open-market";
+import { mergeVenueMarkets } from "./venue-markets";
 
 /**
  * A stock's perpetuals, or for a perpetual market itself its own contract: funding, open interest and when the venue
@@ -34,9 +36,15 @@ export function PerpEquityRow({ symbol, exchange, instrumentType, maxRows = 3, w
     : loadPerpsEquity({ symbol: listingSymbol!, exchange: listingExchange! }, accessKey, force), [marketId, listingSymbol, listingExchange, accessKey]);
   const resource = useAsyncResource(enabled ? loader : null, { clearOnError: isAccessDenied });
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
-  const rows = resource.data?.payload.rows.filter((row) => !row.delisted && (!marketId || row.marketId === marketId)) ?? [];
+  // A stock's contracts one per venue, deepest first, as DES lists them; the ones shown follow the quote stream.
+  const fetched = useMemo(() => {
+    const rows = resource.data?.payload.rows ?? [];
+    return marketId ? rows.filter((row) => !row.delisted && row.marketId === marketId) : mergeVenueMarkets(rows).map((market) => market.primary);
+  }, [marketId, resource.data]);
+  const shown = useMemo(() => fetched.slice(0, maxRows), [fetched, maxRows]);
+  const { rows } = useLivePerpRows(shown, { surface: marketId ? "detail" : "monitor", enabled });
   if (!enabled || !rows.length) return null;
-  return <>{rows.slice(0, maxRows).map((row) => <PerpRow key={row.marketId} row={row} stale={!!resource.data?.stale} width={width} own={!!marketId} />)}</>;
+  return <>{rows.map((row) => <PerpRow key={row.marketId} row={row} stale={!!resource.data?.stale} width={width} own={!!marketId} />)}</>;
 }
 
 /** The parts that fit `width`, dropped from the end; all of them when the width is not known. */

package/src/plugins/builtin/perps/freshness.ts

@@ -48,18 +48,21 @@ export function fundingNote(rows: readonly Funded[], now = Date.now()): string |
 }
 
 /**
- * How current a view of perpetual markets is: each venue's own newest observation, polled rather than streamed and
- * stale after an hour without a poll, and what the funding figures it shows (`funding`) are. The report, the capture
- * and the pane footer all read this, so they end with the same line.
+ * How current a view of perpetual markets is: each venue's own newest observation, read once a minute (live while
+ * every row followed has a price from its venue's socket within the minute) and stale after an hour without a read, and
+ * what the funding figures it shows (`funding`) are. The report, the capture and the pane footer all read this, so they
+ * end with the same line.
  */
-export function perpFreshness(rows: readonly Dated[], { funding = [], venue = "all", now = Date.now() }: {
+export function perpFreshness(rows: readonly Dated[], { funding = [], venue = "all", now = Date.now(), live = false }: {
   funding?: readonly Funded[]; venue?: string; now?: number;
+  /** Every row followed moves with its venue's socket: the view is a live feed, not the minute's read. */
+  live?: boolean;
 } = {}): HeadlessPaneFreshness {
   const sources = venuesOf(rows).map((id) => ({ source: venueName(id), asOf: new Date(Math.max(...rows.filter((row) => row.venue === id)
     .map((row) => Date.parse(row.observedAt)))).toISOString() }));
   const source = sources.length ? sources.map((entry) => entry.source).join(", ") : venue !== "all" ? venueName(venue) : null;
   const note = fundingNote(funding, now);
-  return { ...(source ? { source } : {}), sources, status: "delayed", maxAgeMinutes: 60, ...(note ? { note } : {}) };
+  return { ...(source ? { source } : {}), sources, status: live ? "live" : "delayed", maxAgeMinutes: 60, ...(note ? { note } : {}) };
 }
 
 /** What a capture reads of a row: when it was observed and whether the venue has stopped answering for it. */

package/src/plugins/builtin/perps/headless.ts

@@ -89,8 +89,10 @@ const aprNote = (rows: readonly PerpBoardRow[]) => {
 const requestedOf = (args: HeadlessPaneLoadArgs) => String(Array.isArray(args.argument) ? args.argument.join(" ") : args.argument ?? "").trim();
 // No tab named: a market opens its history, nothing opens the board, as the pane does.
 const tabOf = (args: HeadlessPaneLoadArgs) => PERP_TABS.find((tab) => tab === args.options.tab) ?? openingTab(requestedOf(args));
+// A free account's market opens its latest values under the title, so the title names the function, not the Pro history: a table the free view
+// locks is left out and named on the report's one Pro line (`lockedTable`), never marked on the title over the free ones.
 const TITLES: Record<typeof PERP_TABS[number], string> = { board: "Perpetual markets", rankings: "Perpetual rankings", compare: "Perpetual contracts across venues",
-  history: "Perpetual history (Pro)", evidence: "Perpetual evidence (Pro)" };
+  history: "Perpetuals", evidence: "Perpetual evidence" };
 const copy = (rows: readonly PerpBoardRow[]) => rows.map((row) => ({ ...row }));
 const more = (count: number, noun: string) => `${count.toLocaleString("en-US")} more ${noun} need Gloom Pro`;
 // A table the free view leaves empty is locked: the report leaves it out and its one Pro line says what Pro adds.

package/src/plugins/builtin/perps/list-perpetuals.ts

@@ -8,6 +8,7 @@ import { useResearchCloudSession } from "../shared/research-cloud-session";
 import { perpetualListing } from "../../../tickers/perpetual-listing";
 import { loadPerpSelection, loadPerpsEquities } from "./client";
 import { perpEquityIdentity } from "./equity-identity";
+import { useLivePerpRows } from "./live-rows";
 
 const STOCK_TYPES = new Set(["STK", "EQUITY", "STOCK", "COMMON STOCK"]);
 const listingKey = (listing: PerpEquityListing) => `${listing.symbol}:${listing.exchange}`;
@@ -26,6 +27,7 @@ function rowListing(ticker: TickerRecord): PerpEquityListing | null {
 const rowMarket = (ticker: TickerRecord) => perpetualListing(ticker.metadata.ticker, ticker.metadata.exchange)?.marketId ?? null;
 
 const NO_PERPETUALS: ListPerpetuals = { markets: new Map(), version: 0, stale: false };
+const NO_SYMBOLS: ReadonlySet<string> = new Set();
 
 export interface ListPerpetuals {
   /** Each row's contract by ticker, null for none; a row is missing while its first answer loads. */
@@ -55,7 +57,7 @@ async function loadOwnMarket(marketId: string, access: string, force: boolean):
  * A row's figures never wait on anything else: rows without a stock listing read as no perpetual at once, and a
  * failed or refused lookup leaves every row without one, as DES leaves out its perpetual row.
  */
-export function useListPerpetuals(tickers: readonly TickerRecord[], enabled: boolean): ListPerpetuals {
+export function useListPerpetuals(tickers: readonly TickerRecord[], enabled: boolean, liveSymbols: ReadonlySet<string> = NO_SYMBOLS): ListPerpetuals {
   const session = useResearchCloudSession();
   const plan = usePlanAccess();
   const accessKey = `${session.requestKey}:${plan.hasProAccess ? "pro" : "preview"}`;
@@ -98,7 +100,7 @@ export function useListPerpetuals(tickers: readonly TickerRecord[], enabled: boo
   useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
   const versionRef = useRef(0);
   const { data, loading } = resource;
-  return useMemo(() => {
+  const fetched = useMemo(() => {
     if (!enabled) return NO_PERPETUALS;
     const byListing = new Map<string, PerpBoardRow | null>();
     data?.listings.forEach((listing, index) => byListing.set(listingKey(listing), data.results[index]?.market ?? null));
@@ -112,7 +114,26 @@ export function useListPerpetuals(tickers: readonly TickerRecord[], enabled: boo
       // Still loading: the row's cell waits. Otherwise there is nothing to show.
       else if ((!key && !market) || !loading) markets.set(ticker.metadata.ticker, null);
     }
-    versionRef.current += 1;
-    return { markets, version: versionRef.current, stale: !!data?.stale };
+    return { markets, version: 0, stale: !!data?.stale };
   }, [data, enabled, loading, tickers]);
+  // The contracts of the rows in view follow the quote stream, as many as useLivePerpRows follows; each is subscribed
+  // once however many rows share it.
+  const liveRows = useMemo(() => {
+    const rows = new Map<string, PerpBoardRow>();
+    for (const symbol of liveSymbols) {
+      const row = fetched.markets.get(symbol);
+      if (row) rows.set(row.marketId, row);
+    }
+    return [...rows.values()];
+  }, [fetched, liveSymbols]);
+  const live = useLivePerpRows(liveRows, { surface: "watchlist", enabled: enabled && liveRows.length > 0 });
+  return useMemo(() => {
+    if (fetched === NO_PERPETUALS) return NO_PERPETUALS;
+    const byMarket = new Map(live.rows.map((row) => [row.marketId, row]));
+    const markets = byMarket.size
+      ? new Map([...fetched.markets].map(([symbol, row]) => [symbol, row ? byMarket.get(row.marketId) ?? row : row]))
+      : fetched.markets;
+    versionRef.current += 1;
+    return { markets, version: versionRef.current, stale: fetched.stale };
+  }, [fetched, live.rows]);
 }