gloomberb 0.17.4 → 0.17.5

package/src/plugins/builtin/chat/controller/unread-people.ts

@@ -0,0 +1,240 @@
+import { apiClient, type ChatChannel, type ChatMessage } from "../../../../api-client";
+import type { ChannelRuntimeState, ChannelUnreadPeople } from "./state";
+import { chatMessageMentionsUsername, normalizeChatUsername } from "./utils";
+
+/** The most messages the server returns for one request. */
+const PAGE_SIZE = 100;
+/**
+ * A channel reads at most this many pages of its unread messages, the newest
+ * ones: 300. A mention older than that in a channel with more than 300 unread
+ * is not counted, which keeps a busy channel left unread for weeks from
+ * costing hundreds of requests at every launch.
+ */
+const MAX_PAGES = 3;
+const RETRY_AFTER_FAILURE_MS = 60_000;
+
+interface Reader {
+  id: string;
+  username: string | null;
+}
+
+/** What the app badge needs of one unread message: who sent it, and whether it mentions you. */
+interface UnreadFact {
+  senderId: string;
+  mentionsYou: boolean;
+}
+
+function unreadFact(message: ChatMessage, reader: Reader): UnreadFact {
+  return {
+    senderId: message.user.id,
+    mentionsYou: !!reader.username && chatMessageMentionsUsername(message.content, reader.username),
+  };
+}
+
+function peopleOf(facts: Iterable<UnreadFact>): ChannelUnreadPeople {
+  const senders = new Set<string>();
+  const mentioners = new Set<string>();
+  for (const fact of facts) {
+    senders.add(fact.senderId);
+    if (fact.mentionsYou) mentioners.add(fact.senderId);
+  }
+  return { senders: [...senders], mentioners: [...mentioners] };
+}
+
+/**
+ * The people behind unread messages: who sent them and who mentioned
+ * `reader`. Your own messages are never unread.
+ */
+export function summarizeUnreadMessages(
+  messages: readonly ChatMessage[],
+  reader: { id: string; username: string | null },
+): ChannelUnreadPeople {
+  return peopleOf(messages.filter((message) => message.user.id !== reader.id).map((message) => unreadFact(message, reader)));
+}
+
+/** Messages read from the server for a channel whose unread messages are not all on this device. */
+interface LoadedUnread {
+  userId: string;
+  username: string | null;
+  /** The read marker they follow; a new marker makes them stale. */
+  markerId: string;
+  facts: Map<string, UnreadFact>;
+  /** The newest message read, where the next load picks up. */
+  newestId: string | null;
+  /** The unread count the load was asked for, so a count that never matches is not asked for again. */
+  loadedFor: number;
+  failedAt: number | null;
+}
+
+interface UnreadPeopleOptions {
+  getChannels: () => ChatChannel[];
+  getChannelStates: () => Iterable<[string, ChannelRuntimeState]>;
+  getUser: () => { id: string; username: string; emailVerified: boolean } | null;
+  /** A load finished: the people changed. */
+  onChange: () => void;
+}
+
+/**
+ * Who each channel's unread messages are from, for the app badge. The server
+ * keeps a count per channel and a read marker, not the senders, so they come
+ * from the messages after the marker: the ones this device holds, and for a
+ * channel whose unread messages are not all here, the newest 300 of the rest
+ * read from the server once (then only what is new). Nothing is guessed: a
+ * channel that has not loaded yet reports the unread messages it does hold.
+ *
+ * Only a host that keeps an app badge needs this, so it does nothing, and
+ * makes no request, until something asks to {@link track} it.
+ */
+export class ChatControllerUnreadPeople {
+  private readonly loaded = new Map<string, LoadedUnread>();
+  private readonly inFlight = new Set<string>();
+  private generation = 0;
+  private trackers = 0;
+
+  constructor(private readonly options: UnreadPeopleOptions) {}
+
+  /** Starts keeping the people current for as long as the returned stop has not been called. */
+  track(): () => void {
+    this.trackers += 1;
+    if (this.trackers === 1) this.options.onChange();
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      this.trackers -= 1;
+      if (this.trackers === 0) this.clear();
+    };
+  }
+
+  snapshot(): Record<string, ChannelUnreadPeople> {
+    const reader = this.trackers > 0 ? this.reader() : null;
+    if (!reader) return {};
+    const channels = new Map(this.options.getChannels().map((channel) => [channel.id, channel]));
+    const people: Record<string, ChannelUnreadPeople> = {};
+    for (const [channelId, state] of this.options.getChannelStates()) {
+      if (state.unreadCount <= 0) continue;
+      const otherPerson = directPerson(channels.get(channelId));
+      // Everything unread in a DM is from the one person on the other side.
+      people[channelId] = otherPerson
+        ? { senders: [otherPerson], mentioners: [] }
+        : peopleOf(this.knownFacts(channelId, state, reader).values());
+    }
+    return people;
+  }
+
+  /** Starts reading what is missing for channels whose unread messages are not all here. Cheap when nothing is. */
+  sync(): void {
+    const reader = this.trackers > 0 ? this.reader() : null;
+    if (!reader || !this.options.getUser()?.emailVerified) return;
+    const channels = new Map(this.options.getChannels().map((channel) => [channel.id, channel]));
+    for (const [channelId, state] of this.options.getChannelStates()) {
+      const marker = state.lastViewedMessageId;
+      const channel = channels.get(channelId);
+      if (state.unreadCount <= 0 || !marker || !channel || directPerson(channel) || this.inFlight.has(channelId)) continue;
+      if (this.knownFacts(channelId, state, reader).size >= state.unreadCount) continue;
+      const loaded = this.currentLoad(channelId, marker, reader);
+      if (loaded && loaded.loadedFor >= state.unreadCount) continue;
+      if (loaded?.failedAt && Date.now() - loaded.failedAt < RETRY_AFTER_FAILURE_MS) continue;
+      void this.load(channelId, marker, reader, state.unreadCount);
+    }
+  }
+
+  /** Drops what was read and lets late answers fall away, as on sign-out. */
+  clear(): void {
+    this.generation += 1;
+    this.loaded.clear();
+    this.inFlight.clear();
+  }
+
+  private reader(): Reader | null {
+    const user = this.options.getUser();
+    return user ? { id: user.id, username: normalizeChatUsername(user.username) } : null;
+  }
+
+  private currentLoad(channelId: string, marker: string, reader: Reader): LoadedUnread | null {
+    const loaded = this.loaded.get(channelId);
+    return loaded && loaded.markerId === marker && loaded.userId === reader.id && loaded.username === reader.username
+      ? loaded
+      : null;
+  }
+
+  /**
+   * The unread messages known for certain: those read from the server after
+   * the read marker, and the cached ones after it. Without the marker nothing
+   * can be placed before or after it, so none is claimed (the server counts
+   * no unread without one either).
+   */
+  private knownFacts(channelId: string, state: ChannelRuntimeState, reader: Reader): Map<string, UnreadFact> {
+    const facts = new Map<string, UnreadFact>();
+    const marker = state.lastViewedMessageId;
+    if (!marker) return facts;
+    for (const [id, fact] of this.currentLoad(channelId, marker, reader)?.facts ?? []) facts.set(id, fact);
+    const markerIndex = state.messages.findIndex((message) => message.id === marker);
+    if (markerIndex < 0) return facts;
+    for (const message of state.messages.slice(markerIndex + 1)) {
+      if (message.user.id === reader.id || message.clientStatus) continue;
+      facts.set(message.id, unreadFact(message, reader));
+    }
+    return facts;
+  }
+
+  private async load(channelId: string, marker: string, reader: Reader, wanted: number): Promise<void> {
+    const generation = this.generation;
+    this.inFlight.add(channelId);
+    const previous = this.currentLoad(channelId, marker, reader);
+    try {
+      const messages = await readAfter(channelId, previous?.newestId ?? marker);
+      if (generation !== this.generation) return;
+      const facts = new Map(previous?.facts);
+      for (const message of messages) {
+        if (message.user.id !== reader.id) facts.set(message.id, unreadFact(message, reader));
+      }
+      this.loaded.set(channelId, {
+        userId: reader.id,
+        username: reader.username,
+        markerId: marker,
+        facts,
+        newestId: messages.at(-1)?.id ?? previous?.newestId ?? null,
+        loadedFor: wanted,
+        failedAt: null,
+      });
+    } catch {
+      if (generation !== this.generation) return;
+      this.loaded.set(channelId, {
+        userId: reader.id,
+        username: reader.username,
+        markerId: marker,
+        facts: previous?.facts ?? new Map(),
+        newestId: previous?.newestId ?? null,
+        loadedFor: previous?.loadedFor ?? 0,
+        failedAt: Date.now(),
+      });
+    } finally {
+      if (generation === this.generation) this.inFlight.delete(channelId);
+    }
+    this.options.onChange();
+  }
+}
+
+/** The one other person in a direct message, when the channel says who. */
+function directPerson(channel: ChatChannel | undefined): string | null {
+  return channel?.kind === "direct" ? channel.dmUser?.id ?? null : null;
+}
+
+/**
+ * Every message after `after`, oldest first. The server answers a request
+ * with the newest ones, so a long run reads back from the newest page to the
+ * one that reaches `after`.
+ */
+async function readAfter(channelId: string, after: string): Promise<ChatMessage[]> {
+  const pages: ChatMessage[][] = [];
+  let before: string | undefined;
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const messages = await apiClient.getMessages(channelId, { after, before, limit: PAGE_SIZE });
+    if (messages.length === 0) break;
+    pages.unshift(messages);
+    if (messages.length < PAGE_SIZE) break;
+    before = messages[0]!.id;
+  }
+  return pages.flat();
+}

