gloomberb 0.16.1 → 0.16.3

package/src/plugins/builtin/supply-chain/pane.tsx

@@ -27,27 +27,46 @@ import { SupplyFlow } from "./flow";
 import { SupplyGraphPane } from "./graph-pane";
 import {
   cellText, counterpartyKind, counterpartyKindLabel, counterpartyLabel, counterpartyName, disclosedValue, nativeValue, percentage, ROLE_COLORS, roleLabel,
-  shareParts, sortRows, type SupplySort,
+  shareParts, sortRows, supplyRoleCounts, type SupplySort,
 } from "./model";
 import { RowEvidence } from "./row-evidence";
 import { evidenceDate, evidenceLabel, isUnconfirmed, matchesSupplyOptions, supplyOptions, TIER_OPTIONS } from "./trust";
 
 type Item = { kind: "edge"; row: SupplyRow } | { kind: "locked"; id: string };
 const itemId = (item: Item) => item.kind === "edge" ? item.row.id : item.id;
-const ROLE_ORDER: SupplyRole[] = ["customer", "supplier", "partner", "competitor", "investee"];
 const ROLE_PLURALS: Record<SupplyRole, string> = { customer: "Customers", supplier: "Suppliers", partner: "Partners", competitor: "Competitors", investee: "Investees" };
-const BAR_CELLS = 8;
+/** A share figure is at most five cells (`99.9%`, `100%`), right-aligned so the bars line up. */
+const SHARE_FIGURE_CELLS = 5;
+/** Bar, gap and figure: below this a share cell shows the figure alone. */
+const SHARE_BAR_MIN_CELLS = 3 + 1 + SHARE_FIGURE_CELLS;
 
 /**
- * A narrow pane folds the ticker into the name and leaves the filing to the
- * evidence view before anything scrolls sideways. Value shows only when some
- * row discloses a value, retaining its original currency and units.
+ * Cells of a share column's bar: as long as the column allows after the figure
+ * and the longest basis that fits, between 3 and 8 cells, and the same on every
+ * row so the bars and figures line up. Zero leaves the figure alone.
  */
