@gloom-sh/terminal 0.0.0-stage → 0.19.0

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

@@ -0,0 +1,329 @@
+import type { CrowdingRow, TickerHolderRow } from "./signals";
+import { formatMoneyCompact } from "./format";
+import { formatSplitRatio } from "./model";
+import type { ThirteenFFilingGap, ThirteenFOtherManager } from "./types";
+
+/**
+ * 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";
+
+/** What a 13F filing leaves out and how late it arrives; the text reports' note and the catalog's limitation. */
+export const THIRTEENF_LIMITS = "Long US-listed equity positions only: shorts, cash and most foreign stocks are absent. Filed up to 45 days after quarter end.";
+
+/** The value basis of option rows, for exports. */
+export const THIRTEENF_OPTIONS_NOTE = "CALL/PUT rows: Value and Shares are the underlying stock's (notional), not the option premium.";
+
+/** The marker the text reports put on an option row's type, explained by `OPTION_ROWS_NOTE`. */
+const OPTION_MARK = "*";
+export const OPTION_ROWS_NOTE = `${OPTION_MARK} ${THIRTEENF_OPTIONS_NOTE}`;
+
+export function isOptionType(type: unknown): boolean {
+  const text = typeof type === "string" ? type.trim().toUpperCase() : "";
+  return text === "CALL" || text === "PUT";
+}
+
+/** A position type as the text report prints it: `CALL*` for an option, which `OPTION_ROWS_NOTE` explains. */
+export function markedPositionType(type: unknown): string {
+  const text = typeof type === "string" && type ? type : "--";
+  return isOptionType(type) ? `${text}${OPTION_MARK}` : text;
+}
+
+const count = (value: number) => value.toLocaleString("en-US");
+
+function periodText(period: string | null | undefined, previousPeriod?: string | null): string {
+  if (!period) return "";
+  return previousPeriod ? `Period ${period} vs ${previousPeriod}` : `Period ${period}`;
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+const DAY_MS = 86_400_000;
+
+function calendarDay(date: string | null | undefined): Date | null {
+  if (!date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return null;
+  const day = new Date(`${date}T00:00:00Z`);
+  return Number.isFinite(day.getTime()) ? day : null;
+}
+
+/** "30 Jun 2026", or "30 Jun" in `omitYear`. */
+export function filingDayText(date: string, omitYear?: number): string {
+  const day = calendarDay(date);
+  if (!day) return date;
+  const text = `${day.getUTCDate()} ${MONTHS[day.getUTCMonth()]}`;
+  return day.getUTCFullYear() === omitYear ? text : `${text} ${day.getUTCFullYear()}`;
+}
+
+/** Whole days from a quarter end to the filing, or null when either date is unreadable. */
+export function filingLagDays(period: string | null | undefined, filed: string | null | undefined): number | null {
+  const end = calendarDay(period);
+  const day = calendarDay(filed);
+  return end && day ? Math.round((day.getTime() - end.getTime()) / DAY_MS) : null;
+}
+
+/**
+ * "Period 30 Jun · filed 14 Aug 2026 (45 days after quarter end) | QoQ vs 31 Mar":
+ * when the positions date from and when they became public. A date in the
+ * filing's year leaves its year out.
+ */
+export function filedPeriodText(
+  period: string | null | undefined,
+  filed: string | null | undefined,
+  previousPeriod?: string | null,
+): string {
+  if (!period) return "";
+  const filedDay = calendarDay(filed);
+  if (!filed || !filedDay) return periodText(period, previousPeriod);
+  const year = filedDay.getUTCFullYear();
+  const lag = filingLagDays(period, filed);
+  const after = lag != null && lag >= 0 ? ` (${count(lag)} ${lag === 1 ? "day" : "days"} after quarter end)` : "";
+  return [
+    `Period ${filingDayText(period, year)} · filed ${filingDayText(filed)}${after}`,
+    previousPeriod ? `QoQ vs ${filingDayText(previousPeriod, year)}` : "",
+  ].filter(Boolean).join(" | ");
+}
+
+/**
+ * The quarters whose filings Gloom Cloud restated to dollars, in its own words:
+ * "Values restated from thousands: 30 Jun 2026". Empty when none was.
+ */
+export function restatedValuesText(forms: readonly { periodOfReport: string; valueNote?: string }[]): string {
+  const noted = forms.filter((form) => form.valueNote);
+  if (noted.length === 0) return "";
+  const note = noted[0]!.valueNote!;
+  const periods = [...new Set(noted.map((form) => form.periodOfReport))].sort().reverse();
+  return `${note[0]!.toUpperCase()}${note.slice(1)}: ${periods.map((period) => filingDayText(period)).join(", ")}`;
+}
+
+/** A filer this many quarters behind the reporting cycle has missed a filing, not just filed late. */
+export function isStaleFiling(quartersBehind: number | null | undefined): quartersBehind is number {
+  return quartersBehind != null && quartersBehind > 1;
+}
+
+export function quartersOldText(quarters: number): string {
+  return `${count(quarters)} quarters old`;
+}
+
+const NOTHING_LATER = "nothing filed for a later quarter";
+
+export function staleFilingText(quarters: number): string {
+  return `Latest filing is ${quartersOldText(quarters)}; ${NOTHING_LATER}`;
+}
+
+/** The funds in a list whose latest filing is stale, the first few by name. */
+export function staleFundsText(funds: readonly { name: string; quarters: number }[], shown = 3): string {
+  if (funds.length === 0) return "";
+  if (funds.length === 1) return `${funds[0]!.name}: latest filing is ${quartersOldText(funds[0]!.quarters)}; ${NOTHING_LATER}`;
+  const named = funds.slice(0, shown).map((fund) => `${fund.name} (${quartersOldText(fund.quarters)})`).join(", ");
+  return `Latest filing 2+ quarters old: ${named}${funds.length > shown ? ` and ${count(funds.length - shown)} more` : ""}`;
+}
+
+interface SplitLine {
+  ticker: string;
+  issuer: string;
+}
+
+const lineName = (line: SplitLine) => line.ticker || line.issuer;
+
+/** The first few lines as `text` gives them, then a count of the rest. */
+function listedLines<T>(lines: readonly T[], text: (line: T) => string, shown = 5): string {
+  return `${lines.slice(0, shown).map(text).join(", ")}${lines.length > shown ? ` and ${count(lines.length - shown)} more` : ""}`;
+}
+
+/** "Split-adjusted: NVDA 10:1, Odd Co 1:10 (split between the filings, as the corporate actions show)": lines priced on split-adjusted shares. */
+export function splitAdjustedText(lines: readonly (SplitLine & { ratio: number })[], prefix = "Split-adjusted"): string {
+  return `${prefix}: ${listedLines(lines, (line) => `${lineName(line)} ${formatSplitRatio(line.ratio)}`)} (split between the filings, as the corporate actions show)`;
+}
+
+/** "No Est P&L: XYZ (shares and value per share moved as across a split, and the corporate actions could not be read to tell)": lines left without a figure, `leftOut` opening it. */
+export function splitUnreadText(lines: readonly SplitLine[], leftOut: string): string {
+  return `${leftOut}: ${listedLines(lines, lineName)} (shares and value per share moved as across a split, and the corporate actions could not be read to tell)`;
+}
+
+/** The note for the lines of a Holdings table left without an Est P&L because their split could not be confirmed: a data limitation, the pane's notice as well as the report's. */
+export function holdingUnreadNotes(rows: readonly (SplitLine & { splitUnread?: boolean })[]): string[] {
+  const unread = rows.filter((row) => row.splitUnread);
+  return unread.length ? [splitUnreadText(unread, "No Est P&L")] : [];
+}
+
+/** What a Holdings report says of its lines that moved as across a split: the ones priced split-adjusted (method, so a report's note only), and the ones left without a figure. */
+export function holdingSplitNotes(rows: readonly (SplitLine & { splitRatio?: number; splitUnread?: boolean })[]): string[] {
+  const adjusted = rows.flatMap((row) => row.splitRatio ? [{ ...row, ratio: row.splitRatio }] : []);
+  return [...(adjusted.length ? [splitAdjustedText(adjusted, "Est P&L split-adjusted")] : []), ...holdingUnreadNotes(rows)];
+}
+
+/** "Q2 2026" for the quarter ending 30 Jun 2026. */
+function quarterText(period: string): string {
+  const day = calendarDay(period);
+  return day ? `Q${Math.floor(day.getUTCMonth() / 3) + 1} ${day.getUTCFullYear()}` : period;
+}
+
+/** The fund to open for a manager: its CIK, else its quoted name. */
+function openCommand(manager: ThirteenFOtherManager): string {
+  return manager.cik ? `fn 13F ${manager.cik}` : `fn 13F "${manager.name}"`;
+}
+
+/**
+ * What a fund filed for the newest quarter past its deadline instead of a
+ * holdings report: "13F-NT for Q2 2026, filed 14 Aug; holdings reported by
+ * PERSHING SQUARE INC. | open: fn 13F 0002026053", or "No 13F for Q2 2026,
+ * due 14 Aug" once EDGAR shows nothing. `command: false` names the CIK instead
+ * of the command, for the pane.
+ */
+export function filingGapText(gap: ThirteenFFilingGap, { command = true }: { command?: boolean } = {}): string {
+  const quarter = quarterText(gap.period);
+  const year = Number(gap.due.slice(0, 4));
+  const filing = gap.filing;
+  if (filing?.form.startsWith("13F-NT")) {
+    const [first, ...others] = filing.otherManagers ?? [];
+    const filed = `13F-NT for ${quarter}, filed ${filingDayText(filing.filed, year)}`;
+    if (!first) return `${filed}; another manager reported its holdings`;
+    const more = others.length ? ` and ${count(others.length)} more` : "";
+    return command
+      ? `${filed}; holdings reported by ${first.name}${more} | open: ${openCommand(first)}`
+      : `${filed}; holdings reported by ${first.name}${first.cik ? ` (CIK ${first.cik})` : ""}${more}`;
+  }
+  if (filing) return `${filing.form} for ${quarter} filed ${filingDayText(filing.filed, year)}; its holdings are not loaded yet`;
+  // Unasked, EDGAR may well hold a 13F-NT or a report the source has not loaded: say only what the loaded filings show.
+  if (!gap.checked) return `${quarter} 13F (due ${filingDayText(gap.due, year)}) not in the loaded filings; EDGAR not checked`;
+  return `No 13F for ${quarter}, due ${filingDayText(gap.due, year)}`;
+}
+
+/** A search asks EDGAR about a few lagging funds only: "EDGAR checked for the first 10 of 14 funds with no Q2 2026 13F loaded; ...". */
+export function uncheckedFundsText(asked: number, behind: number, period: string): string {
+  return `EDGAR checked for the first ${count(asked)} of ${count(behind)} funds with no ${quarterText(period)} 13F loaded; fn 13F <CIK> checks any other`;
+}
+
+/** "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/thirteenf/signals-pane.tsx

@@ -0,0 +1,153 @@
+import { useCallback, useEffect, useMemo, useRef, type ReactNode } from "react";
+import { DataTableStackView, DataTableView, EmptyState, QueryBar, usePagedRows, usePaneNoticeFooter, useTableLoadMore, type DataTableColumn, type PageRequest, type DataTableKeyEvent, type DataTableRootKeyContext, type PaneHint, StatGrid, type StatItem } from "../../../components";
+import { useShortcut } from "../../../react/input";
+import { colors } from "../../../theme/colors";
+import type { PaneProps } from "../../../types/plugin";
+import { Box, type ScrollBoxRenderable } from "../../../ui";
+import { isPlainKey } from "../../../utils/keyboard";
+import { usePluginPaneState, usePluginTickerActions } from "../../runtime";
+import { useMineTickers } from "../shared/mine-tickers";
+import { usePaneStatusFooter } from "../../../components/layout/pane/status-footer";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { useAsyncResource } from "../../../react/async-resource";
+import { actionLabel, formatMoneyCompact, formatShares, formatWeightMaybe } from "./format";
+import { FundDetailView } from "./pane";
+import { appendTickerHoldings, loadCrowding, loadTickerHoldings, type Crowding, type CrowdingRow, type TickerHolderRow } from "./signals";
+import { usePaneTickerIdentity } from "../../../state/hooks/pane-ticker";
+
+export function ThirteenFTickerPane({ focused, width, height }: Pick<PaneProps, "focused" | "width" | "height">) {
+  const { ticker } = usePaneTickerIdentity();
+  const symbol = ticker?.metadata.ticker ?? "";
+  if (!symbol) return <EmptyState title="Select a ticker." />;
+  return <ThirteenFTickerHoldingsView symbol={symbol} focused={focused} width={width} height={height} />;
+}
+
+/**
+ * A ticker's 13F holders with their position in that ticker: value, shares,
+ * weight in the fund's book and the quarter's action. The 13F pane shows it
+ * for a ticker query, as `fn 13F <ticker>` does.
+ */
+export function ThirteenFTickerHoldingsView({ symbol, focused, width, height, queryBar, hints, onRootKeyDown, onUnavailable, onDetailChange }: Pick<PaneProps, "focused" | "width" | "height"> & {
+  symbol: string;
+  /** The pane's query bar, given the report period for its meta. */
+  queryBar?: (period: string | undefined) => ReactNode;
+  hints?: PaneHint[];
+  onRootKeyDown?: (event: DataTableKeyEvent, context: DataTableRootKeyContext) => boolean;
+  /** The first page failed, e.g. a ticker without a mapped CUSIP. */
+  onUnavailable?: () => void;
+  onDetailChange?: (open: boolean) => void;
+}) {
+  const [selectedId, setSelectedId] = usePluginPaneState<string | null>("13f-ticker:selected", null);
+  const [fund, setFund] = usePluginPaneState<{ cik: string; name: string } | null>("13f-ticker:fund", null);
+  const unavailableRef = useRef(onUnavailable); unavailableRef.current = onUnavailable;
+  useEffect(() => {
+    onDetailChange?.(!!fund);
+    return () => onDetailChange?.(false);
+  }, [fund, onDetailChange]);
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null);
+  const loadPage = useCallback(({ offset, signal }: PageRequest) => loadTickerHoldings(symbol, offset, signal), [symbol]);
+  const paged = usePagedRows(symbol ? loadPage : null);
+  // Later pages merge into the first the same way the headless command merges them.
+  const data = useMemo(() => (paged.pages.length > 0 ? paged.pages.reduce(appendTickerHoldings) : null), [paged.pages]);
+  const loading = paged.loading || paged.loadingMore;
+  // A failed first page means the ticker has no positions view; a caller
+  // with a fallback takes over instead of showing the failure.
+  const error = (paged.moreError ?? (onUnavailable ? null : paged.error))?.message ?? null;
+  useEffect(() => { if (paged.error) unavailableRef.current?.(); }, [paged.error]);
+  useEffect(() => { setFund(null); setSelectedId(null); }, [symbol]);
+  const more = useTableLoadMore(scrollRef, paged.hasMore && !fund, paged.loadMore);
+  usePaneRefreshKey(paged.reload, { focused, enabled: !fund });
+  usePaneStatusFooter({ registrationId: "13f-ticker", enabled: !fund, loading, error, hints });
+  usePaneNoticeFooter({ registrationId: "13f-ticker-notice", enabled: !fund, focused, notices: data?.warnings ?? [] });
+  const columns: DataTableColumn[] = [
+    { id: "fund", label: "FUND", width: 20, align: "left", flexGrow: 1 },
+    { id: "type", label: "TYPE", width: 6, align: "left" },
+    { id: "value", label: "VALUE", width: 12, align: "right" },
+    { id: "shares", label: "SHARES", width: 12, align: "right" },
+    { id: "weight", label: "13F %", width: 9, align: "right" },
+    { id: "action", label: "ACTION", width: 8, align: "left" },
+  ];
+  const [sort, setSort] = usePluginPaneState<{ id: string; desc: boolean }>("13f-ticker:sort", { id: "value", desc: true });
+  const rows = useMemo(() => [...(data?.rows ?? [])].sort((a, b) => compareCells(a, b, sort.id, sort.desc)), [data?.rows, sort]);
+  // The period is the as-of: the query bar's meta where there is one, else a
+  // cell. Holder counts and the loaded rows' value total say how much of the
+  // list has paged in, not something about the ticker, so they stay out.
+  const net = data ? data.newCount - data.exitCount : 0;
+  const statItems: StatItem[] = data ? [
+    ...(queryBar ? [] : [{ id: "period", label: "Period", value: data.period }]),
+    { id: "net", label: "Net funds", value: `${net > 0 ? "+" : ""}${net}`, detail: `${data.newCount} new, ${data.exitCount} exited`, tone: net > 0 ? "positive" : net < 0 ? "negative" : undefined },
+  ] : [];
+  const header = queryBar || data ? <>{queryBar?.(data?.period)}<StatGrid items={statItems} width={width} /></> : undefined;
+  return <DataTableStackView<TickerHolderRow, DataTableColumn>
+    focused={focused} detailOpen={!!fund} onBack={() => setFund(null)} detailTitle={fund?.name}
+    detailContent={fund ? <FundDetailView focused={focused} seed={fund} width={width} /> : <Box />}
+    rootWidth={width} rootHeight={height} scrollRef={scrollRef} onBodyScrollActivity={more}
+    onRootKeyDown={onRootKeyDown}
+    rootBefore={header}
+    columns={columns} items={rows} getItemKey={row => row.id}
+    selection={{ kind: "id", selectedId, getId: row => row.id, onChange: setSelectedId }}
+    onActivate={row => setFund({ cik: row.cik, name: row.fund })}
+    sortColumnId={sort.id} sortDirection={sort.desc ? "desc" : "asc"}
+    onHeaderClick={id => setSort(current => ({ id, desc: current.id === id ? !current.desc : id !== "fund" }))}
+    renderCell={(row, column, _index, state) => ({ text: column.id === "value" ? formatMoneyCompact(row.value) : column.id === "shares" ? formatShares(row.shares) : column.id === "weight" ? formatWeightMaybe(row.weight) : column.id === "action" ? actionLabel(row.action) : String(row[column.id as keyof TickerHolderRow] ?? "--"), color: state.selected ? colors.selectedText : colors.text })}
+    emptyStateTitle={loading ? "Loading 13F holders..." : error ? "13F holders unavailable." : "No reported holders."}
+  />;
+}
+function compareCells(a: object, b: object, id: string, desc: boolean) {
+  const left = (a as Record<string, unknown>)[id], right = (b as Record<string, unknown>)[id];
+  if (left == null) return right == null ? 0 : 1;
+  if (right == null) return -1;
+  const compared = typeof left === "number" && typeof right === "number" ? left - right : String(left).localeCompare(String(right));
+  return desc ? -compared : compared;
+}
+
+const CROWDING_RANKS = ["newCount", "exitCount", "weightChange", "decreases"] as const;
+type CrowdingRank = typeof CROWDING_RANKS[number];
+function crowdingRank(value: string): CrowdingRank {
+  return (CROWDING_RANKS as readonly string[]).includes(value) ? value as CrowdingRank : "newCount";
+}
+
+const loadCrowdingResource = () => loadCrowding();
+
+export function ThirteenFCrowdingPane({ focused, width, height }: Pick<PaneProps, "focused" | "width" | "height">) {
+  const { data, loading, error, reload } = useAsyncResource<Crowding>(loadCrowdingResource);
+  const [selectedId, setSelectedId] = usePluginPaneState<string | null>("13f-crowding:selected", null);
+  const mine = useMineTickers();
+  const [mineOnly, setMineOnly] = usePluginPaneState<boolean>("13f-crowding:mine", false);
+  const [storedRanking, setRanking] = usePluginPaneState<string>("13f-crowding:ranking", "newCount");
+  // Header clicks used to store any column id; only the four views rank.
+  const ranking = crowdingRank(storedRanking);
+  const { pinTicker } = usePluginTickerActions();
+  usePaneRefreshKey(() => void reload(), { focused });
+  useShortcut(event => { if (!focused) return; if (isPlainKey(event, "m")) { event.preventDefault?.(); setMineOnly(value => !value); } if (isPlainKey(event, "c")) { event.preventDefault?.(); setRanking(value => CROWDING_RANKS[(CROWDING_RANKS.indexOf(crowdingRank(value)) + 1) % CROWDING_RANKS.length]!); } });
+  // Mine and the ranking sit in the query bar; m and c stay as their keys.
+  usePaneStatusFooter({ registrationId: "13f-crowding", loading, error });
+  usePaneNoticeFooter({ registrationId: "13f-crowding-notice", focused, notices: [
+    ...(data && data.loadedFunds < data.sourceFunds ? [`The ranking covers ${data.loadedFunds} of ${data.sourceFunds} funds.`] : []),
+    ...(data?.warnings ?? []),
+  ] });
+  // Only the ranked columns sort, and each maps to its view; DELTA PP flips
+  // between increases and decreases.
+  const rankByHeader = useCallback((columnId: string) => {
+    if (columnId === "newCount" || columnId === "exitCount") setRanking(columnId);
+    else if (columnId === "weightChange") setRanking(value => crowdingRank(value) === "weightChange" ? "decreases" : "weightChange");
+  }, [setRanking]);
+  const rows = useMemo(() => [...(data?.rows ?? [])].filter(row => !mineOnly || mine.has(row.ticker)).sort((a, b) => compareCells(a, b, ranking === "decreases" ? "weightChange" : ranking, ranking !== "decreases")), [data?.rows, ranking, mineOnly, mine]);
+  const columns: DataTableColumn[] = [
+    { id: "mine", label: "MINE", width: 5, align: "left" }, { id: "ticker", label: "TICKER", width: 10, align: "left" }, { id: "issuer", label: "ISSUER", width: Math.max(18, width - 82), align: "left" }, { id: "type", label: "TYPE", width: 5, align: "left" },
+    { id: "holderCount", label: "FUNDS", width: 6, align: "right" }, { id: "newCount", label: "NEW", width: 5, align: "right" }, { id: "exitCount", label: "EXIT", width: 5, align: "right" },
+    { id: "weightChange", label: "DELTA PP", width: 11, align: "right" }, { id: "comparedFunds", label: "COMP", width: 5, align: "right" }, { id: "totalValue", label: "VALUE", width: 12, align: "right" },
+  ];
+  return <Box flexDirection="column" width={width} height={height}>
+    <QueryBar width={width} filters={[{ id: "mine", kind: "toggle", label: "Mine", value: mineOnly, onChange: setMineOnly }]}
+      view={{ value: ranking, options: [{ label: "New", value: "newCount" }, { label: "Exits", value: "exitCount" }, { label: "Increases", value: "weightChange" }, { label: "Decreases", value: "decreases" }], onChange: setRanking }}
+      meta={data?.period} />
+    <DataTableView<CrowdingRow, DataTableColumn> focused={focused} columns={columns} items={rows} getItemKey={row => row.id}
+      selection={{ kind: "id", selectedId, getId: row => row.id, onChange: setSelectedId }}
+      onActivate={row => { if (row.ticker && row.ticker !== row.cusip) pinTicker(row.ticker, { floating: true }); }}
+      onHeaderClick={rankByHeader} isColumnSortable={column => column.id === "newCount" || column.id === "exitCount" || column.id === "weightChange"} sortColumnId={ranking === "decreases" ? "weightChange" : ranking} sortDirection={ranking === "decreases" ? "asc" : "desc"}
+      renderCell={(row, column, _index, state) => ({ text: column.id === "mine" ? mine.has(row.ticker) ? "yes" : "" : column.id === "totalValue" ? formatMoneyCompact(row.totalValue) : column.id === "weightChange" ? row.weightChange == null ? "--" : `${row.weightChange > 0 ? "+" : ""}${(row.weightChange * 100).toFixed(2)}` : String(row[column.id as keyof CrowdingRow] ?? "--"), color: state.selected ? colors.selectedText : colors.text })}
+      emptyStateTitle={loading ? "Loading 13F crowding..." : error ? "13F crowding unavailable." : "No comparable positions."}
+    />
+  </Box>;
+}

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

@@ -0,0 +1,74 @@
+import { apiClient } from "../../../api-client";
+import type { HoldingAction } from "./types";
+
+export interface TickerHolderRow {
+  id: string;
+  cik: string;
+  fund: string;
+  ticker: string;
+  cusip: string;
+  issuer: string;
+  type: string;
+  value: number | null;
+  shares: number | null;
+  /** Shares at the prior period end when the two reports compare: 0 for a new position, null when unknown. Absent from an older service. */
+  previousShares?: number | null;
+  weight: number | null;
+  previousWeight: number | null;
+  weightChange: number | null;
+  action: HoldingAction;
+}
+export interface CrowdingRow {
+  id: string;
+  ticker: string;
+  cusip: string;
+  issuer: string;
+  type: string;
+  holderCount: number;
+  newCount: number;
+  exitCount: number;
+  comparedFunds: number;
+  totalValue: number | null;
+  weightChange: number | null;
+}
+interface SignalsBase {
+  quarter: string;
+  period: string;
+  previousPeriod: string;
+  warnings: string[];
+  asOf: string;
+}
+export interface TickerHoldings extends SignalsBase {
+  ticker: string;
+  rows: TickerHolderRow[];
+  holderCount: number;
+  newCount: number;
+  exitCount: number;
+  totalValue: number | null;
+  valueScope: string;
+  hasMore: boolean;
+  nextOffset: number;
+}
+export interface Crowding extends SignalsBase {
+  rows: CrowdingRow[];
+  requestedFunds: number;
+  sourceFunds: number;
+  loadedFunds: number;
+}
+export async function loadTickerHoldings(ticker: string, offset = 0, signal?: AbortSignal): Promise<TickerHoldings> {
+  signal?.throwIfAborted();
+  const result = await apiClient.getCloudSec13F("ticker-holdings", { tickers: ticker, offset, limit: 25 }, { signal }) as TickerHoldings;
+  signal?.throwIfAborted();
+  return result;
+}
+export async function loadCrowding(signal?: AbortSignal): Promise<Crowding> {
+  signal?.throwIfAborted();
+  const result = await apiClient.getCloudSec13F("crowding", { limit: 25 }) as Crowding;
+  signal?.throwIfAborted();
+  return result;
+}
+export function appendTickerHoldings(current: TickerHoldings, page: TickerHoldings): TickerHoldings {
+  if (current.ticker !== page.ticker || current.period !== page.period) return page;
+  const rows = [...new Map([...current.rows, ...page.rows].map(row => [row.id, row])).values()];
+  return { ...page, rows, warnings: [...new Set([...current.warnings, ...page.warnings])], totalValue: rows.filter(row => row.action !== "exit").reduce<number | null>((total, row) => total != null && row.value != null ? total + row.value : null, 0), valueScope: "loaded funds" };
+}