gloomberb 0.16.0 → 0.16.2

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/index.tsx

@@ -14,6 +14,7 @@ import {
 import { thirteenFHeadless } from "./headless";
 import { ThirteenFTickerPane } from "./signals-pane";
 import { isKnownNonUsListing } from "../../../utils/sec";
+import { isKnownMutualFund } from "../../../tickers/instrument-kind";
 
 
 function queryFromOptions(options?: PaneTemplateCreateOptions): string {
@@ -33,7 +34,7 @@ export const thirteenFModule: PluginModule = {
       order: 39,
       component: ThirteenFTickerPane,
       instruments: ["equity", "fund"],
-      isVisible: ({ ticker }) => !isKnownNonUsListing(ticker),
+      isVisible: ({ ticker, financials }) => !isKnownNonUsListing(ticker) && !isKnownMutualFund(ticker, financials),
     });
   },
 

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/headless.ts

@@ -25,10 +25,13 @@ import {
 import {
   loadHeadlessFinancials, loadHeadlessPriceHistory, loadHeadlessSymbols, resolveHeadlessInstrument,
 } from "../shared/headless-market-data";
+import { barHistoryFreshness, barResolutionFromDates, quoteFreshnessFields, REPORTED_DATA } from "../shared/report-freshness";
 
 export const financialStatementsHeadless: HeadlessPaneDefinition<"rows"> = {
   ...paneSchemas["financial-analysis-pane"],
   shape: "rows",
+  // Dated by the latest reported period; earlier periods are the statement's history.
+  freshness: { ...REPORTED_DATA, basis: "financial statements", observedKey: "date", oldest: null },
   description: "Annual or quarterly financial statement rows for one ticker: the income statement, balance sheet, cash flow, or a ratio table.",
   describe: ({ symbols, options }) => `Financial Statements | ${symbols[0]} | ${options.period} | ${options.statement}`,
   async load({ symbols, options }, ctx) {
@@ -206,6 +209,7 @@ export const quoteComparisonHeadless: HeadlessPaneDefinition<"rows"> = {
           ...(quote.priceBasis ? { priceBasis: quote.priceBasis } : {}),
           change: display.change, changePercent: display.changePercent,
           marketCap: quote.marketCap ?? null, updatedAt: quote.lastUpdated,
+          ...quoteFreshnessFields(quote),
         };
       }),
       unavailableSymbols: loaded.unavailableSymbols, errors: loaded.errors,
@@ -239,6 +243,8 @@ export const historicalPricesHeadless: HeadlessPaneDefinition<"rows"> = {
       };
     }).sort((left, right) => left.date.localeCompare(right.date));
     const notice = priceHistoryIntegrityNotice(rows.filter((row) => row.integrity).length);
-    return { rows, ...(notice ? { complete: false } : {}), unavailableSymbols: rows.some((row) => row.close !== null) ? [] : [symbol], metadata: { symbol, range, ...(notice ? { notices: [notice] } : {}) } };
+    // A bar history: dated by its last bar, stale once bars of its size stop arriving.
+    const freshness = { ...barHistoryFreshness(barResolutionFromDates(rows.map((row) => row.date))), observedKey: "date", oldest: null };
+    return { rows, freshness, ...(notice ? { complete: false } : {}), unavailableSymbols: rows.some((row) => row.close !== null) ? [] : [symbol], metadata: { symbol, range, ...(notice ? { notices: [notice] } : {}) } };
   },
 };

package/src/plugins/builtin/ticker-detail/index.tsx

