gloomberb 0.18.2 → 0.18.4

package/src/plugins/builtin/holders/index-holders.ts

@@ -0,0 +1,264 @@
+import { apiClient } from "../../../api-client";
+import type { HolderData, HolderRecord } from "../../../types/financials";
+import type { TickerHoldings } from "../thirteenf/signals";
+import { logFailure } from "../../../utils/log-failure";
+import { nonUsHolderCaveat } from "./report-header";
+
+/**
+ * A US listing's 13F holders from the SEC 13F holder index, the list `fn 13F`
+ * pages through: every filer that reported the security for the latest
+ * quarter, largest first, 25 to a page. HDS shows them in the units of the
+ * source's own short list (each position at the latest price, the stake as a
+ * share of the class that list divides by), and keeps that short list for a
+ * listing abroad and whenever the index cannot be read.
+ */
+
+/** The most holder rows `fn HDS` and `holders` print. */
+export const HOLDER_ROWS_MAX = 200;
+
+/** One filer's position in the security, summed over the ticker's CUSIPs. */
+export interface IndexedHolder {
+  cik: string;
+  name: string;
+  shares: number;
+  /** Shares at the prior quarter end: 0 for a new position, undefined when unknown. */
+  previousShares?: number;
+}
+
+/** The index's holders loaded so far. */
+export interface IndexedHolderList {
+  rows: IndexedHolder[];
+  /** The report period the positions are as of. */
+  period: string;
+  /** Every filer that holds the security at the period end. */
+  holderCount: number;
+  hasMore: boolean;
+  nextOffset: number;
+  /** A later page failed: the rows are the ones loaded before it, short of the limit asked. */
+  partial?: boolean;
+}
+
+const usTicker = /^[A-Z0-9]{1,10}(\.[A-Z]{1,2})?$/;
+
+/**
+ * The ticker to ask the index for, or null when the listing is not a US
+ * line: a venue abroad (typed `SAN:EPA` or given apart), another currency,
+ * or a home line whose list the service priced from the filings.
+ */
+export function indexHolderTicker(
+  symbol: string | null | undefined,
+  exchange = "",
+  data?: Pick<HolderData, "exchange" | "currency" | "valueBasis"> | null,
+): string | null {
+  const [bare = "", typed = ""] = (symbol ?? "").trim().toUpperCase().split(":");
+  const ticker = bare.replace(/[/-]/g, ".");
+  if (!usTicker.test(ticker)) return null;
+  if (nonUsHolderCaveat(typed || exchange, null) != null) return null;
+  if (data && (data.valueBasis === "period_end_price" || nonUsHolderCaveat(data.exchange, data.currency ?? "USD") != null)) return null;
+  return ticker;
+}
+
+/**
+ * One page of the index's holders. Rows that exited during the quarter, and
+ * option or principal positions, are not holders of the shares; the pages
+ * list the period's holders before its exits, so the list ends where the
+ * holder count does.
+ */
+export function indexedHolderPage(holdings: TickerHoldings): IndexedHolderList {
+  const byCik = new Map<string, IndexedHolder & { previousKnown: boolean }>();
+  for (const row of holdings.rows) {
+    const type = row.type.trim().toUpperCase();
+    if (row.action === "exit" || (type && type !== "SH")) continue;
+    if (row.shares == null || !(row.shares > 0)) continue;
+    const previous = typeof row.previousShares === "number" ? row.previousShares : null;
+    const current = byCik.get(row.cik);
+    if (!current) {
+      byCik.set(row.cik, {
+        cik: row.cik,
+        name: row.fund,
+        shares: row.shares,
+        previousShares: previous ?? undefined,
+        previousKnown: previous != null,
+      });
+      continue;
+    }
+    // Two CUSIPs under one ticker (a re-issued one) are one position.
+    current.shares += row.shares;
+    current.previousKnown &&= previous != null;
+    current.previousShares = current.previousKnown ? (current.previousShares ?? 0) + previous! : undefined;
+  }
+  return {
+    rows: [...byCik.values()].map(({ previousKnown: _known, ...row }) => row),
+    period: holdings.period,
+    holderCount: holdings.holderCount,
+    hasMore: holdings.hasMore && holdings.nextOffset < holdings.holderCount,
+    nextOffset: holdings.nextOffset,
+  };
+}
+
+/** Rows the service gives a page, as `fn 13F` asks for them. */
+const INDEX_PAGE_ROWS = 25;
+/**
+ * Pages one list reads at most: twice what the most rows take, for pages
+ * whose options and exits leave fewer holders, and never without end.
+ */
+const INDEX_PAGES_MAX = Math.ceil(HOLDER_ROWS_MAX / INDEX_PAGE_ROWS) * 2;
+
+/** The client the pages come through; headless reports pass their own. */
+export type IndexedHolderClient = Pick<typeof apiClient, "getCloudSec13F">;
+
+/** One page of 25, as `fn 13F` asks for it, so the two share the service's copy. */
+export async function loadIndexedHolderPage(
+  ticker: string,
+  offset: number,
+  signal?: AbortSignal,
+  client: IndexedHolderClient = apiClient,
+): Promise<IndexedHolderList> {
+  signal?.throwIfAborted();
+  const holdings = await client.getCloudSec13F("ticker-holdings", { tickers: ticker, offset, limit: INDEX_PAGE_ROWS }, { signal }) as TickerHoldings;
+  signal?.throwIfAborted();
+  if (!Array.isArray(holdings?.rows) || typeof holdings.period !== "string") throw new Error(`13F holders of ${ticker} are unreadable`);
+  const page = indexedHolderPage(holdings);
+  // A page that does not move the offset on ends the list, or it would be asked for again and again.
+  return page.nextOffset > offset ? page : { ...page, hasMore: false };
+}
+
+/** Later pages after the first; a page of another period starts the list over. */
+function appendIndexedHolders(current: IndexedHolderList, page: IndexedHolderList): IndexedHolderList {
+  if (current.period !== page.period) return page;
+  const seen = new Set(current.rows.map((row) => row.cik));
+  return { ...page, rows: [...current.rows, ...page.rows.filter((row) => !seen.has(row.cik))] };
+}
+
+/**
+ * The largest `limit` holders, paging as far as that takes, never more than
+ * `INDEX_PAGES_MAX` pages. A later page that fails keeps the holders already
+ * loaded, marked partial; only a first page that fails leaves the source's list.
+ */
+export async function loadIndexedHolders(
+  ticker: string,
+  limit: number,
+  signal?: AbortSignal,
+  client: IndexedHolderClient = apiClient,
+): Promise<IndexedHolderList> {
+  let list = await loadIndexedHolderPage(ticker, 0, signal, client);
+  for (let pages = 1; list.hasMore && list.rows.length < limit && pages < INDEX_PAGES_MAX; pages += 1) {
+    const offset = list.nextOffset;
+    let page: IndexedHolderList;
+    try {
+      page = await loadIndexedHolderPage(ticker, offset, signal, client);
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      logFailure("holders.index", "Read a later page of the 13F holder index failed", null)(error);
+      return { ...list, partial: true };
+    }
+    list = appendIndexedHolders(list, page);
+  }
+  return list;
+}
+
+/** What a list cut short by a failed page says, when it holds fewer rows than were asked for. */
+export function indexedHoldersPartialNote(list: IndexedHolderList | null | undefined, limit: number): string | null {
+  if (!list?.partial || list.rows.length >= limit) return null;
+  return `13F holders past the largest ${list.rows.length} could not be read this time.`;
+}
+
+/** How the source's own rows value and divide a position, which the index's rows take on. */
+export interface IndexedHolderUnits {
+  /** The price a position's shares are valued at. */
+  price?: number;
+  /**
+   * The share count a stake is a share of. The source divides by the class
+   * the line trades (PBR's receipts stand for the common shares alone), not
+   * by every share the company has.
+   */
+  classShares?: number;
+}
+
+function median(values: number[]): number | undefined {
+  if (values.length === 0) return undefined;
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1]! + sorted[middle]!) / 2;
+}
+
+/**
+ * The units of the source's list: its rows' price (shares times the latest
+ * price), else the quote's, and the count its stakes divide by. The stakes
+ * are rounded to four places, so the count is taken over all of them, where
+ * the largest weigh most.
+ */
+export function indexedHolderUnits(data: HolderData | null | undefined, quotePrice?: number | null): IndexedHolderUnits {
+  const rows = (data?.holders ?? []).filter((row) => row.ownerType === "institution" && row.shares != null && row.shares > 0);
+  const price = median(rows.flatMap((row) => (row.value != null && row.value > 0 ? [row.value / row.shares!] : [])))
+    ?? (quotePrice != null && Number.isFinite(quotePrice) && quotePrice > 0 ? quotePrice : undefined);
+  const staked = rows.filter((row) => row.percentHeld != null && row.percentHeld > 0);
+  const held = staked.reduce((sum, row) => sum + row.percentHeld!, 0);
+  const classShares = held > 0 ? staked.reduce((sum, row) => sum + row.shares!, 0) / held : undefined;
+  return {
+    ...(price != null ? { price } : {}),
+    ...(classShares != null && Number.isFinite(classShares) ? { classShares } : {}),
+  };
+}
+
+/** The source's rows of the period by their shares, where only one row has that many. */
+function sourceRowsByShares(source: readonly HolderRecord[], period: string): Map<number, HolderRecord> {
+  const counts = new Map<number, number>();
+  for (const row of source) if (row.reportDate === period && row.shares != null) counts.set(row.shares, (counts.get(row.shares) ?? 0) + 1);
+  return new Map(source.flatMap((row) => row.reportDate === period && row.shares != null && counts.get(row.shares) === 1 ? [[row.shares, row]] : []));
+}
+
+/**
+ * The index's filers as holder rows. A filer whose position is exactly one of
+ * the source's rows keeps that row's value and stake, so the largest holders
+ * read as they did; the others are valued and divided in the same units.
+ */
+function indexedHolderRecords(
+  rows: readonly IndexedHolder[],
+  period: string,
+  units: IndexedHolderUnits,
+  source: readonly HolderRecord[] = [],
+): HolderRecord[] {
+  const known = sourceRowsByShares(source, period);
+  return rows.map((row) => {
+    const change = row.previousShares == null ? undefined : row.shares - row.previousShares;
+    const same = known.get(row.shares);
+    const value = same?.value ?? (units.price != null ? Math.round(row.shares * units.price) : undefined);
+    const percentHeld = same?.percentHeld ?? (units.classShares != null ? row.shares / units.classShares : undefined);
+    return {
+      ownerType: "institution",
+      // The source's spelling of the same holder, not the filer's capitals.
+      name: same?.name ?? row.name,
+      cik: row.cik,
+      reportDate: period,
+      shares: row.shares,
+      ...(value != null ? { value } : {}),
+      ...(percentHeld != null ? { percentHeld } : {}),
+      ...(change != null ? { changeShares: change } : {}),
+      // A fraction of the prior position, as every holder record carries it; a new one has none.
+      ...(change != null && row.previousShares! > 0
+        ? { changePercent: Math.round((change / row.previousShares!) * 1e6) / 1e6 }
+        : {}),
+    };
+  });
+}
+
+/**
+ * The holder list with the index's filers in place of the source's few: the
+ * listing's facts and units as the source gave them, the index's period and
+ * count.
+ */
+export function withIndexedHolders(
+  data: HolderData | null | undefined,
+  symbol: string,
+  list: IndexedHolderList,
+  units: IndexedHolderUnits,
+): HolderData {
+  return {
+    ...(data ?? { symbol, currency: "USD" }),
+    asOf: list.period,
+    holders: indexedHolderRecords(list.rows, list.period, units, data?.holders),
+    summary: { ...data?.summary, institutionsCount: list.holderCount },
+    ...(units.price != null ? { valueBasis: "latest_price" as const } : {}),
+  };
+}

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

