gloomberb 0.16.1 → 0.16.3

package/src/cli/listing-arg.ts

@@ -0,0 +1,321 @@
+import type { DataProvider } from "../types/data-provider";
+import type { Quote } from "../types/financials";
+import type { CliCommandContext } from "../types/plugin";
+import type { TickerRecord } from "../types/ticker";
+import { AmbiguousContractError, AmbiguousTickerError, listingChoiceQuery, resolveTickerSearch } from "../tickers/search";
+import { cliStyles } from "../utils/cli-output";
+import {
+  canonicalExchange,
+  exchangeLabel,
+  isKnownExchangeCode,
+  parsePublicTickerKey,
+  publicTickerKey,
+} from "../utils/exchanges";
+import { withMarketData } from "./scoped-context";
+
+/** The `--exchange` option of every command that takes a ticker. */
+export const EXCHANGE_OPTION = {
+  flags: "--exchange <code>",
+  description: "Listing exchange, for a symbol that trades in several places (same as SYMBOL:CODE)",
+};
+
+export class ListingArgError extends Error {
+  constructor(message: string, readonly details?: string) {
+    super(message);
+    this.name = "ListingArgError";
+  }
+}
+
+export interface ListingArg {
+  /** The symbol without a venue: SAN. */
+  symbol: string;
+  /** The canonical code of the exchange the user named, or "" when none was. */
+  exchange: string;
+  /** SAN:EPA, or SAN when no exchange was named. */
+  key: string;
+}
+
+/**
+ * `SAN:EPA` and `SAN --exchange EPA` name the same listing. Both spellings of
+ * an exchange go through the app's alias table, so `SAN:XPAR` is `SAN:EPA`.
+ * A symbol's own exchange and `--exchange` that disagree are an error, unless
+ * the command takes several symbols and `--exchange` only fills in the ones
+ * without an exchange of their own.
+ */
+export function parseListingArg(
+  raw: string,
+  exchangeOption?: string | null,
+  { ownExchangeWins = false }: { ownExchangeWins?: boolean } = {},
+): ListingArg {
+  const option = canonicalExchange(exchangeOption ?? "");
+  let typed = raw.trim().replace(/^\$/, "").toUpperCase();
+  // `SAN:` asks which listing; with --exchange it has its answer.
+  if (option && typed.endsWith(":")) typed = typed.slice(0, -1);
+  const parsed = parsePublicTickerKey(typed);
+  if (parsed.exchange && option && parsed.exchange !== option && !ownExchangeWins) {
+    throw new ListingArgError(
+      `${typed} names exchange ${parsed.exchange}, but --exchange names ${option}.`,
+      `Name the exchange once, as ${parsed.symbol}:${parsed.exchange} or ${parsed.symbol} --exchange ${option}.`,
+    );
+  }
+  const exchange = parsed.exchange ?? option;
+  return { symbol: parsed.symbol, exchange, key: exchange ? `${parsed.symbol}:${exchange}` : parsed.symbol };
+}
+
+interface ListingStore {
+  loadTicker(symbol: string): Promise<TickerRecord | null>;
+  loadAllTickers(): Promise<TickerRecord[]>;
+}
+
+export interface ListingDeps {
+  store: ListingStore;
+  dataProvider: DataProvider;
+}
+
+export interface ListingVenue {
+  /** Canonical code. */
+  exchange: string;
+  name: string;
+}
+
+/**
+ * The venues a symbol trades on and the company on each, from the same
+ * listing picker the command bar opens for `SAN:`.
+ */
+export async function listingVenues(symbol: string, { store, dataProvider }: ListingDeps): Promise<ListingVenue[]> {
+  const query = `${symbol}:`;
+  if (!listingChoiceQuery(query)) return [];
+  const tickers = new Map((await store.loadAllTickers()).map((ticker) => [ticker.metadata.ticker.toUpperCase(), ticker] as const));
+  let venues: ListingVenue[];
+  try {
+    const resolved = await resolveTickerSearch({ query, activeTicker: null, tickers, dataProvider });
+    const only = !resolved ? null
+      : resolved.kind === "local" ? { exchange: resolved.ticker.metadata.exchange, name: resolved.ticker.metadata.name }
+      : {
+        exchange: resolved.result.exchange === "SMART" ? resolved.result.primaryExchange ?? "" : resolved.result.exchange || resolved.result.primaryExchange || "",
+        name: resolved.result.name,
+      };
+    venues = only?.exchange ? [{ exchange: canonicalExchange(only.exchange), name: only.name }] : [];
+  } catch (error) {
+    // One listing settles the picker; several are its choices.
+    if (!(error instanceof AmbiguousTickerError) || error instanceof AmbiguousContractError) return [];
+    venues = error.listings.flatMap((listing) => {
+      const exchange = parsePublicTickerKey(listing).exchange;
+      return exchange ? [{ exchange, name: error.listingNames[listing] ?? "" }] : [];
+    });
+  }
+  return venues.filter((venue, index) => venues.findIndex((other) => other.exchange === venue.exchange) === index);
+}
+
+function tradesOn(symbol: string, venues: readonly ListingVenue[]): string {
+  return venues.length > 0 ? ` ${symbol} trades on: ${venues.map((venue) => venue.exchange).join(", ")}.` : "";
+}
+
+/**
+ * An exchange code the app does not know is accepted only when the symbol is
+ * listed there, so a typo never falls back to another venue's line.
+ */
+async function checkListingExchange(listing: ListingArg, deps: ListingDeps): Promise<void> {
+  if (listing.symbol.endsWith(":")) {
+    const symbol = listing.symbol.slice(0, -1);
+    throw new ListingArgError(`Choose an exchange for ${symbol}.${tradesOn(symbol, await listingVenues(symbol, deps))}`);
+  }
+  if (!listing.exchange || isKnownExchangeCode(listing.exchange)) return;
+  const venues = await listingVenues(listing.symbol, deps);
+  if (venues.some((venue) => venue.exchange === listing.exchange)) return;
+  throw new ListingArgError(
+    `Unknown exchange ${listing.exchange} for ${listing.symbol}.${tradesOn(listing.symbol, venues)}`,
+    venues.length > 0 ? undefined : `No listings of ${listing.symbol} were found.`,
+  );
+}
+
+/**
+ * "SAN does not trade on TSX. SAN trades on: NYSE, EPA." for a listing whose
+ * exchange the symbol is not listed on, from the same picker `SAN:` opens.
+ * Null when no exchange was named, when the symbol is listed there, or when its
+ * venues cannot be found, so the request's own failure stands. It searches, so
+ * ask only after a request came back empty.
+ */
+export async function notTradedMessage(
+  listing: Pick<ListingArg, "symbol" | "exchange">,
+  deps: ListingDeps,
+): Promise<string | null> {
+  if (!listing.exchange) return null;
+  const venues = await listingVenues(listing.symbol, deps).catch(() => []);
+  if (venues.length === 0 || venues.some((venue) => venue.exchange === listing.exchange)) return null;
+  return `${listing.symbol} does not trade on ${listing.exchange}.${tradesOn(listing.symbol, venues)}`;
+}
+
+/** Fails the command with `notTradedMessage`; returns when the symbol does trade there. */
+export async function failIfNotTraded(
+  listing: Pick<ListingArg, "symbol" | "exchange">,
+  deps: ListingDeps,
+  ctx: Pick<CliCommandContext, "fail">,
+): Promise<void> {
+  const message = await notTradedMessage(listing, deps);
+  if (message) ctx.fail(message);
+}
+
+/**
+ * A data request for the listings a command named. When it throws, or `isMiss`
+ * calls what it returned empty, and a listing's exchange is one its symbol does
+ * not trade on, the command ends in that message instead of the request's own
+ * "unavailable". A request that succeeds costs no extra lookup.
+ */
+export async function loadForListing<T>(
+  listings: Pick<ListingArg, "symbol" | "exchange"> | readonly Pick<ListingArg, "symbol" | "exchange">[],
+  deps: ListingDeps,
+  ctx: Pick<CliCommandContext, "fail">,
+  load: () => Promise<T>,
+  isMiss?: (value: T) => boolean,
+): Promise<T> {
+  const named = ("symbol" in listings ? [listings] : listings).filter((listing) => listing.exchange);
+  const checkVenues = () => Promise.all(named.map((listing) => failIfNotTraded(listing, deps, ctx)));
+  let value: T;
+  try {
+    value = await load();
+  } catch (error) {
+    await checkVenues();
+    throw error;
+  }
+  if (isMiss?.(value)) await checkVenues();
+  return value;
+}
+
+/** The saved ticker for a listing: under its own key, or a saved symbol whose venue it is. */
+export async function loadSavedListing(store: ListingStore, listing: ListingArg): Promise<TickerRecord | null> {
+  if (!listing.exchange) return store.loadTicker(listing.symbol);
+  for (const key of new Set([listing.key, publicTickerKey(listing.symbol, listing.exchange), listing.symbol])) {
+    const ticker = await store.loadTicker(key);
+    if (ticker && (key === listing.key || canonicalExchange(ticker.metadata.exchange) === listing.exchange)) return ticker;
+  }
+  return null;
+}
+
+export interface CliListing extends ListingArg {
+  saved: TickerRecord | null;
+  /**
+   * What data requests take: a named listing goes by its key (SAN:EPA), never
+   * the bare symbol's cache; a bare symbol goes on its saved venue, as the
+   * command bar opens it.
+   */
+  request: { symbol: string; exchange: string };
+}
+
+export async function resolveCliListing(
+  raw: string,
+  exchangeOption: string | null | undefined,
+  deps: ListingDeps,
+  options: { ownExchangeWins?: boolean } = {},
+): Promise<CliListing> {
+  const listing = parseListingArg(raw, exchangeOption, options);
+  if (!listing.symbol) throw new ListingArgError("Ticker symbol is required.");
+  await checkListingExchange(listing, deps);
+  const saved = await loadSavedListing(deps.store, listing);
+  return {
+    ...listing,
+    saved,
+    request: listing.exchange
+      ? { symbol: listing.key, exchange: listing.exchange }
+      : { symbol: listing.symbol, exchange: saved?.metadata.exchange ?? "" },
+  };
+}
+
+/** `resolveCliListing` for a command: a bad exchange fails the command with its message. */
+export async function requireCliListing(
+  raw: string,
+  exchangeOption: string | null | undefined,
+  deps: ListingDeps,
+  ctx: Pick<CliCommandContext, "fail">,
+  options: { ownExchangeWins?: boolean } = {},
+): Promise<CliListing> {
+  try {
+    return await resolveCliListing(raw, exchangeOption, deps, options);
+  } catch (error) {
+    if (error instanceof ListingArgError) ctx.fail(error.message, error.details);
+    throw error;
+  }
+}
+
+/**
+ * The listing for commands that store things by symbol (notes, alerts). The
+ * data sources are only opened to check an exchange the app does not know.
+ */
+export async function requireListingArg(
+  raw: string,
+  exchangeOption: string | null | undefined,
+  ctx: Pick<CliCommandContext, "fail" | "initMarketData">,
+): Promise<ListingArg> {
+  try {
+    const listing = parseListingArg(raw, exchangeOption);
+    if (listing.symbol.endsWith(":") || (listing.exchange && !isKnownExchangeCode(listing.exchange))) {
+      await withMarketData(ctx, (market) => checkListingExchange(listing, market));
+    }
+    return listing;
+  } catch (error) {
+    if (error instanceof ListingArgError) ctx.fail(error.message, error.details);
+    throw error;
+  }
+}
+
+export interface ListingIdentity {
+  symbol: string;
+  /** Canonical code of the venue the data is for. */
+  exchange: string;
+  /** The listing's company, from its own quote. */
+  name: string | null;
+}
+
+export function listingIdentity(
+  listing: CliListing,
+  quote?: Pick<Quote, "name" | "listingExchangeName" | "exchangeName"> | null,
+): ListingIdentity {
+  const quoteExchange = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName);
+  const exchange = listing.exchange || quoteExchange || canonicalExchange(listing.saved?.metadata.exchange);
+  // A quote that prices another venue names another listing's company.
+  const quoteName = !quoteExchange || quoteExchange === exchange ? quote?.name?.trim() : undefined;
+  return { symbol: listing.symbol, exchange, name: quoteName || listing.saved?.metadata.name?.trim() || null };
+}
+
+/** The listing's own quote, for its company name and venue; null when it has none. */
+export async function loadListingQuote(dataProvider: DataProvider, listing: CliListing): Promise<Quote | null> {
+  try {
+    return await dataProvider.getQuote(listing.request.symbol, listing.request.exchange);
+  } catch {
+    return null;
+  }
+}
+
+/** One line above a table naming what it is about: "Sanofi  ·  Euronext Paris (EPA)". */
+export function listingHeading(identity: ListingIdentity): string {
+  const venue = identity.exchange ? cliStyles.muted(`  ·  ${exchangeLabel(identity.exchange)}`) : "";
+  return `${cliStyles.bold(identity.name || identity.symbol)}${venue}`;
+}
+
+/** "Sanofi (EPA)", for sentences. */
+export function listingTitle(identity: ListingIdentity): string {
+  const name = identity.name || identity.symbol;
+  return identity.exchange ? `${name} (${identity.exchange})` : name;
+}
+
+export interface SavedListingName {
+  symbol: string;
+  /** Canonical code of the venue the row is saved for, or "" when it has none. */
+  exchange: string;
+  /** SAN:EPA, whichever way the row is stored (SAN, SAN:XNYS). */
+  key: string;
+  name: string | null;
+  /** "SAN:EPA (Sanofi)", for sentences. */
+  label: string;
+}
+
+/** The listing a saved ticker row is, as a collection command names it after adding or removing it. */
+export function savedListingName(ticker: TickerRecord): SavedListingName {
+  const { symbol } = parsePublicTickerKey(ticker.metadata.ticker);
+  const exchange = canonicalExchange(ticker.metadata.exchange);
+  const key = exchange ? `${symbol}:${exchange}` : symbol;
+  // A row saved without a company carries its symbol as the name.
+  const typed = ticker.metadata.name?.trim();
+  const name = typed && typed !== symbol && typed !== ticker.metadata.ticker ? typed : null;
+  return { symbol, exchange, key, name, label: name ? `${key} (${name})` : key };
+}