package/src/plugins/builtin/chat/controller/view.ts

@@ -23,6 +23,7 @@ interface ChatControllerViewOptions {
   getListenerSnapshot: (channelId: string) => ChatControllerSnapshot;
   getVisibleMessages: (channelId: string) => ChatMessage[];
   getUnreadMentionCount: (channelId: string) => number;
+  getUnreadPeople: () => ChatControllerSnapshot["unreadPeople"];
 }
 
 interface ChannelListenerEntry {
@@ -78,6 +79,7 @@ export class ChatControllerView {
       draftAttachments: channel.draftAttachments.map(publicDraftAttachment),
       replyToId: channel.replyToId,
       unreadMentionCount: this.options.getUnreadMentionCount(normalizedChannelId),
+      unreadPeople: this.options.getUnreadPeople(),
     };
   }
 

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

@@ -157,7 +157,7 @@ export const chatModule: PluginModule = {
     chatController.attachPersistence(ctx.persistence, ctx.resume);
     chatSidebarStore.attach(ctx.persistence);
     chatHandlePromptStore.attach(ctx.persistence);
-    // The desktop app's Dock badge follows the Unread count; other hosts have no badge.
+    // The desktop app's Dock badge counts the people who wrote to you or tagged you, plus the missed notices; other hosts have no badge.
     disposeUnreadBadge?.();
     const badgeHost = getAppBadgeHost();
     disposeUnreadBadge = badgeHost

package/src/plugins/builtin/chat/share/flow.tsx

@@ -1,6 +1,6 @@
 import { apiClient } from "../../../../api-client";
 import { pngDataUrl } from "../../../../shares/pane-image";
-import { registerPaneChatSharing } from "../../../../shares/chat";
+import { registerPaneChatSharing, type ChatPostPurpose } from "../../../../shares/chat";
 import type { GloomPluginContext } from "../../../../types/plugin";
 import { requestAuthDialog } from "../../../../account/auth-dialog";
 import { MAX_CHAT_IMAGE_BYTES } from "../attachments/model";
@@ -11,6 +11,11 @@ import { defaultShareTarget, shareTargets } from "./targets";
 
 type ShareContext = Pick<GloomPluginContext, "notify" | "createPaneFromTemplate" | "configState">;
 const INCLUDE_LINK_KEY = "share.includeLink";
+/** How the sign-in and verify prompts finish "Sign in to ...". */
+const PURPOSE_TEXT: Record<ChatPostPurpose, string> = {
+  share: "share to chat",
+  "bug-report": "report a bug",
+};
 
 function errorText(error: unknown, fallback: string): string {
   return error instanceof Error && error.message ? error.message : fallback;
@@ -18,12 +23,13 @@ function errorText(error: unknown, fallback: string): string {
 
 /**
  * Whether the account can post, saying in one line what is missing when it
- * cannot: a sign-in (which then carries on with the share) or a verified email.
+ * cannot: a sign-in (which then carries on with the share or the bug report)
+ * or a verified email.
  */
-function readyToPost(ctx: ShareContext, retry: () => void): boolean {
+function readyToPost(ctx: ShareContext, retry: () => void, purpose: ChatPostPurpose): boolean {
   if (!apiClient.isSignedIn()) {
     ctx.notify({
-      body: "Sign in to share to chat.",
+      body: `Sign in to ${PURPOSE_TEXT[purpose]}.`,
       type: "info",
       action: { label: "Sign in", onClick: () => { requestAuthDialog({ onSignedIn: retry }); } },
     });
@@ -31,7 +37,7 @@ function readyToPost(ctx: ShareContext, retry: () => void): boolean {
   }
   if (!apiClient.isVerified()) {
     ctx.notify({
-      body: "Verify your email to share to chat.",
+      body: `Verify your email to ${PURPOSE_TEXT[purpose]}.`,
       type: "info",
       action: {
         label: "Resend link",
@@ -55,10 +61,14 @@ async function loadTargets() {
   return shareTargets(list ? buildChatConversations(list.states, list.userId) : []);
 }
 
+function openMessage(ctx: ShareContext, channelId: string, messageId: string): void {
+  ctx.createPaneFromTemplate("new-chat-pane", { arg: channelId, values: { messageId } });
+}
+
 /** Chat contributes a destination, never another menu entry, command or key. */
 export function installPaneChatSharing(ctx: ShareContext): () => void {
   return registerPaneChatSharing({
-    ready: (retry) => readyToPost(ctx, retry),
+    ready: (retry, purpose = "share") => readyToPost(ctx, retry, purpose),
     targets: loadTargets,
     defaultChannel: (targets) => defaultShareTarget(targets, ctx.configState.get<string>(LAST_VISITED_CHAT_CHANNEL_KEY)),
     includeLink: () => ctx.configState.get<boolean>(INCLUDE_LINK_KEY) !== false,
@@ -78,10 +88,9 @@ export function installPaneChatSharing(ctx: ShareContext): () => void {
       ctx.notify({
         body: `Posted to ${label}`,
         type: "success",
-        action: { label: "Open", onClick: () => {
-          ctx.createPaneFromTemplate("new-chat-pane", { arg: result.channelId, values: { messageId: result.messageId } });
-        } },
+        action: { label: "Open", onClick: () => { openMessage(ctx, result.channelId, result.messageId); } },
       });
     },
+    openMessage: (channelId, messageId) => openMessage(ctx, channelId, messageId),
   });
 }

package/src/plugins/builtin/chat/unread-badge.ts

@@ -1,9 +1,11 @@
+import type { ChatChannel } from "../../../api-client";
 import { appBadgeLabel } from "../../../notifications/app-badge";
 import type { NotificationLogEntry } from "../../../notifications/notification-log";
 import { unreadNotificationLogCount } from "../../../notifications/notification-log";
 import type { ChatControllerSnapshot } from "./controller/state";
 
 type UnreadSnapshot = Pick<ChatControllerSnapshot, "channelStates" | "hasSavedSession" | "user">;
+type BadgeSnapshot = UnreadSnapshot & Pick<ChatControllerSnapshot, "channels" | "unreadPeople">;
 
 /**
  * What the Unread list holds as unread, and what the status bar counts: the
@@ -16,9 +18,34 @@ export function unreadTotal(snapshot: UnreadSnapshot, notices: readonly Notifica
   return chat + unreadNotificationLogCount(notices);
 }
 
+/** DMs and group chats: what only the people in them read, and every message in them is for you. */
+function isPeopleConversation(channel: ChatChannel | undefined): boolean {
+  return channel?.kind === "direct" || channel?.kind === "group";
+}
+
+/**
+ * What the app badge counts: people, not messages. Everyone who sent you an
+ * unread DM or group message, and everyone whose unread message in any other
+ * channel mentions you, each once however many messages they sent or where;
+ * then every missed notice not yet read. Untagged channel messages add
+ * nothing. Zero signed out. The status bar keeps counting every unread
+ * message ({@link unreadTotal}).
+ */
+export function unreadBadgeCount(snapshot: BadgeSnapshot, notices: readonly NotificationLogEntry[]): number {
+  if (!snapshot.user && !snapshot.hasSavedSession) return 0;
+  const channels = new Map(snapshot.channels.map((channel) => [channel.id, channel]));
+  const people = new Set<string>();
+  for (const [channelId, who] of Object.entries(snapshot.unreadPeople)) {
+    for (const id of isPeopleConversation(channels.get(channelId)) ? who.senders : who.mentioners) people.add(id);
+  }
+  return people.size + unreadNotificationLogCount(notices);
+}
+
 interface UnreadBadgeOptions {
   controller: {
-    subscribe(listener: (snapshot: UnreadSnapshot) => void): () => void;
+    subscribe(listener: (snapshot: BadgeSnapshot) => void): () => void;
+    /** Starts reading who the unread messages are from; the returned stop ends it. */
+    trackUnreadPeople(): () => void;
   };
   log: {
     get(): readonly NotificationLogEntry[];
@@ -28,14 +55,16 @@ interface UnreadBadgeOptions {
 }
 
 /**
- * Keeps the app badge on the unread count: one `setBadge` per change of the
- * label, none while it stays the same (past 99 it reads `99+` however many
- * more arrive), and a clear when stopped, as when the plugin is turned off.
- * Signing out zeroes the count, which clears it. Returns the stop.
+ * Keeps the app badge on {@link unreadBadgeCount}: one `setBadge` per change
+ * of the label, none while it stays the same (past 99 it reads `99+` however
+ * many more arrive), and a clear when stopped, as when the plugin is turned
+ * off. Signing out zeroes the count, which clears it. While it runs the
+ * controller reads who the unread messages are from; a host with no badge
+ * never starts it, so reads nothing extra. Returns the stop.
  */
 export function watchUnreadBadge({ controller, log, setBadge }: UnreadBadgeOptions): () => void {
   let applied = "";
-  let snapshot: UnreadSnapshot | null = null;
+  let snapshot: BadgeSnapshot | null = null;
 
   const apply = (label: string) => {
     if (label === applied) return;
@@ -47,9 +76,10 @@ export function watchUnreadBadge({ controller, log, setBadge }: UnreadBadgeOptio
     }
   };
   const update = () => {
-    if (snapshot) apply(appBadgeLabel(unreadTotal(snapshot, log.get())));
+    if (snapshot) apply(appBadgeLabel(unreadBadgeCount(snapshot, log.get())));
   };
 
+  const stopTracking = controller.trackUnreadPeople();
   const stopController = controller.subscribe((next) => {
     snapshot = next;
     update();
@@ -59,6 +89,7 @@ export function watchUnreadBadge({ controller, log, setBadge }: UnreadBadgeOptio
   return () => {
     stopController();
     stopLog();
+    stopTracking();
     snapshot = null;
     apply("");
   };

package/src/plugins/builtin/cloud/askg/pane-attachment.ts

@@ -1,3 +1,4 @@
+import { paneFunctionLabel } from "../../../../ask-gloom/pane-context";
 import type { AskGloomPaneAttachment } from "../../../../ask-gloom/pane-request";
 import type { ASKGSessionContext, JsonValue } from "./protocol";
 
@@ -38,9 +39,7 @@ function sharesPaneContents(attached: ASKGAttachedPane): boolean {
 
 /** What the chip says: the function and what it shows, such as `DES AAPL`. */
 export function attachedPaneLabel(pane: AskGloomPaneAttachment): string {
-  const title = pane.title.trim() || pane.paneType;
-  if (!pane.code) return title;
-  return title.split(/\s+/)[0]?.toUpperCase() === pane.code ? title : `${pane.code} ${title}`;
+  return paneFunctionLabel(pane);
 }
 
 /** Drops whole lines from the end, then characters, until `fits` holds. */

package/src/plugins/builtin/futures-curve/headless.ts

@@ -3,7 +3,7 @@ import { futuresSpecLines } from "../../../market-data/futures-contract";
 import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneEntry, HeadlessPaneFreshness } from "../../../types/plugin";
 import { newestReportTime, oldestReportTime } from "../../../utils/utc-time";
 import { fetchFuturesCurve, loadCurveSpot, loadFuturesCurveAsOf } from "./client";
-import { basisSpotSymbol, catalogueCurveUnit, contractBasis, curveAsOfDate, curveBasisPercent, curveChangeText, curveContractCode, curvePrice, curveRoundedPrice, curveSpotLabel, curveSpreadLabel, curveTimestamp, curveUnitLabel, normalizeCurveRoot, thinContractCount, unsupportedCurveRootMessage, type ContractBasis } from "./model";
+import { basisSpotSymbol, BASIS_CONVENTION, blankBasisNote, catalogueCurveUnit, curveAsOfDate, curveBasisPercent, curveBasisRows, curveChangeText, curveContractCode, curvePrice, curveRoundedPrice, curveSpotLabel, curveSpotSource, curveSpreadLabel, curveTimestamp, curveUnitLabel, normalizeCurveRoot, shortDatedBasisNote, thinContractCount, unsupportedCurveRootMessage, type ContractBasis } from "./model";
 
 /** The root a report shows when none is given. */
 const DEFAULT_ROOT = "ES";
@@ -73,7 +73,9 @@ function specEntries(data: FuturesCurvePayload): HeadlessPaneEntry[] {
 
 export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
   discovery: { aliases: ["CTM"], dataRequirements: ["Gloom Cloud futures curve endpoint"],
-    limitations: ["Listed-contract catalogues can be incomplete.", "Ghosts and percentiles use the same listed contracts.", "Cboe VIX is daily settlement."] },
+    limitations: ["Listed-contract catalogues can be incomplete.", "Ghosts and percentiles use the same listed contracts.", "Cboe VIX is daily settlement.",
+    "Ann Basis is simple actual/365 on the latest trade against the spot quote, and noisy under 30 days to expiry."],
+    intents: ["futures basis trade", "cash and carry", "basis against spot"] },
   shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "root", description: "FUT root such as CL, ES, ZN or VX, or a CME crypto root (BTC, ETH, SOL, XRP). Defaults to ES." },
   // Only the pane reads the tab; the report always carries both.
   options: [{ key: "tab", description: "Curve or the full contract table.", type: "enum",
@@ -93,11 +95,15 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
       date ? loadFuturesCurveAsOf(root, date, ctx.apiClient) : fetchFuturesCurve(root, ctx.apiClient),
       spotSymbol ? loadCurveSpot(spotSymbol, ctx.marketData, now) : null,
     ]);
-    const bases = spot ? data.contracts.map((row) => contractBasis(row, spot)) : [];
+    const bases = spot ? curveBasisRows(data.contracts, spot) : null;
     const unit = curveUnitLabel(data);
     const terms = specEntries(data);
+    const source = spot ? curveSpotSource(spot) : null;
     const notices = [...args.argument ? [] : [`Showing ${DEFAULT_ROOT}. Try fn CTM ${EXAMPLE_ROOT}.`],
-      ...spot ? [spot.status === "ok" ? `Basis against ${curveSpotLabel(spot, root, now)}.` : `Basis blank: ${spot.reason}.`] : []];
+      ...spot ? [spot.status === "ok" ? `Basis against ${curveSpotLabel(spot, root, now)}${source ? ` (${source})` : ""}; not the CME reference rate.` : `Basis blank: ${spot.reason}.`] : []];
+    // The footnotes under the table: the convention, why a cell is blank, and where a short-dated rate is not to be trusted.
+    // Against a spot that is not usable every cell is blank for the spot's reason, which the notice above already gives.
+    const notes = spot && bases ? [BASIS_CONVENTION, ...spot.status === "ok" ? [blankBasisNote(data.contracts, bases), shortDatedBasisNote(data.contracts, bases, spot)].filter((note): note is string => !!note) : []] : [];
     // Dated by the contracts' own quotes; the same-contract history rows are a year of context, not observations.
     const quoted = data.contracts.map((row) => row.asOf);
     const freshness: HeadlessPaneFreshness = date
@@ -109,7 +115,7 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
       sections: [
         { title: "Contracts", columns: contractColumns(root, data.settlementDate ?? null,
           { basis: !!spot, last: data.source !== "cboe", notice: data.contracts.some((row) => row.firstNotice) }),
-          rows: data.contracts.map((row, index) => contractRow(row, data, root, !!date, bases[index])) },
+          rows: data.contracts.map((row) => contractRow(row, data, root, !!date, bases?.get(row.symbol))) },
         { title: "Front spread", rows: [{ label: curveSpreadLabel(data.slope), ...data.slope, value: curveRoundedPrice(data.slope.value, root),
           annualizedRollYield: data.slope.annualizedRollYield == null ? null : Number(data.slope.annualizedRollYield.toFixed(2)),
           percentile: rank(data.slope.percentile), rollPercentile: rank(data.slope.rollPercentile) }] },
@@ -117,7 +123,8 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
         ...data.ghosts.map((ghost) => ({ title: `${ghost.label} same-contract history`, rows: ghost.points.map((point) => ({ ...point })) })),
       ],
       errors: data.gaps,
-      metadata: { ...data, quoteUnit: unit, ...(spot ? { spot, basisBlankedThin: thinContractCount(bases) } : {}), ...(args.argument ? {} : { defaultArgument: DEFAULT_ROOT }),
+      ...(notes.length ? { notes } : {}),
+      metadata: { ...data, quoteUnit: unit, ...(spot && bases ? { spot, basisBlankedThin: thinContractCount(bases.values()) } : {}), ...(args.argument ? {} : { defaultArgument: DEFAULT_ROOT }),
         ...(notices.length ? { notices } : {}),
         complete: data.status === "available", percentileBasis: "Same-contract observations within one year; actual sample start/end retained" },
     };

package/src/plugins/builtin/futures-curve/index.tsx

@@ -1,7 +1,7 @@
 import type { PluginModule } from "../plugin-module";
 import { futuresCurveCache } from "./client";
 import { futuresCurveHeadless } from "./headless";
-import { CURVE_HORIZONS, CURVE_ROOTS, curveRootForTicker, DEFAULT_CURVE_HORIZON, normalizeCurveRoot } from "./model";
+import { BASIS_FORMULA, CURVE_HORIZONS, CURVE_ROOTS, curveRootForTicker, DEFAULT_CURVE_HORIZON, normalizeCurveRoot } from "./model";
 import { FuturesCurvePane } from "./pane";
 
 export const futuresCurveModule: PluginModule = {
@@ -17,8 +17,8 @@ export const futuresCurveModule: PluginModule = {
     }),
   }],
   paneTemplates: [{ id: "futures-curve-pane", paneId: "futures-curve", label: "Futures Curve",
-    description: "Listed futures contracts, historical curves, roll yield and open interest including VIX and CME crypto futures.",
-    keywords: ["ctm", "futures", "curve", "term structure", "contango", "backwardation", "roll", "vix", "crude oil", "natural gas"],
+    description: `Listed futures contracts, historical curves, roll yield and open interest including VIX and CME crypto futures, which add basis against spot: Ann Basis = ${BASIS_FORMULA}, simple actual/365.`,
+    keywords: ["ctm", "futures", "curve", "term structure", "contango", "backwardation", "roll", "basis", "basis trade", "carry", "annualised basis", "vix", "crude oil", "natural gas"],
     shortcut: { prefix: "CTM", aliases: ["CT"], argKind: "text", argPlaceholder: "root", argOptional: true,
       argOptions: () => CURVE_ROOTS },
     headless: futuresCurveHeadless,

package/src/plugins/builtin/futures-curve/model.ts

@@ -282,6 +282,10 @@ export interface CurveSpot {
   asOf: string | null;
   status: "ok" | "stale" | "missing";
   reason: string | null;
+  /** The listing the quote path reports for the pair (`CCC`), when it reports one. */
+  venue?: string;
+  /** Whether the quote is real-time or held back, as the quote path reports it. */
+  feed?: "real-time" | "delayed";
 }
 
 export interface SpotQuote {
@@ -289,6 +293,8 @@ export interface SpotQuote {
   lastUpdated: number;
   stale?: boolean;
   dataSource?: string;
+  listingExchangeName?: string;
+  exchangeName?: string;
 }
 
 const positive = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value > 0;
@@ -303,16 +309,20 @@ function quoteAge(ms: number): string {
 /** Judges one spot quote at `now`: usable, older than the rule allows, or absent. */
 export function curveSpot(symbol: string, quote: SpotQuote | null | undefined, now: number): CurveSpot {
   if (!quote || !positive(quote.price)) return { symbol, price: null, asOf: null, status: "missing", reason: `no ${symbol} quote` };
+  // What the quote path says about the quote itself, kept beside the price so the footer can name it.
+  const venue = (quote.listingExchangeName || quote.exchangeName)?.trim();
+  const feed: CurveSpot["feed"] = quote.dataSource === "live" ? "real-time" : quote.dataSource === "delayed" ? "delayed" : undefined;
+  const source = { ...venue ? { venue } : {}, ...feed ? { feed } : {} };
   const time = quote.lastUpdated;
   if (!Number.isFinite(time) || time <= 0) {
-    return { symbol, price: quote.price, asOf: null, status: "stale", reason: `${symbol} quote has no time` };
+    return { symbol, price: quote.price, asOf: null, status: "stale", reason: `${symbol} quote has no time`, ...source };
   }
   const asOf = new Date(time).toISOString().replace(".000Z", "Z");
   const age = now - time;
   const limit = SPOT_STALE_MS + (quote.dataSource === "delayed" ? DELAYED_SPOT_MS : 0);
-  if (age > limit) return { symbol, price: quote.price, asOf, status: "stale", reason: `${symbol} quote is ${quoteAge(age)} old` };
-  if (quote.stale === true) return { symbol, price: quote.price, asOf, status: "stale", reason: `${symbol} quote is stale` };
-  return { symbol, price: quote.price, asOf, status: "ok", reason: null };
+  if (age > limit) return { symbol, price: quote.price, asOf, status: "stale", reason: `${symbol} quote is ${quoteAge(age)} old`, ...source };
+  if (quote.stale === true) return { symbol, price: quote.price, asOf, status: "stale", reason: `${symbol} quote is stale`, ...source };
+  return { symbol, price: quote.price, asOf, status: "ok", reason: null, ...source };
 }
 
 /** How far the contract trades over (positive) or under spot, in percent. */
@@ -400,6 +410,56 @@ export function thinContractsNotice(count: number): string {
   return `Basis blank on ${count} thin contract${count === 1 ? "" : "s"} (last print over 1h before spot)`;
 }
 
+/** What the quote path reports of the spot itself, as the footer names it: `CCC, real-time`. Null when it reports neither. */
+export function curveSpotSource(spot: Pick<CurveSpot, "venue" | "feed">): string | null {
+  const parts = [spot.venue, spot.feed].filter((part): part is string => !!part);
+  return parts.length ? parts.join(", ") : null;
+}
+
+/** What Ann Basis is: Vs Spot is the same ratio before it is annualised. */
+export const BASIS_FORMULA = "(Last / spot - 1) × 365 / days to expiry";
+/** The two basis columns' convention in one line. */
+export const BASIS_CONVENTION = `Ann Basis = ${BASIS_FORMULA}: simple actual/365, the latest trade against the spot quote.`;
+
+/** Why one priced-or-not contract has no basis against a usable spot, in the order `contractBasis` decides it. */
+function blankReason(row: Pick<FuturesContract, "price" | "stale">, basis: ContractBasis): string | null {
+  if (basis.vsSpotPct != null) return null;
+  if (!positive(row.price)) return "no price";
+  if (row.stale) return "price over two sessions old";
+  return basis.thin ? "last trade over 1h before the spot quote" : null;
+}
+
+/**
+ * The contracts whose basis cells are blank against a good spot, grouped by cause and named, so a blank is never
+ * unexplained: the far months of a curve print rarely, and a print an hour before the spot is not read against it.
+ */
+export function blankBasisNote(rows: readonly Pick<FuturesContract, "symbol" | "price" | "stale">[], basis: CurveBasisRows): string | null {
+  const groups = new Map<string, string[]>();
+  for (const row of rows) {
+    const cell = basis.get(row.symbol);
+    const reason = cell ? blankReason(row, cell) : null;
+    if (reason) groups.set(reason, [...groups.get(reason) ?? [], curveContractCode(row.symbol)]);
+  }
+  return groups.size ? `Basis blank for ${[...groups].map(([reason, codes]) => `${codes.join(", ")} (${reason})`).join("; ")}.` : null;
+}
+
+/** Under this many days to expiry a few basis points of spot move the annualised rate by whole points. */
+const SHORT_DATED_DAYS = 30;
+/** The noise the note sizes the swing against: ten basis points of spot, a quote's usual gap to the contract's print. */
+const SPOT_NOISE_PCT = 0.1;
+
+/** The note for contracts showing an annualised basis inside `SHORT_DATED_DAYS`: what 10 bp of spot noise does to each. */
+export function shortDatedBasisNote(rows: readonly Pick<FuturesContract, "symbol" | "expiration">[], basis: CurveBasisRows, spot: CurveSpot | null): string | null {
+  if (!spot || spot.status !== "ok" || spot.asOf == null) return null;
+  const spotTime = Date.parse(spot.asOf);
+  const near = rows.flatMap((row) => {
+    if (basis.get(row.symbol)?.annualisedBasisPct == null) return [];
+    const days = daysToExpiry(spotTime, row.expiration);
+    return days != null && days > 0 && days < SHORT_DATED_DAYS ? [`${curveContractCode(row.symbol)} (${days}d) by ±${(SPOT_NOISE_PCT * 365 / days).toFixed(1)} points`] : [];
+  });
+  return near.length ? `Ann Basis is noisy under ${SHORT_DATED_DAYS} days to expiry: 10 bp of spot noise moves ${near.join(", ")}.` : null;
+}
+
 /** A past date for the as-of view: empty (or "latest") for the live curve, else YYYY-MM-DD no later than today. */
 export function curveAsOfDate(value: unknown, now = new Date()): string {
   const date = typeof value === "string" ? value.trim() : "";