@@ -1,13 +1,16 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { Box, Text, TextAttributes, useUiCapabilities } from "../../../ui";
+import { Box, Text, TextAttributes, useUiCapabilities, type ScrollBoxRenderable } from "../../../ui";
 import {
   Badge,
   DataTableView,
+  usePagedRows,
   usePaneFooter,
   usePaneTabs,
   usePaneTicker,
+  useTableLoadMore,
   type DataTableCell,
   type DataTableKeyEvent,
+  type PageRequest,
 } from "../../../components";
 import { handleRefreshKey, loadingErrorFooterInfo } from "../../../components/data-table/table-pane";
 import { useAsyncResource } from "../../../react/async-resource";
@@ -22,8 +25,8 @@ import { THIRTEENF_TEMPLATE_ID } from "../thirteenf/model";
 import { useInResearchTab } from "../ticker-detail/research-tab-keys";
 import {
   displayDate,
+  formatHolderChangePercent,
   formatHolderOwnershipPercent,
-  formatMaybePercent,
   formatMoneyCompact,
   formatSignedCompact,
   holderStakeMarketCap,
@@ -40,15 +43,23 @@ import {
   sortRows,
   VIEW_TABS,
 } from "./table-model";
-import { classSharesToday, loadHolderData } from "./client";
+import { classSharesAsOf, classSharesToday, 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 { indexedHolderUnits, indexHolderTicker, loadIndexedHolderPage, withIndexedHolders } from "./index-holders";
 import { useSampledValue, useTickerQuoteStream } from "../../../state/hooks/live-ticker-financials";
 
 const HOLDER_MARKET_CAP_SAMPLE_MS = 5_000;
+/** Rows past the end of the table that a scroll loads the next page within, as `useTableLoadMore` does. */
+const LOAD_MORE_ROWS = 8;
+
+/** Index rows have their CIK, so their 13F filing needs no name search. */
+function cikMatches(rows: readonly HolderRow[]): Map<string, Holder13FMatch> {
+  return new Map(rows.flatMap((row) => row.cik ? [[row.id, { cik: row.cik, fundName: row.name, periodOfReport: row.reportDate }]] : []));
+}
 
 /** The width of a three-letter badge ("13F", "ADR"): the label and its padding. */
 const BADGE_WIDTH = 5;
@@ -64,6 +75,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   const [fundMatching, setFundMatching] = useState(false);
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const fundMatchAbortRef = useRef<AbortController | null>(null);
+  const tableScrollRef = useRef<ScrollBoxRenderable | null>(null);
 
   const exchange = ticker?.metadata.exchange ?? "";
   const issuerListing = useIssuerListing(ticker);
@@ -80,8 +92,33 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
     keepPreviousData: true,
   });
 
