gloomberb 0.16.1 → 0.16.2

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

@@ -0,0 +1,126 @@
+import type { BeneficialOwnersCoverage, BeneficialOwnersForm, BeneficialOwnersPayload } from "../../../api-client/beneficial-owners";
+import type { HolderData } from "../../../types/financials";
+import {
+  beneficialReportRow,
+  buildBeneficialRows,
+  DEFAULT_BENEFICIAL_SORT,
+  formatClassPercent,
+  formatOwnerShares,
+  formatPointChange,
+  stakeMarker,
+  sortBeneficialRows,
+  type BeneficialReportRow,
+  type BeneficialSortPreference,
+} from "./beneficial-model";
+import { buildRows } from "./table-model";
+
+/** What `holders --form` lists: the 13F table, or the 13D/13G beneficial owners. */
+export type HolderForm = "13f" | "13d" | "13g" | "all";
+export const HOLDER_FORMS: readonly HolderForm[] = ["13f", "13d", "13g", "all"];
+
+export function parseHolderForm(value: unknown): HolderForm | null {
+  const form = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return (HOLDER_FORMS as readonly string[]).includes(form) ? form as HolderForm : null;
+}
+
+export function beneficialRouteForm(form: Exclude<HolderForm, "13f">): BeneficialOwnersForm {
+  return form === "13d" ? "13D" : form === "13g" ? "13G" : "all";
+}
+
+/** Text columns for the 13D/13G rows; CSV and JSON keep the raw values. */
+export const BENEFICIAL_REPORT_COLUMNS = [
+  { key: "filer", header: "Filer", maxWidth: 32 },
+  { key: "form", header: "Form" },
+  {
+    key: "percentOfClass",
+    header: "% Class",
+    align: "right" as const,
+    format: (value: unknown, row: Record<string, unknown>) => {
+      const marker = stakeMarker(row.status === "below-threshold" || row.status === "exited" ? row.status : null);
+      if (typeof value !== "number") return marker || "-";
+      return marker ? `${formatClassPercent(value)} ${marker}` : formatClassPercent(value);
+    },
+  },
+  {
+    key: "changePoints",
+    header: "Chg",
+    align: "right" as const,
+    format: (value: unknown) => formatPointChange(typeof value === "number" ? value : null),
+  },
+  {
+    key: "shares",
+    header: "Shares",
+    align: "right" as const,
+    format: (value: unknown) => formatOwnerShares(typeof value === "number" ? value : null),
+  },
+  { key: "eventDate", header: "Event", format: (value: unknown) => typeof value === "string" ? value : "-" },
+  { key: "filingDate", header: "Filed" },
+  { key: "thirteenF", header: "13F", align: "right" as const, format: (value: unknown) => typeof value === "string" ? value : "-" },
+];
+
+const filings = (count: number) => `${count} ${count === 1 ? "filing" : "filings"}`;
+
+/**
+ * What the list leaves out, a sentence each: reports that could not be read
+ * this time, and reports known only from the EDGAR index whose figures are
+ * blank.
+ */
+export function beneficialCoverageNotices(coverage: BeneficialOwnersCoverage | null | undefined): string[] {
+  if (!coverage) return [];
+  const notices: string[] = [];
+  if (coverage.unavailable) {
+    notices.push(`${coverage.unavailable} of ${filings(coverage.filings)} could not be read this time and are left out, so a filer's row may not be its latest report; a refresh retries them.`);
+  }
+  // Reports that could not be read count as unparsed too.
+  const indexOnly = Math.max(0, coverage.unparsed - (coverage.unavailable ?? 0));
+  if (indexOnly) {
+    notices.push(`Percent of class and shares are blank for ${filings(indexOnly)} known only from the EDGAR index.`);
+  }
+  return notices;
+}
+
+/** What the list covers, for the line above it: `13D/13G filings since 2022-10-09`, `11 filers`. */
+export function beneficialListFacts(
+  payload: Pick<BeneficialOwnersPayload, "coverage">,
+  form: Exclude<HolderForm, "13f">,
+  rows: number,
+  history: boolean,
+): string[] {
+  const kind = form === "all" ? "13D/13G" : form.toUpperCase();
+  const since = payload.coverage?.from ? `${kind} filings since ${payload.coverage.from}` : `${kind} filings`;
+  const count = history ? `${rows} ${rows === 1 ? "report" : "reports"}` : `${rows} ${rows === 1 ? "filer" : "filers"}`;
+  return [since, count];
+}
+
+/** Every page loaded and every filing in the window read. */
+export function beneficialListComplete(payload: Pick<BeneficialOwnersPayload, "hasMore" | "coverage">): boolean {
+  return !payload.hasMore && !payload.coverage?.unavailable && payload.coverage?.complete !== false;
+}
+
+/** No rows although filings are listed: they could not be read, which is not the same as none filed. */
+export function beneficialListUnreadable(payload: Pick<BeneficialOwnersPayload, "owners" | "coverage">): boolean {
+  return payload.owners.length === 0 && (payload.coverage?.filings ?? 0) > 0;
+}
+
+/**
+ * The rows `--form 13d|13g|all` prints: the latest report per filer by
+ * percent of class, stakes under 5% and exits after the 5% holders, or with `history` every report
+ * newest first. The 13F action joins by name to the 13F holders when they
+ * loaded; a report without one shows none.
+ */
+export function buildBeneficialReportRows(
+  payload: BeneficialOwnersPayload,
+  {
+    history = false,
+    holders = null,
+    sort = DEFAULT_BENEFICIAL_SORT,
+  }: { history?: boolean; holders?: HolderData | null; sort?: BeneficialSortPreference } = {},
+): BeneficialReportRow[] {
+  const holderRows = buildRows(holders);
+  if (history) {
+    const filings = [...(payload.filings ?? payload.owners)]
+      .sort((left, right) => right.filingDate.localeCompare(left.filingDate));
+    return buildBeneficialRows(filings, holderRows).map(beneficialReportRow);
+  }
+  return sortBeneficialRows(buildBeneficialRows(payload.owners, holderRows), sort).map(beneficialReportRow);
+}

