gloomberb 0.16.1 → 0.16.2

package/src/theme/heat-colors.ts

@@ -1,5 +1,5 @@
-import { colors } from "./colors";
-import { blendHex, contrastRatio, relativeLuminance } from "./color-utils";
+import { colors, type ThemeColors } from "./colors";
+import { blendHex, contrastRatio, higherContrast, relativeLuminance } from "./color-utils";
 
 const HEATMAP_BASE_BLEND = 0.35;
 const HEATMAP_TEXT_MIN_CONTRAST = 4.5;
@@ -100,46 +100,66 @@ export function resolveHeatCellColors(
 }
 
 /**
- * Heat map tiles: one fixed diverging hue scale for every theme, so a move
- * reads the same in Amber as in GitHub Light. Losses run to a bright hot
- * pink, a flat session sits on a muted violet and gains run to a bright aqua;
- * pink against aqua also separates for red-green colour blindness, where red
- * against green does not. Each tile takes whichever text reads best on it,
- * white on the violet middle and a dark navy on the bright ends, at 4.5:1 or
- * better. The stops were sampled from a market wall's pinks, violets and
- * aquas. A light theme starts from a pale lavender so the page is not a dark
- * block; the ends stay the same.
+ * Heat map tiles take their colours from the selected theme. Losses run from
+ * a muted middle to the theme's negative colour and gains to its positive, so
+ * the strongest tiles are the app's own down and up colours. The middle is
+ * the theme's neutral tone, lifted off a dark page or set into a light one
+ * just far enough to read as a tile. Colour builds in OKLab, hue ahead of
+ * lightness so a small move already leans to its side, and is full at 3%.
+ * Each tile takes whichever of the theme's light or dark text reads better
+ * on it, or white or black where neither reaches 4.5:1.
  */
 const HEATMAP_TILE_FULL_SCALE_PERCENT = 3;
-/** How fast colour builds from flat: below 1 a small move already leans to its hue. */
+/** How fast colour builds from flat: below 1 a small move already leans to its side. */
 const HEATMAP_TILE_EASING = 0.8;
+/** Hue arrives ahead of lightness, so a mid-size move is a clear colour, not a grey. */
+const HEATMAP_TILE_HUE_LEAD = 0.4;
 const HEATMAP_TILE_TEXT_MIN_CONTRAST = 4.5;