+  // A US line's 13F holders are every filer in the SEC holder index, paged
+  // as fn 13F pages them and asked beside the source's short list, which
+  // stands until the first page answers and whenever the index cannot be read.
+  const indexTicker = indexHolderTicker(symbol, exchange);
+  const loadIndexPage = useMemo(() => indexTicker
+    ? ({ offset, signal }: PageRequest) => loadIndexedHolderPage(indexTicker, offset, signal)
+    : null, [indexTicker]);
+  const index = usePagedRows(loadIndexPage, { getId: (row) => row.cik });
+  // The source's list kept from the previous ticker must not price this one's filers: they wait for its own.
+  const base = data && indexHolderTicker(data.symbol) === indexTicker ? data : null;
+  const indexed = index.rows.length > 0 && (!!base || !loading) && indexHolderTicker(symbol, exchange, base) != null;
+  const indexPending = !!indexTicker && index.loading && index.rows.length === 0;
+  // Index rows take the source's price; the quote's only when the source gave none, sampled so ticks do not re-sort.
+  // The rows follow the units in use, so a quote that is not the price used leaves them as they are.
+  const quotePrice = useSampledValue(financials?.quote?.price, HOLDER_MARKET_CAP_SAMPLE_MS, symbol ?? "");
+  const { price: unitPrice, classShares: unitClassShares } = indexedHolderUnits(base, quotePrice);
+  const listData = useMemo(() => {
+    const first = index.pages[0];
+    if (!indexed || !first || !indexTicker) return data;
+    return withIndexedHolders(base, indexTicker, { ...first, rows: index.rows }, {
+      ...(unitPrice != null ? { price: unitPrice } : {}),
+      ...(unitClassShares != null ? { classShares: unitClassShares } : {}),
+    });
+  }, [base, data, index.pages, index.rows, indexTicker, indexed, unitClassShares, unitPrice]);
+
   // The values' own currency: dollars from the 13F filings on a London line, not its pence.
