gloomberb 0.17.0 → 0.17.2

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

@@ -27,7 +27,9 @@ export const optionsScenarioModule: PluginModule = {
   paneTemplates: [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.",
-    keywords: ["osa", "options", "scenario", "payoff", "strategy", "greeks", "hedge", "hedging", "collar", "protective put", "put spread"],
+    // OSA owns the phrases; OMON and VCA carry the same words without them, so a put-selling search finds all three, OSA first.
+    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,
     settings: (symbol, _context, options) => ({ symbol, ...Object.fromEntries(scenarioSettingKeys
       .filter((key) => options?.values?.[key] != null).map((key) => [key, options!.values![key]])) }),

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

@@ -21,7 +21,10 @@ 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, type ScenarioMarketSnapshot } from "./client";
+import { loadScenarioMarket, scenarioControlsFromSettings, scenarioPositionFromSettings, scenarioSpotBasis, type ScenarioMarketSnapshot } from "./client";
+import { cashSecuredPut, cspStatItems, loadNextEarningsDate } from "./csp";
+import { useAssetData } from "../../runtime";
+import { formatSpotTime } from "../options/model-spot";
 import { buildScenario, currencyLabel, scenarioCurrency, scenarioValueUnit, UNKNOWN_CURRENCY, type ScenarioLeg, type ScenarioPosition,
   type ScenarioControls, validatePosition } from "./model";
 import { EMPTY_SAVED_STRATEGIES, restoreSavedStrategies, type SavedScenarioStrategy } from "./state";
@@ -141,6 +144,19 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   }, [frozen, position, controls, seeded.error, controlState, baseControls.error]);
   const scenario = result.scenario;
   const error = localError ?? result.error;
+  // A cash-secured put reads the earnings calendar for whether a report falls before it expires.
+  const assetData = useAssetData();
+  const cspStrategy = settings.strategy === "csp";
+  const earningsLoader = useCallback(() => loadNextEarningsDate(assetData, underlying), [assetData, underlying]);
+  // A screenshot keeps the date its report read.
+  const frozenEarnings = Object.hasOwn(settings, "scenarioEarningsDate");
+  const earnings = useAsyncResource(cspStrategy && underlying && !frozenEarnings ? earningsLoader : null);
+  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;
+  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]);
   // The report's Hedge budget, from the same position and quotes; a live position sizes at its live quotes and spot.
   const hedge = useMemo(() => {
     if (!scenario) return { value: null, error: null };
@@ -230,13 +246,19 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
     && money(market.spot) !== money(position!.spot) ? ` · 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}` : ""}` : "";
+  // 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: [
     ...(resource.loading ? [{ id: "loading", parts: [{ text: "loading chain", tone: "muted" as const }] }] : []),
     ...(error ? [{ id: "error", parts: [{ text: error, tone: "warning" as const }] }] : []),
     ...(hedge.error ? [{ id: "hedge-error", parts: [{ text: hedge.error, tone: "warning" as const }] }] : []),
-    ...(live ? [{ id: "asof", parts: [{ text: `${live.basis} · as of ${new Date(live.observedAt).toISOString().slice(11, 19)} UTC`, tone: "muted" as const }] }]
-      : position ? [{ id: "asof", parts: [{ text: `${dateLabel(position.asOf)} · ${market?.source ? "market" : "input assumptions"}${midVolatility}`, tone: "muted" as const }] }] : []),
-  ], hints }), [hints, position, market?.source, resource.loading, error, hedge.error, live?.basis, live?.observedAt, midVolatility]);
+    ...(live ? [{ id: "asof", parts: [{ text: `${live.basis} · ${spotText} · ${new Date(live.observedAt).toISOString().slice(11, 19)} UTC`, tone: "muted" as const }],
+      variants: [[{ text: shortSpotText, tone: "muted" as const }]] }]
+      : position ? [{ id: "asof", parts: [{ text: `${spotText} · ${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 });
   // A choice dialog (scenario date, saved strategies) owns the keys while open.
   const dialogOpen = useDialogState((state) => state.isOpen);
@@ -262,7 +284,9 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
   const stats: StatItem[] = scenario ? [
     { id: "pnl", label: "P&L", value: money(scenario.valuation.pnl), detail: valueUnit,
       tone: cents(scenario.valuation.pnl) >= 0 ? "positive" : "negative" },
-    { id: "spot", label: "Spot", value: money(scenario.position.spot), detail: "per share" },
+    // 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" },
     { 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) },
@@ -274,9 +298,10 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
     { id: "rho", label: "Rho", value: money(scenario.valuation.rhoPerPoint), detail: "per pt" },
   ] : [];
   const hedgeItems = hedge.value ? hedgeStatItems(hedge.value) : [];
