gloomberb 0.20.9 → 0.20.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/package.json +1 -1
  2. package/src/api-client/auth.ts +6 -0
  3. package/src/api-client/data.ts +1 -0
  4. package/src/api-client/earnings.ts +15 -0
  5. package/src/api-client/index.ts +14 -3
  6. package/src/api-client/types/account.ts +10 -0
  7. package/src/api-client/types/billing.ts +10 -0
  8. package/src/api-client/types/econ.ts +19 -7
  9. package/src/api-client/types/market.ts +7 -0
  10. package/src/api-client/types/screener.ts +2 -0
  11. package/src/cli/commands/market.ts +18 -8
  12. package/src/cli/commands/overview.ts +26 -7
  13. package/src/cli/commands/ticker.ts +40 -15
  14. package/src/cli/desktop-pane-shot.ts +39 -0
  15. package/src/cli/errors.ts +20 -3
  16. package/src/cli/fx-pair.ts +11 -2
  17. package/src/cli/history-rows.ts +34 -3
  18. package/src/cli/index.ts +1 -1
  19. package/src/cli/listing-arg.ts +51 -13
  20. package/src/cli/pane-functions/headless.ts +4 -2
  21. package/src/cli/pane-functions/index.ts +1 -0
  22. package/src/cli/pane-functions/resolver.ts +2 -1
  23. package/src/cli/pane-functions/screenshot-assessment.ts +73 -5
  24. package/src/cli/pane-functions/screenshot-types.ts +4 -0
  25. package/src/components/chart/composite/chart-layout.ts +7 -4
  26. package/src/components/chart/composite/composite-chart.tsx +6 -16
  27. package/src/components/chart/composite/toolbar.tsx +258 -82
  28. package/src/components/chart/composite/use-composite-chart-keyboard.ts +5 -6
  29. package/src/components/command-bar/list/model.ts +13 -0
  30. package/src/components/command-bar/routes/ticker-search/actions.ts +2 -0
  31. package/src/components/command-bar/routes/ticker-search/results.ts +15 -8
  32. package/src/components/command-bar/surface/index.tsx +10 -5
  33. package/src/components/command-bar/workflow/alert.ts +21 -7
  34. package/src/components/data-table/table-pane.ts +3 -1
  35. package/src/components/layout/pane/footer/model.ts +26 -1
  36. package/src/components/metric-treemap/heat-surface.tsx +2 -1
  37. package/src/components/metric-treemap/index.tsx +3 -2
  38. package/src/components/ui/confirm-dialog.tsx +253 -7
  39. package/src/components/ui/data-table/index.tsx +1 -1
  40. package/src/components/ui/data-table/types.ts +7 -0
  41. package/src/components/ui/list-view.tsx +4 -3
  42. package/src/components/ui/status.tsx +9 -6
  43. package/src/docs/snapshot.json +36 -0
  44. package/src/i18n/es.ts +12 -0
  45. package/src/i18n/ja.ts +12 -0
  46. package/src/i18n/ko.ts +12 -0
  47. package/src/i18n/zh-cn.ts +12 -0
  48. package/src/i18n/zh-tw.ts +12 -0
  49. package/src/market-data/fx-closes.ts +14 -2
  50. package/src/market-data/market/change-basis.ts +35 -1
  51. package/src/market-data/market/status.ts +37 -0
  52. package/src/market-data/performance.ts +4 -1
  53. package/src/market-data/quotes/live-valuation.ts +25 -2
  54. package/src/market-data/realized-volatility.ts +3 -0
  55. package/src/market-data/us-bond-market.ts +115 -0
  56. package/src/plugins/builtin/account-management/invite-row.tsx +54 -0
  57. package/src/plugins/builtin/account-management/keyboard.ts +3 -0
  58. package/src/plugins/builtin/account-management/model.ts +1 -0
  59. package/src/plugins/builtin/account-management/pane.tsx +51 -5
  60. package/src/plugins/builtin/account-management/trial-cancel.ts +32 -7
  61. package/src/plugins/builtin/cloud/askg/pane-session.ts +94 -0
  62. package/src/plugins/builtin/cloud/askg/pane.tsx +40 -83
  63. package/src/plugins/builtin/congress-trades/pane.tsx +8 -2
  64. package/src/plugins/builtin/correlation/compute.ts +4 -3
  65. package/src/plugins/builtin/earnings/board-model.ts +33 -0
  66. package/src/plugins/builtin/earnings/board-table.ts +50 -11
  67. package/src/plugins/builtin/earnings/board.tsx +29 -13
  68. package/src/plugins/builtin/earnings/calendar.tsx +15 -3
  69. package/src/plugins/builtin/earnings/client.ts +4 -1
  70. package/src/plugins/builtin/earnings/headless.ts +27 -14
  71. package/src/plugins/builtin/econ/calendar-source.ts +3 -0
  72. package/src/plugins/builtin/help/index.tsx +1 -1
  73. package/src/plugins/builtin/ipo-calendar/model.ts +3 -3
  74. package/src/plugins/builtin/iv-history/headless.ts +12 -10
  75. package/src/plugins/builtin/macro-day/headless.ts +15 -5
  76. package/src/plugins/builtin/macro-day/model.ts +17 -4
  77. package/src/plugins/builtin/macro-day/releases.ts +36 -15
  78. package/src/plugins/builtin/market-halts/model.ts +3 -2
  79. package/src/plugins/builtin/market-movers/headless.ts +2 -1
  80. package/src/plugins/builtin/market-movers/index.tsx +3 -2
  81. package/src/plugins/builtin/market-movers/model.ts +75 -22
  82. package/src/plugins/builtin/market-movers/screener.ts +2 -1
  83. package/src/plugins/builtin/market-movers/table.ts +7 -5
  84. package/src/plugins/builtin/pe-band/model.ts +4 -0
  85. package/src/plugins/builtin/portfolio-list/cell-version.ts +4 -4
  86. package/src/plugins/builtin/portfolio-list/cli/render.ts +9 -4
  87. package/src/plugins/builtin/portfolio-list/pane/index.tsx +2 -1
  88. package/src/plugins/builtin/portfolio-list/summary/index.tsx +24 -7
  89. package/src/plugins/builtin/portfolio-list/summary/totals.ts +40 -11
  90. package/src/plugins/builtin/portfolio-list/table.tsx +13 -1
  91. package/src/plugins/builtin/research/analyst-headless.ts +9 -1
  92. package/src/plugins/builtin/research/analyst-pane.tsx +10 -4
  93. package/src/plugins/builtin/research/client.ts +25 -1
  94. package/src/plugins/builtin/research/corporate-actions-pane.tsx +2 -1
  95. package/src/plugins/builtin/research/event-model.ts +3 -13
  96. package/src/plugins/builtin/research/event-sources.ts +3 -1
  97. package/src/plugins/builtin/short-interest/headless.ts +2 -0
  98. package/src/plugins/builtin/short-interest/publications-headless.ts +2 -0
  99. package/src/plugins/builtin/short-interest/watch-headless.ts +1 -0
  100. package/src/plugins/builtin/yield-curve/headless.ts +5 -1
  101. package/src/plugins/builtin/yield-curve/index.tsx +5 -0
  102. package/src/portfolio/column-values.ts +47 -14
  103. package/src/portfolio/return-metrics.ts +4 -2
  104. package/src/renderers/dom/host/image-surface.tsx +19 -9
  105. package/src/renderers/dom/host/input.tsx +4 -0
  106. package/src/renderers/electrobun/view/cli-pane-shot-entry.tsx +23 -1
  107. package/src/sources/gloomberb-cloud/normalizers.ts +2 -0
  108. package/src/sources/provider-errors.ts +12 -0
  109. package/src/sources/provider-router/index.ts +12 -4
  110. package/src/state/pane-session.ts +145 -0
  111. package/src/tickers/search/home-listing.ts +44 -1
  112. package/src/tickers/search/index.ts +5 -2
  113. package/src/tickers/search/ranking.ts +7 -7
  114. package/src/tickers/us-listing.ts +11 -5
  115. package/src/time-series/base-series.ts +7 -1
  116. package/src/time-series/fundamentals/current-valuation.ts +8 -0
  117. package/src/time-series/fundamentals/series.ts +6 -0
  118. package/src/time-series/resolve.ts +1 -0
  119. package/src/types/financials.ts +20 -0
  120. package/src/types/headless.ts +9 -0
  121. package/src/ui/host.tsx +2 -0
  122. package/src/utils/exchanges.ts +13 -8
  123. package/src/utils/price-earnings.ts +17 -10
  124. package/src/utils/price-history-integrity.ts +15 -0
  125. package/src/utils/reason-codes.ts +79 -0
  126. package/src/utils/share-multiples.cases.json +889 -0
  127. package/src/utils/share-multiples.ts +254 -0
  128. package/src/utils/untrusted-text.ts +11 -0