-  const currency = holderValueCurrency(data, ticker?.metadata.currency || "USD")!;
+  const currency = holderValueCurrency(listData, ticker?.metadata.currency || "USD")!;
   // A stake without a reported percentage is the holding's value over the
   // 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
@@ -91,10 +128,11 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   const marketCap = useSampledValue(liveMarketCap, HOLDER_MARKET_CAP_SAMPLE_MS, `${symbol ?? ""}:${currency}`);
   // Today's share count, which a 13D/13G report's own base is checked against.
   const sharesOutstanding = classSharesToday(financials);
-  const rows = useMemo(() => buildRows(data), [data]);
+  const sharesOutstandingAsOf = classSharesAsOf(financials);
+  const rows = useMemo(() => buildRows(listData), [listData]);
   const periodsDiffer = useMemo(() => holderPeriodsDiffer(rows), [rows]);
   const sortedRows = useMemo(() => sortRows(rows, sortPreference, marketCap), [marketCap, rows, sortPreference]);
-  // Change columns only when the source reports a change; otherwise they read "-" on every row.
+  // Change columns only when the source reports a change; otherwise every row would read as missing.
   const showChange = useMemo(() => hasHolderChanges(rows), [rows]);
   const columns = useMemo(() => buildColumns(width, showChange), [showChange, width]);
   const selectedIdx = selectedId
