gloomberb 0.18.0 → 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/broker-reconnect.ts

@@ -0,0 +1,105 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import { signedInBrokerForProfile } from "../../../brokers/signed-in/connect";
+import { isSignedInBrokerProfile } from "../../../brokers/signed-in/profile";
+import { requestBrokerSignIn } from "../../../brokers/signed-in/sign-in-dialog";
+import type { PaneFooterSegment, PaneHint } from "../../../components/layout/pane/footer/model";
+import { t, tf } from "../../../i18n";
+import type { BrokerInstanceConfig } from "../../../types/config";
+import { formatShortDate } from "../../../utils/datetime-format";
+import { usePluginAppActions, usePluginBrokerActions } from "../../runtime";
+
+/** A broker profile Gloom cannot reach right now, so what a pane shows of it is from its last sync. */
+export interface OfflineBroker {
+  instance: BrokerInstanceConfig;
+  brokerName: string;
+  /** When the profile last synced its positions, or null when it never has. */
+  syncedAt: number | null;
+  /** Why it is offline, in the broker's words when it gave some. */
+  reason: string;
+  /** False when no plugin connects it, so pressing a key could not help. */
+  reconnectable: boolean;
+}
+
+/** The key onboarding gives "Connect a broker". */
+const RECONNECT_BROKER_KEY = "b";
+
+/** `as of 14:02` today, `as of Oct 17 14:02` before. */
+function formatBrokerSyncedAt(syncedAt: number, now = Date.now()): string {
+  const date = new Date(syncedAt);
+  const time = date.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit", hour12: false });
+  const today = date.toDateString() === new Date(now).toDateString();
+  return today
+    ? tf("as of {time}", { time })
+    : tf("as of {date} {time}", { date: formatShortDate(date, { year: false }), time });
+}
+
+export interface OfflineBrokerFooter {
+  /** `as of …`, when the profile has synced. */
+  asOf: PaneFooterSegment[];
+  /** Why the broker is offline, or that it is reconnecting. */
+  status: PaneFooterSegment[];
+  hints: PaneHint[];
+}
+
+const ONLINE: OfflineBrokerFooter = { asOf: [], status: [], hints: [] };
+
+/**
+ * Footer status and key for a pane showing a broker that is offline: when its
+ * positions were synced, why it is offline, and `[b] reconnect`. Reconnecting
+ * does what Connect does in Brokers (a signed-in broker asks for a new
+ * sign-in, any other connects), then syncs the profile so the positions are
+ * current again. Nothing changes on screen until that sync lands.
+ */
+export function useOfflineBrokerFooter(offline: OfflineBroker | null): OfflineBrokerFooter {
+  const { connectBrokerInstance, syncBrokerInstance } = usePluginBrokerActions();
+  const { notify } = usePluginAppActions();
+  const [reconnecting, setReconnecting] = useState(false);
+  const runningRef = useRef(false);
+  const offlineRef = useRef(offline);
+  offlineRef.current = offline;
+
+  const reconnect = useCallback(async () => {
+    const target = offlineRef.current;
+    if (!target?.reconnectable || runningRef.current) return;
+    runningRef.current = true;
+    setReconnecting(true);
+    try {
+      if (isSignedInBrokerProfile(target.instance)) {
+        if (!await requestBrokerSignIn(signedInBrokerForProfile(target.instance, target.brokerName))) return;
+      } else {
+        await connectBrokerInstance(target.instance.id);
+      }
+      await syncBrokerInstance(target.instance.id);
+    } catch (error) {
+      notify({
+        type: "error",
+        body: error instanceof Error ? error.message : tf("Could not reconnect {broker}.", { broker: target.brokerName }),
+      });
+    } finally {
+      runningRef.current = false;
+      setReconnecting(false);
+    }
+  }, [connectBrokerInstance, notify, syncBrokerInstance]);
+
+  return useMemo(() => {
+    if (!offline) return ONLINE;
+    // Dates the positions, not the quotes, so a shot that dates its quotes keeps it.
+    const asOf: PaneFooterSegment[] = offline.syncedAt != null
+      ? [{ id: "broker-as-of", asOf: false, parts: [{ text: formatBrokerSyncedAt(offline.syncedAt), tone: "muted" }] }]
+      : [];
+    const status: PaneFooterSegment[] = [reconnecting
+      ? { id: "broker-status", parts: [{ text: t("Reconnecting…"), tone: "muted" }] }
+      : { id: "broker-status", parts: [{ text: offline.reason, tone: "warning" }] }];
+    const hints: PaneHint[] = offline.reconnectable
+      ? [{
+          id: "reconnect-broker",
+          key: RECONNECT_BROKER_KEY,
+          label: " reconnect",
+          title: tf("Reconnect {broker}", { broker: offline.brokerName }),
+          onPress: () => { void reconnect(); },
+          disabled: reconnecting,
+        }]
+      : [];
+    return { asOf, status, hints };
+  }, [offline, reconnect, reconnecting]);
+}

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-feature-wall.tsx

@@ -23,8 +23,11 @@ export type ReadGuard = <T>(read: Promise<T>) => Promise<T>;
  * then upgrade. The session's plan decides before anything loads. Reads go
  * through `guard`, so a refusal from the server (a plan that ended while the
  * app was open, an expired session) shows the same wall, not an error.
+ *
+ * `preview`: the pane opens on every plan, the server serving a preview
+ * without Pro (EXEC), so only a refusal puts up the wall.
  */
-export function useProFeatureWall(copy: ProFeatureWallCopy, size: { width: number; height: number }): {
+export function useProFeatureWall(copy: ProFeatureWallCopy, size: { width: number; height: number }, options: { preview?: boolean } = {}): {
   wall: ReactNode;
   guard: ReadGuard;
 } {
@@ -39,12 +42,14 @@ export function useProFeatureWall(copy: ProFeatureWallCopy, size: { width: numbe
     throw error;
   }), []);
 
+  // A preview pane is walled by the server's answer alone, never by the plan up front.
+  const gated = !options.preview;
   let wall: ReactNode = null;
-  if (!access.signedIn || refused === 401) {
+  if ((gated && !access.signedIn) || refused === 401) {
     wall = <SignInWall placement={`${copy.placement.replace(/-wall$/, "")}-signin`} {...size} symbol={symbol} exchange={exchange} action={copy.action} />;
-  } else if (!access.emailVerified || refused === 403) {
+  } else if ((gated && !access.emailVerified) || refused === 403) {
     wall = <SignInWall placement={`${copy.placement.replace(/-wall$/, "")}-signin`} {...size} symbol={symbol} exchange={exchange} action={copy.action} needsVerification />;
-  } else if (!access.hasProAccess || refused === 402) {
+  } else if ((gated && !access.hasProAccess) || refused === 402) {
     wall = <ProWall placement={copy.placement} title={copy.title} message={copy.message} {...size} symbol={symbol} exchange={exchange} />;
   }
   return { wall, guard };

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 })),