gloomberb 0.16.2 → 0.16.4

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

@@ -12,6 +12,7 @@ import {
   formatMaybePercent,
   formatMoneyCompact,
   formatSignedCompact,
+  holderValueCurrency,
   resolveHolderOwnershipPercent,
 } from "./format";
 import { buildRows, sortRows } from "./table-model";
@@ -19,6 +20,8 @@ import type { HolderData } from "../../../types/financials";
 import type { HolderColumnId } from "./types";
 import { SEC_FILINGS } from "../shared/report-freshness";
 import {
+  holderShareBasisMarker,
+  holderShareBasisNote,
   holderValueBasis,
   holdersHeaderLine,
   moneyColumnHeader,
@@ -28,8 +31,11 @@ import {
 
 /** Columns a source fills only when it reports the quarter's change. */
 const CHANGE_COLUMN_KEYS = new Set(["changeShares", "changePercent"]);
+/** Shown only when some row is held as depositary receipts, as on a home line abroad. */
+const BASIS_COLUMN_KEY = "shareBasis";
 import type { BeneficialOwnersPayload } from "../../../api-client/beneficial-owners";
 import { fetchBeneficialOwners, type BeneficialOwnersRequest } from "./beneficial-client";
+import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
 import type { BeneficialColumnId } from "./beneficial-model";
 import {
   BENEFICIAL_REPORT_COLUMNS,
@@ -60,6 +66,11 @@ const HOLDER_COLUMNS: HeadlessPaneColumn[] = [
     align: "right",
     format: (value) => value == null ? "-" : formatCompact(Number(value)),
   },
+  {
+    key: BASIS_COLUMN_KEY,
+    header: "Basis",
+    format: (_value, row) => holderShareBasisMarker(row),
+  },
   {
     key: "changeShares",
     header: "Chg",
@@ -126,7 +137,11 @@ export interface HoldersHeadlessDependencies {
 
 const defaultDependencies: HoldersHeadlessDependencies = {
   loadSnapshot: (symbol, _args, ctx) => loadHolderSnapshot(ctx.marketData, symbol),
-  loadBeneficialOwners: (symbol, request, ctx) => fetchBeneficialOwners(symbol, request, {
+  // A listing abroad names its venue and company, so it never reads a US namesake's owners.
+  loadBeneficialOwners: async (symbol, request, ctx) => fetchBeneficialOwners(symbol, {
+    ...request,
+    listing: await resolveHeadlessIssuerListing(ctx, symbol),
+  }, {
     client: ctx.apiClient,
     signal: ctx.signal,
   }),
@@ -238,6 +253,8 @@ export function createHoldersHeadless(
       }
       const { data, marketCap } = await dependencies.loadSnapshot(symbol, args, ctx);
       const currency = data.currency ?? "USD";
+      // A London line's values can be dollars from the 13F filings; they are labelled and formatted as such.
+      const valueCurrency = holderValueCurrency(data, currency)!;
       const sorted = sortRows(buildRows(data), {
         columnId: SORT_COLUMNS[String(args.options.sort)] ?? "value",
         direction: args.options.order === "asc" ? "asc" : "desc",
@@ -253,19 +270,23 @@ export function createHoldersHeadless(
           changePercent: row.changePercent ?? null,
           percentHeld: resolveHolderOwnershipPercent(row, marketCap) ?? null,
           reportDate: row.reportDate ?? null,
-          currency,
+          currency: valueCurrency,
+          shareBasis: row.shareBasis ?? null,
         }));
       const total = data.summary?.institutionsCount ?? null;
       const changeReported = rows.some((row) => row.changeShares != null || row.changePercent != null);
       const reportDate = sharedReportDate(rows);
-      const valueBasis = holderValueBasis(reportDate);
+      const valueBasis = holderValueBasis(reportDate, data.valueBasis, valueCurrency);
       const positionsBasis = rows.length > 0 ? nonUsHolderCaveat(data.exchange, currency) : null;
+      const shareBasisNote = holderShareBasisNote(data, rows);
+      const markedRows = rows.some((row) => holderShareBasisMarker(row));
       // The title names the ticker and the closing line carries the as-of date.
       const header = holdersHeaderLine({
         name: data.name,
         symbol: data.symbol && data.symbol !== symbol ? data.symbol : null,
         exchange: data.exchange,
-        currency,
+        currency: valueCurrency,
+        listingCurrency: data.currency,
         shown: rows.length,
         reported: sorted.length,
         total,
@@ -278,13 +299,18 @@ export function createHoldersHeadless(
         // A change column that is empty on every row says nothing; the line above explains it once.
         columns: HOLDER_COLUMNS
           .filter((column) => changeReported || !CHANGE_COLUMN_KEYS.has(column.key))
-          .map((column) => column.key === "value" ? { ...column, header: moneyColumnHeader(column.header, currency) } : column),
+          .filter((column) => markedRows || column.key !== BASIS_COLUMN_KEY)
+          .map((column) => column.key === "value" ? { ...column, header: moneyColumnHeader(column.header, valueCurrency) } : column),
         rows,
         metadata: {
           symbol: data.symbol || symbol,
           name: data.name ?? null,
           exchange: data.exchange ?? null,
           currency,
+          valueCurrency,
+          ...(data.isDepositaryReceipt != null ? { isDepositaryReceipt: data.isDepositaryReceipt } : {}),
+          ...(data.shareBasis ? { shareBasis: data.shareBasis } : {}),
+          ...(data.adrRatio != null ? { adrRatio: data.adrRatio } : {}),
           asOf: data.asOf ?? null,
           summary: data.summary ?? null,
           shown: rows.length,
@@ -294,7 +320,7 @@ export function createHoldersHeadless(
           valueBasis,
           changeReported,
           positionsBasis,
-          notices: [header, basis, positionsBasis].filter((line): line is string => !!line),
+          notices: [header, basis, positionsBasis, shareBasisNote].filter((line): line is string => !!line),
         },
       };
     },

package/src/plugins/builtin/holders/pane.tsx

@@ -26,8 +26,11 @@ import {
   formatMaybePercent,
   formatMoneyCompact,
   formatSignedCompact,
+  holderStakeMarketCap,
+  holderValueCurrency,
   resolveHolderOwnershipPercent,
 } from "./format";
+import { holderShareBasisMarker } from "./report-header";
 import {
   buildColumns,
   hasHolderChanges,
@@ -40,14 +43,15 @@ import {
 import { loadHolderData } from "./client";
 import { HoldersTreemap } from "./treemap";
 import { BeneficialOwnersView } from "./beneficial-view";
+import { useIssuerListing } from "../shared/ticker-request";
 import type { HolderColumn, HolderColumnId, HolderRow, SortPreference, ViewMode } from "./types";
 import { loadHolder13FMatches, type Holder13FMatch } from "./thirteenf-match";
 import { useSampledValue, useTickerQuoteStream } from "../../../state/hooks/live-ticker-financials";
 
 const HOLDER_MARKET_CAP_SAMPLE_MS = 5_000;
 
-/** The "13F" badge: the label and its padding. */
-const FUND_BADGE_WIDTH = 5;
+/** The width of a three-letter badge ("13F", "ADR"): the label and its padding. */
+const BADGE_WIDTH = 5;
 
 export function HoldersView({ focused, width, height }: { focused: boolean; width: number; height: number }) {
   const { nativePaneChrome } = useUiCapabilities();
@@ -62,6 +66,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   const fundMatchAbortRef = useRef<AbortController | null>(null);
 
   const exchange = ticker?.metadata.exchange ?? "";
+  const issuerListing = useIssuerListing(ticker);
   const loadHolders = useMemo(() => symbol ? async (forceRefresh: boolean) => {
     if (!dataProvider) throw new Error("Holder data unavailable");
     return loadHolderData(dataProvider, symbol, exchange, forceRefresh ? { cacheMode: "refresh" } : undefined);
@@ -70,13 +75,14 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   // refresh keeps the last holders; the failure goes to the footer.
   const { data, loading, error, reload } = useAsyncResource<HolderData>(loadHolders, { keepPreviousData: true });
 
-  const currency = data?.currency || ticker?.metadata.currency || "USD";
+  // The values' own currency: dollars from the 13F filings on a London line, not its pence.
+  const currency = holderValueCurrency(data, ticker?.metadata.currency || "USD")!;
   // A stake without a reported percentage is the holding's value over the
-  // market cap. The stream keeps the cap current, about once a second; the
-  // stakes follow it at most every few seconds so ticks do not re-sort them.
+  // market cap, when both are in one currency. The stream keeps the cap
+  // current, about once a second; the stakes follow it at most every few
+  // seconds so ticks do not re-sort them.
   useTickerQuoteStream(ticker ? symbol : null, ticker, { surface: "detail", visible: false, weight: 30 });
-  const quoteMarketCap = financials?.quote?.marketCap;
-  const liveMarketCap = financials?.quote?.currency && financials.quote.currency !== currency ? undefined : quoteMarketCap;
+  const liveMarketCap = holderStakeMarketCap(financials?.quote?.marketCap, financials?.quote?.currency, currency);
   const marketCap = useSampledValue(liveMarketCap, HOLDER_MARKET_CAP_SAMPLE_MS, `${symbol ?? ""}:${currency}`);
   const rows = useMemo(() => buildRows(data), [data]);
   const sortedRows = useMemo(() => sortRows(rows, sortPreference, marketCap), [marketCap, rows, sortPreference]);
@@ -216,17 +222,22 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
     switch (column.id) {
       case "holder": {
         const color = rowState.selected ? colors.selectedText : colors.textBright;
-        if (!fundMatches.has(row.id)) return { text: row.name, color, attributes: TextAttributes.BOLD };
-        // A fund with a 13F opens on Enter or o. The name gives way first, so
-        // the marker survives a narrow column.
+        // ADR: a position held as receipts on a home line's list. 13F: a fund
+        // whose filing opens on Enter or o.
+        const receipts = holderShareBasisMarker(row);
+        const fund = fundMatches.has(row.id);
+        if (!receipts && !fund) return { text: row.name, color, attributes: TextAttributes.BOLD };
+        const badges = (receipts ? 1 : 0) + (fund ? 1 : 0);
+        // The name gives way first, so the markers survive a narrow column.
         return {
-          text: `${row.name} 13F`,
+          text: [row.name, receipts, fund ? "13F" : ""].filter(Boolean).join(" "),
           content: (
             <Box flexDirection="row" gap={1} width={column.width} overflow="hidden">
               <Text fg={color} attributes={TextAttributes.BOLD}>
-                {clipToDisplayWidth(row.name, Math.max(1, column.width - FUND_BADGE_WIDTH - 1))}
+                {clipToDisplayWidth(row.name, Math.max(1, column.width - badges * (BADGE_WIDTH + 1)))}
               </Text>
-              <Badge label="13F" tone="accent" />
+              {receipts ? <Badge label={receipts} /> : null}
+              {fund ? <Badge label="13F" tone="accent" /> : null}
             </Box>
           ),
         };
@@ -328,6 +339,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
           focused={focused}
           width={width}
           symbol={symbol ?? null}
+          listing={issuerListing}
           holderRows={rows}
           fundMatches={fundMatches}
           onCycleView={toggleView}

package/src/plugins/builtin/holders/report-header.ts

@@ -1,4 +1,6 @@
+import type { HolderData } from "../../../types/financials";
 import { currencyUnitLabel, resolveCurrencyUnit } from "../../../utils/currency-units";
+import { adrRatioText } from "../../../utils/depositary-receipt";
 import { canonicalExchange, isUsListingExchange, resolveExchangeTimeZone } from "../../../utils/exchanges";
 
 /**
@@ -12,7 +14,10 @@ export interface HolderReportFacts {
   /** Left out when the report title already names it. */
   symbol?: string | null;
   exchange?: string | null;
+  /** The unit the values are in. */
   currency?: string | null;
+  /** The listing's price currency, when the values are in another one. */
+  listingCurrency?: string | null;
   /** Left out when the report's closing line already carries it. */
   asOf?: string | null;
   /** Rows printed. */
@@ -46,10 +51,13 @@ function venueLabel(exchange?: string | null): string {
 
 /** What the list is, after the listing is named: its unit, date and how much of it is shown. */
 export function holderListFacts(
-  facts: Pick<HolderReportFacts, "currency" | "asOf" | "shown" | "reported" | "total">,
+  facts: Pick<HolderReportFacts, "currency" | "listingCurrency" | "asOf" | "shown" | "reported" | "total">,
 ): string[] {
+  const unit = currencyUnitLabel(facts.currency);
+  // Dollars on a London line: say they are the values' unit, not the listing's.
+  const otherUnit = unit && facts.listingCurrency?.trim() && facts.listingCurrency.trim() !== facts.currency?.trim();
   return [
-    currencyUnitLabel(facts.currency),
+    otherUnit ? `values in ${unit}` : unit,
     facts.asOf ? `as of ${facts.asOf}` : "",
     holderCountText(facts.shown, facts.reported, facts.total),
   ].filter(Boolean);
@@ -69,9 +77,42 @@ export function sharedReportDate(rows: ReadonlyArray<{ reportDate?: unknown }>):
   return dates.size === 1 && only ? only : null;
 }
 
-/** How a holder value was reached: reported shares times a current price, not the filing's own value. */
-export function holderValueBasis(reportDate: string | null): string {
-  return `shares reported${reportDate ? ` at ${reportDate}` : ""} x latest price`;
+/**
+ * How a holder value was reached: reported shares times the latest price, or,
+ * where Gloom Cloud priced the filings themselves, times the security's price
+ * at the report date in the values' currency.
+ */
+export function holderValueBasis(
+  reportDate: string | null,
+  basis?: HolderData["valueBasis"] | null,
+  valueCurrency?: string | null,
+): string {
+  const shares = `shares reported${reportDate ? ` at ${reportDate}` : ""}`;
+  if (basis === "period_end_price") {
+    const unit = valueCurrency?.trim();
+    return `${shares} x period-end price${unit ? ` (${unit})` : ""}`;
+  }
+  return `${shares} x latest price`;
+}
+
+/** The short marker a holder row carries when its position is held as depositary receipts. */
+export function holderShareBasisMarker(row: { shareBasis?: unknown }): string {
+  return row.shareBasis === "depositary_receipt" ? "ADR" : "";
+}
+
+/**
+ * What the share counts are, when Gloom Cloud says: which rows of a home
+ * line are positions in the receipts, or that a receipt line's rows all are.
+ */
+export function holderShareBasisNote(
+  data: Pick<HolderData, "shareBasis" | "adrRatio">,
+  rows: ReadonlyArray<{ shareBasis?: unknown }>,
+): string | null {
+  const ratio = adrRatioText(data.adrRatio);
+  const each = ratio ? ` (${ratio})` : "";
+  if (rows.some((row) => holderShareBasisMarker(row))) return `ADR: shares held as depositary receipts${each}.`;
+  if (rows.length > 0 && data.shareBasis === "depositary_receipt") return `Shares are depositary receipts${each}.`;
+  return null;
 }
 
 /** A listing outside the US, by its venue, or by a currency other than the dollar. */

package/src/plugins/builtin/insider/index.tsx

@@ -22,7 +22,7 @@ import {
   type StatItem,
 } from "../../../components";
 import { useDebouncedPluginPaneState, usePluginPaneState } from "../../runtime";
-import { isUsEquityTicker } from "../../../utils/sec";
+import { mayBeUsEquityTicker } from "../../../utils/sec";
 import { formatCompact } from "../../../utils/format";
 import { nextHeaderSort } from "../../../utils/sort-values";
 import { formatShortDate } from "../../../utils/datetime-format";
@@ -130,7 +130,7 @@ function InsiderView({ width, height, focused }: { width: number; height: number
     [setOpenItemIdState],
   );
   const [sort, setSort] = useState<StackSortPreference<InsiderColumnId>>({ columnId: "date", direction: "desc" });
-  const eligibleTicker = isUsEquityTicker(ticker);
+  const eligibleTicker = mayBeUsEquityTicker(ticker);
   const instrument = instrumentFromTicker(ticker, ticker?.metadata.ticker ?? null);
 
   const filingsEntry = useSecFilingsQuery(
@@ -458,7 +458,7 @@ export const insiderModule: PluginModule = {
         description: "Insider transaction activity for the selected ticker.",
         keywords: ["insider", "form 4", "ownership", "transactions", "ins"],
         shortcut: "INS",
-        canCreate: (_context, options) => !options?.ticker || isUsEquityTicker(options.ticker),
+        canCreate: (_context, options) => !options?.ticker || mayBeUsEquityTicker(options.ticker),
       }),
       headless: insiderHeadless,
     },
@@ -471,7 +471,7 @@ export const insiderModule: PluginModule = {
       order: 47,
       component: InsiderView,
       instruments: ["equity"],
-      isVisible: ({ ticker }) => isUsEquityTicker(ticker),
+      isVisible: ({ ticker }) => mayBeUsEquityTicker(ticker),
     });
   },
 };

package/src/plugins/builtin/iv-history/charts.tsx

@@ -3,7 +3,8 @@ import { CompositeChart } from "../../../components";
 import { resolveChartPalette } from "../../../components/chart/core/palette";
 import { formatCompositeSeriesValue } from "../../../components/chart/composite/format";
 import { staticSeries } from "../../../components/chart/static/series";
-import { useThemeColors } from "../../../theme/theme-context";
+import { useThemeColors, useThemeId } from "../../../theme/theme-context";
+import { themeSeriesColors } from "../../../theme/series-colors";
 import type { ResolvedSeries } from "../../../time-series/types";
 import { formatPoints } from "./format";
 import type { DatedValue, IvHistoryModel } from "./model";
@@ -11,8 +12,15 @@ import type { DatedValue, IvHistoryModel } from "./model";
 const PANELS = [{ id: "vol", height: 3 }, { id: "spread", height: 1 }];
 /** The chart drawing blue: IV90 must read apart from amber IV30 in every theme. */
 const IV90_COLOR = "#4c9aff";
-/** The live capture point must stand apart from the amber IV30 line it continues. */
-const LIVE_COLOR = "#c084fc";
+/** The quote capture point must stand apart from the amber IV30 line it continues. */
+const QUOTE_COLOR = "#c084fc";
+/** IV1Y: pink, apart from amber IV30, blue IV90, green HV and the violet quote points. */
+const IV365_COLOR = "#f783ac";
+/**
+ * Palette slots for a theme with its own series colours (the colour-blind
+ * ones), where the up colour HV takes elsewhere is the same blue as IV90.
+ */
+const THEMED_SLOTS = { iv30: 1, iv90: 0, hv: 2, quote: 5, iv365: 4 } as const;
 
 function volSeries(id: string, label: string, color: string, points: readonly DatedValue[], panelId: string,
   style: ResolvedSeries["style"] = "line"): ResolvedSeries {
@@ -27,22 +35,28 @@ function formatLegendValue(value: number, series: ResolvedSeries): string {
   return series.id === "spread" ? `${formatPoints(value / 100)} pts` : formatCompositeSeriesValue(value, series);
 }
 
-function ivHistorySeries(model: IvHistoryModel, colors: { iv30: string; iv90: string; hv: string; quote: string; spread: string },
+function ivHistorySeries(model: IvHistoryModel, colors: { iv30: string; iv90: string; iv365: string; hv: string; quote: string; spread: string },
   hvLabel: string): ResolvedSeries[] {
   return [
     volSeries("iv30", "IV 30d", colors.iv30, model.iv30, "vol"),
     volSeries("iv90", "IV 90d", colors.iv90, model.iv90, "vol"),
+    // Drawn only once there is a 1Y close, so an empty legend entry never suggests one.
+    ...(model.iv365.length ? [volSeries("iv365", "IV 1Y", colors.iv365, model.iv365, "vol")] : []),
     volSeries("hv", hvLabel, colors.hv, model.hv, "vol"),
-    ...(model.quoteIv30.length ? [volSeries("iv30-quote", "IV 30d live", colors.quote, model.quoteIv30, "vol", "points")] : []),
+    ...(model.quoteIv30.length ? [volSeries("iv30-quote", "IV 30d quote", colors.quote, model.quoteIv30, "vol", "points")] : []),
     { ...volSeries("spread", `IV 30d - ${hvLabel}`, colors.spread, model.spread, "spread", "columns"), ...SPREAD_UNIT },
   ];
 }
 
 export function IvHistoryChart({ model, width, height, hvLabel, focused = false }: { model: IvHistoryModel; width: number; height: number; hvLabel: string; focused?: boolean }) {
   const colors = useThemeColors();
+  const themed = themeSeriesColors(useThemeId());
   const palette = resolveChartPalette(colors);
-  const series = useMemo(() => ivHistorySeries(model, { iv30: colors.warning, iv90: IV90_COLOR, hv: colors.positive,
-    quote: LIVE_COLOR, spread: colors.textDim }, hvLabel), [model, colors, hvLabel]);
+  const series = useMemo(() => ivHistorySeries(model, themed
+    ? { iv30: themed[THEMED_SLOTS.iv30]!, iv90: themed[THEMED_SLOTS.iv90]!, iv365: themed[THEMED_SLOTS.iv365]!, hv: themed[THEMED_SLOTS.hv]!,
+      quote: themed[THEMED_SLOTS.quote]!, spread: colors.textDim }
+    : { iv30: colors.warning, iv90: IV90_COLOR, iv365: IV365_COLOR, hv: colors.positive, quote: QUOTE_COLOR, spread: colors.textDim },
+  hvLabel), [model, colors, themed, hvLabel]);
   return <CompositeChart series={series} panels={PANELS} width={width} height={height} focused={focused} navigable={false} showLegend showTimeAxis formatValue={formatLegendValue}
     remoteKind="implied-volatility-history"
     colors={{ background: palette.bgColor, grid: palette.gridColor, crosshair: palette.crosshairColor, text: colors.text,

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

@@ -33,6 +33,10 @@ export interface IvStats {
   high: number | null;
   samples: number;
   windowStart: string | null;
+  /** Prior sessions the rank needs: 120, or 60 for IV1Y. Absent from older servers. */
+  minSamples?: number;
+  /** Why rank or percentile is empty, when one is. */
+  rankNote?: string | null;
 }
 interface IvReading {
   date: string;
@@ -51,8 +55,12 @@ export interface IvHistoryPayload {
   symbol: string;
   asOf: string;
   status: IvCoverageStatus;
-  coverage: { source: "seed" | "demand"; addedAt: string; backfilledThrough: string | null; since: string | null } | null;
-  stats: { iv30: IvStats | null; iv90: IvStats | null };
+  coverage: {
+    source: "seed" | "demand"; addedAt: string; backfilledThrough: string | null; since: string | null;
+    /** First trade close with a one-year reading; the 1Y series starts later and is sparser. */
+    iv365Since?: string | null;
+  } | null;
+  stats: { iv30: IvStats | null; iv90: IvStats | null; iv365?: IvStats | null };
   latest: IvReading | null;
   series: IvPoint[];
   warnings: string[];
@@ -62,6 +70,8 @@ export interface IvScreenRow {
   status: "ready" | "queued";
   iv30: IvStats | null;
   iv90: IvStats | null;
+  iv365?: IvStats | null;
+  iv365Since?: string | null;
   latest: IvReading | null;
   skew: { date: string; put25: number; call25: number; skew: number } | null;
 }

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

@@ -1,4 +1,16 @@
-import type { IvStatRow, IvStatUnit, RichCheap } from "./model";
+import type { IvMethod } from "./client";
+import type { IvStatRow, IvStatUnit, RichCheap, 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.
+ */
+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 const formatVol = (value: number | null | undefined) => value == null || !Number.isFinite(value) ? "--" : `${(value * 100).toFixed(1)}%`;
 export const formatPoints = (value: number | null | undefined) =>
@@ -13,6 +25,25 @@ export function formatStat(value: number | null | undefined, unit: IvStatUnit):
   if (value == null || !Number.isFinite(value)) return "--";
   return unit === "vol" ? formatVol(value) : unit === "points" ? formatPoints(value) : value.toFixed(2);
 }
+/**
+ * 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.
+ */
+const readingSource = (method: IvMethod | null | undefined) => method === "quote-mid" ? "quote" : "close";
 export function statSource(row: Pick<IvStatRow, "method">): string {
-  return row.method === "quote-mid" ? "live" : row.method === "prices" ? "closes" : row.method === "trade-close" ? "close" : "";
+  return row.method === "prices" ? "closes" : row.method ? readingSource(row.method) : "";
+}
+/** "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)}`,
+    rank && (short ? `IVR/IVP ${shortDate(rank)} close` : `IVR/IVP vs 52 weeks to ${rank} close`)].filter((part): part is string => !!part);
 }

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

@@ -2,8 +2,8 @@ import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import { createRealizedVolatilityDependencies, loadRealizedVolatilityHistory } from "../realized-vol/client";
 import { createHvDependencies, loadIvHistory, loadIvScreen, loadRealizedVolatilities } from "./client";
-import { formatPoints, formatRank, formatStat, formatVol, verdictLabel } from "./format";
-import { HV_WINDOWS, type HvWindow, type IvLookback, type IvStatRow, projectIvHistory, projectRichCheap, sharedReading, VCA_LIMIT, VCA_PRESETS } from "./model";
+import { formatPoints, formatRank, formatStat, formatVol, readingLabel, sharedDates, VCA_DEFINITIONS, verdictLabel } from "./format";
+import { HV_WINDOWS, type HvWindow, type IvLookback, type IvStatRow, projectIvHistory, projectRichCheap, type RichCheapRow, richCheapDates, VCA_LIMIT, VCA_PRESETS } from "./model";
 import { vcaUniverse } from "./universe";
 
 const METHODOLOGY = "docs/research-data.md#implied-volatility-history";
@@ -14,7 +14,8 @@ export const ivHistoryHeadless: HeadlessPaneDefinition<"bundle"> = {
   freshness: { status: "not-a-feed", basis: "daily implied volatility", cadence: "daily", observedKey: "date", oldest: null },
   describe: (args) => `HIVG ${args.symbols[0] ?? ""}`,
   discovery: { aliases: ["HIVG"], screenshotReadiness: "live-dom", dataRequirements: ["Cloud stored implied volatility", "Daily price history"],
-    limitations: ["History starts February 2024 (OPRA daily trade closes)", "Rank and percentile use trade-close readings only"] },
+    limitations: ["History starts February 2024 (daily option trade closes)", "Rank and percentile use trade-close readings only",
+      "IV1Y needs long-dated trades: it can start later, has gaps, and ranks from 60 prior sessions"] },
   options: [
     { key: "lookback", type: "enum", values: [{ value: "1Y" }, { value: "2Y" }, { value: "ALL" }], defaultValue: "1Y", description: "Visible history" },
     { key: "hvWindow", type: "enum", values: HV_WINDOWS.map((window) => ({ value: String(window) })), defaultValue: "20", description: "Realized volatility window in sessions" },
@@ -28,8 +29,10 @@ export const ivHistoryHeadless: HeadlessPaneDefinition<"bundle"> = {
     const model = projectIvHistory(payload, prices.history, { lookback: String(args.options.lookback) as IvLookback,
       hvWindow: (Number(args.options.hvWindow) === 30 ? 30 : 20) as HvWindow });
     const hvByDay = new Map(model.hv.map((point) => [point.date.getTime(), point.value]));
+    const iv365ByDay = new Map(model.iv365.map((point) => [point.date.getTime(), point.value]));
     const rows = model.iv30.map((point, index) => ({ date: point.date.toISOString().slice(0, 10), iv30: point.value,
       iv90: model.iv90.find((entry) => entry.date.getTime() === point.date.getTime())?.value ?? null,
+      iv365: iv365ByDay.get(point.date.getTime()) ?? null,
       hv: hvByDay.get(point.date.getTime()) ?? null, spread: model.spread[index]?.value ?? null })).reverse();
     const errors = [prices.error, ...model.warnings].filter((value): value is string => !!value);
     return {
@@ -45,11 +48,12 @@ export const ivHistoryHeadless: HeadlessPaneDefinition<"bundle"> = {
           { key: "samples", header: "Sessions" },
         ], rows: model.stats.map((row) => ({ ...row })) },
         { title: "Daily history", columns: [{ key: "date", header: "Session" },
-          ...["iv30", "iv90", "hv"].map((key) => ({ key, header: key.toUpperCase(), format: percent })),
+          ...[["iv30", "IV30"], ["iv90", "IV90"], ["iv365", "IV1Y"], ["hv", "HV"]].map(([key, header]) => ({ key: key!, header: header!, format: percent })),
           { key: "spread", header: "IV-HV", format: (value: unknown) => typeof value === "number" ? formatPoints(value) : "--" }], rows },
       ],
       complete: payload.status === "ready" && errors.length === 0,
       unavailableSymbols: model.iv30.length ? [] : [instrument.symbol], errors,
+      ...(model.oneYearNote ? { notes: [model.oneYearNote] } : {}),
       metadata: { status: payload.status, coverage: payload.coverage, latest: payload.latest, stats: payload.stats,
         unit: "decimal annualized volatility", methodology: METHODOLOGY },
     };
@@ -58,7 +62,8 @@ export const ivHistoryHeadless: HeadlessPaneDefinition<"bundle"> = {
 
 export const ivScreenHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
-  freshness: { status: "not-a-feed", basis: "daily implied volatility", cadence: "daily" },
+  // Dated by the readings themselves; the response's own date is the day it was fetched.
+  freshness: { status: "not-a-feed", basis: "daily implied volatility", cadence: "daily", observedKey: "date" },
   argument: { kind: "symbol-list", optional: true, maximum: VCA_LIMIT, description: "US option underlyings; defaults to index and sector ETFs." },
   options: [{ key: "preset", type: "enum", values: [{ value: "etfs" }, { value: "megacaps" }], defaultValue: "etfs", description: "Preset when no symbols are given" }],
   describe: "Volatility rich/cheap",
@@ -73,24 +78,31 @@ export const ivScreenHeadless: HeadlessPaneDefinition<"bundle"> = {
     ]);
     const rows = projectRichCheap(payload.rows, hv).sort((a, b) => (b.percentile ?? -1) - (a.percentile ?? -1));
     const queued = rows.filter((row) => row.status === "queued").map((row) => row.symbol);
-    const shared = sharedReading(rows);
+    const dates = richCheapDates(rows);
     const hasSkew = rows.some((row) => row.skew != null);
+    const hasIv1y = rows.some((row) => row.iv1y != null), hasIv1yRank = rows.some((row) => row.iv1yPercentile != null);
+    const dated = (value: unknown) => typeof value === "string" ? value : "--";
     return {
-      sections: [{ title: `Rich/cheap · ${universe.label}${shared ? ` · ${shared.date} ${shared.method === "quote-mid" ? "live" : "close"}` : ""}`, columns: [
+      sections: [{ title: ["Rich/cheap", universe.label, ...sharedDates(dates)].join(" · "), columns: [
         { key: "symbol", header: "Symbol" }, { key: "iv30", header: "IV30", format: percent },
-        ...(shared ? [] : [{ key: "date", header: "As of" }]),
+        ...(dates.reading ? [] : [{ key: "date", header: "As of", format: (value: unknown, row?: unknown) =>
+          typeof value === "string" ? readingLabel(value, (row as RichCheapRow).method) : "--" }]),
+        ...(dates.rankApart ? [{ key: "rankDate", header: "Rank as of", format: (value: unknown) => typeof value === "string" ? `${value} close` : "--" }] : []),
         { key: "rank", header: "IVR", format: (value: unknown) => formatRank(value as number | null) },
         { key: "percentile", header: "IVP", format: (value: unknown) => formatRank(value as number | null) },
         { key: "verdict", header: "Rich/Cheap", format: (value: unknown) => verdictLabel(value as never) },
+        ...(hasIv1y ? [{ key: "iv1y", header: "IV1Y", format: percent }] : []),
+        ...(hasIv1yRank ? [{ key: "iv1yPercentile", header: "IVP1Y", format: (value: unknown) => formatRank(value as number | null) }] : []),
         { key: "termSlope", header: "30-90", format: (value: unknown) => formatPoints(value as number | null) },
         ...(hasSkew ? [{ key: "skew", header: "25D skew", format: (value: unknown) => formatPoints(value as number | null) }] : []),
+        ...(hasSkew && dates.skewApart ? [{ key: "skewDate", header: "Skew as of", format: dated }] : []),
         { key: "hv", header: "HV20", format: percent },
         { key: "ivHv", header: "IV/HV", format: (value: unknown) => typeof value === "number" ? value.toFixed(2) : "--" },
       ], rows: rows.map((row) => ({ ...row })) }],
       complete: !queued.length && !universe.error, unavailableSymbols: queued,
       errors: [universe.error].filter((value): value is string => !!value),
-      ...(queued.length ? { notes: [`Queued for backfill: ${queued.join(", ")}.`] } : {}),
-      metadata: { asOf: payload.asOf, presets: VCA_PRESETS, methodology: METHODOLOGY },
+      notes: [...queued.length ? [`Queued for backfill: ${queued.join(", ")}.`] : [], ...VCA_DEFINITIONS],
+      metadata: { presets: VCA_PRESETS, methodology: METHODOLOGY },
     };
   },
 };

package/src/plugins/builtin/iv-history/index.tsx

@@ -26,12 +26,12 @@ export const ivHistoryModule: PluginModule = {
   paneTemplates: [
     { ...createTickerSurfacePaneTemplate({
       id: "iv-history-pane", paneId: "iv-history", label: "Implied Volatility History",
-      description: "30 and 90-day ATM implied volatility since 2024 against realized, with IV rank and percentile.",
-      keywords: ["hivg", "implied", "volatility", "history", "iv rank", "ivr", "percentile", "vrp"], shortcut: "HIVG", publicShare: true,
+      description: "30-day, 90-day and one-year ATM implied volatility since 2024 against realized, with IV rank and percentile.",
+      keywords: ["hivg", "implied", "volatility", "history", "iv rank", "ivr", "percentile", "vrp", "iv1y", "leaps"], shortcut: "HIVG", publicShare: true,
     }), headless: ivHistoryHeadless },
     {
       id: "iv-screen-pane", paneId: "iv-screen", label: "Volatility Rich/Cheap",
-      description: "IV rank, percentile, term slope, skew and IV/HV across a list, ranked rich to cheap.",
+      description: "IV rank, percentile, one-year IV, term slope, skew and IV/HV across a list, ranked rich to cheap.",
       keywords: ["vca", "rich", "cheap", "iv rank", "implied volatility", "screen"],
       shortcut: { prefix: "VCA", argKind: "ticker-list" as const, argOptional: true }, headless: ivScreenHeadless,
       createInstance: (_context, options) => ({