@@ -114,8 +152,14 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   // restart 25 two-request 13F lookups.
   useEffect(() => {
     fundMatchAbortRef.current?.abort();
+    if (rows.length > 0 && rows.every((row) => row.cik)) {
+      setFundMatches(cikMatches(rows));
+      setFundMatching(false);
+      return;
+    }
     setFundMatches(new Map());
-    if (rows.length === 0) {
+    // The source's rows are not matched while the index's may replace them.
+    if (rows.length === 0 || indexPending) {
       setFundMatching(false);
       return;
     }
@@ -138,7 +182,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
         fundMatchAbortRef.current = null;
       }
     };
-  }, [rows]);
+  }, [indexPending, rows]);
 
   const selectedRow = activeIdx >= 0 ? sortedRows[activeIdx] ?? null : null;
   const selectedFundMatch = selectedRow ? fundMatches.get(selectedRow.id) ?? null : null;
@@ -167,9 +211,12 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
     setViewMode(nextViewMode);
   }, [setViewMode]);
 
+  const reloadIndex = index.reload;
   const refresh = useCallback(() => {
     void reload();
-  }, [reload]);
+    reloadIndex();
+  }, [reload, reloadIndex]);
+  const loadMoreFromScroll = useTableLoadMore(tableScrollRef, indexed && index.hasMore, index.loadMore);
 
   // Plain keys only: Cmd/Ctrl+Shift+R, S and O resize, share and pop out the pane.
   const handleKeyDown = useCallback((event: DataTableKeyEvent) => {
@@ -261,7 +308,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
         };
       case "changePercent":
         return {
-          text: formatMaybePercent(row.changePercent),
+          text: formatHolderChangePercent(row.changePercent),
           color: row.changePercent != null ? priceColor(row.changePercent) : colors.textDim,
         };
       case "percentHeld":
@@ -282,8 +329,14 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
         // One date only when every holder's row is of it; the PERIOD column dates each row.
         ...(periodsDiffer
           ? [{ id: "as-of", parts: [{ text: "latest period per holder", tone: "muted" as const }] }]
-          : data?.asOf ? [{ id: "as-of", parts: [{ text: data.asOf, tone: "value" as const }] }] : []),
-        ...loadingErrorFooterInfo(loading, data ? error : null),
+          : listData?.asOf ? [{ id: "as-of", parts: [{ text: listData.asOf, tone: "value" as const }] }] : []),
+        // The index's first page replaces the source's list, so it is loading too; a failed one leaves that list.
+        ...loadingErrorFooterInfo(loading || (indexPending && !!data), listData ? error : null),
+        ...(index.loadingMore ? [{ id: "loading-more", parts: [{ text: "loading more", tone: "muted" as const }] }] : []),
+        // A later page that failed keeps the rows loaded; scrolling asks for it again.
+        ...(indexed && index.moreError && !index.loadingMore
+          ? [{ id: "more-error", parts: [{ text: "more holders could not be read", tone: "warning" as const }] }]
+          : []),
         ...(fundMatching ? [{ id: "fund-matching", parts: [{ text: "13F matching", tone: "muted" as const }] }] : []),
       ],
       // The title-bar tabs (or the query bar inside Ticker Research) switch
