gloomberb 0.18.2 → 0.18.4

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

@@ -5,9 +5,10 @@ import { isAccessDenied } from "../../../api-client/errors";
 import { usePlanAccess } from "../../../api-client/plan-access";
 import type { SupplyChainPayload, SupplyOptions, SupplyRole, SupplyRow, SupplyTierFilter } from "../../../api-client/supply-chain";
 import {
-  Badge, buildSectionedRows, DataTableView, EmptyState, isSectionedItemRow, PageStackView, renderSectionedRowHeader, PaneStatusBody, QueryBar, StatGrid, statGridRows, usePaneNoticeFooter,
-  usePaneStatusFooter, usePaneTabs, type DataTableCell, type DataTableColumn, type PaneHint, type SectionedRow, type StatItem,
+  Badge, buildSectionedRows, ChartTableHeader, DataTableView, EmptyState, formatPercentAxis, isSectionedItemRow, PageStackView, renderSectionedRowHeader, PaneStatusBody, QueryBar, StatGrid,
+  statGridRows, useChartTableSelection, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, type DataTableCell, type DataTableColumn, type PaneHint, type SectionedRow, type StatItem,
 } from "../../../components";
+import { staticSeries } from "../../../components/chart/static/series";
 import { ClippedText } from "../../../components/ui/display";
 import { RatioBar } from "../../../components/ui/ratio-bar";
 import { getTableWidth } from "../../../components/ui/table-layout";
@@ -30,7 +31,7 @@ import { SupplyFlow } from "./flow";
 import { SupplyGraphPane } from "./graph-pane";
 import { entityTicker } from "./graph-model";
 import {
-  cellText, counterpartyKind, counterpartyKindLabel, counterpartyLabel, counterpartyName, disclosedValue, earlierRows, lockedDisclosures, nativeValue, percentage, ROLE_COLORS, roleLabel,
+  cellText, counterpartyKind, counterpartyKindLabel, counterpartyLabel, counterpartyName, disclosedValue, earlierRows, fitShareBasis, receivablesConcentration, lockedDisclosures, nativeValue, percentage, ROLE_COLORS, roleLabel,
   shareParts, sortRows, supplyPreviewNote, supplyRoleCounts, type SupplySort,
 } from "./model";
 import { RowEvidence } from "./row-evidence";
