gloomberb 0.16.1 → 0.16.3

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/resolution.ts

@@ -37,6 +37,21 @@ const RANGE_PRESET_RESOLUTION: Record<TimeRange, ManualChartResolution> = {
   "ALL": "1mo",
 };
 
+/**
+ * The bar size a price history for a range is served in, unlike the chart
+ * presets above: what `gloomberb history` and the historical prices pane get.
+ */
+export const RANGE_HISTORY_RESOLUTION: Readonly<Record<TimeRange, ManualChartResolution>> = {
+  "1D": "5m",
+  "1W": "1h",
+  "1M": "1d",
+  "3M": "1d",
+  "6M": "1d",
+  "1Y": "1d",
+  "5Y": "1wk",
+  "ALL": "1mo",
+};
+
 const RANGE_PRELOAD_BUFFER: Record<TimeRange, TimeRange> = {
   "1D": "1W",
   "1W": "1M",

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

@@ -38,7 +38,21 @@ export interface QuoteMetadata {
   fieldSources?: Partial<Record<"currency" | "instrumentType", QuoteMetadataSource>>;
 }
 
-export interface Quote {
+/**
+ * What a record's share counts count: depositary receipts or the ordinary
+ * shares behind them. Gloom Cloud states it only when it established it.
+ */
+export type ShareBasis = "depositary_receipt" | "ordinary";
+
+/** How a depositary receipt relates to the ordinary shares, as Gloom Cloud states it. */
+interface DepositaryReceiptFacts {
+  /** Whether the listing is a depositary receipt; absent when unknown. */
+  isDepositaryReceipt?: boolean;
+  /** Ordinary shares per receipt, on a receipt's own records. */
+  adrRatio?: number;
+}
+
+export interface Quote extends DepositaryReceiptFacts {
   /** Applies to this price observation; a stored position cannot supply it. */
   priceBasis?: PriceBasis;
   /** Daily fund net asset value; independent of the units used to format its price. */
@@ -58,6 +72,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;
@@ -106,7 +123,11 @@ export interface QuoteContribution extends Quote {
 
 export type QuoteContributionMap = Record<string, QuoteContribution>;
 
-export interface Fundamentals {
+export interface Fundamentals extends DepositaryReceiptFacts {
+  /** Every share count here is on this basis, the basis of the listing's price and market cap; absent when unproven. */
+  shareBasis?: ShareBasis;
+  /** On a receipt, the ordinary shares behind `sharesOutstanding`. */
+  underlyingOrdinaryShares?: number;
   source?: "gloom";
   fetchedAt?: string;
   stale?: boolean;
@@ -177,6 +198,8 @@ export interface HolderRecord {
   percentHeld?: number;
   changeShares?: number;
   changePercent?: number;
+  /** Set when the position's filing ties it to the receipts or to the ordinary shares. */
+  shareBasis?: ShareBasis;
 }
 
 interface HolderSummary {
@@ -186,11 +209,18 @@ interface HolderSummary {
   institutionsCount?: number;
 }
 
-export interface HolderData {
+export interface HolderData extends DepositaryReceiptFacts {
   providerId?: string;
   symbol: string;
   name?: string;
+  /** The listing's price currency. */
   currency?: string;
+  /** The currency of `value`, which can differ from the listing's (USD on a London line priced from 13F filings). */
+  valueCurrency?: string;
+  /** Reported shares times the latest price, or times the price at the report date. */
+  valueBasis?: "latest_price" | "period_end_price";
+  /** Set when every row is on one basis. */
+  shareBasis?: ShareBasis;
   exchange?: string;
   asOf?: string;
   summary?: HolderSummary;
@@ -427,6 +457,8 @@ export interface ReportedEarningsCohort {
 export interface EarningsResultProvenance { version: 1; reported: ReportedEarningsCohort }
 
 export interface FinancialStatement {
+  /** The basis of this row's share counts and per-share earnings; absent when unproven. */
+  shareBasis?: ShareBasis;
   /** @deprecated No longer populated. */
   earningsResult?: EarningsResultProvenance;
   /** EPS lines unavailable for this period, for example because they disagree with the row's own income and shares. */