package/src/plugins/builtin/holders/beneficial-view.tsx

@@ -0,0 +1,241 @@
+import { useCallback, useMemo, useState } from "react";
+import { TextAttributes, useRendererHost } from "../../../ui";
+import {
+  DataTableView,
+  EmptyState,
+  PaneStatusBody,
+  usePaneFooter,
+  usePaneNoticeFooter,
+  type DataTableCell,
+  type DataTableKeyEvent,
+} from "../../../components";
+import { handleRefreshKey, loadingErrorFooterInfo } from "../../../components/data-table/table-pane";
+import { useAsyncResource } from "../../../react/async-resource";
+import { useAutoRefresh } from "../../../react/auto-refresh";
+import { colors, priceColor } from "../../../theme/colors";
+import { isPlainKey } from "../../../utils/keyboard";
+import { nextHeaderSort } from "../../../utils/sort-values";
+import { usePluginAppActions, usePluginPaneState } from "../../runtime";
+import { SignInWall } from "../cloud/auth-actions";
+import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
+import { openSecFilingInPane } from "../sec/command-bar-search";
+import { cachedBeneficialOwners, loadBeneficialOwners } from "./beneficial-client";
+import { beneficialCoverageNotices, beneficialListUnreadable } from "./beneficial-report";
+import {
+  buildBeneficialColumns,
+  buildBeneficialRows,
+  DEFAULT_BENEFICIAL_SORT,
+  formatFilerName,
+  formatOwnerShares,
+  formatPercentOfClass,
+  formatPointChange,
+  sortBeneficialRows,
+  stakeMarker,
+  type BeneficialColumn,
+  type BeneficialColumnId,
+  type BeneficialOwnerRow,
+  type BeneficialSortPreference,
+} from "./beneficial-model";
+import type { Holder13FMatch } from "./thirteenf-match";
+import type { HolderRow } from "./types";
+
+const STALE_SEGMENT = { id: "stale", parts: [{ text: "stale", tone: "warning" as const }] };
+
+/**
+ * The 13D/G tab: who disclosed more than 5% of the class, the stake each
+ * filer's latest report gives and how it moved, one row per filer, joined to
+ * the Table tab's 13F holders for the quarter's action. A latest report is
+ * the latest disclosure, not today's position.
+ */
+export function BeneficialOwnersView({
+  focused,
+  width,
+  symbol,
+  holderRows,
+  fundMatches,
+  onCycleView,
+  onRefreshHolders,
+}: {
+  focused: boolean;
+  width: number;
+  symbol: string | null;
+  holderRows: readonly HolderRow[];
+  fundMatches: ReadonlyMap<string, Holder13FMatch>;
+  onCycleView: () => void;
+  onRefreshHolders: () => void;
+}) {
+  const rendererHost = useRendererHost();
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const session = useResearchCloudSession();
+  const [sortPreference, setSortPreference] = usePluginPaneState<BeneficialSortPreference>(
+    "beneficialSort",
+    DEFAULT_BENEFICIAL_SORT,
+  );
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  // A session change retries a request the sign-in wall was shown for.
+  const loader = useMemo(
+    () => symbol ? (force: boolean) => loadBeneficialOwners(symbol, force) : null,
+    [symbol, session.requestKey],
+  );
+  const resource = useAsyncResource(loader, {
+    initialData: () => symbol ? cachedBeneficialOwners(symbol) : null,
+    clearOnError: (error) => error instanceof Error && isCloudSessionRequired(error.message),
+  });
+  useAutoRefresh(resource.updatedAt, resource.load);
+  const payload = resource.data?.payload ?? null;
+
+  const rows = useMemo(
+    () => buildBeneficialRows(payload?.owners ?? [], holderRows, fundMatches),
+    [fundMatches, holderRows, payload],
+  );
+  const sortedRows = useMemo(() => sortBeneficialRows(rows, sortPreference), [rows, sortPreference]);
+  const columns = useMemo(() => buildBeneficialColumns(width), [width]);
+  const selectedRow = sortedRows.find((row) => row.id === selectedId) ?? sortedRows[0] ?? null;
+
+  const openFiling = useCallback((row: BeneficialOwnerRow | null | undefined) => {
+    if (!row || !symbol) return;
+    openSecFilingInPane({ createPaneFromTemplate }, symbol, row.filing.accessionNumber);
+  }, [createPaneFromTemplate, symbol]);
+
+  const openFilingUrl = useCallback(() => {
+    const url = selectedRow?.filing.filingUrl;
+    if (url) void rendererHost.openExternal(url);
+  }, [rendererHost, selectedRow]);
+
+  const refresh = useCallback(() => {
+    void resource.reload();
+    onRefreshHolders();
+  }, [onRefreshHolders, resource]);
+
+  const handleKeyDown = useCallback((event: DataTableKeyEvent) => {
+    if (handleRefreshKey(event, refresh, { stopPropagation: true })) return true;
+    if (isPlainKey(event, "s")) {
+      event.preventDefault?.();
+      event.stopPropagation?.();
+      onCycleView();
+      return true;
+    }
+    return false;
+  }, [onCycleView, refresh]);
+
+  const handleHeaderClick = useCallback((columnId: string) => {
+    setSortPreference((current) => nextHeaderSort(current, columnId as BeneficialColumnId, {
+      firstDirection: (id) => id === "filer" || id === "form" ? "asc" : "desc",
+    }));
+  }, [setSortPreference]);
+
+  const renderCell = useCallback((
+    row: BeneficialOwnerRow,
+    column: BeneficialColumn,
+    _index: number,
+    rowState: { selected: boolean },
+  ): DataTableCell => {
+    const { filing } = row;
+    // A report of zero reads as history; a stake under 5% is still a stake.
+    const exited = row.stake === "exited";
+    const tone = exited ? colors.textMuted : colors.text;
+    switch (column.id) {
+      case "filer":
+        return {
+          text: formatFilerName(filing.filerName, Math.max(0, filing.reportingPersons.length - 1), column.width),
+          value: filing.filerName,
+          color: exited ? colors.textMuted : rowState.selected ? colors.selectedText : colors.textBright,
+          attributes: exited ? undefined : TextAttributes.BOLD,
+        };
+      case "form":
+        return { text: row.formLabel, color: tone };
+      case "percentOfClass": {
+        // A column too narrow for `4.9% <5%` keeps the figure alone.
+        const marker = column.width >= formatPercentOfClass(row, { marker: true }).length;
+        return {
+          text: formatPercentOfClass(row, { marker }),
+          value: filing.percentOfClass,
+          color: row.stake === "holder" ? colors.textBright : stakeMarker(row.stake) ? colors.textDim : colors.text,
+        };
+      }
+      case "change":
+        return {
+          text: formatPointChange(row.changePoints),
+          value: row.changePoints,
+          color: row.changePoints == null || row.changePoints === 0 ? colors.textDim : priceColor(row.changePoints),
+        };
+      case "shares":
+        return { text: formatOwnerShares(filing.shares), value: filing.shares, color: tone };
+      case "eventDate":
+        return { text: filing.eventDate ?? "-", value: filing.eventDate, color: colors.textDim };
+      case "filingDate":
+        return { text: filing.filingDate, value: filing.filingDate, color: colors.textDim };
+      case "thirteenF": {
+        const action = row.thirteenF;
+        if (!action) return { text: "-", value: null, color: colors.textDim };
+        return { text: action.label, color: action.value === 0 ? colors.textDim : priceColor(action.value) };
+      }
+    }
+  }, []);
+
+  const authWall = !payload && isCloudSessionRequired(resource.error);
+  const error = authWall ? null : resource.error;
+  // Listed filings that could not be read are a failure, not "no filings".
+  const unreadable = !!payload && beneficialListUnreadable(payload);
+  const coverageNotices = useMemo(
+    () => unreadable ? [] : beneficialCoverageNotices(payload?.coverage),
+    [payload, unreadable],
+  );
+  usePaneNoticeFooter({
+    registrationId: "holders-13dg:coverage",
+    notices: coverageNotices,
+    focused,
+    title: "13D/13G coverage",
+  });
+  usePaneFooter("holders-13dg", () => ({
+    info: [
+      ...(payload?.asOf ? [{ id: "as-of", parts: [{ text: `as of ${payload.asOf.slice(0, 10)}`, tone: "muted" as const }] }] : []),
+      ...(payload && resource.data?.stale ? [STALE_SEGMENT] : []),
+      ...loadingErrorFooterInfo(resource.loading, payload ? error : null),
+    ],
+    hints: selectedRow?.filing.filingUrl
+      ? [{ id: "filing", key: "o", label: "pen filing", onPress: openFilingUrl }]
+      : [],
+  }), [error, openFilingUrl, payload, resource.data?.stale, resource.loading, selectedRow]);
+
+  if (!symbol) return <EmptyState title="No ticker selected." />;
+  if (authWall) {
+    return <SignInWall placement="holders-13dg-signin" action="view 13D/13G filings" needsVerification={session.needsVerification} />;
+  }
+
+  return (
+    <PaneStatusBody
+      loading={resource.loading && !payload}
+      error={!payload ? error
+        : unreadable ? `${payload.coverage?.filings ?? 0} filings are listed for ${symbol} but none could be read this time. A refresh retries them.`
+        : null}
+      subject="13D/13G filings"
+      empty={!!payload && sortedRows.length === 0}
+      emptyTitle={`No 13D/13G filings in the last 4 years for ${symbol}.`}
+    >
+      <DataTableView<BeneficialOwnerRow, BeneficialColumn>
+        focused={focused}
+        selection={{
+          kind: "id",
+          selectedId: selectedRow?.id ?? null,
+          getId: (row) => row.id,
+          onChange: (id) => setSelectedId(id),
+        }}
+        onActivate={openFiling}
+        onRootKeyDown={handleKeyDown}
+        resetScrollKey={symbol}
+        rootWidth={width}
+        columns={columns}
+        items={sortedRows}
+        sortColumnId={sortPreference.columnId}
+        sortDirection={sortPreference.direction}
+        onHeaderClick={handleHeaderClick}
+        getItemKey={(row) => row.id}
+        renderCell={renderCell}
+        selectedTextOverridesCellColor
+        emptyStateTitle={`No 13D/13G filings in the last 4 years for ${symbol}.`}
+      />
+    </PaneStatusBody>
+  );
+}

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