@@ -38,37 +39,58 @@ import { evidenceDate, evidenceLabel, isUnconfirmed, matchesSupplyOptions, suppl
 
 type Item = { kind: "edge"; row: SupplyRow } | { kind: "locked"; id: string };
 const itemId = (item: Item) => item.kind === "edge" ? item.row.id : item.id;
+const rowId = (row: SupplyRow) => row.id;
+const formatShare = (value: number) => `${Number(value.toFixed(2))}%`;
 const ROLE_PLURALS: Record<SupplyRole, string> = { customer: "Customers", supplier: "Suppliers", partner: "Partners", competitor: "Competitors", investee: "Investees" };
 /** A share figure is at most five cells (`99.9%`, `100%`), right-aligned so the bars line up. */
 const SHARE_FIGURE_CELLS = 5;
-/** Bar, gap and figure: below this a share cell shows the figure alone. */
+/** Bar, gap and figure: the least a share cell draws with its bar. */
 const SHARE_BAR_MIN_CELLS = 3 + 1 + SHARE_FIGURE_CELLS;
+/** Cells a column keeps for the bare basis of the longest row (`cost of sales`); a longer one is cut by an ellipsis. */
+const SHARE_BASIS_FLOOR_CELLS = 13;
+/** Cells of basis kept in the last resort: three letters and an ellipsis. */
+const SHARE_BASIS_LAST_CELLS = 4;
+
+/** Every row's basis as the cells of each form, whole wording first: what a share column is laid out by. */
+type BasisForms = readonly (readonly number[])[];
+
+/** Cells a row's basis keeps in `room`: its longest whole form that fits, else as much of its bare form as the floor allows. */
+const keptBasis = (forms: readonly number[], room: number) => forms.find((cells) => cells <= room) ?? Math.min(room, SHARE_BASIS_FLOOR_CELLS);
+/** The cells the narrowest column keeps for the longest bare basis. */
+const bareBasis = (bases: BasisForms) => Math.min(SHARE_BASIS_FLOOR_CELLS, Math.max(0, ...bases.map((forms) => forms[forms.length - 1]!)));
+
+/** Cells of a share column's bar and of its basis; no bar leaves the figure beside its basis. */
+interface ShareLayout { bar: number; basis: number }
 
 /**
- * Cells of a share column's bar: as long as the column allows after the figure
- * and the longest basis that fits, between 3 and 8 cells, and the same on every
- * row so the bars and figures line up. Zero leaves the figure alone.
+ * The bar and the basis of a share column, the same on every row so the bars
+ * and figures line up. A share keeps what it is a share of: the column gives
+ * up the bar, then the whole wording, before it gives up the basis. The bar
+ * takes what the longest basis leaves, between 3 and 8 cells.
  */
-function shareBarCells(width: number, bases: readonly number[]): number {
-  if (width < SHARE_BAR_MIN_CELLS) return 0;
-  // Room for the longest basis that can show at all; a longer one gives way, not every bar.
-  const basis = longestBasis(bases, width);
-  return Math.min(width >= 36 ? 8 : 5, Math.max(3, width - SHARE_FIGURE_CELLS - 2 - basis));
+function shareLayout(width: number, bases: BasisForms): ShareLayout {
+  const beside = width - SHARE_BAR_MIN_CELLS - 1;
+  if (beside >= bareBasis(bases)) {
+    const longest = Math.max(0, ...bases.map((forms) => keptBasis(forms, beside)));
+    const bar = Math.min(width >= 36 ? 8 : 5, Math.max(3, width - SHARE_FIGURE_CELLS - 2 - longest));
+    return { bar, basis: width - bar - SHARE_FIGURE_CELLS - 2 };
+  }
+  return { bar: 0, basis: Math.max(0, width - SHARE_FIGURE_CELLS - 1) };
 }
-const longestBasis = (bases: readonly number[], width: number) => Math.max(0, ...bases.filter((cells) => SHARE_BAR_MIN_CELLS + 1 + cells <= width));
 
 /** A period end date; its length, when the source states it, follows it in a wider column. */
 const PERIOD_DATE_CELLS = 10;
 /**
  * Columns that fit the pane, giving up the least first: the share bar shortens
  * to keep the whole basis, the name shortens to 18 cells, the ticker folds into
- * the name and the period is left to the evidence view; then the share drops
- * its basis and its bar, and the name shortens further. Only a pane narrower
- * than that scrolls sideways, so the pane edge never cuts a share in half.
+ * the name and the period is left to the evidence view; then the share gives
+ * its bar, then its whole wording for the bare basis, and the name shortens
+ * further. A share never loses its basis. Only a pane narrower than that
+ * scrolls sideways, so the pane edge never cuts a share in half.
  * Value shows only when some row discloses a value, retaining its original
  * currency and units.
  */
-function tableColumns(width: number, desktop: boolean, locked: boolean, valueWidth: number | null, bases: readonly number[], periodWidth = PERIOD_DATE_CELLS): DataTableColumn[] {
+function tableColumns(width: number, desktop: boolean, locked: boolean, valueWidth: number | null, bases: BasisForms, periodWidth = PERIOD_DATE_CELLS): DataTableColumn[] {
   const wide = width >= 150, medium = width >= 110;
   const name: DataTableColumn = { id: "name", label: "Counterparty", width: Math.max(locked && !desktop ? 34 : 0, wide ? 30 : medium ? 26 : 20), flexGrow: 1, align: "left" };
   const share: DataTableColumn = { id: "pct", label: "Share", width: wide ? 34 : medium ? 30 : 26, align: "left" };
@@ -89,8 +111,11 @@ function tableColumns(width: number, desktop: boolean, locked: boolean, valueWid
   const preferred = { share: share.width, name: name.width };
   // The table ignores its last trailing gutter when deciding whether it fits.
   const overflow = () => getTableWidth(columns) - width - 1;
-  // Native units keep their column before the share keeps its bar or basis.
-  const shareFloor = valueWidth !== null ? SHARE_BAR_MIN_CELLS + 1 : SHARE_BAR_MIN_CELLS + 1 + longestBasis(bases, preferred.share);
+  // Native units keep their column before the share keeps its bar or its whole wording.
+  const withBar = SHARE_BAR_MIN_CELLS + 1;
+  const plain = SHARE_FIGURE_CELLS + 1;
+  const bare = bareBasis(bases);
+  const shareFloor = withBar + (valueWidth !== null ? bare : Math.max(bare, ...bases.map((forms) => keptBasis(forms, preferred.share - withBar))));
   const fit = (shareMin: number, nameMin = 18) => {
     share.width = preferred.share; name.width = preferred.name;
     share.width = Math.max(shareMin, share.width - Math.max(0, overflow()));
@@ -103,9 +128,12 @@ function tableColumns(width: number, desktop: boolean, locked: boolean, valueWid
     columns = columns.filter((column) => column.id !== id);
     fit(shareFloor);
   }
-  // The narrowest panes keep the figure alone, then a shorter name, before anything scrolls.
-  if (overflow() > 0) fit(SHARE_BAR_MIN_CELLS);
-  if (overflow() > 0) fit(SHARE_FIGURE_CELLS + 2, 12);
+  // The narrowest panes keep the figure and the bare basis, then a shorter name and a cut basis, before anything scrolls.
+  const shares = bases.length > 0;
+  if (overflow() > 0) fit(withBar + bare);
+  if (overflow() > 0 && shares) fit(plain + bare);
+  if (overflow() > 0) fit(shares ? plain + bare : SHARE_FIGURE_CELLS + 2, 12);
+  if (overflow() > 0 && shares) fit(plain + SHARE_BASIS_LAST_CELLS, 12);
   return columns;
 }
 
@@ -123,20 +151,20 @@ function supplyFigures(data: SupplyChainPayload, views: readonly ("says" | "name
 
 /**
  * The share as a bar on a 0 to 100% scale, the figure, and what it is a share
- * of. The basis shows whole or not at all: a column too narrow for it keeps
- * the bar and figure, and the evidence view says the rest.
+ * of. The basis never goes: a column too narrow for the whole wording shows a
+ * shorter form of it, then drops the bar, then cuts it behind an ellipsis.
+ * The evidence view and the selected row's line say it whole.
  */
-function ShareCell({ row, focusId, width, bases, selected }: { row: SupplyRow; focusId?: string; width: number; bases: readonly number[]; selected: boolean }) {
+function ShareCell({ row, focusId, width, layout, selected }: { row: SupplyRow; focusId?: string; width: number; layout: ShareLayout; selected: boolean }) {
   const colors = useThemeColors();
   const share = shareParts(row, focusId);
   if (!share) return <Text fg={colors.textMuted}>{""}</Text>;
-  const bar = shareBarCells(width, bases);
-  if (!bar) return <Text fg={selected ? colors.selectedText : colors.textBright} attributes={TextAttributes.BOLD}>{share.value}</Text>;
-  const basis = bar + SHARE_FIGURE_CELLS + 2 + displayWidth(share.basis) <= width;
+  const ink = selected ? colors.selectedText : colors.textBright;
+  const basis = fitShareBasis(share, layout.basis);
   return <Box flexDirection="row" width={width} height={1} gap={1} overflow="hidden">
-    <RatioBar ratio={row.pctOfRevenue! / 100} width={bar} color={ROLE_COLORS[row.role]} track />
-    <Text fg={selected ? colors.selectedText : colors.textBright} attributes={TextAttributes.BOLD}>{share.value.padStart(SHARE_FIGURE_CELLS)}</Text>
-    {basis ? <Text fg={selected ? colors.selectedText : colors.textDim}>{share.basis}</Text> : null}
+    {layout.bar ? <RatioBar ratio={row.pctOfRevenue! / 100} width={layout.bar} color={ROLE_COLORS[row.role]} track /> : null}
+    <Text fg={ink} attributes={TextAttributes.BOLD}>{share.value.padStart(SHARE_FIGURE_CELLS)}</Text>
+    {basis ? <Text fg={selected ? colors.selectedText : colors.textDim}>{basis}</Text> : null}
   </Box>;
 }
 
@@ -225,9 +253,18 @@ function SupplyView({ symbol, width, height, focused }: Pick<PaneProps, "width"
     ...(savedTab === "flow" && tooSmall ? ["Flow needs a wider pane. Showing the table."] : []),
   ] });
   const focusId = data?.entity?.id;
+  // Over the table, how much of the receivables one customer holds at each period end the company disclosed.
+  const concentration = useMemo(() => tab === "table" && view === "says" ? receivablesConcentration(tableRows, focusId) : [], [tab, view, tableRows, focusId]);
+  const concentrationDates = useMemo(() => new Map(concentration.map((point) => [point.rowId, point.date])), [concentration]);
+  const getConcentrationDate = useCallback((row: SupplyRow) => concentrationDates.get(row.id) ?? null, [concentrationDates]);
+  const chartSelection = useChartTableSelection({ rows: tableRows, getId: rowId, getDate: getConcentrationDate,
+    selectedId: selected?.id ?? null, onSelect: setSelected, focused: focused && !openRow, enabled: concentration.length > 0 });
+  const concentrationSeries = useMemo(() => [{ ...staticSeries(concentration.map((point) => ({ date: point.date, observedAt: point.date, value: point.pct })),
+    { id: "receivables-concentration", label: "Largest disclosed customer · receivables", color: ROLE_COLORS.customer, calendarSpaced: true, style: "points" }), unit: "%", unitGroup: "percent" }], [concentration]);
+  const concentrationChart = concentration.length ? { series: concentrationSeries, formatValue: formatShare, formatAxisValue: formatPercentAxis, strip: null, ...chartSelection } : null;
   const values = tableRows.filter((row) => nativeValue(row) !== null || row.usd !== null);
   const valueWidth = values.length ? Math.min(28, Math.max(...values.map((row) => displayWidth(disclosedValue(row).replace(/ (disclosed|derived)$/, ""))))) : null;
-  const bases = tableRows.flatMap((row) => { const share = shareParts(row, focusId); return share ? [displayWidth(share.basis)] : []; });
+  const bases: BasisForms = tableRows.flatMap((row) => { const share = shareParts(row, focusId); return share ? [share.forms.map(displayWidth)] : []; });
   // The period's length follows its end date when the source states it (2026-07-31 half) and costs
   // no column; laid out a cell narrower, the table also clears its own scrollbar. Otherwise the
   // evidence view says it.
@@ -235,6 +272,7 @@ function SupplyView({ symbol, width, height, focused }: Pick<PaneProps, "width"
   const dated = tableColumns(width, desktop, locked > 0, valueWidth, bases);
   const lengths = periodWidth > PERIOD_DATE_CELLS ? tableColumns(width - 1, desktop, locked > 0, valueWidth, bases, periodWidth) : null;
   const columns = lengths?.some((column) => column.id === "fy") && lengths.map((column) => column.id).join() === dated.map((column) => column.id).join() ? lengths : dated;
+  const shareColumn = shareLayout(columns.find((column) => column.id === "pct")?.width ?? 0, bases);
   const renderCell = (entry: SectionedRow<Item>, column: DataTableColumn, _index: number, state: { selected: boolean }): DataTableCell => {
     if (!isSectionedItemRow(entry)) return { text: "" };
     const item = entry.item;
@@ -278,7 +316,7 @@ function SupplyView({ symbol, width, height, focused }: Pick<PaneProps, "width"
         <Text fg={ink ?? ROLE_COLORS[row.role]}>{` ${roleLabel(row.role)}`}</Text>
       </Box> };
       case "pct": return { text: percentage(row) === "--" ? "" : `${shareParts(row, focusId)?.value ?? ""} ${shareParts(row, focusId)?.basis ?? ""}`.trim(), value: row.pctOfRevenue,
-        content: <ShareCell row={row} focusId={focusId} width={column.width} bases={bases} selected={state.selected} /> };
+        content: <ShareCell row={row} focusId={focusId} width={column.width} layout={shareColumn} selected={state.selected} /> };
       case "usd": return nativeValue(row) === null && row.usd === null ? { text: "", value: null }
         : { text: disclosedValue(row).replace(/ (disclosed|derived)$/, ""), value: row.nativeAmount != null ? row.nativeAmount * (row.nativeScale ?? 1) : row.usd, color: colors.text };
       case "fy": return { text: displayWidth(cellText(row, "fy")) <= column.width ? cellText(row, "fy") : row.period, color: colors.textDim };
@@ -291,12 +329,13 @@ function SupplyView({ symbol, width, height, focused }: Pick<PaneProps, "width"
   const bodyHeight = Math.max(3, height - tabRows);
   const figures = data ? supplyFigures(data, tab === "flow" ? ["says", "names"] : [view], options) : [];
   const tierFilter = { id: "tiers", label: "Evidence", kind: "multi" as const, emptyLabel: "Primary", values: options.tiers, options: TIER_OPTIONS, onChange: (value: string[]) => { setTiers(supplyOptions(value).tiers); setSelected(null); setOpen(null); } };
-  const header = <Box flexDirection="column" flexShrink={0}>
-    <QueryBar width={width} filters={[{ id: "direction", label: "Direction", inline: true, value: view,
-      options: [{ value: "says", label: `${symbol} says` }, { value: "names", label: `Names ${symbol}` }], onChange: (value: string) => { setView(value); setSelected(null); setOpen(null); } }, tierFilter]}
-      meta={view === "names" ? "% of reporting company's basis" : undefined} />
-    <StatGrid items={figures} width={width} />
-  </Box>;
+  const query = <QueryBar width={width} filters={[{ id: "direction", label: "Direction", inline: true, value: view,
+    options: [{ value: "says", label: `${symbol} says` }, { value: "names", label: `Names ${symbol}` }], onChange: (value: string) => { setView(value); setSelected(null); setOpen(null); } }, tierFilter]}
+    meta={view === "names" ? "% of reporting company's basis" : undefined} />;
+  // Without a trend the figures keep every row they had; the chart layout shares the height with the table only when it draws.
+  const header = concentrationChart
+    ? <ChartTableHeader width={width} height={bodyHeight} tableRows={items.length} tableColumns={columns} figures={figures} chart={concentrationChart} query={query} />
+    : <Box flexDirection="column" flexShrink={0}>{query}<StatGrid items={figures} width={width} /></Box>;
   const flowFigureColumns = Math.min(Math.max(1, figures.length), Math.max(1, Math.floor(width / 24)));
   // A short flow keeps one row of figures, dropping the last roles, so the cards keep their room.
   const flowFigures = bodyHeight < 26 ? figures.slice(0, flowFigureColumns) : figures;

package/src/plugins/builtin/supply-chain/row-evidence.tsx

@@ -25,7 +25,7 @@ export function SupplyVerification({ row }: { row: SupplyRow }) {
     <KeyValueRow label="Corroboration" value={corroborationLabel(row)} labelWidth={20} />
     {row.pctScope ? <KeyValueRow label={row.sourceKind === "xbrl" ? "Tagged context" : "Percentage scope"} value={row.pctScope} labelWidth={20} /> : null}
     {row.sectionRef ? <KeyValueRow label="Section" value={row.sectionRef} labelWidth={20} /> : null}
-    {row.jurisdiction ? <KeyValueRow label="Jurisdiction" value={row.jurisdiction} labelWidth={20} /> : null}
+    {row.jurisdiction ? <KeyValueRow label="Jurisdiction" value={row.jurisdiction} country={row.jurisdiction} labelWidth={20} /> : null}
     {row.firstSeenAt ? <KeyValueRow label="First seen" value={row.firstSeenAt.slice(0, 10)} detail={row.lastSeenAt ? `last seen ${row.lastSeenAt.slice(0, 10)}` : undefined} labelWidth={20} /> : null}
     {!isUnconfirmed(row) && row.lastConfirmedAt ? <KeyValueRow label="Last confirmed" value={row.lastConfirmedAt.slice(0, 10)} labelWidth={20} /> : null}
   </>;

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

@@ -5,7 +5,7 @@ import { formatRelativeAge } from "../../../utils/datetime-format";
 import { fetchThemeMembers, fetchThemes } from "./client";
 import {
   aggregateText, boardClose, boardYtdBase, DEFAULT_SORT, matchTheme, memberExtended, memberExtendedSessions, memberPrice, percent, periodLabel,
-  SNAPSHOT_STALE_MS, sortMembers, sortThemes,
+  isLiveBoard, SNAPSHOT_STALE_MS, sortMembers, sortThemes,
 } from "./model";
 
 /** The period columns; YTD names the close it is measured from, `YTD vs 31 Dec close`. */
@@ -50,13 +50,15 @@ function boardObservation(payload: ThemesPayload | ThemeMembersPayload, now = Da
     regularSessionDate: close?.date ?? null,
     regularSessionClosedAt: close?.closedAt ?? null,
   };
+  // A Pro account's board is priced from the server's live read.
+  const feed = isLiveBoard(payload) ? { status: "live" as const } : {};
   if (close && now - assembledAt <= SNAPSHOT_STALE_MS) {
     return {
       metadata: { asOf: close.closedAt != null ? new Date(close.closedAt).toISOString() : close.date, sessionExchange: "NYSE", ...snapshot },
-      freshness: { tradingDayMarket: "US", note: `snapshot ${formatRelativeAge(assembledAt, now)}` },
+      freshness: { ...feed, tradingDayMarket: "US", note: `snapshot ${formatRelativeAge(assembledAt, now)}` },
     };
   }
-  return { metadata: { asOf: payload.asOf, ...snapshot }, freshness: { maxAgeMinutes: 30 } };
+  return { metadata: { asOf: payload.asOf, ...snapshot }, freshness: { ...feed, maxAgeMinutes: 30 } };
 }
 
 /**
@@ -74,14 +76,15 @@ function themeReportTitle(query: string | undefined, theme: Pick<ThemeSummary, "
 
 export const themesHeadless: HeadlessPaneDefinition<"rows"> = {
   shape: "rows",
-  // The pane's stored snapshot: 15-minute delayed prices, refreshed every 15 minutes. As in the pane,
+  // The pane's stored snapshot, refreshed every 15 minutes, priced in real time for a Pro account and
+  // fifteen minutes delayed otherwise (boardObservation says which). As in the pane,
   // the payload's stale flags are historical; a snapshot over 30 minutes old is what reads stale
   // (boardObservation, which dates a board outside the regular session by its close).
   freshness: { status: "delayed", delayMinutes: 15, ignoreStaleFlags: true },
   argument: { kind: "free-text", optional: true, placeholder: "theme", description: "Theme name or keyword, such as nuclear; omit for all themes." },
   options: [],
   discovery: { aliases: ["THEM"], dataRequirements: ["Gloom Cloud stored equity snapshot"],
-    limitations: ["Updated every 15 minutes for Free and Pro.", "Equal-weight price returns; missing observations reduce coverage.", "Below half coverage a period is unavailable.",
+    limitations: ["Prices and 1D are real-time with Pro and fifteen minutes delayed otherwise; the longer returns start from a snapshot updated every 15 minutes.", "Equal-weight price returns; missing observations reduce coverage.", "Below half coverage a period is unavailable.",
       "Outside the regular session Price, 1D and the returns end at the last regular close; a pre-market or after-hours print is shown beside it and never enters them."] },
   describe: (args, result) => themeReportTitle(args.rawArgument, (result?.metadata as { theme?: ThemeSummary } | undefined)?.theme),
   async load(args, context) {

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

@@ -82,14 +82,24 @@ function closeLabel(date: string): string {
  * How current the board is, for its footer. Outside the regular session the
  * close its figures describe and how old the snapshot is, `Fri 9 Oct close ·
  * snapshot 12m ago`; while a session trades, or from a server that does not
- * name the close, the delay and the snapshot's age. `age` is the relative age
- * (`12m ago`).
+ * name the close, whether its prices are live (a Pro account's) or delayed,
+ * and the snapshot's age, which the longer returns start from. `age` is the
+ * relative age (`12m ago`).
  */
-export function snapshotFooterText(payload: { regularSessionDate?: unknown; regularSessionClosedAt?: unknown }, age: string): string {
+export function snapshotFooterText(payload: { regularSessionDate?: unknown; regularSessionClosedAt?: unknown; access?: unknown }, age: string): string {
   const close = boardClose(payload);
-  return close ? `${closeLabel(close.date)} · snapshot ${age}` : `15m delayed · snapshot ${age}`;
+  if (close) return `${closeLabel(close.date)} · snapshot ${age}`;
+  return `${isLiveBoard(payload) ? "live" : "15m delayed"} · snapshot ${age}`;
 }
 
+/** Whether a board's prices are real-time: a Pro account's, priced from the server's live read. */
+export function isLiveBoard(payload: { access?: unknown } | null | undefined): boolean {
+  return payload?.access === "realtime";
+}
+
+/** How often a board is worth checking again: the server renews a live board's prices every 15 seconds. */
+export const LIVE_BOARD_REFRESH_MS = 15_000;
+
 /** A member's pre-market or after-hours print and its move from the close in Price, when it has a valid one. */
 export function memberExtended(row: ThemeMember): { session: ExtendedSession; price: number; change: number | null; changePercent: number | null } | null {
   const session = row.extendedSession;

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

@@ -13,10 +13,21 @@ import { useMembersMenu } from "../shared/members-menu";
 import { cachedMembers, cachedThemes, loadMembers, loadThemes } from "./client";
 import {
   aggregateText, boardYtdBase, coverageWidth, DEFAULT_SORT, extendedMove, matchTheme, memberColumns, memberExtendedSessions, memberPrice, percent,
-  SNAPSHOT_STALE_MS, snapshotFooterText, sortMembers, sortThemes, themeColumns, type ThemeSort,
+  isLiveBoard, LIVE_BOARD_REFRESH_MS, SNAPSHOT_STALE_MS, snapshotFooterText, sortMembers, sortThemes, themeColumns, type ThemeSort,
 } from "./model";
 
-type SnapshotPayload = { asOf: string; stale: boolean; regularSessionDate?: string | null; regularSessionClosedAt?: number | null };
+const LIVE_LEAD = "live · ";
+type SnapshotPayload = { asOf: string; stale: boolean; access?: "realtime" | "delayed"; regularSessionDate?: string | null; regularSessionClosedAt?: number | null };
+
+/**
+ * Refreshes a board on the user's interval, or every 15 seconds while it is
+ * live: a Pro account's prices are renewed that often on the server.
+ */
+function useBoardRefresh(resource: { updatedAt: number | null; load: (force?: boolean) => Promise<unknown>; data: { payload: SnapshotPayload } | null }) {
+  const live = isLiveBoard(resource.data?.payload);
+  const { load } = resource;
+  useAutoRefresh(resource.updatedAt, live ? () => void load(true) : () => void load(), { intervalMs: live ? LIVE_BOARD_REFRESH_MS : null });
+}
 
 function useSnapshotFooter(id: string, resource: { loading: boolean; error: string | null; data: { payload: SnapshotPayload; stale: boolean; refreshError: string | null } | null }, focused: boolean, enabled = true) {
   const data = resource.data;
@@ -24,7 +35,15 @@ function useSnapshotFooter(id: string, resource: { loading: boolean; error: stri
   const payload = data?.payload;
   // Outside the regular session the figures are a close, so the footer names it, not the snapshot's time.
   const text = age && payload ? snapshotFooterText(payload, age) : null;
-  const info = useMemo(() => text ? splitDelayedStatus({ id: "snapshot", parts: [{ text, tone: "muted" }] }) : [], [text]);
+  const info = useMemo(() => {
+    if (!text) return [];
+    // A live board says so as the other live panes do, before the snapshot's age.
+    if (text.startsWith(LIVE_LEAD)) {
+      return [{ id: "snapshot-live", parts: [{ text: "live", tone: "positive" as const }] },
+        { id: "snapshot", parts: [{ text: text.slice(LIVE_LEAD.length), tone: "muted" as const }] }];
+    }
+    return splitDelayedStatus({ id: "snapshot", parts: [{ text, tone: "muted" }] });
+  }, [text]);
   // The server flag includes retained historical returns; it does not mean the daily board is old.
   const snapshotStale = !!data && Date.now() - Date.parse(data.payload.asOf) > SNAPSHOT_STALE_MS;
   usePaneStatusFooter({ registrationId: id, enabled, loading: resource.loading && !!data,
@@ -49,7 +68,7 @@ function Members({ id, width, height, focused }: { id: string; width: number; he
   const ytdBase = data ? boardYtdBase(data) : null;
   const columns = useMemo(() => memberColumns(width, extendedSessionsKey ? extendedSessionsKey.split(",") as ExtendedSession[] : [], ytdBase),
     [extendedSessionsKey, width, ytdBase]);
-  useAutoRefresh(resource.updatedAt, resource.load);
+  useBoardRefresh(resource);
   usePaneRefreshKey(() => void resource.reload(), { focused });
   useSnapshotFooter("themes:members", resource, focused);
   const memberList = useMemo(() => data ? { title: data.theme.name, watchlistName: data.theme.name, members: rows } : null, [data, rows]);
@@ -107,7 +126,7 @@ export function ThemesBoard({ width, height, focused, tabStrip, tabRows = 0 }: T
   const rows = useMemo(() => sortThemes(data?.themes ?? [], sort), [data, sort]);
   const columns = useMemo(() => themeColumns(width, data?.themes ?? [], data ? boardYtdBase(data) : null), [width, data]);
   const theme = opened && data ? matchTheme(data.themes, opened) : null;
-  useAutoRefresh(resource.updatedAt, resource.load);
+  useBoardRefresh(resource);
   usePaneRefreshKey(() => void resource.reload(), { focused, enabled: !opened });
   useSnapshotFooter("themes:list", resource, focused, !opened || !data);
   const renderCell = useCallback((row: ThemeSummary, column: DataTableColumn): DataTableCell => {

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

@@ -471,10 +471,10 @@ function thirteenFShotState(args: HeadlessPaneLoadArgs, metadata: Record<string,
       });
     }
     case "crowding":
-      if (query) throw new Error(`The 13F pane draws the whole crowding ranking, not one ticker's rank. Drop "${query}" from shot, or run the report: gloomberb fn 13F ${query} --view crowding`);
+      if (query) throw new Error(`The 13F pane draws the whole crowding ranking, not one ticker's rank. Drop "${query}" from shot, or run the report: gloom fn 13F ${query} --view crowding`);
       return { pluginState: { [PANE_STATE_ID]: { browserTab: "crowding", "13f-crowding:ranking": CROWDING_RANKING[String(metadata.rank ?? "new")] ?? "newCount" } } };
     case "performance":
-      if (cik) throw new Error(`The 13F pane draws the performance ranking, not one fund's row. Run the report for ${metadata.fund ?? cik}: gloomberb fn 13F ${cik} --view performance, or gloomberb shot 13F --view performance for the ranking.`);
+      if (cik) throw new Error(`The 13F pane draws the performance ranking, not one fund's row. Run the report for ${metadata.fund ?? cik}: gloom fn 13F ${cik} --view performance, or gloom shot 13F --view performance for the ranking.`);
       return browser("");
     case "latest":
       return browser("latest");
@@ -484,7 +484,7 @@ function thirteenFShotState(args: HeadlessPaneLoadArgs, metadata: Record<string,
       return browser(query);
     case "byTicker":
       // The pane lists a ticker's holders with their positions, and their whole books only when it cannot.
-      if (String(args.options.view) !== "auto") throw new Error(`The 13F pane lists a ticker's holders with their positions. Drop --view ${args.options.view} from shot, or run the report: gloomberb fn 13F ${query} --view by-ticker`);
+      if (String(args.options.view) !== "auto") throw new Error(`The 13F pane lists a ticker's holders with their positions. Drop --view ${args.options.view} from shot, or run the report: gloom fn 13F ${query} --view by-ticker`);
       return browser(query);
     default:
       return {};
@@ -796,7 +796,7 @@ export function createThirteenFHeadless(
       // A fund's own row of the performance list, with the command that copies its basket.
       if (view === "performance" && query && inferBrowserTabFromQuery(query) === "funds") {
         const fund = await resolveFund(query, args, ctx, dependencies, {
-          notFound: `No 13F fund matched "${query}". For the performance ranking, run gloomberb fn 13F --view performance; for one fund, give its CIK, as in gloomberb fn 13F 0001067983 --view performance.`,
+          notFound: `No 13F fund matched "${query}". For the performance ranking, run gloom fn 13F --view performance; for one fund, give its CIK, as in gloom fn 13F 0001067983 --view performance.`,
         });
         const performance = await dependencies.loadPerformance(fund.cik, fund.name, ctx);
         const row = performance.rows[0]!;
@@ -832,7 +832,7 @@ export function createThirteenFHeadless(
               performance.skipped?.length ? splitUnreadText(performance.skipped, "Left out of Est 13F") : "",
               performance.unavailable ? `No Est 13F${rankingText ? ` (${rankingText})` : ""}: ${performance.unavailable}` : "",
               ...filingGapNotes(performance.period ?? null, performance.filingGap ?? null),
-              `Copy this basket: gloomberb portfolio import --13f ${row.cik}`,
+              `Copy this basket: gloom portfolio import --13f ${row.cik}`,
             ].filter(Boolean),
           },
         };

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

@@ -11,6 +11,8 @@ export interface TickerHolderRow {
   type: string;
   value: number | null;
   shares: number | null;
+  /** Shares at the prior period end when the two reports compare: 0 for a new position, null when unknown. Absent from an older service. */
+  previousShares?: number | null;
   weight: number | null;
   previousWeight: number | null;
   weightChange: number | null;
@@ -55,7 +57,7 @@ export interface Crowding extends SignalsBase {
 }
 export async function loadTickerHoldings(ticker: string, offset = 0, signal?: AbortSignal): Promise<TickerHoldings> {
   signal?.throwIfAborted();
-  const result = await apiClient.getCloudSec13F("ticker-holdings", { tickers: ticker, offset, limit: 25 }) as TickerHoldings;
+  const result = await apiClient.getCloudSec13F("ticker-holdings", { tickers: ticker, offset, limit: 25 }, { signal }) as TickerHoldings;
   signal?.throwIfAborted();
   return result;
 }

package/src/plugins/builtin/ticker-detail/adr-pair/headless.ts

@@ -0,0 +1,123 @@
+import type { HeadlessPaneDefinition } from "../../../../types/headless";
+import type { Quote } from "../../../../types/financials";
+import { dollarPairLabel, spotFromUsdValue, spotRateKind } from "../../../../market-data/depositary-pair";
+import { loadHeadlessFinancials, resolveHeadlessInstrument } from "../../shared/headless-market-data";
+import { quoteObservation } from "../../shared/report-freshness";
+import { heldCurrencyUnit } from "../../../../utils/currency-units";
+import { adrPairComparison, adrPairFigures, adrPairInputRows, adrPairLegs, ADR_PAIR_TEMPLATE_ID } from "./model";
+
+/** Words that ask for this report's figures without being its code: `fn CCL` answers with ADR. */
+export const ADR_PAIR_KEYWORDS = [
+  "adr", "adrs", "adr vs home", "adr ratio", "adr premium", "adr discount", "depositary receipt", "depositary receipts",
+  "home listing", "home line", "implied fx", "implied exchange rate", "implied dollar", "ccl", "contado con liquidacion",
+  "dolar ccl", "mep", "dolar mep", "dolar bolsa", "blue chip swap", "cross listing", "dual listing",
+];
+
+type LoadContext = Parameters<HeadlessPaneDefinition["load"]>[1];
+
+/** The currency's dollar rate, dated when the cached query says when it was observed (as `fx` dates it). */
+async function readSpot(currency: string, ctx: LoadContext) {
+  if (currency === "USD") return { rate: 1, observedAt: null };
+  const { marketData } = ctx;
+  if (marketData.getCachedQuery) {
+    const entry = await marketData.getCachedQuery("getExchangeRate", [currency]).load({ background: marketData.revalidatesInBackground });
+    return spotFromUsdValue(entry.value, entry.asOf ?? null);
+  }
+  return spotFromUsdValue(await marketData.getExchangeRate(currency));
+}
+
+/** A leg's quote through the standard quote path, so both legs are read alike. */
+async function readQuote(key: string, ctx: LoadContext, failed: (error: unknown) => null): Promise<Quote | null> {
+  const instrument = await resolveHeadlessInstrument(ctx, key);
+  return ctx.marketData.getQuote(instrument.symbol, instrument.exchange ?? "").catch(failed);
+}
+
+export const adrPairHeadless: HeadlessPaneDefinition<"bundle"> = {
+  shape: "bundle",
+  argument: { kind: "ticker", description: "A depositary receipt (GGAL, TSM) or its home listing (GGAL.BA, 2330.TW)" },
+  options: [],
+  discovery: {
+    // CCL is also a ticker (Carnival), so neither word opens ADR: `fn CCL` and `catalog ccl` point to it.
+    suggestFor: ["CCL", "MEP"],
+    screenshotReadiness: "ready",
+    limitations: [
+      "Listings Gloom Cloud pairs with a receipt only; the ratio is the depositary's, checked against both lines' prices.",
+    ],
+  },
+  description: "A depositary receipt beside its home listing: the ratio, both regular-session prices with when each was set, the dollar rate they imply (home × ratio / ADR, the CCL rate for an Argentine pair), spot, and the receipt's premium or discount at spot.",
+  describe: ({ symbols }) => `ADR vs Home | ${symbols[0] ?? ""}`,
+  async load({ symbols }, ctx) {
+    const key = symbols[0]!;
+    const financials = await loadHeadlessFinancials(ctx, key);
+    ctx.signal.throwIfAborted();
+    const legs = adrPairLegs(financials, null, key);
+    if (!legs) {
+      return {
+        sections: [],
+        empty: `${key} has no depositary receipt pair on record. ADR takes a receipt (GGAL, TSM) or its home listing (GGAL.BA, 2330.TW).`,
+        unavailableSymbols: [key],
+      };
+    }
+    const errors: string[] = [];
+    const failed = (label: string) => (error: unknown) => {
+      errors.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    };
+    const [receipt, home] = await Promise.all([
+      readQuote(legs.receiptKey, ctx, failed(legs.receiptKey)),
+      readQuote(legs.homeKey, ctx, failed(legs.homeKey)),
+    ]);
+    ctx.signal.throwIfAborted();
+    const quotes = { receipt, home };
+    // A minor unit (GBp) is read as its currency, as the comparison reads the price.
+    const homeCurrency = quotes.home?.currency ? heldCurrencyUnit(quotes.home.currency).currency : "";
+    const spot = homeCurrency ? await readSpot(homeCurrency, ctx).catch(failed(dollarPairLabel(homeCurrency))) : null;
+    const comparison = adrPairComparison(legs, quotes, spot);
+    if (!comparison) {
+      const missing = !quotes.receipt ? legs.receiptKey : legs.homeKey;
+      return { sections: [], empty: `No price for ${missing}, so the pair cannot be compared.`, unavailableSymbols: [missing], errors };
+    }
+    const figures = adrPairFigures(comparison);
+    const rows = adrPairInputRows(comparison);
+    const kind = spotRateKind(homeCurrency);
+    return {
+      sections: [
+        {
+          title: `${legs.receiptKey} vs ${legs.homeKey}`,
+          entries: figures.map((figure) => ({
+            key: figure.id, label: figure.label,
+            value: figure.id === "implied" ? comparison.impliedFx
+              : figure.id === "spot" ? comparison.spot?.rate ?? null
+              : figure.id === "premium" ? comparison.premiumPercent
+              : comparison.ratio,
+            formatted: figure.detail ? `${figure.value} (${figure.detail})` : figure.value,
+          })),
+        },
+        {
+          title: "Inputs",
+          columns: [
+            { key: "listing", header: "Listing" },
+            { key: "role", header: "Role" },
+            { key: "price", header: "Price", align: "right" },
+            { key: "asOf", header: "As of (UTC)" },
+            { key: "session", header: "Session" },
+          ],
+          rows: rows.map(({ opens: _opens, ...row }) => row),
+        },
+      ],
+      ...(comparison.timingNote ? { notes: [comparison.timingNote] } : {}),
+      ...(errors.length > 0 ? { errors } : {}),
+      freshness: {
+        observations: [quotes.receipt, quotes.home].filter((quote): quote is Quote => !!quote).map((quote) => ({ ...quoteObservation(quote) })),
+      },
+      metadata: {
+        receipt: legs.receiptKey, home: legs.homeKey, ratio: comparison.ratio, currency: homeCurrency,
+        impliedFx: comparison.impliedFx, spot: comparison.spot?.rate ?? null, ...(kind ? { spotKind: kind } : {}),
+        premiumPercent: comparison.premiumPercent,
+        receiptPrice: comparison.receipt.price, receiptObservedAt: comparison.receipt.observedAt,
+        homePrice: comparison.home.price, homeObservedAt: comparison.home.observedAt,
+        spotObservedAt: comparison.spot?.observedAt ?? null, template: ADR_PAIR_TEMPLATE_ID,
+      },
+    };
+  },
+};