package/src/cli/options.ts

@@ -15,6 +15,8 @@ export interface ParsedCliArgs {
   options: CliGlobalOptions;
   /** `--help` or `-h` appeared before `--`. The flag is removed from args. */
   help: boolean;
+  /** Index in `args` where the arguments after a bare `--` begin; they are never options. */
+  literalStart: number;
 }
 
 export function isCliHelpFlag(arg: string): boolean {
@@ -43,10 +45,12 @@ export function parseCliGlobalArgs(rawArgs: string[]): ParsedCliArgs {
   const options: CliGlobalOptions = { ...DEFAULT_CLI_OPTIONS };
   const args: string[] = [];
   let help = false;
+  let literalStart: number | null = null;
 
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index]!;
     if (arg === "--") {
+      literalStart = args.length;
       args.push(...rawArgs.slice(index + 1));
       break;
     }
@@ -102,5 +106,5 @@ export function parseCliGlobalArgs(rawArgs: string[]): ParsedCliArgs {
     args.push(arg);
   }
 
-  return { args, options, help };
+  return { args, options, help, literalStart: literalStart ?? args.length };
 }

package/src/cli/pane-functions/access-gate.ts

@@ -0,0 +1,42 @@
+/**
+ * What keeps a pane from showing everything it has: a Pro lock on part of it,
+ * or a wall that needs an account. Reports and screenshots name it, so a
+ * failure says "locked" instead of a generic incomplete or empty.
+ */
+export type PaneAccessGate = "pro" | "sign-in";
+
+// A Pro-gated loader reports what is locked in its errors ("Full history requires Gloom Pro").
+const SIGN_IN_ERROR = /\bsign(?:ed)?[ -]?in\b|\bsignup\b|\bemail verification\b|\bverify your email\b/i;
+const PRO_ERROR = /\bGloom (?:Cloud )?Pro\b|\b(?:requires?|needs?) Pro\b|\bPro access\b/;
+
+function errorMessages(errors: unknown): string[] {
+  return Array.isArray(errors) ? errors.filter((error): error is string => typeof error === "string") : [];
+}
+
+/** Why the output cannot be used as it is, as a clause: "some values need Gloom Cloud Pro (locked)". */
+function accessGateReason(gate: PaneAccessGate): string {
+  return gate === "pro" ? "some values need Gloom Cloud Pro (locked)" : "it needs a Gloom Cloud sign-in";
+}
+
+/** The reason as a sentence, for a screenshot's "Reason" row. */
+export function accessGateSentence(gate: PaneAccessGate): string {
+  const reason = accessGateReason(gate);
+  return `${reason.charAt(0).toUpperCase()}${reason.slice(1)}.`;
+}
+
+/** The word a screenshot's status line uses in place of "empty" for a gated pane. */
+export function accessGateStatus(gate: PaneAccessGate): string {
+  return gate === "pro" ? "locked" : "needs sign-in";
+}
+
+/**
+ * The failure for an incomplete report whose own errors name a gate, with
+ * those errors saying which values; null when they name none.
+ */
+export function incompleteReportGateMessage(token: string, errors: unknown): string | null {
+  const messages = errorMessages(errors);
+  const gate = messages.some((message) => SIGN_IN_ERROR.test(message)) ? "sign-in"
+    : messages.some((message) => PRO_ERROR.test(message)) ? "pro" : null;
+  const detail = messages.map((message) => message.replace(/\.+$/, "")).join(". ");
+  return gate ? `${token} is not bot-safe: ${accessGateReason(gate)}. ${detail}.` : null;
+}

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