-function tableColumns(width: number, desktop: boolean, locked: boolean, valueWidth: number | null): DataTableColumn[] {
+function shareBarCells(width: number, bases: readonly number[]): number {
+  if (width < SHARE_BAR_MIN_CELLS) return 0;
+  // Room for the longest basis that can show at all; a longer one gives way, not every bar.
+  const basis = longestBasis(bases, width);
+  return Math.min(width >= 36 ? 8 : 5, Math.max(3, width - SHARE_FIGURE_CELLS - 2 - basis));
+}
+const longestBasis = (bases: readonly number[], width: number) => Math.max(0, ...bases.filter((cells) => SHARE_BAR_MIN_CELLS + 1 + cells <= width));
+
+/**
+ * Columns that fit the pane, giving up the least first: the share bar shortens
+ * to keep the whole basis, the name shortens to 18 cells, the ticker folds into
+ * the name and the period is left to the evidence view; then the share drops
+ * its basis and its bar, and the name shortens further. Only a pane narrower
+ * than that scrolls sideways, so the pane edge never cuts a share in half.
+ * Value shows only when some row discloses a value, retaining its original
+ * currency and units.
+ */
+function tableColumns(width: number, desktop: boolean, locked: boolean, valueWidth: number | null, bases: readonly number[]): DataTableColumn[] {
   const wide = width >= 150, medium = width >= 110;
   const name: DataTableColumn = { id: "name", label: "Counterparty", width: Math.max(locked && !desktop ? 34 : 0, wide ? 30 : medium ? 26 : 20), flexGrow: 1, align: "left" };
   const share: DataTableColumn = { id: "pct", label: "Share", width: wide ? 34 : medium ? 30 : 26, align: "left" };
-  const columns: DataTableColumn[] = [
+  let columns: DataTableColumn[] = [
     name,
     { id: "evidence", label: "Evidence", width: 12, align: "left" },
     ...(medium ? [{ id: "ticker", label: "Ticker", width: 8, align: "left" as const }] : []),
@@ -61,40 +80,57 @@ function tableColumns(width: number, desktop: boolean, locked: boolean, valueWid
       { id: "corroboration", label: "Origins", width: 8, align: "right" as const },
     ] : []),
   ];
-  // Preserve trust labels, native units and final columns before expanding the share and name.
+  const preferred = { share: share.width, name: name.width };
   // The table ignores its last trailing gutter when deciding whether it fits.
-  if (valueWidth !== null || width >= 80) {
-    share.width = Math.max(valueWidth !== null ? 10 : 14, share.width - Math.max(0, getTableWidth(columns) - width - 1));
-    name.width = Math.max(18, name.width - Math.max(0, getTableWidth(columns) - width - 1));
+  const overflow = () => getTableWidth(columns) - width - 1;
+  // Native units keep their column before the share keeps its bar or basis.
+  const shareFloor = valueWidth !== null ? SHARE_BAR_MIN_CELLS + 1 : SHARE_BAR_MIN_CELLS + 1 + longestBasis(bases, preferred.share);
+  const fit = (shareMin: number, nameMin = 18) => {
+    share.width = preferred.share; name.width = preferred.name;
+    share.width = Math.max(shareMin, share.width - Math.max(0, overflow()));
+    name.width = Math.max(nameMin, name.width - Math.max(0, overflow()));
+  };
+  fit(shareFloor);
+  for (const id of ["ticker", "fy"]) {
+    if (overflow() <= 0) break;
+    if (!columns.some((column) => column.id === id)) continue;
+    columns = columns.filter((column) => column.id !== id);
+    fit(shareFloor);
   }
+  // The narrowest panes keep the figure alone, then a shorter name, before anything scrolls.
+  if (overflow() > 0) fit(SHARE_BAR_MIN_CELLS);
+  if (overflow() > 0) fit(SHARE_FIGURE_CELLS + 2, 12);
   return columns;
 }
 
-/** Company, then disclosed counterparties per role: the strip that heads both tabs. */
-function supplyFigures(data: SupplyChainPayload, views: readonly ("says" | "names")[], options: Required<SupplyOptions>, flow: boolean): StatItem[] {
-  const shown = views.flatMap((view) => data[view]).filter((row) => matchesSupplyOptions(row, options) && !isUnconfirmed(row));
+/**
+ * Company, then the counterparties per role on this tab, with how many
+ * disclosures a free preview locks: the strip that heads the table and the flow.
+ */
+function supplyFigures(data: SupplyChainPayload, views: readonly ("says" | "names")[], options: Required<SupplyOptions>): StatItem[] {
   return [
     ...(data.entity ? [{ id: "company", label: "Company", value: data.entity.name }] : []),
-    ...ROLE_ORDER.flatMap((role) => {
-      const visible = shown.filter((row) => row.role === role).length;
-      const count = data.truncated && !flow && !options.includeLeads ? views.reduce((total, view) => total + data.counts[view][role], 0) : visible;
-      return count ? [{ id: role, label: ROLE_PLURALS[role], value: String(count), color: ROLE_COLORS[role],
-        detail: visible < count ? `${visible} shown` : undefined }] : [];
-    }),
+    ...supplyRoleCounts(data, views, options).map(({ role, counterparties, locked }) => ({ id: role, label: ROLE_PLURALS[role], value: String(counterparties),
+      color: ROLE_COLORS[role], detail: locked ? `+${locked} locked` : undefined })),
   ];
 }
 
-/** The share as a bar on a 0 to 100% scale, the figure, and what it is a share of. */
-function ShareCell({ row, focusId, width, selected }: { row: SupplyRow; focusId?: string; width: number; selected: boolean }) {
+/**
+ * The share as a bar on a 0 to 100% scale, the figure, and what it is a share
+ * of. The basis shows whole or not at all: a column too narrow for it keeps
+ * the bar and figure, and the evidence view says the rest.
+ */
+function ShareCell({ row, focusId, width, bases, selected }: { row: SupplyRow; focusId?: string; width: number; bases: readonly number[]; selected: boolean }) {
   const colors = useThemeColors();
   const share = shareParts(row, focusId);
   if (!share) return <Text fg={colors.textMuted}>{""}</Text>;
-  if (width < 14) return <Text fg={selected ? colors.selectedText : colors.textBright} attributes={TextAttributes.BOLD}>{share.value}</Text>;
-  const barWidth = width >= 36 ? BAR_CELLS : Math.min(5, Math.max(3, width - 11));
+  const bar = shareBarCells(width, bases);
+  if (!bar) return <Text fg={selected ? colors.selectedText : colors.textBright} attributes={TextAttributes.BOLD}>{share.value}</Text>;
+  const basis = bar + SHARE_FIGURE_CELLS + 2 + displayWidth(share.basis) <= width;
   return <Box flexDirection="row" width={width} height={1} gap={1} overflow="hidden">
-    <RatioBar ratio={row.pctOfRevenue! / 100} width={barWidth} color={ROLE_COLORS[row.role]} track />
-    <Text fg={selected ? colors.selectedText : colors.textBright} attributes={TextAttributes.BOLD}>{share.value.padStart(5)}</Text>
-    <Text fg={selected ? colors.selectedText : colors.textDim}>{truncateToDisplayWidth(share.basis, Math.max(4, width - barWidth - 7))}</Text>
+    <RatioBar ratio={row.pctOfRevenue! / 100} width={bar} color={ROLE_COLORS[row.role]} track />
+    <Text fg={selected ? colors.selectedText : colors.textBright} attributes={TextAttributes.BOLD}>{share.value.padStart(SHARE_FIGURE_CELLS)}</Text>
+    {basis ? <Text fg={selected ? colors.selectedText : colors.textDim}>{share.basis}</Text> : null}
   </Box>;
 }
 
@@ -180,7 +216,8 @@ function SupplyView({ symbol, width, height, focused }: Pick<PaneProps, "width"
   const focusId = data?.entity?.id;
   const values = rows.filter((row) => nativeValue(row) !== null || row.usd !== null);
   const valueWidth = values.length ? Math.min(28, Math.max(...values.map((row) => displayWidth(disclosedValue(row).replace(/ (disclosed|derived)$/, ""))))) : null;
-  const columns = tableColumns(width, desktop, locked > 0, valueWidth);
+  const bases = rows.flatMap((row) => { const share = shareParts(row, focusId); return share ? [displayWidth(share.basis)] : []; });
+  const columns = tableColumns(width, desktop, locked > 0, valueWidth, bases);
   const renderCell = (entry: SectionedRow<Item>, column: DataTableColumn, _index: number, state: { selected: boolean }): DataTableCell => {
     if (!isSectionedItemRow(entry)) return { text: "" };
     const item = entry.item;
@@ -222,7 +259,7 @@ function SupplyView({ symbol, width, height, focused }: Pick<PaneProps, "width"
         <Text fg={ink ?? ROLE_COLORS[row.role]}>{` ${roleLabel(row.role)}`}</Text>
       </Box> };
       case "pct": return { text: percentage(row) === "--" ? "" : `${shareParts(row, focusId)?.value ?? ""} ${shareParts(row, focusId)?.basis ?? ""}`.trim(), value: row.pctOfRevenue,
-        content: <ShareCell row={row} focusId={focusId} width={column.width} selected={state.selected} /> };
+        content: <ShareCell row={row} focusId={focusId} width={column.width} bases={bases} selected={state.selected} /> };
       case "usd": return nativeValue(row) === null && row.usd === null ? { text: "", value: null }
         : { text: disclosedValue(row).replace(/ (disclosed|derived)$/, ""), value: row.nativeAmount != null ? row.nativeAmount * (row.nativeScale ?? 1) : row.usd, color: colors.text };
       case "fy": return { text: row.period, color: colors.textDim };
@@ -233,7 +270,7 @@ function SupplyView({ symbol, width, height, focused }: Pick<PaneProps, "width"
   if (graphTab) return <Box width={width} height={height} flexDirection="column">{strip}<SupplyGraphPane symbol={symbol} tab={savedTab as "graph" | "path"} width={width} height={Math.max(3, height - tabRows)} focused={focused} /></Box>;
   if (!data && isCloudSessionRequired(resource.error)) return <SignInWall placement="supply-chain-signin" action="view supply chain disclosures" needsVerification={session.needsVerification} />;
   const bodyHeight = Math.max(3, height - tabRows);
-  const figures = data ? supplyFigures(data, tab === "flow" ? ["says", "names"] : [view], options, tab === "flow") : [];
+  const figures = data ? supplyFigures(data, tab === "flow" ? ["says", "names"] : [view], options) : [];
   const tierFilter = { id: "tiers", label: "Evidence", kind: "multi" as const, emptyLabel: "Primary", values: options.tiers, options: TIER_OPTIONS, onChange: (value: string[]) => { setTiers(supplyOptions(value).tiers); setSelected(null); setOpen(null); } };
   const header = <Box flexDirection="column" flexShrink={0}>
     <QueryBar width={width} filters={[{ id: "direction", label: "Direction", inline: true, value: view,
@@ -263,7 +300,9 @@ function SupplyView({ symbol, width, height, focused }: Pick<PaneProps, "width"
         </Box> : <DataTableView<SectionedRow<Item>> columns={columns}
           items={items} focused={focused && !openRow} rootWidth={width} rootHeight={bodyHeight} rootBefore={header}
           selection={{ kind: "id", selectedId: selected?.id ?? null, getId: (entry) => entry.key, onChange: (id) => setSelected(id) }} getItemKey={(entry) => entry.key}
-          isNavigable={isSectionedItemRow} renderSectionHeader={renderSectionedRowHeader}
+          isNavigable={isSectionedItemRow}
+          // The placeholders stand for every locked disclosure; the header counts those, as the figures do.
+          renderSectionHeader={(entry) => entry.kind === "section" && entry.label === "Pro" ? { text: `Pro (${locked})` } : renderSectionedRowHeader(entry)}
           onActivate={(entry) => { if (isSectionedItemRow(entry)) entry.item.kind === "edge" ? navigate(entry.item.row) : openUpgrade(); }}
           renderCell={renderCell} sortColumnId={sort.column} sortDirection={sort.direction}
           onHeaderClick={(column) => setSort((old) => ({ column, direction: old.column === column && old.direction === "desc" ? "asc" : "desc" }))}

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

@@ -6,6 +6,9 @@ import { aggregateText, DEFAULT_SORT, matchTheme, memberPrice, percent, PERIOD_L
 const periods: HeadlessPaneColumn[] = THEME_PERIODS.map((key) => ({ key, header: PERIOD_LABELS[key], align: "right", format: (value) => percent(value as number | null) }));
 export const themesHeadless: HeadlessPaneDefinition<"rows"> = {
   shape: "rows",
+  // The pane's stored snapshot: 15-minute delayed prices, refreshed every 15 minutes. As in the pane,
+  // the payload's stale flags are historical; a snapshot over 30 minutes old is what reads stale.
+  freshness: { status: "delayed", delayMinutes: 15, maxAgeMinutes: 30, ignoreStaleFlags: true },
   argument: { kind: "free-text", optional: true, placeholder: "theme", description: "Theme name or keyword, such as nuclear; omit for all themes." },
   options: [],
   discovery: { aliases: ["THEM"], dataRequirements: ["Gloom Cloud stored equity snapshot"],

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

@@ -8,6 +8,7 @@ import { priceColor } from "../../../theme/colors";
 import { useThemeColors } from "../../../theme/theme-context";
 import { Box, Text } from "../../../ui";
 import { nextHeaderSort } from "../../../utils/sort-values";
+import { useMembersMenu } from "../shared/members-menu";
 import { cachedMembers, cachedThemes, loadMembers, loadThemes } from "./client";
 import { aggregateText, coverageWidth, DEFAULT_SORT, matchTheme, memberColumns, memberPrice, percent, sortMembers, sortThemes, themeColumns, type ThemeSort } from "./model";
 
@@ -37,6 +38,8 @@ function Members({ id, width, height, focused }: { id: string; width: number; he
   useAutoRefresh(resource.updatedAt, resource.load);
   usePaneRefreshKey(() => void resource.reload(), { focused });
   useSnapshotFooter("themes:members", resource, focused);
+  const memberList = useMemo(() => data ? { title: data.theme.name, watchlistName: data.theme.name, members: rows } : null, [data, rows]);
+  useMembersMenu("themes:members-menu", memberList);
   const renderCell = useCallback((row: ThemeMember, column: DataTableColumn): DataTableCell => {
     if (column.id === "symbol") return { text: row.symbol, color: colors.textBright };
     if (column.id === "name") return { text: row.name ?? "--", color: colors.text };

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

@@ -7,7 +7,16 @@ import type {
 import { formatShortDate } from "../../../utils/datetime-format";
 import { normalizeCik } from "./api";
 import { buildFundOverlap, overlapPeriod } from "./overlap";
-import { appendTickerHoldings, loadCrowding, loadTickerHoldings, type TickerHoldings } from "./signals";
+import { appendTickerHoldings, loadCrowding, loadTickerHoldings, type CrowdingRow, type TickerHoldings } from "./signals";
+import {
+  AS_FILED_VALUE,
+  compareCrowding,
+  crowdingForTicker,
+  cutText,
+  periodText,
+  summarizeTickerHoldings,
+  THIRTEENF_MAX_LIMIT,
+} from "./report-notes";
 import {
   loadBrowserRows,
   loadFundDetail,
@@ -44,6 +53,7 @@ import type {
   ThirteenFBrowserTab,
 } from "./types";
 import { finiteOrNull } from "../../../utils/guards";
+import { SEC_FILINGS } from "../shared/report-freshness";
 
 const money = (value: unknown) => formatMoneyCompact(finiteOrNull(value));
 const weight = (value: unknown) => formatWeightMaybe(finiteOrNull(value));
@@ -65,7 +75,7 @@ const BROWSER_COLUMNS: HeadlessPaneColumn[] = [
   },
   {
     key: "tableValueTotal",
-    header: "Value",
+    header: "Value (USD)",
     align: "right",
     format: (value) => formatMoneyCompact(value == null ? null : Number(value)),
   },
@@ -83,13 +93,13 @@ const HOLDING_COLUMNS: HeadlessPaneColumn[] = [
   { key: "issuer", header: "Issuer" },
   {
     key: "value",
-    header: "Value",
+    header: "Value (USD)",
     align: "right",
     format: (value) => formatMoneyCompact(value == null ? null : Number(value)),
   },
   {
     key: "estimatedPnl",
-    header: "Est P&L",
+    header: "Est P&L (USD)",
     align: "right",
     format: (value) => formatMoneyCompact(value == null ? null : Number(value)),
   },
@@ -124,7 +134,7 @@ const FILING_COLUMNS: HeadlessPaneColumn[] = [
   },
   {
     key: "tableValueTotal",
-    header: "Value",
+    header: "Value (USD)",
     align: "right",
     format: (value) => formatMoneyCompact(value == null ? null : Number(value)),
   },
@@ -177,6 +187,30 @@ const defaultDependencies: ThirteenFHeadlessDependencies = {
   loadDetail: (cik, name, _args, ctx) => loadFundDetail(cik, name, ctx.signal),
 };
 
+const VIEW_TITLES: Record<string, string> = {
+  overlap: "13F Overlap",
+  crowding: "13F Crowding",
+  "ticker-holdings": "13F Holders",
+  byTicker: "13F Holders",
+  "by-ticker": "13F Holders",
+  holdings: "13F Holdings",
+  filings: "13F Filings",
+  performance: "13F Performance",
+  funds: "13F Funds",
+  latest: "13F Latest Filings",
+};
+
+/** The view a query resolved to and what it is about, never the bare `auto` it was asked as. */
+function thirteenFTitle(args: HeadlessPaneLoadArgs, metadata: Record<string, unknown> | undefined): string {
+  const query = typeof args.argument === "string" ? args.argument.trim() : "";
+  const view = String(metadata?.view ?? args.options.view);
+  const text = (value: unknown) => (typeof value === "string" && value ? value : "");
+  const subject = view === "overlap" && metadata?.firstFund && metadata.secondFund
+    ? `${text(metadata.firstFund)} vs ${text(metadata.secondFund)}`
+    : text(metadata?.ticker) || text(metadata?.fund) || (view === "latest" || view === "performance" ? "" : query);
+  return [VIEW_TITLES[view] ?? "13F Funds", subject].filter(Boolean).join(" | ");
+}
+
 function browserTab(view: HeadlessThirteenFView, query: string): ThirteenFBrowserTab {
   if (view === "performance" || view === "funds" || view === "latest") return view;
   if (view === "by-ticker") return "byTicker";
@@ -210,6 +244,7 @@ export function createThirteenFHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    freshness: { ...SEC_FILINGS, basis: "13F filings", observedKey: "filedAsOfDate" },
     argument: {
       kind: "free-text",
       placeholder: "fund, ticker, or CIK",
@@ -245,10 +280,10 @@ export function createThirteenFHeadless(
         type: "integer",
         defaultValue: 50,
         minimum: 1,
-        maximum: 200,
+        maximum: THIRTEENF_MAX_LIMIT,
       },
     ],
-    describe: (args) => `13F Funds | ${String(args.options.view)}`,
+    describe: (args, result) => thirteenFTitle(args, result?.metadata),
     async load(args, ctx) {
       const query = typeof args.argument === "string" ? args.argument.trim() : "";
       const requestedView = String(args.options.view) as HeadlessThirteenFView;
@@ -264,21 +299,23 @@ export function createThirteenFHeadless(
         const [first, second] = await Promise.all([dependencies.loadDetail(fund.cik, fund.name, args, ctx), dependencies.loadDetail(other.cik, other.name, args, ctx)]);
         const comparedPeriod = overlapPeriod(first, second);
         const rows = buildFundOverlap(first, second);
-        return { columns: [{ key: "ticker", header: "Ticker" }, { key: "type", header: "Type" }, { key: "issuer", header: "Issuer" }, { key: "weight", header: "First weight", align: "right", format: weight }, { key: "comparedWeight", header: "Second weight", align: "right", format: weight }], rows: rows.slice(0, limit).map(row => ({ ...row })), errors: [...(first.warnings ?? []), ...(second.warnings ?? []), ...(!comparedPeriod ? ["No reporting quarter is loaded for both funds."] : [])], metadata: { firstFund: first.name, secondFund: second.name, firstPeriod: first.latestForm?.periodOfReport ?? null, secondPeriod: second.latestForm?.periodOfReport ?? null, comparedPeriod, truncated: rows.length > limit, notices: comparedPeriod ? [`Quarter compared: ${comparedPeriod}`] : [] } };
+        const cut = cutText(rows.length, limit, "positions");
+        return { columns: [{ key: "ticker", header: "Ticker" }, { key: "type", header: "Type" }, { key: "issuer", header: "Issuer" }, { key: "weight", header: "First weight", align: "right", format: weight }, { key: "comparedWeight", header: "Second weight", align: "right", format: weight }], rows: rows.slice(0, limit).map(row => ({ ...row })), errors: [...(first.warnings ?? []), ...(second.warnings ?? []), ...(!comparedPeriod ? ["No reporting quarter is loaded for both funds."] : [])], metadata: { view, firstFund: first.name, secondFund: second.name, firstPeriod: first.latestForm?.periodOfReport ?? null, secondPeriod: second.latestForm?.periodOfReport ?? null, comparedPeriod, shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit, notices: [[comparedPeriod ? `Quarter compared: ${comparedPeriod}` : "", cut].filter(Boolean).join(" | ")].filter(Boolean) } };
       }
       if (view === "crowding") {
         const { rows: sourceRows, ...metadata } = await loadCrowding(ctx.signal);
         const rank = String(args.options.rank ?? "new");
-        const rows = [...sourceRows].sort((left, right) => {
-          if (rank === "new") return right.newCount - left.newCount;
-          if (rank === "exits") return right.exitCount - left.exitCount;
-          if (left.weightChange == null) return right.weightChange == null ? 0 : 1;
-          if (right.weightChange == null) return -1;
-          return (left.weightChange - right.weightChange) * (rank === "decreases" ? 1 : -1);
-        });
-        return { columns: [{ key: "ticker", header: "Ticker" }, { key: "issuer", header: "Issuer" }, { key: "type", header: "Type" }, { key: "holderCount", header: "Funds", align: "right" }, { key: "newCount", header: "New", align: "right" }, { key: "exitCount", header: "Exits", align: "right" }, { key: "weightChange", header: "Weight change", align: "right", format: weightPoints }, { key: "comparedFunds", header: "Compared", align: "right" }, { key: "totalValue", header: "Value", align: "right", format: money }], rows: rows.slice(0, limit).map(row => ({ ...row })),
-          // The pane states the fund sample beside the table; the text report needs it too.
-          metadata: { ...metadata, view, rank, truncated: rows.length > limit, notices: [`${metadata.period}: ${metadata.loadedFunds}/${metadata.sourceFunds} ranked funds`] }, errors: metadata.warnings };
+        const ranked = [...sourceRows].sort((left, right) => compareCrowding(rank, left, right));
+        // The pane states the fund sample beside the table; the text report needs it too.
+        const sample = `${metadata.period}: ${metadata.loadedFunds}/${metadata.sourceFunds} ranked funds`;
+        const ticker = query ? query.replace(/^\$/, "").toUpperCase() : null;
+        const focus = ticker ? crowdingForTicker(ranked, ticker, rank) : null;
+        const rows: Array<CrowdingRow & { rank?: number }> = focus ? focus.rows : ranked;
+        const columns: HeadlessPaneColumn[] = [{ key: "ticker", header: "Ticker" }, { key: "issuer", header: "Issuer" }, { key: "type", header: "Type" }, { key: "holderCount", header: "Funds", align: "right" }, { key: "newCount", header: "New", align: "right" }, { key: "exitCount", header: "Exits", align: "right" }, { key: "weightChange", header: "Weight change", align: "right", format: weightPoints }, { key: "comparedFunds", header: "Compared", align: "right" }, { key: "totalValue", header: "Value (USD)", align: "right", format: money }];
+        const cut = cutText(rows.length, limit, "securities");
+        return { columns: focus ? [{ key: "rank", header: "Rank", align: "right" }, ...columns] : columns, rows: rows.slice(0, limit).map(row => ({ ...row })),
+          metadata: { ...metadata, view, rank, ...(ticker ? { ticker, found: rows.length > 0, rankedSecurities: ranked.length } : {}), shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit, notices: [[sample, cut].filter(Boolean).join(" | "), ...(focus ? [focus.notice] : [])] },
+          freshness: { asOf: metadata.period }, errors: metadata.warnings };
       }
       let holdings: TickerHoldings | null = null;
       if (view === "ticker-holdings") {
@@ -297,16 +334,42 @@ export function createThirteenFHeadless(
       }
       if (holdings) {
         const { rows, ...metadata } = holdings;
-        return { columns: [{ key: "fund", header: "Fund" }, { key: "cik", header: "CIK" }, { key: "type", header: "Type" }, { key: "value", header: "Value", align: "right", format: money }, { key: "shares", header: "Shares", align: "right", format: shares }, { key: "weight", header: "13F weight", align: "right", format: weight }, { key: "action", header: "Action" }], rows: rows.slice(0, limit).map(row => ({ ...row })), metadata: { ...metadata, view, truncated: rows.length > limit || metadata.hasMore }, errors: metadata.warnings };
+        const offset = Number(args.options.offset ?? 0);
+        const summary = summarizeTickerHoldings({ ...metadata, offset, limit, loaded: rows });
+        return {
+          columns: [{ key: "fund", header: "Fund" }, { key: "cik", header: "CIK" }, { key: "type", header: "Type" }, { key: "value", header: "Value (USD)", align: "right", format: money }, { key: "shares", header: "Shares", align: "right", format: shares }, { key: "weight", header: "13F weight", align: "right", format: weight }, { key: "action", header: "Action" }],
+          rows: rows.slice(0, limit).map(row => ({ ...row })),
+          metadata: {
+            ...metadata,
+            view,
+            offset,
+            shown: Math.min(rows.length, limit),
+            shownFunds: summary.shownFunds,
+            total: summary.total,
+            truncated: summary.truncated,
+            hasMore: summary.truncated,
+            nextOffset: summary.nextOffset,
+            // The value of the rows shown, not of every fund a page loaded.
+            totalValue: summary.shownValue,
+            valueScope: "shown funds",
+            valueBasis: "as reported at period end",
+            notices: summary.notices,
+          },
+          freshness: { asOf: metadata.period },
+          errors: metadata.warnings,
+        };
       }
 
       if (view === "holdings" || view === "filings") {
         const fund = await resolveFund(query, args, ctx, dependencies);
         const detail = await dependencies.loadDetail(fund.cik, fund.name, args, ctx);
+        const latestPeriod = detail.latestForm?.periodOfReport ?? null;
         if (view === "filings") {
-          const rows = sortTimelineRows(buildTimelineRows(detail.forms), DEFAULT_TIMELINE_SORT)
+          const all = sortTimelineRows(buildTimelineRows(detail.forms), DEFAULT_TIMELINE_SORT);
+          const rows = all
             .slice(0, limit)
             .map((row) => ({ ...row }));
+          const cut = cutText(all.length, limit, "filings");
           return {
             columns: FILING_COLUMNS,
             rows,
@@ -315,14 +378,21 @@ export function createThirteenFHeadless(
               view,
               cik: detail.cik,
               fund: detail.name,
-              latestPeriod: detail.latestForm?.periodOfReport ?? null,
+              latestPeriod,
+              shown: rows.length,
+              total: all.length,
+              truncated: all.length > limit,
+              notices: [[`CIK ${detail.cik}`, cut].filter(Boolean).join(" | ")],
             },
           };
         }
-        const rows = sortHoldingRows(
+        const all = sortHoldingRows(
           buildFundHoldingRows(detail),
           DEFAULT_HOLDING_SORT,
-        )
+        );
+        const previousPeriod = detail.previousForm?.periodOfReport ?? null;
+        const cut = cutText(all.length, limit, "positions, exits included");
+        const rows = all
           .slice(0, limit)
           .map((row) => ({
             ...row,
@@ -333,12 +403,21 @@ export function createThirteenFHeadless(
           columns: HOLDING_COLUMNS,
           rows,
           ...(detail.warnings?.length ? { errors: detail.warnings } : {}),
+          // Positions as of the quarter they report; the rows carry no filing date.
+          ...(latestPeriod ? { freshness: { asOf: latestPeriod } } : {}),
           metadata: {
             view,
             cik: detail.cik,
             fund: detail.name,
-            latestPeriod: detail.latestForm?.periodOfReport ?? null,
-            previousPeriod: detail.previousForm?.periodOfReport ?? null,
+            latestPeriod,
+            previousPeriod,
+            shown: rows.length,
+            total: all.length,
+            truncated: all.length > limit,
+            notices: [
+              [`CIK ${detail.cik}`, periodText(latestPeriod, hasComparable13FQuarter(detail) ? previousPeriod : null), AS_FILED_VALUE].filter(Boolean).join(" | "),
+              ...(cut ? [`${cut[0]!.toUpperCase()}${cut.slice(1)}`] : []),
+            ],
             comparisonAvailable: hasComparable13FQuarter(detail),
             currentFilings: detail.latestReport?.filings.map((form) => form.accessionNumber) ?? [],
             previousFilings: detail.previousReport?.filings.map((form) => form.accessionNumber) ?? [],
@@ -352,6 +431,7 @@ export function createThirteenFHeadless(
 
       const tab = browserTab(view === "ticker-holdings" ? requestedView : view, query);
       const result = await dependencies.loadBrowser(tab, query, limit, args, ctx);
+      const more = result.hasMore || result.rows.length > limit;
       return {
         columns: result.rows[0]?.priorReturns?.length ? [...BROWSER_COLUMNS.filter(column => !["filedAsOfDate", "tableEntryTotal"].includes(column.key)), ...result.rows[0].priorReturns.map((point, index) => ({ key: `return${index + 1}`, header: point.quarter, align: "right" as const, format: (value: unknown) => formatRawPercentMaybe(typeof value === "number" ? value : null) }))]
           : tab === "performance" ? BROWSER_COLUMNS : BROWSER_COLUMNS.filter(column => column.key !== "estQuarterReturn"),
@@ -365,6 +445,11 @@ export function createThirteenFHeadless(
           period: result.period ?? null,
           quarter: result.quarter ?? null,
           hasMore: result.hasMore ?? false,
+          shown: Math.min(result.rows.length, limit),
+          truncated: more,
+          notices: more
+            ? [[`Showing the first ${Math.min(result.rows.length, limit)}`, limit < THIRTEENF_MAX_LIMIT ? `more: --limit ${THIRTEENF_MAX_LIMIT}` : ""].filter(Boolean).join(" | ")]
+            : [],
         },
       };
     },

package/src/plugins/builtin/thirteenf/report-notes.ts

@@ -0,0 +1,149 @@
+import type { CrowdingRow, TickerHolderRow } from "./signals";
+import { formatMoneyCompact } from "./format";
+
+/**
+ * Summary lines for the 13F text reports. Each says which quarters the rows
+ * compare, that values are as filed, and, whenever rows are cut, how many
+ * are shown and the option that shows the rest.
+ */
+
+/** The largest `--limit` the 13F report accepts. */
+export const THIRTEENF_MAX_LIMIT = 200;
+
+export const AS_FILED_VALUE = "Value (USD) as reported at period end, not today's price";
+
+const count = (value: number) => value.toLocaleString("en-US");
+
+export function periodText(period: string | null | undefined, previousPeriod?: string | null): string {
+  if (!period) return "";
+  return previousPeriod ? `Period ${period} vs ${previousPeriod}` : `Period ${period}`;
+}
+
+/** "showing 50 of 374" from the start of the list, "showing 51-100 of 374" past it. */
+function shownRangeText(offset: number, end: number, total: number): string {
+  return offset > 0
+    ? `showing ${count(offset + 1)}-${count(end)} of ${count(total)}`
+    : `showing ${count(end)} of ${count(total)}`;
+}
+
+/** "showing 50 of 104 positions | more: --limit 104"; empty when nothing is cut. */
+export function cutText(total: number, limit: number, noun: string): string {
+  if (total <= limit) return "";
+  return [
+    `showing ${count(limit)} of ${count(total)} ${noun}`,
+    limit < THIRTEENF_MAX_LIMIT ? `more: --limit ${Math.min(THIRTEENF_MAX_LIMIT, total)}` : "",
+  ].filter(Boolean).join(" | ");
+}
+
+export interface TickerHoldingsSummary {
+  notices: string[];
+  /** Funds in the list: holders, then the funds that exited. */
+  total: number;
+  /** The fund offset where the next page starts. */
+  nextOffset: number;
+  /** Funds with rows shown. */
+  shownFunds: number;
+  /** Rows follow the ones shown. */
+  truncated: boolean;
+  /** Reported value of the positions shown, exits excluded. */
+  shownValue: number | null;
+}
+
+/**
+ * The ticker-holdings list ranks a quarter's holders by size, then the funds
+ * that exited. A fund can have several rows (shares, calls, puts), so pages
+ * are counted in funds.
+ */
+export function summarizeTickerHoldings(input: {
+  period: string;
+  previousPeriod?: string | null;
+  holderCount: number;
+  newCount?: number | null;
+  exitCount?: number | null;
+  offset: number;
+  limit: number;
+  /** Rows of the pages loaded from `offset`, in list order. */
+  loaded: readonly Pick<TickerHolderRow, "cik" | "value" | "action">[];
+  /** The source has pages after the loaded ones, from `nextOffset`. */
+  hasMore: boolean;
+  nextOffset: number;
+}): TickerHoldingsSummary {
+  const shownRows = input.loaded.slice(0, input.limit);
+  const funds = [...new Set(shownRows.map((row) => row.cik))];
+  const cut = input.loaded.length > shownRows.length;
+  const lastCut = cut && input.loaded[shownRows.length]?.cik === shownRows.at(-1)?.cik;
+  // A fund whose holdings could not be read keeps its place in the source's
+  // list without rows, so a cut page restarts after the funds shown whole:
+  // that can repeat a few, never skip one.
+  const nextOffset = cut ? input.offset + Math.max(1, funds.length - (lastCut ? 1 : 0)) : input.nextOffset;
+  const truncated = cut || input.hasMore;
+  const partial = truncated || input.offset > 0;
+  const compared = !!input.previousPeriod;
+  const exits = compared ? input.exitCount ?? 0 : 0;
+  const listed = input.holderCount + exits;
+  // The source's next offset steps a whole page, past the end of the list on the last one.
+  const total = truncated ? Math.max(listed, nextOffset + 1) : Math.max(listed, input.offset + funds.length);
+  const end = !truncated ? total : cut ? input.offset + funds.length : nextOffset;
+  const shownValue = shownRows
+    .filter((row) => row.action !== "exit")
+    .reduce<number | null>((sum, row) => (sum != null && row.value != null ? sum + row.value : null), 0);
+  const holders = [
+    `${count(input.holderCount)} holders`,
+    compared && input.newCount != null ? ` (${count(input.newCount)} new)` : "",
+    compared && input.exitCount != null ? `, ${count(input.exitCount)} exited` : "",
+    !partial && shownValue ? `, total ${formatMoneyCompact(shownValue)}` : "",
+  ].join("");
+  const notices = [[periodText(input.period, input.previousPeriod), holders, AS_FILED_VALUE].filter(Boolean).join(" | ")];
+  if (partial) {
+    const shown = [
+      `${shownRangeText(input.offset, end, total)} funds`,
+      exits > 0 ? ", exits last" : "",
+      shownValue ? `; the ${count(funds.length)} shown hold ${formatMoneyCompact(shownValue)}` : "",
+    ].join("");
+    // The limit counts rows and a fund can have several, so the larger page is the safe suggestion.
+    const more = truncated
+      ? `more: --offset ${nextOffset}${input.limit < THIRTEENF_MAX_LIMIT ? ` or --limit ${THIRTEENF_MAX_LIMIT}` : ""}`
+      : null;
+    notices.push([`${shown[0]!.toUpperCase()}${shown.slice(1)}`, more].filter(Boolean).join(" | "));
+  }
+  return { notices, total, nextOffset, shownFunds: funds.length, truncated, shownValue };
+}
+
+type CrowdingRank = "new" | "exits" | "increases" | "decreases";
+
+const RANK_LABELS: Record<CrowdingRank, string> = {
+  new: "new holders",
+  exits: "exits",
+  increases: "weight increase",
+  decreases: "weight decrease",
+};
+
+export function compareCrowding(rank: string, left: CrowdingRow, right: CrowdingRow): number {
+  if (rank === "new") return right.newCount - left.newCount;
+  if (rank === "exits") return right.exitCount - left.exitCount;
+  if (left.weightChange == null) return right.weightChange == null ? 0 : 1;
+  if (right.weightChange == null) return -1;
+  return (left.weightChange - right.weightChange) * (rank === "decreases" ? 1 : -1);
+}
+
+/**
+ * One ticker's place in the crowding ranking. Ties share a rank, so the
+ * number is how many securities rank strictly ahead, plus one.
+ */
+export function crowdingForTicker(
+  ranked: readonly CrowdingRow[],
+  ticker: string,
+  rank: string,
+): { rows: Array<CrowdingRow & { rank: number }>; notice: string } {
+  const label = RANK_LABELS[rank as CrowdingRank] ?? rank;
+  const rows = ranked
+    .filter((row) => row.ticker.toUpperCase() === ticker)
+    .map((row) => ({ ...row, rank: 1 + ranked.filter((other) => compareCrowding(rank, other, row) < 0).length }));
+  const of = `of ${count(ranked.length)} securities by ${label}`;
+  const notice = rows.length === 0
+    ? `${ticker} is not in this ranking | full ranking: fn 13F --view crowding | its 13F holders: fn 13F ${ticker}`
+    : rows.length === 1
+      ? `${ticker} ranks ${count(rows[0]!.rank)} ${of} | full ranking: fn 13F --view crowding`
+      : `${ticker} ranks ${rows.map((row) => `${count(row.rank)} (${row.type})`).join(", ")} ${of} | full ranking: fn 13F --view crowding`;
+  return { rows, notice };
+}

package/src/plugins/builtin/ticker-detail/financials/aggregation.ts

@@ -166,10 +166,14 @@ function aggregateQuarterlyStatements(
   }
   const currencies = new Set(statements.map((statement) => statement.currency));
   if (currencies.size > 1) return null;
+  // Its counts and EPS are on the quarters' share basis when all four state the same one.
+  const shareBases = new Set(statements.map((statement) => statement.shareBasis));
+  const shareBasis = shareBases.size === 1 ? [...shareBases][0] : undefined;
 
   const aggregate: FinancialTableStatement = {
     date,
     currency: [...currencies][0],
+    ...(shareBasis ? { shareBasis } : {}),
     aggregation: {
       kind: "trailing-four-quarters",
       periodEnd: statements.at(-1)!.date,