@@ -293,7 +346,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
         ...(selectedFundMatch ? [{ id: "fund", key: "o", label: "pen 13F", onPress: () => openFundDetail(selectedRow) }] : []),
       ],
     };
-  }, [data, error, fundMatching, loading, openFundDetail, periodsDiffer, selectedFundMatch, selectedRow, viewMode]);
+  }, [data, error, fundMatching, index.loadingMore, index.moreError, indexed, indexPending, listData, loading, openFundDetail, periodsDiffer, selectedFundMatch, selectedRow, viewMode]);
 
   const selectView = useCallback((value: string) => setViewMode(value as ViewMode), [setViewMode]);
   // As a research tab, h/l move between research tabs; `s` switches the view.
@@ -313,11 +366,19 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   // values" while the request is still in flight or the pane has no ticker.
   const statusTitle = !symbol
     ? "No ticker selected."
-    : loading && !data
+    : (loading || indexPending) && !listData
       ? "Loading holders..."
-      : !data && error ? error : sortedRows.length === 0 ? "No holders available" : null;
+      : !listData && error ? error : sortedRows.length === 0 ? "No holders available" : null;
   const chartHeight = Math.max(1, height - tabRows - (nativePaneChrome ? 1 : 0));
 
+  // A list shorter than the table cannot scroll to load more, so it pages on
+  // until it fills the table, as a scroll would; a failed page waits for one.
+  const { hasMore: indexHasMore, loading: indexLoading, loadingMore: indexLoadingMore, moreError: indexMoreError, loadMore: loadMoreIndex } = index;
+  useEffect(() => {
+    if (viewMode !== "table" || !indexed || !indexHasMore || indexLoading || indexLoadingMore || indexMoreError) return;
+    if (sortedRows.length < chartHeight + LOAD_MORE_ROWS) loadMoreIndex();
+  }, [chartHeight, indexHasMore, indexLoading, indexLoadingMore, indexMoreError, indexed, loadMoreIndex, sortedRows.length, viewMode]);
+
   return (
     <Box flexDirection="column" width={width} height={height}>
       {nativePaneChrome ? tabStrip : tabStrip && <Box height={1} paddingX={1}>{tabStrip}</Box>}
@@ -333,6 +394,8 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
           }}
           onActivate={openFundDetail}
           onRootKeyDown={handleKeyDown}
+          scrollRef={tableScrollRef}
+          onBodyScrollActivity={loadMoreFromScroll}
           resetScrollKey={data?.symbol}
           rootWidth={width}
           columns={columns}
@@ -354,6 +417,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
           holderRows={rows}
           fundMatches={fundMatches}
           sharesOutstanding={sharesOutstanding}
+          sharesOutstandingAsOf={sharesOutstandingAsOf}
           onCycleView={toggleView}
           onRefreshHolders={refresh}
         />

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

