gloomberb 0.16.3 → 0.16.5

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

@@ -3,7 +3,7 @@ import { isAccessDenied } from "../../../api-client/errors";
 import { SignInWall } from "../cloud/auth-actions";
 import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
-import { useCallback } from "react";
+import { useCallback, useMemo } from "react";
 import { PaneStatusBody, usePaneFooter, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs } from "../../../components";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActions, usePluginPaneState } from "../../../public/react";
@@ -11,11 +11,11 @@ import { usePaneInstance } from "../../../state/app/context";
 import type { PaneProps } from "../../../types/plugin";
 import { Box } from "../../../ui";
 import { GpuBoard } from "./board";
-import { getCachedGpuBoard, gpuCacheScope, GPU_NOT_AVAILABLE, loadGpuBoard } from "./client";
+import { getCachedGpuBoard, gpuCacheScope, GPU_NOT_AVAILABLE, gpuPreviewModels, loadGpuBoard, loadGpuModelPreviews } from "./client";
 import { GpuChanges } from "./changes";
 import { GpuEquities } from "./equities";
 import { GpuHistory } from "./history";
-import { GPU_TABS, gpuTab, gpuTime } from "./model";
+import { GPU_TABS, gpuEquityModels, gpuFamilies, gpuFamily, gpuNoMatch, gpuTab, gpuTime } from "./model";
 
 export function GpuPane(props: PaneProps) {
   usePlanAccess();
@@ -34,12 +34,28 @@ function GpuView({ width, height, focused }: PaneProps) {
   const resource = useAsyncResource(loadGpuBoard, { initialData: getCachedGpuBoard, clearOnError: isAccessDenied });
   const data = resource.data?.payload;
   const { createPaneFromTemplate } = usePluginAppActions();
+  const locked = !!data?.access?.locked;
+  const families = useMemo(() => gpuFamilies(data?.rows ?? []), [data]);
+  // What was typed ("h-100", "H100 80GB SXM") reads as the GPU it names; a name that matches none stays as typed and says so.
+  const activeModel = model ? gpuFamily(model, families) ?? model : "";
+  const unknownModel = !!model && !families.includes(activeModel);
+  // The free board is one GPU's three rows; another GPU's free preview stands in for the rows it leaves out.
+  const previewKey = useMemo(() => data && !unknownModel ? gpuPreviewModels(data, tab === "equities" ? gpuEquityModels(activeModel || "H100")
+    : tab === "changes" ? [] : tab === "history" ? [activeModel || "H100"] : [activeModel]).join("\n") : "", [data, unknownModel, tab, activeModel]);
+  const previewLoader = useCallback((force: boolean) => loadGpuModelPreviews(previewKey.split("\n"), force), [previewKey]);
+  const preview = useAsyncResource(previewKey ? previewLoader : null);
+  const rows = useMemo(() => data ? [...data.rows, ...(previewKey ? preview.data ?? [] : [])] : [], [data, previewKey, preview.data]);
+  const models = useMemo(() => locked ? [...families].sort() : [...new Set(rows.map((row) => row.gpuModel))].sort(), [locked, families, rows]);
+  // A failed preview is the footer's error; the body does not repeat it.
+  const emptyTitle = unknownModel ? gpuNoMatch(model, families)
+    : preview.error ? `No ${activeModel} rental prices to show.` : `No ${activeModel} rental prices have been observed yet.`;
   useAutoRefresh(resource.updatedAt, resource.load);
-  usePaneRefreshKey(() => void resource.reload(), { focused: focused && (tab === "board" || !data) });
+  useAutoRefresh(preview.updatedAt, preview.load);
+  usePaneRefreshKey(() => { void resource.reload(); void preview.reload(); }, { focused: focused && (tab === "board" || !data) });
   const signIn = !data && (session.needsVerification || isCloudSessionRequired(resource.error));
   const notAvailable = !data && resource.error === GPU_NOT_AVAILABLE;
-  usePaneStatusFooter({ registrationId: "gpu", loading: resource.loading, error: notAvailable || signIn ? null : resource.error,
-    stale: !!data && (data.stale || resource.data?.stale), info: data?.asOf ? [{ id: "asof", parts: [{ text: `as of ${gpuTime(data.asOf)}`, tone: "muted" }] }] : [] });
+  usePaneStatusFooter({ registrationId: "gpu", loading: resource.loading || preview.loading, error: notAvailable || signIn ? null : resource.error ?? preview.error,
+    stale: !!data && (data.stale || resource.data?.stale), info: data?.asOf ? [{ id: "asof", asOf: true, parts: [{ text: `as of ${gpuTime(data.asOf)}`, tone: "muted" }] }] : [] });
   usePaneNoticeFooter({ registrationId: "gpu:notices", focused,
     notices: [...(data?.gaps ?? []), ...(resource.data?.refreshError ? [resource.data.refreshError] : [])] });
   usePaneFooter("gpu:actions", () => ({ info: data?.access?.preview ? [{ id: "preview", parts: [{ text: "Free preview", tone: "muted" }] }] : [],
@@ -47,17 +63,17 @@ function GpuView({ width, height, focused }: PaneProps) {
     onPress: () => createPaneFromTemplate("buildout-pane") }] }), [createPaneFromTemplate, data?.access, upgrade]);
   const { strip, rows: tabRows } = usePaneTabs(data ? { tabs: [...GPU_TABS], activeValue: tab, onSelect: setTab, focused, dense: true } : null);
   const body = { width, height: Math.max(3, height - tabRows), focused };
-  const reloadBoard = useCallback(() => { void resource.reload(); }, [resource.reload]);
+  const reloadBoard = useCallback(() => { void resource.reload(); void preview.reload(); }, [resource.reload, preview.reload]);
   if (signIn) return <SignInWall placement="gpu" width={width} height={height} action="browse GPU rental prices" needsVerification={session.needsVerification} />;
   return <Box width={width} height={height} flexDirection="column">
     {strip}
-    <PaneStatusBody loading={resource.loading && !data} error={!data && !notAvailable ? resource.error : null}
+    <PaneStatusBody loading={(resource.loading && !data) || (!!previewKey && preview.loading && !preview.data)} error={!data && !notAvailable ? resource.error : null}
       empty={notAvailable} emptyTitle={GPU_NOT_AVAILABLE} subject="GPU rental prices">
-      {data ? tab === "board" ? <GpuBoard rows={data.rows} asOf={data.asOf} model={model} setModel={setModel} selectedId={selectedId}
+      {data ? tab === "board" ? <GpuBoard rows={rows} models={models} asOf={data.asOf} model={activeModel} setModel={setModel} selectedId={selectedId} emptyTitle={emptyTitle}
         select={(row, open) => { setSelectedId(row.id); if (open) setTab("history"); }} {...body} />
-        : tab === "history" ? <GpuHistory rows={data.rows} model={model} setModel={setModel} selectedId={selectedId} onSelect={setSelectedId} reloadBoard={reloadBoard} {...body} />
-          : tab === "changes" ? <GpuChanges board={data.rows} model={model} setModel={setModel} reloadBoard={reloadBoard} {...body} />
-            : <GpuEquities board={data.rows} model={model} setModel={setModel} reloadBoard={reloadBoard} {...body} /> : null}
+        : tab === "history" ? <GpuHistory rows={rows} models={models} model={unknownModel ? "" : activeModel} setModel={setModel} selectedId={selectedId} onSelect={setSelectedId} reloadBoard={reloadBoard} {...body} />
+          : tab === "changes" ? <GpuChanges models={models} model={unknownModel ? "" : activeModel} setModel={setModel} reloadBoard={reloadBoard} {...body} />
+            : <GpuEquities board={rows} models={models} locked={locked} model={unknownModel ? "" : activeModel} setModel={setModel} reloadBoard={reloadBoard} {...body} /> : null}
     </PaneStatusBody>
   </Box>;
 }

