gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/portfolio-list/summary/live-accounts.ts

@@ -9,6 +9,7 @@ import { usePluginBrokerActions } from "../../../runtime";
 import type { OfflineBroker } from "../../shared/broker-reconnect";
 import { tf } from "../../../../i18n";
 import { isSignedInBrokerProfile, signedInBrokerId } from "../../../../brokers/signed-in/profile";
+import { accountsShownFor } from "../../../../brokers/broker-portfolio-sync";
 import { resolvePortfolioAccountState, type ResolvedPortfolioAccountState } from "./index";
 
 const EMPTY_ACCOUNTS = { instanceId: null, accounts: [] as BrokerAccount[], error: null };
@@ -98,9 +99,10 @@ export interface PortfolioAccountStateResult {
 
 /**
  * The broker behind a portfolio while Gloom cannot reach it: disconnected,
- * failing, or without the plugin that connects it. Null while it is connected
- * or connecting, before it reports a status, for a profile turned off, and for
- * one that only syncs on demand (IBKR Flex), which is never connected.
+ * failing, without the plugin that connects it, or turned off (`disabled`),
+ * which nothing syncs until it is enabled. Null while it is connected or
+ * connecting, before it reports a status, and for one that only syncs on
+ * demand (IBKR Flex), which is never connected.
  */
 export function resolveOfflineBroker(
   portfolio: Portfolio | null,
@@ -108,16 +110,20 @@ export function resolveOfflineBroker(
   broker: BrokerAdapter | null | undefined,
   status: BrokerConnectionStatus | null,
 ): OfflineBroker | null {
-  if (!portfolio || !brokerInstance || brokerInstance.enabled === false) return null;
+  if (!portfolio || !brokerInstance) return null;
   const syncedAt = portfolio.lastSyncedAt ?? brokerInstance.lastSyncedAt ?? null;
+  // A profile signed in through Gloom names its broker, not the adapter it needs.
+  const brokerName = broker
+    ? broker.describeInstance?.(brokerInstance).brokerName ?? broker.name
+    : (isSignedInBrokerProfile(brokerInstance) ? signedInBrokerId(brokerInstance) : brokerInstance.brokerType).toUpperCase();
+  if (brokerInstance.enabled === false) {
+    return { instance: brokerInstance, brokerName, syncedAt, reason: tf("{broker} disabled", { broker: brokerName }), reconnectable: !!broker, disabled: true };
+  }
   if (!broker) {
-    // A profile signed in through Gloom names its broker, not the adapter it needs.
-    const brokerName = (isSignedInBrokerProfile(brokerInstance) ? signedInBrokerId(brokerInstance) : brokerInstance.brokerType).toUpperCase();
     return { instance: brokerInstance, brokerName, syncedAt, reason: tf("{broker} unavailable", { broker: brokerName }), reconnectable: false };
   }
   if (!status || status.state === "connected" || status.state === "connecting") return null;
   if (status.mode?.toLowerCase() === "flex") return null;
-  const brokerName = broker.describeInstance?.(brokerInstance).brokerName ?? broker.name;
   const reason = status.state === "error"
     ? status.message?.trim() || tf("{broker} unavailable", { broker: brokerName })
     : tf("{broker} disconnected", { broker: brokerName });
@@ -141,9 +147,10 @@ export function usePortfolioAccountState(
   const { getBrokerAdapter } = usePluginBrokerActions();
   const broker = brokerInstance ? getBrokerAdapter(brokerInstance.brokerType) : null;
   const live = useLiveBrokerAccounts(broker, brokerInstance, instanceId ? state.brokerAccounts[instanceId] : undefined);
+  // An account another profile holds under its own number is that profile's, here as in sync.
   const snapshot = useMemo(
-    () => ({ status: live.status, accounts: live.accounts }),
-    [live.accounts, live.status],
+    () => ({ status: live.status, accounts: brokerInstance ? accountsShownFor(state.config, brokerInstance, live.accounts) : live.accounts }),
+    [brokerInstance, live.accounts, live.status, state.config],
   );
   const accountState = useMemo(
     () => resolvePortfolioAccountState(portfolio, state, snapshot),

package/src/plugins/builtin/portfolio-list/summary/totals.ts

@@ -1,12 +1,11 @@
 import type { TickerFinancials } from "../../../../types/financials";
-import type { Portfolio, TickerRecord } from "../../../../types/ticker";
+import type { TickerRecord } from "../../../../types/ticker";
 import { convertCurrency, formatCompactAmount } from "../../../../utils/format";
 import { getCurrencySymbol } from "../../../../market-data/market/format";
 import { getActiveQuoteDisplay } from "../../../../market-data/market/status";
 import { combinedChangeBasisLabel, quoteChangeBasis, type QuoteChangeBasis } from "../../../../market-data/market/change-basis";
 import { isQuoteStaleForCurrentSession } from "../../../../market-data/quotes/freshness";
 import { headlineQuoteDisplay } from "../../../../portfolio/column-values";
-import { isManualPortfolio } from "../../../../portfolio/mutations";
 import type { AllocationHolding } from "../../../../portfolio/allocation";
 import { getPortfolioValuationDisplay, type PortfolioValuationBasis } from "../../../../portfolio/valuation-basis";
 import type { PortfolioFuturesTerms } from "../../../../portfolio/futures-positions";
@@ -76,19 +75,7 @@ function currencyCode(value: string | undefined): string | null {
   return CURRENCY_CODE.test(code) ? code : null;
 }
 
-/**
- * The currency a portfolio's totals, market values and P&L are in. A broker
- * portfolio uses its account currency. A manual portfolio uses its stored
- * currency with the default USD base (its first holding sets it, see
- * adoptFirstPositionCurrency); a base currency the user chose is what manual
- * portfolios and watchlists total in.
- */
-export function resolvePortfolioTotalsCurrency(portfolio: Portfolio | null | undefined, baseCurrency: string): string {
-  const base = currencyCode(baseCurrency) ?? "USD";
-  if (!portfolio) return base;
-  if (isManualPortfolio(portfolio) && base !== "USD") return base;
-  return currencyCode(portfolio.currency) ?? base;
-}
+export { resolvePortfolioTotalsCurrency } from "../../../../portfolio/totals-currency";
 
 /**
  * A compact total in the portfolio's currency. Bare when both it and the app's

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

@@ -15,7 +15,10 @@ const nullableText = (v: unknown) => v === null || text(v);
 const nonnegative = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v) && v >= 0;
 const integer = (v: unknown) => nonnegative(v) && Number.isInteger(v);
 const instant = (v: unknown) => text(v) && Number.isFinite(Date.parse(v));
-const url = (v: unknown) => { try { return text(v) && new URL(v).protocol === "https:"; } catch { return false; } };
+const url = (v: unknown) => { try { return text(v) && new URL(v).protocol === "https:"; } catch {
+  // Intentional ignore: malformed URLs fail this HTTPS field validator.
+  return false;
+} };
 const access = (v: unknown) => v === "full" || v === "preview";
 const entities = (v: unknown) => Array.isArray(v) && v.every((e) => record(e) && text(e.name) && text(e.entityId)
   && ["utility", "developer"].includes(e.role) && nonnegative(e.confidence) && e.confidence <= 1

package/src/plugins/builtin/power/evidence.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import type { CarbonBoard, CarbonHistory, EuropePowerBoard, EuropePowerHistory, GasStorageBoard, GasStorageSeasonal } from "../../../api-client/europe-energy";
 import type { PowerBoard, PowerHistory } from "../../../api-client/power";
 import type { PaneScreenshotEvidenceHook } from "../../../cli/pane-functions/screenshot-evidence";
@@ -21,6 +22,7 @@ interface PowerEvidence {
   /** The day-ahead board and the EUA board, on the Prices tab. */
   prices?: EuropePowerBoard | null;
   carbon?: CarbonBoard | null;
+  carbonError?: string;
   /** The gas storage board, on the Prices tab's gas board. */
   gas?: GasStorageBoard | null;
   tab: string;
@@ -33,6 +35,8 @@ export interface PowerPricesSnapshot {
   history: EuropePowerHistory | CarbonHistory | null;
   /** Null when the server has no EUA price yet; the tab then shows the board alone. */
   carbon: CarbonBoard | null;
+  /** A completed optional read that failed; older snapshots omit this field. */
+  carbonError?: string;
 }
 /** What the gas board draws, frozen by `shot`: the board and the selected area's seasonal range. */
 export interface GasStorageSnapshot {
@@ -45,10 +49,10 @@ export function usePowerEvidence(board: PowerBoard | undefined, history: PowerHi
     plottedValueCount: rowIds.length, board, history: history ?? null, tab, rowIds,
   }) });
 }
-export function usePowerPricesEvidence(prices: EuropePowerBoard | null, carbon: CarbonBoard | null, rowIds: string[], loading: boolean) {
+export function usePowerPricesEvidence(prices: EuropePowerBoard | null, carbon: CarbonBoard | null, rowIds: string[], loading: boolean, carbonError?: string | null) {
   useRemoteUiNode({ role: "chart-data", label: "Rendered day-ahead power and carbon prices", getMetadata: () => ({
     kind: "power", version: 1, complete: !!prices && !loading, ready: !!prices && !loading,
-    plottedValueCount: rowIds.length, board: null, history: null, prices, carbon, tab: "prices", rowIds,
+    plottedValueCount: rowIds.length, board: null, history: null, prices, carbon, ...(carbonError ? { carbonError } : {}), tab: "prices", rowIds,
   }) });
 }
 export function useGasStorageEvidence(gas: GasStorageBoard | null, rowIds: string[], loading: boolean) {
@@ -71,13 +75,19 @@ export const powerScreenshotEvidence: PaneScreenshotEvidenceHook<PowerEvidence>
     }
     if (tab === "prices") {
       const board = await fetchPowerPrices();
-      // The carbon figures are captured when the server has them, and left out when it does not.
-      const carbon = await fetchCarbonPrice().catch(() => null);
+      // Optional carbon failure travels with the board, just as it does in the live pane.
+      let carbonError: string | undefined;
+      const carbon = await fetchCarbonPrice().catch((error: unknown) => {
+        logFailure("power.evidence", "Load carbon price for capture failed")(error);
+        const message = error instanceof Error ? error.message : String(error);
+        carbonError = message.trim() ? message : "Request failed";
+        return null;
+      });
       const arg = resolved.createOptions?.arg;
       const market = powerPriceMarket(arg)?.code ?? DEFAULT_PRICE_MARKET;
       const history = isCarbonQuery(arg) && carbon?.row.date ? await fetchCarbonHistory()
         : board.rows.some((row) => row.code === market && row.date) ? await fetchPowerPriceHistory(market) : null;
-      return { settings: { powerPricesSnapshot: { board, history, carbon } satisfies PowerPricesSnapshot }, financials: [] };
+      return { settings: { powerPricesSnapshot: { board, history, carbon, ...(carbonError ? { carbonError } : {}) } satisfies PowerPricesSnapshot }, financials: [] };
     }
     const symbol = resolved.createOptions?.symbol ?? resolved.createOptions?.arg;
     const filter = powerQuery({ ...settings, ...resolved.options, tab }, symbol);
@@ -103,6 +113,7 @@ export const powerScreenshotEvidence: PaneScreenshotEvidenceHook<PowerEvidence>
         if (!isRecord(value.prices)) return null;
         const prices = validatePowerPrices(value.prices as unknown as EuropePowerBoard);
         if (value.carbon != null) validateCarbonPrice(value.carbon as unknown as CarbonBoard);
+        if (value.carbonError !== undefined && (typeof value.carbonError !== "string" || !value.carbonError.trim() || value.carbon != null)) return null;
         if (value.rowIds.some((id) => !prices.rows.some((row) => row.code === id))) return null;
         return value as unknown as PowerEvidence;
       }
@@ -112,7 +123,10 @@ export const powerScreenshotEvidence: PaneScreenshotEvidenceHook<PowerEvidence>
       const rows = ["queue", "loads", "capacity"].includes(tab) ? projectRows(board.projects) : otherRows(tab, board, history?.points ?? []);
       if (value.rowIds.some((id) => !rows.some((r) => r.id === id))) return null;
       return value as unknown as PowerEvidence;
-    } catch { return null; }
+    } catch {
+      // Intentional ignore: invalid captured observations are rejected as evidence by returning null.
+      return null;
+    }
   },
   mismatches(evidence, { resolved, payload }) {
     const settings = instanceSettings(payload);
@@ -123,7 +137,8 @@ export const powerScreenshotEvidence: PaneScreenshotEvidenceHook<PowerEvidence>
     } else if (evidence.tab === "prices") {
       const snapshot = settings?.powerPricesSnapshot;
       if (!isRecord(snapshot) || JSON.stringify(snapshot.board) !== JSON.stringify(evidence.prices)
-        || JSON.stringify(snapshot.carbon ?? null) !== JSON.stringify(evidence.carbon ?? null)) errors.push("Power prices differ from the captured data.");
+        || JSON.stringify(snapshot.carbon ?? null) !== JSON.stringify(evidence.carbon ?? null)
+        || (snapshot.carbonError ?? null) !== (evidence.carbonError ?? null)) errors.push("Power prices differ from the captured data.");
     } else {
       const snapshot = settings?.powerSnapshot;
       if (!isRecord(snapshot) || JSON.stringify(snapshot.board) !== JSON.stringify(evidence.board)

package/src/plugins/builtin/power/gas.tsx

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { useCallback, useMemo } from "react";
 import type { GasStorageRow } from "../../../api-client/europe-energy";
 import {
@@ -99,7 +100,10 @@ export function GasStorageView({ width, height, focused, snapshot }: {
   const frozen = useMemo(() => {
     try {
       return snapshot ? { board: validateGasStorage(snapshot.board), seasonal: snapshot.seasonal ? validateGasSeasonal(snapshot.seasonal) : null } : null;
-    } catch { return null; }
+    } catch (error) {
+      logFailure("power.gas", "Validate gas storage snapshot failed")(error);
+      return null;
+    }
   }, [snapshot]);
   const resource = useAsyncResource(frozen ? null : loadGasStorage, { initialData: getCachedGasStorage });
   const board = frozen?.board ?? resource.data?.payload ?? null;

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

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { useCallback, useEffect, useMemo, useRef } from "react";
 import type { PowerBoard, PowerFilter, PowerHistory } from "../../../api-client/power";
 import { isAccessDenied } from "../../../api-client/errors";
@@ -8,6 +9,7 @@ import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActi
 import { useThemeColors } from "../../../theme/theme-context";
 import type { PaneProps } from "../../../types/plugin";
 import { Box, Text, TextAttributes, useRendererHost, useUiCapabilities, type ScrollBoxRenderable } from "../../../ui";
+import { withCountryFlag } from "../../../components/ui/country-flag";
 import { publicTickerKey } from "../../../utils/exchanges";
 import { getSharedRegistry } from "../../registry/shared";
 import { usePaneInstance } from "../../../state/app/context";
@@ -86,7 +88,10 @@ function PowerView({ width, height, focused, scope, needsVerification }: PanePro
   const searchFocus = useQueryBarSearch();
   const [snapshotSetting] = usePaneSettingValue<{ board: PowerBoard; history?: PowerHistory; tickerScopes?: PowerTickerScope[] } | null>("powerSnapshot", null);
   const snapshot = useMemo(() => { try { return snapshotSetting ? { board: validatePowerBoard(snapshotSetting.board), history: snapshotSetting.history ? validatePowerHistory(snapshotSetting.history) : undefined,
-    tickerScopes: Array.isArray(snapshotSetting.tickerScopes) ? snapshotSetting.tickerScopes : null } : null; } catch { return null; } }, [snapshotSetting]);
+    tickerScopes: Array.isArray(snapshotSetting.tickerScopes) ? snapshotSetting.tickerScopes : null } : null; } catch (error) {
+      logFailure("power.pane", "Validate power snapshot failed")(error);
+      return null;
+    } }, [snapshotSetting]);
   const projectTab = ["queue", "loads", "capacity"].includes(tab);
   const filter = useMemo(() => powerQuery({ tab, country, region, fuel, status, search, historical, context, loadClass, sourceId, from, to,
     sort: sort.column, direction: sort.direction }, symbol), [tab, country, region, fuel, status, search, historical, context, loadClass, sourceId, from, to, sort.column, sort.direction, symbol]);
@@ -207,6 +212,8 @@ function PowerView({ width, height, focused, scope, needsVerification }: PanePro
     if (column.id === "status") return { text, color: toneColor(STATUS_TONES[text] ?? "text", colors) };
     if (column.id === "changeMw" && typeof value === "number") return { text: `${value > 0 ? "+" : ""}${text}`, value, color: signedColor(value, colors) };
     if (column.id === "ticker") return { text, color: colors.textBright, attributes: state.selected ? 0 : TextAttributes.BOLD };
+    // The column has room for the flag beside a code.
+    if (column.id === "country") return withCountryFlag({ text, color: colors.textDim }, text, desktop);
     return { text, value: numeric,
       color: column.id === "name" || column.id === "utility" || column.id === "capacityMw" || column.id === "requestedMw" ? colors.textBright
         : ["location", "asOf", "observedAt", "scope", "proposedDate", "region", "country", "kind", "role", "period"].includes(column.id) ? colors.textDim : colors.text };

package/src/plugins/builtin/power/prices.tsx

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { useCallback, useMemo } from "react";
 import type { CarbonBoard, PowerPriceRow } from "../../../api-client/europe-energy";
 import {
@@ -140,15 +141,21 @@ function PowerPriceBoard({ width, height, focused }: { width: number; height: nu
   const [snapshotSetting] = usePaneSettingValue<PowerPricesSnapshot | null>("powerPricesSnapshot", null);
   const snapshot = useMemo(() => {
     try {
+      if (snapshotSetting?.carbonError !== undefined && (typeof snapshotSetting.carbonError !== "string"
+        || !snapshotSetting.carbonError.trim() || snapshotSetting.carbon != null)) throw new Error("Invalid carbon price failure state.");
       return snapshotSetting ? { ...snapshotSetting, board: validatePowerPrices(snapshotSetting.board),
         carbon: snapshotSetting.carbon ? validateCarbonPrice(snapshotSetting.carbon) : null } : null;
-    } catch { return null; }
+    } catch (error) {
+      logFailure("power.prices", "Validate power prices snapshot failed")(error);
+      return null;
+    }
   }, [snapshotSetting]);
   const resource = useAsyncResource(snapshot ? null : loadPowerPrices, { initialData: getCachedPowerPrices });
   const board = snapshot?.board ?? resource.data?.payload ?? null;
   // The carbon allowance loads beside the board; its failure is a notice, never the board's.
   const carbonResource = useAsyncResource(snapshot ? null : loadCarbonPrice, { initialData: getCachedCarbonPrice });
   const carbon = snapshot ? snapshot.carbon : carbonResource.data?.payload ?? null;
+  const carbonError = snapshot ? snapshot.carbonError : carbonResource.error;
   const figures = useMemo(() => carbon ? carbonFigures(carbon) : [], [carbon]);
   const rows = useMemo(() => board?.rows.map(boardRow) ?? [], [board]);
   // The band charts the selected market, or the carbon allowance from `c` or EPWR EUA until a market is chosen.
@@ -160,7 +167,7 @@ function PowerPriceBoard({ width, height, focused }: { width: number; height: nu
   const loaded = useAsyncResource<{ payload: { code: string; points: ReadonlyArray<{ date: string; value: number }> } }>(
     code && !snapshot ? historyLoader : null, { keepPreviousData: true });
   const history = snapshot ? { ...loaded, data: snapshot.history ? { payload: snapshot.history } : null, loading: false, error: null } : loaded;
-  usePowerPricesEvidence(board, carbon, useMemo(() => rows.map((row) => row.id), [rows]), resource.loading || history.loading || carbonResource.loading);
+  usePowerPricesEvidence(board, carbon, useMemo(() => rows.map((row) => row.id), [rows]), resource.loading || history.loading || carbonResource.loading, snapshot?.carbonError);
   useAutoRefresh(resource.updatedAt, resource.load);
   useAutoRefresh(carbonResource.updatedAt, carbonResource.load);
   usePaneRefreshKey(() => { void resource.reload(); void history.reload(); void carbonResource.reload(); }, { focused });
@@ -185,7 +192,7 @@ function PowerPriceBoard({ width, height, focused }: { width: number; height: nu
     error: board ? resource.error ?? (open ? null : history.error) : null, stale: !!resource.data?.stale, hints });
   usePaneNoticeFooter({ registrationId: "power-prices:notices", focused,
     notices: [...(board?.gaps ?? []), ...(resource.data?.refreshError ? [resource.data.refreshError] : []),
-      ...(carbon?.gaps ?? []), ...(board && !carbon && carbonResource.error ? [carbonResource.error] : [])] });
+      ...(carbon?.gaps ?? []), ...(board && !carbon && carbonError ? [carbonError] : [])] });
   return <Box width={width} height={height} flexDirection="column">
     <PaneStatusBody loading={resource.loading && !board} error={!board && !notAvailable ? resource.error : null}
       empty={notAvailable} emptyTitle={POWER_PRICES_NOT_AVAILABLE} subject="power prices" width={width} height={height}>

package/src/plugins/builtin/research/analyst-headless.ts

@@ -6,11 +6,15 @@ import type {
   HeadlessPaneEntry,
   HeadlessPaneLoadArgs,
 } from "../../../types/plugin";
-import type { AnalystResearchData } from "../../../types/financials";
+import type { AnalystResearchData, Quote } from "../../../types/financials";
+import { logFailure } from "../../../utils/log-failure";
 import { formatPercent } from "../../../utils/format";
 import { loadAnalystResearch } from "./client";
 import {
+  analystReferenceMetadata,
   analystTargetCurrency,
+  analystUpside,
+  formatAnalystReference,
   formatAnalystPrice,
   formatRecommendationMix,
   recommendationMix,
@@ -18,7 +22,6 @@ import {
   formatRatingTarget,
   recommendationTotal,
   sortRatingRows,
-  targetUpside,
   type RatingColumnId,
 } from "./analyst-model";
 import { REPORTED_DATA } from "../shared/report-freshness";
@@ -48,10 +51,11 @@ const SORT_COLUMNS: Record<string, RatingColumnId> = {
   target: "target",
 };
 
-function overviewEntries(data: AnalystResearchData): HeadlessPaneEntry[] {
+/** The summary: the upside from Last (the quote's regular session price), and the price and time it is measured from, as `analyst` gives them. */
+function overviewEntries(data: AnalystResearchData, quote: Quote | null): HeadlessPaneEntry[] {
   const target = data.priceTarget;
   const currency = analystTargetCurrency(data);
-  const upside = targetUpside(target);
+  const { upside, reference } = analystUpside(data, quote);
   return [
     {
       label: "Average target",
@@ -65,8 +69,8 @@ function overviewEntries(data: AnalystResearchData): HeadlessPaneEntry[] {
     },
     {
       label: "Upside reference price",
-      value: target?.current ?? null,
-      formatted: formatAnalystPrice(target?.current, currency),
+      value: reference.price ?? null,
+      formatted: formatAnalystReference(reference, currency),
     },
     {
       label: "Target range",
@@ -97,6 +101,8 @@ export interface AnalystResearchHeadlessDependencies {
     args: HeadlessPaneLoadArgs,
     ctx: HeadlessPaneContext,
   ): Promise<AnalystResearchData>;
+  /** The listing's quote, whose regular session price the upside is measured from; null when none loads. */
+  loadQuote?(symbol: string, ctx: HeadlessPaneContext): Promise<Quote | null>;
 }
 
 const defaultDependencies: AnalystResearchHeadlessDependencies = {
@@ -104,6 +110,11 @@ const defaultDependencies: AnalystResearchHeadlessDependencies = {
     const instrument = await ctx.resolveInstrument?.(symbol);
     return loadAnalystResearch(ctx.marketData, symbol, instrument?.exchange);
   },
+  async loadQuote(symbol, ctx) {
+    const instrument = await ctx.resolveInstrument?.(symbol);
+    return ctx.marketData.getQuote(instrument?.symbol ?? symbol, instrument?.exchange ?? "")
+      .catch(logFailure("analyst", "Read the quote the upside is measured from failed", null));
+  },
 };
 
 export function createAnalystResearchHeadless(
@@ -148,7 +159,11 @@ export function createAnalystResearchHeadless(
     describe: (args) => `Analyst Research | ${args.symbols[0]}`,
     async load(args, ctx) {
       const symbol = args.symbols[0]!;
-      const data = await dependencies.loadData(symbol, args, ctx);
+      const [data, quote] = await Promise.all([
+        dependencies.loadData(symbol, args, ctx),
+        dependencies.loadQuote?.(symbol, ctx) ?? Promise.resolve(null),
+      ]);
+      const { upside, reference } = analystUpside(data, quote);
       const currency = analystTargetCurrency(data);
       const ratings = sortRatingRows(data.ratings, {
         columnId: SORT_COLUMNS[String(args.options.sort)] ?? "date",
@@ -161,7 +176,7 @@ export function createAnalystResearchHeadless(
           currency: currency ?? null,
         }));
       const sections: HeadlessBundleSection[] = [
-        { title: "Summary", entries: overviewEntries(data) },
+        { title: "Summary", entries: overviewEntries(data, quote) },
         { title: "Recent analyst actions", columns: RATING_COLUMNS, rows: ratings },
       ];
       return {
@@ -174,6 +189,8 @@ export function createAnalystResearchHeadless(
           currency: currency ?? null,
           fetchedAt: data.fetchedAt,
           stale: data.stale,
+          upside: upside ?? null,
+          upsideReference: analystReferenceMetadata(reference),
         },
       };
     },

package/src/plugins/builtin/research/analyst-model.ts

@@ -6,7 +6,9 @@ import { displayWidth, formatCurrency, formatNumber } from "../../../utils/forma
 import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
 import { loadingErrorFooterInfo } from "../../../components/data-table/table-pane";
 import { delayedFooterSegment } from "../../../components/layout/pane/footer/model";
-import { regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
+import { regularSessionValuationPrice, regularSessionValuationTime } from "../../../market-data/quotes/regular-session-valuation";
+import { getCompletedRegularSessionDisplay } from "../../../market-data/market/status";
+import { formatUtcDayTime, parseReportTime, type ReportTime } from "../../../utils/utc-time";
 
 function compactPeriod(period: string): string {
   return period
@@ -32,6 +34,15 @@ export interface AnalystReferencePrice {
   /** What the price is when it is the live quote, such as `real-time` or `15m delayed`. */
   freshness: string | null;
   live: boolean;
+  /**
+   * When the price is from: a live quote's regular session close once that session is over, else the quote's own
+   * time (regularSessionValuationTime); the provider's reference from when the research was fetched. Null unknown.
+   */
+  time?: ReportTime | null;
+  /** The live price is a completed session's close. */
+  close?: boolean;
+  /** The exchange-local date of that session, when the quote names it. */
+  sessionDate?: string;
 }
 
 function quoteFreshness(quote: Quote): string | null {
@@ -51,12 +62,62 @@ export function analystReferencePrice(
   data: AnalystResearchData | null,
   quote: Quote | null | undefined,
 ): AnalystReferencePrice {
-  const fallback = { price: data?.priceTarget?.current, freshness: null, live: false };
+  const fallback = { price: data?.priceTarget?.current, freshness: null, live: false, time: parseReportTime(data?.fetchedAt), close: false };
   const currency = analystTargetCurrency(data);
   const price = regularSessionValuationPrice(quote);
   if (!quote || quote.stale || !currency || price == null) return fallback;
   if (quote.currency?.trim() !== currency) return fallback;
-  return { price, freshness: quoteFreshness(quote), live: true };
+  return {
+    price, freshness: quoteFreshness(quote), live: true,
+    time: regularSessionValuationTime(quote), close: getCompletedRegularSessionDisplay(quote) != null,
+    ...(quote.regularCloseSessionDate ? { sessionDate: quote.regularCloseSessionDate } : {}),
+  };
+}
+
+/**
+ * The upside and what it is measured from, as `analyst`, `fn ANR` and the ANR
+ * pane read it: the average target over Last (the quote's regular session
+ * price, as `valuation` and RV show it), or the provider's reference price when
+ * no quote in the target's currency stands (analystReferencePrice).
+ */
+export function analystUpside(data: AnalystResearchData | null, quote: Quote | null | undefined) {
+  const reference = analystReferencePrice(data, quote);
+  return { upside: targetUpside(data?.priceTarget, reference.price), reference };
+}
+
+/** The reference an upside is measured from, for JSON: the price, when it is from, and whose it is. */
+export function analystReferenceMetadata(reference: AnalystReferencePrice) {
+  const time = reference.time;
+  return {
+    price: reference.price ?? null,
+    asOf: time ? (time.dateOnly ? new Date(time.time).toISOString().slice(0, 10) : new Date(time.time).toISOString()) : null,
+    basis: !reference.live ? "provider reference at retrieval" : reference.close ? "regular session close" : "regular session price",
+    ...(reference.freshness ? { freshness: reference.freshness } : {}),
+  };
+}
+
+/** When a reference price is from, in the words a change line uses: "Thu 22 Oct close" or a print's time. */
+function analystReferenceWhen(reference: AnalystReferencePrice, now: number): string {
+  const at = (time: ReportTime) => formatUtcDayTime(time, now) + (time.dateOnly ? "" : " UTC");
+  if (reference.live && reference.close) {
+    const day = reference.sessionDate ? { time: Date.parse(`${reference.sessionDate}T00:00:00Z`), dateOnly: true }
+      : reference.time ? { ...reference.time, dateOnly: true } : null;
+    return day ? `${at(day)} close` : "close";
+  }
+  return reference.time ? at(reference.time) : "";
+}
+
+/**
+ * The price an upside is measured from and when it is from: "$141.39, Thu 22 Oct close", "$141.39, Fri 23 Oct
+ * 14:05 UTC (15m delayed)" while the session trades, or the provider's reference, "$137.32, provider reference at
+ * retrieval Wed 21 Oct 21:30 UTC".
+ */
+export function formatAnalystReference(reference: AnalystReferencePrice, currency: string | undefined, now = Date.now()): string {
+  if (reference.price == null || !Number.isFinite(reference.price)) return "-";
+  const price = formatAnalystPrice(reference.price, currency);
+  const when = analystReferenceWhen(reference, now);
+  if (!reference.live) return `${price}, provider reference${when ? ` at retrieval ${when}` : ""}`;
+  return `${price}${when ? `, ${when}` : ""}${reference.freshness && !reference.close ? ` (${reference.freshness})` : ""}`;
 }
 
 function isCurrentMonthPeriod(period: string | undefined): boolean {
@@ -340,6 +401,7 @@ export function buildAnalystFooterInfo(
 export function buildAnalystStatusSegments(
   data: AnalystResearchData | null,
   reference: AnalystReferencePrice = analystReferencePrice(data, null),
+  now = Date.now(),
 ): PaneFooterSegment[] {
   if (!data) return [];
 
@@ -372,11 +434,14 @@ export function buildAnalystStatusSegments(
   if (reference.price != null) {
     // A delayed price is the footer's clock beside it; a real-time one says so in words.
     const delay = reference.freshness?.endsWith(" delayed") ? reference.freshness.slice(0, -" delayed".length) : null;
+    const when = !reference.live ? "provider ref" : reference.close ? analystReferenceWhen(reference, now) : null;
     segments.push({
       id: "analyst-reference-price",
       parts: [
         { text: "upside vs", tone: "label" },
         { text: price(reference.price) },
+        // When it is from, as `analyst` and `fn ANR` print it: "Thu 22 Oct close" or the provider's reference.
+        ...(when ? [{ text: when, tone: "muted" as const }] : []),
         ...(reference.freshness && !delay ? [{ text: reference.freshness, tone: "muted" as const }] : []),
       ],
     });