@@ -1,8 +1,9 @@
 import type { HeadlessPaneColumn } from "../../../types/plugin";
 import type { HolderData, ShareBasis } from "../../../types/financials";
-import { formatCompact, formatPercentRaw } from "../../../utils/format";
+import { formatCompact, MISSING_VALUE } from "../../../utils/format";
 import {
   displayDate,
+  formatChangePercent,
   formatMoneyCompact,
   formatPercentHeld,
   formatSignedCompact,
@@ -21,6 +22,7 @@ import {
   nonUsHolderCaveat,
   sharedReportDate,
 } from "./report-header";
+import { HOLDER_ROWS_MAX } from "./index-holders";
 import { buildRows, DEFAULT_SORT, sortRows } from "./table-model";
 import type { HolderColumnId, SortPreference } from "./types";
 
@@ -28,7 +30,8 @@ import type { HolderColumnId, SortPreference } from "./types";
  * A holder as `holders` and `fn HDS` report it; the keys are the JSON
  * contract. `value` is in `currency`, the values' own currency; the percents
  * are in percent (0.59 is 0.59% of the shares outstanding, 13.15 a 13.15%
- * change on the quarter). A figure the source did not give is null.
+ * change on the quarter, 108.6 a position that more than doubled), from the
+ * record's fractions. A figure the source did not give is null.
  */
 export interface HolderReportRow {
   name: string;
@@ -63,14 +66,14 @@ export const HOLDER_REPORT_COLUMNS: HeadlessPaneColumn[] = [
     key: "value",
     header: "Mkt value",
     align: "right",
-    format: (value) => num(value) == null ? "-" : formatCompact(num(value)!),
+    format: (value) => num(value) == null ? MISSING_VALUE : formatCompact(num(value)!),
     textFormat: (value, row) => formatMoneyCompact(num(value) ?? undefined, String(row.currency ?? "USD")),
   },
   {
     key: "shares",
     header: "Amount",
     align: "right",
-    format: (value) => num(value) == null ? "-" : formatCompact(num(value)!),
+    format: (value) => num(value) == null ? MISSING_VALUE : formatCompact(num(value)!),
   },
   {
     key: BASIS_COLUMN_KEY,
@@ -87,13 +90,13 @@ export const HOLDER_REPORT_COLUMNS: HeadlessPaneColumn[] = [
     key: "changePercent",
     header: "Chg%",
     align: "right",
-    format: (value) => num(value) == null ? "-" : formatPercentRaw(num(value)!),
+    format: (value) => formatChangePercent(num(value)),
   },
   {
     key: "percentHeld",
     header: "Held",
     align: "right",
-    format: (value) => num(value) == null ? "-" : `${num(value)!.toFixed(2)}%`,
+    format: (value) => num(value) == null ? MISSING_VALUE : `${num(value)!.toFixed(2)}%`,
     textFormat: (value) => formatPercentHeld(num(value)),
   },
   {
@@ -186,10 +189,13 @@ export function holderReportNotices({
   reported,
   total,
   sort = DEFAULT_SORT,
+  indexed = false,
 }: {
   data: HolderData;
   /** The symbol as asked for, which `fn 13F` takes. */
   requested: string;
+  /** The rows are the SEC 13F holder index's, largest first, not the source's short list. */
+  indexed?: boolean;
   shown: readonly HolderReportRow[];
   /** Holders on the list before a limit. */
   reported: number;
@@ -218,8 +224,14 @@ export function holderReportNotices({
     `Mkt value = ${valueBasis}.`,
     changeReported ? "" : `Change vs prior quarter: not reported by this source; see fn 13F ${requested}`,
   ].filter(Boolean).join(" ");
+  const cut = indexed
+    ? indexedListCut(requested, shown.length, total, sort)
+    // The source names only its largest holders, so a higher limit shows no more of them.
+    : shown.length > 0 && shown.length === reported && total != null && total > reported
+      ? `The source lists its ${reported} largest holders; fn 13F ${requested} lists all ${total.toLocaleString("en-US")}.`
+      : null;
   return {
-    notices: [header, basis, positionsBasis, holderShareBasisNote(data, shown), unvaluedHoldersNote(shown, sort)]
+    notices: [header, basis, cut, positionsBasis, holderShareBasisNote(data, shown), unvaluedHoldersNote(shown, sort)]
       .filter((line): line is string => !!line),
     valueBasis,
     positionsBasis,
@@ -227,6 +239,22 @@ export function holderReportNotices({
   };
 }
 
+/**
+ * What a cut index list leaves out: the rows are its largest holders, so
+ * another order ranks only those, and `--limit` or `fn 13F` shows the rest.
+ */
+function indexedListCut(requested: string, shown: number, total: number | null, sort: SortPreference): string | null {
+  if (shown === 0 || total == null || shown >= total) return null;
+  const within = sort.columnId === "value" || sort.columnId === "shares" ? "" : `Sorted among the ${shown} largest. `;
+  const all = total.toLocaleString("en-US");
+  const more = total <= HOLDER_ROWS_MAX
+    ? `--limit ${total} lists them all.`
+    : shown < HOLDER_ROWS_MAX
+      ? `--limit lists up to ${HOLDER_ROWS_MAX}; fn 13F ${requested} lists all ${all}.`
+      : `fn 13F ${requested} lists all ${all}.`;
+  return within + more;
+}
+
 /**
  * Holders the list gives no value for (a home line's position its filing
  * could not tie to a priced security) sort after every valued one, and a

package/src/plugins/builtin/holders/table-model.ts

@@ -23,7 +23,8 @@ export function nextViewMode(current: ViewMode): ViewMode {
 export function buildRows(data: HolderData | null): HolderRow[] {
   return (data?.holders ?? []).map((holder, index) => ({
     ...holder,
-    id: `${holder.ownerType}:${holder.name}:${holder.reportDate ?? ""}:${index}`,
+    // A filer's CIK names its row across pages; the source's rows have none.
+    id: holder.cik ? `cik:${holder.cik}` : `${holder.ownerType}:${holder.name}:${holder.reportDate ?? ""}:${index}`,
   }));
 }
 

package/src/plugins/builtin/holders/thirteenf-match.ts

@@ -2,6 +2,7 @@ import { listThirteenFForms, normalizeCik, searchThirteenFFunds } from "../thirt
 import { isoDateToday, isoDateYearsAgo } from "../../../utils/calendar-date";
 import { buildPeriodReports } from "../thirteenf/model";
 import type { HolderRow } from "./types";
+import { logFailure } from "../../../utils/log-failure";
 
 export interface Holder13FMatch {
   cik: string;
@@ -100,8 +101,9 @@ export async function loadHolder13FMatches(
           filedAsOfDate: form?.filedAsOfDate,
           tableValueTotal: report?.complete && forms.length < 100 ? report.tableValueTotal : null,
         });
-      } catch {
+      } catch (error) {
         // Matching 13F metadata is an enhancement; holder rows should remain usable.
+        if (!signal.aborted) logFailure("holders.thirteenf-match", "Match holder fund filings failed")(error);
       }
     }
   }

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

@@ -2,8 +2,8 @@ import { useMemo } from "react";
 import { MetricTreemapSurface, type MetricTreemapItem } from "../../../components/metric-treemap";
 import { formatCompact } from "../../../utils/format";
 import {
+  formatHolderChangePercent,
   formatHolderOwnershipLine,
-  formatMaybePercent,
   formatMoneyCompact,
 } from "./format";
 import type { HolderRow } from "./types";
@@ -22,7 +22,7 @@ export function HoldersTreemap({ rows, width, height, selectedId, onSelect, onAc
 }) {
   const items = useMemo<Array<MetricTreemapItem<HolderRow>>>(() => rows.map((row) => {
     const ownership = formatHolderOwnershipLine(row, marketCap);
-    const change = row.changePercent != null ? formatMaybePercent(row.changePercent) : "No change";
+    const change = row.changePercent != null ? formatHolderChangePercent(row.changePercent) : "No change";
     return {
       id: row.id,
       label: row.name,