@@ -134,6 +134,11 @@ function resolveOptionDef(
   ));
 }
 
+/** Whether the function has an option of its own under this name or an alias. */
+export function capabilityHasOption(capability: PaneFunctionCapability, key: string): boolean {
+  return resolveOptionDef(capability, key) !== undefined;
+}
+
 function normalizeEnumValue(option: PaneFunctionOptionDef, rawValue: string): string {
   const token = optionToken(rawValue);
   const match = option.values?.find((candidate) => (

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

@@ -199,6 +199,30 @@ export async function buildPaneCatalogEntries(
   return entries.sort((left, right) => left.token.localeCompare(right.token));
 }
 
+/** The phrase starting a word of the text, so "funding rate" finds "funding rates" but "rate" is not found in "separate". */
+function containsPhrase(text: string, phrase: string): boolean {
+  for (let at = text.indexOf(phrase); at >= 0; at = text.indexOf(phrase, at + 1)) {
+    if (at === 0 || !/[a-z0-9]/.test(text[at - 1]!)) return true;
+  }
+  return false;
+}
+
+// A multi-word query ranks a function carrying the whole phrase in its name or keywords first, then in its
+// description, then one matching every word somewhere; the rest rank by how many words they match.
+const PHRASE_IN_NAME_BAND = 4000;
+const PHRASE_IN_DESCRIPTION_BAND = 3000;
+const ALL_WORDS_BAND = 2000;
+const PER_MATCHED_WORD = 100;
+
+function phraseBand(entry: PaneCatalogEntry, phrase: string): number {
+  const lower = (values: Array<string | undefined>) => values
+    .filter((value): value is string => !!value).map((value) => value.toLowerCase().replace(/\s+/g, " "));
+  const names = lower([entry.token, entry.label, entry.paneName, entry.shortcut, ...entry.aliases, ...entry.keywords, ...entry.capability.aliases]);
+  if (names.some((name) => containsPhrase(name, phrase))) return PHRASE_IN_NAME_BAND;
+  const descriptions = lower([entry.description, ...entry.capability.intents]);
+  return descriptions.some((description) => containsPhrase(description, phrase)) ? PHRASE_IN_DESCRIPTION_BAND : 0;
+}
+
 function paneCatalogSearchScore(entry: PaneCatalogEntry, query: string): number {
   const terms = query.toLowerCase().split(/\s+/).map((term) => term.trim()).filter(Boolean);
   if (terms.length === 0) return 1;
@@ -253,7 +277,10 @@ function paneCatalogSearchScore(entry: PaneCatalogEntry, query: string): number
   if (matchedTerms === 0) return 0;
   score += Math.round((matchedTerms / terms.length) * 8);
   if (entry.capability.botSafe) score += 2;
-  return score;
+  // One word has no phrase to prefer: it keeps the plain term scores.
+  if (terms.length === 1) return score;
+  const band = phraseBand(entry, terms.join(" "));
+  return score + matchedTerms * PER_MATCHED_WORD + (band || (matchedTerms === terms.length ? ALL_WORDS_BAND : 0));
 }
 
 export function filterPaneCatalogEntries(entries: PaneCatalogEntry[], query: string): PaneCatalogEntry[] {

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

@@ -182,5 +182,7 @@ export function collectShotSymbols(resolved: ResolvedPaneFunction, rawArg: strin
   if (resolved.capability.id === "security-relationship" && symbols.length === 1) {
     symbols = [...symbols, "SPY"];
   }
-  return [...new Set(symbols.map(cleanTickerInput).filter(Boolean))];
+  // Entries a ticker list keeps as typed (CORR's GEO:HORMUZ) are not tickers to fetch.
+  const keep = resolved.template?.shortcut?.keepArgToken;
+  return [...new Set(symbols.filter((symbol) => !keep?.(symbol)).map(cleanTickerInput).filter(Boolean))];
 }

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

@@ -1,10 +1,13 @@
 import type { DesktopPaneShotRenderedRow } from "../desktop-pane-shot";
-import { renderSection, renderTable } from "../../utils/cli-output";
+import { cliStyles, renderSection, renderTable } from "../../utils/cli-output";
+import { formatUtcTime } from "../../utils/utc-time";
 import type { MarketContext } from "../types";
 import type { PaneFunctionReport } from "./report";
 import type { ResolvedPaneFunction } from "./resolver";
 import { collectShotSymbols } from "./data";
 import { renderDesktopShot, type PaneScreenshotResult } from "./screenshot";
+import { deriveRenderedFreshness, formatFreshnessLine, type ReportFreshness } from "./freshness";
+import { exportTextTable, reportFooterLines, type CliReportTables } from "../report-tables";
 
 const DOM_REPORT_WIDTH = 1280;
 const DOM_REPORT_HEIGHT = 720;
@@ -32,7 +35,21 @@ function domCellKeys(row: DesktopPaneShotRenderedRow): string[] {
   });
 }
 
-function renderDomTables(rows: DesktopPaneShotRenderedRow[]): string[] {
+/**
+ * A pane may shorten a time to fit ("Wed 11:27", "Oct 2"); the report prints
+ * the instant behind it with its date and zone instead.
+ */
+function cellText(cell: DesktopPaneShotRenderedRow["cells"][number]): string {
+  return cell.instant ? formatUtcTime(cell.instant) || cell.text : cell.text;
+}
+
+interface DomTable {
+  tableIndex: number;
+  columns: Array<{ key: string; header: string }>;
+  rows: Array<Map<string, DesktopPaneShotRenderedRow["cells"][number]>>;
+}
+
+function domTables(rows: DesktopPaneShotRenderedRow[]): DomTable[] {
   const byTable = new Map<number, DesktopPaneShotRenderedRow[]>();
   for (const row of rows) {
     const tableRows = byTable.get(row.tableIndex) ?? [];
@@ -40,7 +57,7 @@ function renderDomTables(rows: DesktopPaneShotRenderedRow[]): string[] {
     byTable.set(row.tableIndex, tableRows);
   }
 
-  return [...byTable.entries()].flatMap(([tableIndex, tableRows], index) => {
+  return [...byTable.entries()].map(([tableIndex, tableRows]) => {
     // Captured rows omit blank cells, so a cell's position is not its column.
     const columns: Array<{ key: string; header: string }> = [];
     for (const row of tableRows) {
@@ -56,22 +73,54 @@ function renderDomTables(rows: DesktopPaneShotRenderedRow[]): string[] {
         previous = position;
       }
     }
-    const output = renderTable(
+    return {
+      tableIndex,
       columns,
-      tableRows.map((row) => {
+      rows: tableRows.map((row) => {
         const keys = domCellKeys(row);
-        const textByKey = new Map(row.cells.map((cell, cellIndex) => [keys[cellIndex]!, cell.text]));
-        return columns.map((column) => textByKey.get(column.key) ?? "");
+        return new Map(row.cells.map((cell, cellIndex) => [keys[cellIndex]!, cell]));
       }),
-    );
-    return [
-      ...(index > 0 ? [""] : []),
-      ...(byTable.size > 1 ? [renderSection(`Rendered table ${tableIndex + 1}`)] : []),
-      output,
-    ];
+    };
   });
 }
 
+function domTableTitle(table: DomTable): string {
+  return `Rendered table ${table.tableIndex + 1}`;
+}
+
+function renderDomTables(rows: DesktopPaneShotRenderedRow[]): string[] {
+  const tables = domTables(rows);
+  return tables.flatMap((table, index) => [
+    ...(index > 0 ? [""] : []),
+    ...(tables.length > 1 ? [renderSection(domTableTitle(table))] : []),
+    renderTable(
+      table.columns,
+      table.rows.map((cells) => table.columns.map((column) => {
+        const cell = cells.get(column.key);
+        return cell ? cellText(cell) : "";
+      })),
+    ),
+  ]);
+}
+
+/** The rendered tables as `--csv` writes them, with the instant behind a shortened time. */
+function domReportTables(
+  rows: DesktopPaneShotRenderedRow[],
+  title: string,
+  freshness: ReportFreshness,
+  incomplete: boolean | string,
+): CliReportTables {
+  const tables = domTables(rows);
+  return {
+    tables: tables.map((table) => exportTextTable(
+      tables.length > 1 ? domTableTitle(table) : title,
+      table.columns.map((column) => column.header),
+      table.rows.map((cells) => table.columns.map((column) => cells.get(column.key))),
+    )),
+    footer: reportFooterLines({ freshness, incomplete }),
+  };
+}
+
 function renderedFailureReason(
   result: PaneScreenshotResult,
   rows: DesktopPaneShotRenderedRow[],
@@ -129,7 +178,12 @@ export function buildDomPaneReportFromRender(
     textLines.push(failureReason ?? "No rendered values were available.");
   }
   if (failureReason && rows.length > 0) textLines.push("", failureReason);
+  const freshness = deriveRenderedFreshness(resolved.pane.reportFreshness, {
+    footerText: result.render.footerText ?? "",
+    cellTimes: rows.flatMap((row) => row.cells.flatMap((cell) => cell.instant ?? [])),
+  });
 
+  const complete = failureReason === null && !truncated;
   return {
     data: {
       kind: "rendered-view",
@@ -139,7 +193,7 @@ export function buildDomPaneReportFromRender(
       options: resolved.options,
       rowCount: rows.length,
       empty: rows.length === 0,
-      complete: failureReason === null && !truncated,
+      complete,
       unavailableSymbols,
       rows,
       visibleText: result.render.visibleText,
@@ -147,8 +201,15 @@ export function buildDomPaneReportFromRender(
       truncationReasons,
       limitation: DOM_LIMITATION,
       ...(failureReason ? { reason: failureReason } : {}),
+      freshness,
     },
     text: textLines.join("\n").trimEnd(),
+    tables: domReportTables(
+      rows,
+      resolved.label,
+      freshness,
+      !complete && (failureReason ?? (truncationReasons.length > 0 ? truncationReasons.join("; ") : true)),
+    ),
   };
 }
 
@@ -156,15 +217,22 @@ export function appendDomReportFooter(
   text: string,
   elapsedMs: number,
   truncated: boolean,
+  freshness: ReportFreshness,
 ): string {
-  const clipping = truncated ? "The rendered view is clipped." : "The rendered view may be clipped.";
   return [
     text,
     "",
-    `Rendered view: values come from the visible pane. ${clipping} Render time: ${elapsedMs} ms.`,
+    domReportNote(elapsedMs, truncated),
+    cliStyles.muted(formatFreshnessLine(freshness)),
   ].join("\n");
 }
 
+/** What a rendered-view report says about where its values come from. */
+export function domReportNote(elapsedMs: number, truncated: boolean): string {
+  const clipping = truncated ? "The rendered view is clipped." : "The rendered view may be clipped.";
+  return `Rendered view: values come from the visible pane. ${clipping} Render time: ${elapsedMs} ms.`;
+}
+
 function failedDomReport(
   resolved: ResolvedPaneFunction,
   rawArg: string,
@@ -176,6 +244,7 @@ function failedDomReport(
     .trim();
   const reason = `The rendered view could not be read: ${message || "unknown renderer error"}`;
   const symbols = collectShotSymbols(resolved, rawArg);
+  const freshness = deriveRenderedFreshness(resolved.pane.reportFreshness, { footerText: "", cellTimes: [] });
   return {
     data: {
       kind: "rendered-view",
@@ -193,8 +262,10 @@ function failedDomReport(
       truncationReasons: [],
       limitation: DOM_LIMITATION,
       reason,
+      freshness,
     },
     text: [resolved.label, "", reason].join("\n"),
+    tables: { tables: [], footer: reportFooterLines({ freshness, incomplete: reason }) },
   };
 }