gloomberb 0.16.1 → 0.16.3

package/src/cli/pane-functions/headless.ts

@@ -1,4 +1,5 @@
 import { getSharedRegistry } from "../../plugins/registry";
+import { findCachedPortfolioAccount } from "../../plugins/builtin/portfolio-list/cached-account";
 import { parsePublicTickerKey } from "../../utils/exchanges";
 import { apiClient } from "../../api-client";
 import type { MarketContext } from "../types";
@@ -19,11 +20,23 @@ import type {
 } from "../../types/plugin";
 import { cliStyles, renderSection, renderStats, renderTable } from "../../utils/cli-output";
 import { humanizeCliKey } from "../result";
+import {
+  exportEntriesTable,
+  exportNumber,
+  exportRowsTable,
+  float32Shortest,
+  reportFooterLines,
+  type CliReportTable,
+  type CliReportTables,
+} from "../report-tables";
+import { labelWithUnit } from "../../utils/display-number";
 import { observationDate } from "../../time-series/price-comparison";
 import type { ResolvedSeries } from "../../time-series/types";
 import type { PaneFunctionReport } from "./report";
 import type { ResolvedPaneFunction } from "./resolver";
 import { isRecord } from "../../utils/guards";
+import { formatUtcTime } from "../../utils/utc-time";
+import { deriveHeadlessFreshness, formatFreshnessLine, type ReportFreshness } from "./freshness";
 
 interface SerializableHeadlessColumn {
   key: string;
@@ -149,7 +162,9 @@ async function loadHeadlessPaneModel(
  */
 export async function loadResolvedHeadlessPaneModel(
   resolved: ResolvedPaneFunction,
-  context: Pick<MarketContext, "config" | "store" | "refresh"> & { dataProvider: HeadlessPaneContext["marketData"] },
+  context: Pick<MarketContext, "config" | "store" | "refresh"> & Partial<Pick<MarketContext, "persistence">> & {
+    dataProvider: HeadlessPaneContext["marketData"];
+  },
   rawArgument: string,
   signal: AbortSignal = new AbortController().signal,
 ): Promise<LoadedHeadlessPaneModel> {
@@ -168,7 +183,7 @@ export async function loadResolvedHeadlessPaneModel(
       const portfolio = context.config.portfolios.find(row => row.id === id);
       if (!portfolio) return null;
       const tickers = (await context.store.loadAllTickers()).filter(row => row.metadata.portfolios.includes(id));
-      return { portfolio, tickers };
+      return { portfolio, tickers, account: findCachedPortfolioAccount(context.config, portfolio, context.persistence?.resources) };
     },
     async resolveWatchlist(id) {
       if (!context.config.watchlists.some(row => row.id === id)) return null;
@@ -244,6 +259,7 @@ export function serializeHeadlessPaneResult(
 ): Record<string, unknown> {
   const common = {
     ...(result.errors ? { errors: result.errors } : {}),
+    ...(result.notes?.length ? { notes: result.notes } : {}),
     ...(result.metadata ? { metadata: result.metadata } : {}),
   };
   switch (definition.shape) {
@@ -310,36 +326,43 @@ function displayNumber(value: number): string {
   return String(float32Shortest(value) ?? Number(value.toPrecision(12)));
 }
 
-/**
- * Some feeds store prices as float32, so 338.93 arrives as 338.929992676. A value
- * that is exactly a float32 prints as the shortest decimal that rounds back to it,
- * which leaves genuine doubles (never exactly float32 unless short) untouched.
- */
-function float32Shortest(value: number): number | null {
-  if (Math.fround(value) !== value) return null;
-  for (let digits = 1; digits <= 9; digits += 1) {
-    const candidate = Number(value.toPrecision(digits));
-    if (Math.fround(candidate) === value) return candidate;
-  }
-  return null;
-}
-
 function displayTime(time: number): string {
   if (!Number.isFinite(time)) return "-";
-  const iso = new Date(time).toISOString();
-  return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : `${iso.slice(0, 16).replace("T", " ")} UTC`;
+  return formatUtcTime(new Date(time));
 }
 
 const CALENDAR_RESOLUTIONS = new Set(["1d", "1wk", "1mo"]);
 
-/** Session bars print the trading date the chart and comparison notice use, not the bar's open instant. */
-function seriesPointDate(series: HeadlessSeries, date: HeadlessSeries["points"][number]["date"]): string {
-  const time = date instanceof Date ? date.getTime() : typeof date === "number" ? date : Date.parse(date);
-  if (!Number.isFinite(time)) return typeof date === "string" ? date : "-";
+type SeriesPointDate = HeadlessSeries["points"][number]["date"];
+
+function seriesPointTime(date: SeriesPointDate): number {
+  return date instanceof Date ? date.getTime() : typeof date === "number" ? date : Date.parse(date);
+}
+
+function isDateOnly(date: SeriesPointDate): boolean {
+  return typeof date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(date);
+}
+
+/** Session bars are dated by the trading date the chart and comparison notice use, not the bar's open instant. */
+function calendarSeries(series: HeadlessSeries): (HeadlessSeries & Partial<Pick<ResolvedSeries, "historyResolution" | "timeBasis">>) | null {
   const resolved = series as HeadlessSeries & Partial<Pick<ResolvedSeries, "historyResolution" | "timeBasis">>;
-  return resolved.historyResolution && CALENDAR_RESOLUTIONS.has(resolved.historyResolution)
-    ? observationDate(time, resolved)
-    : displayTime(time);
+  return resolved.historyResolution && CALENDAR_RESOLUTIONS.has(resolved.historyResolution) ? resolved : null;
+}
+
+function seriesPointDate(series: HeadlessSeries, date: SeriesPointDate): string {
+  const time = seriesPointTime(date);
+  if (!Number.isFinite(time)) return typeof date === "string" ? date : "-";
+  const calendar = calendarSeries(series);
+  return calendar ? observationDate(time, calendar) : formatUtcTime({ time, dateOnly: isDateOnly(date) });
+}
+
+/** The same date for a spreadsheet: the trading date, the calendar date, or the ISO instant. */
+function seriesPointExportDate(series: HeadlessSeries, date: SeriesPointDate): string {
+  const time = seriesPointTime(date);
+  if (!Number.isFinite(time)) return typeof date === "string" ? date : "";
+  const calendar = calendarSeries(series);
+  if (calendar) return observationDate(time, calendar);
+  return isDateOnly(date) ? date as string : new Date(time).toISOString().replace(".000Z", "Z");
 }
 
 function seriesValue(series: HeadlessSeries, value: number | null): string {
@@ -372,6 +395,10 @@ function renderEntries(entries: HeadlessPaneEntry[]): string {
   return renderStats(entries.map((entry) => [entry.label, entry.formatted ?? displayValue(entry.value)]));
 }
 
+function statisticsEntries(stats: NonNullable<HeadlessSeriesResult["stats"]>): HeadlessPaneEntry[] {
+  return Array.isArray(stats) ? stats : Object.entries(stats).map(([label, value]) => ({ label, value }));
+}
+
 function renderBundle(
   definition: HeadlessPaneDefinition,
   result: HeadlessBundleResult,
@@ -407,31 +434,150 @@ function renderSeries(result: HeadlessSeriesResult): string[] {
   ];
   const lines = [renderRows(rows, columns, undefined)];
   if (result.stats) {
-    const entries = Array.isArray(result.stats)
-      ? result.stats
-      : Object.entries(result.stats).map(([label, value]) => ({ label, value }));
-    lines.push("", renderSection("Statistics"), renderEntries(entries));
+    lines.push("", renderSection("Statistics"), renderEntries(statisticsEntries(result.stats)));
   }
   return lines;
 }
 
-function reportTitle(definition: HeadlessPaneDefinition, args: HeadlessPaneLoadArgs, fallback: string): string {
-  if (typeof definition.describe === "function") return definition.describe(args);
+/** The headers the text table prints. */
+function displayedColumns(columns: HeadlessPaneColumn[]): HeadlessPaneColumn[] {
+  return columns.map((column) => ({ ...column, header: humanizeCliKey(column.header) }));
+}
+
+const SERIES_FIELDS = ["value", "open", "high", "low", "close", "volume"] as const;
+
+/** Every point of a series: its date (the trading date for session bars) and its values, in the series' unit. */
+function seriesTable(series: HeadlessSeries): CliReportTable {
+  const fields = SERIES_FIELDS.filter((field) => series.points.some((point) => point[field] != null));
+  const unit = series.unit?.trim() ?? "";
+  const dates = series.points.map((point) => seriesPointExportDate(series, point.date));
+  const header = (field: (typeof SERIES_FIELDS)[number]) => {
+    const name = `${field[0]!.toUpperCase()}${field.slice(1)}`;
+    return field === "volume" ? name : labelWithUnit(name, unit);
+  };
+  return {
+    title: series.label,
+    columns: [dates.every((date) => date.length <= 10) ? "Date" : "Time", ...fields.map(header)],
+    rows: series.points.map((point, index) => [
+      dates[index]!,
+      ...fields.map((field) => {
+        const value = point[field];
+        return typeof value === "number" && Number.isFinite(value) ? exportNumber(value) : "";
+      }),
+    ]),
+  };
+}
+
+/** What a report leaves out, for the closing `# incomplete` line. */
+function incompleteDetail(
+  result: HeadlessPaneResult,
+  status: { complete: boolean; unavailableSymbols: string[] },
+): boolean | string {
+  if (status.complete) return false;
+  const requested = result.metadata?.requested;
+  const available = result.metadata?.available;
+  if (typeof requested === "number" && typeof available === "number" && available < requested) {
+    return `${available} of ${requested} available`;
+  }
+  return status.unavailableSymbols.length > 0 ? `no data for ${status.unavailableSymbols.join(", ")}` : true;
+}
+
+function textNotices(result: HeadlessPaneResult): string[] {
+  const notices = result.metadata?.notices;
+  if (!Array.isArray(notices)) return [];
+  return [...new Set(notices.filter((notice): notice is string => typeof notice === "string" && notice.trim().length > 0))];
+}
+
+/**
+ * The tables of a headless report for `--csv` and `--ndjson`, with the text
+ * view's columns: a rows or snapshot report is one table, a bundle one per
+ * section (key/value sections as `Metric,Value`), a series report one per
+ * series with every point, then its statistics. The footer carries the text
+ * view's closing line, notices, notes and errors.
+ */
+export function headlessReportTables(
+  definition: HeadlessPaneDefinition,
+  result: HeadlessPaneResult,
+  args: HeadlessPaneLoadArgs,
+  fallbackTitle: string,
+  freshness: ReportFreshness,
+  status: { complete: boolean; unavailableSymbols: string[] },
+): CliReportTables {
+  const title = reportTitle(definition, args, result, fallbackTitle);
+  let tables: CliReportTable[];
+  switch (definition.shape) {
+    case "rows": {
+      const rowsResult = result as HeadlessPaneResult & { rows: HeadlessPaneRow[]; columns?: HeadlessPaneColumn[] };
+      const columns = displayedColumns(columnsFor(rowsResult.rows, rowsResult.columns, definition.columns));
+      tables = [exportRowsTable(title, columns, rowsResult.rows)];
+      break;
+    }
+    case "bundle":
+      tables = (result as HeadlessBundleResult).sections.map((section) => (
+        "rows" in section && section.rows
+          ? exportRowsTable(section.title, displayedColumns(columnsFor(section.rows, section.columns, definition.columns)), section.rows)
+          : exportEntriesTable(section.title, section.entries)
+      ));
+      break;
+    case "series": {
+      const seriesResult = result as HeadlessSeriesResult;
+      tables = seriesResult.series.map(seriesTable);
+      if (seriesResult.stats) tables.push(exportEntriesTable("Statistics", statisticsEntries(seriesResult.stats)));
+      break;
+    }
+    case "snapshot": {
+      const snapshot = result as HeadlessSnapshotResult;
+      tables = [exportRowsTable(title, displayedColumns(columnsFor(snapshot.items, undefined, definition.columns)), snapshot.items)];
+      break;
+    }
+    default: {
+      const _exhaustive: never = definition.shape;
+      return _exhaustive;
+    }
+  }
+  return {
+    tables,
+    footer: reportFooterLines({
+      freshness,
+      incomplete: incompleteDetail(result, status),
+      errors: result.errors,
+      notes: [...textNotices(result), ...(result.notes ?? [])],
+    }),
+  };
+}
+
+function reportTitle(
+  definition: HeadlessPaneDefinition,
+  args: HeadlessPaneLoadArgs,
+  result: HeadlessPaneResult,
+  fallback: string,
+): string {
+  if (typeof definition.describe === "function") return definition.describe(args, result);
   return definition.describe ?? fallback;
 }
 
+/** One message stays on the label's line; several each get a line of their own, so none runs into the next. */
+function renderMessages(label: string, messages: readonly string[]): string[] {
+  return messages.length === 1
+    ? [cliStyles.warning(`${label}: ${messages[0]}`)]
+    : [cliStyles.warning(`${label}:`), ...messages.map((message) => `  ${message}`)];
+}
+
+/**
+ * The text form of every headless report. It always ends with the source,
+ * as-of and status line, so no pane can leave it out; a pane can only make it
+ * more accurate through its `freshness` declaration.
+ */
 export function renderHeadlessPaneText(
   definition: HeadlessPaneDefinition,
   result: HeadlessPaneResult,
   args: HeadlessPaneLoadArgs,
   fallbackTitle: string,
+  freshness: ReportFreshness = deriveHeadlessFreshness(definition, result),
 ): string {
-  const lines = [cliStyles.bold(reportTitle(definition, args, fallbackTitle)), ""];
-  const notices = result.metadata?.notices;
-  if (Array.isArray(notices)) {
-    const textNotices = [...new Set(notices.filter((notice): notice is string => typeof notice === "string" && notice.trim().length > 0))];
-    if (textNotices.length) lines.push(...textNotices, "");
-  }
+  const lines = [cliStyles.bold(reportTitle(definition, args, result, fallbackTitle)), ""];
+  const notices = textNotices(result);
+  if (notices.length) lines.push(...notices, "");
   switch (definition.shape) {
     case "rows": {
       const rowsResult = result as HeadlessPaneResult & { rows: HeadlessPaneRow[]; columns?: HeadlessPaneColumn[] };
@@ -446,7 +592,8 @@ export function renderHeadlessPaneText(
       break;
     case "snapshot": {
       const snapshot = result as HeadlessSnapshotResult;
-      lines.push(`As of: ${displayValue(snapshot.asOf)}`, "", renderRows(snapshot.items, undefined, definition.columns));
+      // The closing source line carries the snapshot's as-of, so it is not printed twice.
+      lines.push(renderRows(snapshot.items, undefined, definition.columns));
       break;
     }
     default: {
@@ -454,8 +601,9 @@ export function renderHeadlessPaneText(
       return _exhaustive;
     }
   }
-  if (result.errors?.length) lines.push("", cliStyles.warning(`Errors: ${result.errors.join(" ")}`));
-  return lines.join("\n").trimEnd();
+  if (result.notes?.length) lines.push("", ...renderMessages("Notes", result.notes));
+  if (result.errors?.length) lines.push("", ...renderMessages("Errors", result.errors));
+  return [lines.join("\n").trimEnd(), "", cliStyles.muted(formatFreshnessLine(freshness))].join("\n");
 }
 
 function resultRowCount(definition: HeadlessPaneDefinition, result: HeadlessPaneResult): number {
@@ -487,6 +635,8 @@ export async function buildHeadlessFunctionReport(
   const symbols = loaded.result.symbols ?? loaded.args.symbols;
   const unavailableSymbols = loaded.result.unavailableSymbols ?? (rowCount === 0 ? symbols : []);
   const serialized = serializeHeadlessPaneResult(loaded.definition, loaded.result);
+  const freshness = deriveHeadlessFreshness(loaded.definition, loaded.result);
+  const complete = loaded.result.complete !== false && unavailableSymbols.length === 0 && !loaded.result.errors?.length;
   return {
     data: {
       kind: loaded.definition.shape,
@@ -496,15 +646,25 @@ export async function buildHeadlessFunctionReport(
       options: resolved.options,
       rowCount,
       empty: rowCount === 0,
-      complete: loaded.result.complete !== false && unavailableSymbols.length === 0 && !loaded.result.errors?.length,
+      complete,
       unavailableSymbols,
       ...serialized,
+      freshness,
     },
     text: renderHeadlessPaneText(
       loaded.definition,
       loaded.result,
       loaded.args,
       resolved.label,
+      freshness,
+    ),
+    tables: headlessReportTables(
+      loaded.definition,
+      loaded.result,
+      loaded.args,
+      resolved.label,
+      freshness,
+      { complete, unavailableSymbols },
     ),
   };
 }

package/src/cli/pane-functions/index.ts

@@ -14,13 +14,16 @@ import {
   parsePaneFunctionArgs,
   type ParsedPaneFunctionArgs,
 } from "./options";
-import { resolvePaneFunction, type ResolvedPaneFunction } from "./resolver";
+import { applyListingArgument, resolvePaneFunction, type ResolvedPaneFunction } from "./resolver";
 import { buildFunctionReport } from "./report";
 import { defaultScreenshotPath, renderDesktopShot } from "./screenshot";
 import {
   buildPaneCatalogEntries,
 } from "./catalog";
+import { accessGateStatus, incompleteReportGateMessage } from "./access-gate";
 import { withPersistedCloudSession } from "./cloud-session";
+import { loadForListing } from "../listing-arg";
+import { selectReportTables } from "../report-tables";
 
 async function withPaneRuntime<T>(
   ctx: CliCommandContext,
@@ -31,13 +34,13 @@ async function withPaneRuntime<T>(
     registry: PaneFunctionCatalog;
     resolved: ResolvedPaneFunction;
   }) => Promise<T>,
-  settings: { strictHeadlessOptions?: boolean } = {},
+  settings: { strictHeadlessOptions?: boolean; tableSection?: boolean } = {},
 ): Promise<T> {
-  const parsed = parsePaneFunctionArgs(args, ctx.cliOptions);
   return withMarketData(ctx, async (market) => {
     const context: MarketContext = ctx.cliOptions.refresh ? { ...market, refresh: true } : market;
     const registry = await createPaneCatalog(context, ctx.plugins);
     try {
+      const parsed = await applyListingArgument(registry, context, parsePaneFunctionArgs(args, ctx.cliOptions));
       const resolved = await resolvePaneFunction(registry, context, parsed, settings);
       return await run({ parsed, context, registry, resolved });
     } finally {
@@ -57,22 +60,37 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
           + `Use "gloomberb catalog ${resolved.token}" to inspect readiness.`,
         );
       }
+      const tabular = ctx.cliOptions.format === "csv" || ctx.cliOptions.format === "ndjson";
+      if (resolved.tableSection !== undefined && !tabular) {
+        throw new Error("--section picks one table of --csv or --ndjson output.");
+      }
+      if (resolved.tableSection === true) throw new Error("--section needs a section title or number.");
+      // A report that fails or comes back empty for an exchange the symbol is not listed on says so.
       const report = await withPersistedCloudSession(
         context,
-        () => buildFunctionReport(resolved, context, parsed.arg),
+        () => loadForListing(
+          parsed.listing ?? [],
+          context,
+          ctx,
+          () => buildFunctionReport(resolved, context, parsed.arg),
+          (built) => built.data.empty || !built.data.complete,
+        ),
       );
       if (parsed.requireBotSafe && (report.data.empty || !report.data.complete)) {
         const unavailable = report.data.unavailableSymbols.length > 0
           ? ` Missing data for ${report.data.unavailableSymbols.join(", ")}.`
           : "";
+        const gated = incompleteReportGateMessage(resolved.token, report.data.errors);
+        if (gated) throw new Error(gated);
         throw new Error(
           `${resolved.token} did not produce a complete bot-safe report.${unavailable}`,
         );
       }
       ctx.printResult({ data: report.data }, {
         text: () => report.text,
+        ...(tabular ? { tables: selectReportTables(report.tables, resolved.tableSection) } : {}),
       });
-    }, { strictHeadlessOptions: true });
+    }, { strictHeadlessOptions: true, tableSection: true });
   });
 }
 
@@ -110,7 +128,7 @@ export async function runPaneScreenshot(args: string[], ctx: CliCommandContext)
       ctx.printResult({ data: result }, {
         text: (data) => {
           const issues = [
-            data.empty ? "empty" : null,
+            data.render.accessGate && (data.empty || !data.usable) ? accessGateStatus(data.render.accessGate) : data.empty ? "empty" : null,
             data.complete ? null : "incomplete",
             data.semanticMismatch ? "does not match the data" : null,
             data.usable ? null : "not usable",

package/src/cli/pane-functions/options.ts

@@ -9,6 +9,7 @@ import {
 } from "../../plugins/builtin/ticker-detail/financials/ratios";
 import type { PaneRuntimeState } from "../../core/state/app/state";
 import type { NormalizedPaneFunctionOptions } from "./capabilities";
+import type { ListingArg } from "../listing-arg";
 
 const DEFAULT_SHOT_WIDTH = 1280;
 const DEFAULT_SHOT_HEIGHT = 720;
@@ -32,6 +33,8 @@ export interface ParsedPaneFunctionArgs {
   /** Small label drawn in the pane title bar, e.g. a domain; null draws nothing. */
   watermark: string | null;
   requireBotSafe: boolean;
+  /** The listing a one-ticker function's argument named, once `applyListingArgument` has resolved it. */
+  listing?: ListingArg;
 }
 
 export interface ParsedPaneCatalogArgs {

package/src/cli/pane-functions/report.ts

@@ -2,7 +2,9 @@ import type { MarketContext } from "../types";
 import type { NormalizedPaneFunctionOptions } from "./capabilities";
 import type { ResolvedPaneFunction } from "./resolver";
 import { buildHeadlessFunctionReport } from "./headless";
-import { appendDomReportFooter, buildDomFunctionReport } from "./dom";
+import { appendDomReportFooter, buildDomFunctionReport, domReportNote } from "./dom";
+import type { ReportFreshness } from "./freshness";
+import type { CliReportTables } from "../report-tables";
 
 export type PaneFunctionReportSource = "headless" | "dom";
 
@@ -20,12 +22,16 @@ interface PaneFunctionReportData {
   empty: boolean;
   complete: boolean;
   unavailableSymbols: string[];
+  /** Source, as-of in UTC and live/delayed/stale/not-a-feed status; the last line of the text report. */
+  freshness: ReportFreshness;
   [key: string]: unknown;
 }
 
 export interface PaneFunctionReport {
   data: PaneFunctionReportData;
   text: string;
+  /** What `--csv` and `--ndjson` write: the text view's tables as flat rows, and the closing `#` lines. */
+  tables: CliReportTables;
 }
 
 export function resolvePaneFunctionReportSource(
@@ -56,7 +62,12 @@ export async function buildFunctionReport(
       report.text,
       elapsedMs,
       report.data.truncated === true,
+      report.data.freshness,
     );
+    report.tables = {
+      ...report.tables,
+      footer: [...report.tables.footer, `note: ${domReportNote(elapsedMs, report.data.truncated === true)}`],
+    };
   }
   return report;
 }

package/src/cli/pane-functions/resolver.ts

@@ -10,6 +10,7 @@ import { applyChartComposerCapabilityOptions } from "../../plugins/builtin/chart
 import { parseChartSpec } from "../../plugins/builtin/chart-composer/chart-spec";
 import { normalizeTickerInput } from "../../tickers/search";
 import { slugifyName } from "../../utils/slugify";
+import { resolveCliListing } from "../listing-arg";
 import type { MarketContext } from "../types";
 import {
   buildPaneFunctionLookup,
@@ -24,6 +25,7 @@ import {
   type ParsedPaneFunctionArgs,
 } from "./options";
 import {
+  capabilityHasOption,
   capabilityPaneSettings,
   getHeadlessPaneDefinition,
   getPaneFunctionCapability,
@@ -45,6 +47,8 @@ export interface ResolvedPaneFunction {
   optionSettings: Record<string, unknown>;
   capability: PaneFunctionCapability;
   options: NormalizedPaneFunctionOptions;
+  /** `--section` of a report: the table `--csv` and `--ndjson` write, when the function has no `section` option of its own. */
+  tableSection?: string | true;
 }
 
 async function buildPaneInstance(
@@ -94,19 +98,65 @@ async function buildPaneInstance(
   };
 }
 
-export async function resolvePaneFunction(
+function findPaneFunction(registry: PaneFunctionCatalog, target: string): { template?: PaneTemplateDef; pane?: PaneDef } | null {
+  const entry = buildPaneFunctionLookup(registry).get(normalizeLookupToken(target));
+  if (!entry) return null;
+  const template = "paneId" in entry && "description" in entry ? entry as PaneTemplateDef : undefined;
+  return { template, pane: template ? registry.panes.get(template.paneId) : entry as PaneDef };
+}
+
+/**
+ * `fn ANR SAN --exchange EPA` is `fn ANR SAN:EPA`: a function that takes one
+ * ticker gets the listing in its argument, and an exchange the app does not
+ * know fails with the venues the symbol trades on.
+ */
+export async function applyListingArgument(
   registry: PaneFunctionCatalog,
   context: MarketContext,
   args: ParsedPaneFunctionArgs,
-  resolutionSettings: { strictHeadlessOptions?: boolean } = {},
+): Promise<ParsedPaneFunctionArgs> {
+  const found = args.target ? findPaneFunction(registry, args.target) : null;
+  if (!found?.pane || !args.arg || /\s/.test(args.arg)) return args;
+  const headless = getHeadlessPaneDefinition(found.template, found.pane);
+  const takesOneTicker = headless ? headless.argument.kind === "ticker" : found.template?.shortcut?.argKind === "ticker";
+  // A function with an exchange option of its own (DIST) keeps it.
+  if (!takesOneTicker || getPaneFunctionCapability(found.template, found.pane).options.some((option) => option.key === "exchange")) {
+    return args;
+  }
+  const exchange = typeof args.options.exchange === "string" ? args.options.exchange : undefined;
+  const listing = await resolveCliListing(args.arg, exchange, context);
+  const { exchange: _exchange, ...options } = args.options;
+  return { ...args, arg: listing.key, options, listing };
+}
+
+/**
+ * `--section` picks one table of a report's `--csv` or `--ndjson` output. A
+ * function that has a `section` option of its own (CALLS: which part of a
+ * transcript) keeps the flag; its report is one table, so there is nothing to
+ * pick there.
+ */
+function takeTableSection(
+  capability: PaneFunctionCapability,
+  options: ParsedPaneFunctionArgs["options"],
+): { options: ParsedPaneFunctionArgs["options"]; tableSection?: string | true } {
+  if (!("section" in options) || capabilityHasOption(capability, "section")) return { options };
+  const { section, ...rest } = options;
+  return { options: rest, tableSection: section };
+}
+
+export async function resolvePaneFunction(
+  registry: PaneFunctionCatalog,
+  context: MarketContext,
+  parsedArgs: ParsedPaneFunctionArgs,
+  resolutionSettings: { strictHeadlessOptions?: boolean; tableSection?: boolean } = {},
 ): Promise<ResolvedPaneFunction> {
+  let args = parsedArgs;
   if (!args.target) {
     throw new Error("Usage: gloomberb fn <function-or-pane> [argument] [--key value]");
   }
 
-  const lookup = buildPaneFunctionLookup(registry);
-  const entry = lookup.get(normalizeLookupToken(args.target));
-  if (!entry) {
+  const found = findPaneFunction(registry, args.target);
+  if (!found) {
     const shortcuts = [...registry.paneTemplates.values()]
       .map((template) => template.shortcut?.prefix)
       .filter((prefix): prefix is string => !!prefix)
@@ -114,16 +164,19 @@ export async function resolvePaneFunction(
     throw new Error(`Unknown function or pane "${args.target}". Try one of: ${shortcuts.slice(0, 18).join(", ")}`);
   }
 
-  const template = "paneId" in entry && "description" in entry ? entry as PaneTemplateDef : undefined;
-  const pane = template
-    ? registry.panes.get(template.paneId)
-    : entry as PaneDef;
+  const { template, pane } = found;
   if (!pane) {
     throw new Error(`Template "${template?.id}" points at missing pane "${template?.paneId}".`);
   }
   const createOptions = buildCreateOptions(template, args.arg);
   const headless = getHeadlessPaneDefinition(template, pane);
   const capability = getPaneFunctionCapability(template, pane);
+  let tableSection: string | true | undefined;
+  if (resolutionSettings.tableSection) {
+    const taken = takeTableSection(capability, args.options);
+    args = { ...args, options: taken.options };
+    tableSection = taken.tableSection;
+  }
   const normalizedOptions = normalizeCapabilityOptions(capability, args.options, {
     strict: args.requireBotSafe || (!!headless && resolutionSettings.strictHeadlessOptions === true),
   });
@@ -149,6 +202,7 @@ export async function resolvePaneFunction(
     optionSettings: settings,
     capability,
     options: normalizedOptions,
+    ...(tableSection !== undefined ? { tableSection } : {}),
   };
   resolved.instance = await buildPaneInstance(resolved, context, args.arg);
   return resolved;

package/src/cli/pane-functions/screenshot-evidence.ts

@@ -18,6 +18,7 @@ import { scenarioScreenshotEvidence } from "../../plugins/builtin/options-scenar
 import { realizedVolScreenshotEvidence } from "../../plugins/builtin/realized-vol/evidence";
 import { volSurfaceScreenshotEvidence } from "../../plugins/builtin/vol-surface/evidence";
 import { volatilityScreenshotEvidence } from "../../plugins/builtin/volatility/evidence";
+import { worldMapScreenshotEvidence } from "../../plugins/builtin/world-venue-map/evidence";
 
 /** The envelope every pane's rendered chart-data evidence carries. */
 export interface PaneScreenshotEvidence {
@@ -93,6 +94,7 @@ const PANE_SCREENSHOT_EVIDENCE: readonly PaneScreenshotEvidenceHook[] = [
   realizedVolScreenshotEvidence,
   volSurfaceScreenshotEvidence,
   volatilityScreenshotEvidence,
+  worldMapScreenshotEvidence,
 ];
 
 export function paneScreenshotEvidenceHook(resolved: ResolvedPaneFunction): PaneScreenshotEvidenceHook | null {