package/src/plugins/builtin/gpu/series.ts

@@ -0,0 +1,38 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { cachedSeriesWarning } from "../shared/series-warning";
+import { loadGpuBoard, loadGpuHistory } from "./client";
+import { GPU_MODELS, gpuListIndex } from "./model";
+
+/** What the GPU pane says when the free preview leaves history out. */
+const GPU_PRO_ONLY = "Full history is available with Pro.";
+
+/**
+ * Each GPU's list index, the one the GPU pane's Equities tab reads shares
+ * against. The per-provider listings stay on the board and its History tab:
+ * the server lists them, and they come and go.
+ */
+export const GPU_SERIES: readonly SeriesDefinition[] = GPU_MODELS.map((model): SeriesDefinition => ({
+  id: `gpu:${model.toLowerCase().replaceAll(" ", "-")}-list-index`,
+  name: `${model} rental list index`,
+  unit: "USD/GPU-hour",
+  frequency: "intraday",
+  group: "Alternative data",
+  tags: ["GPU", "rental", "compute", "cloud", "list price", model],
+  description: `Median list price to rent one ${model} from neocloud providers (hyperscalers where none list it), chained so a change of providers causes no jump, as GPU charts it. Needs Pro.`,
+  style: "step",
+  load: async () => {
+    const board = await loadGpuBoard();
+    if (board.payload.access?.locked) throw new Error(GPU_PRO_ONLY);
+    const index = gpuListIndex(board.payload.rows, model);
+    if (!index) throw new Error(`No ${model} list index is listed yet.`);
+    const history = await loadGpuHistory(index.id);
+    if (history.payload.access?.locked) throw new Error(GPU_PRO_ONLY);
+    const warning = cachedSeriesWarning(history);
+    return {
+      points: history.payload.points
+        .filter((point) => `${point.source}:${point.skuKey}` === index.id)
+        .map((point) => ({ date: point.observedAt, value: point.pricePerGpuHr })),
+      ...(warning ? { warning } : {}),
+    };
+  },
+}));

