gloomberb 0.16.1 → 0.16.2

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

@@ -1,8 +1,8 @@
 import { Box, Span, Text, TextAttributes, useUiCapabilities } from "../../../ui";
 import { useThemeColors } from "../../../theme/theme-context";
 import { blendHex } from "../../../theme/colors";
-import { displayWidth, truncateToDisplayWidth } from "../../../utils/format";
-import { gpuAxisTicks, gpuBasisColor, gpuBasisLabel, gpuPrice, type GpuLadderRow } from "./model";
+import { truncateToDisplayWidth } from "../../../utils/format";
+import { gpuAxisLabels, gpuBasisColor, gpuBasisLabel, gpuPrice, type GpuAxisLabel, type GpuLadderRow } from "./model";
 
 const LABEL_CELLS = 28;
 const VALUE_CELLS = 17;
@@ -10,14 +10,13 @@ const VALUE_CELLS = 17;
 const position = (value: number, low: number, high: number) => high > low ? (value - low) / (high - low) : 0.5;
 const percent = (ratio: number) => `${(Math.max(0, Math.min(1, ratio)) * 100).toFixed(2)}%`;
 
-/** The domain every basis shares, padded to whole axis steps so the ends never touch a band. */
-function gpuLadderDomain(rows: readonly GpuLadderRow[]): { low: number; high: number; ticks: number[] } | null {
+/** The domain every basis shares, padded so the ends never touch a band. */
+function gpuLadderDomain(rows: readonly GpuLadderRow[]): { low: number; high: number } | null {
   if (!rows.length) return null;
   const min = Math.min(...rows.map((row) => row.min));
   const max = Math.max(...rows.map((row) => row.max));
   const pad = Math.max((max - min) * 0.04, max * 0.02, 0.05);
-  const low = Math.max(0, min - pad), high = max + pad;
-  return { low, high, ticks: gpuAxisTicks(low, high).filter((tick) => tick >= low && tick <= high) };
+  return { low: Math.max(0, min - pad), high: max + pad };
 }
 
 /** Terminal cells of one track: thin rule for the range, heavy for the quartiles, a bar at the median. */
@@ -51,7 +50,10 @@ export function GpuPriceLadder({ rows, width, height, selected }: {
   const valueCells = wide ? VALUE_CELLS : 6;
   // Two cells of padding, two gaps, and one spare so the value never clips.
   const trackCellsWidth = Math.max(8, width - labelCells - valueCells - 5);
-  const { low, high, ticks } = domain;
+  const { low, high } = domain;
+  // Labels may hang into the empty label and value columns of the axis row, so the end ticks stay centred.
+  const room = { left: labelCells + 1, right: valueCells + 1 };
+  const labels = gpuAxisLabels(low, high, trackCellsWidth, room);
   return (
     <Box flexDirection="column" width={width} height={shown.length + 1} paddingX={1} data-gloom-role="gpu-price-ladder">
       {shown.map((row) => {
@@ -91,37 +93,31 @@ export function GpuPriceLadder({ rows, width, height, selected }: {
           </Box>
         );
       })}
-      <Box flexDirection="row" height={1} gap={1}>
-        <Box width={labelCells} flexShrink={0} />
-        <GpuLadderAxis ticks={ticks} low={low} high={high} width={trackCellsWidth} desktop={desktop} />
-      </Box>
+      <GpuLadderAxis labels={labels} width={trackCellsWidth} room={room} desktop={desktop} />
     </Box>
   );
 }
 
-function GpuLadderAxis({ ticks, low, high, width, desktop }: { ticks: number[]; low: number; high: number; width: number; desktop: boolean }) {
+/**
+ * Each label centred on its tick, on the scale the bands and markers use. The
+ * desktop places real elements by percentage, as it does the markers; the
+ * terminal writes the whole axis row so an end label can hang past the track.
+ */
+function GpuLadderAxis({ labels, width, room, desktop }: { labels: readonly GpuAxisLabel[]; width: number; room: { left: number; right: number }; desktop: boolean }) {
   const colors = useThemeColors();
-  const label = (tick: number) => `$${Number.isInteger(tick) ? tick : tick.toFixed(1)}`;
   if (desktop) {
     return (
-      <Box width={width} height={1} flexShrink={0} style={{ position: "relative" }}>
-        {ticks.map((tick, index) => {
-          const ratio = position(tick, low, high);
-          const align = index === 0 ? "0%" : index === ticks.length - 1 ? "-100%" : "-50%";
-          return <Box key={tick} style={{ position: "absolute", left: percent(ratio), transform: `translateX(${align})` }}>
-            <Text fg={colors.textDim}>{label(tick)}</Text>
-          </Box>;
-        })}
+      <Box flexDirection="row" height={1}>
+        <Box width={room.left} flexShrink={0} />
+        <Box width={width} height={1} flexShrink={0} style={{ position: "relative" }}>
+          {labels.map((label) => <Box key={label.value} style={{ position: "absolute", left: percent(label.ratio), transform: "translateX(-50%)", whiteSpace: "nowrap" }}>
+            <Text fg={colors.textDim}>{label.text}</Text>
+          </Box>)}
+        </Box>
       </Box>
     );
   }
-  const line = Array.from({ length: width }, () => " ");
-  for (const [index, tick] of ticks.entries()) {
-    const text = label(tick);
-    const center = Math.round(position(tick, low, high) * (width - 1));
-    const start = index === 0 ? 0 : index === ticks.length - 1 ? width - displayWidth(text) : center - Math.floor(text.length / 2);
-    if (start < 0 || start + text.length > width || line.slice(Math.max(0, start - 1), start + text.length + 1).some((char) => char !== " ")) continue;
-    for (let i = 0; i < text.length; i++) line[start + i] = text[i]!;
-  }
-  return <Box width={width} height={1} flexShrink={0}><Text fg={colors.textDim}>{line.join("")}</Text></Box>;
+  const line = Array.from({ length: room.left + width + room.right }, () => " ");
+  for (const label of labels) for (let i = 0; i < label.text.length; i++) line[room.left + label.start + i] = label.text[i]!;
+  return <Box height={1} flexShrink={0}><Text fg={colors.textDim}>{line.join("").trimEnd()}</Text></Box>;
 }

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

@@ -151,7 +151,7 @@ export function gpuPriceLadder(rows: readonly GpuBoardRow[], model: string): Gpu
 }
 
 /** Round dollar ticks for a price axis: one, two or five times a power of ten, four to six of them. */
-export function gpuAxisTicks(low: number, high: number): number[] {
+function gpuAxisTicks(low: number, high: number): number[] {
   if (!(high > low)) return [low];
   const raw = (high - low) / 5;
   const power = 10 ** Math.floor(Math.log10(raw));
@@ -161,6 +161,32 @@ export function gpuAxisTicks(low: number, high: number): number[] {
   return ticks;
 }
 
+export interface GpuAxisLabel { value: number; text: string; ratio: number; start: number }
+
+/**
+ * Labels for a price axis `cells` wide over `low`..`high`: each centred on its
+ * tick's own value, on the linear scale the bands and markers use (`ratio`, and
+ * `start`, the first cell on the terminal), with the decimals the tick step
+ * needs so neighbours never read alike ($2.0 $2.1 $2.2, $2.05 $2.10). A label
+ * that would touch its neighbour or run past the room beside the axis is left
+ * out, never moved off its value.
+ */
+export function gpuAxisLabels(low: number, high: number, cells: number, room: { left: number; right: number } = { left: 0, right: 0 }): GpuAxisLabel[] {
+  const ticks = gpuAxisTicks(low, high).filter((tick) => tick >= low && tick <= high);
+  const digits = [0, 1, 2, 3].find((places) => ticks.every((tick) => Math.abs(Number(tick.toFixed(places)) - tick) < 1e-9)) ?? 3;
+  const labels: GpuAxisLabel[] = [];
+  for (const value of ticks) {
+    const text = `$${value.toFixed(digits)}`;
+    const ratio = high > low ? (value - low) / (high - low) : 0.5;
+    // The cell a track draws this value in, so the label's middle sits on the marker's cell.
+    const start = Math.round(ratio * (cells - 1)) - Math.floor(text.length / 2);
+    const previous = labels.at(-1);
+    if (start < -room.left || start + text.length > cells + room.right || (previous && start <= previous.start + previous.text.length)) continue;
+    labels.push({ value, text, ratio, start });
+  }
+  return labels;
+}
+
 /** Published notices use their effective date; observed changes use the dated evidence. */
 export const gpuEventDate = (event: Pick<GpuEvent, "origin" | "effectiveAt" | "observedAt">) =>
   event.origin === "published" ? event.effectiveAt ?? event.observedAt : event.observedAt;

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

@@ -0,0 +1,209 @@
+import { apiClient } from "../../../api-client";
+import type {
+  BeneficialOwnerFiling,
+  BeneficialOwnerReportingPerson,
+  BeneficialOwnerStatus,
+  BeneficialOwnersForm,
+  BeneficialOwnersPayload,
+} from "../../../api-client/beneficial-owners";
+import { ApiRequestError, isAccessDenied } from "../../../api-client/errors";
+import { createPluginCache } from "../../../data/plugin-cache";
+import { finiteOrNull, recordOrNull } from "../../../utils/guards";
+import { cachedCloudResource, loadCloudResource, type CloudResource } from "../shared/cloud-resource";
+import { CLOUD_SESSION_REQUIRED } from "../shared/research-cloud-session";
+
+/** One page of the route; the loader follows `nextOffset` until it has every report. */
+const PAGE_SIZE = 100;
+/** More than any issuer has filers; a history this long is cut and marked incomplete. */
+const MAX_ROWS = 2_000;
+
+export const beneficialOwnersCache = createPluginCache<BeneficialOwnersPayload>({
+  kind: "beneficial-owners",
+  source: "gloom-cloud",
+  schemaVersion: 1,
+  policy: { staleMs: 30 * 60_000, expireMs: 7 * 24 * 60 * 60_000 },
+});
+
+export interface BeneficialOwnersRequest {
+  form?: BeneficialOwnersForm;
+  /** Every report instead of the latest per filer. */
+  history?: boolean;
+}
+
+type BeneficialOwnersClient = Pick<typeof apiClient, "getCloudSecBeneficialOwners">;
+
+const text = (value: unknown): string | null => typeof value === "string" && value.trim() ? value.trim() : null;
+const isoDate = (value: unknown): string | null => {
+  const raw = text(value);
+  return raw && /^\d{4}-\d{2}-\d{2}/.test(raw) ? raw.slice(0, 10) : null;
+};
+const cikOrNull = (value: unknown): string | null => {
+  const raw = typeof value === "number" ? String(value) : text(value);
+  return raw && /\d/.test(raw) ? raw : null;
+};
+
+function normalizeReportingPerson(value: unknown): BeneficialOwnerReportingPerson | null {
+  const raw = recordOrNull(value);
+  const name = text(raw?.name);
+  if (!raw || !name) return null;
+  return { name, cik: cikOrNull(raw.cik), percentOfClass: finiteOrNull(raw.percentOfClass), shares: finiteOrNull(raw.shares) };
+}
+
+const STATUSES: readonly BeneficialOwnerStatus[] = ["holder", "below-threshold", "exited"];
+
+/**
+ * A report as the table can trust it. Fields the route adds later pass
+ * through; a report without a filer, accession or filing date is dropped,
+ * and a number that is not one stays null instead of being guessed. History
+ * reports carry no previous report or status, and none is made up for them.
+ */
+function normalizeBeneficialOwnerFiling(value: unknown): BeneficialOwnerFiling | null {
+  const raw = recordOrNull(value);
+  if (!raw) return null;
+  const filerName = text(raw.filerName);
+  const accessionNumber = text(raw.accessionNumber);
+  const filingDate = isoDate(raw.filingDate);
+  const form = text(raw.form) ?? "";
+  const kind = raw.kind === "13D" || raw.kind === "13G" ? raw.kind
+    : /13D/i.test(form) ? "13D" : /13G/i.test(form) ? "13G" : null;
+  if (!filerName || !accessionNumber || !filingDate || !kind) return null;
+  const source = raw.source === "xml" || raw.source === "text" ? raw.source : "index";
+  return {
+    ...raw,
+    filerCik: cikOrNull(raw.filerCik),
+    filerName,
+    form: form || `SCHEDULE ${kind}`,
+    kind,
+    amendment: raw.amendment === true || /\/A\b/i.test(form),
+    amendmentNo: finiteOrNull(raw.amendmentNo),
+    percentOfClass: finiteOrNull(raw.percentOfClass),
+    shares: finiteOrNull(raw.shares),
+    classTitle: text(raw.classTitle),
+    cusip: text(raw.cusip),
+    eventDate: isoDate(raw.eventDate),
+    filingDate,
+    accessionNumber,
+    filingUrl: text(raw.filingUrl) ?? "",
+    previousPercent: "previousPercent" in raw ? finiteOrNull(raw.previousPercent) : undefined,
+    previousFilingDate: "previousFilingDate" in raw ? isoDate(raw.previousFilingDate) : undefined,
+    status: STATUSES.includes(raw.status as BeneficialOwnerStatus) ? raw.status as BeneficialOwnerStatus : undefined,
+    provisional: raw.provisional === true ? true : undefined,
+    source,
+    reportingPersons: Array.isArray(raw.reportingPersons)
+      ? raw.reportingPersons.map(normalizeReportingPerson).filter((person) => person != null)
+      : [],
+  };
+}
+
+function normalizeFilings(value: unknown): BeneficialOwnerFiling[] {
+  return Array.isArray(value)
+    ? value.map(normalizeBeneficialOwnerFiling).filter((filing) => filing != null)
+    : [];
+}
+
+function normalizeBeneficialOwnersPayload(value: unknown, ticker: string): BeneficialOwnersPayload {
+  const raw = recordOrNull(value);
+  if (!raw || !Array.isArray(raw.owners)) throw new Error("The server returned an invalid 13D/13G list");
+  const coverage = recordOrNull(raw.coverage);
+  const nextOffset = finiteOrNull(raw.nextOffset);
+  return {
+    ...raw,
+    ticker: text(raw.ticker) ?? ticker,
+    cik: cikOrNull(raw.cik) ?? "",
+    companyName: text(raw.companyName) ?? "",
+    asOf: text(raw.asOf),
+    owners: normalizeFilings(raw.owners),
+    ...(Array.isArray(raw.filings) ? { filings: normalizeFilings(raw.filings) } : {}),
+    hasMore: raw.hasMore === true && nextOffset != null,
+    nextOffset,
+    coverage: coverage ? {
+      ...coverage,
+      from: isoDate(coverage.from),
+      filings: finiteOrNull(coverage.filings) ?? 0,
+      parsed: finiteOrNull(coverage.parsed) ?? 0,
+      unparsed: finiteOrNull(coverage.unparsed) ?? 0,
+      unavailable: finiteOrNull(coverage.unavailable) ?? 0,
+    } : null,
+  };
+}
+
+function describeFailure(error: unknown, ticker: string): unknown {
+  if (isAccessDenied(error)) return new Error(CLOUD_SESSION_REQUIRED);
+  // An unknown ticker, and a server that does not serve the route yet.
+  if (error instanceof ApiRequestError && error.status === 404) {
+    return new Error(`13D/13G filings are not available for ${ticker}.`);
+  }
+  return error;
+}
+
+/**
+ * Every page of the issuer's reports: the latest per filer, or with
+ * `history` every report. A list cut at the row cap keeps `hasMore`.
+ */
+export async function fetchBeneficialOwners(
+  ticker: string,
+  { form = "all", history = false }: BeneficialOwnersRequest = {},
+  { client = apiClient, signal }: { client?: BeneficialOwnersClient; signal?: AbortSignal } = {},
+): Promise<BeneficialOwnersPayload> {
+  const symbol = ticker.trim().toUpperCase();
+  try {
+    let offset = 0;
+    let first: BeneficialOwnersPayload | null = null;
+    const owners: BeneficialOwnerFiling[] = [];
+    const filings: BeneficialOwnerFiling[] = [];
+    for (;;) {
+      const page = normalizeBeneficialOwnersPayload(await client.getCloudSecBeneficialOwners({
+        ticker: symbol,
+        form,
+        history,
+        limit: PAGE_SIZE,
+        offset,
+      }, { signal }), symbol);
+      first ??= page;
+      owners.push(...page.owners);
+      filings.push(...(page.filings ?? []));
+      const loaded = history ? filings.length : owners.length;
+      const nextOffset = page.nextOffset ?? 0;
+      if (!page.hasMore || nextOffset <= offset || loaded >= MAX_ROWS) {
+        return {
+          ...first,
+          asOf: page.asOf ?? first.asOf,
+          coverage: page.coverage ?? first.coverage,
+          owners: dedupe(owners),
+          ...(history ? { filings: dedupe(filings) } : {}),
+          hasMore: page.hasMore,
+          nextOffset: page.nextOffset,
+        };
+      }
+      offset = nextOffset;
+    }
+  } catch (error) {
+    throw describeFailure(error, symbol);
+  }
+}
+
+/** Pages can overlap when a report lands between two requests. */
+function dedupe(rows: BeneficialOwnerFiling[]): BeneficialOwnerFiling[] {
+  const seen = new Set<string>();
+  return rows.filter((row) => {
+    const key = `${row.accessionNumber}:${row.filerCik ?? row.filerName}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+const cacheKey = (ticker: string) => ticker.trim().toUpperCase();
+
+export function cachedBeneficialOwners(ticker: string): CloudResource<BeneficialOwnersPayload> | null {
+  return cachedCloudResource(beneficialOwnersCache, cacheKey(ticker));
+}
+
+/** 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>> {
+  try {
+    return await loadCloudResource(beneficialOwnersCache, cacheKey(ticker), () => fetchBeneficialOwners(ticker), { force });
+  } catch (error) {
+    throw describeFailure(error, cacheKey(ticker));
+  }
+}

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

@@ -0,0 +1,279 @@
+import type { BeneficialOwnerFiling, BeneficialOwnerStatus } from "../../../api-client/beneficial-owners";
+import type { DataTableColumn } from "../../../components";
+import type { HolderRecord } from "../../../types/financials";
+import { clipToDisplayWidth, displayWidth, formatCompact } from "../../../utils/format";
+import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
+import { matchFilerToHolder, type Holder13FMatch } from "./thirteenf-match";
+
+export type BeneficialColumnId =
+  | "filer"
+  | "form"
+  | "percentOfClass"
+  | "change"
+  | "shares"
+  | "eventDate"
+  | "filingDate"
+  | "thirteenF";
+export type BeneficialColumn = DataTableColumn & { id: BeneficialColumnId };
+
+export interface BeneficialSortPreference {
+  columnId: BeneficialColumnId;
+  direction: SortDirection;
+}
+
+export const DEFAULT_BENEFICIAL_SORT: BeneficialSortPreference = { columnId: "percentOfClass", direction: "desc" };
+
+/** What the filer did in its latest 13F against the quarter before. */
+export interface ThirteenFAction {
+  label: string;
+  /** The share change as a fraction of the prior position: NEW sorts first, EXIT is -1. */
+  value: number;
+}
+
+export interface BeneficialOwnerRow {
+  id: string;
+  filing: BeneficialOwnerFiling;
+  /** `13G/A`: the kind, and `/A` for an amendment. */
+  formLabel: string;
+  /** Percent points against the filer's report before this one. */
+  changePoints: number | null;
+  thirteenF: ThirteenFAction | null;
+  /** The stake the report discloses; null when the report gives neither a percentage nor shares. */
+  stake: BeneficialOwnerStatus | null;
+}
+
+/** Holder rows the 13F join reads: the Table tab's rows, keyed by their id. */
+type JoinableHolder = HolderRecord & { id: string };
+
+/** The Schedule 13D/13G reporting threshold, in percent of the class. */
+const REPORTING_THRESHOLD = 5;
+
+/**
+ * The stake a report discloses, from its own figures first, as the route
+ * reads them. A stake under 5% is still a stake; only a report whose figures
+ * are all zero (0% and zero shares, or one of them with the other missing)
+ * is an exit, and a contradictory one is not. A report with neither figure
+ * keeps the route's word for a stake under the threshold, but is never read
+ * as an exit.
+ */
+export function disclosedStake(
+  filing: Pick<BeneficialOwnerFiling, "percentOfClass" | "shares" | "status">,
+): BeneficialOwnerStatus | null {
+  const { percentOfClass: percent, shares } = filing;
+  const reported = [percent, shares].filter((value) => value != null);
+  if (reported.length > 0 && reported.every((value) => value === 0)) return "exited";
+  if (percent != null) return percent < REPORTING_THRESHOLD ? "below-threshold" : "holder";
+  return filing.status === "holder" || filing.status === "below-threshold" ? filing.status : null;
+}
+
+function signedPercent(fraction: number): string {
+  const rounded = Math.round(fraction * 100);
+  return rounded > 0 ? `+${rounded}%` : rounded < 0 ? `${rounded}%` : "0%";
+}
+
+/**
+ * The quarter's action from a 13F holder row. A position that grew from
+ * nothing is NEW, one reported at zero shares after a sale EXIT; without a
+ * reported change it is unknown, never "no change".
+ */
+export function thirteenFAction(holder: HolderRecord | undefined): ThirteenFAction | null {
+  if (!holder) return null;
+  const { shares, changeShares, changePercent } = holder;
+  if (shares === 0 && changeShares != null && changeShares < 0) return { label: "EXIT", value: -1 };
+  if (shares != null && changeShares != null) {
+    const prior = shares - changeShares;
+    if (changeShares > 0 && prior === 0) return { label: "NEW", value: Number.POSITIVE_INFINITY };
+    if (prior > 0) return { label: signedPercent(changeShares / prior), value: changeShares / prior };
+  }
+  if (changePercent != null && Number.isFinite(changePercent)) {
+    // The Table tab reads a provider's change the same way: a fraction up to 1, percent points above.
+    const fraction = Math.abs(changePercent) <= 1 ? changePercent : changePercent / 100;
+    return { label: signedPercent(fraction), value: fraction };
+  }
+  return null;
+}
+
+function beneficialFormLabel(filing: Pick<BeneficialOwnerFiling, "kind" | "amendment">): string {
+  return `${filing.kind}${filing.amendment ? "/A" : ""}`;
+}
+
+function pointChange(filing: BeneficialOwnerFiling): number | null {
+  if (filing.percentOfClass == null || filing.previousPercent == null) return null;
+  return Math.round((filing.percentOfClass - filing.previousPercent) * 100) / 100;
+}
+
+/**
+ * One row per report, joined to the filer's 13F holder row (CIK first, then
+ * name) for the quarter's action.
+ */
+export function buildBeneficialRows(
+  filings: readonly BeneficialOwnerFiling[],
+  holders: readonly JoinableHolder[] = [],
+  fundMatches: ReadonlyMap<string, Pick<Holder13FMatch, "cik">> = new Map(),
+): BeneficialOwnerRow[] {
+  return filings.map((filing) => ({
+    id: `${filing.accessionNumber}:${filing.filerCik ?? filing.filerName}`,
+    filing,
+    formLabel: beneficialFormLabel(filing),
+    changePoints: pointChange(filing),
+    thirteenF: thirteenFAction(matchFilerToHolder(filing, holders, fundMatches)),
+    stake: disclosedStake(filing),
+  }));
+}
+
+function sortValue(row: BeneficialOwnerRow, columnId: BeneficialColumnId): string | number | null {
+  switch (columnId) {
+    case "filer": return row.filing.filerName;
+    case "form": return row.formLabel;
+    case "percentOfClass": return row.filing.percentOfClass;
+    case "change": return row.changePoints;
+    case "shares": return row.filing.shares;
+    case "eventDate": return row.filing.eventDate;
+    case "filingDate": return row.filing.filingDate;
+    case "thirteenF": {
+      const value = row.thirteenF?.value;
+      // NEW leads a descending sort without leaving the finite range compareSortValues keeps.
+      return value == null ? null : value === Number.POSITIVE_INFINITY ? Number.MAX_SAFE_INTEGER : value;
+    }
+  }
+}
+
+/** Filers over the threshold (or not saying) first, then stakes under 5%, then exits. */
+function stakeGroup(row: BeneficialOwnerRow): number {
+  return row.stake === "exited" ? 2 : row.stake === "below-threshold" ? 1 : 0;
+}
+
+/** Sorted by the column within each stake group, whatever the direction; ties newest filing first. */
+export function sortBeneficialRows(rows: readonly BeneficialOwnerRow[], preference: BeneficialSortPreference): BeneficialOwnerRow[] {
+  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));
+}
+
+// Widths as the table draws them: never narrower than the header and its sort marker.
+const FORM_WIDTH = 6;
+/** `22.2%`, `4.9% <5%`, `0.0% EXIT`. */
+const PERCENT_WIDTH = 9;
+const CHANGE_WIDTH = 8;
+const SHARES_WIDTH = 8;
+const DATE_WIDTH = 10;
+const THIRTEEN_F_WIDTH = 5;
+const MIN_FILER_WIDTH = 14;
+/** The longest filer names and a group count; a wider pane keeps the figures beside the names. */
+const MAX_FILER_WIDTH = 56;
+/** Below this the event date gives its room to the filer's name; the filing date stays. */
+const EVENT_FILER_WIDTH = 20;
+
+export function buildBeneficialColumns(width: number): BeneficialColumn[] {
+  const fixed = FORM_WIDTH + PERCENT_WIDTH + CHANGE_WIDTH + SHARES_WIDTH + DATE_WIDTH + THIRTEEN_F_WIDTH;
+  // Two cells of padding and one gap after every column.
+  const roomWithEvent = width - 2 - 8 - fixed - DATE_WIDTH;
+  const showEvent = roomWithEvent >= EVENT_FILER_WIDTH;
+  const filerWidth = Math.min(MAX_FILER_WIDTH, Math.max(MIN_FILER_WIDTH, showEvent ? roomWithEvent : roomWithEvent + DATE_WIDTH + 1));
+  return [
+    { id: "filer", label: "FILER", width: filerWidth, align: "left" },
+    { id: "form", label: "FORM", width: FORM_WIDTH, align: "left" },
+    { id: "percentOfClass", label: "% CLASS", width: PERCENT_WIDTH, align: "right" },
+    { id: "change", label: "CHG", width: CHANGE_WIDTH, align: "right" },
+    { id: "shares", label: "SHARES", width: SHARES_WIDTH, align: "right" },
+    ...(showEvent ? [{ id: "eventDate" as const, label: "EVENT", width: DATE_WIDTH, align: "right" as const }] : []),
+    { id: "filingDate", label: "FILED", width: DATE_WIDTH, align: "right" },
+    { id: "thirteenF", label: "13F", width: THIRTEEN_F_WIDTH, align: "right" },
+  ];
+}
+
+/** Entity suffixes a narrow column drops before it cuts into the name itself. */
+const LEGAL_SUFFIX = /(?:[,\s]+(?:L\.?L\.?C|L\.?L\.?P|L\.?P|INC|LTD|LIMITED|CORP|CORPORATION|CO|PLC|N\.?A|S\.?A|AG|GMBH)\.?)+$/i;
+
+/**
+ * The filer's name in `width` cells, with ` +N` for the other reporting
+ * persons of a group. The entity suffix goes first, then the name is cut
+ * behind an ellipsis; the count is never cut.
+ */
+export function formatFilerName(name: string, otherPersons: number, width: number): string {
+  const suffix = otherPersons > 0 ? ` +${otherPersons}` : "";
+  const room = Math.max(1, width - displayWidth(suffix));
+  if (displayWidth(name) <= room) return `${name}${suffix}`;
+  const short = name.replace(LEGAL_SUFFIX, "").trim() || name;
+  return `${clipToDisplayWidth(short, room)}${suffix}`;
+}
+
+/** The marker after a stake that is not a 5% holding: under the threshold, or reported at zero. */
+export function stakeMarker(stake: BeneficialOwnerStatus | null): string {
+  return stake === "below-threshold" ? "<5%" : stake === "exited" ? "EXIT" : "";
+}
+
+/**
+ * A percent of class to one decimal, or two when one would round a stake
+ * under 5% up to `5.0%`: 4.96 reads `4.96%`.
+ */
+export function formatClassPercent(value: number): string {
+  const short = value.toFixed(1);
+  if (value >= REPORTING_THRESHOLD || Number(short) < REPORTING_THRESHOLD) return `${short}%`;
+  return `${(Math.floor(value * 100) / 100).toFixed(2)}%`;
+}
+
+/**
+ * The reported percent of class, as filed: `4.9%` stays `4.9%`. With
+ * `marker`, a stake under 5% reads `4.9% <5%` and a report of zero
+ * `0.0% EXIT`. A missing figure is a dash, or the bare marker when the
+ * route says which side of 5% the stake is on.
+ */
+export function formatPercentOfClass(
+  row: Pick<BeneficialOwnerRow, "stake" | "filing">,
+  { marker = false }: { marker?: boolean } = {},
+): string {
+  const value = row.filing.percentOfClass;
+  const mark = marker ? stakeMarker(row.stake) : "";
+  if (value == null) return mark || "-";
+  return mark ? `${formatClassPercent(value)} ${mark}` : formatClassPercent(value);
+}
+
+export function formatPointChange(value: number | null): string {
+  if (value == null) return "";
+  const rounded = Math.round(value * 10) / 10;
+  if (rounded === 0) return "0.0 pt";
+  return `${rounded > 0 ? "+" : ""}${rounded.toFixed(1)} pt`;
+}
+
+export function formatOwnerShares(value: number | null): string {
+  return value == null ? "-" : formatCompact(value);
+}
+
+/**
+ * A row as `holders --form` and `fn HDS --form` print it; the keys are the
+ * JSON contract. Numbers a report did not give stay null, and `status` is
+ * the disclosed stake, null when the report does not say.
+ */
+export function beneficialReportRow(row: BeneficialOwnerRow) {
+  const { filing } = row;
+  return {
+    filer: filing.filerName,
+    filerCik: filing.filerCik,
+    form: row.formLabel,
+    formType: filing.form,
+    kind: filing.kind,
+    amendment: filing.amendment,
+    amendmentNo: filing.amendmentNo,
+    percentOfClass: filing.percentOfClass,
+    previousPercent: filing.previousPercent ?? null,
+    changePoints: row.changePoints,
+    shares: filing.shares,
+    classTitle: filing.classTitle,
+    cusip: filing.cusip,
+    eventDate: filing.eventDate,
+    filingDate: filing.filingDate,
+    previousFilingDate: filing.previousFilingDate ?? null,
+    thirteenF: row.thirteenF?.label ?? null,
+    status: row.stake,
+    /** The route could not read every filing, so this may not be the filer's latest disclosure or its change may be off. */
+    provisional: filing.provisional === true,
+    parsedFrom: filing.source,
+    accessionNumber: filing.accessionNumber,
+    filingUrl: filing.filingUrl,
+    reportingPersons: filing.reportingPersons,
+  };
+}
+
+export type BeneficialReportRow = ReturnType<typeof beneficialReportRow>;