gloomberb 0.16.4 → 0.16.5

package/src/plugins/builtin/insider/client.ts

@@ -1,16 +1,19 @@
-import type { DataProvider, SecFilingItem } from "../../../types/data-provider";
+import type { DataProvider } from "../../../types/data-provider";
 import { parseInsiderFiling, type ParsedInsiderFiling } from "./model";
 import { isInsiderForm } from "./insider-data";
+import { filesAsForeignPrivateIssuer } from "./issuer";
 
-async function loadInsiderFilings(
-  provider: DataProvider,
-  symbol: string,
-  count: number,
-  exchange = "",
-): Promise<SecFilingItem[]> {
-  if (!provider.getSecFilings) throw new Error("Insider filing data unavailable");
-  const filings = await provider.getSecFilings(symbol, count, exchange);
-  return filings.filter((filing) => isInsiderForm(filing.form));
+// Recent EDGAR dumps cap at 1,000 mixed forms; older archives are read until
+// this many filings or the company's history ends.
+const SEC_FILING_SCAN_LIMIT = 20_000;
+
+export interface InsiderFilingsLoad {
+  /** The rows of the company's own Form 4 filings, newest first. */
+  parsed: ParsedInsiderFiling[];
+  /** Every Form 4 listed was read, none is the company's own, and it reports as a foreign private issuer. */
+  foreignPrivateIssuer: boolean;
+  /** The SEC lists no filing of any form for the company. */
+  noFilings: boolean;
 }
 
 function throwIfAborted(signal: AbortSignal | undefined): void {
@@ -18,29 +21,41 @@ function throwIfAborted(signal: AbortSignal | undefined): void {
   throw signal.reason instanceof Error ? signal.reason : new Error("Insider filing load was aborted.");
 }
 
+/**
+ * Reads the company's Form 4 filings newest first, one at a time, until
+ * `limit` of them are its own. A form it filed as an owner of another
+ * company's shares is read and left out, so a list of only those is read to
+ * the end before it can say there are none.
+ */
 export async function loadParsedInsiderFilings(
   provider: DataProvider,
   symbol: string,
   options: { limit: number; exchange?: string; signal?: AbortSignal },
-): Promise<ParsedInsiderFiling[]> {
+): Promise<InsiderFilingsLoad> {
+  if (!provider.getSecFilings) throw new Error("Insider filing data unavailable");
   if (!provider.getSecFilingContent) throw new Error("Insider filing content unavailable");
-  const filings = (await loadInsiderFilings(
-    provider,
-    symbol,
-    20_000,
-    options.exchange,
-  )).slice(0, options.limit);
+  const filings = await provider.getSecFilings(symbol, SEC_FILING_SCAN_LIMIT, options.exchange ?? "");
 
   const parsed: ParsedInsiderFiling[] = [];
+  let own = 0;
   for (const filing of filings) {
+    if (own >= options.limit) break;
+    if (!isInsiderForm(filing.form)) continue;
     throwIfAborted(options.signal);
+    let content: string | null;
     try {
-      const content = await provider.getSecFilingContent(filing);
-      parsed.push(...parseInsiderFiling(filing, content));
+      content = await provider.getSecFilingContent(filing);
     } catch {
       throwIfAborted(options.signal);
+      // An unread filing may be the company's own; it stays as a row that says so.
       parsed.push({ filing, transaction: null, isLoading: false });
+      own += 1;
+      continue;
     }
+    const entries = parseInsiderFiling(filing, content);
+    if (entries.length === 0) continue;
+    parsed.push(...entries);
+    own += 1;
   }
-  return parsed;
+  return { parsed, foreignPrivateIssuer: own === 0 && filesAsForeignPrivateIssuer(filings), noFilings: filings.length === 0 };
 }

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

@@ -3,9 +3,11 @@ import type {
   HeadlessPaneContext,
   HeadlessPaneDefinition,
   HeadlessPaneLoadArgs,
+  HeadlessPaneRow,
 } from "../../../types/plugin";
 import { formatCompact, formatCurrency } from "../../../utils/format";
-import { loadParsedInsiderFilings } from "./client";
+import { loadParsedInsiderFilings, type InsiderFilingsLoad } from "./client";
+import { insiderEmptyNotice } from "./issuer";
 import {
   buildInsiderRows,
   buildInsiderSummary,
@@ -15,9 +17,12 @@ import {
   matchesInsiderTypeFilter,
   type ParsedInsiderFiling,
 } from "./model";
-import { relevantInsiderAmendments } from "./amendments";
+import { isAmendedInsiderFiling, relevantInsiderAmendments } from "./amendments";
 import { formatInsiderName } from "./display";
 import { SEC_FILINGS } from "../shared/report-freshness";
+import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
+import { noSecReportsNotice } from "../../../utils/sec";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
 
 const INSIDER_COLUMNS: HeadlessPaneColumn[] = [
   { key: "form", header: "Form" },
@@ -62,15 +67,23 @@ const INSIDER_COLUMNS: HeadlessPaneColumn[] = [
     align: "right",
     format: (value) => value == null ? "-" : `$${formatCompact(Number(value))}`,
   },
+  // An amendment's original date, remarks and footnotes, under the amendment's own row.
+  { key: "note", header: "Note", underRow: true, format: (value) => typeof value === "string" ? value : "" },
 ];
 
+/** What a Form 4/A says about itself, for its last row in the report. */
+function amendmentNote(entry: ParsedInsiderFiling): string {
+  const original = entry.disclosure?.originalFilingDate;
+  return [original ? `Original filed ${original}` : "", ...buildInsiderDisclosureText(entry).split("\n")].filter(Boolean).join("\n");
+}
+
 export interface InsiderHeadlessDependencies {
   loadParsed(
     symbol: string,
     limit: number,
     args: HeadlessPaneLoadArgs,
     ctx: HeadlessPaneContext,
-  ): Promise<ParsedInsiderFiling[]>;
+  ): Promise<InsiderFilingsLoad>;
 }
 
 const defaultDependencies: InsiderHeadlessDependencies = {
@@ -80,6 +93,17 @@ const defaultDependencies: InsiderHeadlessDependencies = {
   }),
 };
 
+/**
+ * "CAR Group (ASX) files no SEC reports." for a listing abroad the SEC lists
+ * nothing for, as `filings` says it; null for a US listing or a symbol with no
+ * venue, whose empty list is only no Form 4.
+ */
+async function noSecReportsEmpty(ctx: HeadlessPaneContext, key: string): Promise<string | null> {
+  const listing = await resolveHeadlessIssuerListing(ctx, key);
+  if (!listing.exchange) return null;
+  return noSecReportsNotice({ symbol: parsePublicTickerKey(key).symbol, exchange: listing.exchange, name: listing.name ?? null });
+}
+
 export function createInsiderHeadless(
   dependencies: InsiderHeadlessDependencies = defaultDependencies,
 ): HeadlessPaneDefinition<"rows"> {
@@ -113,7 +137,7 @@ export function createInsiderHeadless(
       {
         key: "limit",
         aliases: ["count", "rows"],
-        description: "Maximum Form 4 and Form 4/A filings to parse.",
+        description: "Maximum of the company's own Form 4 and Form 4/A filings to parse.",
         type: "integer",
         defaultValue: 20,
         minimum: 1,
@@ -125,7 +149,9 @@ export function createInsiderHeadless(
     async load(args, ctx) {
       const symbol = args.symbols[0]!;
       const limit = Number(args.options.limit);
-      const parsed = await dependencies.loadParsed(symbol, limit, args, ctx);
+      const { parsed, foreignPrivateIssuer, noFilings } = await dependencies.loadParsed(symbol, limit, args, ctx);
+      const empty = parsed.length > 0 ? null
+        : (noFilings ? await noSecReportsEmpty(ctx, symbol) : null) ?? insiderEmptyNotice(foreignPrivateIssuer);
       const name = String(args.options.name ?? "").trim().toLocaleLowerCase();
       const type = isInsiderTypeFilter(args.options.type) ? args.options.type : "all";
       const owned = name
@@ -136,8 +162,16 @@ export function createInsiderHeadless(
       const incomplete = [...new Set(buildInsiderRows(parsed)
         .filter((row) => row.status !== "parsed" && row.status !== "disclosure")
         .map((row) => row.accessionNumber))];
+      // A filing's lines sit together, so its note goes once, under the last of them.
+      const rows: HeadlessPaneRow[] = buildInsiderRows(filtered, parsed).map((row, index) => {
+        const entry = filtered[index]!;
+        const last = filtered[index + 1]?.filing.accessionNumber !== entry.filing.accessionNumber;
+        return isAmendedInsiderFiling(entry) && last ? { ...row, note: amendmentNote(entry) || null } : row;
+      });
       return {
-        rows: buildInsiderRows(filtered, parsed),
+        rows,
+        // Nothing at all: the company has no Form 4 of its own, which is the whole answer.
+        ...(empty ? { empty, unavailableSymbols: [] } : {}),
         errors: [
           ...incomplete.map((accessionNumber) => `${accessionNumber}: Form 4 transactions are unavailable or incomplete.`),
           ...amendments.map((scope) => `${scope.accessionNumber}: Form 4/A is unreconciled; affected transaction totals are unavailable.`),
@@ -146,11 +180,7 @@ export function createInsiderHeadless(
           symbol,
           summary: buildInsiderSummary(owned, Date.now(), parsed),
           amendments,
-          notices: amendments.map((scope) => {
-            const entry = parsed.find(({ filing }) => filing.accessionNumber === scope.accessionNumber)!;
-            return [`Form 4/A ${scope.accessionNumber}${scope.originalFilingDate ? ` | Original filed ${scope.originalFilingDate}` : ""}`,
-              buildInsiderDisclosureText(entry)].filter(Boolean).join("\n");
-          }),
+          foreignPrivateIssuer,
           parsed: new Set(parsed.filter(({ transaction }) => transaction != null).map(({ filing }) => filing.accessionNumber)).size,
           transactions: filtered.filter(({ transaction }) => transaction != null).length,
           requested: limit,

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

@@ -22,7 +22,8 @@ import {
   type StatItem,
 } from "../../../components";
 import { useDebouncedPluginPaneState, usePluginPaneState } from "../../runtime";
-import { mayBeUsEquityTicker } from "../../../utils/sec";
+import { mayBeSecEquityListing, mayBeUsEquityTicker, noSecReportsNotice, nonUsSecListingVenue } from "../../../utils/sec";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
 import { formatCompact } from "../../../utils/format";
 import { nextHeaderSort } from "../../../utils/sort-values";
 import { formatShortDate } from "../../../utils/datetime-format";
@@ -48,6 +49,7 @@ import {
 import { formatInsiderName } from "./display";
 import { insiderHeadless } from "./headless";
 import { isInsiderForm } from "./insider-data";
+import { filesAsForeignPrivateIssuer, insiderEmptyNotice, isOtherIssuerFiling } from "./issuer";
 import { relevantInsiderAmendments } from "./amendments";
 import { usePaneTickerIdentity } from "../../../state/hooks/pane-ticker";
 import {
@@ -130,7 +132,9 @@ function InsiderView({ width, height, focused }: { width: number; height: number
     [setOpenItemIdState],
   );
   const [sort, setSort] = useState<StackSortPreference<InsiderColumnId>>({ columnId: "date", direction: "desc" });
-  const eligibleTicker = mayBeUsEquityTicker(ticker);
+  const eligibleTicker = mayBeSecEquityListing(ticker);
+  // A listing abroad is looked up by its company; an empty list means it files nothing with the SEC.
+  const abroadVenue = ticker ? nonUsSecListingVenue(ticker.metadata.ticker, ticker.metadata.exchange) : null;
   const instrument = instrumentFromTicker(ticker, ticker?.metadata.ticker ?? null);
 
   const filingsEntry = useSecFilingsQuery(
@@ -185,6 +189,17 @@ function InsiderView({ width, height, focused }: { width: number; height: number
     scopeKey: `${ticker?.metadata.ticker ?? "none"}:${ticker?.metadata.exchange ?? ""}`,
     targets: visibleForm4Filings,
   });
+  // The list also holds the Form 4s the company filed as an owner of another
+  // company's shares, which only their documents tell apart. Until one of its
+  // own is read, the pages are read on to the end, so a list of none says so.
+  const ownerFilingsShown = useMemo(() => visibleForm4Filings.some((filing) => (
+    isOtherIssuerFiling(filing, contentMap.get(filing.accessionNumber))
+  )), [contentMap, visibleForm4Filings]);
+  const ownFilingShown = useMemo(() => visibleForm4Filings.some((filing) => (
+    contentMap.has(filing.accessionNumber) && !isOtherIssuerFiling(filing, contentMap.get(filing.accessionNumber))
+  )), [contentMap, visibleForm4Filings]);
+  const searchingOwn = !ownFilingShown && pendingCount === 0 && shownCount < form4Filings.length;
+  const noOwnFilings = !loading && !ownFilingShown && pendingCount === 0 && shownCount >= form4Filings.length;
 
   const allParsed: ParsedFiling[] = useMemo(() => visibleForm4Filings.flatMap((filing) => {
     const hasContent = contentMap.has(filing.accessionNumber);
@@ -223,13 +238,13 @@ function InsiderView({ width, height, focused }: { width: number; height: number
   // load here until it fills a page, back to a year at most.
   const oldestShown = visibleForm4Filings[visibleForm4Filings.length - 1]?.filingDate;
   const oldestShownTime = oldestShown ? new Date(oldestShown).getTime() : Number.NaN;
-  const wantsOlderFilings = (typeFilter !== "all" || nameFilter != null)
+  const wantsOlderFilings = (typeFilter !== "all" || nameFilter != null || ownerFilingsShown)
     && shown.length < Math.max(FORM4_PAGE_SIZE, height)
     && shownCount < Math.min(form4Filings.length, AUTO_FILL_FILING_CAP)
     && oldestShownTime >= Date.now() - AUTO_FILL_DAYS * DAY_MS;
   useEffect(() => {
-    if (wantsOlderFilings && pendingCount === 0) loadNextPage();
-  }, [loadNextPage, pendingCount, shownCount, wantsOlderFilings]);
+    if (searchingOwn || (wantsOlderFilings && pendingCount === 0)) loadNextPage();
+  }, [loadNextPage, pendingCount, searchingOwn, shownCount, wantsOlderFilings]);
 
   const summary = useMemo(() => buildInsiderSummaryFigures(parsed, Date.now(), allParsed), [parsed, allParsed]);
   // A page loading in on scroll clears the totals until it is read; the last
@@ -353,15 +368,17 @@ function InsiderView({ width, height, focused }: { width: number; height: number
   if (authWall) return <SignInWall placement="insider-signin" action="view insider transactions" needsVerification={cloudSession.needsVerification} />;
   if (loading && allFilings.length === 0) return <Spinner label="Loading insider filings..." />;
   if (error && allFilings.length === 0) return <EmptyState title="Insider filings unavailable." message={error} />;
-  if (!loading && form4Filings.length === 0) {
-    return renderFilingNotice(`No Form 4 filings found for ${ticker.metadata.ticker}.`, width);
+  if (noOwnFilings) {
+    return renderFilingNotice(abroadVenue && allFilings.length === 0
+      ? noSecReportsNotice({ symbol: parsePublicTickerKey(ticker.metadata.ticker).symbol, exchange: abroadVenue, name: ticker.metadata.name ?? null })
+      : insiderEmptyNotice(filesAsForeignPrivateIssuer(allFilings)), width);
   }
 
   // Until a filing is read there is nothing to say; after that the empty
   // list says how far back the filings it has read go, while older ones load.
   const oldestRead = allParsed.findLast((entry) => !entry.isLoading)?.filing.filingDate;
   const since = oldestRead ? ` since ${formatShortDate(oldestRead, { utc: true })}` : "";
-  const emptyTitle = typeCounts.all === 0 && (pendingCount > 0 || wantsOlderFilings)
+  const emptyTitle = typeCounts.all === 0 && (pendingCount > 0 || wantsOlderFilings || searchingOwn)
     ? "Loading Form 4 transactions..."
     : typeFilter === "trades"
       ? `No open-market buys or sells${nameFilter ? " by this insider" : ""}${since}.`
@@ -458,7 +475,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 || mayBeUsEquityTicker(options.ticker),
+        canCreate: (_context, options) => !options?.ticker || mayBeSecEquityListing(options.ticker),
       }),
       headless: insiderHeadless,
     },

package/src/plugins/builtin/insider/insider-data.ts

@@ -104,6 +104,16 @@ function disclosureText(xml: string): string {
   return decodeHtmlEntities(xml.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1").replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim());
 }
 
+/**
+ * The CIK of the company whose shares the form reports, without leading
+ * zeros, or null when the document is not a Form 4 or names none.
+ */
+export function parseForm4IssuerCik(xml: string): string | null {
+  if (!/<(?:[\w.-]+:)?ownershipDocument(?:\s|>)/i.test(xml)) return null;
+  const cik = tagText(tagContent(xml, "issuer") ?? "", "issuerCik").replace(/^0+/, "");
+  return /^\d+$/.test(cik) ? cik : null;
+}
+
 export function parseForm4Disclosure(xml: string): InsiderFilingDisclosure | null {
   if (!/<(?:[\w.-]+:)?ownershipDocument(?:\s|>)/i.test(xml)) return null;
   const original = tagText(xml, "dateOfOriginalSubmission");

package/src/plugins/builtin/insider/issuer.ts

@@ -0,0 +1,49 @@
+import type { SecFilingItem } from "../../../types/data-provider";
+import { parseForm4IssuerCik } from "./insider-data";
+
+/**
+ * A company's SEC filing list holds every Form 4 it is named on: its insiders'
+ * trades in its shares, and the ones it filed itself as an owner of another
+ * company's shares (Banco Santander buying Santander Consumer, Sanofi
+ * converting Regeneron notes). Only the form's issuer tells them apart, so a
+ * filing is the company's own until its document names another issuer.
+ */
+export function isOtherIssuerFiling(filing: SecFilingItem, content: string | null | undefined): boolean {
+  if (!content) return false;
+  const issuer = parseForm4IssuerCik(content);
+  const company = filing.cik.trim().replace(/^0+/, "");
+  return issuer != null && /^\d+$/.test(company) && issuer !== company;
+}
+
+const FOREIGN_PRIVATE_ISSUER_FORM = /^(?:20-F|40-F|6-K)(?:\/A)?$/i;
+const DOMESTIC_REPORT_FORM = /^(?:10-KT?|10-QT?|8-K)(?:\/A)?$/i;
+
+function newestFiled(filings: readonly SecFilingItem[], form: RegExp): number {
+  let newest = Number.NEGATIVE_INFINITY;
+  for (const filing of filings) {
+    if (!form.test(filing.form.trim())) continue;
+    const time = new Date(filing.filingDate).getTime();
+    if (Number.isFinite(time) && time > newest) newest = time;
+  }
+  return newest;
+}
+
+/**
+ * The company reports as a foreign private issuer: its newest report is a
+ * 20-F, 40-F or 6-K rather than a 10-K, 10-Q or 8-K. Such an issuer's insiders
+ * file no Form 4, so its list holds only the forms it filed as an owner.
+ */
+export function filesAsForeignPrivateIssuer(filings: readonly SecFilingItem[]): boolean {
+  const foreign = newestFiled(filings, FOREIGN_PRIVATE_ISSUER_FORM);
+  return Number.isFinite(foreign) && foreign > newestFiled(filings, DOMESTIC_REPORT_FORM);
+}
+
+/**
+ * What the pane, `fn INS` and `insider` say when a company has no Form 4 of
+ * its own. Each already names the company above it.
+ */
+export function insiderEmptyNotice(foreignPrivateIssuer: boolean): string {
+  return foreignPrivateIssuer
+    ? "No Form 4 insiders: foreign private issuers file none."
+    : "No Form 4 insider filings.";
+}

package/src/plugins/builtin/insider/model.ts

@@ -3,6 +3,7 @@ import { formatCompact, formatCurrency } from "../../../utils/format";
 import { parseForm4Xml, parseForm4Disclosure, transactionTypeLabel, type InsiderTransaction, type InsiderFilingDisclosure, type InsiderReportingOwner } from "./insider-data";
 import { affectingInsiderAmendments, buildInsiderAmendmentScopes, isAmendedInsiderFiling } from "./amendments";
 import { formatInsiderName, isOpenMarketTrade, shortInsiderRole } from "./display";
+import { isOtherIssuerFiling } from "./issuer";
 
 const NINETY_DAYS_MS = 90 * 24 * 60 * 60 * 1000;
 
@@ -13,7 +14,9 @@ export interface ParsedInsiderFiling {
   disclosure?: InsiderFilingDisclosure | null;
 }
 
+/** The rows of one filing; none for a Form 4 the company filed as an owner of another issuer. */
 export function parseInsiderFiling(filing: SecFilingItem, content: string | null, isLoading = false): ParsedInsiderFiling[] {
+  if (isOtherIssuerFiling(filing, content)) return [];
   const transactions = content ? parseForm4Xml(content) : [];
   const disclosure = content ? parseForm4Disclosure(content) : null;
   return transactions.length

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

@@ -1,5 +1,5 @@
 import { apiClient } from "../../../api-client";
-import { parsePublicTickerKey } from "../../../utils/exchanges";
+import { listingAbroadVenue, usListingSymbol } from "../../../utils/sec";
 import { getSharedMarketDataCoordinator, MarketDataCoordinator, resolveEntryValue } from "../../../market-data/coordinator";
 import type { ChartRequest, InstrumentRef } from "../../../market-data/request-types";
 import type { QueryEntry } from "../../../market-data/result-types";
@@ -8,7 +8,7 @@ import type { PricePoint } from "../../../types/financials";
 import { realizedVolatility, realizedVolatilityCadenceIssue } from "../shared/volatility";
 
 export type IvMethod = "quote-mid" | "trade-close";
-type IvCoverageStatus = "ready" | "backfilling" | "queued" | "unavailable";
+export type IvCoverageStatus = "ready" | "backfilling" | "queued" | "unavailable";
 export interface IvPoint {
   sessionDate: string;
   method: IvMethod;
@@ -67,7 +67,14 @@ export interface IvHistoryPayload {
 }
 export interface IvScreenRow {
   symbol: string;
+  /** Has readings, or none yet. All an older server says; `coverageStatus` is exact. */
   status: "ready" | "queued";
+  /** Where the symbol's history stands, as in `IvHistoryPayload.status`. Absent from older servers. */
+  coverageStatus?: IvCoverageStatus;
+  /** When the symbol was queued and how far its backfill has got; null when it is not covered. */
+  coverage?: { source: "seed" | "demand"; addedAt: string; backfilledThrough: string | null } | null;
+  /** Why it is not covered yet, such as demand coverage being full. */
+  warnings?: string[];
   iv30: IvStats | null;
   iv90: IvStats | null;
   iv365?: IvStats | null;
@@ -88,14 +95,17 @@ export interface StoredSurfacePayload {
 export type ImpliedVolatilityApi = Pick<typeof apiClient, "impliedVolatility">;
 const query = (params: Record<string, string>) => new URLSearchParams(params).toString();
 /** Stored IV is keyed by the bare US symbol; a listing key ("SPY:ARCX") drops its exchange. */
-export const ivSymbol = (symbol: string) => parsePublicTickerKey(symbol.trim()).symbol.toUpperCase();
+/** A US listing's symbol; a listing abroad is refused, since its bare symbol's options are another company's. */
+export const ivSymbol = (symbol: string) => usListingSymbol(symbol, "Implied volatility");
 
 export function loadIvHistory(symbol: string, options: { signal?: AbortSignal; days?: number } = {}, api: ImpliedVolatilityApi = apiClient) {
   return api.impliedVolatility<IvHistoryPayload>(`history?${query({ symbol: ivSymbol(symbol), days: String(options.days ?? 1100) })}`,
     { signal: options.signal });
 }
+/** A listing abroad has no row: its bare symbol's options are another company's. */
 export function loadIvScreen(symbols: readonly string[], options: { signal?: AbortSignal } = {}, api: ImpliedVolatilityApi = apiClient) {
-  return api.impliedVolatility<IvScreenPayload>(`screen?${query({ symbols: symbols.map(ivSymbol).join(",") })}`, { signal: options.signal });
+  const us = symbols.filter((symbol) => listingAbroadVenue(symbol) == null).map(ivSymbol);
+  return api.impliedVolatility<IvScreenPayload>(`screen?${query({ symbols: us.join(",") })}`, { signal: options.signal });
 }
 export function loadSurfaceDates(symbol: string, options: { signal?: AbortSignal } = {}, api: ImpliedVolatilityApi = apiClient) {
   return api.impliedVolatility<{ version: 1; symbol: string; dates: string[] }>(`surface-dates?${query({ symbol: ivSymbol(symbol) })}`,

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

@@ -3,7 +3,7 @@ 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, 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 { HV_WINDOWS, type HvWindow, type IvLookback, type IvStatRow, projectIvHistory, projectRichCheap, type RichCheapRow, richCheapDates, screenCoverage, VCA_LIMIT, VCA_PRESETS } from "./model";
 import { vcaUniverse } from "./universe";
 
 const METHODOLOGY = "docs/research-data.md#implied-volatility-history";
@@ -11,6 +11,7 @@ const percent = (value: unknown) => typeof value === "number" ? formatVol(value)
 
 export const ivHistoryHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "US option underlying" },
+  usListingsOnly: "Implied volatility history",
   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"],
@@ -65,6 +66,7 @@ export const ivScreenHeadless: HeadlessPaneDefinition<"bundle"> = {
   // 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." },
+  usListingsOnly: "Implied volatility",
   options: [{ key: "preset", type: "enum", values: [{ value: "etfs" }, { value: "megacaps" }], defaultValue: "etfs", description: "Preset when no symbols are given" }],
   describe: "Volatility rich/cheap",
   discovery: { aliases: ["VCA"], screenshotReadiness: "live-dom", dataRequirements: ["Cloud stored implied volatility", "Daily price history"],
@@ -77,7 +79,7 @@ export const ivScreenHeadless: HeadlessPaneDefinition<"bundle"> = {
       loadRealizedVolatilities(universe.instruments, 20, { signal: ctx.signal }, createHvDependencies(ctx.marketData)),
     ]);
     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 coverage = screenCoverage(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);
@@ -99,9 +101,10 @@ export const ivScreenHeadless: HeadlessPaneDefinition<"bundle"> = {
         { 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,
+      // A symbol with no options history is final; only history still to come leaves the screen incomplete.
+      complete: !coverage.pending.length && !universe.error, unavailableSymbols: coverage.missing,
       errors: [universe.error].filter((value): value is string => !!value),
-      notes: [...queued.length ? [`Queued for backfill: ${queued.join(", ")}.`] : [], ...VCA_DEFINITIONS],
+      notes: [...coverage.notes, ...VCA_DEFINITIONS],
       metadata: { presets: VCA_PRESETS, methodology: METHODOLOGY },
     };
   },

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

@@ -1,4 +1,5 @@
 import type { PluginModule } from "../plugin-module";
+import { IV_SERIES } from "./series";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import { ivHistoryHeadless, ivScreenHeadless } from "./headless";
 import { IvHistoryPane } from "./pane";
@@ -6,6 +7,7 @@ import { IvScreenPane, VCA_SCOPE_OPTIONS } from "./screen-pane";
 
 
 export const ivHistoryModule: PluginModule = {
+  series: IV_SERIES,
   panes: [{
     id: "iv-history", name: "Implied Volatility History", icon: "V", component: IvHistoryPane,
     defaultPosition: "right", tickerFollower: true, defaultMode: "floating", defaultFloatingSize: { width: 118, height: 36 },