gloomberb 0.18.1 → 0.18.2

package/src/plugins/builtin/risk-factors/index.tsx

@@ -1,4 +1,6 @@
 import type { PluginModule } from "../plugin-module";
+import type { PaneLock } from "../../../types/plugin";
+import { filesForm } from "../shared/free-routes";
 import { proLockNote } from "../shared/pro-lock-note";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import {
@@ -18,14 +20,21 @@ const description =
  * RISK is Pro whole (`useProFeatureWall`). The 10-Ks it reads are in the SEC
  * filing list, which needs no account: `filings` lists them with a link to
  * each, where Item 1A is the risk factors as written, without RISK's grouping
- * or its changes since the year before.
+ * or its changes since the year before. A foreign issuer files a 20-F instead
+ * (ASML), whose Item 3.D holds them.
  */
-function riskFactorsLockNote(lock: { gate: "sign-in" | "pro"; symbol: string | null }): string {
+function riskFactorsLockNote(lock: PaneLock): Promise<string> {
   return proLockNote(lock, {
     token: "RISK",
     does: "it groups a 10-K's risk factors by theme and shows what was added, dropped or reworded since the year before",
     shows: "it",
-    free: (ticker, company) => `gloomberb filings ${ticker} --form 10-K lists ${company}'s annual reports, each with its filing date and a link to the filing, whose Item 1A holds the risk factors as written.`,
+    free: [{
+      text: (ticker, company) => `gloomberb filings ${ticker} --form 10-K lists ${company}'s annual reports, each with its filing date and a link to the filing, whose Item 1A holds the risk factors as written.`,
+      answers: (symbol, context) => filesForm(symbol, "10-K", context),
+    }, {
+      text: (ticker, company) => `gloomberb filings ${ticker} --form 20-F lists ${company}'s annual reports, each with its filing date and a link to the filing, whose Item 3.D holds the risk factors as written.`,
+      answers: (symbol, context) => filesForm(symbol, "20-F", context),
+    }],
   });
 }
 

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

@@ -12,6 +12,7 @@ import { usePaneStatusFooter } from "../../../components/layout/pane/status-foot
 import { CLOUD_QUOTE_DELAY_MINUTES } from "../../../api-client/plan-access";
 import { useAppVisible } from "../../../state/app/activity";
 import { ScannerClientContext } from "../shared/scanner-capture";
+import { delayedFooterSegment } from "../../../components/layout/pane/footer/model";
 
 export interface ScannerFeedState<T extends ScannerPayload> {
   payload: T | null;
@@ -102,7 +103,11 @@ export function useScannerStatusFooter(
   const info = useMemo<PaneFooterSegment[]>(
     () => {
       const base = segment ? [segment, ...status]
-        : delayMinutes != null ? [{ id: "scanner-delay", parts: [{ text: tf("{delay} delayed", { delay: tf("{count}m", { count: delayMinutes }) }), tone: "muted" as const }] }, ...status]
+        : delayMinutes != null ? [delayedFooterSegment({
+          id: "scanner-delay",
+          detail: tf("{delay} delayed", { delay: tf("{count}m", { count: delayMinutes }) }),
+          delay: tf("{count}m", { count: delayMinutes }),
+        }), ...status]
           : status;
       return extra ? [...base, extra] : base;
     },

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

@@ -236,7 +236,7 @@ function createFlowHeadless(
     describe: "Options Flow",
     async load(args, ctx) {
       const payload = await dependencies.load(args, ctx.apiClient, ctx.signal)
-        .catch((error: unknown) => { throw explainRefusal(error, flowLockNote, { symbol: null }); });
+        .catch(async (error: unknown) => { throw await explainRefusal(error, flowLockNote, { symbol: null }); });
       return projectFlowSnapshot(payload, {
         ...DEFAULT_FLOW_FILTERS,
         ...(args.options as Partial<FlowFilters>),

package/src/plugins/builtin/scanner/lock-note.ts

@@ -5,13 +5,14 @@ import { proLockNote } from "../shared/pro-lock-note";
  * FLOW is Pro whole: the one scanner with no delayed tier to fall back to.
  * The options chain needs no account and lists each contract's day volume and
  * open interest, the raw counts behind a sweep or a block, without the prints.
+ * FLOW takes no ticker, so the route names none to check.
  */
-export function flowLockNote(lock: PaneLock): string {
+export function flowLockNote(lock: PaneLock): Promise<string> {
   return proLockNote(lock, {
     token: "FLOW",
     argument: "none",
     does: "it streams real-time sweeps, blocks and large premium prints across US options exchanges",
     shows: "it",
-    free: (ticker, company) => `gloomberb options ${ticker} lists ${company}'s option chain, each contract with its volume and open interest.`,
+    free: [{ text: (ticker, company) => `gloomberb options ${ticker} lists ${company}'s option chain, each contract with its volume and open interest.` }],
   });
 }

package/src/plugins/builtin/series-inventory.ts

@@ -62,6 +62,7 @@ export const SERIES_INVENTORY: readonly SeriesInventoryEntry[] = [
   { module: "crypto-board", chart: "Price sparklines for the large coins", series: ["crypto:*"] },
   { module: "perps", chart: "Perpetual funding, open interest, premium and long/short account share", series: ["perps:*"] },
   { module: "perps", chart: "Perpetual mark price", notInCatalog: "not-yet", reason: "The pair's price is in the catalog; the perpetual's own mark price could be a crypto series." },
+  { module: "primary-dealers", chart: "A primary dealer position's weekly net level, the sum of the release's series behind the row", notInCatalog: "not-yet", reason: "Weekly and dated, one series per row of the board; the pane reads each only when its row is selected, and none is registered for the composer yet." },
   { module: "short-interest", chart: "A ticker's short interest and days to cover", series: ["short-interest:*"] },
   { module: "short-volume", chart: "A ticker's daily short volume ratio", series: ["short-volume:*"] },
   { module: "social-mentions", chart: "A ticker's daily posts", series: ["social-mentions:*"] },

package/src/plugins/builtin/shared/cloud-denied.ts

@@ -34,13 +34,14 @@ export function refusedLock(error: unknown): Pick<PaneLock, "gate" | "verifyEmai
  * What a headless read throws when the server refused it behind a wall: the
  * pane's lock note on one line, so every consumer of the read says what is
  * locked and how to unlock it, with the refusal as its cause for `fn`, which
- * prints the whole note. Any other failure is returned as it is.
+ * prints the whole note. Any other failure is returned as it is. The read's
+ * context lets the note check the free route it names.
  */
-export function explainRefusal(
+export async function explainRefusal(
   error: unknown,
-  note: (lock: PaneLock) => string,
-  lock: Pick<PaneLock, "symbol" | "token">,
-): unknown {
+  note: (lock: PaneLock) => string | Promise<string>,
+  lock: Pick<PaneLock, "symbol" | "token" | "context">,
+): Promise<unknown> {
   const refused = refusedLock(error);
-  return refused ? new Error(lockNoteReason(note({ ...refused, ...lock })), { cause: error }) : error;
+  return refused ? new Error(lockNoteReason(await note({ ...refused, ...lock })), { cause: error }) : error;
 }

package/src/plugins/builtin/shared/cloud-upgrade.ts

@@ -3,6 +3,7 @@ import { apiClient } from "../../../api-client";
 import { recordResearchActivity, researchUpgradeUrl } from "../../../api-client/research-activity";
 import { getCurrentPluginTarget } from "../../current-target";
 import type { PaneFooterSegment, PaneHint } from "../../../components";
+import { delayedFooterSegment } from "../../../components/layout/pane/footer/model";
 import { t, tf } from "../../../i18n";
 import { useAppLanguage } from "../../../i18n/react";
 import { useRendererHost } from "../../../ui";
@@ -303,19 +304,17 @@ export function useCloudAccessFooter({
       };
     }
     if (!showUpgrade) return null;
-    return {
+    // The footer's clock, pressed for the upgrade. With a key the pitch is the
+    // upgrade hint, so the clock says only what is true of the data; without
+    // one its tooltip carries the pitch too.
+    return delayedFooterSegment({
       id: segmentId,
+      detail: shortcutScope
+        ? tf("{delay} delayed", { delay: delayLabel })
+        : tf("{delay} delayed · try Pro live", { delay: delayLabel }),
+      delay: delayLabel,
       onPress: openUpgrade,
-      parts: [{
-        // With a key the pitch is the upgrade hint, so the status says only
-        // what is true of the data. Without one there is nowhere else for it
-        // to go.
-        text: shortcutScope
-          ? tf("{delay} delayed", { delay: delayLabel })
-          : tf("{delay} delayed · try Pro live", { delay: delayLabel }),
-        tone: "warning",
-      }],
-    };
+    });
   }, [
     access.trialDaysLeft,
     delayLabel,

package/src/plugins/builtin/shared/free-routes.ts

@@ -0,0 +1,24 @@
+import type { HeadlessPaneContext } from "../../../types/headless";
+import { filingFormMatches } from "../sec/forms";
+import { resolveHeadlessInstrument, resolveHeadlessIssuerListing } from "./headless-market-data";
+
+/**
+ * Whether the SEC lists a filing of the form for the company, as
+ * `filings <ticker> --form <form>` would list it: ASML files 20-F and 6-K, so
+ * a route to its 10-Ks or 8-Ks answers "No filings". The service filters by
+ * form, so one filing answers; the form is checked again here, as a server
+ * without the filter sends the newest filing of any form.
+ */
+export async function filesForm(symbol: string, form: string, context: HeadlessPaneContext): Promise<boolean> {
+  const [{ symbol: ticker }, listing] = await Promise.all([
+    resolveHeadlessInstrument(context, symbol),
+    resolveHeadlessIssuerListing(context, symbol),
+  ]);
+  // A listing abroad whose company is unknown cannot be matched to a registrant, and `filings` says so.
+  if (listing.exchange && !listing.name) return false;
+  const { filings } = await context.apiClient.getCloudSecFilings(
+    { ticker, ...listing, forms: [form], limit: 1 },
+    { signal: context.signal },
+  );
+  return filings.some((filing) => filingFormMatches(filing.form, form));
+}

package/src/plugins/builtin/shared/headless-options.ts

@@ -11,6 +11,17 @@ export const HISTORY_RANGE_VALUES: HeadlessPaneOptionValue[] = [
   { value: "ALL", aliases: ["max", "maximum"] },
 ];
 
+/**
+ * The history windows and YTD, which runs from the prior year's last close
+ * (the one year-to-date returns are measured from), for a chart that compares
+ * returns.
+ */
+export const RETURN_RANGE_VALUES: HeadlessPaneOptionValue[] = [
+  ...HISTORY_RANGE_VALUES.slice(0, 5),
+  { value: "YTD", aliases: ["year-to-date", "year to date"] },
+  ...HISTORY_RANGE_VALUES.slice(5),
+];
+
 export const FINANCIAL_PERIOD_OPTION: HeadlessPaneOptionDef = {
   key: "period",
   description: "Financial reporting period.",

package/src/plugins/builtin/shared/pro-lock-note.ts

@@ -1,10 +1,90 @@
+import type { HeadlessPaneContext } from "../../../types/headless";
 import type { PaneLock } from "../../../types/plugin";
+import { settleWithin, signalWithTimeout } from "../../../utils/async-deadline";
+import { logFailure } from "../../../utils/log-failure";
 
 /** A lock note on one line, as JSON and CSV say why a locked report is empty and as an error carries it. */
 export function lockNoteReason(note: string): string {
   return note.replace(/\s*\n\s*/g, " ");
 }
 
+/**
+ * A free command a lock note can name in place of the locked function: what
+ * it lists, and whether it has data for the symbol the reader asked about. A
+ * note never sends a reader to a command that answers "No data".
+ */
+export interface FreeRoute {
+  /** The command and what it lists, finishing "Free, with no sign-in: ...". Run it signed out before naming it. */
+  text(ticker: string, company: string): string;
+  /**
+   * Whether the route has data for the symbol, read as the route reads it.
+   * Leave it out only for a route that answers for every symbol the function
+   * takes. A read that fails, or is still out after a few seconds, counts as
+   * no data; pass `context.signal` on to reads that take one.
+   */
+  answers?(symbol: string, context: HeadlessPaneContext): Promise<boolean>;
+}
+
+/** A refused read asks for its note twice (the error it throws, then the report), so an answer is kept a while. */
+const ANSWER_TTL_MS = 5 * 60_000;
+
+/**
+ * How long a note waits on its routes' data checks, all of them together: a
+ * check still out then counts as no data, so a stalled service costs the note
+ * its route, never the reader's command.
+ */
+const ROUTE_CHECK_WAIT_MS = 3_000;
+
+interface KeptAnswer { at: number; answer: Promise<boolean> }
+const answers = new WeakMap<FreeRoute, Map<string, KeptAnswer>>();
+
+/**
+ * Whether the route has data for the symbol, null when its check failed or was
+ * still out at the deadline. A check that answered is kept for the TTL; one
+ * that failed or ran out of time is dropped, so the next note checks again
+ * rather than hiding the route for minutes over one slow read.
+ */
+async function routeAnswers(route: FreeRoute, check: NonNullable<FreeRoute["answers"]>, symbol: string, context: HeadlessPaneContext, deadline: number): Promise<boolean | null> {
+  const bySymbol = answers.get(route) ?? new Map<string, KeptAnswer>();
+  answers.set(route, bySymbol);
+  const key = symbol.trim().toUpperCase();
+  let kept = bySymbol.get(key);
+  if (!kept || Date.now() - kept.at >= ANSWER_TTL_MS) {
+    // The check's own reads stop at the deadline where they take a signal.
+    const signal = signalWithTimeout(context.signal, Math.max(0, deadline - Date.now()));
+    const entry: KeptAnswer = { at: Date.now(), answer: check(symbol, { ...context, signal }) };
+    entry.answer.catch(logFailure("plugins.pro-lock-note", "Check a free route's data failed"));
+    bySymbol.set(key, entry);
+    kept = entry;
+  }
+  const answer = await settleWithin(kept.answer, Math.max(0, deadline - Date.now()));
+  if (answer === null && bySymbol.get(key) === kept) bySymbol.delete(key);
+  return answer;
+}
+
+/**
+ * The first of the routes, best first, that has data for the lock's symbol:
+ * GUIDE's guidance ranges where it covers the company, else its 8-Ks. The
+ * checks run together under one deadline, so a stalled first route neither
+ * holds the note past it nor keeps the next route from being named. Without a
+ * symbol the routes read `<ticker>` and the first is named; without a way to
+ * read data, only a route that answers for every symbol is.
+ */
+async function answeringFreeRoute(lock: PaneLock, routes: readonly FreeRoute[]): Promise<FreeRoute | null> {
+  const { symbol, context } = lock;
+  if (!symbol) return routes[0] ?? null;
+  // Routes past the first that needs no check are never named, so they are not checked.
+  const unchecked = routes.findIndex((route) => !route.answers);
+  const candidates = unchecked < 0 ? routes : routes.slice(0, unchecked + 1);
+  const deadline = Date.now() + ROUTE_CHECK_WAIT_MS;
+  const checks = candidates.map((route) => !route.answers ? Promise.resolve(true)
+    : context ? routeAnswers(route, route.answers, symbol, context, deadline) : Promise.resolve(false));
+  for (const [index, check] of checks.entries()) {
+    if (await check) return candidates[index]!;
+  }
+  return null;
+}
+
 /**
  * The `reportLockNote` of a pane its wall covers whole (`useProFeatureWall`, a
  * scanner's denied state): what the function is and that a wall shows none of
@@ -12,8 +92,8 @@ export function lockNoteReason(note: string): string {
  * to unlock it. One shape for every lock a reader meets in `fn`, so a refused
  * read never ends in a bare "Sign in required".
  */
-export function proLockNote(
-  { gate, symbol, token: typed, verifyEmail }: PaneLock,
+export async function proLockNote(
+  lock: PaneLock,
   pane: {
     /** The function's shortcut, such as `EK`; a pane that serves several names the one run in the lock. */
     token: string;
@@ -22,10 +102,10 @@ export function proLockNote(
     /** What the wall hides, as the object of "none of" and "to read": "it" or "them". */
     shows: "it" | "them";
     /**
-     * The free route and what it lists, finishing "Free, with no sign-in: ...".
-     * Name one only after running it signed out; leave it out when none answers.
+     * The free routes, best first: the note names the first with data for the
+     * symbol (`answeringFreeRoute`), or none.
      */
-    free?(ticker: string, company: string): string;
+    free?: readonly FreeRoute[];
     /** What the wall asks for: Gloom Cloud Pro (default), or only a free Gloom account. */
     needs?: "pro" | "sign-in";
     /**
@@ -35,7 +115,8 @@ export function proLockNote(
      */
     argument?: "ticker" | "optional" | "none";
   },
-): string {
+): Promise<string> {
+  const { gate, symbol, token: typed, verifyEmail } = lock;
   const token = typed ?? pane.token;
   const ticker = symbol ?? "<ticker>";
   // A plan refused at the server is Pro whatever the function usually asks for.
@@ -50,9 +131,10 @@ export function proLockNote(
     : `To read ${pane.shows} in ${token}, open the app (gloomberb), ${account}${pro ? ", then upgrade (Ctrl+P, UPGRADE)" : ""}`;
   const bare = pane.argument === "none" || (pane.argument === "optional" && !symbol);
   const command = bare ? `gloomberb fn ${token}` : `gloomberb fn ${token} ${ticker}`;
+  const free = pane.free ? await answeringFreeRoute(lock, pane.free) : null;
   return [
     `${token} ${what}: ${pane.does}. ${without} it shows none of ${pane.shows}.`,
-    ...pane.free ? [`Free, with no sign-in: ${pane.free(ticker, symbol ?? "the company")}`] : [],
+    ...free ? [`Free, with no sign-in: ${free.text(ticker, symbol ?? "the company")}`] : [],
     `${unlock}; ${command} then reads with that session.`,
   ].join("\n");
 }

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

@@ -0,0 +1,62 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { usePaneMenuItems } from "../../../components";
+import type { CompositeChartLevel } from "../../../components/chart/composite/levels";
+import { useShortcut } from "../../../react/input";
+import { useDialogState } from "../../../ui/dialog";
+import type { InstrumentRef } from "../../../market-data/request-types";
+import type { BrokerContractRef } from "../../../types/instrument";
+import { canonicalExchange, parsePublicTickerKey } from "../../../utils/exchanges";
+import { scopedBrokerContractIdentityKey } from "../../../utils/instrument-identity";
+
+export interface ResearchTradeProjection {
+  levels: readonly CompositeChartLevel[];
+  contract?: BrokerContractRef;
+  mode?: "simulation" | "live" | "unknown";
+  busy?: boolean;
+}
+export interface ResearchTrading extends ResearchTradeProjection {
+  symbol: string;
+  /** A trading-capable broker profile is enabled, so t leads somewhere. */
+  available?: boolean;
+  docked: boolean;
+  visible: boolean;
+  /** The docked ticket holds focus; the chart beside it only sees keys the ticket leaves. */
+  ticketFocused?: boolean;
+  /** Opens the ticket; without a side it keeps its draft, and Buy or Sell is chosen in it. */
+  open(side?: "BUY" | "SELL"): void;
+  close(): void;
+  /** This ticker's working orders and latest fills, for Overview; absent without a trading profile. */
+  orders?(width: number): ReactNode;
+  publish(projection: ResearchTradeProjection): void;
+}
+const Context = createContext<ResearchTrading | null>(null);
+export const ResearchTradingProvider = Context.Provider;
+export const useResearchTrading = () => useContext(Context);
+
+/** Never put an option premium or another venue's price on the underlying chart. */
+export function researchTradeMatches(trade: ResearchTradeProjection | null, listing: InstrumentRef | null): boolean {
+  const contract = trade?.contract;
+  if (!contract || !listing) return false;
+  if (listing.instrument) return scopedBrokerContractIdentityKey(contract) === scopedBrokerContractIdentityKey(listing.instrument);
+  if (contract.secType && !["STK", "ETF"].includes(contract.secType)) return false;
+  if (contract.symbol.toUpperCase() !== parsePublicTickerKey(listing.symbol).symbol.toUpperCase()) return false;
+  const exchange = canonicalExchange(listing.exchange ?? parsePublicTickerKey(listing.symbol).exchange);
+  // SMART is a route, not a listing: a share a broker routes is on any of its venues.
+  const venue = [contract.exchange, contract.primaryExchange].map(canonicalExchange).find((name) => name && name !== "SMART");
+  return !venue || !exchange || venue === exchange;
+}
+
+/** Trade stays in the pane menu and keyboard, not the range toolbar: one key, and the ticket picks the side. */
+export function ResearchTradeActions({ focused }: { focused: boolean }) {
+  const trade = useResearchTrading();
+  const dialog = useDialogState((state) => state.isOpen);
+  useShortcut((event) => {
+    if (!trade || trade.ticketFocused || event.defaultPrevented || event.propagationStopped || event.targetEditable || event.ctrl || event.alt || event.meta || event.shift || event.super || event.repeat) return;
+    if (event.name !== "t") return;
+    event.preventDefault(); event.stopPropagation(); trade.open();
+  }, { enabled: focused && !!trade && !dialog, phase: "before", scope: "research:trade-open" });
+  usePaneMenuItems("research:trade-open", () => trade ? [
+    { id: "trade-open", label: "Trade", accelerator: "t", enabled: !trade.busy, onSelect: () => trade.open() },
+  ] : null, [trade]);
+  return null;
+}

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

@@ -18,7 +18,7 @@ export const socialMentionsHeadless: HeadlessPaneDefinition<"bundle"> = {
     const range = (["1y", "5y", "max"].includes(String(args.options.range)) ? args.options.range : "1y") as SocialMentionsRange;
     const symbol = String(args.symbols[0]).toUpperCase();
     const data = await fetchSocialMentions(symbol, range, ctx.apiClient)
-      .catch((error: unknown) => { throw explainRefusal(error, socialMentionsLockNote, { symbol }); });
+      .catch(async (error: unknown) => { throw await explainRefusal(error, socialMentionsLockNote, { symbol, context: ctx }); });
     return { complete: !data.pending.length, errors: data.warnings,
       sections: [{ title: "Daily posts on X", columns: [
         { key: "day", header: "Date" },

package/src/plugins/builtin/social-mentions/lock-note.ts

@@ -5,7 +5,7 @@ import { proLockNote } from "../shared/pro-lock-note";
  * BUZZ needs a signed-in account, not a plan. No command reads the posts it
  * counts without one, so the note names no free route.
  */
-export function socialMentionsLockNote(lock: PaneLock): string {
+export function socialMentionsLockNote(lock: PaneLock): Promise<string> {
   return proLockNote(lock, {
     token: "BUZZ",
     needs: "sign-in",

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

@@ -4,11 +4,15 @@ import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneFreshness
 import { formatRelativeAge } from "../../../utils/datetime-format";
 import { fetchThemeMembers, fetchThemes } from "./client";
 import {
-  aggregateText, boardClose, DEFAULT_SORT, matchTheme, memberExtended, memberExtendedSessions, memberPrice, percent, PERIOD_LABELS,
+  aggregateText, boardClose, boardYtdBase, DEFAULT_SORT, matchTheme, memberExtended, memberExtendedSessions, memberPrice, percent, periodLabel,
   SNAPSHOT_STALE_MS, sortMembers, sortThemes,
 } from "./model";
 
-const periods: HeadlessPaneColumn[] = THEME_PERIODS.map((key) => ({ key, header: PERIOD_LABELS[key], align: "right", format: (value) => percent(value as number | null) }));
+/** The period columns; YTD names the close it is measured from, `YTD vs 31 Dec close`. */
+const periodColumns = (payload: ThemesPayload | ThemeMembersPayload): HeadlessPaneColumn[] => {
+  const base = boardYtdBase(payload);
+  return THEME_PERIODS.map((key) => ({ key, header: periodLabel(key, base), align: "right", format: (value) => percent(value as number | null) }));
+};
 
 /** The pre-market or after-hours print and its move from the regular close in Price, for the members that have one. */
 function extendedColumn(session: ExtendedSession): HeadlessPaneColumn {
@@ -90,6 +94,7 @@ export const themesHeadless: HeadlessPaneDefinition<"rows"> = {
       const observation = boardObservation(data);
       // Price and 1D are the regular session's; an extended print gets a column only when a member has one.
       const extendedSessions = memberExtendedSessions(data.members);
+      const periods = periodColumns(data);
       return { rows: sortMembers(data.members, DEFAULT_SORT).map((row) => {
         const extended = memberExtended(row);
         return { ...row, extendedSession: extended?.session ?? null, extendedPrice: extended?.price ?? null,
@@ -104,6 +109,7 @@ export const themesHeadless: HeadlessPaneDefinition<"rows"> = {
         metadata: { ...observation.metadata, theme: data.theme } };
     }
     const observation = boardObservation(board);
+    const periods = periodColumns(board);
     return { rows: sortThemes(board.themes, DEFAULT_SORT).map((row) => ({ name: row.name, memberCount: row.memberCount,
       ...Object.fromEntries(THEME_PERIODS.map((period) => [period, row.returns[period].value])), breadth: row.breadth.value, coverage: row.returns,
       breadthCoverage: row.breadth, best: row.best?.symbol ?? null, worst: row.worst?.symbol ?? null })),

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

@@ -2,9 +2,29 @@ import { THEME_PERIODS, type ThemeAggregate, type ThemeMember, type ThemePeriod,
 import type { DataTableColumn } from "../../../components";
 import { dropColumnsToFit, getTableWidth } from "../../../components/ui/table-layout";
 import { extendedSessionStateLabel, type ExtendedSession } from "../../../market-data/market/status";
+import { yearToDateBaseLabel } from "../../../market-data/market/year-to-date";
 import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
 
-export const PERIOD_LABELS: Record<ThemePeriod, string> = { changePercent: "1D", return1WPercent: "1W", return1MPercent: "1M", return3MPercent: "3M", returnYtdPercent: "YTD" };
+const PERIOD_LABELS: Record<ThemePeriod, string> = { changePercent: "1D", return1WPercent: "1W", return1MPercent: "1M", return3MPercent: "3M", returnYtdPercent: "YTD" };
+
+/**
+ * The close a board's YTD is measured from, `31 Dec`: NYSE's last session of
+ * the year before the session the board describes, as the server measures it.
+ */
+export function boardYtdBase(payload: { asOf?: unknown; regularSessionDate?: unknown; regularSessionClosedAt?: unknown }, now = Date.now()): string {
+  const day = boardClose(payload)?.date ?? (typeof payload.asOf === "string" && /^\d{4}-\d{2}-\d{2}/.test(payload.asOf) ? payload.asOf.slice(0, 10) : new Date(now).toISOString().slice(0, 10));
+  return yearToDateBaseLabel(day, "NYSE", now);
+}
+
+/**
+ * A period's header. YTD names its base close, as long as `room` allows:
+ * `YTD vs 31 Dec close`, `YTD vs 31 Dec`, then `YTD 31 Dec`.
+ */
+export function periodLabel(period: ThemePeriod, ytdBase: string | null, room = Infinity): string {
+  if (period !== "returnYtdPercent" || !ytdBase) return PERIOD_LABELS[period];
+  const labels = [`YTD vs ${ytdBase} close`, `YTD vs ${ytdBase}`, `YTD ${ytdBase}`];
+  return labels.find((label) => label.length <= room) ?? labels.at(-1)!;
+}
 export interface ThemeSort { columnId: string; direction: SortDirection }
 export const DEFAULT_SORT: ThemeSort = { columnId: "changePercent", direction: "desc" };
 export function percent(value: number | null): string {
@@ -110,17 +130,27 @@ export function matchTheme(rows: readonly ThemeSummary[], input: string): ThemeS
 }
 
 const column = (id: string, label: string, width: number, align: "left" | "right" = "right"): DataTableColumn => ({ id, label, width, align });
-/** Drop leaders/laggards first, then longer windows; keep the day's move and breadth. */
-export function themeColumns(width: number, rows: readonly ThemeSummary[]): DataTableColumn[] {
+/** Room a header has in its column: the sort indicator takes two cells. */
+const HEADER_ROOM = 2;
+/**
+ * Drop leaders/laggards first, then longer windows; keep the day's move and
+ * breadth. YTD names `ytdBase`, the close it is measured from, as fully as
+ * its column allows.
+ */
+export function themeColumns(width: number, rows: readonly ThemeSummary[], ytdBase: string | null = null): DataTableColumn[] {
   const suffixWidth = (period: ThemePeriod) => coverageWidth(rows.map((row) => row.returns[period]));
   const metricWidth = (period: ThemePeriod) => Math.max(8, ...rows.map((row) => percent(row.returns[period].value).length)) + suffixWidth(period);
+  // The same trailing space is reserved in every cell and its header. A note
+  // occupies that space without moving the number away from its label.
+  const label = (period: ThemePeriod, room?: number) => periodLabel(period, ytdBase, room) + " ".repeat(suffixWidth(period));
   const columns = [column("name", "Theme", 26, "left"), column("memberCount", "N", 3),
-    // The same trailing space is reserved in every cell and its header. A note
-    // occupies that space without moving the number away from its label.
-    ...THEME_PERIODS.map((period) => column(period, PERIOD_LABELS[period] + " ".repeat(suffixWidth(period)), metricWidth(period))),
+    ...THEME_PERIODS.map((period) => column(period, label(period, 0), Math.max(metricWidth(period), label(period, 0).length + HEADER_ROOM))),
     column("breadth", "Breadth" + " ".repeat(coverageWidth(rows.map((row) => row.breadth))), 7 + coverageWidth(rows.map((row) => row.breadth))),
     column("best", "Best 1D", 15), column("worst", "Worst 1D", 15)];
-  return fitColumns(columns, width, ["worst", "best", "return3MPercent", "returnYtdPercent", "return1MPercent", "return1WPercent", "memberCount"]);
+  const fitted = fitColumns(columns, width, ["worst", "best", "return3MPercent", "returnYtdPercent", "return1MPercent", "return1WPercent", "memberCount"]);
+  const ytd = fitted.find((col) => col.id === "returnYtdPercent");
+  if (ytd) ytd.label = label("returnYtdPercent", ytd.width - HEADER_ROOM - suffixWidth("returnYtdPercent"));
+  return fitted;
 }
 /**
  * The member table at `width`. Price and 1D are the regular session's; a
@@ -128,12 +158,15 @@ export function themeColumns(width: number, rows: readonly ThemeSummary[]): Data
  * each session in `extendedSessions`. A narrow pane gives up the longer
  * windows first, then that column, then the name.
  */
-export function memberColumns(width: number, extendedSessions: readonly ExtendedSession[] = []): DataTableColumn[] {
+export function memberColumns(width: number, extendedSessions: readonly ExtendedSession[] = [], ytdBase: string | null = null): DataTableColumn[] {
   const extended = extendedSessions.map((session) => column(session === "PRE" ? "preMarket" : "afterHours", extendedSessionStateLabel(session), 9));
-  const [day, ...windows] = THEME_PERIODS.map((period) => column(period, PERIOD_LABELS[period], 9));
-  return fitColumns([column("symbol", "Ticker", 7, "left"), column("name", "Name", 24, "left"), column("price", "Price $", 10),
+  const [day, ...windows] = THEME_PERIODS.map((period) => column(period, periodLabel(period, ytdBase, 0), Math.max(9, periodLabel(period, ytdBase, 0).length + HEADER_ROOM)));
+  const fitted = fitColumns([column("symbol", "Ticker", 7, "left"), column("name", "Name", 24, "left"), column("price", "Price $", 10),
     day!, ...extended, ...windows], width,
   ["return3MPercent", "returnYtdPercent", "return1MPercent", "return1WPercent", "preMarket", "afterHours", "name", "price"]);
+  const ytd = fitted.find((col) => col.id === "returnYtdPercent");
+  if (ytd) ytd.label = periodLabel("returnYtdPercent", ytdBase, ytd.width - HEADER_ROOM);
+  return fitted;
 }
 function fitColumns(columns: DataTableColumn[], width: number, drop: string[]): DataTableColumn[] {
   columns = dropColumnsToFit(columns, width, drop);

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

@@ -1,6 +1,6 @@
 import { useCallback, useMemo, type ReactNode } from "react";
 import type { ThemeMember, ThemePeriod, ThemeSummary } from "../../../api-client/themes";
-import { DataTableStackView, DataTableView, PaneStatusBody, usePaneNoticeFooter, usePaneStatusFooter, type DataTableCell, type DataTableColumn } from "../../../components";
+import { splitDelayedStatus, DataTableStackView, DataTableView, PaneStatusBody, usePaneNoticeFooter, usePaneStatusFooter, type DataTableCell, type DataTableColumn } from "../../../components";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import type { ExtendedSession } from "../../../market-data/market/status";
 import { useAsyncResource, useAutoRefresh, usePluginPaneState, usePluginTickerActions, useUpdatedAgo } from "../../../public/react";
@@ -12,7 +12,7 @@ import { nextHeaderSort } from "../../../utils/sort-values";
 import { useMembersMenu } from "../shared/members-menu";
 import { cachedMembers, cachedThemes, loadMembers, loadThemes } from "./client";
 import {
-  aggregateText, coverageWidth, DEFAULT_SORT, extendedMove, matchTheme, memberColumns, memberExtendedSessions, memberPrice, percent,
+  aggregateText, boardYtdBase, coverageWidth, DEFAULT_SORT, extendedMove, matchTheme, memberColumns, memberExtendedSessions, memberPrice, percent,
   SNAPSHOT_STALE_MS, snapshotFooterText, sortMembers, sortThemes, themeColumns, type ThemeSort,
 } from "./model";
 
@@ -24,7 +24,7 @@ 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 ? [{ id: "snapshot", parts: [{ text, tone: "muted" as const }] }] : [], [text]);
+  const info = useMemo(() => text ? 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,
@@ -45,8 +45,10 @@ function Members({ id, width, height, focused }: { id: string; width: number; he
   const rows = useMemo(() => sortMembers(data?.members ?? [], sort), [data, sort]);
   // Price and 1D are the regular session's; a pre-market or after-hours print gets its own column when a member has one.
   const extendedSessionsKey = useMemo(() => memberExtendedSessions(data?.members ?? []).join(","), [data]);
-  const columns = useMemo(() => memberColumns(width, extendedSessionsKey ? extendedSessionsKey.split(",") as ExtendedSession[] : []),
-    [extendedSessionsKey, width]);
+  // YTD names the close it is measured from, `31 Dec`.
+  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);
   usePaneRefreshKey(() => void resource.reload(), { focused });
   useSnapshotFooter("themes:members", resource, focused);
@@ -103,7 +105,7 @@ export function ThemesBoard({ width, height, focused, tabStrip, tabRows = 0 }: T
   const resource = useAsyncResource(loadThemes, { initialData: cachedThemes });
   const data = resource.data?.payload;
   const rows = useMemo(() => sortThemes(data?.themes ?? [], sort), [data, sort]);
-  const columns = useMemo(() => themeColumns(width, data?.themes ?? []), [width, data]);
+  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);
   usePaneRefreshKey(() => void resource.reload(), { focused, enabled: !opened });