gloomberb 0.16.0 → 0.16.2

package/src/plugins/builtin/chat/profile-popover.ts

@@ -4,10 +4,14 @@ import {
   type AccountProfile,
   type ChatUserSummary,
 } from "../../../api-client";
-import {
-  PROFILE_POPOVER_CLOSE_DELAY_MS,
-  hasPublicChatProfileInfo,
-} from "./message/profile-popover";
+import { PROFILE_POPOVER_CLOSE_DELAY_MS } from "./message/profile-popover";
+import type { ChatUserAnchor } from "./message/types";
+
+interface ProfilePopoverOptions {
+  ownProfile?: boolean;
+  /** The name or @mention it opens from; the desktop places the card beside it. */
+  anchor?: ChatUserAnchor;
+}
 
 function accountProfileToChatUser(profile: AccountProfile): ChatUserSummary {
   return {
@@ -39,6 +43,7 @@ function isAccountProfileConfigured(profile: AccountProfile): boolean {
 
 export function useChatProfilePopover(trackOwnProfileUserId?: string) {
   const [profilePopoverUser, setProfilePopoverUser] = useState<ChatUserSummary | null>(null);
+  const [profilePopoverAnchor, setProfilePopoverAnchor] = useState<ChatUserAnchor>(null);
   const [ownProfileConfigured, setOwnProfileConfigured] = useState<boolean | null>(null);
   const profilePopoverCloseTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const ownProfileRef = useRef<ChatUserSummary | null>(null);
@@ -60,6 +65,7 @@ export function useChatProfilePopover(trackOwnProfileUserId?: string) {
     pinnedRef.current = false;
     profilePopoverUserIdRef.current = null;
     setProfilePopoverUser(null);
+    setProfilePopoverAnchor(null);
   }, [cancelProfilePopoverClose]);
 
   const scheduleProfilePopoverClose = useCallback(() => {
@@ -70,6 +76,7 @@ export function useChatProfilePopover(trackOwnProfileUserId?: string) {
       if (pinnedRef.current) return;
       profilePopoverUserIdRef.current = null;
       setProfilePopoverUser(null);
+      setProfilePopoverAnchor(null);
     }, PROFILE_POPOVER_CLOSE_DELAY_MS);
   }, [cancelProfilePopoverClose]);
 
@@ -104,32 +111,29 @@ export function useChatProfilePopover(trackOwnProfileUserId?: string) {
 
   const showProfilePopover = useCallback((
     targetUser: ChatUserSummary,
-    options?: { ownProfile?: boolean; pin?: boolean },
+    options?: ProfilePopoverOptions & { pin?: boolean },
   ) => {
     const ownProfile = options?.ownProfile === true;
     const cachedUser = ownProfile && ownProfileRef.current?.id === targetUser.id
       ? ownProfileRef.current
       : targetUser;
-    // Only what the server shared: a private or empty profile has no card.
-    if (!ownProfile && !hasPublicChatProfileInfo(cachedUser)) {
-      closeProfilePopover();
-      return;
-    }
+    // Every name has a card: a private or empty profile gets the name-only one.
     cancelProfilePopoverClose();
     pinnedRef.current = options?.pin === true;
     profilePopoverUserIdRef.current = cachedUser.id;
     setProfilePopoverUser(cachedUser);
+    setProfilePopoverAnchor(options?.anchor ?? null);
     if (ownProfile) refreshOwnProfile(targetUser.id);
-  }, [cancelProfilePopoverClose, closeProfilePopover, refreshOwnProfile]);
+  }, [cancelProfilePopoverClose, refreshOwnProfile]);
 
   /** Pointing at a name previews its card, but never over one a click pinned. */
-  const hoverProfilePopover = useCallback((targetUser: ChatUserSummary, options?: { ownProfile?: boolean }) => {
+  const hoverProfilePopover = useCallback((targetUser: ChatUserSummary, options?: ProfilePopoverOptions) => {
     if (pinnedRef.current) return;
     showProfilePopover(targetUser, options);
   }, [showProfilePopover]);
 
   /** A click on a name pins its card until Esc, a click outside, or a second click. */
-  const toggleProfilePopover = useCallback((targetUser: ChatUserSummary, options?: { ownProfile?: boolean }) => {
+  const toggleProfilePopover = useCallback((targetUser: ChatUserSummary, options?: ProfilePopoverOptions) => {
     // The desktop card hears the same click first, as a click outside it.
     if (dismissedPinnedUserIdRef.current === targetUser.id) {
       dismissedPinnedUserIdRef.current = null;
@@ -177,6 +181,7 @@ export function useChatProfilePopover(trackOwnProfileUserId?: string) {
     closeProfilePopover,
     dismissProfilePopover,
     ownProfileConfigured,
+    profilePopoverAnchor,
     profilePopoverUser,
     hoverProfilePopover,
     scheduleProfilePopoverClose,

package/src/plugins/builtin/clinical-trials/index.tsx

@@ -31,6 +31,7 @@ export const clinicalTrialsPlugin: GloomPlugin = {
   panes: [
     {
       id: CLINICAL_TRIALS_PANE_ID,
+      reportFreshness: { source: "ClinicalTrials.gov", status: "not-a-feed", basis: "registry records" },
       name: "Trials",
       icon: "C",
       component: TrialsPane,

package/src/plugins/builtin/cloud/askg/executor.ts

@@ -285,7 +285,8 @@ function defaultHeadlessExecutor(
     return {
       result: serializeHeadlessPaneResult(loaded.definition, result),
       rowCount: headlessRowCount(loaded.definition, result),
-      ...(result.errors?.length ? { errors: result.errors } : {}),
+      // Ask Gloom reads a caveat as a partial result, so notes join the errors here.
+      ...(result.errors?.length || result.notes?.length ? { errors: [...(result.errors ?? []), ...(result.notes ?? [])] } : {}),
     };
   };
 }

package/src/plugins/builtin/cloud/plugin.tsx

@@ -65,6 +65,7 @@ const askgModule: PluginModule = {
   },
   panes: [{
     id: ASKG_PANE_ID,
+    reportFreshness: { status: "not-a-feed", basis: "generated answer" },
     name: "Ask Gloom",
     icon: "K",
     component: ASKGPane,

package/src/plugins/builtin/cloud/team/module.tsx

@@ -23,6 +23,7 @@ export const teamModule: PluginModule = {
   capabilities: [createCloudTeamCapability(), createCloudViewsCapability()],
   panes: [{
     id: TEAM_PANE_ID,
+    reportFreshness: { status: "not-a-feed", basis: "account data" },
     name: "Team",
     icon: "T",
     component: TeamPane,

package/src/plugins/builtin/cloud/thesis/module.tsx

@@ -12,6 +12,7 @@ import { ThesisTickerTab } from "./ticker-tab";
 export const thesisModule: PluginModule = {
   panes: [{
     id: THESIS_PANE_ID,
+    reportFreshness: { source: "Your theses", status: "not-a-feed", basis: "your theses" },
     name: "Theses",
     icon: "Θ",
     component: ThesisBoardPane,

package/src/plugins/builtin/cloud-tweets/registration.ts

@@ -28,6 +28,7 @@ export function registerTwitterFeedFeature(ctx: GloomPluginContext): void {
 
   ctx.registerPane({
     id: TWITTER_FEED_PANE_ID,
+    reportFreshness: { source: "X posts", status: "not-a-feed", basis: "posts" },
     name: "X Feed",
     icon: "X",
     component: TwitterFeedPane,

package/src/plugins/builtin/comment-letters/index.tsx

@@ -34,6 +34,7 @@ export const commentLettersPlugin: GloomPlugin = {
   panes: [
     {
       id: COMMENT_LETTERS_PANE_ID,
+      reportFreshness: { source: "SEC EDGAR", status: "not-a-feed", basis: "comment letters" },
       name: "Comment Letters",
       icon: "L",
       component: CommentLettersPane,

package/src/plugins/builtin/company-attention/headless.ts

@@ -7,6 +7,9 @@ import { appsModel, hiringModel, type AttentionKind } from "./model";
 export function attentionHeadless(kind: AttentionKind): HeadlessPaneDefinition<"bundle"> {
   return {
     shape: "bundle",
+    freshness: kind === "hiring"
+      ? { source: "Company careers sites", status: "not-a-feed", basis: "observed job postings" }
+      : { source: "App Store and Google Play charts", status: "not-a-feed", basis: "observed chart ranks" },
     argument: { kind: "ticker", optional: true, placeholder: "ticker", description: "Company ticker, including exchange for non-US listings. Omit for the global board." },
     options: [
       { key: "limit", type: "string", defaultValue: "100", description: "Rows per REST page, up to 200 for hiring and 500 for apps." },
@@ -36,7 +39,8 @@ export function attentionHeadless(kind: AttentionKind): HeadlessPaneDefinition<"
       const nextOffset = kind === "hiring" && "total" in data ? offset + data.companies.length < data.total ? offset + data.companies.length : null : (data as AppAttentionPayload).page?.nextOffset ?? null;
       return {
         complete: !model.preview && nextOffset === null,
-        errors: [...model.notices, ...(nextOffset !== null ? [`Additional observations available with --offset ${nextOffset}.`] : []), ...(model.preview ? ["Additional rows and history require Gloom Pro."] : [])],
+        errors: [...model.notices, ...(model.preview ? ["Additional rows and history require Gloom Pro."] : [])],
+        ...(nextOffset !== null ? { notes: [`Additional observations available with --offset ${nextOffset}.`] } : {}),
         sections: Object.entries(model.sections).map(([key, section]) => ({ title: key === "mix" ? kind === "hiring" ? "Role family" : "Countries" : key,
           columns: section.columns.map((column) => ({ key: column.id, header: column.label, align: column.align })),
           rows: section.rows.map((row) => ({ ...row.values, ...(row.url ? { sourceUrl: row.url } : {}), ...(row.details ? { evidence: row.details } : {}) })) })),

package/src/plugins/builtin/company-attention/pane.tsx

@@ -172,7 +172,7 @@ function AttentionView({ kind, symbol, width, height, focused }: Size & { kind:
             const numeric = typeof value === "number";
             const decimals = DECIMALS[column.id] ?? 0;
             const text = numeric ? `${SIGNED_COLUMNS.has(column.id) && value > 0 ? "+" : ""}${value.toLocaleString("en-US", { minimumFractionDigits: decimals, maximumFractionDigits: decimals })}` : LABEL_COLUMNS.has(column.id) ? humanLabel(value) : column.id === "title" ? value.trim() : value;
-            if (column.id === "share" && numeric && tab === "mix") return { ...shareCell(text, maxShare ? value / maxShare : null, column.width, colors, state.selected, desktop), value };
+            if (column.id === "share" && numeric && tab === "mix") return { ...shareCell(text, maxShare ? value / maxShare : null, column.width, colors, state.selected), value };
             return { text, value, color: numeric && SIGNED_COLUMNS.has(column.id) ? signedColor(value, colors)
               : column.id === "name" || column.id === "title" ? colors.textBright : column.id === "date" || column.id === "observed" || column.id === "confidence" ? colors.textDim : colors.text };
           }} selectedTextOverridesCellColor showHorizontalScrollbar resetScrollKey={`${kind}:${symbol}:${tab}:${mix}:${country}:${chart}`}

package/src/plugins/builtin/company-kpis/headless.ts

@@ -4,6 +4,7 @@ import { companyQuery, fetchCompanyData, type CompanyMode } from "./client";
 export function companyHeadless(mode: CompanyMode): HeadlessPaneDefinition<"bundle"> {
   return {
     shape: "bundle",
+    freshness: { source: "Company filings and calls", status: "not-a-feed", basis: "reported data" },
     argument: { kind: "ticker", description: "Listed company ticker, including exchange-qualified global symbols.", placeholder: "ticker" },
     discovery: { aliases: [mode === "kpis" ? "KPIS" : "GUIDE"], dataRequirements: ["Gloom Cloud company disclosures"],
       limitations: ["Pro dataset with a fixed latest preview on Free", "Coverage follows available company disclosures; missing data is not zero", "Compare matching definition, period, currency, basis and scope", "Fiscal labels without explicit calendar dates are retained without inferred dates"] },

package/src/plugins/builtin/congress-trades/headless.ts

@@ -104,6 +104,7 @@ export function createCongressHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    freshness: { source: "House and Senate disclosures", status: "not-a-feed", basis: "filed reports" },
     argument: {
       kind: "ticker",
       optional: true,

package/src/plugins/builtin/correlation/compute.ts

@@ -8,9 +8,19 @@ export interface CorrelationResult {
 
 export interface DailyClose {
   dateKey: string;
+  /** A closing price, or a map series' value for the day (a transit count). */
   close: number;
 }
 
+/**
+ * How a series moves between two shared dates. Prices use returns. A map
+ * series is a daily count that can be zero (Hormuz logs days with no
+ * transits), where a return or log change is undefined, so it uses the
+ * change in level. Pearson correlation ignores the unit, so the level change
+ * needs no scaling.
+ */
+export type ChangeBasis = "return" | "difference";
+
 /** Keep the final valid close for each UTC trading date, in chronological order. */
 export function dailyCloses(points: readonly PricePoint[]): DailyClose[] {
   const byDate = new Map<string, number>();
@@ -41,11 +51,55 @@ export function alignDailyCloses(left: readonly DailyClose[], right: readonly Da
   });
 }
 
-export function correlateDailyCloses(left: readonly DailyClose[], right: readonly DailyClose[], minObservations = 5): CorrelationResult {
-  const aligned = alignDailyCloses(left, right);
-  const x = computeReturns(aligned.map((point) => point.leftClose));
-  const y = computeReturns(aligned.map((point) => point.rightClose));
-  return { correlation: pearsonCorrelation(x, y, minObservations), sampleSize: x.length };
+/** A map series' daily values, oldest first; zero is a value, unlike a zero close. */
+export function dailyValues(points: readonly { date: Date; value: number | null }[]): DailyClose[] {
+  const byDate = new Map<string, number>();
+  for (const point of [...points].sort((left, right) => left.date.getTime() - right.date.getTime())) {
+    if (point.value === null || !Number.isFinite(point.value) || !Number.isFinite(point.date.getTime())) continue;
+    byDate.set(point.date.toISOString().slice(0, 10), point.value);
+  }
+  return [...byDate].map(([dateKey, close]) => ({ dateKey, close }));
+}
+
+export interface PairedChange {
+  dateKey: string;
+  left: number;
+  right: number;
+}
+
+function change(previous: number, current: number, basis: ChangeBasis): number {
+  return basis === "difference" ? current - previous : previous > 0 ? (current - previous) / previous : Number.NaN;
+}
+
+/** Each side's move between consecutive shared dates, dropped for both sides when either is undefined. */
+export function pairedChanges(
+  aligned: readonly AlignedDailyClose[],
+  leftBasis: ChangeBasis = "return",
+  rightBasis: ChangeBasis = "return",
+): PairedChange[] {
+  const changes: PairedChange[] = [];
+  for (let index = 1; index < aligned.length; index++) {
+    const previous = aligned[index - 1]!;
+    const current = aligned[index]!;
+    const left = change(previous.leftClose, current.leftClose, leftBasis);
+    const right = change(previous.rightClose, current.rightClose, rightBasis);
+    if (Number.isFinite(left) && Number.isFinite(right)) changes.push({ dateKey: current.dateKey, left, right });
+  }
+  return changes;
+}
+
+export function correlateDailyCloses(
+  left: readonly DailyClose[],
+  right: readonly DailyClose[],
+  minObservations = 5,
+  leftBasis: ChangeBasis = "return",
+  rightBasis: ChangeBasis = "return",
+): CorrelationResult {
+  const changes = pairedChanges(alignDailyCloses(left, right), leftBasis, rightBasis);
+  return {
+    correlation: pearsonCorrelation(changes.map((point) => point.left), changes.map((point) => point.right), minObservations),
+    sampleSize: changes.length,
+  };
 }
 
 function toDateKey(point: PricePoint): string | null {
@@ -58,17 +112,6 @@ function comparePricePointsByDate(left: PricePoint, right: PricePoint): number {
   return getPricePointTimestamp(left) - getPricePointTimestamp(right);
 }
 
-export function computeReturns(closes: number[]): number[] {
-  const returns: number[] = [];
-  for (let i = 1; i < closes.length; i++) {
-    const previous = closes[i - 1]!;
-    const current = closes[i]!;
-    if (!Number.isFinite(previous) || !Number.isFinite(current) || previous === 0) continue;
-    returns.push((current - previous) / previous);
-  }
-  return returns;
-}
-
 export function pearsonCorrelation(x: number[], y: number[], minObservations = 5): number | null {
   const n = Math.min(x.length, y.length);
   if (n < minObservations) return null;

package/src/plugins/builtin/correlation/geo.ts

@@ -0,0 +1,34 @@
+/**
+ * Map series (`GEO:HORMUZ`) in CORR, read through the same parser and
+ * resolver G uses, so an alias G charts is one CORR correlates.
+ */
+import { loadGeoCatalog, type GeoRequest } from "../../../api-client/geo";
+import type { TimeRange } from "../../../time-series/range";
+import { GEO_SERIES_CAPABILITY_ID, parseSeriesExpression } from "../chart-composer/series-expression";
+import { resolveGeoChartSeries } from "../world-venue-map/geo-series";
+import { dailyValues, type DailyClose } from "./compute";
+import { CORRELATION_HISTORY_RESOLUTION } from "./history";
+
+/** The map series a CORR entry names, or null for a ticker. */
+export function geoSeriesToken(entry: string): string | null {
+  if (!/^GEO:/i.test(entry.trim())) return null;
+  const parsed = parseSeriesExpression(entry);
+  return parsed?.kind === "capability" && parsed.capabilityId === GEO_SERIES_CAPABILITY_ID ? parsed.seriesId : null;
+}
+
+/** A map series' daily values over the range. A server without map series says so instead of "not found". */
+export async function loadGeoCorrelationHistory(
+  request: GeoRequest,
+  seriesId: string,
+  range: TimeRange,
+  signal?: AbortSignal,
+): Promise<DailyClose[]> {
+  try {
+    const series = await resolveGeoChartSeries(request, seriesId, { range, resolution: CORRELATION_HISTORY_RESOLUTION }, signal);
+    return dailyValues(series.points);
+  } catch (error) {
+    signal?.throwIfAborted();
+    if (!await loadGeoCatalog(request, { signal })) throw new Error("Map series unavailable.");
+    throw error;
+  }
+}

package/src/plugins/builtin/correlation/headless-schema.ts

@@ -25,7 +25,10 @@ export const paneSchemas = {
     discovery: {
       id: "return-correlation",
       aliases: ["correlation", "return correlation", "correlation matrix", "pearson correlation"],
-      limitations: ["Correlation is computed from daily returns with at least five shared observations."],
+      limitations: [
+        "Correlation is computed from daily returns with at least five shared observations.",
+        "GEO:<series> entries correlate a map series' daily change with the others on shared dates.",
+      ],
       screenshotReadiness: "partial",
     },
   },

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

@@ -1,12 +1,16 @@
 import type { HeadlessPaneDefinition } from "../../../types/headless";
 import type { TimeRange } from "../../../time-series/range";
-import { formatNumber } from "../../../utils/format";
+import { formatNumber, formatSignificant } from "../../../utils/format";
+import { mixedSessionCloseNote } from "../../../market-data/market/session-close-note";
 import { resolveHeadlessInstrument, loadHeadlessSymbols } from "../shared/headless-market-data";
-import { buildCorrelationMatrix, buildCorrelationSeries, pairKey } from "./matrix/model";
+import { buildCorrelationMatrix, buildCorrelationSeries, buildGeoCorrelationSeries, pairKey, type CorrelationSeries } from "./matrix/model";
+import { geoSeriesToken, loadGeoCorrelationHistory } from "./geo";
 import { buildRelationshipAnalysis, DEFAULT_RELATIONSHIP_SECOND_SYMBOL } from "./relationship/model";
 import { paneSchemas } from "./headless-schema";
-import { CORRELATION_RETURN_BASIS, loadCorrelationHistory } from "./history";
+import { CORRELATION_RETURN_BASIS, GEO_CORRELATION_CHANGE_BASIS, loadCorrelationHistory } from "./history";
 import type { HeadlessPaneContext } from "../../../types/headless";
+import { newestReportTime } from "../../../utils/utc-time";
+import { DAILY_CLOSES } from "../shared/report-freshness";
 
 async function loadHistory(ctx: HeadlessPaneContext, key: string, range: TimeRange) {
   const { symbol, exchange } = await resolveHeadlessInstrument(ctx, key);
@@ -14,9 +18,32 @@ async function loadHistory(ctx: HeadlessPaneContext, key: string, range: TimeRan
     ctx.refresh ? { cacheMode: "refresh" } : undefined);
 }
 
+/**
+ * Daily closes with the exchange the symbol trades on, which the session note
+ * needs. A symbol that is not in the local data names no exchange, so its
+ * quote says where it lists; a missing quote only leaves the note out.
+ */
+async function loadListedHistory(ctx: HeadlessPaneContext, key: string, range: TimeRange) {
+  const { symbol, exchange } = await resolveHeadlessInstrument(ctx, key);
+  const [points, quote] = await Promise.all([
+    loadHistory(ctx, key, range),
+    exchange ? null : (async () => ctx.marketData.getQuote(symbol, "", ctx.refresh ? { cacheMode: "refresh" } : undefined))().catch(() => null),
+  ]);
+  return { exchange: exchange || quote?.listingExchangeName || quote?.exchangeName || "", points };
+}
+
+/** A ticker's daily closes, or a map series' daily values read straight from the Cloud client. */
+async function loadCorrelationInput(ctx: HeadlessPaneContext, key: string, range: TimeRange): Promise<CorrelationSeries> {
+  const geo = geoSeriesToken(key);
+  if (!geo) return buildCorrelationSeries(key, await loadHistory(ctx, key, range));
+  const request = <T,>(path: string, init?: RequestInit) => ctx.apiClient.geo<T>(path, { ...init, signal: init?.signal ?? ctx.signal });
+  return buildGeoCorrelationSeries(key, await loadGeoCorrelationHistory(request, geo, range, ctx.signal));
+}
+
 export const correlationHeadless: HeadlessPaneDefinition<"rows"> = {
   ...paneSchemas["correlation-pane"],
   shape: "rows",
+  freshness: DAILY_CLOSES,
   describe: ({ symbols, options }) => `Correlation Matrix | Daily returns | ${options.rangePreset ?? "1Y"} | ${symbols.join(", ")}`,
   columns: [
     { key: "pair", header: "Pair", format: (_value, row) => `${row.left}/${row.right}` },
@@ -25,8 +52,8 @@ export const correlationHeadless: HeadlessPaneDefinition<"rows"> = {
   ],
   async load({ symbols, options }, ctx) {
     const range = (options.rangePreset ?? "1Y") as TimeRange;
-    const loaded = await loadHeadlessSymbols(symbols, ctx, (symbol) => loadHistory(ctx, symbol, range));
-    const bySymbol = new Map(loaded.entries.map(({ symbol, data }) => [symbol, buildCorrelationSeries(symbol, data)]));
+    const loaded = await loadHeadlessSymbols(symbols, ctx, (symbol) => loadCorrelationInput(ctx, symbol, range));
+    const bySymbol = new Map(loaded.entries.map(({ symbol, data }) => [symbol, data]));
     const matrix = buildCorrelationMatrix(symbols, bySymbol);
     const rows = symbols.flatMap((left, index) => symbols.slice(index + 1).map((right) => {
       const result = matrix.results.get(pairKey(left, right));
@@ -41,6 +68,7 @@ export const correlationHeadless: HeadlessPaneDefinition<"rows"> = {
         : row.sampleSize < 5 ? "Insufficient shared return observations" : "Zero return variance",
     }));
     return {
+      freshness: { asOf: newestReportTime(symbols.map((symbol) => bySymbol.get(symbol)?.prices.at(-1)?.dateKey)) },
       rows, unavailableSymbols,
       errors: [
         ...loaded.errors,
@@ -50,6 +78,7 @@ export const correlationHeadless: HeadlessPaneDefinition<"rows"> = {
         range,
         unavailablePairs,
         returnAlignment: CORRELATION_RETURN_BASIS,
+        ...(symbols.some((symbol) => geoSeriesToken(symbol)) ? { mapSeriesChange: GEO_CORRELATION_CHANGE_BASIS } : {}),
         availability: symbols.map((symbol) => ({
           symbol, status: bySymbol.get(symbol)?.status ?? "error", observationCount: bySymbol.get(symbol)?.observationCount ?? 0,
           ...(bySymbol.get(symbol)?.integrity ? { integrity: bySymbol.get(symbol)!.integrity } : {}),
@@ -64,14 +93,18 @@ export const correlationHeadless: HeadlessPaneDefinition<"rows"> = {
 export const relationshipHeadless: HeadlessPaneDefinition<"series"> = {
   ...paneSchemas["relationship-graph-pane"],
   shape: "series",
+  freshness: DAILY_CLOSES,
   describe: ({ symbols, options }) => `Relationship Graph | ${symbols[0]}/${symbols[1] ?? DEFAULT_RELATIONSHIP_SECOND_SYMBOL} | ${options.range ?? "1Y"}`,
   async load(args, ctx) {
     const symbols = [args.symbols[0]!, args.symbols[1] ?? DEFAULT_RELATIONSHIP_SECOND_SYMBOL];
     const range = (args.options.range ?? "1Y") as TimeRange;
     const correlationWindow = Number(args.options.correlationWindow ?? 120);
-    const loaded = await loadHeadlessSymbols(symbols, ctx, (symbol) => loadHistory(ctx, symbol, range));
-    const histories = new Map(loaded.entries.map(({ symbol, data }) => [symbol, data]));
+    const loaded = await loadHeadlessSymbols(symbols, ctx, (symbol) => loadListedHistory(ctx, symbol, range));
+    const listings = new Map(loaded.entries.map(({ symbol, data }) => [symbol, data]));
+    const histories = new Map(loaded.entries.map(({ symbol, data }) => [symbol, data.points]));
     const analysis = buildRelationshipAnalysis(histories.get(symbols[0]!) ?? [], histories.get(symbols[1]!) ?? [], correlationWindow);
+    const [left, right] = symbols.map((symbol) => ({ symbol, ...listings.get(symbol) }));
+    const sessionNote = listings.size === 2 ? mixedSessionCloseNote(left!, right!, analysis.aligned.at(-1)?.dateKey) : null;
     const unavailableSymbols = symbols.filter((symbol) => (histories.get(symbol) ?? []).filter((point) => (
       Number.isFinite(point.close) && point.close > 0 && Number.isFinite(new Date(point.date).getTime())
     )).length < 2);
@@ -86,7 +119,7 @@ export const relationshipHeadless: HeadlessPaneDefinition<"series"> = {
         { id: "correlation", label: `Rolling correlation (${correlationWindow})`, points: analysis.returns.slice(correlationWindow - 1).map(({ date }) => ({ date: date.toISOString(), value: correlations.get(date.getTime()) ?? null })) },
       ],
       stats: [
-        { key: "latestRatio", label: "Latest ratio", value: analysis.latestRatio, formatted: formatNumber(analysis.latestRatio ?? undefined, 4) },
+        { key: "latestRatio", label: "Latest ratio", value: analysis.latestRatio, formatted: formatSignificant(analysis.latestRatio ?? undefined) },
         { key: "latestCorrelation", label: `Rolling correlation (${correlationWindow})`, value: analysis.latestCorrelation, formatted: formatNumber(analysis.latestCorrelation ?? undefined, 3) },
         ...(["beta", "alpha", "rSquared"] as const).map((key) => ({
           key, label: { beta: "Beta", alpha: "Alpha", rSquared: "R squared" }[key],
@@ -102,6 +135,7 @@ export const relationshipHeadless: HeadlessPaneDefinition<"series"> = {
       metadata: {
         left: symbols[0], right: symbols[1], range, correlationWindow,
         returnAlignment: CORRELATION_RETURN_BASIS,
+        ...(sessionNote ? { notices: [sessionNote] } : {}),
         firstDate: analysis.aligned.at(0)?.dateKey ?? null,
         lastDate: analysis.aligned.at(-1)?.dateKey ?? null,
         ...(analysis.integrity ? { integrity: analysis.integrity } : {}),

package/src/plugins/builtin/correlation/history.ts

@@ -17,3 +17,5 @@ export async function loadCorrelationHistory(
 }
 
 export const CORRELATION_RETURN_BASIS = "Local-price close-to-close returns between shared UTC dates; cash distributions and FX conversion are excluded, and exchange closing times may differ.";
+
+export const GEO_CORRELATION_CHANGE_BASIS = "Map series (GEO:) use the change in daily value between the same shared UTC dates, because counts such as transits can be zero.";

package/src/plugins/builtin/correlation/index.tsx

@@ -15,7 +15,10 @@ import { useShortcut } from "../../../react/input";
 import { buildChartKey } from "../../../market-data/selectors";
 import { formatTickerListInput } from "../../../tickers/list";
 import { isPlainKey } from "../../../utils/keyboard";
-import { formatCorrelation } from "./compute";
+import { useAsyncResource } from "../../../react/async-resource";
+import { cloudGeoRequest } from "../world-venue-map/client";
+import { geoSeriesToken, loadGeoCorrelationHistory } from "./geo";
+import { formatCorrelation, type DailyClose } from "./compute";
 import {
   CORRELATION_RANGE_OPTIONS,
   DEFAULT_CORRELATION_SYMBOLS,
@@ -37,6 +40,7 @@ import {
   ROW_HEADER_WIDTH,
   buildCorrelationMatrix,
   buildCorrelationPaneTitle,
+  buildGeoCorrelationSeries,
   buildStatusSummary,
   type CorrelationSeries,
   displaySymbol,
@@ -50,6 +54,13 @@ import { CORRELATION_HISTORY_RESOLUTION } from "./history";
 import { buildMatrixPairHistory, clampMatrixCursor, matrixChartRows, matrixSelection, moveMatrixCursor, type MatrixCursor } from "./matrix/selection";
 import { MatrixPairChart } from "./matrix/pair-chart";
 
+/** A map series' values and when they arrived; after a failed load, the error and any values kept from before. */
+interface GeoSeriesLoad {
+  values?: DailyClose[];
+  fetchedAt?: number;
+  error?: string;
+}
+
 function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
   const pane = usePaneInstance();
   const { navigateTicker, pinTicker } = usePluginTickerActions();
@@ -75,9 +86,12 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
   const matrixScrollRef = useRef<ScrollBoxRenderable | null>(null);
   const horizontalScrollRef = useRef<ScrollBoxRenderable | null>(null);
 
+  const entries = settings.symbolsError ? [] : settings.symbols;
+  const geoEntries = entries.filter((entry) => geoSeriesToken(entry));
+  const geoKey = geoEntries.join(",");
   const instruments = useMemo(() => {
     if (settings.symbolsError) return [];
-    return settings.symbols.map((symbol) => {
+    return settings.symbols.filter((symbol) => !geoSeriesToken(symbol)).map((symbol) => {
       const ticker = tickers.get(symbol);
       return {
         symbol,
@@ -103,6 +117,28 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
 
   const chartEntries = useChartQueries(chartRequests);
 
+  // Map series load beside the tickers; one that fails leaves the others and every ticker pair working.
+  // A failed refresh keeps the series' last values for the same range, as a ticker keeps its last history.
+  const geoRetainedRef = useRef(new Map<string, { values: DailyClose[]; fetchedAt: number }>());
+  const geoLoader = useMemo(() => geoKey ? async () => {
+    const range = settings.rangePreset;
+    const results = await Promise.allSettled(geoEntries.map((entry) => (
+      loadGeoCorrelationHistory(cloudGeoRequest, geoSeriesToken(entry)!, range)
+    )));
+    return new Map(geoEntries.map((entry, index): [string, GeoSeriesLoad] => {
+      const result = results[index]!;
+      const key = `${range}|${entry}`;
+      if (result.status === "fulfilled") {
+        const loaded = { values: result.value, fetchedAt: Date.now() };
+        geoRetainedRef.current.set(key, loaded);
+        return [entry, loaded];
+      }
+      const error = result.reason instanceof Error ? result.reason.message : String(result.reason);
+      return [entry, { ...geoRetainedRef.current.get(key), error }];
+    }));
+  } : null, [geoKey, settings.rangePreset]);
+  const geoHistory = useAsyncResource(geoLoader, { keepPreviousData: true });
+
   const seriesBySymbol = useMemo(() => {
     const map = new Map<string, CorrelationSeries>();
     for (let i = 0; i < instruments.length; i++) {
@@ -112,10 +148,21 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
       const entry = chartEntries.get(key);
       map.set(instrument.symbol, getSeriesForEntry(instrument.symbol, entry, settings.rangePreset));
     }
+    for (const symbol of geoEntries) {
+      const loaded = geoHistory.data?.get(symbol);
+      map.set(symbol, !loaded
+        ? { symbol, prices: [], basis: "difference", status: "loading", observationCount: 0 }
+        : loaded.values
+          ? {
+            ...buildGeoCorrelationSeries(symbol, loaded.values),
+            loading: geoHistory.loading, refreshError: loaded.error, fetchedAt: loaded.fetchedAt,
+          }
+          : { symbol, prices: [], basis: "difference", status: "error", observationCount: 0, refreshError: loaded.error });
+    }
     return map;
-  }, [chartEntries, chartRequests, instruments, settings.rangePreset]);
+  }, [chartEntries, chartRequests, instruments, settings.rangePreset, geoKey, geoHistory.data, geoHistory.loading]);
 
-  const symbols = instruments.map((instrument) => instrument.symbol);
+  const symbols = entries;
   const symbolsKey = symbols.join(",");
   const cursor = clampMatrixCursor(cellCursor, symbols.length);
   const selection = matrixSelection(symbols, cursor);
@@ -139,15 +186,20 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
   const refresh = useCallback(() => {
     const coordinator = getSharedMarketDataCoordinator();
     for (const request of chartRequests) void coordinator?.loadChart(request, { forceRefresh: true });
-  }, [chartRequests]);
+    if (geoKey) void geoHistory.reload();
+  }, [chartRequests, geoKey, geoHistory.reload]);
 
   const openSymbol = useCallback((symbol: string) => {
+    if (geoSeriesToken(symbol)) {
+      createPaneFromTemplate("chart-composer-pane", { arg: symbol });
+      return;
+    }
     if (tickers.has(symbol)) {
       pinTicker(symbol, { floating: true, paneType: TICKER_RESEARCH_PANE_ID });
       return;
     }
     navigateTicker(symbol);
-  }, [navigateTicker, pinTicker, tickers]);
+  }, [createPaneFromTemplate, navigateTicker, pinTicker, tickers]);
 
   /** Hovered symbols remain a keyboard starting point; Left reaches their row cursor. */
   const moveCursor = (key: string) => {
@@ -170,6 +222,8 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
       event.preventDefault();
       event.stopPropagation();
       if (hoveredSymbol && symbols.includes(hoveredSymbol)) openSymbol(hoveredSymbol);
+      // Ratio and beta are price measures, so a pair with a map series charts both in G instead.
+      else if (pair && pair.some((entry) => geoSeriesToken(entry))) createPaneFromTemplate("chart-composer-pane", { arg: formatTickerListInput(pair) });
       else if (pair) createPaneFromTemplate("relationship-graph-pane", { symbols: pair, arg: formatTickerListInput(pair) });
       else openSymbol(selection[0]);
     }
@@ -210,13 +264,13 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
   }, []);
 
   const headerBg = colors.panel;
-  const rowHeaderWidth = Math.max(
-    ROW_HEADER_WIDTH,
-    Math.min(12, Math.max(0, ...symbols.map((symbol) => displaySymbol(symbol).length)) + 2),
-  );
+  const labelWidth = Math.max(0, ...symbols.map((symbol) => displaySymbol(symbol).length));
+  const rowHeaderWidth = Math.max(ROW_HEADER_WIDTH, Math.min(12, labelWidth + 2));
+  // A map series label (SUEZ.TANKER) is wider than a ticker's: columns keep room for it and the matrix scrolls instead.
+  const minCellWidth = Math.max(MIN_MATRIX_CELL_WIDTH, labelWidth + 2);
   const cellCount = Math.max(1, symbols.length);
-  const availableCellWidth = Math.floor((Math.max(width - rowHeaderWidth - 4, cellCount * MIN_MATRIX_CELL_WIDTH)) / cellCount);
-  const cellWidth = Math.max(MIN_MATRIX_CELL_WIDTH, Math.min(MATRIX_CELL_WIDTH, availableCellWidth));
+  const availableCellWidth = Math.floor((Math.max(width - rowHeaderWidth - 4, cellCount * minCellWidth)) / cellCount);
+  const cellWidth = Math.max(minCellWidth, Math.min(MATRIX_CELL_WIDTH, availableCellWidth));
   // Rows are exactly as wide as the matrix (after the one-cell inset), so the
   // zebra and hover bands stop at the last column instead of running on.
   const matrixRowWidth = 1 + rowHeaderWidth + symbols.length * cellWidth;
@@ -401,9 +455,9 @@ export const correlationModule: PluginModule = {
       headless: correlationHeadless,
       paneId: "correlation",
       label: "Correlation Matrix",
-      description: "Date-aligned Pearson correlation matrix for ticker returns.",
+      description: "Date-aligned Pearson correlation matrix for ticker returns and map series such as GEO:HORMUZ.",
       keywords: ["correlation", "corr", "matrix", "pearson", "returns", "covariance"],
-      shortcut: { prefix: "CORR", argPlaceholder: "tickers", argKind: "ticker-list" },
+      shortcut: { prefix: "CORR", argPlaceholder: "tickers", argKind: "ticker-list", keepArgToken: (token) => !!geoSeriesToken(token) },
       wizard: [
         {
           key: "tickers",