-const HEATMAP_FLAT_DARK = { l: 0.53, c: 0.12, h: 296 } as const;
-const HEATMAP_FLAT_LIGHT = { l: 0.9, c: 0.035, h: 290 } as const;
-/** From flat to full strength, evenly spaced; dark pages pass a saturated middle stop on the way. */
-const HEATMAP_STOPS = {
-  dark: {
-    loss: [{ l: 0.62, c: 0.2, h: 350 }, { l: 0.7, c: 0.22, h: 356 }],
-    gain: [{ l: 0.64, c: 0.1, h: 205 }, { l: 0.8, c: 0.13, h: 185 }],
-  },
-  light: {
-    loss: [{ l: 0.7, c: 0.22, h: 356 }],
-    gain: [{ l: 0.8, c: 0.13, h: 185 }],
-  },
+/** How far the flat middle stands off the page, as contrast against the background. */
+const HEATMAP_FLAT_CONTRAST = { dark: 2.1, light: 1.4 } as const;
+/** A missing move sits between the page and the flat middle: there, but saying nothing. */
+const HEATMAP_MISSING_CONTRAST = { dark: 1.35, light: 1.16 } as const;
+/** The middle keeps a hint of the theme's neutral tint, never a colour of its own. */
+const HEATMAP_FLAT_MAX_CHROMA = 0.025;
+const HEATMAP_MISSING_MAX_CHROMA = 0.008;
+/** Light text tokens with more colour than this (a phosphor green, amber) are left off the tiles. */
+const HEATMAP_INK_MAX_CHROMA = 0.06;
+/** Luminance a token needs to count as the theme's light text, and may not exceed to count as its dark text. */
+const HEATMAP_INK_LUMINANCE = { light: 0.6, dark: 0.05 } as const;
+/** Below this an end has no hue to carry the scale. */
+const HEATMAP_END_MIN_CHROMA = 0.05;
+/** The full-strength end must stand this far from the flat middle... */
+const HEATMAP_END_MIN_FROM_FLAT = 0.12;
+/** ...and the two ends this far from each other. */
+const HEATMAP_ENDS_MIN_APART = 0.15;
+/**
+ * Only for a palette whose own up and down colours cannot carry the scale: an
+ * end too close to the page keeps its hue at this lightness, and an end with
+ * no hue, or two ends too alike, take the usual red and green.
+ */
+const HEATMAP_FALLBACK = {
+  lightness: { dark: 0.7, light: 0.52 },
+  chroma: 0.15,
+  lossHue: 25,
+  gainHue: 150,
 } as const;
-const HEATMAP_MISSING_DARK = "#3a3a40";
-const HEATMAP_MISSING_LIGHT = "#cfcfd6";
-const HEATMAP_TEXT_LIGHT = "#ffffff";
-const HEATMAP_TEXT_DARK = "#0a0d1f";
-/** Where neither white nor the navy reaches 4.5:1, black always does. */
-const HEATMAP_TEXT_BLACK = "#000000";
+/** How far a selected tile is pulled away from the page, further for a tile already near the end of the range. */
+const HEATMAP_SELECTED_LIFT = { start: 0.45, step: 0.05, max: 0.8 } as const;
+const HEATMAP_SELECTED_MIN_DISTANCE = 0.1;
 const HEATMAP_STEPS = 64;
+const HEATMAP_SCALE_CACHE_LIMIT = 32;
 
 export interface HeatmapTileColors {
   background: string;
   foreground: string;
 }
 
+/** A selected tile's outline on the desktop and the web: a ring, then a hairline of the page. */
+export interface HeatmapSelectionRing {
+  outer: string;
+  inner: string;
+}
+
 type Oklab = readonly [number, number, number];
 
 function srgbToLinear(channel: number): number {
@@ -168,89 +188,253 @@ export function hexToOklab(hex: string): Oklab {
   ];
 }
 
-function oklabToHex([lightness, a, b]: Oklab): string {
+function oklabToLinear([lightness, a, b]: Oklab): [number, number, number] {
   const l = (lightness + 0.3963377774 * a + 0.2158037573 * b) ** 3;
   const m = (lightness - 0.1055613458 * a - 0.0638541728 * b) ** 3;
   const s = (lightness - 0.0894841775 * a - 1.291485548 * b) ** 3;
-  const r = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
-  const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
-  const blue = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
-  return `#${[r, g, blue].map((channel) => linearToSrgb(channel).toString(16).padStart(2, "0")).join("")}`;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+
+function inGamut(color: Oklab): boolean {
+  return oklabToLinear(color).every((channel) => channel >= -0.0005 && channel <= 1.0005);
+}
+
+/** Into sRGB by giving up chroma, never lightness or hue, so a clipped colour cannot drift toward another. */
+function toGamut(color: Oklab): Oklab {
+  if (inGamut(color)) return color;
+  const [lightness, a, b] = color;
+  let low = 0;
+  let high = 1;
+  for (let index = 0; index < 20; index += 1) {
+    const mid = (low + high) / 2;
+    if (inGamut([lightness, a * mid, b * mid])) low = mid;
+    else high = mid;
+  }
+  return [lightness, a * low, b * low];
+}
+
+function oklabToHex(color: Oklab): string {
+  return `#${oklabToLinear(toGamut(color)).map((channel) => linearToSrgb(channel).toString(16).padStart(2, "0")).join("")}`;
+}
+
+function chromaOf(color: Oklab): number {
+  return Math.hypot(color[1], color[2]);
+}
+
+function oklabDistance(left: Oklab, right: Oklab): number {
+  return Math.hypot(left[0] - right[0], left[1] - right[1], left[2] - right[2]);
 }
 
-function lch({ l, c, h }: Lch): Oklab {
-  const radians = h * Math.PI / 180;
-  return [l, c * Math.cos(radians), c * Math.sin(radians)];
+/** The colour's hue at most `maxChroma` strong. */
+function tint(color: Oklab, maxChroma: number): [number, number] {
+  const chroma = chromaOf(color);
+  const scale = chroma > maxChroma ? maxChroma / chroma : 1;
+  return [color[1] * scale, color[2] * scale];
+}
+
+/**
+ * The lightness at which a tile of this tint stands `contrast` off the page:
+ * above a dark page, below a light one.
+ */
+function standOffPage(page: string, [a, b]: readonly [number, number], contrast: number, dark: boolean): Oklab {
+  const pageLightness = hexToOklab(page)[0];
+  let low = dark ? pageLightness : 0;
+  let high = dark ? 1 : pageLightness;
+  for (let index = 0; index < 24; index += 1) {
+    const mid = (low + high) / 2;
+    const reaches = contrastRatio(oklabToHex([mid, a, b]), page) >= contrast;
+    if (dark === reaches) high = mid;
+    else low = mid;
+  }
+  return toGamut([dark ? high : low, a, b]);
 }
 
-type Lch = { readonly l: number; readonly c: number; readonly h: number };
+interface HeatmapInks {
+  light: string;
+  dark: string;
+}
 
-/** Around the hue wheel the short way, so the scale passes through magenta and blue instead of grey. */
-function mixLch(from: Lch, to: Lch, ratio: number): Lch {
-  const turn = ((to.h - from.h + 540) % 360) - 180;
+/**
+ * The theme's own text for tiles: its lightest near-neutral tone and its
+ * darkest, with white and black where the theme has none.
+ */
+function heatmapInks(palette: ThemeColors): HeatmapInks {
+  const tokens = [palette.textBright, palette.text, palette.selectedText, palette.headerText, palette.bg, palette.panel];
+  const lights = tokens.filter((token) => relativeLuminance(token) >= HEATMAP_INK_LUMINANCE.light && chromaOf(hexToOklab(token)) <= HEATMAP_INK_MAX_CHROMA);
+  const darks = tokens.filter((token) => relativeLuminance(token) <= HEATMAP_INK_LUMINANCE.dark);
   return {
-    l: from.l + (to.l - from.l) * ratio,
-    c: from.c + (to.c - from.c) * ratio,
-    h: from.h + turn * ratio,
+    light: lights.reduce((best, token) => (relativeLuminance(token) > relativeLuminance(best) ? token : best), lights[0] ?? "#ffffff"),
+    dark: darks.reduce((best, token) => (relativeLuminance(token) < relativeLuminance(best) ? token : best), darks[0] ?? "#000000"),
   };
 }
 
-function heatmapTextColor(background: string): string {
-  const best = highestContrast([HEATMAP_TEXT_LIGHT, HEATMAP_TEXT_DARK], background);
+function heatmapTextColor(background: string, inks: HeatmapInks): string {
+  const best = higherContrast(inks.light, inks.dark, background);
   if (contrastRatio(best, background) >= HEATMAP_TILE_TEXT_MIN_CONTRAST) return best;
-  return highestContrast([HEATMAP_TEXT_LIGHT, HEATMAP_TEXT_BLACK], background);
+  return higherContrast("#ffffff", "#000000", background);
+}
+
+interface HeatmapEnd {
+  color: Oklab;
+  /** The theme's own token when it carries the scale as is. */
+  hex: string;
+}
+
+function fallbackEnd(hue: number, dark: boolean): HeatmapEnd {
+  const radians = hue * Math.PI / 180;
+  const color = toGamut([
+    dark ? HEATMAP_FALLBACK.lightness.dark : HEATMAP_FALLBACK.lightness.light,
+    HEATMAP_FALLBACK.chroma * Math.cos(radians),
+    HEATMAP_FALLBACK.chroma * Math.sin(radians),
+  ]);
+  return { color, hex: oklabToHex(color) };
+}
+
+/**
+ * The theme's up or down colour as the end of the scale. One that sits too
+ * close to the page keeps its hue at a lightness that stands clear; one with
+ * no hue to speak of gives way to the fallback.
+ */
+function heatmapEnd(token: string, fallbackHue: number, flat: Oklab, page: Oklab, dark: boolean): HeatmapEnd {
+  const color = hexToOklab(token);
+  const chroma = chromaOf(color);
+  if (chroma < HEATMAP_END_MIN_CHROMA) return fallbackEnd(fallbackHue, dark);
+  if (oklabDistance(color, flat) >= HEATMAP_END_MIN_FROM_FLAT && oklabDistance(color, page) >= oklabDistance(flat, page)) {
+    return { color, hex: token };
+  }
+  const scale = Math.max(chroma, HEATMAP_FALLBACK.chroma) / chroma;
+  const lifted = toGamut([
+    dark ? HEATMAP_FALLBACK.lightness.dark : HEATMAP_FALLBACK.lightness.light,
+    color[1] * scale,
+    color[2] * scale,
+  ]);
+  return { color: lifted, hex: oklabToHex(lifted) };
+}
+
+interface HeatmapScale {
+  /** 2 * HEATMAP_STEPS + 1 tiles from full loss to full gain. */
+  tiles: HeatmapTileColors[];
+  selected: HeatmapTileColors[];
+  missing: HeatmapTileColors;
+  missingSelected: HeatmapTileColors;
+  ring: HeatmapSelectionRing;
 }
 
-const heatmapScaleCache = new Map<string, HeatmapTileColors[]>();
+function buildHeatmapScale(palette: ThemeColors): HeatmapScale {
+  // Dark is defined as the theme defines it: text lighter than the page.
+  const dark = relativeLuminance(palette.text) > relativeLuminance(palette.bg);
+  const inks = heatmapInks(palette);
+  const page = hexToOklab(palette.bg);
+  // Halfway between the page's tint and the neutral's, so a warm page gets a warm grey and a black one the neutral's.
+  const neutral = hexToOklab(palette.neutral);
+  const grey: Oklab = [neutral[0], (page[1] + neutral[1]) / 2, (page[2] + neutral[2]) / 2];
+  const flat = standOffPage(palette.bg, tint(grey, HEATMAP_FLAT_MAX_CHROMA), dark ? HEATMAP_FLAT_CONTRAST.dark : HEATMAP_FLAT_CONTRAST.light, dark);
+  let loss = heatmapEnd(palette.negative, HEATMAP_FALLBACK.lossHue, flat, page, dark);
+  let gain = heatmapEnd(palette.positive, HEATMAP_FALLBACK.gainHue, flat, page, dark);
+  if (oklabDistance(loss.color, gain.color) < HEATMAP_ENDS_MIN_APART) {
+    loss = fallbackEnd(HEATMAP_FALLBACK.lossHue, dark);
+    gain = fallbackEnd(HEATMAP_FALLBACK.gainHue, dark);
+  }
 
-/** 2 * HEATMAP_STEPS + 1 colours from full loss to full gain, built once per light or dark page. */
-function heatmapScale(light: boolean): HeatmapTileColors[] {
-  const key = light ? "light" : "dark";
-  const cached = heatmapScaleCache.get(key);
-  if (cached) return cached;
-  const flat = light ? HEATMAP_FLAT_LIGHT : HEATMAP_FLAT_DARK;
-  const stops = HEATMAP_STOPS[key];
-  const scale: HeatmapTileColors[] = [];
+  const lift = dark ? inks.light : inks.dark;
+  const tile = (background: string): HeatmapTileColors => ({ background, foreground: heatmapTextColor(background, inks) });
+  const selectedTile = (background: string) => {
+    let ratio: number = HEATMAP_SELECTED_LIFT.start;
+    while (ratio < HEATMAP_SELECTED_LIFT.max && oklabDistance(hexToOklab(blendHex(background, lift, ratio)), hexToOklab(background)) < HEATMAP_SELECTED_MIN_DISTANCE) {
+      ratio += HEATMAP_SELECTED_LIFT.step;
+    }
+    return tile(blendHex(background, lift, Math.min(ratio, HEATMAP_SELECTED_LIFT.max)));
+  };
+  const tiles: HeatmapTileColors[] = [];
   for (let step = -HEATMAP_STEPS; step <= HEATMAP_STEPS; step += 1) {
+    const end = step < 0 ? loss : gain;
+    if (Math.abs(step) === HEATMAP_STEPS) {
+      tiles.push(tile(end.hex));
+      continue;
+    }
     const strength = (Math.abs(step) / HEATMAP_STEPS) ** HEATMAP_TILE_EASING;
-    const path: readonly Lch[] = [flat, ...(step < 0 ? stops.loss : stops.gain)];
-    const position = strength * (path.length - 1);
-    const segment = Math.min(path.length - 2, Math.floor(position));
-    const background = oklabToHex(lch(mixLch(path[segment]!, path[segment + 1]!, position - segment)));
-    scale.push({ background, foreground: heatmapTextColor(background) });
+    const hue = strength ** HEATMAP_TILE_HUE_LEAD;
+    tiles.push(tile(oklabToHex([
+      flat[0] + (end.color[0] - flat[0]) * strength,
+      flat[1] + (end.color[1] - flat[1]) * hue,
+      flat[2] + (end.color[2] - flat[2]) * hue,
+    ])));
   }
-  heatmapScaleCache.set(key, scale);
-  return scale;
+  const missing = tile(oklabToHex(standOffPage(
+    palette.bg,
+    tint(grey, HEATMAP_MISSING_MAX_CHROMA),
+    dark ? HEATMAP_MISSING_CONTRAST.dark : HEATMAP_MISSING_CONTRAST.light,
+    dark,
+  )));
+  return {
+    tiles,
+    selected: tiles.map(({ background }) => selectedTile(background)),
+    missing,
+    missingSelected: selectedTile(missing.background),
+    ring: { outer: lift, inner: palette.bg },
+  };
 }
 
-function isLightPage(): boolean {
-  return relativeLuminance(colors.bg) > 0.4;
-}
+const heatmapScaleCache = new Map<string, HeatmapScale>();
 
 /**
- * The tile colours for a day's move in percent. Full strength at +/-3%; a
- * missing move is neutral grey, never the flat colour, so it cannot pass for
- * an unchanged price.
+ * Built once per palette and keyed by its colours, never by its name or a
+ * light or dark flag, so a theme switch or an edited palette recolours the
+ * map at once.
  */
-export function resolveHeatmapTileColors(changePercent: number | null | undefined): HeatmapTileColors {
-  const light = isLightPage();
-  if (changePercent == null || !Number.isFinite(changePercent)) {
-    const background = light ? HEATMAP_MISSING_LIGHT : HEATMAP_MISSING_DARK;
-    return { background, foreground: heatmapTextColor(background) };
+function heatmapScale(palette: ThemeColors): HeatmapScale {
+  const key = `${palette.bg}|${palette.panel}|${palette.text}|${palette.textBright}|${palette.selectedText}|${palette.headerText}|${palette.neutral}|${palette.positive}|${palette.negative}`;
+  let scale = heatmapScaleCache.get(key);
+  if (!scale) {
+    scale = buildHeatmapScale(palette);
+    if (heatmapScaleCache.size >= HEATMAP_SCALE_CACHE_LIMIT) heatmapScaleCache.clear();
+    heatmapScaleCache.set(key, scale);
   }
+  return scale;
+}
+
+function heatmapStep(changePercent: number): number {
   const ratio = Math.max(-1, Math.min(1, changePercent / HEATMAP_TILE_FULL_SCALE_PERCENT));
-  return heatmapScale(light)[Math.round(ratio * HEATMAP_STEPS) + HEATMAP_STEPS]!;
+  return Math.round(ratio * HEATMAP_STEPS) + HEATMAP_STEPS;
+}
+
+function hasMove(changePercent: number | null | undefined): changePercent is number {
+  return changePercent != null && Number.isFinite(changePercent);
 }
 
-const HEATMAP_SELECTED_LIFT = 0.45;
+/**
+ * The tile colours for a day's move in percent. Full strength at +/-3%; a
+ * missing move is the theme's grey, never the flat colour, so it cannot pass
+ * for an unchanged price.
+ */
+export function resolveHeatmapTileColors(
+  changePercent: number | null | undefined,
+  palette: ThemeColors = colors,
+): HeatmapTileColors {
+  const scale = heatmapScale(palette);
+  return hasMove(changePercent) ? scale.tiles[heatmapStep(changePercent)]! : scale.missing;
+}
 
 /**
  * The selected tile on a cell grid, which cannot draw an outline: the same
- * hue lifted toward white, so the selection still says which way it moved.
+ * hue pulled away from the page, lighter on a dark theme and deeper on a
+ * light one, so the selection still says which way it moved.
  */
-export function resolveHeatmapSelectedTileColors(changePercent: number | null | undefined): HeatmapTileColors {
-  const background = blendHex(resolveHeatmapTileColors(changePercent).background, "#ffffff", HEATMAP_SELECTED_LIFT);
-  return { background, foreground: heatmapTextColor(background) };
+export function resolveHeatmapSelectedTileColors(
+  changePercent: number | null | undefined,
+  palette: ThemeColors = colors,
+): HeatmapTileColors {
+  const scale = heatmapScale(palette);
+  return hasMove(changePercent) ? scale.selected[heatmapStep(changePercent)]! : scale.missingSelected;
+}
+
+/** The selected tile's outline where one can be drawn: the theme's text tone against the page, then a hairline of the page. */
+export function resolveHeatmapSelectionRing(palette: ThemeColors = colors): HeatmapSelectionRing {
+  return heatmapScale(palette).ring;
 }
 
 const oklabCache = new Map<string, Oklab>();
@@ -267,7 +451,5 @@ export function heatmapColorDistance(left: string, right: string): number {
     }
     return value;
   };
-  const [l1, a1, b1] = read(left);
-  const [l2, a2, b2] = read(right);
-  return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+  return oklabDistance(read(left), read(right));
 }

package/src/time-series/resolve.ts

@@ -1647,7 +1647,7 @@ async function resolveChartSpecPass(
       || (request.bounds.end !== null && now() - (request.bounds.end + 1) < 60 * 60_000);
     const staleCurrent = (value: LoadedPriceHistory) => currentWindow() && !!value.session
       && isPriceHistoryStaleForCurrentWindow(value.points, now(), {
-        exchange: source.instrument.exchange, session: value.session,
+        symbol: source.instrument.symbol, exchange: source.instrument.exchange, session: value.session,
         ...(value.resolution ? { intervalMs: CHART_RESOLUTION_STEP_MS[value.resolution] } : {}),
       });
     if (staleCurrent(loaded)) {

package/src/time-series/use-chart-resolution.ts

@@ -105,7 +105,7 @@ function freshSeedPoints(
   // Broker contract/session interpretation remains unproven, as at acquisition.
   const session = instrument.instrument ? undefined : result.session;
   if (currentWindow && isIntradayResolution(resolution) && isPriceHistoryStaleForCurrentWindow(points, now, {
-    exchange: target.exchange, intervalMs: CHART_RESOLUTION_STEP_MS[resolution], session,
+    symbol: target.symbol, exchange: target.exchange, intervalMs: CHART_RESOLUTION_STEP_MS[resolution], session,
   })) return null;
   return points.length ? points : null;
 }

package/src/types/context-menu.ts

@@ -80,6 +80,12 @@ export type ContextMenuContext =
     layoutIndex: number;
     layoutName: string;
     active: boolean;
+  }
+  | {
+    /** A person's name or @mention in the chat. */
+    kind: "chat-user";
+    userId: string;
+    username: string | null;
   };
 
 export function hasRunnableContextMenuItem(items: readonly ContextMenuItem[]): boolean {

package/src/types/data-provider.ts

@@ -116,6 +116,8 @@ export interface MarketDataRequestContext {
   historyRequestKey?: string;
   /** Intraday history should include pre-market and after-hours bars where the source has them. */
   historySession?: "extended";
+  /** The listing's company, from its own quote: an SEC lookup for a non-US listing checks the registrant against it. */
+  listingName?: string;
 }
 
 export interface CachedFinancialsTarget {

package/src/types/financials.ts

@@ -58,6 +58,9 @@ export interface Quote {
   regularClose?: number;
   /** Exchange-local date of regularClose; separate from the daily previous-close reference. */
   regularCloseSessionDate?: string;
+  /** Move of that completed regular session from the one before it, in this quote's currency; set and cleared together with regularClose. */
+  regularChange?: number;
+  regularChangePercent?: number;
   /** Provider's exchange-local session date for the daily quote reference. */
   changeSessionDate?: string;
   high52w?: number;

package/src/types/headless.ts

@@ -71,7 +71,12 @@ export interface HeadlessPaneContext {
   settings?: Record<string, unknown>;
   capabilities?: CapabilityInvoker;
   /** Read one local portfolio without passing holdings through a remote endpoint. */
-  resolvePortfolio?: (id: string) => Promise<{ portfolio: import("./ticker").Portfolio; tickers: import("./ticker").TickerRecord[] } | null>;
+  resolvePortfolio?: (id: string) => Promise<{
+    portfolio: import("./ticker").Portfolio;
+    tickers: import("./ticker").TickerRecord[];
+    /** The broker account the portfolio was last synced with, as saved on this device. */
+    account?: import("./trading").BrokerAccount | null;
+  } | null>;
   /** Read locally remembered watchlist membership. */
   resolveWatchlist?: (id: string) => Promise<import("./ticker").TickerRecord[] | null>;
   /** Resolve locally remembered exchange identities without coupling plugins to storage. */
@@ -97,6 +102,63 @@ export interface HeadlessPaneEntry {
   formatted?: string;
 }
 
+/**
+ * How current a report's data is (docs/usage.md#how-current-a-report-is):
+ * - `live`: a real-time feed, such as a streaming venue or a real-time quote.
+ * - `delayed`: a feed held back on purpose, by `delayMinutes` when known.
+ * - `stale`: a feed or scheduled release whose newest observation is older
+ *   than that kind of data allows.
+ * - `not-a-feed`: data that is not a feed at all (filings, fundamentals,
+ *   calendars, statistics releases, calculators, local portfolio data). It
+ *   never reads stale just because it is old.
+ */
+export type HeadlessFreshnessStatus = "live" | "delayed" | "stale" | "not-a-feed";
+
+/**
+ * What a report can cite about its data. Every field is optional: the report
+ * fills what is missing from the result itself (quote `dataSource`,
+ * `delayMinutes`, `stale`, `asOf`/`observedAt`/`lastUpdated` fields, the last
+ * point of each series), so a pane declares only what that would get wrong.
+ */
+export interface HeadlessPaneFreshness {
+  /**
+   * Who a reader would cite: the venue, exchange or agency for primary data
+   * ("SEC EDGAR", "Hyperliquid"), "Gloom Cloud" for aggregated market data,
+   * "Local data" or "Your inputs". Never a data vendor or an internal provider id.
+   */
+  source?: string;
+  /** Newest observation in the data. A `YYYY-MM-DD` string reads as a date without a time. */
+  asOf?: string | number | Date | null;
+  /** Oldest observation, mentioned when it is far older than `asOf`; `null` when the rows are a history. */
+  oldest?: string | number | Date | null;
+  /**
+   * The row field that says when each row was observed, when it is not one of
+   * the standard names (`asOf`, `observedAt`, `lastUpdated`...). The report is
+   * then dated by that field alone, not by metadata stamps.
+   */
+  observedKey?: string;
+  status?: HeadlessFreshnessStatus;
+  /** How far a delayed feed is held back, in minutes. */
+  delayMinutes?: number;
+  /** What not-a-feed data is, in a few words: "filed data", "monthly release", "your inputs". */
+  basis?: string;
+  /** The newest observation is stale once it is older than this many minutes. */
+  maxAgeMinutes?: number;
+  /**
+   * The rows' and metadata's own `stale` flags mean something other than "this
+   * value is out of date" (a historical marker, a cache state), so the report
+   * judges staleness from the schedule alone.
+   */
+  ignoreStaleFlags?: boolean;
+  /**
+   * `daily`: one observation per US trading day, stale once more than one
+   * completed session has passed after the newest (a day's lag is allowed).
+   */
+  cadence?: "daily";
+  /** The newest observation is stale once this time (the next scheduled release) has passed by a day. */
+  nextExpectedAt?: string | number | Date | null;
+}
+
 interface HeadlessPaneResultBase {
   /** False when usable output does not fully cover the requested inputs/depth. */
   complete?: boolean;
@@ -104,8 +166,17 @@ interface HeadlessPaneResultBase {
   symbols?: string[];
   /** Missing inputs must remain visible even when other inputs returned rows. */
   unavailableSymbols?: string[];
+  /** Failures: a source that did not answer, or a value that could not be computed. */
   errors?: string[];
+  /**
+   * Caveats about a report that did load: what it leaves out, what it assumes,
+   * how a value was marked. One sentence each. They never make a report fail;
+   * `complete: false` says when the report does not cover what was asked.
+   */
+  notes?: string[];
   metadata?: Record<string, unknown>;
+  /** What this load knows about its data's source and age; overrides the definition's `freshness`. */
+  freshness?: HeadlessPaneFreshness;
 }
 
 export interface HeadlessRowsResult extends HeadlessPaneResultBase {
@@ -185,8 +256,14 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
   description?: string;
   argument: HeadlessPaneArgumentDef;
   options: HeadlessPaneOptionDef[];
+  /** What is true of every load: its source, and whether it is a feed. */
+  freshness?: HeadlessPaneFreshness;
   columns?: HeadlessPaneColumn[];
-  describe?: string | ((args: HeadlessPaneLoadArgs) => string);
+  /**
+   * The report title. A report passes the loaded result, so a title can name
+   * what the load resolved (the view an `auto` query became, a fund's name).
+   */
+  describe?: string | ((args: HeadlessPaneLoadArgs, result?: HeadlessPaneResult) => string);
   load(
     args: HeadlessPaneLoadArgs,
     ctx: HeadlessPaneContext,

package/src/types/plugin.ts

@@ -1,10 +1,11 @@
 import type { ReactNode } from "react";
 import type { AppTickerRepositoryPort } from "../core/app-service-ports";
-import type { HeadlessPaneDefinition } from "./headless";
+import type { HeadlessPaneDefinition, HeadlessPaneFreshness } from "./headless";
 
 export type {
   HeadlessBundleResult,
   HeadlessBundleSection,
+  HeadlessFreshnessStatus,
   HeadlessPaneApiClient,
   HeadlessPaneArgumentDef,
   HeadlessPaneArgumentKind,
@@ -12,6 +13,7 @@ export type {
   HeadlessPaneContext,
   HeadlessPaneDefinition,
   HeadlessPaneEntry,
+  HeadlessPaneFreshness,
   HeadlessPaneLoadArgs,
   HeadlessPaneOptionDef,
   HeadlessPaneOptionType,
@@ -124,6 +126,12 @@ export interface PaneDef {
   tickerFollower?: boolean | ((pane: PaneInstanceConfig) => boolean);
   /** Renderer-neutral data model used by CLI functions, automation, and hosted tools. */
   headless?: HeadlessPaneDefinition;
+  /**
+   * Source and status a rendered-view report (`fn` on a pane without a
+   * `headless` model) cites, when "Gloom Cloud" with the state the footer
+   * shows would be wrong: local data, a calculator, filed records.
+   */
+  reportFreshness?: Pick<HeadlessPaneFreshness, "source" | "status" | "basis">;
   /** Add an Excel-compatible CSV action for the pane's single active DataTable. */
   tableExport?: true;
   settings?: PaneSettingsDef | ((context: PaneSettingsContext) => PaneSettingsDef | null);
@@ -146,6 +154,12 @@ export interface PaneQuickSettingDef {
    * it off picks the field's other option.
    */
   onValue?: string;
+  /**
+   * Shows the control only where it changes something, for a setting that
+   * applies to some of what the pane can show. The field stays in the
+   * settings dialog either way.
+   */
+  visible?: (context: PaneSettingsContext) => boolean;
 }
 
 export interface PaneSettingsContext {
@@ -264,6 +278,11 @@ interface PaneTemplateShortcut {
   aliases?: readonly string[];
   argPlaceholder?: string;
   argKind?: "text" | "ticker" | "ticker-list";
+  /**
+   * For a ticker list, entries kept as typed instead of resolved as tickers:
+   * CORR keeps map series (`GEO:HORMUZ`) beside its tickers.
+   */
+  keepArgToken?: (token: string) => boolean;
   argOptional?: boolean;
   /**
    * With no argument typed and none to infer from the active ticker, open