@@ -127,6 +127,8 @@ export interface DesktopPaneShotBridge {
127
127
  }
128
128
 
129
129
  interface DesktopPaneShotRenderedCell {
130
+ /** The column can be blank in every row with nothing missing (DataTableColumn.mayBeBlank). */
131
+ mayBeBlank?: true;
130
132
  columnId?: string;
131
133
  columnLabel: string;
132
134
  text: string;
@@ -195,6 +197,12 @@ export interface DesktopPaneShotRenderResult {
195
197
  * the body shows anything more.
196
198
  */
197
199
  emptyStateText?: string[];
200
+ /**
201
+ * What each visible error and empty state says, its title and message
202
+ * without its buttons, a line each: the words a `--strict` Reason quotes.
203
+ * Absent when no state shows, or in a capture that did not read them.
204
+ */
205
+ stateText?: { error?: string[]; empty?: string[] };
198
206
  /** A wall that needs an account, or a Pro lock on part of the pane. */
199
207
  accessGate?: PaneAccessGate | null;
200
208
  /**
@@ -894,6 +902,7 @@ async function readRenderedPaneState(session: CdpPage): Promise<DesktopPaneShotR
894
902
  const exact = Number(cell.getAttribute("data-gloom-cell-value") || "NaN");
895
903
  return {
896
904
  ...(typeof semanticColumn.id === "string" ? { columnId: semanticColumn.id } : {}),
905
+ ...(semanticColumn.mayBeBlank === true ? { mayBeBlank: true } : {}),
897
906
  columnLabel: typeof semanticColumn.label === "string"
898
907
  ? semanticColumn.label
899
908
  : headers[cellIndex] || (values.length === 1 ? "Row" : String(cellIndex + 1)),
@@ -979,6 +988,25 @@ async function readRenderedPaneState(session: CdpPage): Promise<DesktopPaneShotR
979
988
  .map((child) => normalize(child.innerText || child.textContent))
980
989
  .filter(Boolean);
981
990
  })(),
991
+ // What each visible error and empty state says, for the Reason a strict capture gives.
992
+ stateText: (() => {
993
+ const said = (status) => [...new Set([...root.querySelectorAll('[data-gloom-status="' + status + '"]')]
994
+ // The innermost: a pane's status body holds the state it draws.
995
+ .filter((state) => isVisible(state) && !state.querySelector('[data-gloom-status="' + status + '"]'))
996
+ .map((state) => {
997
+ const parts = state.children.length > 0 ? [...state.children] : [state];
998
+ return parts
999
+ .filter((part) => isVisible(part) && !part.matches('button, [role="button"]') && !part.querySelector('button, [role="button"]'))
1000
+ .map((part) => normalize(part.innerText || part.textContent))
1001
+ .filter(Boolean)
1002
+ // A title and its message read as two sentences.
1003
+ .reduce((text, part) => !text ? part : /[.!?:]$/.test(text) ? text + " " + part : text + ". " + part, "");
1004
+ })
1005
+ .filter(Boolean))].slice(0, 3);
1006
+ const error = said("error");
1007
+ const empty = said("empty");
1008
+ return { ...(error.length ? { error } : {}), ...(empty.length ? { empty } : {}) };
1009
+ })(),
982
1010
  contentFigures: (${countContentFigures.toString()})(root, isVisible),
983
1011
  // The shared sign-in wall and the Pro lock prompt every gated pane draws.
984
1012
  accessGate: [...root.querySelectorAll('[data-gloom-ui="sign-in-wall"]')].some(isVisible) ? "sign-in"
@@ -1007,6 +1035,7 @@ async function readRenderedPaneState(session: CdpPage): Promise<DesktopPaneShotR
1007
1035
  errorStateDetected?: boolean;
1008
1036
  emptyStateDetected?: boolean;
1009
1037
  emptyStateText?: string[];
1038
+ stateText?: { error?: unknown; empty?: unknown };
1010
1039
  contentFigures?: number;
1011
1040
  accessGate?: string;
1012
1041
  rows?: DesktopPaneShotRenderedRow[];
@@ -1062,11 +1091,21 @@ async function readRenderedPaneState(session: CdpPage): Promise<DesktopPaneShotR
1062
1091
  ...(Array.isArray(value?.emptyStateText) && value.emptyStateText.length > 0
1063
1092
  ? { emptyStateText: value.emptyStateText.filter((line): line is string => typeof line === "string" && line.length > 0) } : {}),
1064
1093
  accessGate,
1094
+ ...shotStateText(value?.stateText),
1065
1095
  ...(typeof value?.contentFigures === "number" ? { contentFigures: value.contentFigures } : {}),
1066
1096
  semanticUi: Array.isArray(value?.semanticUi) ? value.semanticUi : [],
1067
1097
  };
1068
1098
  }
1069
1099
 
1100
+ /** The state words a page read, as strings only; nothing when it read none. */
1101
+ function shotStateText(value: { error?: unknown; empty?: unknown } | undefined): Pick<DesktopPaneShotRenderResult, "stateText"> {
1102
+ const lines = (said: unknown) => Array.isArray(said) ? said.filter((line): line is string => typeof line === "string" && line.length > 0) : [];
1103
+ const error = lines(value?.error);
1104
+ const empty = lines(value?.empty);
1105
+ if (error.length === 0 && empty.length === 0) return {};
1106
+ return { stateText: { ...(error.length ? { error } : {}), ...(empty.length ? { empty } : {}) } };
1107
+ }
1108
+
1070
1109
  /** Draws the first variant that fits the pane footer, and returns what it drew. */
1071
1110
  async function fitShotStatusLine(session: CdpPage, { variants, dates }: ShotStatusLineVariants): Promise<string | null> {
1072
1111
  const result = await session.send("Runtime.evaluate", {
package/src/cli/errors.ts CHANGED
@@ -6,6 +6,7 @@ import { cliStyles, cliTerminalWidth, wrapText } from "../utils/cli-output";
6
6
  import { withSearchHints, type FredSeriesCheck } from "./not-a-ticker";
7
7
  import { isProviderBusy, isSourceFailure, SEARCH_BUSY_CODE, SEARCH_BUSY_MESSAGE, serviceDidNotAnswerMessage } from "../sources/provider-errors";
8
8
  import { DATA_SERVICE_UNREACHABLE_MESSAGE, isNetworkFailure } from "../utils/network-failure";
9
+ import { isReasonCode, readableError } from "../utils/reason-codes";
9
10
 
10
11
  const USAGE_PREFIX = "Usage: ";
11
12
  /** The code of every error a command fails with: bad input, nothing found, an option it does not take. */
@@ -144,9 +145,25 @@ function cliErrorObject(error: unknown): CliErrorObject {
144
145
  if (error instanceof ApiRequestError && error.status === 400) {
145
146
  return { code: CLI_ERROR_CODE, message: error.message };
146
147
  }
148
+ const message = error instanceof Error ? error.message : String(error);
149
+ // A read that ended in the data service's bare reason code: it had nothing, or its source failed and may answer later.
150
+ if (isReasonCode(message)) {
151
+ return NOTHING_CODES.has(message.trim())
152
+ ? { code: NO_DATA_CODE, message }
153
+ : { code: SOURCE_UNAVAILABLE_CODE, message, retryable: true };
154
+ }
155
+ return { code: "unexpected_error", message };
156
+ }
157
+
158
+ /** The reason codes that say the data service has nothing, as opposed to a source that failed. */
159
+ const NOTHING_CODES = new Set(["NO_DATA", "NOT_FOUND", "BAD_MAPPING"]);
160
+
161
+ /** What a failure says in words: a reason code (UPSTREAM_ERROR) in its message or details reads as what happened. */
162
+ function readableCliError(error: CliErrorObject): CliErrorObject {
147
163
  return {
148
- code: "unexpected_error",
149
- message: error instanceof Error ? error.message : String(error),
164
+ ...error,
165
+ message: readableError(error.message),
166
+ ...(typeof error.details === "string" ? { details: readableError(error.details) } : {}),
150
167
  };
151
168
  }
152
169
 
@@ -197,7 +214,7 @@ function hintedError(error: CliErrorObject, args: readonly string[], isFredSerie
197
214
 
198
215
  export function printCliError(error: unknown, options: CliGlobalOptions, context: CliErrorContext = {}): void {
199
216
  if (options.quiet && options.format === "text") return;
200
- const errorObject = cliErrorObject(error);
217
+ const errorObject = readableCliError(cliErrorObject(error));
201
218
  console.error(options.format === "text"
202
219
  ? formatCliErrorText(hintedError(errorObject, context.args ?? [], context.isFredSeries), context)
203
220
  : serializeCliError(errorObject, options));
@@ -181,9 +181,18 @@ function joinNameWords(args: readonly string[]): readonly string[] {
181
181
  * refuses `1,234`.
182
182
  * An amount and one currency converts to USD (`toUsdByDefault`). An amount
183
183
  * may carry a K, M or B suffix (`959.81M USD/EUR`). The error sentence
184
- * otherwise.
184
+ * otherwise. Words pasted as one argument (`fx "1234.5 eur/usd "`) are read
185
+ * as typed apart, a slash with spaces around it joining its pair.
185
186
  */
186
- export function parseFxArgs(words: readonly string[], baseCurrency: string): FxArgs | { error: string } {
187
+ export function parseFxArgs(typedWords: readonly string[], baseCurrency: string): FxArgs | { error: string } {
188
+ const words = typedWords.flatMap((word) => word.replace(/\s*\/\s*/g, "/").trim().split(/\s+/)).filter(Boolean)
189
+ // A scale typed apart from its amount (`959.81 M`) stays the amount's.
190
+ .reduce<string[]>((joined, word) => {
191
+ const last = joined.at(-1);
192
+ if (/^[kKmMbB]$/.test(word) && joined.length === 1 && last && parseTypedNumber(last).kind !== "invalid") joined[0] = `${last}${word}`;
193
+ else joined.push(word);
194
+ return joined;
195
+ }, []);
187
196
  const scaled = words.length > 1 ? amountScale(words[0]) : null;
188
197
  const args = joinNameWords(scaled ? [scaled.number, ...words.slice(1)] : words);
189
198
  if (args.length === 1) {
@@ -16,8 +16,8 @@ import { currencyPairCode } from "../utils/currency-pair";
16
16
  import { currencyUnitLabel, resolveCurrencyUnit } from "../utils/currency-units";
17
17
  import { dailyBarDate, getPricePointTimestamp } from "../utils/price-history";
18
18
  import {
19
- isWickFlag, latestTradeIndex, missingVolumeNotice, OPEN_WITHHELD_FLAG, priceHistoryIntegrityNotice, pricePointIntegrityFlags,
20
- pricePointOpenWithheld, pricePointValues, pricePointWickFlags,
19
+ CLOSE_COPIED_FLAG, CLOSE_REBUILT_FLAG, isWickFlag, latestTradeIndex, missingVolumeNotice, OPEN_WITHHELD_FLAG, priceHistoryIntegrityNotice,
20
+ pricePointIntegrityFlags, pricePointOpenWithheld, pricePointValues, pricePointWickFlags,
21
21
  } from "../utils/price-history-integrity";
22
22
  import { formatUtcTime } from "../utils/utc-time";
23
23
  import { maxDrawdown, type DrawdownScale, type MaxDrawdown } from "../utils/max-drawdown";
@@ -315,9 +315,14 @@ export function historyBarFlags(point: PricePoint): string[] {
315
315
  return [
316
316
  ...pricePointIntegrityFlags(point), ...pricePointOpenWithheld(point) ? [OPEN_WITHHELD_FLAG] : [],
317
317
  ...pricePointWickFlags(point), ...rescaleFlags(point),
318
+ // A pair's close its source repeated from the open: rebuilt from the next session's open, or a copy nothing rebuilt.
319
+ ...point.closeRebuilt ? [CLOSE_REBUILT_FLAG] : [], ...point.closeCopied ? [CLOSE_COPIED_FLAG] : [],
318
320
  ];
319
321
  }
320
322
 
323
+ /** Whether a flag code marks a close its source repeated from the open (CLOSE_REBUILT_FLAG, CLOSE_COPIED_FLAG), whose prices stay. */
324
+ const isCopiedCloseFlag = (code: string) => code === CLOSE_REBUILT_FLAG || code === CLOSE_COPIED_FLAG;
325
+
321
326
  /** Days a month's daily bars may leave out at either end or between two of them and still say its range: a week. */
322
327
  const REBUILD_MAX_HOLE_DAYS = 7;
323
328
 
@@ -384,7 +389,8 @@ export function withDailyRebuiltBars(rows: readonly HistoryRow[], daily: readonl
384
389
 
385
390
  /** The codes of a bar left blank for prices that contradict each other: not a break before it, nor a withheld wick or open. */
386
391
  function blankingCodes(row: Pick<HistoryRow, "flag">): string[] {
387
- return flagCodes(row).filter((code) => !BREAK_FLAGS.has(code) && !isWickFlag(code) && !isRescaleFlag(code) && code !== OPEN_WITHHELD_FLAG);
392
+ return flagCodes(row).filter((code) => !BREAK_FLAGS.has(code) && !isWickFlag(code) && !isRescaleFlag(code) && code !== OPEN_WITHHELD_FLAG
393
+ && !isCopiedCloseFlag(code));
388
394
  }
389
395
 
390
396
  /**
@@ -1220,6 +1226,31 @@ export function historyOpenNote(rows: readonly Pick<HistoryRow, "date" | "flag">
1220
1226
  return `${flagged.length} of ${rows.length} bars have an open outside their high and low in the source data${dates}; ${kept}`;
1221
1227
  }
1222
1228
 
1229
+ /**
1230
+ * What a pair's history says of the closes its source repeated from the open
1231
+ * (EUR/USD's 5 Jul 2022 came as open and close 1.043319 on a day that closed
1232
+ * near 1.026): the ones rebuilt from the next session's open (flag close
1233
+ * rebuilt), and the ones nothing could rebuild (the last session of their
1234
+ * week, or a next open over 5% away), which returns leave out
1235
+ * (flag close copied). Three or more of either are counted. Null when no bar
1236
+ * is either.
1237
+ */
1238
+ export function historyCopiedCloseNote(rows: readonly Pick<HistoryRow, "date" | "flag">[]): string | null {
1239
+ const dated = (code: string) => rows.filter((row) => flagCodes(row).includes(code)).map((row) => row.date);
1240
+ const listed = (dates: readonly string[]) => dates.length <= LISTED_GAPS ? listItems(dates) : `${dates.length} bars`;
1241
+ const rebuilt = dated(CLOSE_REBUILT_FLAG);
1242
+ const copied = dated(CLOSE_COPIED_FLAG);
1243
+ const notes = [
1244
+ rebuilt.length > 0 ? `The source repeated the open of ${listed(rebuilt)} as ${rebuilt.length === 1 ? "its" : "their"} close; `
1245
+ + `${rebuilt.length === 1 ? "it closes" : "they close"} at the next session's open (flag ${CLOSE_REBUILT_FLAG})` : null,
1246
+ copied.length > 0 ? `the source repeated the open of ${listed(copied)} as ${copied.length === 1 ? "its" : "their"} close, which `
1247
+ + `no next open in the week rebuilds (none, or one over 5% away): no day's close, `
1248
+ + `left out of returns (flag ${CLOSE_COPIED_FLAG})` : null,
1249
+ ].filter((note): note is string => note != null);
1250
+ const text = notes.join("; ");
1251
+ return text ? text.charAt(0).toUpperCase() + text.slice(1) : null;
1252
+ }
1253
+
1223
1254
  /**
1224
1255
  * "The low of 2021-11-29 is under half its open and close, too far to have
1225
1256
  * traded; left blank and out of ranges", or null when no bar has such a wick
package/src/cli/index.ts CHANGED
@@ -226,7 +226,7 @@ export function createCoreCliCommands(
226
226
  { flags: "--scale <n>", description: "Text scale from 0.5 to 4 (default 1)" },
227
227
  { flags: "--watermark <label>", description: "Label drawn in the pane title bar" },
228
228
  { flags: "--no-status", description: "Leave out the dated status line (as-of, delay, market hours) drawn in the pane footer" },
229
- { flags: "--strict", description: `Exit ${CLI_EXIT_CODES.unusableShot} when the pane is empty, shows an error, is still loading or is access-gated; the PNG and the Reason line are still written` },
229
+ { flags: "--strict", description: `Exit ${CLI_EXIT_CODES.unusableShot} when the pane is empty, shows an error, is still loading, is access-gated or draws a column blank in every row; the PNG and the Reason line, which names what it saw, are still written` },
230
230
  { flags: "--<option> <value>", description: "A function setting; gloom catalog <function> lists them" },
231
231
  EXCHANGE_OPTION,
232
232
  ],
@@ -15,6 +15,7 @@ import {
15
15
  type ListingVenue,
16
16
  } from "../tickers/listing-venues";
17
17
  import { findUsListingOfCompany, type UsListing } from "../tickers/us-listing";
18
+ import { listingDepositaryPair } from "../market-data/depositary-pair";
18
19
  import {
19
20
  findListingOfCompanyName, isCompanyNameInput, marksAnotherListing, readTerminalCodeArg, serviceMarkedListing, serviceMarkedOtherListing, type CompanyNameListing,
20
21
  } from "../tickers/company-name-listing";
@@ -33,6 +34,7 @@ import {
33
34
  isSharedExchangeCode,
34
35
  isUsEquityExchange,
35
36
  isUsListingExchange,
37
+ isUsOtcVenue,
36
38
  usShareClassSpellings,
37
39
  parsePublicTickerKey,
38
40
  publicTickerKey,
@@ -614,21 +616,51 @@ export async function usLineOfListing(
614
616
  }
615
617
 
616
618
  /**
617
- * The company's own listing on a US exchange: its line under the same symbol
618
- * (SAN:MCE's New York receipt), else the one search finds by its name
619
- * (Sanofi's SNY for SAN:EPA, Toyota's TM for 7203:JPX). Funds and contracts
620
- * that carry its name are not its listing. Null for a listing in the US or
621
- * with no venue, and when the company has no US line search knows.
619
+ * The US line a listing abroad's own quote names as its depositary receipt
620
+ * (0700:HKEX's TCEHY, 9988:HKEX's BABA), on the venue the receipt's quote is
621
+ * from: a US exchange, or over the counter (canonically OTC). Null when the
622
+ * quote names none, the listing is the receipt, or the receipt trades
623
+ * outside the US (Tencent's HTCD on SGX).
624
+ */
625
+ async function depositaryReceiptLine(quote: Quote | null, deps: Pick<ListingDeps, "dataProvider">): Promise<UsListing | null> {
626
+ const pair = listingDepositaryPair({ quote });
627
+ if (!pair || quote?.isDepositaryReceipt === true) return null;
628
+ const receipt = await deps.dataProvider.getQuote(pair.receipt, "").catch(logFailure("cli.listing-arg", "Read a depositary receipt's quote failed", null));
629
+ const venue = canonicalExchange(receipt?.listingExchangeName || receipt?.exchangeName || "");
630
+ const exchange = isUsListingExchange(venue) ? venue : isUsOtcVenue(venue) ? "OTC" : null;
631
+ return receipt && exchange ? { symbol: pair.receipt, exchange, name: receipt.name ?? quote?.name ?? pair.receipt } : null;
632
+ }
633
+
634
+ /** A company's US line as a function abroad offers it: `line` when its data covers it; `otc` the line over the counter it does not. */
635
+ interface UsLineOffer {
636
+ line: UsListing | null;
637
+ otc: UsListing | null;
638
+ }
639
+
640
+ /**
641
+ * The company's own listing in the US: its line under the same symbol
642
+ * (SAN:MCE's New York receipt), else the receipt its quote names (Tencent's
643
+ * TCEHY for 0700:HKEX), else the one search finds by its name (Sanofi's SNY
644
+ * for SAN:EPA, Toyota's TM for 7203:JPX). Funds and contracts that carry its
645
+ * name are not its listing. A line over the counter is offered only with
646
+ * `otc`, for data that covers one (FINRA's short interest); otherwise it is
647
+ * named apart. Nothing for a listing in the US or with no venue, and when
648
+ * the company has no US line search knows.
622
649
  */
623
650
  async function usListingOfCompany(
624
651
  listing: Pick<ListingArg, "symbol" | "exchange">,
625
652
  company: string | null | undefined,
626
653
  deps: ListingDeps,
627
- ): Promise<UsListing | null> {
654
+ quote: Quote | null,
655
+ otc: boolean,
656
+ ): Promise<UsLineOffer> {
628
657
  const sameSymbol = await usLineOfListing(listing, company, deps);
629
- if (sameSymbol) return { ...sameSymbol, symbol: listing.symbol };
630
- if (!listing.exchange || isUsListingExchange(listing.exchange)) return null;
631
- return findUsListingOfCompany(deps.dataProvider, company);
658
+ if (sameSymbol) return { line: { ...sameSymbol, symbol: listing.symbol }, otc: null };
659
+ if (!listing.exchange || isUsListingExchange(listing.exchange)) return { line: null, otc: null };
660
+ const receipt = await depositaryReceiptLine(quote, deps);
661
+ if (receipt && (otc || receipt.exchange !== "OTC")) return { line: receipt, otc: null };
662
+ const searched = await findUsListingOfCompany(deps.dataProvider, company, { otc });
663
+ return { line: searched, otc: searched ? null : receipt };
632
664
  }
633
665
 
634
666
  /**
@@ -638,13 +670,17 @@ async function usListingOfCompany(
638
670
  * symbol: "Time and sales covers US listings only, and SAN:EPA is Sanofi on
639
671
  * Euronext Paris (EPA).", then the company's US listing with the command that
640
672
  * asks for it ("Sanofi's US listing: SNY (try: gloom fn TAS SNY)"), or that
641
- * none was found.
673
+ * none was found. With `otc` (usListingsOtc) a line over the counter is
674
+ * offered too, said to be one ("Tencent Holdings's US listing: TCEHY, over
675
+ * the counter"); without it such a line is named as one the data does not
676
+ * cover, never offered.
642
677
  */
643
678
  export async function usListingsOnlyMessage(
644
679
  what: string,
645
680
  listing: Pick<CliListing, "symbol" | "exchange" | "key" | "request" | "saved">,
646
681
  deps: ListingDeps,
647
682
  retry: (key: string) => string | null,
683
+ { otc = false }: { otc?: boolean } = {},
648
684
  ): Promise<{ message: string; details: string }> {
649
685
  const quote = await loadListingQuote(deps.dataProvider, listing);
650
686
  const company = listingIdentity(listing, quote).name;
@@ -658,14 +694,16 @@ export async function usListingsOnlyMessage(
658
694
  }
659
695
  const where = venue ? exchangeLabel(venue) : "";
660
696
  const named = company ? `${shortCompanyName(company)}${where ? ` on ${where}` : ""}` : where || "not a US listing";
661
- const us = await usListingOfCompany(local, company, deps);
697
+ const { line: us, otc: outside } = await usListingOfCompany(local, company, deps, quote, otc);
662
698
  const owner = company ? shortCompanyName(company) : listing.key;
663
699
  const command = us ? retry(us.symbol) : null;
664
700
  return {
665
701
  message: `${what} covers US listings only, and ${listing.key} is ${named}.`,
666
702
  details: us
667
- ? `${owner}'s US listing: ${us.symbol}${command ? ` (try: ${command})` : ""}`
668
- : `No US listing of ${owner} was found.`,
703
+ ? `${owner}'s US listing: ${us.symbol}${us.exchange === "OTC" || isUsOtcVenue(us.exchange) ? ", over the counter" : ""}${command ? ` (try: ${command})` : ""}`
704
+ : outside
705
+ ? `${owner} has no US exchange listing; its US line ${outside.symbol} trades over the counter, which this data does not cover.`
706
+ : `No US listing of ${owner} was found.`,
669
707
  };
670
708
  }
671
709
 
@@ -50,6 +50,7 @@ import { formatCompact } from "../../utils/format";
50
50
  import { deriveHeadlessFreshness, formatFreshnessLine, staleRowsText, withSavedCopy, type ReportFreshness } from "./freshness";
51
51
  import { DATA_SERVICE_UNREACHABLE_MESSAGE } from "../../utils/network-failure";
52
52
  import { accessGateStatus, errorsAccessGate, isProLock, reportGateText } from "./access-gate";
53
+ import { readableStatus } from "../../utils/reason-codes";
53
54
  import { noArgumentMessage } from "./capabilities";
54
55
  import { lockedHeadlessReport } from "./lock-note";
55
56
  import { resumeStateKey } from "../../plugins/registry/plugin-state";
@@ -368,7 +369,7 @@ export function serializeHeadlessPaneResult(
368
369
  result: HeadlessPaneResult,
369
370
  ): Record<string, unknown> {
370
371
  const common = {
371
- ...(result.errors ? { errors: result.errors } : {}),
372
+ ...(result.errors ? { errors: result.errors.map((error) => isProLock(error) ? error : readableStatus(error)) } : {}),
372
373
  ...(result.notes?.length ? { notes: result.notes } : {}),
373
374
  ...(result.warnings?.length ? { warnings: result.warnings } : {}),
374
375
  ...(result.metadata ? { metadata: result.metadata } : {}),
@@ -757,7 +758,8 @@ function incompleteDetail(
757
758
  /** What Gloom Pro would unlock apart from what failed: a lock is not an error, though it stays in `errors` for JSON. */
758
759
  function splitErrors(result: HeadlessPaneResult): { locked: string[]; failed: string[] } {
759
760
  const errors = result.errors ?? [];
760
- return { locked: errors.filter(isProLock), failed: errors.filter((error) => !isProLock(error)) };
761
+ // A failure reads in words: "AAPL: the source did not answer", not its reason code.
762
+ return { locked: errors.filter(isProLock), failed: errors.filter((error) => !isProLock(error)).map(readableStatus) };
761
763
  }
762
764
 
763
765
  /**
@@ -631,6 +631,7 @@ async function capturePaneScreenshot(args: string[], ctx: CliCommandContext, onS
631
631
  if (data.unreadRows?.length) {
632
632
  stats.push(["Not loaded", cliStyles.warning(data.unreadRows.map((symbol) => data.unreadReasons?.[symbol] ? `${symbol} (${data.unreadReasons[symbol]})` : symbol).join(", "))]);
633
633
  }
634
+ if (data.blankColumns?.length) stats.push(["Blank columns", cliStyles.warning(data.blankColumns.join(", "))]);
634
635
  if (data.render.emptyStateMarkers.length > 0) stats.push(["Empty states", data.render.emptyStateMarkers.join(", ")]);
635
636
  if (data.render.missingExpectedText.length > 0) stats.push(["Missing text", data.render.missingExpectedText.join(", ")]);
636
637
  return [`Saved ${displayPath(data.outputPath)}`, renderStats(stats)].join("\n");
@@ -316,7 +316,8 @@ export async function applyListingArgument(
316
316
  const abroad = usOnly ? listings.filter((listing) => listingAbroadVenue(listing.key) != null) : [];
317
317
  if (usOnly && abroad.length > 0) {
318
318
  const answers = await Promise.all(abroad.map(async (listing) => {
319
- const answer = await usListingsOnlyMessage(usOnly, listing, context, (key) => `gloom ${command} ${token} ${key}`);
319
+ const answer = await usListingsOnlyMessage(usOnly, listing, context, (key) => `gloom ${command} ${token} ${key}`,
320
+ { otc: headless?.usListingsOtc === true });
320
321
  const hint = headless?.usListingsOnlyHint?.(listing.key);
321
322
  return hint ? { ...answer, details: `${answer.details}\n${hint}` } : answer;
322
323
  }));
@@ -2,7 +2,7 @@ import { SHOT_REQUEST_REFUSED, SHOT_UNAVAILABLE } from "../../api-client/errors"
2
2
  import { CHART_COMPOSER_PANE_ID } from "../../types/config";
3
3
  import { isRecord } from "../../utils/guards";
4
4
  import { parsePublicTickerKey } from "../../utils/exchanges";
5
- import type { DesktopPaneShotPayload, DesktopPaneShotRenderResult } from "../desktop-pane-shot";
5
+ import type { DesktopPaneShotPayload, DesktopPaneShotRenderResult, DesktopPaneShotRenderedRow } from "../desktop-pane-shot";
6
6
  import type { ResolvedPaneFunction } from "./resolver";
7
7
  import type { RemoteUiNodeSnapshot } from "../../remote/types";
8
8
  import { accessGateSentence, accessGateStatus } from "./access-gate";
@@ -60,6 +60,7 @@ export function shotShowsText(visibleText: string, value: string): boolean {
60
60
 
61
61
  export function isPaneScreenshotUsable(signals: PaneScreenshotReadinessSignals): boolean {
62
62
  return !signals.refused
63
+ && !signals.blankColumns?.length
63
64
  && (signals.interactive || ((signals.rowCount > 0 || signals.contentShown === true) && !signals.emptyStateDetected))
64
65
  && !signals.loadingStateDetected
65
66
  && !signals.errorStateDetected
@@ -168,6 +169,8 @@ export function assessPaneScreenshot(
168
169
  && shotShowsContent(render);
169
170
  // The capture's refusal of a request (chat, a team's) drawn where the pane's content goes is not the pane.
170
171
  const refused = shotShowsRefusal(render);
172
+ // A column with no value in any row is data the pane lost, as Market Movers' VOL and V/AVG did before the open.
173
+ const blankColumns = interactive ? [] : shotBlankColumns(render.rows);
171
174
  const empty = render.loadingStateDetected
172
175
  || render.errorStateDetected
173
176
  || refused
@@ -185,11 +188,12 @@ export function assessPaneScreenshot(
185
188
  semanticMismatch,
186
189
  requiresStructuredDataEvidence: requiresStructuredDataEvidence(resolved),
187
190
  hasStructuredDataEvidence: dataEvidence !== null,
191
+ blankColumns,
188
192
  });
189
193
  const unusableReason = usable
190
194
  ? null
191
195
  : refused ? refusedShotReason(resolved)
192
- : shotUnusableReasonFor(resolved, payload, render, unavailableSymbols, semanticMismatch);
196
+ : shotUnusableReasonFor(resolved, payload, render, unavailableSymbols, semanticMismatch, blankColumns);
193
197
  const tableRows = shotTableRows(resolved, render);
194
198
  const notices = [
195
199
  ...renderedReportNotices(render.semanticUi ?? []).notices,
@@ -217,6 +221,7 @@ export function assessPaneScreenshot(
217
221
  usable,
218
222
  unusableReason,
219
223
  ...(refused ? { refused: true as const } : {}),
224
+ ...(blankColumns.length > 0 ? { blankColumns } : {}),
220
225
  dataEvidence,
221
226
  ...(notices.length > 0 ? { notices } : {}),
222
227
  ...(tableRows ? { tableRows } : {}),
@@ -288,6 +293,66 @@ function requiresStructuredDataEvidence(resolved: ResolvedPaneFunction): boolean
288
293
 
289
294
  const PLACEHOLDER_VALUE = /^(?:[-\u2013\u2014]+|n\/?a)?$/i;
290
295
 
296
+ /**
297
+ * Rows a table must draw before a column that is blank in all of them reads
298
+ * as a column the pane lost, rather than a short list's gaps.
299
+ */
300
+ const BLANK_COLUMN_MIN_ROWS = 3;
301
+
302
+ /**
303
+ * The columns of a capture's tables whose every drawn row shows a placeholder
304
+ * for a missing value ("—", "n/a"), by their headers, as Market Movers' VOL
305
+ * and V/AVG did before the open. A column some rows leave empty is a sparse
306
+ * marker (an event column), not a blank one, and neither is a column the pane
307
+ * says can be blank (`mayBeBlank`: a value that comes after an event, such as
308
+ * an upcoming report's move); section headers and tables of fewer than
309
+ * BLANK_COLUMN_MIN_ROWS rows are not read.
310
+ */
311
+ function shotBlankColumns(rows: readonly Pick<DesktopPaneShotRenderedRow, "tableIndex" | "cells" | "section">[]): string[] {
312
+ const tables = new Map<number, Array<Pick<DesktopPaneShotRenderedRow, "cells">>>();
313
+ for (const row of rows) {
314
+ // A row drawn as one cell is a section header or a prose entry, not a row of the table's columns.
315
+ if (row.section || row.cells.length < 2) continue;
316
+ tables.set(row.tableIndex, [...tables.get(row.tableIndex) ?? [], row]);
317
+ }
318
+ const blank: string[] = [];
319
+ for (const tableRows of tables.values()) {
320
+ if (tableRows.length < BLANK_COLUMN_MIN_ROWS) continue;
321
+ const columns = new Map<string, { label: string; placeholders: number; filled: boolean }>();
322
+ for (const row of tableRows) {
323
+ for (const cell of row.cells) {
324
+ const key = cell.columnId ?? cell.columnLabel;
325
+ const column = columns.get(key) ?? { label: cell.columnLabel, placeholders: 0, filled: false };
326
+ if (PLACEHOLDER_VALUE.test(cell.text.trim()) && !cell.mayBeBlank) column.placeholders += 1;
327
+ else column.filled = true;
328
+ columns.set(key, column);
329
+ }
330
+ }
331
+ for (const { label, placeholders, filled } of columns.values()) {
332
+ if (!filled && placeholders === tableRows.length && !blank.includes(label)) blank.push(label);
333
+ }
334
+ }
335
+ return blank;
336
+ }
337
+
338
+ /** "The VOL and V/AVG columns are blank in every row." */
339
+ function blankColumnsSentence(columns: readonly string[]): string {
340
+ const named = columns.length === 1 ? columns[0]!
341
+ : `${columns.slice(0, -1).join(", ")} and ${columns[columns.length - 1]}`;
342
+ return `The ${named} column${columns.length === 1 ? " is" : "s are"} blank in every row.`;
343
+ }
344
+
345
+ /**
346
+ * What the pane's states said, quoted after the sentence that names the
347
+ * state: ` It reads "Market movers temporarily unavailable. Try again in a
348
+ * moment."` Empty when the capture read no words for it.
349
+ */
350
+ function stateSaid(lines: readonly string[] | undefined): string {
351
+ if (!lines?.length) return "";
352
+ const quoted = lines.map((line) => `"${line}"`).join(" and ");
353
+ return ` It reads ${quoted}${/[.!?]$/.test(lines[lines.length - 1]!) ? "" : "."}`;
354
+ }
355
+
291
356
  /**
292
357
  * What a live pane shows, counted: its table's rows; else the values its
293
358
  * chart plotted, as a chart pane counts them (RETURN's chart view, whose
@@ -360,9 +425,10 @@ export function surfaceNotDrawnMismatches(render: Pick<DesktopPaneShotRenderResu
360
425
  export function shotUnusableReasonFor(
361
426
  resolved: ResolvedPaneFunction,
362
427
  payload: DesktopPaneShotPayload,
363
- render: Pick<DesktopPaneShotRenderResult, "loadingStateDetected" | "errorStateDetected" | "emptyStateDetected" | "accessGate" | "surfaces">,
428
+ render: Pick<DesktopPaneShotRenderResult, "loadingStateDetected" | "errorStateDetected" | "emptyStateDetected" | "accessGate" | "surfaces" | "stateText" | "errorStateMarkers" | "emptyStateMarkers">,
364
429
  unavailableSymbols: string[],
365
430
  semanticMismatch: boolean,
431
+ blankColumns: readonly string[] = [],
366
432
  ): string {
367
433
  if (resolved.capability.id === "intraday-price-chart") {
368
434
  const intraday = payload.intradayHistories[0];
@@ -375,14 +441,16 @@ export function shotUnusableReasonFor(
375
441
  }
376
442
  if (render.loadingStateDetected) return "The pane was still loading when the screenshot was captured.";
377
443
  if (render.accessGate) return accessGateSentence(render.accessGate);
378
- if (render.errorStateDetected) return "The pane rendered an error state.";
379
- if (render.emptyStateDetected) return "The pane rendered an empty state.";
444
+ // The first sentence stays as scripts match it; the state's own words follow it.
445
+ if (render.errorStateDetected) return `The pane rendered an error state.${stateSaid(render.stateText?.error ?? render.errorStateMarkers)}`;
446
+ if (render.emptyStateDetected) return `The pane rendered an empty state.${stateSaid(render.stateText?.empty ?? render.emptyStateMarkers)}`;
380
447
  const surfaceGap = surfaceNotDrawnMismatches(render)[0];
381
448
  if (surfaceGap) return `${surfaceGap[0]!.toUpperCase()}${surfaceGap.slice(1)}.`;
382
449
  if (unavailableSymbols.length > 0) return `Data is unavailable for ${unavailableSymbols.join(", ")}.`;
383
450
  const ratioGap = financialRatioShotGap(resolved, payload);
384
451
  if (ratioGap) return ratioGap;
385
452
  if (semanticMismatch) return "The rendered content did not match the requested capability.";
453
+ if (blankColumns.length > 0) return blankColumnsSentence(blankColumns);
386
454
  return "The pane did not produce verifiable screenshot evidence.";
387
455
  }
388
456
 
@@ -125,6 +125,8 @@ export interface PaneScreenshotReadinessSignals {
125
125
  semanticMismatch: boolean;
126
126
  requiresStructuredDataEvidence: boolean;
127
127
  hasStructuredDataEvidence: boolean;
128
+ /** Columns blank in every row the capture drew (`shotBlankColumns`). */
129
+ blankColumns?: readonly string[];
128
130
  }
129
131
 
130
132
  export interface PaneScreenshotResult {
@@ -152,6 +154,8 @@ export interface PaneScreenshotResult {
152
154
  unusableReason: string | null;
153
155
  /** The pane drew the capture's refusal of the requests it reads its content with (CHAT's channels). */
154
156
  refused?: true;
157
+ /** Columns blank in every row the capture drew, by their headers: data the pane lost (`shotBlankColumns`). */
158
+ blankColumns?: string[];
155
159
  dataEvidence: PaneScreenshotDataEvidence | null;
156
160
  /** What the pane says its view leaves out, such as OMON's "21 of 145 strikes". */
157
161
  notices?: string[];
@@ -2,7 +2,7 @@ import { allocateCompositePanelHeights } from "./scene";
2
2
 
3
3
  /**
4
4
  * How a chart pane lays its chart out, as the user left it: the panels'
5
- * heights, a panel given the whole plot, the drawing tool bar hidden and the
5
+ * heights, a panel given the whole plot, the drawing tool bar kept open and the
6
6
  * legend collapsed. Kept in the pane's settings beside its drawings, so it
7
7
  * outlives a restart; a chart outside a pane keeps it while it is mounted.
8
8
  */
@@ -16,8 +16,11 @@ export interface ChartLayoutPrefs {
16
16
  panelWeights?: Readonly<Record<string, number>>;
17
17
  /** The panel given the whole plot while the others wait. */
18
18
  maximizedPanelId?: string;
19
- /** The drawing tool bar is folded to the one button that brings it back. */
20
- toolbarHidden?: boolean;
19
+ /**
20
+ * The drawing tool bar is kept open. It is folded to the tool in hand
21
+ * otherwise, and opens under the pointer.
22
+ */
23
+ toolbarPinned?: boolean;
21
24
  /** The legend shows its first series and how many more it holds. */
22
25
  legendCollapsed?: boolean;
23
26
  }
@@ -35,7 +38,7 @@ export function parseChartLayoutPrefs(value: unknown): ChartLayoutPrefs {
35
38
  if (weights.length > 0) layout.panelWeights = Object.fromEntries(weights);
36
39
  }
37
40
  if (typeof source.maximizedPanelId === "string" && source.maximizedPanelId) layout.maximizedPanelId = source.maximizedPanelId;
38
- if (source.toolbarHidden === true) layout.toolbarHidden = true;
41
+ if (source.toolbarPinned === true) layout.toolbarPinned = true;
39
42
  if (source.legendCollapsed === true) layout.legendCollapsed = true;
40
43
  return Object.keys(layout).length > 0 ? layout : NO_CHART_LAYOUT;
41
44
  }