@@ -17,6 +17,30 @@ import {
 import { buildRows, sortRows } from "./table-model";
 import type { HolderData } from "../../../types/financials";
 import type { HolderColumnId } from "./types";
+import { SEC_FILINGS } from "../shared/report-freshness";
+import {
+  holderValueBasis,
+  holdersHeaderLine,
+  moneyColumnHeader,
+  nonUsHolderCaveat,
+  sharedReportDate,
+} from "./report-header";
+
+/** Columns a source fills only when it reports the quarter's change. */
+const CHANGE_COLUMN_KEYS = new Set(["changeShares", "changePercent"]);
+import type { BeneficialOwnersPayload } from "../../../api-client/beneficial-owners";
+import { fetchBeneficialOwners, type BeneficialOwnersRequest } from "./beneficial-client";
+import type { BeneficialColumnId } from "./beneficial-model";
+import {
+  BENEFICIAL_REPORT_COLUMNS,
+  beneficialCoverageNotices,
+  beneficialListComplete,
+  beneficialListFacts,
+  beneficialRouteForm,
+  buildBeneficialReportRows,
+  HOLDER_FORMS,
+  parseHolderForm,
+} from "./beneficial-report";
 
 const HOLDER_COLUMNS: HeadlessPaneColumn[] = [
   { key: "name", header: "Holder" },
@@ -71,6 +95,17 @@ const SORT_COLUMNS: Record<string, HolderColumnId> = {
   date: "reportDate",
 };
 
+/** The same sort keys order the 13D/13G rows; `value` and `held` are the percent of class. */
+const BENEFICIAL_SORT_COLUMNS: Record<string, BeneficialColumnId> = {
+  holder: "filer",
+  value: "percentOfClass",
+  shares: "shares",
+  change: "change",
+  "change-percent": "thirteenF",
+  held: "percentOfClass",
+  date: "filingDate",
+};
+
 interface HolderSnapshot {
   data: HolderData;
   marketCap?: number;
@@ -82,17 +117,28 @@ export interface HoldersHeadlessDependencies {
     args: HeadlessPaneLoadArgs,
     ctx: HeadlessPaneContext,
   ): Promise<HolderSnapshot>;
+  loadBeneficialOwners(
+    symbol: string,
+    request: BeneficialOwnersRequest,
+    ctx: HeadlessPaneContext,
+  ): Promise<BeneficialOwnersPayload>;
 }
 
 const defaultDependencies: HoldersHeadlessDependencies = {
   loadSnapshot: (symbol, _args, ctx) => loadHolderSnapshot(ctx.marketData, symbol),
+  loadBeneficialOwners: (symbol, request, ctx) => fetchBeneficialOwners(symbol, request, {
+    client: ctx.apiClient,
+    signal: ctx.signal,
+  }),
 };
 
 export function createHoldersHeadless(
-  dependencies: HoldersHeadlessDependencies = defaultDependencies,
+  overrides: Partial<HoldersHeadlessDependencies> = {},
 ): HeadlessPaneDefinition<"rows"> {
+  const dependencies = { ...defaultDependencies, ...overrides };
   return {
     shape: "rows",
+    freshness: { ...SEC_FILINGS, basis: "13F filings" },
     argument: {
       kind: "ticker",
       placeholder: "ticker",
@@ -124,23 +170,79 @@ export function createHoldersHeadless(
       },
       {
         key: "view",
-        description: "Rendered pane view: the holder table or the ownership treemap.",
+        description: "Rendered pane view: the holder table, the ownership treemap or the 13D/13G beneficial owners.",
         type: "enum",
-        values: [{ value: "table" }, { value: "chart" }],
+        values: [{ value: "table" }, { value: "chart" }, { value: "13dg", aliases: ["beneficial"] }],
         defaultValue: "table",
         pluginState: { pluginId: "ticker-research", key: "viewMode" },
       },
+      {
+        key: "form",
+        description: "Rows: 13f for institutional holders, 13d or 13g for beneficial owners over 5% of the class (activists, crowding into large stakes), all for both kinds.",
+        type: "enum",
+        values: HOLDER_FORMS.map((value) => ({ value })),
+        defaultValue: "13f",
+      },
+      {
+        key: "history",
+        description: "With a 13d, 13g or all form, every report newest first instead of the latest per filer.",
+        type: "boolean",
+        defaultValue: false,
+      },
     ],
     columns: HOLDER_COLUMNS,
     describe: (args) => `Holders | ${args.symbols[0]}`,
     async load(args, ctx) {
       const symbol = args.symbols[0]!;
+      const requestedForm = parseHolderForm(args.options.form) ?? "13f";
+      // The 13D/G view reports what it shows when no form is asked for.
+      const form = requestedForm === "13f" && args.options.view === "13dg" ? "all" : requestedForm;
+      if (form !== "13f") {
+        const history = args.options.history === true;
+        const [payload, snapshot] = await Promise.all([
+          dependencies.loadBeneficialOwners(symbol, { form: beneficialRouteForm(form), history }, ctx),
+          // The 13F column is a join; the 13D/13G rows stand without it.
+          dependencies.loadSnapshot(symbol, args, ctx).catch(() => null),
+        ]);
+        const rows = buildBeneficialReportRows(payload, {
+          history,
+          holders: snapshot?.data ?? null,
+          sort: {
+            columnId: BENEFICIAL_SORT_COLUMNS[String(args.options.sort)] ?? "percentOfClass",
+            direction: args.options.order === "asc" ? "asc" : "desc",
+          },
+        });
+        const limited = rows.slice(0, Number(args.options.limit));
+        return {
+          columns: BENEFICIAL_REPORT_COLUMNS,
+          rows: limited,
+          // Reports that could not be read this time are missing from the rows.
+          complete: beneficialListComplete(payload),
+          freshness: { ...SEC_FILINGS, basis: "13D/13G filings", observedKey: "filingDate" },
+          metadata: {
+            symbol: payload.ticker || symbol,
+            name: payload.companyName || null,
+            cik: payload.cik || null,
+            form,
+            history,
+            asOf: payload.asOf,
+            coverage: payload.coverage,
+            notices: [
+              [payload.companyName || symbol, ...beneficialListFacts(payload, form, rows.length, history)].join(" · "),
+              ...beneficialCoverageNotices(payload.coverage),
+            ],
+            returned: limited.length,
+            total: rows.length,
+          },
+        };
+      }
       const { data, marketCap } = await dependencies.loadSnapshot(symbol, args, ctx);
       const currency = data.currency ?? "USD";
-      const rows = sortRows(buildRows(data), {
+      const sorted = sortRows(buildRows(data), {
         columnId: SORT_COLUMNS[String(args.options.sort)] ?? "value",
         direction: args.options.order === "asc" ? "asc" : "desc",
-      }, marketCap)
+      }, marketCap);
+      const rows = sorted
         .slice(0, Number(args.options.limit))
         .map((row) => ({
           name: row.name,
@@ -153,14 +255,46 @@ export function createHoldersHeadless(
           reportDate: row.reportDate ?? null,
           currency,
         }));
+      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 positionsBasis = rows.length > 0 ? nonUsHolderCaveat(data.exchange, currency) : null;
+      // 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,
+        shown: rows.length,
+        reported: sorted.length,
+        total,
+      });
+      const basis = rows.length === 0 ? null : [
+        `Mkt value = ${valueBasis}.`,
+        changeReported ? "" : `Change vs prior quarter: not reported by this source; see fn 13F ${symbol}`,
+      ].filter(Boolean).join(" ");
       return {
+        // 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),
         rows,
         metadata: {
           symbol: data.symbol || symbol,
           name: data.name ?? null,
+          exchange: data.exchange ?? null,
           currency,
           asOf: data.asOf ?? null,
           summary: data.summary ?? null,
+          shown: rows.length,
+          reported: sorted.length,
+          total,
+          truncated: rows.length < (total ?? sorted.length),
+          valueBasis,
+          changeReported,
+          positionsBasis,
+          notices: [header, basis, positionsBasis].filter((line): line is string => !!line),
         },
       };
     },

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

@@ -1,11 +1,12 @@
 import type { PluginModule } from "../plugin-module";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
+import { beneficialOwnersCache } from "./beneficial-client";
 import { holdersHeadless } from "./headless";
 import { HoldersView } from "./pane";
 
-
 export const holdersModule: PluginModule = {
   setup(ctx) {
+    beneficialOwnersCache.attach(ctx.persistence);
     ctx.registerTickerResearchTab({
       id: "holders",
       name: "Holders",
@@ -14,6 +15,9 @@ export const holdersModule: PluginModule = {
       instruments: ["equity"],
     });
   },
+  dispose() {
+    beneficialOwnersCache.reset();
+  },
 
   panes: [
     {
@@ -35,8 +39,11 @@ export const holdersModule: PluginModule = {
         id: "holders-pane",
         paneId: "holders",
         label: "Holders",
-        description: "Institutional holders for the selected ticker.",
-        keywords: ["holders", "ownership", "institutional", "owners", "hds"],
+        description: "Institutional holders from 13F filings, and 13D/13G beneficial owners: activist and passive stakes over 5% of the class.",
+        keywords: [
+          "holders", "ownership", "institutional", "owners", "hds",
+          "13d", "13g", "13d/g", "schedule 13d", "schedule 13g", "beneficial owners", "beneficial ownership", "activist", "activists",
+        ],
         shortcut: "HDS",
       }),
       headless: holdersHeadless,

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

@@ -30,13 +30,16 @@ import {
 } from "./format";
 import {
   buildColumns,
+  hasHolderChanges,
   buildRows,
   DEFAULT_SORT,
+  nextViewMode,
   sortRows,
   VIEW_TABS,
 } from "./table-model";
 import { loadHolderData } from "./client";
 import { HoldersTreemap } from "./treemap";
+import { BeneficialOwnersView } from "./beneficial-view";
 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";
@@ -77,7 +80,9 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   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]);
-  const columns = useMemo(() => buildColumns(width), [width]);
+  // Change columns only when the source reports a change; otherwise they read "-" on every row.
+  const showChange = useMemo(() => hasHolderChanges(rows), [rows]);
+  const columns = useMemo(() => buildColumns(width, showChange), [showChange, width]);
   const selectedIdx = selectedId
     ? sortedRows.findIndex((row) => row.id === selectedId)
     : -1;
@@ -145,7 +150,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   }, [setSortPreference]);
 
   const toggleView = useCallback(() => {
-    setViewMode((current) => current === "table" ? "chart" : "table");
+    setViewMode(nextViewMode);
   }, [setViewMode]);
 
   const refresh = useCallback(() => {
@@ -250,7 +255,9 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
     }
   }, [currency, fundMatches, marketCap]);
 
+  // The 13D/G tab registers its own footer.
   usePaneFooter("holders", () => {
+    if (viewMode === "13dg") return null;
     return {
       info: [
         ...(data?.asOf ? [{ id: "as-of", parts: [{ text: data.asOf, tone: "value" as const }] }] : []),
@@ -264,7 +271,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, selectedFundMatch, selectedRow]);
+  }, [data, error, fundMatching, loading, openFundDetail, 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.
@@ -316,6 +323,16 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
           selectedTextOverridesCellColor
           emptyStateTitle={statusTitle ?? "No holders available"}
         />
+      ) : viewMode === "13dg" ? (
+        <BeneficialOwnersView
+          focused={focused}
+          width={width}
+          symbol={symbol ?? null}
+          holderRows={rows}
+          fundMatches={fundMatches}
+          onCycleView={toggleView}
+          onRefreshHolders={refresh}
+        />
       ) : (
         <HoldersTreemap
           rows={sortedRows}