gloomberb 0.16.1 → 0.16.2

package/src/plugins/builtin/research/relative-valuation-pane.tsx

@@ -1,4 +1,4 @@
-import { formatPriceEarnings } from "../../../utils/price-earnings";
+import { formatPriceEarnings, NOT_MEANINGFUL } from "../../../utils/price-earnings";
 import { useCallback, useMemo, useState } from "react";
 import { TextAttributes } from "../../../ui";
 import {
@@ -198,9 +198,9 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
       case "marketCap":
         return { text: formatCompact(row.marketCap ?? undefined, { fixedDecimals: true }), color: colors.textDim };
       case "trailingPE":
-        return { text: formatPriceEarnings(row.reportedMultiples.trailingPE), color: colors.text };
+        return { text: formatPriceEarnings(row.notMeaningful.trailingPE ? NOT_MEANINGFUL : row.reportedMultiples.trailingPE), color: colors.text };
       case "forwardPE":
-        return { text: formatPriceEarnings(row.reportedMultiples.forwardPE), color: colors.text };
+        return { text: formatPriceEarnings(row.notMeaningful.forwardPE ? NOT_MEANINGFUL : row.reportedMultiples.forwardPE), color: colors.text };
       case "evSales":
         return { text: formatNumber(row.evSales ?? undefined, 1), color: colors.text };
       case "fcfYield":

package/src/plugins/builtin/research-search/index.tsx

@@ -37,6 +37,7 @@ export const researchSearchPlugin: GloomPlugin = {
   panes: [
     {
       id: RESEARCH_SEARCH_PANE_ID,
+      reportFreshness: { status: "not-a-feed", basis: "search results" },
       name: "Research Search",
       icon: "RS",
       component: ResearchSearchPane,

package/src/plugins/builtin/revenue-breakdown/headless.ts

@@ -2,9 +2,11 @@ import type { RevenueBreakdownView } from "../../../api-client/revenue-breakdown
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchRevenueBreakdown } from "./client";
 import { quarterLabel, reportedSpan } from "./model";
+import { SEC_FILINGS } from "../shared/report-freshness";
 
 export const revenueBreakdownHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { ...SEC_FILINGS, basis: "10-Q and 10-K filings" },
   argument: {
     kind: "ticker",
     description: "SEC reporting issuer ticker.",

package/src/plugins/builtin/reverse-dcf/headless.ts

@@ -9,6 +9,7 @@ const implied = (value: ImpliedGrowth | null) => !value ? null : value.kind ===
 
 export const reverseDcfHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Ticker" },
+  freshness: { status: "not-a-feed", basis: "price and reported cash flows" },
   describe: (args) => `RDCF ${args.symbols[0] ?? ""}`,
   discovery: { screenshotReadiness: "live-dom", limitations: ["Trailing twelve-month free cash flow against the reported enterprise value."] },
   options: [
@@ -35,6 +36,7 @@ export const reverseDcfHeadless: HeadlessPaneDefinition<"bundle"> = {
           ...Object.fromEntries(row.implied.map((value, index) => [`t${index}`, implied(value)])) })) },
       ],
       complete: !inputs.stale && !inputs.error && !model.error,
+      ...(inputs.stale ? { freshness: { status: "stale" as const } } : {}),
       unavailableSymbols: model.implied ? [] : [instrument.symbol],
       errors: [inputs.error, model.error].filter((value): value is string => !!value),
       metadata: { currency: model.currency, discountRate, terminalGrowth: TERMINAL_GROWTH, discountRates: DISCOUNT_RATES,

package/src/plugins/builtin/risk-factors/headless.ts

@@ -1,8 +1,10 @@
 import type { HeadlessBundleSection, HeadlessPaneDefinition } from "../../../types/plugin";
 import { loadRiskReportWithClient, loadRiskReportsWithClient, type RiskReportsResult } from "./data";
+import { SEC_FILINGS } from "../shared/report-freshness";
 
 export const riskFactorsHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { ...SEC_FILINGS, basis: "10-K filings" },
   argument: { kind: "ticker", placeholder: "ticker", description: "Company symbol." },
   options: [
     { key: "year", type: "string", defaultValue: "latest", description: "Filing year (for example 2025), or latest discovered report." },

package/src/plugins/builtin/scanner/flow-history.ts

@@ -5,6 +5,7 @@ import {
   type ScannerFlowHistoryPage,
   type ScannerFlowHistoryQuery,
 } from "../../../api-client";
+import { signalWithTimeout } from "../../../utils/async-deadline";
 import { flowHistorySearch, mergeFlowRows } from "./flow-model";
 
 export interface FlowHistoryState {
@@ -21,20 +22,8 @@ export type FlowHistoryLoader = (
   signal: AbortSignal,
 ) => Promise<ScannerFlowHistoryPage>;
 
-/** Aborts on the caller's signal or after `ms`; AbortSignal.any is too new for older system WebViews. */
-function withTimeout(signal: AbortSignal, ms: number): AbortSignal {
-  const controller = new AbortController();
-  const abort = () => controller.abort();
-  if (signal.aborted) abort();
-  else signal.addEventListener("abort", abort, { once: true });
-  const timeout = AbortSignal.timeout(ms);
-  if (timeout.aborted) abort();
-  else timeout.addEventListener("abort", abort, { once: true });
-  return controller.signal;
-}
-
 const loadRecordedPrints: FlowHistoryLoader = (query, signal) =>
-  apiClient.getScannerFlowHistory(flowHistorySearch(query), withTimeout(signal, 20_000));
+  apiClient.getScannerFlowHistory(flowHistorySearch(query), signalWithTimeout(signal, 20_000));
 
 function emptyHistory(key: string): FlowHistoryState {
   return { key, events: [], hasMore: true, loading: false, error: null };

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

@@ -7,6 +7,7 @@ import type {
 import type {
   HeadlessPaneApiClient,
   HeadlessPaneDefinition,
+  HeadlessPaneFreshness,
   HeadlessPaneLoadArgs,
   HeadlessPaneOptionDef,
   HeadlessSnapshotResult,
@@ -88,6 +89,17 @@ export function loadHiloSnapshot(
   return loadScannerSnapshot<ScannerHiloPayload>(client, "hilo", signal, timeoutMs);
 }
 
+/**
+ * The scanner says which instance served it, real-time or the delayed one free
+ * accounts get, and whether it is running: a closed session's scan is final,
+ * and a degraded one may have fallen behind.
+ */
+function scannerFreshness(payload: Pick<ScannerHiloPayload, "access" | "delayMinutes" | "status">): HeadlessPaneFreshness {
+  if (payload.status === "closed") return { status: "not-a-feed", basis: "closed session" };
+  if (payload.status === "degraded") return { status: "stale" };
+  return payload.access === "realtime" ? { status: "live" } : { status: "delayed", delayMinutes: payload.delayMinutes };
+}
+
 function projectHiloSnapshot(
   payload: ScannerHiloPayload,
   minPrice: HiloMinPrice,
@@ -99,6 +111,7 @@ function projectHiloSnapshot(
     asOf: new Date(payload.asOf).toISOString(),
     items: [...lows, ...highs],
     ...(payload.status === "degraded" ? { errors: ["Scanner feed degraded"] } : {}),
+    freshness: scannerFreshness(payload),
     metadata: {
       ...(payload.access === "delayed" ? { notices: [`Delayed ${payload.delayMinutes} minutes`] } : {}),
       status: payload.status,
@@ -214,6 +227,7 @@ function projectFlowSnapshot(
     asOf: new Date(payload.asOf).toISOString(),
     items: events.map((event) => ({ ...event })),
     ...(payload.status === "degraded" ? { errors: ["Scanner feed degraded"] } : {}),
+    freshness: scannerFreshness(payload),
     metadata: {
       status: payload.status,
       access: payload.access,

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

@@ -7,6 +7,8 @@ const percent = (value: unknown) => typeof value === "number" ? `${(value * 100)
 
 export const seasonalityHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Ticker" },
+  // Dated by the month of its last monthly close.
+  freshness: { status: "not-a-feed", basis: "monthly closes", maxAgeMinutes: 45 * 24 * 60 },
   describe: (args) => `SEAS ${args.symbols[0] ?? ""}`,
   discovery: { screenshotReadiness: "live-dom", limitations: ["Local-price closes; dividends and FX are excluded."] },
   options: [

package/src/plugins/builtin/sec/command-bar-search.ts

@@ -116,6 +116,19 @@ function requestSecFilingFocus(symbol: string, accessionNumber: string): void {
   for (const listener of listeners.values()) listener(accessionNumber);
 }
 
+/**
+ * Opens a filing in the SEC pane for `symbol`, reusing an open one, the way a
+ * filing row in the command bar does.
+ */
+export function openSecFilingInPane(
+  ctx: Pick<GloomPluginContext, "createPaneFromTemplate">,
+  symbol: string,
+  accessionNumber: string,
+): void {
+  requestSecFilingFocus(symbol, accessionNumber);
+  void ctx.createPaneFromTemplate(SEC_TEMPLATE_ID, { symbol });
+}
+
 export function useSecFilingFocusRequest(symbol: string | null | undefined, onFocus: FocusListener): void {
   const [view] = useState(() => ({}));
   useEffect(() => {
@@ -173,10 +186,7 @@ function filingRow(
     badge: filing.form.replace(/\s+/g, "").slice(0, 6),
     right: filingDateLabel(filedAt(filing), now),
     keywords: [ticker, filing.form],
-    execute: () => {
-      requestSecFilingFocus(ticker, filing.accessionNumber);
-      void ctx.createPaneFromTemplate(SEC_TEMPLATE_ID, { symbol: ticker });
-    },
+    execute: () => openSecFilingInPane(ctx, ticker, filing.accessionNumber),
   };
 }
 

package/src/plugins/builtin/sec/filing-content.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useResolvedEntryValue, useSecFilingContent } from "../../../market-data/hooks";
+import { useSecFilingContent } from "../../../market-data/hooks";
 import { getSharedMarketDataCoordinator, resolveEntryValue } from "../../../market-data/coordinator";
+import type { QueryEntry } from "../../../market-data/result-types";
 import type { SecFilingDocument, SecFilingItem } from "../../../types/data-provider";
 import { documentContentTarget, isInlineExhibitDocument } from "./filing-documents";
 
@@ -14,6 +15,22 @@ interface ScopedFilingContentCache {
 const EMPTY_CONTENT_CACHE = new Map<string, string | null>();
 const EMPTY_ERRORS = new Map<string, string>();
 
+/** What a finished content entry holds, or null while it is still loading. */
+function settledFilingContent(
+  entry: QueryEntry<string | null> | null | undefined,
+): { content: string | null; error: string | null } | null {
+  if (!entry) return null;
+  const resolved = resolveEntryValue(entry);
+  const settled = entry.phase === "ready"
+    || entry.phase === "error"
+    || (entry.phase === "refreshing" && resolved !== null);
+  if (!settled) return null;
+  return {
+    content: entry.phase === "error" ? null : resolved,
+    error: entry.error?.reasonCode === "NO_DATA" ? null : entry.error?.message ?? null,
+  };
+}
+
 export function buildInlineFilingContentTargets(
   filing: SecFilingItem | null | undefined,
   documents: readonly SecFilingDocument[],
@@ -69,28 +86,36 @@ export function useSecFilingContentCache({
     [contentCache, targets],
   );
   const contentEntry = useSecFilingContent(nextTarget);
-  const resolvedContent = useResolvedEntryValue(contentEntry);
 
   useEffect(() => {
     if (!nextTarget) return;
-    const phase = contentEntry?.phase;
-    const settled = phase === "ready"
-      || phase === "error"
-      || (phase === "refreshing" && resolvedContent !== null);
-    if (!settled) return;
-    const key = nextTarget.accessionNumber;
-    const content = phase === "error" ? null : resolvedContent;
-    const error = contentEntry?.error?.reasonCode === "NO_DATA" ? null : contentEntry?.error?.message;
+    const first = settledFilingContent(contentEntry);
+    if (!first) return;
+    const coordinator = getSharedMarketDataCoordinator();
     setState((current) => {
-      if (current.scopeKey !== scopeKey || current.values.has(key)) return current;
-      return {
-        scopeKey,
-        values: new Map(current.values).set(key, content),
-        errors: error ? new Map(current.errors).set(key, error) : current.errors,
-        retryingKey: current.retryingKey,
+      if (current.scopeKey !== scopeKey) return current;
+      let values = current.values;
+      let errors = current.errors;
+      const record = (key: string, settled: { content: string | null; error: string | null }) => {
+        if (values === current.values) values = new Map(values);
+        values.set(key, settled.content);
+        if (!settled.error) return;
+        if (errors === current.errors) errors = new Map(errors);
+        errors.set(key, settled.error);
       };
+      if (!values.has(nextTarget.accessionNumber)) record(nextTarget.accessionNumber, first);
+      // Content the coordinator already holds (a pane reopened, a ticker
+      // visited again) is taken in this same update. Taken one target per
+      // render, each one would expose the next, and a few dozen filings chain
+      // that many renders in a row, past React's limit of 50 nested updates.
+      for (const target of targets) {
+        if (values.has(target.accessionNumber)) continue;
+        const settled = settledFilingContent(coordinator?.getSecContentEntry(target.accessionNumber));
+        if (settled) record(target.accessionNumber, settled);
+      }
+      return values === current.values ? current : { ...current, values, errors };
     });
-  }, [contentEntry?.phase, contentEntry?.error, nextTarget, resolvedContent, scopeKey]);
+  }, [contentEntry, nextTarget, scopeKey, targets]);
 
   // Successful accession content is immutable. Retry only selected documents
   // that failed or had no readable content, preserving the sequential queue.

package/src/plugins/builtin/sec/forms.ts

@@ -52,3 +52,15 @@ export function filterFilingsByForms(filings: readonly SecFilingItem[], forms: r
     return accepted.has(form) || (form.endsWith("/A") && accepted.has(form.slice(0, -2)));
   });
 }
+
+/** A form as typed or filed, without punctuation or the `SC`/`SCHEDULE` prefix of ownership schedules. */
+function compactFilingForm(form: string): string {
+  return form.toUpperCase().replace(/[^A-Z0-9]/g, "").replace(/^(?:SCHEDULE|SC)(?=\d)/, "");
+}
+
+/** `13D` matches SC 13D, SCHEDULE 13D and their amendments; `10-K` matches 10-K and 10-K/A. */
+export function filingFormMatches(form: string, wanted: string): boolean {
+  const target = compactFilingForm(wanted);
+  const actual = compactFilingForm(form);
+  return !!target && (actual === target || actual === `${target}A`);
+}

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

@@ -8,6 +8,7 @@ import type { SecFilingItem } from "../../../types/data-provider";
 import { loadSecFilings } from "./client";
 import { filterFilingsByForms, SEC_FILING_FETCH_LIMIT } from "./forms";
 import { buildSecFilingRows, secFilingIssuers, SEC_ACCEPTANCE_NOTE } from "./model";
+import { SEC_FILINGS } from "../shared/report-freshness";
 
 const SEC_COLUMNS: HeadlessPaneColumn[] = [
   {
@@ -49,6 +50,7 @@ export function createSecHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    freshness: { ...SEC_FILINGS, observedKey: "acceptedAt" },
     argument: {
       kind: "ticker",
       placeholder: "ticker",

package/src/plugins/builtin/sectors/client.ts

@@ -87,6 +87,7 @@ export async function loadSectorRows(
         quoteIssue,
         lastReportedPrice,
         quoteUpdatedAt: quote && Number.isFinite(quote.lastUpdated) ? quote.lastUpdated : null,
+        quoteDataSource: quote?.dataSource,
         changePercent,
         return1M: month?.value ?? null,
         return1Y: year?.value ?? null,

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

@@ -32,6 +32,8 @@ export function projectSectorRows(
     loading: false,
     quoteUnavailable: !byEtf.get(definition.etf) || byEtf.get(definition.etf)?.quoteUnavailable === true,
     quoteSessionDate: byEtf.get(definition.etf)?.quoteSessionDate ?? null,
+    quoteUpdatedAt: byEtf.get(definition.etf)?.quoteUpdatedAt ?? null,
+    quoteDataSource: byEtf.get(definition.etf)?.quoteDataSource,
     quoteIssue: byEtf.get(definition.etf)?.quoteIssue ?? null,
     lastReportedPrice: byEtf.get(definition.etf)?.lastReportedPrice ?? null,
     returnIntegrity: byEtf.get(definition.etf)?.returnIntegrity ?? {},
@@ -58,6 +60,8 @@ export function createSectorsHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    // Dated by each ETF's quote; the shared session date is the returns' end, not an observation.
+    freshness: { observedKey: "quoteUpdatedAt" },
     argument: { kind: "none" },
     options: [{
       key: "collection",
@@ -81,7 +85,11 @@ export function createSectorsHeadless(
       return {
         unavailableSymbols: unavailableSymbols.length > 0 ? unavailableSymbols : undefined,
         errors: rows.flatMap((row) => sectorRowIssues(row).map((issue) => `${row.etf}: ${issue}.`)),
-        rows: rows.map((row) => ({ ...row })),
+        // The quote behind each row says whether it is real-time or delayed, and how current it is.
+        rows: rows.map(({ quoteDataSource, ...row }) => ({
+          ...row,
+          ...(quoteDataSource === "live" || quoteDataSource === "delayed" ? { dataSource: quoteDataSource } : {}),
+        })),
         metadata: {
           collection: collectionId,
           available: outcomes.filter((outcome) => outcome.row).length,

package/src/plugins/builtin/sectors/sector-model.ts

@@ -25,6 +25,8 @@ export interface SectorRow extends SectorDef {
   lastReportedPrice?: number | null;
   /** When the snapshot quote behind `price` was stamped; a live quote must be at least as new. */
   quoteUpdatedAt?: number | null;
+  /** Whether that quote is real-time or delayed, for the report's freshness line. */
+  quoteDataSource?: Quote["dataSource"];
   returnIntegrity?: Partial<Record<SectorReturnRange, PriceHistoryIntegrity>>;
   returnAsOfDate?: string | null;
   return1MStartDate?: string | null;

package/src/plugins/builtin/shared/crypto-pair.ts

@@ -0,0 +1,14 @@
+/**
+ * The coin a USD crypto pair names: BTC-USD gives BTC. CME lists bitcoin and
+ * ether futures, but BTC and ETH are also US equity tickers (Grayscale's mini
+ * trusts), so a futures function that falls back to the ticker under the
+ * cursor reads a bare symbol as the equity and only a pair as the coin.
+ */
+export function cryptoPairCoin(ticker: string): string | null {
+  return /^([A-Z0-9]{2,10})-USD$/.exec(ticker.trim().toUpperCase())?.[1] ?? null;
+}
+
+/** `BTC=F`: the spelling of a futures contract, which no equity shares. */
+export function isFuturesSymbol(ticker: string): boolean {
+  return ticker.trim().toUpperCase().endsWith("=F");
+}

package/src/plugins/builtin/shared/locked-rows.tsx

@@ -20,7 +20,7 @@ export function Blurred({ children }: { children: ReactNode }) {
 export function UpgradeLabel({ text, onPress, role }: { text: string; onPress: () => void; role?: string }) {
   const colors = useThemeColors();
   return (
-    <Box flexDirection="row" gap={1} onMouseDown={onPress} data-gloom-role={role}>
+    <Box flexDirection="row" gap={1} onMouseDown={onPress} data-gloom-role={role} data-gloom-ui="pro-lock">
       <Icon name="lock" size={11} color={colors.textBright} />
       <Text fg={colors.textBright}>{text}</Text>
     </Box>

package/src/plugins/builtin/shared/report-freshness.ts

@@ -0,0 +1,57 @@
+import type { HeadlessPaneFreshness } from "../../../types/headless";
+import type { Quote } from "../../../types/financials";
+import { isQuoteStaleForCurrentSession } from "../../../market-data/quotes/freshness";
+
+/**
+ * Freshness declarations shared by built-in reports. Each `fn` report ends
+ * with the source, as-of and status line these feed; see
+ * docs/usage.md#how-current-a-report-is.
+ */
+
+/** Analyses over end-of-day history: not a feed, but stale once the closes stop arriving. */
+export const DAILY_CLOSES: HeadlessPaneFreshness = { status: "not-a-feed", basis: "daily closes", cadence: "daily" };
+
+const DAY_MINUTES = 24 * 60;
+
+/**
+ * Price bars: a history, not a feed, stale once the bars stop arriving for
+ * their size. Intraday and daily bars follow the US trading sessions; a
+ * weekly or monthly bar is dated by the start of its period.
+ */
+export function barHistoryFreshness(resolution: string | null | undefined): HeadlessPaneFreshness {
+  if (resolution === "1wk") return { status: "not-a-feed", basis: "weekly bars", maxAgeMinutes: 14 * DAY_MINUTES };
+  if (resolution === "1mo") return { status: "not-a-feed", basis: "monthly bars", maxAgeMinutes: 45 * DAY_MINUTES };
+  if (resolution === "1d") return DAILY_CLOSES;
+  return { status: "not-a-feed", basis: "intraday bars", cadence: "daily" };
+}
+
+/** The bar size of a dated history, read from the gap between its last two bars. */
+export function barResolutionFromDates(dates: readonly (string | number | Date)[]): "1d" | "1wk" | "1mo" {
+  const times = dates.slice(-2).map((date) => new Date(date).getTime());
+  const gapDays = times.length === 2 && times.every(Number.isFinite) ? (times[1]! - times[0]!) / 86_400_000 : 1;
+  return gapDays >= 25 ? "1mo" : gapDays >= 6 ? "1wk" : "1d";
+}
+
+/** Company filings read from EDGAR. Old filings are not stale; there is no schedule to miss. */
+export const SEC_FILINGS: HeadlessPaneFreshness = { source: "SEC EDGAR", status: "not-a-feed", basis: "filed data", oldest: null };
+
+/** Places and listings that change only when someone edits them: venues, ports, pipelines. */
+export const REFERENCE_DATA: HeadlessPaneFreshness = { status: "not-a-feed", basis: "reference data", oldest: null };
+
+/** Company fundamentals, estimates and calendars: reported figures, not a feed. */
+export const REPORTED_DATA: HeadlessPaneFreshness = { status: "not-a-feed", basis: "reported data" };
+
+/**
+ * The standard freshness fields of one quote, spread into a report row so the
+ * report can say whether that row is live, delayed or stale for its session.
+ */
+export function quoteFreshnessFields(
+  quote: Quote | null | undefined,
+  now = Date.now(),
+): { dataSource?: "live" | "delayed"; stale?: boolean } {
+  if (!quote) return {};
+  return {
+    ...(quote.dataSource === "live" || quote.dataSource === "delayed" ? { dataSource: quote.dataSource } : {}),
+    stale: isQuoteStaleForCurrentSession(quote, now),
+  };
+}

package/src/plugins/builtin/shared/research-cells.tsx

@@ -1,4 +1,5 @@
 import type { DataTableCell, DataTableColumn } from "../../../components";
+import { RatioBar } from "../../../components/ui/ratio-bar";
 import { SplitBar } from "../../../components/ui/split-bar";
 import { blendHex } from "../../../theme/colors";
 import type { ThemeColors } from "../../../theme/colors";
@@ -39,21 +40,15 @@ export function listingCell(key: string | null | undefined, colors: ThemeColors,
  * so the eye compares lengths down the column. The bar gives way first in a
  * narrow column; the number never does.
  */
-export function shareCell(text: string, ratio: number | null, width: number, colors: ThemeColors, selected: boolean, desktop: boolean,
+export function shareCell(text: string, ratio: number | null, width: number, colors: ThemeColors, selected: boolean,
   color = blendHex(colors.bg, colors.borderFocused, 0.6)): DataTableCell {
   const textCells = displayWidth(text);
   const barCells = width - textCells - 1;
   if (ratio == null || !(ratio > 0) || barCells < 4) return { text, color: selected ? colors.selectedText : colors.text };
-  const fill = Math.max(0, Math.min(1, ratio));
-  const ink = selected ? colors.selectedText : color;
-  // The desktop draws the bar on a faint track; terminal cells draw the length alone, at half-cell steps,
+  // The desktop draws the bar on a faint track; terminal cells draw the length alone,
   // since a track of block cells would join the rows above and below into one wall.
-  const units = Math.max(1, Math.round(fill * barCells * 2));
   return { text, content: <Box flexDirection="row" height={1} width={width} overflow="hidden" alignItems="center">
-    <Box width={barCells} flexShrink={0} flexDirection="row" alignItems="center">
-      {desktop ? <SplitBar width={barCells} parts={[{ id: "share", value: fill, color: ink }, { id: "rest", value: 1 - fill, color: blendHex(colors.bg, color, 0.2) }]} />
-        : <Text fg={ink}>{`${"█".repeat(Math.floor(units / 2))}${units % 2 ? "▌" : ""}`}</Text>}
-    </Box>
+    <RatioBar ratio={ratio} width={barCells} color={selected ? colors.selectedText : color} track />
     <Box flexGrow={1} justifyContent="flex-end"><Text fg={selected ? colors.selectedText : colors.text}>{` ${text}`}</Text></Box>
   </Box> };
 }

package/src/plugins/builtin/short-interest/headless.ts

@@ -58,6 +58,8 @@ export function createShortInterestHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    // Settled twice a month and published about a week later; a month without one has missed it.
+    freshness: { source: "FINRA", status: "not-a-feed", basis: "twice-monthly settlement", observedKey: "settlementDate", oldest: null, maxAgeMinutes: 30 * 24 * 60 },
     argument: {
       kind: "ticker",
       placeholder: "ticker",

package/src/plugins/builtin/short-interest/watch-headless.ts

@@ -10,6 +10,7 @@ const signedPercent = (value: unknown) =>
 
 export const shortWatchHeadless: HeadlessPaneDefinition<"rows"> = {
   shape: "rows",
+  freshness: { source: "FINRA", status: "not-a-feed", basis: "twice-monthly settlement", observedKey: "settlementDate", maxAgeMinutes: 30 * 24 * 60 },
   argument: { kind: "symbol-list", maximum: SHORT_WATCH_LIMIT, description: "US tickers; the pane defaults to your portfolios and watchlists." },
   options: [],
   describe: "Short squeeze watch",

package/src/plugins/builtin/short-volume/headless.ts

@@ -4,6 +4,7 @@ import { volumePercent, volumePointStatus, volumeQuantity } from "./model";
 
 export const shortVolumeHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "US equity ticker.", placeholder: "ticker" },
+  freshness: { source: "FINRA", status: "not-a-feed", basis: "daily short volume", cadence: "daily", observedKey: "date", oldest: null },
   discovery: { aliases: ["SIV"], dataRequirements: ["Gloom Cloud FINRA daily short volume"],
     limitations: ["Regular-session off-exchange volume, not short interest", "Short volume includes exempt volume", "One-year history depends on source discovery and ingestion"] },
   options: [

package/src/plugins/builtin/social-mentions/headless.ts

@@ -5,6 +5,7 @@ import { socialCount, socialDayRows, socialRatio, socialStance, topPostCell } fr
 
 export const socialMentionsHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Ticker with a searchable cashtag (up to six letters and digits).", placeholder: "ticker" },
+  freshness: { source: "X posts", status: "not-a-feed", basis: "daily post counts" },
   discovery: { aliases: ["BUZZ"], dataRequirements: ["Gloom Cloud X mention history"],
     limitations: ["Daily $cashtag posts on X in UTC days, spam included", "Top posts and stance cover days that were looked up", "Views exist from 2022-12-22"] },
   options: [

package/src/plugins/builtin/supply-chain/headless.ts

@@ -4,6 +4,7 @@ import { fetchSupplyChain } from "./client";
 import { evidenceLabel, isUnconfirmed, matchesSupplyOptions, supplyOptions, trustTier } from "./trust";
 import { fetchSupplyGraph, graphOptions } from "./graph-client";
 import { exposureLabel, pathLabel } from "./graph-model";
+import { supplyRoleCounts } from "./model";
 
 const pathColumns = [
   { key: "route", header: "Route" }, { key: "hops", header: "Hops" },
@@ -54,6 +55,7 @@ function graphReport(data: GraphPayload, target: string): HeadlessBundleResult {
 
 export const supplyChainHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { source: "Company filings, calls and news", status: "not-a-feed", basis: "disclosed relationships" },
   argument: { kind: "ticker", description: "Company ticker, exchange-qualified ticker, or id:<entity-id>.", placeholder: "ticker" },
   discovery: { aliases: ["SPLC", "SUPPLY"], dataRequirements: ["Gloom Cloud relationship evidence (Pro with free preview)"],
     limitations: ["Filings, company announcements, earnings calls and news where evidence is available globally", "Japan filings await an API key and Taiwan report ingestion is disabled", "English glosses are machine translations, separate from original evidence", "Absence is not proof of no relationship",
@@ -87,6 +89,9 @@ export const supplyChainHeadless: HeadlessPaneDefinition<"bundle"> = {
     }
     const options = supplyOptions(args.options.tiers);
     const data = await fetchSupplyChain(args.symbols[0]!, ctx.apiClient, options);
+    // The pane's figures, per tab: Table shows one direction, Flow both.
+    const figures = (key: "counterparties" | "locked") => Object.fromEntries(([["says", ["says"]], ["names", ["names"]], ["flow", ["says", "names"]]] as const)
+      .map(([scope, views]) => [scope, Object.fromEntries(supplyRoleCounts(data, views, options).filter((entry) => entry[key] > 0).map((entry) => [entry.role, entry[key]]))]));
     return { complete: !data.truncated, errors: data.truncated ? ["Additional relationships need Gloom Pro"] : [],
       sections: (["says", "names"] as const).flatMap((view) => [false, true].map((leads) => ({ title: `${view === "says" ? `${data.symbol} says` : `Names ${data.symbol}`}${leads ? " | Unconfirmed" : ""}`,
         rows: data[view].filter((row) => matchesSupplyOptions(row, options) && isUnconfirmed(row) === leads).map((row) => ({ counterparty: row.counterparty.name, ticker: row.counterparty.ticker, aggregate: row.counterparty.aggregate, role: row.role, direction: row.direction,
@@ -100,6 +105,7 @@ export const supplyChainHeadless: HeadlessPaneDefinition<"bundle"> = {
           quote: row.quote, quoteLanguage: row.quoteLanguage, quoteGloss: row.quoteGloss ?? null, quoteGlossKind: row.quoteGloss ? "machine_translation" : null,
           quoteMatchMode: row.quoteMatchMode, sourceUrl: row.filingUrl, filingUrl: row.filingUrl, sectionRef: row.sectionRef ?? null, sourceAttribution: row.sourceAttribution ?? null,
           evidence: row.evidence ?? [] })) })).filter((section) => section.rows.length > 0)),
-      metadata: { symbol: data.symbol, asOf: data.asOf, counts: data.counts, tierCounts: data.tierCounts, tiers: options.tiers, disclaimer: data.disclaimer } };
+      metadata: { symbol: data.symbol, asOf: data.asOf, counterparties: figures("counterparties"), locked: figures("locked"),
+        counts: data.counts, tierCounts: data.tierCounts, tiers: options.tiers, disclaimer: data.disclaimer } };
   },
 };

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

@@ -5,6 +5,11 @@ import { supplyChainCache } from "./client";
 import { supplyChainHeadless } from "./headless";
 import { SupplyChainPane } from "./pane";
 
+/** What another pane can open SPLC on: a Graph or Path view, its target and its query, as `graphOptions` reads them. */
+const OPENING_SETTINGS = ["tab", "to", "depth", "direction", "roles", "tiers"];
+const openingSettings = (values: Record<string, string> = {}) =>
+  Object.fromEntries(OPENING_SETTINGS.flatMap((key) => values[key] ? [[key, values[key]]] : []));
+
 export const supplyChainModule: PluginModule = {
   setup(ctx) { supplyChainCache.attach(ctx.persistence); graphCache.attach(ctx.persistence); },
   dispose() { supplyChainCache.reset(); graphCache.reset(); },
@@ -13,5 +18,9 @@ export const supplyChainModule: PluginModule = {
     tickerFollower: true, tableExport: true, headless: supplyChainHeadless }],
   paneTemplates: [{ ...createTickerSurfacePaneTemplate({ id: "supply-chain-pane", paneId: "supply-chain", label: "Supply Chain",
     description: "Pro global supply chain evidence from filings, company announcements, calls and news, with trust tiers, original quotes, native units, four-hop graphs, ranked paths and a free preview.",
-    keywords: ["supply", "supply chain", "suppliers", "customers", "concentration", "filings", "earnings calls", "news", "evidence", "global", "Korea", "Japan", "Taiwan", "graph", "paths", "Pro"], shortcut: "SPLC", shortcutAliases: ["SUPPLY"] }), headless: supplyChainHeadless }],
+    keywords: ["supply", "supply chain", "suppliers", "customers", "concentration", "filings", "earnings calls", "news", "evidence", "global", "Korea", "Japan", "Taiwan", "graph", "paths", "Pro"], shortcut: "SPLC", shortcutAliases: ["SUPPLY"],
+    settings: (_symbol, _context, options) => openingSettings(options?.values),
+    // A route opened from another pane gets a pane of its own, so the company's SPLC keeps its view.
+    viewKey: (_symbol, _context, options) => options?.values?.to ? `${options.values.tab ?? "graph"}:${options.values.to}` : undefined,
+  }), headless: supplyChainHeadless }],
 };

package/src/plugins/builtin/supply-chain/model.ts

@@ -1,7 +1,7 @@
-import type { SupplyRole, SupplyRow } from "../../../api-client/supply-chain";
+import type { SupplyChainPayload, SupplyOptions, SupplyRole, SupplyRow } from "../../../api-client/supply-chain";
 import { SERIES_COLORS } from "../../../time-series/resolve";
 import { revenueAmount } from "../revenue-breakdown/model";
-import { activeRelationship, corroborationLabel, evidenceDate, evidenceLabel, isUnconfirmed, trustTier } from "./trust";
+import { activeRelationship, corroborationLabel, evidenceDate, evidenceLabel, isUnconfirmed, matchesSupplyOptions, trustTier } from "./trust";
 
 /** One colour per role from the shared series palette, the same in the table, the flow and the evidence. */
 export const ROLE_COLORS: Record<SupplyRole, string> = {
@@ -64,6 +64,31 @@ export function counterpartyName(row: SupplyRow): string {
   return member ? `${member.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/\s*\(undisclosed\)/gi, "")} (undisclosed)` : name;
 }
 export const roleLabel = (role: SupplyRole) => role[0]!.toUpperCase() + role.slice(1);
+
+const SUPPLY_ROLE_ORDER: readonly SupplyRole[] = ["customer", "supplier", "partner", "competitor", "investee"];
+export interface SupplyRoleCount { role: SupplyRole; counterparties: number; locked: number }
+
+/**
+ * The one count behind the figures over the table, the flow and the headless
+ * report: per role, the companies the reader can see, each counted once
+ * however many disclosures name it (the flow draws one card per counterparty
+ * and role). Unconfirmed leads, inactive links and cohort groups are not
+ * counterparties. The server's counts are disclosures, not companies, so what
+ * a free preview withholds is reported apart as locked disclosures rather
+ * than added to the companies.
+ */
+export function supplyRoleCounts(data: Pick<SupplyChainPayload, "says" | "names" | "counts">, views: readonly ("says" | "names")[], options: Required<SupplyOptions>): SupplyRoleCount[] {
+  return SUPPLY_ROLE_ORDER.map((role) => {
+    const companies = new Set<string>();
+    let locked = 0;
+    for (const view of views) {
+      const rows = data[view].filter((row) => row.role === role);
+      for (const row of rows) if (!row.counterparty.aggregate && !isUnconfirmed(row) && matchesSupplyOptions(row, options)) companies.add(row.counterparty.id);
+      locked += Math.max(0, data.counts[view][role] - rows.length);
+    }
+    return { role, counterparties: companies.size, locked };
+  }).filter((entry) => entry.counterparties > 0 || entry.locked > 0);
+}
 export const percentage = (row: SupplyRow) => row.pctOfRevenue === null || trustTier(row) !== 1 || isUnconfirmed(row) || !activeRelationship(row) ? "--" : `${Number(row.pctOfRevenue.toFixed(2))}% ${row.pctScope ? "scoped " : ""}${row.pctBasis ?? ""}`;
 export const dollars = (row: SupplyRow) => row.usd === null ? "--" : `${row.usdBasis === "derived" ? "≈ " : ""}$${revenueAmount(row.usd)} ${row.usdBasis}`;
 const scaleLabel = (scale: number) => scale === 1 ? "" : scale === 1_000 ? " thousand" : scale === 1_000_000 ? " million" : scale === 1_000_000_000 ? " billion" : ` ×${scale.toLocaleString("en-US")}`;