@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/plugins/builtin/ipo-calendar/headless.ts

@@ -9,11 +9,13 @@ import { fetchIpoCalendar } from "./client";
 import {
   calendarDate,
   filterIpoDeals,
+  formatIpoLockupEnd,
   formatIpoPrice,
   formatIpoReturn,
   formatIpoSize,
   IPO_STATUSES,
   ipoBoardStatus,
+  ipoKeyword,
   isIpoTab,
   marketsBehind,
   marketsBehindText,
@@ -21,7 +23,10 @@ import {
   DEFAULT_IPO_SORT,
   type IpoTab,
 } from "./model";
+import { ipoDetailSentences, loadIpoLockupNews, type IpoLockupStory } from "./listing-ipo";
 import { REPORT_FILTER, REPORT_ROWS } from "../shared/headless-options";
+import { DATE_OPTION_EXAMPLES, isoDateOption } from "../../../utils/calendar-date";
+import { logFailure } from "../../../utils/log-failure";
 
 const COLUMNS: HeadlessPaneColumn[] = [
   { key: "ticker", header: "Ticker" },
@@ -33,6 +38,8 @@ const COLUMNS: HeadlessPaneColumn[] = [
   { key: "price", header: "Price", align: "right" },
   { key: "offerSizeUsd", header: "Size", align: "right", format: (value) => formatIpoSize(value as number | null) },
   { key: "firstDayReturn", header: "Return", align: "right", format: (value) => formatIpoReturn(value as number | null) },
+  // A US IPO's estimated lock-up end: "~2026-11-02".
+  { key: "lockupEnds", header: "Lockup ends", format: (value) => formatIpoLockupEnd(typeof value === "string" ? value : null) },
 ];
 
 type StatusOption = IpoStatus | "all";
@@ -68,7 +75,7 @@ function toRow(deal: IpoDeal, now: Date) {
     status: ipoBoardStatus(deal, now),
     listingType: deal.listingType,
     currency: deal.currency,
-    price: formatIpoPrice(deal),
+    price: formatIpoPrice(deal, { full: true }),
     priceLow: deal.priceLow,
     priceHigh: deal.priceHigh,
     offerPrice: deal.offerPrice,
@@ -78,26 +85,60 @@ function toRow(deal: IpoDeal, now: Date) {
     firstDayClose: deal.firstDay?.close ?? null,
     firstDayReturn: deal.firstDay?.returnPct ?? null,
     filedDate: deal.filedDate,
+    lockupEnds: deal.lockup?.endsOn ?? null,
+    lockupBasis: deal.lockup?.basis ?? null,
+    prospectusDate: deal.lockup?.prospectusDate ?? null,
   };
 }
 
-function projectIpoCalendarHeadless(payload: IpoCalendarPayload, args: HeadlessPaneLoadArgs): HeadlessRowsResult {
+/** One deal found: its IPO in words, as `ticker` gives it, with its price now and its lock-up news. */
+interface IpoDealDetail {
+  price: number | null;
+  news: IpoLockupStory[];
+}
+
+/** Lock-up estimates soonest first, then the ones that have ended, latest first. */
+function byLockupEnd(deals: readonly IpoDeal[], now: Date): IpoDeal[] {
+  const today = now.toISOString().slice(0, 10);
+  const rank = (deal: IpoDeal) => (deal.lockup!.endsOn >= today ? 0 : 1);
+  return [...deals].sort((a, b) => rank(a) - rank(b)
+    || (rank(a) === 0 ? a.lockup!.endsOn.localeCompare(b.lockup!.endsOn) : b.lockup!.endsOn.localeCompare(a.lockup!.endsOn))
+    || a.id.localeCompare(b.id));
+}
+
+/** The most rows `--limit` lists. */
+const MAX_ROWS = 500;
+
+const SPAC_NOTE = "A SPAC's merger with its target (de-SPAC) is no IPO, so the calendar lists the SPACs' own IPOs.";
+
+export function projectIpoCalendarHeadless(
+  payload: IpoCalendarPayload,
+  args: HeadlessPaneLoadArgs,
+  detail: IpoDealDetail | null = null,
+  now = new Date(),
+): HeadlessRowsResult {
   const query = typeof args.argument === "string" ? args.argument.trim() : "";
   const region = regionOption(args);
   const status = statusOption(args);
   const limit = Number(args.options.limit ?? 50);
-  const now = new Date();
-  const matching = sortIpoDeals(
-    filterIpoDeals(payload.deals, region, query, now).filter((deal) => status === "all" || deal.status === status),
-    DEFAULT_IPO_SORT,
-    now,
-  );
+  const keyword = ipoKeyword(query);
+  const found = filterIpoDeals(payload.deals, region, query, now).filter((deal) => status === "all" || deal.status === status);
+  const matching = keyword === "lockup" ? byLockupEnd(found, now) : sortIpoDeals(found, DEFAULT_IPO_SORT, now);
   const rows = matching.slice(0, limit).map((deal) => toRow(deal, now));
   const behind = marketsBehindText(marketsBehind(payload.sources, region, payload.deals));
+  const single = matching.length === 1 && query && !keyword ? matching[0]! : null;
+  const notes = [
+    ...rows.length < matching.length
+      ? [`Showing ${rows.length} of ${matching.length} deals; --limit ${Math.min(matching.length, MAX_ROWS)} lists ${matching.length <= MAX_ROWS ? "them all" : "more"}.`]
+      : [],
+    ...single ? ipoDetailSentences(single, detail?.price ?? null, detail?.news ?? [], now) : [],
+    ...keyword === "spac" || keyword === "de-spac" ? [SPAC_NOTE] : [],
+  ];
   return {
     columns: COLUMNS,
     rows,
     ...(behind ? { errors: [behind] } : {}),
+    ...(notes.length ? { notes } : {}),
     metadata: {
       asOf: payload.asOf,
       total: matching.length,
@@ -149,7 +190,15 @@ export const ipoCalendarHeadless: HeadlessPaneDefinition<"rows"> = {
       type: "integer",
       defaultValue: 50,
       minimum: 1,
-      maximum: 500,
+      maximum: MAX_ROWS,
+    },
+    {
+      key: "from",
+      type: "string",
+      placeholder: "date",
+      description: `First listing date, as ${DATE_OPTION_EXAMPLES}; the calendar keeps a year of listings.`,
+      example: "--from 2025-11-01",
+      normalize: (value) => isoDateOption(value, "from"),
     },
   ],
   columns: COLUMNS,
@@ -164,7 +213,22 @@ export const ipoCalendarHeadless: HeadlessPaneDefinition<"rows"> = {
   async load(args, ctx) {
     // The default window has no filed or withdrawn deals, so a stage is asked for by name.
     const status = statusOption(args);
-    const params = status === "all" ? {} : { status };
-    return projectIpoCalendarHeadless(await fetchIpoCalendar(ctx.apiClient, ctx.signal, params), args);
+    const from = typeof args.options.from === "string" && args.options.from ? args.options.from : undefined;
+    const params = { ...(status === "all" ? {} : { status }), ...(from ? { from } : {}) };
+    const payload = await fetchIpoCalendar(ctx.apiClient, ctx.signal, params);
+    const projected = projectIpoCalendarHeadless(payload, args);
+    // One deal found: its price now and its lock-up news, which never fail the report.
+    const query = typeof args.argument === "string" ? args.argument.trim() : "";
+    const matched = projected.rows.length === 1 && query && !ipoKeyword(query)
+      ? payload.deals.find((deal) => deal.id === projected.rows[0]!.id) : undefined;
+    if (!matched?.symbol) return projected;
+    const [price, news] = await Promise.all([
+      matched.status === "listed"
+        ? ctx.marketData.getQuote(matched.symbol, matched.exchange ?? undefined).then((quote) => quote.price ?? null,
+          logFailure("plugins.ipo-calendar", "Load the price of an IPO failed", null))
+        : Promise.resolve(null),
+      loadIpoLockupNews(ctx.apiClient, matched).catch(logFailure("plugins.ipo-calendar", "Load an IPO's lock-up news failed", [] as IpoLockupStory[])),
+    ]);
+    return projectIpoCalendarHeadless(payload, args, { price, news });
   },
 };

package/src/plugins/builtin/ipo-calendar/listing-ipo.ts

@@ -0,0 +1,160 @@
+import { apiClient } from "../../../api-client";
+import type { IpoDeal } from "../../../api-client/ipo";
+import type { HeadlessPaneApiClient } from "../../../types/plugin";
+import { canonicalExchange } from "../../../utils/exchanges";
+import { fetchIpoCalendar } from "./client";
+import {
+  formatIpoAmount,
+  formatIpoPrice,
+  formatIpoReturn,
+  ipoLockupBasis,
+  ipoLockupText,
+  ipoReturnSince,
+  ipoTickerKey,
+  isLockupStory,
+} from "./model";
+
+/** How far back a listing's IPO is looked for: the calendar keeps a year, and a lock-up runs about half of one. */
+const IPO_LOOKBACK_DAYS = 400;
+const LOCKUP_NEWS_LIMIT = 3;
+
+/** A lock-up story filed under a listing: its headline, publisher and day. */
+export interface IpoLockupStory {
+  title: string;
+  source: string;
+  publishedAt: string;
+  url: string;
+}
+
+/** The stories filed under a listing about its lock-up since it listed (an early release, a waiver), newest first. */
+export async function loadIpoLockupNews(
+  client: Pick<HeadlessPaneApiClient, "searchCloudNews">,
+  deal: IpoDeal,
+): Promise<IpoLockupStory[]> {
+  const key = ipoTickerKey(deal);
+  if (!key || !deal.lockup) return [];
+  const response = await client.searchCloudNews("lock-up", 20, undefined, { tickers: [key] });
+  const since = deal.listingDate ?? deal.firstDay?.session ?? "";
+  return response.items
+    .map((item) => ({
+      title: item.headline,
+      source: item.primaryPublisher || item.primarySource,
+      publishedAt: item.lastPublishedAt || item.firstPublishedAt,
+      url: item.primaryUrl,
+    }))
+    .filter((story) => isLockupStory(story.title) && story.publishedAt.slice(0, 10) >= since)
+    .slice(0, LOCKUP_NEWS_LIMIT);
+}
+
+function shiftDays(day: string, days: number): string {
+  return new Date(Date.parse(`${day}T00:00:00Z`) + days * 86_400_000).toISOString().slice(0, 10);
+}
+
+/**
+ * The IPO a listing came to market with in the last year or so, from the
+ * IPO calendar: the deal listed under its symbol on its exchange. Null for a
+ * listing older than that, one the calendar does not have, or one whose
+ * symbol two deals on its exchange share.
+ */
+export async function loadListingIpo(
+  client: Pick<HeadlessPaneApiClient, "getCloudIpoCalendar">,
+  listing: { symbol: string; exchange?: string | null },
+  { signal, now = new Date() }: { signal?: AbortSignal; now?: Date } = {},
+): Promise<IpoDeal | null> {
+  const symbol = listing.symbol.trim().toUpperCase();
+  if (!symbol) return null;
+  const today = now.toISOString().slice(0, 10);
+  const payload = await fetchIpoCalendar(client, signal, { q: symbol, from: shiftDays(today, -IPO_LOOKBACK_DAYS), to: today });
+  const exchange = listing.exchange ? canonicalExchange(listing.exchange) : "";
+  const deals = payload.deals.filter((deal) => (deal.status === "listed" || deal.status === "priced")
+    && deal.symbol?.toUpperCase() === symbol
+    && (!exchange || (deal.exchange != null && canonicalExchange(deal.exchange) === exchange)));
+  return deals.length === 1 ? deals[0]! : null;
+}
+
+/**
+ * A deal's IPO in rows of a report, label and text:
+ * - IPO date  2026-05-07 on NYSE
+ * - Offer     $26 (or "direct listing, no offer price")
+ * - Since IPO +62.7% ($26 to $42.30)
+ * - Lockup    lockup ends ~2026-11-02 (estimate)
+ */
+export function ipoMetricRows(deal: IpoDeal, price: number | null | undefined, now = new Date()): Array<[string, string]> {
+  const day = deal.listingDate ?? deal.firstDay?.session ?? null;
+  const rows: Array<[string, string]> = [];
+  if (day) rows.push(["IPO date", `${day}${deal.venue ? ` on ${deal.venue}` : ""}`]);
+  rows.push(["Offer", formatIpoPrice(deal, { full: true })]);
+  const since = ipoReturnSince(deal, price);
+  if (since) {
+    const from = since.basis === "offer" ? formatIpoAmount(deal, since.from) : `first trade ${formatIpoAmount(deal, since.from)}`;
+    rows.push(["Since IPO", `${formatIpoReturn(since.returnPct)} (${from} to ${formatIpoAmount(deal, price!)})`]);
+  }
+  const lockup = ipoLockupText(deal, now);
+  if (lockup) rows.push(["Lockup", lockup.replace(/^lockup /, "")]);
+  return rows;
+}
+
+/** The lines under those rows: what the lock-up estimate counts from, then the lock-up stories. */
+export function ipoDetailNotes(deal: IpoDeal, news: readonly IpoLockupStory[]): string[] {
+  const basis = ipoLockupBasis(deal);
+  return [
+    ...basis ? [`Lockup estimate: ${basis}; underwriters can release shares early.`] : [],
+    ...news.map((story) => `Lock-up news ${story.publishedAt.slice(0, 10)}: ${story.title} (${story.source})`),
+  ];
+}
+
+/**
+ * A deal's IPO in sentences, for a report's notes:
+ * - "HAWK listed 2026-05-07 on NYSE at a $26 offer price; $42.30 now, +62.7% since the IPO."
+ * - "GYGY listed 2026-07-30 on Nasdaq: direct listing, no offer price; $30.10 now, +33.8% since the first trade at $22.50."
+ * - "HAWK lockup ends ~2026-11-02 (estimate): 180 days from the prospectus dated 2026-05-06; underwriters can release shares early."
+ * - "Lock-up news 2026-08-31: HawkEye 360 Confirms Early Lock-up Release for September 2nd (PR Newswire)"
+ */
+export function ipoDetailSentences(deal: IpoDeal, price: number | null | undefined, news: readonly IpoLockupStory[], now = new Date()): string[] {
+  const name = deal.symbol ?? deal.company;
+  const day = deal.listingDate ?? deal.firstDay?.session ?? null;
+  const listed = deal.status === "listed" ? "listed" : "prices to list";
+  const where = `${day ? ` ${day}` : ""}${deal.venue ? ` on ${deal.venue}` : ""}`;
+  const offer = deal.offerPrice != null ? ` at a ${formatIpoAmount(deal, deal.offerPrice)} offer price`
+    : deal.listingType === "direct" ? `: ${formatIpoPrice(deal, { full: true })}` : "";
+  // The table's Return is the first day's; the sentence says which is which.
+  const firstDay = deal.firstDay?.returnPct != null && deal.offerPrice != null
+    ? `, ${formatIpoReturn(deal.firstDay.returnPct)} on the first day` : "";
+  const since = ipoReturnSince(deal, price);
+  const priceNow = since ? `; ${formatIpoAmount(deal, price!)} now, ${formatIpoReturn(since.returnPct)} since ${
+    since.basis === "offer" ? "the IPO" : `the first trade at ${formatIpoAmount(deal, since.from)}`}` : "";
+  const lockup = ipoLockupText(deal, now);
+  const basis = ipoLockupBasis(deal);
+  return [
+    `${name} ${listed}${where}${offer}${firstDay}${priceNow}.`,
+    ...lockup ? [`${name} ${lockup}${basis ? `: ${basis}` : ""}; underwriters can release shares early.`] : [],
+    ...news.map((story) => `Lock-up news ${story.publishedAt.slice(0, 10)}: ${story.title} (${story.source})`),
+  ];
+}
+
+/** A listing's recent IPO and its lock-up news, as `ticker` reads them beside the rest. */
+export interface TickerIpo {
+  deal: IpoDeal;
+  news: IpoLockupStory[];
+}
+
+/** How long `ticker` waits for the IPO calendar before leaving the section out. */
+const TICKER_IPO_WAIT_MS = 6_000;
+
+/**
+ * A stock's IPO of the last year or so with its lock-up news, for `ticker`;
+ * null for any other listing, and when the calendar does not answer in time.
+ */
+export async function loadTickerIpo(
+  listing: { symbol: string; exchange?: string | null },
+  client: Pick<HeadlessPaneApiClient, "getCloudIpoCalendar" | "searchCloudNews"> = apiClient,
+): Promise<TickerIpo | null> {
+  const signal = AbortSignal.timeout(TICKER_IPO_WAIT_MS);
+  const deal = await loadListingIpo(client, listing, { signal });
+  if (!deal) return null;
+  const news = await loadIpoLockupNews(client, deal).catch(() => {
+    // Intentional ignore: the IPO's rows stand without its lock-up news.
+    return [];
+  });
+  return { deal, news };
+}

package/src/plugins/builtin/ipo-calendar/model.ts

@@ -161,16 +161,36 @@ const REGION_WORDS: Partial<Record<IpoRegion, readonly string[]>> = {
   apac: ["apac", "asia", "asia-pacific"],
 };
 
+/**
+ * Words that name a kind of deal rather than one: `lockup` (`lock-up`,
+ * `lock up`, `lockups`) lists the deals with a lock-up estimate, `spac` the
+ * SPACs' own IPOs, and `de-spac` (`despac`) those too: a SPAC's merger with
+ * its target is no IPO, so the calendar has none of its own.
+ */
+export type IpoKeyword = "lockup" | "spac" | "de-spac";
+
+export function ipoKeyword(query: string): IpoKeyword | null {
+  const word = query.trim().toLowerCase().replace(/[\s_-]+/g, "");
+  if (/^lockups?$/.test(word)) return "lockup";
+  if (/^spacs?$/.test(word)) return "spac";
+  if (/^despacs?$/.test(word)) return "de-spac";
+  return null;
+}
+
 /**
  * Company in either script, symbol, venue, country code or name, and the
  * status the board shows. The word `pending` is no status of its own: it is
  * every deal not priced yet, offering and overdue ones included.
  * A region's name (`europe`, `asia`) lists the region's deals, on whichever tab is open.
+ * A kind of deal (`lockup`, `spac`, `de-spac`, see ipoKeyword) lists that kind.
  */
 function matchesIpoQuery(deal: IpoDeal, query: string, now: Date): boolean {
   const needle = query.trim().toLowerCase();
   if (!needle) return true;
   if (needle === "pending") return NOT_PRICED_STATUSES.includes(deal.status);
+  const keyword = ipoKeyword(needle);
+  if (keyword === "lockup") return !!deal.lockup;
+  if (keyword) return deal.listingType === "spac";
   if (REGION_WORDS[deal.region]?.includes(needle.replace(/\s+/g, "-"))) return true;
   return [
     deal.company, deal.companyLocal, deal.symbol, deal.venue, deal.mic, deal.exchange,
@@ -343,9 +363,17 @@ function amount(value: number): string {
   return value.toLocaleString("en-US", { minimumFractionDigits: whole ? 0 : 2, maximumFractionDigits: 2 });
 }
 
-/** "$18", "HK$26.20-28.50", "240-260p", "CHF 45": the offer price once set, else the range. */
-export function formatIpoPrice(deal: IpoDeal): string {
+/** What a direct listing with no price reads in a column; a report's row says why in full. */
+const DIRECT_LISTING_PRICE = "direct listing";
+const DIRECT_LISTING_NO_PRICE = "direct listing, no offer price";
+
+/**
+ * "$18", "HK$26.20-28.50", "240-260p", "CHF 45": the offer price once set, else the range.
+ * A direct listing sells no shares at a price: "direct listing" (`full`: "direct listing, no offer price").
+ */
+export function formatIpoPrice(deal: IpoDeal, { full = false }: { full?: boolean } = {}): string {
   const low = deal.offerPrice ?? deal.priceLow ?? deal.priceHigh;
+  if (low == null && deal.listingType === "direct") return full ? DIRECT_LISTING_NO_PRICE : DIRECT_LISTING_PRICE;
   if (low == null) return MISSING;
   const high = deal.offerPrice == null && deal.priceLow != null && deal.priceHigh != null && deal.priceHigh !== deal.priceLow
     ? deal.priceHigh
@@ -387,3 +415,71 @@ export function formatIpoDate(value: string | null, now = new Date()): string {
     ? `${month} ${date.getUTCDate()}`
     : `${month} ${date.getUTCFullYear()}`;
 }
+
+/** "~2026-11-02": when a deal's lock-up is estimated to end; "—" without an estimate. */
+export function formatIpoLockupEnd(endsOn: string | null | undefined): string {
+  return endsOn ? `~${endsOn}` : MISSING;
+}
+
+/** Today in UTC, YYYY-MM-DD. */
+function utcToday(now: Date): string {
+  return now.toISOString().slice(0, 10);
+}
+
+/**
+ * "lockup ends ~2026-11-02 (estimate)", "lockup ended ~2026-07-28 (estimate)":
+ * a deal's lock-up estimate in words; null without one.
+ */
+export function ipoLockupText(deal: Pick<IpoDeal, "lockup">, now = new Date()): string | null {
+  if (!deal.lockup) return null;
+  const verb = deal.lockup.endsOn < utcToday(now) ? "ended" : "ends";
+  return `lockup ${verb} ~${deal.lockup.endsOn} (estimate)`;
+}
+
+/**
+ * What the estimate counts from, as the server made it. The period is the
+ * prospectus's own (`prospectus`) or the typical 180 days; it counts from
+ * the prospectus date when one was read, else from the first session:
+ * - "180 days from the prospectus dated 2026-05-06"
+ * - "90 days from the first session on 2026-05-07, the period the prospectus states"
+ * - "the typical 180 days from the prospectus dated 2026-05-06"
+ * - "the typical 180 days from the first session on 2026-05-07; the prospectus has not been read"
+ */
+export function ipoLockupBasis(deal: Pick<IpoDeal, "lockup" | "listingDate">): string | null {
+  const lockup = deal.lockup;
+  if (!lockup) return null;
+  const stated = lockup.basis === "prospectus";
+  const from = lockup.prospectusDate
+    ? `from the prospectus dated ${lockup.prospectusDate}`
+    : `from the first session${deal.listingDate ? ` on ${deal.listingDate}` : ""}`;
+  if (stated) return `${lockup.days} days ${from}${lockup.prospectusDate ? "" : ", the period the prospectus states"}`;
+  // A prospectus read with no period it states (or none of a lock-up's length) is still read.
+  const read = lockup.prospectusDate != null || lockup.prospectusUrl != null;
+  return `the typical ${lockup.days} days ${from}${read ? "" : "; the prospectus has not been read"}`;
+}
+
+/** A price in the deal's own currency: "$26", "HK$7.20". */
+export function formatIpoAmount(deal: Pick<IpoDeal, "currency">, value: number): string {
+  return formatIpoPrice({ offerPrice: value, priceLow: null, priceHigh: null, currency: deal.currency, listingType: "ipo" } as IpoDeal);
+}
+
+/**
+ * What a listed deal's price has done since it listed: from the offer price,
+ * else (a direct listing) from its first trade. Null without a price now or a
+ * price to measure from.
+ */
+export function ipoReturnSince(deal: IpoDeal, price: number | null | undefined): { from: number; basis: "offer" | "first trade"; returnPct: number } | null {
+  if (price == null || !Number.isFinite(price) || price <= 0) return null;
+  const offer = deal.offerPrice;
+  if (offer != null && offer > 0) return { from: offer, basis: "offer", returnPct: price / offer - 1 };
+  const open = deal.firstDay?.open;
+  if (deal.listingType === "direct" && open != null && open > 0) return { from: open, basis: "first trade", returnPct: price / open - 1 };
+  return null;
+}
+
+/** The lock-up stories worth listing beside a deal: on or after its listing, about its lock-up. */
+const LOCKUP_WORDS = /\block[\s-]?ups?\b/i;
+
+export function isLockupStory(title: string): boolean {
+  return LOCKUP_WORDS.test(title);
+}

package/src/plugins/builtin/iv-history/client.ts

@@ -5,10 +5,18 @@ import type { ChartRequest, InstrumentRef } from "../../../market-data/request-t
 import type { QueryEntry } from "../../../market-data/result-types";
 import type { DataProvider } from "../../../types/data-provider";
 import type { PricePoint } from "../../../types/financials";
-import { realizedVolatility, realizedVolatilityCadenceIssue } from "../shared/volatility";
+import { realizedVolatilityCadenceIssue, rollingRealizedVolatility } from "../shared/volatility";
 import { NO_FATE, type ListingFate } from "../../../tickers/listing-fate";
 
 export type IvMethod = "quote-mid" | "trade-close";
+/**
+ * Which prices a trade-close reading was solved from: each option's closing
+ * print, kept because it sat inside the closing two-sided quote (`print`), the
+ * quote midpoint, used where a print sat outside it (`mid`), or both
+ * (`mixed`). Absent when no closing quote was stored to check the prints
+ * against, as for most history before the checks began.
+ */
+export type IvCloseBasis = "print" | "mid" | "mixed";
 export type IvCoverageStatus = "ready" | "backfilling" | "queued" | "unavailable";
 export interface IvPoint {
   sessionDate: string;
@@ -27,11 +35,14 @@ export interface IvPoint {
    */
   put25_30?: number | null;
   call25_30?: number | null;
+  /** Prices a trade close was solved from; see `IvCloseBasis`. Absent from older servers. */
+  basis?: IvCloseBasis | null;
 }
 export interface IvStats {
   value: number;
   date: string;
   method: IvMethod;
+  basis?: IvCloseBasis | null;
   rank: number | null;
   percentile: number | null;
   low: number | null;
@@ -54,6 +65,7 @@ interface IvReading {
   iv90: number | null;
   iv180: number | null;
   iv365: number | null;
+  basis?: IvCloseBasis | null;
 }
 export interface IvHistoryPayload {
   version: 1;
@@ -155,6 +167,37 @@ export function createHvDependencies(marketData?: DataProvider): HvDependencies
 /** Screen rows with no reading whose symbol's fate is looked up; a long list of them is a backfill, not a lookup. */
 const MAX_FATE_LOOKUPS = 10;
 
+/**
+ * A symbol's realized volatility over one window: the newest, and after every
+ * session's close, so a reading is divided by the HV of its own date and not
+ * of today.
+ */
+export interface ScreenHv {
+  /** HV over the newest window of closes. */
+  value: number | null;
+  /** Date of the newest daily bar: the newest session the symbol's prices reach. */
+  date: string | null;
+  /** HV after each session's close, oldest first; sessions without a full window are left out. */
+  series: ReadonlyArray<readonly [date: string, value: number]>;
+}
+
+const barDay = (value: Date) => new Date(value).toISOString().slice(0, 10);
+
+/** `ScreenHv` from daily closes; a provider that fell back to weekly or intraday bars would misstate daily HV, so it has none. */
+export function screenHv(history: readonly PricePoint[], window: number): ScreenHv {
+  if (realizedVolatilityCadenceIssue(history)) return { value: null, date: null, series: [] };
+  const rolling = rollingRealizedVolatility(history, { windows: [window] });
+  const series = rolling.flatMap((point) => {
+    const value = point.values[window];
+    return value == null ? [] : [[barDay(point.date), value] as const];
+  });
+  const newest = history.reduce<string | null>((latest, point) => {
+    const date = barDay(point.date);
+    return latest == null || date > latest ? date : latest;
+  }, null);
+  return { value: rolling.at(-1)?.values[window] ?? null, date: newest, series };
+}
+
 /**
  * HV for a screen's symbols (`loadRealizedVolatilities`), started at once,
  * and what became of the ones its rows have no reading for, at most
@@ -166,11 +209,11 @@ const MAX_FATE_LOOKUPS = 10;
  */
 export async function loadScreenVolatilities(
   instruments: readonly InstrumentRef[], rows: Promise<readonly IvScreenRow[]>, window: number,
-  options: { signal?: AbortSignal; onValue?: (symbol: string, value: number | null) => void; onFates?: (fates: ReadonlyMap<string, ListingFate>) => void } = {},
+  options: { signal?: AbortSignal; onValue?: (symbol: string, value: ScreenHv | null) => void; onFates?: (fates: ReadonlyMap<string, ListingFate>) => void } = {},
   dependencies: HvDependencies = createHvDependencies(),
-): Promise<{ hv: Map<string, number | null>; fates: Map<string, ListingFate> }> {
+): Promise<{ hv: Map<string, ScreenHv | null>; fates: Map<string, ListingFate> }> {
   const moved = new Set<string>();
-  const onValue = options.onValue && ((symbol: string, value: number | null) => { if (!moved.has(symbol)) options.onValue!(symbol, value); });
+  const onValue = options.onValue && ((symbol: string, value: ScreenHv | null) => { if (!moved.has(symbol)) options.onValue!(symbol, value); });
   const [hv, fates] = await Promise.all([
     loadRealizedVolatilities(instruments, window, { ...options, onValue }, dependencies),
     rows.then(async (screened) => {
@@ -189,20 +232,18 @@ export async function loadScreenVolatilities(
 
 /** Close-to-close HV over one window for each symbol from one year of daily closes, four at a time. */
 async function loadRealizedVolatilities(
-  instruments: readonly InstrumentRef[], window: number, options: { signal?: AbortSignal; onValue?: (symbol: string, value: number | null) => void } = {},
+  instruments: readonly InstrumentRef[], window: number, options: { signal?: AbortSignal; onValue?: (symbol: string, value: ScreenHv | null) => void } = {},
   dependencies: HvDependencies = createHvDependencies(),
-): Promise<Map<string, number | null>> {
-  const result = new Map<string, number | null>();
+): Promise<Map<string, ScreenHv | null>> {
+  const result = new Map<string, ScreenHv | null>();
   let next = 0;
   const worker = async () => {
     while (next < instruments.length && !options.signal?.aborted) {
       const instrument = instruments[next++]!;
-      let value: number | null = null;
+      let value: ScreenHv | null = null;
       try {
         const entry = await dependencies.loadChart({ instrument, bufferRange: "1Y", granularity: "resolution", resolution: "1d" });
-        const history = resolveEntryValue(entry) ?? [];
-        // A provider that fell back to weekly or intraday bars would misstate daily HV.
-        value = realizedVolatilityCadenceIssue(history) ? null : realizedVolatility(history, window);
+        value = screenHv(resolveEntryValue(entry) ?? [], window);
       } catch { value = null; }
       result.set(instrument.symbol, value);
       options.onValue?.(instrument.symbol, value);

package/src/plugins/builtin/iv-history/format.ts

@@ -1,26 +1,32 @@
-import type { IvMethod } from "./client";
-import type { IvStatRow, IvStatUnit, RichCheap, RichCheapDates } from "./model";
+import type { IvCloseBasis, IvMethod } from "./client";
+import { readingSource, type IvStatRow, type IvStatUnit, type RichCheap, type RichCheapDates } from "./model";
 
 /**
  * VCA's sign conventions, and what VIX is beside an at-the-money IV30, one
- * line each: under the table, in the shot and in the report's notes. The skew
- * is the stored 25-delta put and call IVs at a 30-day constant maturity, from
- * the latest quote capture; both differences are decimal IV shown in points.
+ * line each: under the table, in the shot and in the report's notes. The risk
+ * reversal is the stored 25-delta call and put IVs at a 30-day constant
+ * maturity, from the latest quote capture, signed as OVDV signs it; both
+ * differences are decimal IV shown in points. Its line is there only while a
+ * risk reversal column is.
  */
-export const VCA_DEFINITIONS = [
-  "25D skew: 30-day 25-delta put IV minus 25-delta call IV, in vol points; positive means puts are richer. 30-90: IV30 minus IV90.",
-  "VIX is Cboe's 30-day S&P 500 implied vol from the whole SPX strike strip, skew included; IV30 here is at the money, so VIX usually reads higher.",
-] as const;
+export function vcaDefinitions({ skew }: { skew: boolean }): string[] {
+  return [
+    ...(skew ? ["25D RR: 30-day 25-delta call IV minus 25-delta put IV, in vol points, as OVDV's risk reversal; positive means calls are richer."] : []),
+    "30-90: IV30 minus IV90. IV/HV: IV30 over the HV20 of the same date.",
+    "VIX is Cboe's 30-day S&P 500 implied vol from the whole SPX strike strip, skew included; IV30 here is at the money, so VIX usually reads higher.",
+  ];
+}
 
 /** Words for implied volatility that are no function's code: `fn IVOL` names HIVG and OVDV, which list them as `suggestFor`. */
 export const IMPLIED_VOL_WORDS = ["IVOL", "IV", "OVOL", "IMPVOL", "IMPLIEDVOL"];
 
 /**
- * A skew column's header names its sign, since the conventions differ: the
- * 25-delta skew is put minus call (HIVG, VCA), the risk reversal call minus
- * put (OVDV). "skew25d put-call (pts)": the stem a script keys on, the
- * sign, and vol points in the unit's usual place, as in "IV30 (%)". No
- * comma, so a CSV header needs no quoting.
+ * A skew column's header names its sign. The risk reversal is call minus put
+ * wherever it is shown (OVDV, VCA, HIVG's rr25d), so positive means calls are
+ * richer; HIVG's skew25d keeps the put-minus-call sign it was first exported
+ * with, the negative of that. "rr25d call-put (pts)": the stem a script keys
+ * on, the sign, and vol points in the unit's usual place, as in "IV30 (%)".
+ * No comma, so a CSV header needs no quoting.
  */
 export const skewHeader = (stem: string, sign: string) => `${stem} ${sign} (pts)`;
 
@@ -43,22 +49,29 @@ export function formatStat(value: number | null | undefined, unit: IvStatUnit):
 /**
  * How a stored reading was taken. A quote capture is the option quote mids
  * from the minutes before the close, taken once a session and never updated:
- * it is not a live feed, so it is not called live.
+ * it is not a live feed, so it is not called live. A close solved from quote
+ * midpoints, where its prints were off the market, says so.
+ */
+export function statSource(row: Pick<IvStatRow, "method"> & { basis?: IvCloseBasis | null }): string {
+  return row.method === "prices" ? "closes" : row.method ? readingSource(row.method, row.basis) : "";
+}
+/**
+ * "2026-10-09 quote": the session a reading belongs to and how it was taken.
+ * A stale reading says so instead, "2026-05-18 close, stale", and in the short
+ * form "05-18 stale".
  */
-const readingSource = (method: IvMethod | null | undefined) => method === "quote-mid" ? "quote" : "close";
-export function statSource(row: Pick<IvStatRow, "method">): string {
-  return row.method === "prices" ? "closes" : row.method ? readingSource(row.method) : "";
+export function readingLabel(date: string, method: IvMethod | null | undefined, short = false,
+  extra: { basis?: IvCloseBasis | null; stale?: boolean } = {}): string {
+  if (extra.stale) return short ? `${shortDate(date)} stale` : `${date} ${readingSource(method, extra.basis)}, stale`;
+  return `${short ? shortDate(date) : date} ${readingSource(method, extra.basis)}`;
 }
-/** "2026-10-09 quote": the session a reading belongs to and how it was taken. */
-export const readingLabel = (date: string, method: IvMethod | null | undefined, short = false) =>
-  `${short ? shortDate(date) : date} ${readingSource(method)}`;
 /**
  * The dates every row agrees on, said once: the reading's, and the trade close
  * its rank is measured on. `short` is for a footer with little room: month and
  * day, and no window.
  */
 export function sharedDates({ reading, rank }: Pick<RichCheapDates, "reading" | "rank">, short = false): string[] {
-  if (reading?.method === "trade-close" && reading.date === rank) return [readingLabel(reading.date, reading.method, short)];
-  return [reading && `IV30 ${readingLabel(reading.date, reading.method, short)}`,
+  if (reading?.method === "trade-close" && reading.date === rank) return [readingLabel(reading.date, reading.method, short, { basis: reading.basis })];
+  return [reading && `IV30 ${readingLabel(reading.date, reading.method, short, { basis: reading.basis })}`,
     rank && (short ? `IVR/IVP ${shortDate(rank)} close` : `IVR/IVP vs 52 weeks to ${rank} close`)].filter((part): part is string => !!part);
 }