@@ -85,6 +85,7 @@ export const tickerDetailModule: PluginModule = {
     },
     {
       id: "returns",
+      reportFreshness: { status: "not-a-feed", basis: "price history" },
       name: "Returns",
       icon: "R",
       component: ReturnsPane,

package/src/plugins/builtin/ticker-detail/overview/components.tsx

@@ -1,10 +1,10 @@
 import type { ReactNode } from "react";
-import { ExternalLinkText, usePaneLinkMenuEntry } from "../../../../components";
+import { ExternalLinkText, RangeTrack, usePaneLinkMenuEntry } from "../../../../components";
 import { t, tf } from "../../../../i18n";
 import { formatMarketPriceWithCurrency, liveQuoteFormatOptions, type MarketFormatOptions } from "../../../../market-data/market/format";
 import { colors, hoverBg, priceColor } from "../../../../theme/colors";
 import type { Quote } from "../../../../types/financials";
-import { Box, Text, useUiCapabilities } from "../../../../ui";
+import { Box, Text } from "../../../../ui";
 import { displayWidth, formatNumber, padTo, truncateToDisplayWidth } from "../../../../utils/format";
 import type { OverviewFunctionLink, PositionTableRow, StatField } from "./types";
 import { portfolioPnlLabel } from "../../portfolio-list/position-metrics";
@@ -28,57 +28,6 @@ interface PositionColumn {
   minPaneWidth?: number;
 }
 
-function RangeTrack({
-  barWidth,
-  markerIndex,
-  position,
-  markerColor,
-}: {
-  barWidth: number;
-  markerIndex: number;
-  position: number;
-  markerColor: string;
-}) {
-  // The desktop webview must not draw rules out of box-drawing glyphs.
-  if (useUiCapabilities().nativePaneChrome === true) {
-    return (
-      <Box
-        marginLeft={1}
-        marginRight={1}
-        width={barWidth}
-        height={1}
-        style={{ position: "relative", justifyContent: "center" }}
-      >
-        <Box style={{
-          position: "absolute",
-          left: 0,
-          right: 0,
-          height: "2px",
-          borderRadius: "1px",
-          backgroundColor: colors.border,
-        }} />
-        <Box style={{
-          position: "absolute",
-          left: `${position * 100}%`,
-          width: "8px",
-          height: "8px",
-          marginLeft: "-4px",
-          borderRadius: "50%",
-          backgroundColor: markerColor,
-        }} />
-      </Box>
-    );
-  }
-
-  return (
-    <Box marginLeft={1} marginRight={1} width={barWidth} flexDirection="row">
-      <Text fg={colors.border}>{"\u2500".repeat(markerIndex)}</Text>
-      <Text fg={markerColor}>{"\u25cf"}</Text>
-      <Text fg={colors.border}>{"\u2500".repeat(Math.max(0, barWidth - markerIndex - 1))}</Text>
-    </Box>
-  );
-}
-
 /** Cells a range row needs around its track: label, endpoints and the gaps between them. */
 export function rangeRowChrome(labelWidth: number, endpointWidth: number): number {
   return labelWidth + 1 + endpointWidth * 2 + 2;
@@ -136,7 +85,6 @@ export function CompactRangeBar({
   const lowText = formatMarketPriceWithCurrency(low, currency, endpointOptions);
   const highText = formatMarketPriceWithCurrency(high, currency, endpointOptions);
   const barWidth = Math.max(1, width - rangeRowChrome(shownLabelWidth, endpointWidth));
-  const markerIndex = Math.max(0, Math.min(barWidth - 1, Math.round(position * (barWidth - 1))));
 
   return (
     <Box flexDirection="row" height={1} width={width} flexShrink={0} overflow="hidden">
@@ -147,12 +95,9 @@ export function CompactRangeBar({
       <Box flexDirection="row" width={endpointWidth} flexShrink={0} justifyContent="flex-end" overflow="hidden">
         <Text fg={colors.text}>{lowText}</Text>
       </Box>
-      <RangeTrack
-        barWidth={barWidth}
-        markerIndex={markerIndex}
-        position={position}
-        markerColor={colors.textBright}
-      />
+      <Box marginLeft={1} marginRight={1} flexShrink={0}>
+        <RangeTrack width={barWidth} position={position} markerColor={colors.textBright} />
+      </Box>
       <Box width={endpointWidth} flexShrink={0} overflow="hidden">
         <Text fg={colors.text}>{highText}</Text>
       </Box>

package/src/plugins/builtin/ticker-detail/overview/model.ts

@@ -72,6 +72,7 @@ export function buildOverviewStats({
   baseCurrency,
   marketCapExchangeRates = new Map(),
   nextEarnings,
+  depositaryReceipt = false,
   today,
 }: {
   quote: Quote | undefined;
@@ -81,6 +82,8 @@ export function buildOverviewStats({
   toBase: CurrencyConverter;
   marketCapExchangeRates?: ReadonlyMap<string, number>;
   nextEarnings?: NextEarnings;
+  /** The listing is a depositary receipt, so its share count is in receipts. */
+  depositaryReceipt?: boolean;
   /** The listing's calendar day, YYYY-MM-DD; dates before it are left out. */
   today?: string;
 }): StatField[] {
@@ -105,7 +108,11 @@ export function buildOverviewStats({
     });
   }
   if (fundamentals?.sharesOutstanding) {
-    stats.push({ label: "Shares Out", value: formatCompact(fundamentals.sharesOutstanding) });
+    stats.push({
+      label: "Shares Out",
+      value: formatCompact(fundamentals.sharesOutstanding),
+      ...(depositaryReceipt ? { detail: ["ADR equivalent", "in ADRs"] } : {}),
+    });
   }
   if (finite(fundamentals?.floatShares) && fundamentals.floatShares > 0) {
     stats.push({ label: "Float", value: formatCompact(fundamentals.floatShares) });
@@ -122,7 +129,7 @@ export function buildOverviewStats({
     stats.push({ label: "EPS", value: money(fundamentals.eps, true) });
   }
   if (fundamentals?.pegRatio != null) {
-    stats.push({ label: "PEG", value: formatNumber(fundamentals.pegRatio, 2) });
+    stats.push({ label: "PEG", value: formatPriceEarnings(fundamentals.pegRatio, 2) });
   }
   // A report the payload still lists after its day has passed is not the next one.
   if (today && nextEarnings && ISO_DATE.test(nextEarnings.date) && nextEarnings.date >= today) {

package/src/plugins/builtin/ticker-detail/overview/pane.tsx

@@ -42,7 +42,7 @@ export function OverviewResearchTab({ width, focused }: TickerResearchTabProps)
       financials={financials}
       onOpenChart={paneId && !lockedToOneTab ? openChart : undefined}
       onOpenFunction={openFunction}
-      perpetuals={ticker ? <PerpEquityRow symbol={ticker.metadata.ticker} instrumentType={financials?.quote?.instrumentType ?? ticker.metadata.assetCategory} /> : undefined}
+      perpetuals={ticker ? <PerpEquityRow symbol={ticker.metadata.ticker} exchange={ticker.metadata.exchange} instrumentType={financials?.quote?.instrumentType ?? ticker.metadata.assetCategory} /> : undefined}
     />
   );
 }