package/src/plugins/builtin/help/function-card.tsx

@@ -2,8 +2,10 @@
  * The help card for one function, opened by `HELP <fn>` in the command bar
  * and F1 on a focused pane: what it answers, how to type it, the keys that
  * matter in its pane, how fresh its data is on each plan, its Bloomberg
- * equivalent and its docs entry. Enter or the link opens the docs; Esc, the
- * close button or a click outside closes it.
+ * equivalent and its docs entry. Enter reads the entry in DOCS, inside the
+ * app; the link beside it is the same entry on gloom.sh, in the browser. A
+ * popped-out window cannot open a pane, so there Enter opens the link. Esc,
+ * the close button or a click outside closes it.
  *
  * `useFunctionHelpHost` is mounted with the app's global shortcuts for the
  * life of the window and owns the dialog; `requestFunctionHelp` lets the
@@ -13,7 +15,9 @@ import { useEffect, useRef, type ReactNode } from "react";
 import { usePlanAccess } from "../../../api-client/plan-access";
 import { functionDocsUrl, type FunctionFreshness, type FunctionHelpKey } from "../../../cli/pane-functions/function-help";
 import { requestFeedbackDialog } from "../../../components/feedback-dialog";
+import { Button } from "../../../components/ui/button";
 import { ExternalLink } from "../../../components/ui/external-link";
+import { DOCS_PANE_TEMPLATE_ID } from "../../../docs/content";
 import { DialogFrame } from "../../../components/ui/frame";
 import { ShortcutHint } from "../../../components/ui/shortcut-hint";
 import { t } from "../../../i18n";
@@ -21,10 +25,12 @@ import { useViewport } from "../../../react/input";
 import { useThemeColors } from "../../../theme/theme-context";
 import { Box, Text, TextAttributes, useRendererHost } from "../../../ui";
 import { useDialog, useDialogKeyboard, type AlertContext } from "../../../ui/dialog";
+import { getSharedRegistry } from "../../registry";
 import type { HelpFunction } from "./function-index";
 
 export type FunctionHelpRequest =
-  | { kind: "function"; fn: HelpFunction }
+  /** `inAppDocs: false` where DOCS cannot open (a popped-out window). */
+  | { kind: "function"; fn: HelpFunction; inAppDocs?: boolean }
   /** `HELP HELP`: the feedback dialog, which is how people reach us. */
   | { kind: "support" };
 
@@ -103,9 +109,10 @@ function FreshnessRows({ data, pro }: { data: FunctionFreshness; pro: boolean })
   );
 }
 