+  const cspItems = csp ? cspStatItems(csp) : [];
   // The query bar and the stat band sit above the content only once a scenario prices.
   const bodyHeight = Math.max(3, height - tabRows - (scenario ? 1 + statGridRows(stats, width) : 0)
-    - (hedgeItems.length ? statGridRows(hedgeItems, width) : 0));
+    - (hedgeItems.length ? statGridRows(hedgeItems, width) : 0) - (cspItems.length ? statGridRows(cspItems, width) : 0));
   const legColumns: DataTableColumn[] = [{ id: "quantity", label: "Contracts", width: 10, align: "right" },
     { id: "side", label: "Option", width: 7, align: "left" }, { id: "strike", label: "Strike", width: 11, align: "right" },
     { id: "expiration", label: "Expiry", width: 12, align: "left" }, { id: "price", label: "Entry / share", width: 14, align: "right" },
@@ -332,6 +357,7 @@ export function OptionsScenarioPane({ width, height, focused }: PaneProps) {
       />
       <StatGrid items={stats} width={width} />
       {hedgeItems.length > 0 && <StatGrid items={hedgeItems} width={width} />}
+      {cspItems.length > 0 && <StatGrid items={cspItems} width={width} />}
     </>}
     {!position?.legs.length && !scenario ? <PaneStatusBody loading={!!resource.loading && !market} error={seeded.error} subject="scenario inputs">
       <Box paddingX={1}><EmptyState title="Build an options position." actions={<Button label="Add leg" onPress={addTyped} />} /></Box>

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

@@ -2,7 +2,7 @@ import type { AppConfig } from "../../../types/config";
 import type { Portfolio, PortfolioCash, TickerPosition, TickerRecord, Watchlist } from "../../../types/ticker";
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
 import { slugifyName } from "../../../utils/slugify";
-import { parseCollectionRef } from "../cloud/team/collections";
+import { parseCollectionRef } from "../../../team/collections";
 import { findNamedCollection } from "../../../portfolio/collection-name";
 
 export interface DeleteWatchlistResult {

package/src/plugins/builtin/portfolio-list/pane/remove-ticker.ts

@@ -2,7 +2,7 @@ import { t, tf } from "../../../../i18n";
 import { formatMarketCost, formatMarketQuantity } from "../../../../market-data/market/format";
 import type { AppConfig } from "../../../../types/config";
 import type { TickerRecord } from "../../../../types/ticker";
-import { parseCollectionRef } from "../../cloud/team/collections";
+import { parseCollectionRef } from "../../../../team/collections";
 import { isManualPortfolio, removeTickerFromPortfolio, removeTickerFromWatchlist } from "../mutations";
 
 export interface RemovableCollection {

package/src/plugins/builtin/research/corporate-actions-pane.tsx

@@ -285,9 +285,11 @@ export function buildEventDetail({
   const comparison: EventDetailBlock[] = [
     ...(row.dateStatus && row.dateStatus !== "reported" ? [detailRow("Report date", row.date, row.dateStatus)] : []),
     detailRow("Actual", earningsInput(row.epsActual, row.epsCurrency),
-      row.epsBasis === "unknown" ? "basis unknown" : row.epsBasis),
+      row.epsActual == null ? undefined : row.epsBasis === "unknown" ? "basis unknown" : row.epsBasis),
+    // An upcoming estimate names its basis when it is adjusted (a REIT's FFO consensus).
     detailRow("Consensus", earningsInput(row.epsEstimate, row.epsCurrency),
-      row.epsAnalysts != null ? `${row.epsAnalysts} analysts` : undefined),
+      [row.epsAnalysts != null ? `${row.epsAnalysts} analysts` : null,
+        row.epsActual == null && row.epsBasis === "adjusted" ? "adjusted" : null].filter(Boolean).join(", ") || undefined),
   ];
   if (row.epsDifference != null) comparison.push(detailRow("Difference", earningsInput(row.epsDifference, row.epsCurrency)));
   if (row.surprisePercent != null) {

package/src/plugins/builtin/research/event-model.ts

@@ -20,6 +20,7 @@ import {
   epsBasisName,
   epsSurprise,
   inFiscalMonth,
+  showsEpsBasis,
   type EpsBasisName,
 } from "../shared/earnings-report";
 
@@ -46,7 +47,7 @@ export interface EventRow {
   epsEstimate?: number;
   epsDifference?: number;
   surprisePercent?: number;
-  /** A reported figure's basis; the same quarter is named the same way in ERN. */
+  /** A reported figure's basis, or an upcoming estimate's when it is adjusted; the same quarter is named the same way in ERN. */
   epsBasis?: EpsBasisName;
   /** Analysts behind `epsEstimate`, when known. */
   epsAnalysts?: number;
@@ -224,11 +225,12 @@ function ttmRow(
   };
 }
 
-/** A reported row names its basis and beat; a pending one whether its date is announced and its analysts. */
+/** A reported row names its basis and beat; a pending one whether its date is announced, its analysts and an adjusted estimate's basis. */
 function earningsDetail(earning: CorporateActionsData["earnings"][number]): string {
   if (earning.epsActual == null) {
     const status = earningsDateStatus(earning.dateStatus);
-    const parts = [status === "reported" ? null : status, earning.epsAnalysts != null ? `${earning.epsAnalysts} analysts` : null];
+    const parts = [status === "reported" ? null : status, earning.epsAnalysts != null ? `${earning.epsAnalysts} analysts` : null,
+      earningsEpsBasis(earning.epsBasis) === "adjusted" ? BASIS_TEXT.adjusted : null];
     return parts.filter(Boolean).join(", ") || "Pending";
   }
   const basis = BASIS_TEXT[epsBasisName(earningsEpsBasis(earning.epsBasis))];
@@ -341,7 +343,8 @@ export function buildEventRows(
       epsEstimate: earning.epsEstimate,
       epsDifference: earning.epsActual == null ? undefined : earning.difference,
       surprisePercent,
-      epsBasis: earning.epsActual == null ? undefined : epsBasisName(earningsEpsBasis(earning.epsBasis)),
+      epsBasis: showsEpsBasis({ epsActual: earning.epsActual, epsBasis: earningsEpsBasis(earning.epsBasis) })
+        ? epsBasisName(earningsEpsBasis(earning.epsBasis)) : undefined,
       epsAnalysts: earning.epsAnalysts,
       dateStatus: earningsDateStatus(earning.dateStatus) ?? undefined,
       providerId: data?.providerId,

package/src/plugins/builtin/risk-factors/index.tsx

@@ -1,4 +1,5 @@
 import type { PluginModule } from "../plugin-module";
+import { proLockNote } from "../shared/pro-lock-note";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import {
   attachRiskFactorsPersistence,
@@ -13,6 +14,21 @@ import { isKnownNonUsListing } from "../../../utils/sec";
 const description =
   "The company's 10-K risk factors, and what was added, dropped, or rewritten since the prior year.";
 
+/**
+ * RISK is Pro whole (`useProFeatureWall`). The 10-Ks it reads are in the SEC
+ * filing list, which needs no account: `filings` lists them with a link to
+ * each, where Item 1A is the risk factors as written, without RISK's grouping
+ * or its changes since the year before.
+ */
+function riskFactorsLockNote(lock: { gate: "sign-in" | "pro"; symbol: string | null }): string {
+  return proLockNote(lock, {
+    token: "RISK",
+    does: "it groups a 10-K's risk factors by theme and shows what was added, dropped or reworded since the year before",
+    shows: "it",
+    free: (ticker, company) => `gloomberb filings ${ticker} --form 10-K lists ${company}'s annual reports, each with its filing date and a link to the filing, whose Item 1A holds the risk factors as written.`,
+  });
+}
+
 export const riskFactorsModule: PluginModule = {
   setup(ctx) {
     attachRiskFactorsPersistence(ctx.persistence);
@@ -33,6 +49,8 @@ export const riskFactorsModule: PluginModule = {
   panes: [
     {
       id: RISK_FACTORS_PANE_ID,
+      reportLockNote: riskFactorsLockNote,
+      reportRequirements: ["Gloom Cloud Pro"],
       name: "Risk Factors",
       icon: "R",
       component: RiskFactorsPane,

package/src/plugins/builtin/risk-factors/pane.tsx

@@ -283,7 +283,8 @@ function RiskFactorsReader({
               </Box>
             ) : null}
             <Box flexDirection="column">
-              <SectionHeading marginTop={1} title="All Risk Factors" />
+              {/* The title names the pane; the heading only marks where the list starts after another section. */}
+              {report.overview || diff || report.notes.top.length > 0 ? <SectionHeading marginTop={1} title="All Risk Factors" /> : null}
               {report.risks.map((risk, index) => (
                 <Prose
                   key={`${index}-${risk.heading}`}

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

@@ -1,3 +1,4 @@
+import { ApiRequestError } from "../../../api-client/errors";
 import type {
   ScannerFeedEvent,
   ScannerFlowPayload,
@@ -18,6 +19,8 @@ import {
   filterFlowEvents,
   type FlowFilters,
 } from "./flow-model";
+import { explainRefusal } from "../shared/cloud-denied";
+import { flowLockNote } from "./lock-note";
 import { buildHiloBarRows, filterHiloRows, formatHiloPrice, type HiloMinPrice, type HiloSort } from "./hilo-model";
 
 type ScannerName = "hilo" | "flow";
@@ -66,7 +69,10 @@ function loadScannerSnapshot<T extends ScannerPayload>(
     signal.addEventListener("abort", onAbort, { once: true });
     unsubscribe = client.subscribeScanner(scanner, (event: ScannerFeedEvent) => {
       if (event.type === "denied") {
-        finish(() => reject(new Error(event.reason === "pro_required" ? "Pro access required" : "Sign in required")));
+        // The refusal a read gets from the server: 402 for a plan without access, 401 for no session.
+        finish(() => reject(event.reason === "pro_required"
+          ? new ApiRequestError("Pro access required", 402)
+          : new ApiRequestError("Sign in required", 401)));
         return;
       }
       const payload = event.payload as T;
@@ -277,7 +283,8 @@ function createFlowHeadless(
     ],
     describe: "Options Flow",
     async load(args, ctx) {
-      const payload = await dependencies.load(args, ctx.apiClient, ctx.signal);
+      const payload = await dependencies.load(args, ctx.apiClient, ctx.signal)
+        .catch((error: unknown) => { throw explainRefusal(error, flowLockNote, { symbol: null }); });
       return projectFlowSnapshot(payload, {
         ...DEFAULT_FLOW_FILTERS,
         ...(args.options as Partial<FlowFilters>),

package/src/plugins/builtin/scanner/index.ts

@@ -4,6 +4,7 @@ import { DEFAULT_FLOW_FILTERS, FLOW_FILTER_OPTIONS } from "./flow-model";
 import FlowPane from "./flow-pane";
 import HiloPane from "./hilo-pane";
 import { flowHeadless, hiloHeadless } from "./headless";
+import { flowLockNote } from "./lock-note";
 
 
 const HILO_PANE_ID = "scanner-hilo";
@@ -80,6 +81,8 @@ export const scannerModule: PluginModule = {
     },
     {
       id: FLOW_PANE_ID,
+      reportLockNote: flowLockNote,
+      reportRequirements: ["Gloom Cloud Pro"],
       name: "Options Flow",
       icon: "F",
       component: FlowPane,

package/src/plugins/builtin/scanner/lock-note.ts

@@ -0,0 +1,17 @@
+import type { PaneLock } from "../../../types/plugin";
+import { proLockNote } from "../shared/pro-lock-note";
+
+/**
+ * FLOW is Pro whole: the one scanner with no delayed tier to fall back to.
+ * The options chain needs no account and lists each contract's day volume and
+ * open interest, the raw counts behind a sweep or a block, without the prints.
+ */
+export function flowLockNote(lock: PaneLock): string {
+  return proLockNote(lock, {
+    token: "FLOW",
+    argument: "none",
+    does: "it streams real-time sweeps, blocks and large premium prints across US options exchanges",
+    shows: "it",
+    free: (ticker, company) => `gloomberb options ${ticker} lists ${company}'s option chain, each contract with its volume and open interest.`,
+  });
+}

package/src/plugins/builtin/series-inventory.ts

@@ -37,6 +37,7 @@ export const SERIES_INVENTORY: readonly SeriesInventoryEntry[] = [
   { module: "realized-vol", chart: "Realized volatility cone and rolling windows", notInCatalog: "derived", reason: "The composer's realized volatility study draws it from any price series." },
   { module: "vol-surface", chart: "Implied volatility surface by strike and expiry", notInCatalog: "not-a-time-series", reason: "A surface over strike and tenor." },
   { module: "options-positioning", chart: "Open interest and gamma by strike and expiry", notInCatalog: "not-a-time-series", reason: "Plotted by strike and expiry, not by date." },
+  { module: "options-calculator", chart: "A linked option contract's daily premium", series: ["option:*"] },
   { module: "options-scenario", chart: "Option payoff by underlying price", notInCatalog: "not-a-time-series", reason: "A payoff curve over prices." },
   { module: "kelly-sizer", chart: "Position size against win rate", notInCatalog: "account", reason: "Drawn from the inputs typed into the sizer." },
   { module: "yield-curve", chart: "Treasury curve and each maturity's history", series: ["ust:*", "fred:T10Y2Y", "fred:T10Y3M", "fred:DFII*"] },
@@ -54,7 +55,7 @@ export const SERIES_INVENTORY: readonly SeriesInventoryEntry[] = [
   { module: "credit-documents", chart: "Principal due by year", notInCatalog: "not-a-time-series", reason: "A maturity schedule, not a history." },
   { module: "debt-maturities", chart: "A company's principal and the share due soon, across annual filings", series: ["debt-maturities:*"] },
   { module: "debt-maturities", chart: "A company's maturity wall", notInCatalog: "not-a-time-series", reason: "A schedule by maturity year from one filing; its total and near-term shares across filings are in the catalog." },
-  { module: "doe", chart: "Weekly oil and gas inventories against their five-year range", series: ["doe:*"] },
+  { module: "doe", chart: "Weekly oil and gas inventories against their five-year range, and US retail gasoline and diesel prices", series: ["doe:*"] },
   { module: "cot", chart: "Net positioning by trader class, over the front-month price", series: ["cot:*"] },
   { module: "futures", chart: "Front-month futures board, charted from the board", series: ["fut:*"] },
   { module: "futures-curve", chart: "Futures curve by contract month", notInCatalog: "not-a-time-series", reason: "Plotted by delivery month; each front month is in the catalog as FUT:code." },

package/src/plugins/builtin/shared/cloud-denied.ts

@@ -1,15 +1,46 @@
 import { ApiRequestError } from "../../../api-client/errors";
+import type { PaneLock } from "../../../types/plugin";
+import { lockNoteReason } from "./pro-lock-note";
 
 /** A Gloom Cloud refusal the reader can act on: signed out, an unverified email, or no Pro plan. */
-export type CloudDeniedStatus = 401 | 402 | 403;
+type CloudDeniedStatus = 401 | 402 | 403;
 
-/** The account refusal behind a failed request, or null when it failed for another reason. */
-export function cloudDeniedStatus(error: unknown): CloudDeniedStatus | null {
-  const status = error instanceof ApiRequestError ? error.status : undefined;
-  return status === 401 || status === 402 || status === 403 ? status : null;
+/**
+ * The account refusal behind a failed request, or null when it failed for
+ * another reason. Looks through the errors that wrap it, so a message written
+ * for the reader still says which wall it stands for.
+ */
+function cloudDeniedStatus(error: unknown): CloudDeniedStatus | null {
+  for (let current = error, depth = 0; current && depth < 4; depth += 1) {
+    const status = current instanceof ApiRequestError ? current.status : undefined;
+    if (status === 401 || status === 402 || status === 403) return status;
+    current = current instanceof Error ? current.cause : undefined;
+  }
+  return null;
 }
 
-/** What the refused account needs, as a report finishes "JOBS needs ...". */
-export function cloudAccountNeed(status: CloudDeniedStatus): string {
-  return status === 401 ? "sign-in" : status === 403 ? "a verified email" : "Gloom Pro";
+/**
+ * The wall a refused read stands for, as the pane's own wall puts it up: no
+ * session is the sign-in wall, an unverified email the same wall asking for
+ * the email, a plan without access the Pro wall.
+ */
+export function refusedLock(error: unknown): Pick<PaneLock, "gate" | "verifyEmail"> | null {
+  const status = cloudDeniedStatus(error);
+  if (status === 402) return { gate: "pro" };
+  return status ? { gate: "sign-in", ...status === 403 ? { verifyEmail: true } : {} } : null;
+}
+
+/**
+ * What a headless read throws when the server refused it behind a wall: the
+ * pane's lock note on one line, so every consumer of the read says what is
+ * locked and how to unlock it, with the refusal as its cause for `fn`, which
+ * prints the whole note. Any other failure is returned as it is.
+ */
+export function explainRefusal(
+  error: unknown,
+  note: (lock: PaneLock) => string,
+  lock: Pick<PaneLock, "symbol" | "token">,
+): unknown {
+  const refused = refusedLock(error);
+  return refused ? new Error(lockNoteReason(note({ ...refused, ...lock })), { cause: error }) : error;
 }

package/src/plugins/builtin/shared/earnings-report.ts

@@ -2,9 +2,10 @@ import type { EarningsDateStatus, EarningsEpsBasis } from "../../../types/financ
 
 /**
  * How every earnings surface (ERN, EE, the corporate-actions events and
- * their headless rows) reads and names a reported quarter's EPS basis and a
- * report date's status. Gloom Cloud resolves one figure per quarter; this
- * keeps the panes from naming it differently.
+ * their headless rows) reads and names a reported quarter's EPS basis, an
+ * upcoming estimate's when Gloom Cloud names one, and a report date's
+ * status. Gloom Cloud resolves one figure per quarter; this keeps the panes
+ * from naming it differently.
  */
 
 const BASES: ReadonlySet<string> = new Set<EarningsEpsBasis>(["gaap", "adjusted"]);
@@ -27,13 +28,18 @@ export function dateStatusFromEstimateFlag(isDateEstimate: boolean | null | unde
 export type EpsBasisName = "GAAP" | "adjusted" | "unknown";
 
 /** What the basis names mean, in every report's metadata. */
-export const EPS_BASIS_NOTE = "One reported EPS per quarter. GAAP: the quarter's diluted statement EPS. adjusted: the consensus-basis figure the estimate is measured against, which leaves out items the statements include. unknown: no statement on a comparable share basis to tell.";
+export const EPS_BASIS_NOTE = "One reported EPS per quarter. GAAP: the quarter's diluted statement EPS. adjusted: the consensus-basis figure the estimate is measured against, which leaves out items the statements include. unknown: no statement on a comparable share basis to tell. An upcoming report's estimate is labelled adjusted when it is the consensus on the adjusted basis the company's reports are on (a REIT's FFO), not a GAAP forecast.";
 
 /** The basis as rows, exports and tools name it. */
 export function epsBasisName(basis: EarningsEpsBasis | null): EpsBasisName {
   return basis === "gaap" ? "GAAP" : basis === "adjusted" ? "adjusted" : "unknown";
 }
 
+/** Whether a row names a basis: a reported figure always does, an upcoming estimate only when Gloom Cloud labels it. */
+export function showsEpsBasis(row: { epsActual: number | null | undefined; epsBasis: EarningsEpsBasis | null | undefined }): boolean {
+  return row.epsActual != null || row.epsBasis != null;
+}
+
 /** The basis in a table cell or a detail line. */
 export function epsBasisShort(basis: EarningsEpsBasis | null): string {
   return basis === "gaap" ? "GAAP" : basis === "adjusted" ? "adj" : "?";

package/src/plugins/builtin/shared/pro-lock-note.ts

@@ -0,0 +1,58 @@
+import type { PaneLock } from "../../../types/plugin";
+
+/** A lock note on one line, as JSON and CSV say why a locked report is empty and as an error carries it. */
+export function lockNoteReason(note: string): string {
+  return note.replace(/\s*\n\s*/g, " ");
+}
+
+/**
+ * The `reportLockNote` of a pane its wall covers whole (`useProFeatureWall`, a
+ * scanner's denied state): what the function is and that a wall shows none of
+ * it, what a free reader can still get and the command that reads it, and how
+ * to unlock it. One shape for every lock a reader meets in `fn`, so a refused
+ * read never ends in a bare "Sign in required".
+ */
+export function proLockNote(
+  { gate, symbol, token: typed, verifyEmail }: PaneLock,
+  pane: {
+    /** The function's shortcut, such as `EK`; a pane that serves several names the one run in the lock. */
+    token: string;
+    /** What the function does, finishing "EK is part of Gloom Cloud Pro: it ...". */
+    does: string;
+    /** What the wall hides, as the object of "none of" and "to read": "it" or "them". */
+    shows: "it" | "them";
+    /**
+     * The free route and what it lists, finishing "Free, with no sign-in: ...".
+     * Name one only after running it signed out; leave it out when none answers.
+     */
+    free?(ticker: string, company: string): string;
+    /** What the wall asks for: Gloom Cloud Pro (default), or only a free Gloom account. */
+    needs?: "pro" | "sign-in";
+    /**
+     * Whether the function takes a ticker: `none` for a board such as FLOW,
+     * `optional` for one that also lists every company (CALLS, JOBS), where the
+     * command repeats the ticker only when the reader gave one. Default `ticker`.
+     */
+    argument?: "ticker" | "optional" | "none";
+  },
+): string {
+  const token = typed ?? pane.token;
+  const ticker = symbol ?? "<ticker>";
+  // A plan refused at the server is Pro whatever the function usually asks for.
+  const pro = pane.needs !== "sign-in" || gate === "pro";
+  const without = gate === "pro" ? "On a free account" : verifyEmail ? "Until the email is verified" : "Signed out";
+  const what = pro ? "is part of Gloom Cloud Pro" : "needs a free Gloom sign-in";
+  const account = verifyEmail
+    ? "verify your email (Ctrl+P, Resend Verification Email)"
+    : `log in or sign up${pro ? "" : " free"} from the command bar (Ctrl+P, Log In or Sign Up)`;
+  const unlock = gate === "pro"
+    ? `To read ${pane.shows} in ${token}, upgrade in the app (gloomberb, then Ctrl+P, UPGRADE)`
+    : `To read ${pane.shows} in ${token}, open the app (gloomberb), ${account}${pro ? ", then upgrade (Ctrl+P, UPGRADE)" : ""}`;
+  const bare = pane.argument === "none" || (pane.argument === "optional" && !symbol);
+  const command = bare ? `gloomberb fn ${token}` : `gloomberb fn ${token} ${ticker}`;
+  return [
+    `${token} ${what}: ${pane.does}. ${without} it shows none of ${pane.shows}.`,
+    ...pane.free ? [`Free, with no sign-in: ${pane.free(ticker, symbol ?? "the company")}`] : [],
+    `${unlock}; ${command} then reads with that session.`,
+  ].join("\n");
+}

package/src/plugins/builtin/shared/series-list-detail.tsx

@@ -10,6 +10,7 @@ import {
 } from "../../../components";
 import type { DataTableViewProps } from "../../../components/data-table/view";
 import { handleRefreshKey } from "../../../components/data-table/table-pane";
+import { FILL_REST } from "../../../components/ui/fill";
 import { useShortcut } from "../../../react/input";
 import { Box, ScrollBox, useUiCapabilities } from "../../../ui";
 import { isPlainKey } from "../../../utils/keyboard";
@@ -171,13 +172,17 @@ export function SeriesListDetail<Row, Column extends DataTableColumn, R extends
   // pane height leaves its lower content clipped outside the scroll viewport.
   const detailHeight = split ? bodyHeight : Math.max(1, bodyHeight - tableHeight);
   const bodyFocused = focused && !list.searchFocused;
+  // On the desktop and the web the query bar is taller than a row, so the
+  // split table and the detail take what is left under it by flex and end at
+  // the pane footer; the row counts above stay the terminal's.
+  const fill = nativePaneChrome ? FILL_REST : null;
 
   return (
-    <Box flexDirection="column" width={width} height={height}>
+    <Box flexDirection="column" width={width} {...(fill ?? { height })}>
       <QueryBar width={width} search={{ ...list.search, placeholder: searchPlaceholder }} filters={filters} view={list.range} />
-      <Box flexDirection={split ? "row" : "column"} flexGrow={1} overflow="hidden">
+      <Box flexDirection={split ? "row" : "column"} flexGrow={1} overflow="hidden" {...(fill ? { flexBasis: 0, minHeight: 0 } : {})}>
         <Box flexDirection="column" width={listWidth} flexShrink={0}>
-          <Box flexDirection="column" width={listWidth} height={tableHeight} flexShrink={0} overflow="hidden">
+          <Box flexDirection="column" width={listWidth} overflow="hidden" {...(fill && split ? fill : { height: tableHeight, flexShrink: 0 })}>
             <DataTableView<Row, Column>
               focused={bodyFocused}
               rootWidth={listWidth}
@@ -201,8 +206,8 @@ export function SeriesListDetail<Row, Column extends DataTableColumn, R extends
           </Box>
         </Box>
 
-        <Box flexDirection="column" flexGrow={1} width={detailWidth} height={detailHeight} overflow="hidden">
-          <ScrollBox height={detailHeight} scrollY focusable={false}>
+        <Box flexDirection="column" width={detailWidth} overflow="hidden" {...(fill ? split ? { flexGrow: 1, minHeight: 0 } : fill : { flexGrow: 1, height: detailHeight })}>
+          <ScrollBox scrollY focusable={false} {...(fill ? fill : { height: detailHeight })}>
             {renderDetail({ width: detailContentWidth, height: detailHeight, focused: bodyFocused })}
           </ScrollBox>
         </Box>

package/src/plugins/builtin/social-mentions/client.ts

@@ -47,7 +47,7 @@ export function validateSocialMentions(payload: SocialMentionsPayload, symbol: s
     || payload.wikipedia !== undefined && !validWikipedia(payload.wikipedia)
     || payload.reddit !== undefined && !validReddit(payload.reddit)
     || !Array.isArray(payload.pending) || !Array.isArray(payload.warnings) || payload.warnings.some((warning) => typeof warning !== "string"))
-    throw new Error("Gloom Cloud returned invalid social mention history");
+    throw new Error("Social mention history is invalid");
   return payload;
 }
 
@@ -55,7 +55,7 @@ export async function fetchSocialMentions(symbol: string, range: SocialMentionsR
   client: Pick<typeof apiClient, "getCloudSocialMentions"> = apiClient): Promise<SocialMentionsPayload> {
   try { return validateSocialMentions(await client.getCloudSocialMentions(symbol, range), symbol, range); }
   catch (error) {
-    if (error instanceof ApiRequestError && error.status === 404) throw new Error("Social mentions are not available on this Gloom Cloud server yet");
+    if (error instanceof ApiRequestError && error.status === 404) throw new Error("Social mentions are not available yet");
     throw error;
   }
 }
@@ -77,7 +77,7 @@ export async function loadSocialMentionPosts(symbol: string, date: string): Prom
   const result = await socialMentionPostsCache.load(`${symbol}:${date}`, async () => {
     const data = await apiClient.getCloudSocialMentionPosts(symbol, date);
     if (data?.symbol !== symbol || data.day !== date || !Array.isArray(data.posts) || !data.posts.every(validPost))
-      throw new Error("Gloom Cloud returned invalid social posts");
+      throw new Error("Social posts are invalid");
     return data;
   });
   if (result.error && !result.data) throw result.error;

package/src/plugins/builtin/social-mentions/headless.ts

@@ -1,12 +1,14 @@
 import type { SocialMentionsRange } from "../../../api-client/social-mentions";
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
+import { explainRefusal } from "../shared/cloud-denied";
 import { fetchSocialMentions } from "./client";
+import { socialMentionsLockNote } from "./lock-note";
 import { socialCount, socialDayRows, socialRatio, socialStance, topPostCell } from "./model";
 
 export const socialMentionsHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Ticker with a searchable cashtag (up to six letters and digits).", placeholder: "ticker" },
   freshness: { source: "X posts", status: "not-a-feed", basis: "daily post counts" },
-  discovery: { aliases: ["BUZZ"], dataRequirements: ["Gloom Cloud X mention history"],
+  discovery: { aliases: ["BUZZ"], dataRequirements: ["Free Gloom sign-in", "Gloom Cloud X mention history"],
     limitations: ["Daily $cashtag posts on X in UTC days, spam included.", "Top posts and stance cover days that were looked up.", "Views exist from 2022-12-22."] },
   options: [
     { key: "range", type: "enum", description: "History window.", values: [{ value: "1y" }, { value: "5y" }, { value: "max" }], defaultValue: "1y", settingKey: "socialRange" },
@@ -14,7 +16,9 @@ export const socialMentionsHeadless: HeadlessPaneDefinition<"bundle"> = {
   describe: (args) => `Social mentions | ${args.symbols[0]}`,
   async load(args, ctx) {
     const range = (["1y", "5y", "max"].includes(String(args.options.range)) ? args.options.range : "1y") as SocialMentionsRange;
-    const data = await fetchSocialMentions(String(args.symbols[0]).toUpperCase(), range, ctx.apiClient);
+    const symbol = String(args.symbols[0]).toUpperCase();
+    const data = await fetchSocialMentions(symbol, range, ctx.apiClient)
+      .catch((error: unknown) => { throw explainRefusal(error, socialMentionsLockNote, { symbol }); });
     return { complete: !data.pending.length, errors: data.warnings,
       sections: [{ title: "Daily posts on X", columns: [
         { key: "day", header: "Date" },

package/src/plugins/builtin/social-mentions/index.tsx

@@ -3,6 +3,7 @@ import { SOCIAL_MENTION_SERIES } from "./series";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import { socialMentionPostsCache, socialMentionsCache } from "./client";
 import { socialMentionsHeadless } from "./headless";
+import { socialMentionsLockNote } from "./lock-note";
 import { SocialMentionsPane } from "./pane";
 
 const socialMentionsSettings = [
@@ -11,7 +12,7 @@ const socialMentionsSettings = [
 ];
 export const socialMentionsModule: PluginModule = {
   series: SOCIAL_MENTION_SERIES,
-  panes: [{ id: "social-mentions", name: "Social Mentions", icon: "B", component: SocialMentionsPane,
+  panes: [{ id: "social-mentions", reportLockNote: socialMentionsLockNote, name: "Social Mentions", icon: "B", component: SocialMentionsPane,
     defaultPosition: "right", tickerFollower: true, defaultMode: "floating", defaultFloatingSize: { width: 96, height: 30 },
     tableExport: true, headless: socialMentionsHeadless, settings: { title: "Social Mentions", fields: socialMentionsSettings } }],
   paneTemplates: [{ ...createTickerSurfacePaneTemplate({ id: "social-mentions-pane", paneId: "social-mentions", label: "Social Mentions",

package/src/plugins/builtin/social-mentions/lock-note.ts

@@ -0,0 +1,15 @@
+import type { PaneLock } from "../../../types/plugin";
+import { proLockNote } from "../shared/pro-lock-note";
+
+/**
+ * BUZZ needs a signed-in account, not a plan. No command reads the posts it
+ * counts without one, so the note names no free route.
+ */
+export function socialMentionsLockNote(lock: PaneLock): string {
+  return proLockNote(lock, {
+    token: "BUZZ",
+    needs: "sign-in",
+    does: "it counts the daily posts on X that name a company's cashtag, with the top posts and their stance",
+    shows: "it",
+  });
+}