-function FunctionHelpCard({ fn, dismiss, dialogId, width, compact = false }: AlertContext & {
+function FunctionHelpCard({ fn, dismiss, dialogId, width, compact = false, inAppDocs = true }: AlertContext & {
   fn: HelpFunction;
   width: number;
+  inAppDocs?: boolean;
   /** A short terminal: no blank row between the summary and the rows. */
   compact?: boolean;
 }) {
@@ -117,6 +124,10 @@ function FunctionHelpCard({ fn, dismiss, dialogId, width, compact = false }: Ale
     void rendererHost.openExternal(url);
     dismiss();
   };
+  const readInApp = () => {
+    getSharedRegistry()?.createPaneFromTemplate(DOCS_PANE_TEMPLATE_ID, { arg: fn.code });
+    dismiss();
+  };
 
   useDialogKeyboard((event) => {
     if (event.ctrl || event.alt || event.meta || event.super) return;
@@ -124,7 +135,8 @@ function FunctionHelpCard({ fn, dismiss, dialogId, width, compact = false }: Ale
     if (name !== "enter" && name !== "return") return;
     event.preventDefault();
     event.stopPropagation();
-    openDocs();
+    if (inAppDocs) readInApp();
+    else openDocs();
   }, { scope: dialogId });
 
   const help = fn.help;
@@ -153,6 +165,11 @@ function FunctionHelpCard({ fn, dismiss, dialogId, width, compact = false }: Ale
             </CardRow>
           )}
           <CardRow label="Docs">
+            {inAppDocs && (
+              <Box flexDirection="row">
+                <Button label="Read in Docs" shortcut="Enter" compact onPress={readInApp} stopPropagation />
+              </Box>
+            )}
             <ExternalLink url={docsUrl} label={docsUrl.replace(/^https:\/\//, "")} onOpen={openDocs} />
           </CardRow>
         </Box>
@@ -189,7 +206,9 @@ export function useFunctionHelpHost({ closeCommandBar }: { closeCommandBar: () =
         closeOnClickOutside: true,
         // The terminal host defaults to 60 columns; the desktop sizes to the content.
         style: { width: width + TERMINAL_DIALOG_CHROME, ...(compact ? { paddingY: 0 } : {}) },
-        content: (context: AlertContext) => <FunctionHelpCard {...context} fn={request.fn} width={width} compact={compact} />,
+        content: (context: AlertContext) => (
+          <FunctionHelpCard {...context} fn={request.fn} width={width} compact={compact} inAppDocs={request.inAppDocs !== false} />
+        ),
       }).catch(() => {}).finally(() => {
         openRef.current = false;
       });

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

@@ -8,10 +8,11 @@ import { Box, ScrollBox, Text, useRendererHost, useUiHost } from "../../../ui";
 import { detectShortcutPlatform, formatPrimaryShortcut, getShortcutDisplayMode } from "../../../utils/shortcut-labels";
 import { getSharedRegistry } from "../../registry";
 import { apiClient, type CloudPricing } from "../../../api-client";
-import { trialDaysOf } from "../account-management/model";
+import { trialDaysOf } from "../../../account/billing";
 import { usePluginAppActions, usePluginPaneState } from "../../runtime";
 import type { PluginModule } from "../plugin-module";
 import { requestFeedbackDialog } from "../../../components/feedback-dialog";
+import { DOCS_PANE_TEMPLATE_ID } from "../../../docs/content";
 import { FeedbackTab } from "./feedback-tab";
 import { FunctionsTable } from "./functions-table";
 import { KeybindingsEditor } from "./keybindings-editor";
@@ -36,7 +37,7 @@ function entry(id: string, badges: string[], description: string): ShortcutTable
 
 function HelpPane({ focused, width, height }: PaneProps) {
   const registry = getSharedRegistry();
-  const { openCommandBar, showPane } = usePluginAppActions();
+  const { openCommandBar, showPane, createPaneFromTemplate } = usePluginAppActions();
   // A key capture requested from the command bar belongs to the Shortcuts
   // tab, whether the pane is already open or is being opened for it.
   const [activeTabId, setActiveTabId] = usePluginPaneState<HelpTabId>("activeTab", "basics");
@@ -100,6 +101,10 @@ function HelpPane({ focused, width, height }: PaneProps) {
     openCommandBar("PL ");
   }, [openCommandBar]);
 
+  const openDocs = useCallback(() => {
+    createPaneFromTemplate(DOCS_PANE_TEMPLATE_ID);
+  }, [createPaneFromTemplate]);
+
   const openIssues = useCallback(() => {
     void rendererHost.openExternal(GLOOMBERB_ISSUES_URL);
   }, [rendererHost]);
@@ -107,7 +112,10 @@ function HelpPane({ focused, width, height }: PaneProps) {
   // Each tab's actions. `l` moves between tabs, so layout actions take `a`.
   const tabHints = useMemo<PaneHint[]>(() => {
     if (activeTabId === "basics") {
-      return [{ id: "layout-actions", key: "a", label: " layout actions", title: "Layout Actions", onPress: openLayoutActions }];
+      return [
+        { id: "docs", key: "d", label: "ocs", title: "Open Docs", onPress: openDocs },
+        { id: "layout-actions", key: "a", label: " layout actions", title: "Layout Actions", onPress: openLayoutActions },
+      ];
     }
     if (activeTabId === "functions") {
       return [{ id: "plugins", key: "p", label: "lugins", title: "Manage Plugins", onPress: openPluginManager }];
@@ -120,7 +128,7 @@ function HelpPane({ focused, width, height }: PaneProps) {
       ];
     }
     return [];
-  }, [activeTabId, openDebugLog, openIssues, openLayoutActions, openPluginManager]);
+  }, [activeTabId, openDebugLog, openDocs, openIssues, openLayoutActions, openPluginManager]);
 
   // The footer binds each hint's key; a search field keeps its typing.
   usePaneFooter("help:tab", () => tabHints.length > 0 ? { hints: tabHints } : null, [tabHints]);
@@ -152,7 +160,9 @@ function HelpPane({ focused, width, height }: PaneProps) {
         : []),
       entry("des", ["DES", "<ticker>"], "Open security details for a specific ticker."),
       entry("help-card", ["HELP", "<function>"], "Open a function's help card: what it shows, its keys, how fresh its data is. HELP HELP reaches support."),
+      entry("docs", ["DOCS", "<function>"], "Read the docs and Academy lessons in the app. The ? on a pane opens its entry."),
       entry("upgrade", ["UPGRADE"], tf("Go Pro for real-time data at gloom.sh/cloud, free for {days} days.", { days: trialDays })),
+      entry("mcp", ["MCP"], "Connect Claude Code, Codex, Cursor or any MCP client to Gloom's research tools."),
       entry("move", ["Up/Down", "Ctrl+P/N"], "Move through command bar results."),
       entry("page", ["PageUp/PageDown", "Ctrl+Home/End"], "Jump a page, or to the first or last result."),
       entry("run", ["Enter", "Shift+Enter"], "Run the selected result or its secondary action."),
@@ -174,7 +184,7 @@ function HelpPane({ focused, width, height }: PaneProps) {
         entry("back", ["Esc", "Backspace"], "Go back from a detail view."),
         entry("pane-menu", actionBadges("pane-menu"), "Open the focused pane's menu: every action in the pane with its key, sorting, filters, tabs, toggles and the pane actions."),
         ...(functionHelpBadges.length > 0
-          ? [entry("function-help", functionHelpBadges, "Open the focused pane's help card, with a link to its docs.")]
+          ? [entry("function-help", functionHelpBadges, "Open the focused pane's help card; Enter reads its docs.")]
           : []),
         entry("search", ["/"], "Search in the focused pane."),
         entry("warnings", ["!"], "Open the focused pane's data warnings."),
@@ -266,11 +276,11 @@ function HelpPane({ focused, width, height }: PaneProps) {
               <SectionHeading title="How To Use Gloomberb" />
               <Box flexDirection="column">
                 <Text fg={colors.textDim}>{t("Gloomberb is command-bar first.")}</Text>
-                <Text fg={colors.textDim}>{t("Use the keyboard for speed, and the mouse for windows.")}</Text>
+                <Text fg={colors.textDim} wrapText>{t("Click anything to use it; the keys shown beside actions are shortcuts.")}</Text>
                 <Text fg={colors.textDim} wrapText>
                   {commandBarBadges[0]
-                    ? tf("Not sure of a code? Press {key} and type what you want in plain words, like \"apple earnings\". The Functions tab lists everything.", { key: commandBarBadges[0] })
-                    : t("Not sure of a code? Type what you want in plain words, like \"apple earnings\". The Functions tab lists everything.")}
+                    ? tf("Not sure of a code? Click the search bar at the top, or press {key}, and type what you want in plain words, like \"apple earnings\". The Functions tab lists everything.", { key: commandBarBadges[0] })
+                    : t("Not sure of a code? Click the search bar at the top and type what you want in plain words, like \"apple earnings\". The Functions tab lists everything.")}
                 </Text>
               </Box>
             </Box>

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

@@ -7,7 +7,9 @@ import type {
   BeneficialOwnersPayload,
 } from "../../../api-client/beneficial-owners";
 import { ApiRequestError, isAccessDenied } from "../../../api-client/errors";
+import { listingAbroad, type IssuerListingParams } from "../../../api-client/paths";
 import { createPluginCache } from "../../../data/plugin-cache";
+import { secListingKey } from "../../../utils/sec";
 import { finiteOrNull, recordOrNull } from "../../../utils/guards";
 import { cachedCloudResource, loadCloudResource, type CloudResource } from "../shared/cloud-resource";
 import { CLOUD_SESSION_REQUIRED } from "../shared/research-cloud-session";
@@ -28,6 +30,8 @@ export interface BeneficialOwnersRequest {
   form?: BeneficialOwnersForm;
   /** Every report instead of the latest per filer. */
   history?: boolean;
+  /** The listing's venue and company, for a listing outside the US. */
+  listing?: IssuerListingParams;
 }
 
 type BeneficialOwnersClient = Pick<typeof apiClient, "getCloudSecBeneficialOwners">;
@@ -142,7 +146,7 @@ function describeFailure(error: unknown, ticker: string): unknown {
  */
 export async function fetchBeneficialOwners(
   ticker: string,
-  { form = "all", history = false }: BeneficialOwnersRequest = {},
+  { form = "all", history = false, listing }: BeneficialOwnersRequest = {},
   { client = apiClient, signal }: { client?: BeneficialOwnersClient; signal?: AbortSignal } = {},
 ): Promise<BeneficialOwnersPayload> {
   const symbol = ticker.trim().toUpperCase();
@@ -154,6 +158,8 @@ export async function fetchBeneficialOwners(
     for (;;) {
       const page = normalizeBeneficialOwnersPayload(await client.getCloudSecBeneficialOwners({
         ticker: symbol,
+        exchange: listing?.exchange,
+        name: listing?.name,
         form,
         history,
         limit: PAGE_SIZE,
@@ -178,10 +184,20 @@ export async function fetchBeneficialOwners(
       offset = nextOffset;
     }
   } catch (error) {
+    // A listing abroad whose company the SEC does not know has no reports.
+    const abroad = listingAbroad(symbol, listing?.exchange);
+    if (abroad && error instanceof ApiRequestError && error.status === 404) return noReports(symbol, history);
     throw describeFailure(error, symbol);
   }
 }
 
+function noReports(ticker: string, history: boolean): BeneficialOwnersPayload {
+  return {
+    ticker, cik: "", companyName: "", asOf: null, owners: [], ...(history ? { filings: [] } : {}),
+    hasMore: false, nextOffset: null, coverage: null,
+  };
+}
+
 /** Pages can overlap when a report lands between two requests. */
 function dedupe(rows: BeneficialOwnerFiling[]): BeneficialOwnerFiling[] {
   const seen = new Set<string>();
@@ -193,17 +209,23 @@ function dedupe(rows: BeneficialOwnerFiling[]): BeneficialOwnerFiling[] {
   });
 }
 
-const cacheKey = (ticker: string) => ticker.trim().toUpperCase();
+// SAN in Paris is not SAN in New York: a listing abroad is cached under its venue.
+const cacheKey = (ticker: string, listing?: IssuerListingParams) => secListingKey(ticker, listing?.exchange);
 
-export function cachedBeneficialOwners(ticker: string): CloudResource<BeneficialOwnersPayload> | null {
-  return cachedCloudResource(beneficialOwnersCache, cacheKey(ticker));
+export function cachedBeneficialOwners(ticker: string, listing?: IssuerListingParams): CloudResource<BeneficialOwnersPayload> | null {
+  return cachedCloudResource(beneficialOwnersCache, cacheKey(ticker, listing));
 }
 
 /** The pane's list: the latest report per filer, both kinds, cached on disk. */
-export async function loadBeneficialOwners(ticker: string, force = false): Promise<CloudResource<BeneficialOwnersPayload>> {
+export async function loadBeneficialOwners(
+  ticker: string,
+  force = false,
+  listing?: IssuerListingParams,
+): Promise<CloudResource<BeneficialOwnersPayload>> {
+  const key = cacheKey(ticker, listing);
   try {
-    return await loadCloudResource(beneficialOwnersCache, cacheKey(ticker), () => fetchBeneficialOwners(ticker), { force });
+    return await loadCloudResource(beneficialOwnersCache, key, () => fetchBeneficialOwners(ticker, { listing }), { force });
   } catch (error) {
-    throw describeFailure(error, cacheKey(ticker));
+    throw describeFailure(error, key);
   }
 }

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

@@ -30,9 +30,22 @@ export interface ThirteenFAction {
   value: number;
 }
 
+/** The stake a report's shares make of today's count, where the report's own base differs. */
+export interface StakeToday {
+  /** Percent of today's shares outstanding. */
+  percent: number;
+  sharesOutstanding: number;
+}
+
 export interface BeneficialOwnerRow {
   id: string;
   filing: BeneficialOwnerFiling;
+  /** Who the row is: the reporting person whose stake it shows. */
+  holderName: string;
+  /** The other reporting persons on the same report: a group's members, a fund's adviser or principal. */
+  otherPersons: number;
+  /** The report's shares over today's count, when that count is no longer the report's base. */
+  today: StakeToday | null;
   /** `13G/A`: the kind, and `/A` for an amendment. */
   formLabel: string;
   /** Percent points against the filer's report before this one. */
@@ -93,6 +106,71 @@ export function thirteenFAction(holder: HolderRecord | undefined): ThirteenFActi
   return null;
 }
 
+const ALL_CAPS = /^[^a-z]*[A-Z][^a-z]*$/;
+
+function sameEntity(left: string, right: string): boolean {
+  const key = (name: string) => name.toLowerCase().replace(/[^a-z0-9 ]+/g, " ")
+    .replace(/\b(the|inc|llc|ltd|lp|llp|corp|corporation|co|company|plc|n a|s a)\b/g, " ").replace(/\s+/g, " ").trim();
+  return key(left) === key(right);
+}
+
+/**
+ * The name a row goes by, one rule for every report: the reporting person
+ * whose stake the row shows (the highest percent, then shares, the filer's
+ * own entry on a tie), not the EDGAR filer, which only some reports name.
+ * When that person is the filer and the cover spells it in capitals, the
+ * filer's own spelling is kept (`SRS Investment Management, LLC`).
+ */
+export function beneficialHolderName(
+  filing: Pick<BeneficialOwnerFiling, "filerName" | "filerCik" | "reportingPersons">,
+): string {
+  let best: BeneficialOwnerFiling["reportingPersons"][number] | null = null;
+  for (const person of filing.reportingPersons) {
+    if (!person.name.trim()) continue;
+    if (!best) { best = person; continue; }
+    const percent = person.percentOfClass ?? -1;
+    const bestPercent = best.percentOfClass ?? -1;
+    if (percent !== bestPercent) { if (percent > bestPercent) best = person; continue; }
+    const shares = person.shares ?? -1;
+    const bestShares = best.shares ?? -1;
+    if (shares !== bestShares) { if (shares > bestShares) best = person; continue; }
+    if (filing.filerCik && person.cik === filing.filerCik && best.cik !== filing.filerCik) best = person;
+  }
+  const name = best?.name.trim();
+  if (!name) return filing.filerName;
+  const isFiler = (!!filing.filerCik && best?.cik === filing.filerCik) || sameEntity(name, filing.filerName);
+  return isFiler && ALL_CAPS.test(name) && !ALL_CAPS.test(filing.filerName) ? filing.filerName : name;
+}
+
+/** Today's count against the report's own base outside this range is another class or unit, not the same shares. */
+const BASE_RANGE = [2 / 3, 3 / 2] as const;
+
+/**
+ * The report's shares as a percent of today's shares outstanding, when the
+ * count the filer divided by (shares over the filed percent) is no longer
+ * today's. A filed percent is rounded, so a gap within that rounding (0.1
+ * point, or 2% of the stake) is not a new count. Null for an exit, a report
+ * without both figures, or a count that cannot be this class's.
+ */
+export function stakeToday(
+  filing: Pick<BeneficialOwnerFiling, "shares" | "percentOfClass">,
+  sharesOutstanding: number | null | undefined,
+): StakeToday | null {
+  const { shares, percentOfClass: filed } = filing;
+  if (sharesOutstanding == null || !(sharesOutstanding > 0) || shares == null || !(shares > 0) || filed == null || !(filed > 0)) return null;
+  const base = shares / (filed / 100);
+  const ratio = base / sharesOutstanding;
+  if (ratio < BASE_RANGE[0] || ratio > BASE_RANGE[1]) return null;
+  const percent = (shares / sharesOutstanding) * 100;
+  if (Math.abs(percent - filed) < Math.max(0.1, filed * 0.02)) return null;
+  return { percent, sharesOutstanding };
+}
+
+/** `about 49.4% on 35.26M sh today`. */
+export function formatStakeToday(today: StakeToday): string {
+  return `about ${formatClassPercent(today.percent)} on ${formatCompact(today.sharesOutstanding)} sh today`;
+}
+
 function beneficialFormLabel(filing: Pick<BeneficialOwnerFiling, "kind" | "amendment">): string {
   return `${filing.kind}${filing.amendment ? "/A" : ""}`;
 }
@@ -110,10 +188,14 @@ export function buildBeneficialRows(
   filings: readonly BeneficialOwnerFiling[],
   holders: readonly JoinableHolder[] = [],
   fundMatches: ReadonlyMap<string, Pick<Holder13FMatch, "cik">> = new Map(),
+  sharesOutstanding?: number | null,
 ): BeneficialOwnerRow[] {
   return filings.map((filing) => ({
     id: `${filing.accessionNumber}:${filing.filerCik ?? filing.filerName}`,
     filing,
+    holderName: beneficialHolderName(filing),
+    otherPersons: Math.max(0, filing.reportingPersons.length - 1),
+    today: stakeToday(filing, sharesOutstanding),
     formLabel: beneficialFormLabel(filing),
     changePoints: pointChange(filing),
     thirteenF: thirteenFAction(matchFilerToHolder(filing, holders, fundMatches)),
@@ -123,7 +205,7 @@ export function buildBeneficialRows(
 
 function sortValue(row: BeneficialOwnerRow, columnId: BeneficialColumnId): string | number | null {
   switch (columnId) {
-    case "filer": return row.filing.filerName;
+    case "filer": return row.holderName;
     case "form": return row.formLabel;
     case "percentOfClass": return row.filing.percentOfClass;
     case "change": return row.changePoints;
@@ -148,7 +230,7 @@ export function sortBeneficialRows(rows: readonly BeneficialOwnerRow[], preferen
   return [...rows].sort((left, right) => stakeGroup(left) - stakeGroup(right)
     || compareSortValues(sortValue(left, preference.columnId), sortValue(right, preference.columnId), preference.direction)
     || right.filing.filingDate.localeCompare(left.filing.filingDate)
-    || left.filing.filerName.localeCompare(right.filing.filerName));
+    || left.holderName.localeCompare(right.holderName));
 }
 
 // Widths as the table draws them: never narrower than the header and its sort marker.
@@ -249,14 +331,19 @@ export function formatOwnerShares(value: number | null): string {
 export function beneficialReportRow(row: BeneficialOwnerRow) {
   const { filing } = row;
   return {
-    filer: filing.filerName,
+    filer: row.holderName,
+    /** The other reporting persons on the report, which text marks `+N` after the name. */
+    otherPersons: row.otherPersons,
     filerCik: filing.filerCik,
     form: row.formLabel,
     formType: filing.form,
     kind: filing.kind,
     amendment: filing.amendment,
     amendmentNo: filing.amendmentNo,
+    /** As filed: the filer's shares over the share count it used. */
     percentOfClass: filing.percentOfClass,
+    /** The same shares over today's shares outstanding, only when that count is no longer the report's base. */
+    percentToday: row.today ? Number(row.today.percent.toFixed(2)) : null,
     previousPercent: filing.previousPercent ?? null,
     changePoints: row.changePoints,
     shares: filing.shares,

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

@@ -5,6 +5,7 @@ import {
   buildBeneficialRows,
   DEFAULT_BENEFICIAL_SORT,
   formatClassPercent,
+  formatFilerName,
   formatOwnerShares,
   formatPointChange,
   stakeMarker,
@@ -13,6 +14,7 @@ import {
   type BeneficialSortPreference,
 } from "./beneficial-model";
 import { buildRows } from "./table-model";
+import { formatCompact } from "../../../utils/format";
 
 /** What `holders --form` lists: the 13F table, or the 13D/13G beneficial owners. */
 export type HolderForm = "13f" | "13d" | "13g" | "all";
@@ -27,9 +29,23 @@ export function beneficialRouteForm(form: Exclude<HolderForm, "13f">): Beneficia
   return form === "13d" ? "13D" : form === "13g" ? "13G" : "all";
 }
 
-/** Text columns for the 13D/13G rows; CSV and JSON keep the raw values. */
+const num = (value: unknown) => (typeof value === "number" && Number.isFinite(value) ? value : null);
+
+/**
+ * Columns for the 13D/13G rows. `textFormat` is what text prints (`holders
+ * --form` and `fn HDS --form`); `fn HDS --csv` reads `format`, and `holders
+ * --csv` and JSON keep the raw values. `% Class` is as filed; `% Today` is
+ * the same shares over today's count, only where that count is no longer the
+ * report's base.
+ */
 export const BENEFICIAL_REPORT_COLUMNS = [
-  { key: "filer", header: "Filer", maxWidth: 32 },
+  {
+    key: "filer",
+    header: "Filer",
+    maxWidth: 32,
+    // `+N` counts the report's other reporting persons; a long name gives way before it does.
+    textFormat: (value: unknown, row: Record<string, unknown>) => formatFilerName(String(value ?? ""), num(row.otherPersons) ?? 0, 32),
+  },
   { key: "form", header: "Form" },
   {
     key: "percentOfClass",
@@ -41,6 +57,13 @@ export const BENEFICIAL_REPORT_COLUMNS = [
       return marker ? `${formatClassPercent(value)} ${marker}` : formatClassPercent(value);
     },
   },
+  {
+    key: "percentToday",
+    header: "% Today",
+    align: "right" as const,
+    format: (value: unknown) => num(value) == null ? "" : `${num(value)!.toFixed(2)}%`,
+    textFormat: (value: unknown) => num(value) == null ? "" : `about ${formatClassPercent(num(value)!)}`,
+  },
   {
     key: "changePoints",
     header: "Chg",
@@ -58,6 +81,28 @@ export const BENEFICIAL_REPORT_COLUMNS = [
   { key: "thirteenF", header: "13F", align: "right" as const, format: (value: unknown) => typeof value === "string" ? value : "-" },
 ];
 
+/** The 13D/13G columns these rows fill: `% Today` only when a report's base is no longer today's count. */
+export function beneficialReportColumns(rows: readonly BeneficialReportRow[]): typeof BENEFICIAL_REPORT_COLUMNS {
+  const today = rows.some((row) => row.percentToday != null);
+  return BENEFICIAL_REPORT_COLUMNS.filter((column) => today || column.key !== "percentToday");
+}
+
+/**
+ * The legend under the 13D/13G table, one line: the percent is as filed, what
+ * `% Today` divides by, and what `+N` after a name counts.
+ */
+export function beneficialReportLegend(
+  rows: readonly BeneficialReportRow[],
+  sharesOutstanding: number | null | undefined,
+): string | null {
+  if (rows.length === 0) return null;
+  const today = sharesOutstanding != null && rows.some((row) => row.percentToday != null)
+    ? `; % Today is the same shares over ${formatCompact(sharesOutstanding)} shares outstanding today`
+    : "";
+  const others = rows.some((row) => row.otherPersons > 0) ? " +N after a name: other reporting persons on the same report." : "";
+  return `% Class is as filed${today}.${others}`;
+}
+
 const filings = (count: number) => `${count} ${count === 1 ? "filing" : "filings"}`;
 
 /**
@@ -114,13 +159,20 @@ export function buildBeneficialReportRows(
     history = false,
     holders = null,
     sort = DEFAULT_BENEFICIAL_SORT,
-  }: { history?: boolean; holders?: HolderData | null; sort?: BeneficialSortPreference } = {},
+    sharesOutstanding = null,
+  }: {
+    history?: boolean;
+    holders?: HolderData | null;
+    sort?: BeneficialSortPreference;
+    /** Today's shares outstanding in the class's own unit, for `percentToday`. */
+    sharesOutstanding?: number | null;
+  } = {},
 ): 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 buildBeneficialRows(filings, holderRows, undefined, sharesOutstanding).map(beneficialReportRow);
   }
-  return sortBeneficialRows(buildBeneficialRows(payload.owners, holderRows), sort).map(beneficialReportRow);
+  return sortBeneficialRows(buildBeneficialRows(payload.owners, holderRows, undefined, sharesOutstanding), sort).map(beneficialReportRow);
 }