gloomberb 0.11.2 → 0.12.0

package/src/brokers/test-broker.ts

@@ -0,0 +1,68 @@
+import type { BrokerAdapter } from "../types/broker";
+
+/**
+ * A stand-in broker for tests of the generic broker machinery.
+ *
+ * These tests used to reach for the real IBKR adapter, which now lives in its
+ * own repository. Depending on a plugin to exercise host code is backwards
+ * anyway: it made a core test fail whenever that plugin's schema changed, and
+ * it hid which behaviour was actually under test.
+ *
+ * The shape mirrors what the machinery has to handle — a mode switch, a nested
+ * config, and a password field that must survive an edit left blank.
+ */
+export const testBroker: BrokerAdapter = {
+  id: "test-broker",
+  name: "Test Broker",
+  configSchema: [
+    {
+      key: "connectionMode",
+      label: "Connection",
+      type: "select",
+      options: [
+        { value: "token", label: "Token" },
+        { value: "local", label: "Local" },
+      ],
+      defaultValue: "token",
+    },
+    { key: "token", label: "API Token", type: "password", required: true, visibleWhen: { connectionMode: "token" } },
+    { key: "accountId", label: "Account", type: "text", required: true, visibleWhen: { connectionMode: "token" } },
+    { key: "host", label: "Host", type: "text", defaultValue: "127.0.0.1", visibleWhen: { connectionMode: "local" } },
+  ],
+
+  async validate() {
+    return true;
+  },
+
+  async importPositions() {
+    return [];
+  },
+
+  getStatus() {
+    return { state: "disconnected", message: "", updatedAt: 0 };
+  },
+
+  getProfileActions() {
+    // The pane renders and invokes profile actions; one is enough to cover that.
+    return [{ id: "test-console", label: "Console", paneId: "ibkr-trading" }];
+  },
+
+  toConfigValues(instance) {
+    const config = instance.config as Record<string, unknown>;
+    const credentials = (config.credentials ?? {}) as Record<string, unknown>;
+    return {
+      connectionMode: String(config.connectionMode ?? "token"),
+      token: String(credentials.token ?? ""),
+      accountId: String(credentials.accountId ?? ""),
+      host: String(config.host ?? "127.0.0.1"),
+    };
+  },
+
+  fromConfigValues(values) {
+    return {
+      connectionMode: values.connectionMode,
+      credentials: { token: values.token, accountId: values.accountId },
+      host: values.host,
+    };
+  },
+};

package/src/capabilities/chart-series.ts

@@ -9,6 +9,7 @@ import type {
   SeriesTransform,
   TimeSeriesPoint,
 } from "../time-series/types";
+import { CHART_RESOLUTIONS, TIME_RANGES } from "../time-series/range";
 import type {
   CapabilityInvoker,
   CapabilitySchema,
@@ -24,8 +25,8 @@ export const MAX_CHART_SERIES_POINTS = 20_000;
 const CAPABILITY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
 const SERIES_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~%:/-]{0,239}$/;
 const chartSeriesLog = debugLog.createLogger("chart-series");
-const ranges = new Set(["1D", "1W", "1M", "3M", "6M", "1Y", "5Y", "ALL"]);
-const resolutions = new Set(["auto", "1m", "5m", "15m", "30m", "45m", "1h", "1d", "1wk", "1mo"]);
+const ranges = new Set<string>(TIME_RANGES);
+const resolutions = new Set<string>(CHART_RESOLUTIONS);
 const periods = new Set(["auto", "daily", "weekly", "monthly", "quarterly", "annual", "ttm"]);
 const styles = new Set(["line", "area", "step", "columns", "points", "candles", "ohlc", "hlc"]);
 const transforms = new Set(["raw", "percent", "index100", "yoy", "qoq", "log"]);

package/src/cli/commands/market.ts

@@ -1,5 +1,5 @@
 import type { CliCommandDef } from "../../types/plugin";
-import type { TimeRange } from "../../time-series/range";
+import { TIME_RANGES, type TimeRange } from "../../time-series/range";
 import type { EarningsEvent, QuoteBatchResult, SecFilingItem } from "../../types/data-provider";
 import type { NewsArticle, NewsFeed, NewsQuery } from "../../news/types";
 import type {
@@ -15,7 +15,7 @@ import { formatCompact } from "../../utils/format";
 import { withCliServices, withMarketData } from "../context";
 import { isoDate, parsePositiveInt, requireArg, takeOption } from "./command-utils";
 
-const VALID_RANGES = new Set<TimeRange>(["1D", "1W", "1M", "3M", "6M", "1Y", "5Y", "ALL"]);
+const VALID_RANGES = new Set<TimeRange>(TIME_RANGES);
 const VALID_NEWS_FEEDS = new Set<NewsFeed>(["latest", "top", "breaking", "ticker", "sector", "topic"]);
 
 type QuoteCliRecord = Omit<QuoteBatchResult, "error"> & { error: string | null };

package/src/cli/commands/plugins.ts

@@ -2,6 +2,7 @@ import { join } from "path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "fs";
 import { execFileSync } from "child_process";
 import { getPluginsDir } from "../../plugins/loader";
+import { linkHostPackages } from "../../plugins/host-link";
 import {
   cliStyles,
   renderSection,
@@ -50,7 +51,20 @@ function parseGitHubRef(rawRef: string): { url: string; name: string } {
   throw new Error(`Invalid plugin reference: ${ref}. Use user/repo or a GitHub URL.`);
 }
 
-export async function installPlugin(ref: string) {
+export interface InstallPluginOptions {
+  /**
+   * Suppress child-process output and progress logging. The marketplace pane
+   * installs while the terminal UI owns the screen, and git and bun writing to
+   * stdout corrupts the rendered frame.
+   */
+  quiet?: boolean;
+}
+
+export async function installPlugin(ref: string, options: InstallPluginOptions = {}) {
+  const stdio = options.quiet ? "pipe" : "inherit";
+  const say = (message: string) => {
+    if (!options.quiet) console.log(message);
+  };
   ensurePluginsDir();
   const { url, name } = parseGitHubRef(ref);
   const targetDir = join(PLUGINS_DIR, name);
@@ -59,11 +73,11 @@ export async function installPlugin(ref: string) {
     fail(`Plugin "${name}" already exists.`, `Use "gloomberb update ${name}" to refresh it.`);
   }
 
-  console.log(cliStyles.accent(`Installing ${name}`));
-  console.log(cliStyles.muted(url));
+  say(cliStyles.accent(`Installing ${name}`));
+  say(cliStyles.muted(url));
 
   try {
-    execFileSync("git", ["clone", "--depth", "1", url, targetDir], { stdio: "inherit" });
+    execFileSync("git", ["clone", "--depth", "1", url, targetDir], { stdio });
   } catch {
     rmSync(targetDir, { recursive: true, force: true });
     fail(`Failed to clone ${url}.`);
@@ -71,11 +85,24 @@ export async function installPlugin(ref: string) {
 
   const pkgPath = join(targetDir, "package.json");
   if (existsSync(pkgPath)) {
-    console.log(cliStyles.muted("Installing plugin dependencies..."));
+    say(cliStyles.muted("Installing plugin dependencies..."));
     try {
-      execFileSync("bun", ["install"], { cwd: targetDir, stdio: "inherit" });
+      // --production: plugin repos depend on `gloomberb` as a devDependency so
+      // their own CI can typecheck against the real API. At runtime the host is
+      // symlinked in instead, and pulling a second full copy here would both
+      // waste a lot of disk and risk a duplicate React.
+      execFileSync("bun", ["install", "--production"], { cwd: targetDir, stdio });
     } catch {
-      console.error(cliStyles.warning("Warning: failed to install plugin dependencies."));
+      if (!options.quiet) console.error(cliStyles.warning("Warning: failed to install plugin dependencies."));
+    }
+  }
+
+  // After `bun install`, which prunes links it does not know about.
+  const link = linkHostPackages(targetDir);
+  if (link.error) {
+    if (!options.quiet) {
+      console.error(cliStyles.warning(`Warning: could not link the Gloomberb runtime (${link.error}).`));
+      console.error(cliStyles.muted("The plugin's \"gloomberb/*\" imports will not resolve."));
     }
   }
 
@@ -98,13 +125,13 @@ export async function installPlugin(ref: string) {
       const mod = await import(entryFile);
       const plugin = mod.default ?? mod.plugin;
       if (plugin?.id && plugin?.name) {
-        console.log(cliStyles.success(`Installed ${plugin.name} v${plugin.version || "0.0.0"}`));
+        say(cliStyles.success(`Installed ${plugin.name} v${plugin.version || "0.0.0"}`));
         return;
       }
     }
-    console.log(cliStyles.warning("Installed files, but no valid GloomPlugin export was found."));
+    say(cliStyles.warning("Installed files, but no valid GloomPlugin export was found."));
   } catch (err) {
-    console.log(cliStyles.warning(`Plugin validation failed: ${err}`));
+    say(cliStyles.warning(`Plugin validation failed: ${err}`));
   }
 }
 
@@ -141,8 +168,9 @@ export async function updatePlugins(name?: string) {
       execFileSync("git", ["pull", "--ff-only"], { cwd: targetDir, stdio: "inherit" });
       const pkgPath = join(targetDir, "package.json");
       if (existsSync(pkgPath)) {
-        execFileSync("bun", ["install"], { cwd: targetDir, stdio: "inherit" });
+        execFileSync("bun", ["install", "--production"], { cwd: targetDir, stdio: "inherit" });
       }
+      linkHostPackages(targetDir);
     } catch {
       console.error(cliStyles.danger(`Failed to update ${dir}.`));
     }

package/src/cli/desktop-pane-shot.ts

@@ -1,7 +1,6 @@
 import { mkdir, mkdtemp, rm, writeFile } from "fs/promises";
 import { tmpdir } from "os";
-import { join } from "path";
-import { pathToFileURL } from "url";
+import { join, resolve, sep } from "path";
 import type { AppConfig } from "../types/config";
 import type { ResolvedSeries } from "../time-series/types";
 import type { OptionsChain, TickerFinancials } from "../types/financials";
@@ -9,6 +8,7 @@ import type { TickerRecord } from "../types/ticker";
 import type { PaneRuntimeState } from "../core/state/app/state";
 import type { RemoteUiNodeSnapshot } from "../remote/types";
 import type { FredSeriesCacheEntry } from "../data/fred-series";
+import type { DatedObservation } from "../plugins/builtin/market-valuation/series";
 import {
   electrobunViewPath,
   writeElectrobunViewPage,
@@ -21,16 +21,46 @@ export interface DesktopPaneShotPayload {
   heightCells: number;
   widthPx: number;
   heightPx: number;
+  /** Chrome device scale factor; 2 keeps text crisp, higher values zoom the layout. */
+  deviceScaleFactor?: number;
+  /** Label drawn at the right edge of the pane title bar; null draws nothing. */
+  watermark?: string | null;
   tickers: TickerRecord[];
   financials: Array<[string, TickerFinancials]>;
   optionsChains: Array<[string, OptionsChain]>;
   fredSeries: Array<[string, FredSeriesCacheEntry]>;
+  valuationSeries: Array<[string, DatedObservation[]]>;
+  statSeries: Array<[string, DatedObservation[]]>;
   capabilitySeries: Array<[string, ResolvedSeries]>;
   paneState: Record<string, PaneRuntimeState>;
 }
 
+/** Kept in Bun memory and never serialized into the browser page or CLI result. */
+export interface DesktopPaneShotApiProxy {
+  baseUrl: string;
+  sessionToken: string | null;
+}
+
+export interface DesktopPaneShotRenderedCell {
+  columnId?: string;
+  columnLabel: string;
+  text: string;
+}
+
+export interface DesktopPaneShotRenderedRow {
+  tableIndex: number;
+  rowIndex: number;
+  key?: string;
+  selected: boolean;
+  cells: DesktopPaneShotRenderedCell[];
+}
+
 export interface DesktopPaneShotRenderResult {
   visibleText: string;
+  rows: DesktopPaneShotRenderedRow[];
+  loadingStateDetected: boolean;
+  errorStateDetected: boolean;
+  errorStateMarkers: string[];
   emptyStateDetected: boolean;
   emptyStateMarkers: string[];
   semanticUi: RemoteUiNodeSnapshot[];
@@ -47,30 +77,47 @@ type PendingCdpCall = {
   reject: (error: Error) => void;
 };
 
+const SHOT_MODE_CSS = [
+  "[data-gloom-role='composite-chart-toolbar']",
+  "[data-gloom-role='chart-series-quick-add']",
+  "[data-gloom-role='pane-close']",
+].join(", ") + " { display: none !important; }\n"
+  // Sits where the hidden close button was: one cell high, right-aligned in the title bar.
+  + "[data-gloom-role='shot-watermark'] { position: fixed; top: 1px; right: 10px; height: var(--cell-h);"
+  + " line-height: var(--cell-h); font-size: 12px; letter-spacing: 0.02em; color: var(--gloom-text-dim, #888);"
+  + " pointer-events: none; z-index: 1000; }";
+
 const CHROME_POLL_ATTEMPTS = 80;
-const SHOT_READY_TIMEOUT_MS = 10_000;
+const SHOT_READY_TIMEOUT_MS = 45_000;
 const CDP_CALL_TIMEOUT_MS = 10_000;
-const SHOT_DEVICE_SCALE_FACTOR = 2;
+const DEFAULT_DEVICE_SCALE_FACTOR = 2;
+const SHOT_API_PROXY_PREFIX = "/__gloom_cli_api__";
+const SESSION_COOKIE_NAMES = ["__Secure-gloomberb.session_token", "gloomberb.session_token"] as const;
 
 export async function renderDesktopPaneScreenshot(
   payload: DesktopPaneShotPayload,
   outputPath: string,
+  apiProxy: DesktopPaneShotApiProxy,
 ): Promise<DesktopPaneShotRenderResult> {
   const tempDir = await mkdtemp(join(tmpdir(), "gloom-pane-shot-"));
+  let server: ReturnType<typeof Bun.serve> | null = null;
   try {
     const outdir = join(tempDir, "assets");
     await mkdir(outdir, { recursive: true });
-    const htmlPath = await buildShotPage(outdir, payload);
+    await buildShotPage(outdir, payload);
+    server = serveShotPage(outdir, apiProxy);
     const chrome = await findChromeExecutable();
     return await capturePageScreenshot({
       chrome,
-      url: pathToFileURL(htmlPath).href,
+      url: new URL("/", server.url).href,
       outputPath,
       widthPx: payload.widthPx,
       heightPx: payload.heightPx,
+      deviceScaleFactor: payload.deviceScaleFactor ?? DEFAULT_DEVICE_SCALE_FACTOR,
       userDataDir: join(tempDir, "chrome-profile"),
     });
   } finally {
+    server?.stop(true);
     await rm(tempDir, { recursive: true, force: true });
   }
 }
@@ -90,6 +137,20 @@ async function buildShotPage(outdir: string, payload: DesktopPaneShotPayload): P
     loadingText: "Rendering pane...",
     bootstrapScript: `
       window.__GLOOM_CLI_SHOT_PAYLOAD__ = ${payloadJson};
+      (() => {
+        // A screenshot cannot be interacted with, so drawing tools, the
+        // quick-add input and the close button only add noise to the image.
+        const style = document.createElement("style");
+        style.textContent = ${JSON.stringify(SHOT_MODE_CSS)};
+        document.head.appendChild(style);
+        const watermark = ${JSON.stringify(payload.watermark ?? null)};
+        if (watermark) {
+          const mark = document.createElement("div");
+          mark.setAttribute("data-gloom-role", "shot-watermark");
+          mark.textContent = watermark;
+          document.addEventListener("DOMContentLoaded", () => document.body.appendChild(mark));
+        }
+      })();
       window.addEventListener("error", (event) => {
         window.__GLOOM_CLI_SHOT_ERROR__ = event.error && event.error.stack ? event.error.stack : String(event.error || event.message);
       });
@@ -100,6 +161,116 @@ async function buildShotPage(outdir: string, payload: DesktopPaneShotPayload): P
   });
 }
 
+function serveShotPage(
+  outdir: string,
+  apiProxy: DesktopPaneShotApiProxy,
+): ReturnType<typeof Bun.serve> {
+  const staticRoot = resolve(outdir);
+  return Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    idleTimeout: 60,
+    fetch(request) {
+      const url = new URL(request.url);
+      if (url.pathname.startsWith(`${SHOT_API_PROXY_PREFIX}/`)) {
+        return proxyShotApiRequest(request, url, apiProxy);
+      }
+      return serveShotAsset(url, staticRoot);
+    },
+  });
+}
+
+async function serveShotAsset(url: URL, staticRoot: string): Promise<Response> {
+  let pathname: string;
+  try {
+    pathname = decodeURIComponent(url.pathname);
+  } catch {
+    return new Response("Bad request", { status: 400 });
+  }
+  const relativePath = pathname === "/" ? "index.html" : pathname.replace(/^\/+/, "");
+  const filePath = resolve(staticRoot, relativePath);
+  if (filePath !== staticRoot && !filePath.startsWith(`${staticRoot}${sep}`)) {
+    return new Response("Not found", { status: 404 });
+  }
+  const file = Bun.file(filePath);
+  if (!(await file.exists())) return new Response("Not found", { status: 404 });
+  return new Response(file);
+}
+
+async function proxyShotApiRequest(
+  request: Request,
+  requestUrl: URL,
+  apiProxy: DesktopPaneShotApiProxy,
+): Promise<Response> {
+  const baseUrl = new URL(apiProxy.baseUrl);
+  const proxiedPath = requestUrl.pathname.slice(SHOT_API_PROXY_PREFIX.length) || "/";
+  const target = new URL(baseUrl);
+  const basePath = baseUrl.pathname.replace(/\/+$/, "");
+  target.pathname = `${basePath}${proxiedPath.startsWith("/") ? proxiedPath : `/${proxiedPath}`}`;
+  target.search = requestUrl.search;
+  target.hash = "";
+  const headers = new Headers(request.headers);
+  for (const name of [
+    "authorization",
+    "connection",
+    "content-length",
+    "cookie",
+    "host",
+    "origin",
+    "proxy-authorization",
+    "referer",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "x-forwarded-for",
+    "x-forwarded-host",
+    "x-forwarded-proto",
+  ]) {
+    headers.delete(name);
+  }
+  const browserOwnedHeaders: string[] = [];
+  headers.forEach((_value, name) => {
+    if (name.startsWith("sec-") || name === "accept-encoding") browserOwnedHeaders.push(name);
+  });
+  for (const name of browserOwnedHeaders) headers.delete(name);
+  headers.set("Origin", baseUrl.origin);
+  if (apiProxy.sessionToken) {
+    headers.set(
+      "Cookie",
+      SESSION_COOKIE_NAMES.map((name) => `${name}=${apiProxy.sessionToken}`).join("; "),
+    );
+  }
+
+  try {
+    const response = await fetch(target, {
+      method: request.method,
+      headers,
+      body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
+      redirect: "follow",
+    });
+    const responseHeaders = new Headers(response.headers);
+    for (const name of [
+      "access-control-allow-credentials",
+      "access-control-allow-origin",
+      "content-encoding",
+      "content-length",
+      "set-cookie",
+      "transfer-encoding",
+    ]) {
+      responseHeaders.delete(name);
+    }
+    responseHeaders.set("Cache-Control", "no-store");
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: responseHeaders,
+    });
+  } catch {
+    return Response.json({ error: "Cloud API request failed." }, { status: 502 });
+  }
+}
+
 async function findChromeExecutable(): Promise<string> {
   const candidates = [
     process.env.CHROME_PATH,
@@ -123,6 +294,7 @@ async function capturePageScreenshot({
   outputPath,
   widthPx,
   heightPx,
+  deviceScaleFactor,
   userDataDir,
 }: {
   chrome: string;
@@ -130,6 +302,7 @@ async function capturePageScreenshot({
   outputPath: string;
   widthPx: number;
   heightPx: number;
+  deviceScaleFactor: number;
   userDataDir: string;
 }): Promise<DesktopPaneShotRenderResult> {
   await mkdir(userDataDir, { recursive: true });
@@ -166,7 +339,7 @@ async function capturePageScreenshot({
     await session.send("Emulation.setDeviceMetricsOverride", {
       width: widthPx,
       height: heightPx,
-      deviceScaleFactor: SHOT_DEVICE_SCALE_FACTOR,
+      deviceScaleFactor,
       mobile: false,
     });
     await waitForShotReady(session);
@@ -189,6 +362,21 @@ async function capturePageScreenshot({
   }
 }
 
+const LOADING_STATE_PATTERNS = [
+  /\bLoading(?: [^.]{0,80})?\.{3}/gi,
+  /\bRendering pane\.{3}/gi,
+];
+
+const ERROR_STATE_PATTERNS = [
+  /\b[^.]{1,100} unavailable\./gi,
+  /\bFailed to fetch\b/gi,
+  /\bCould not load\b/gi,
+  /\bSign in to\b/gi,
+  /\bVerify your email\b/gi,
+  /\bpart of Gloom Cloud Pro\b/gi,
+  /\bCloud API request failed\b/gi,
+];
+
 const EMPTY_STATE_PATTERNS = [
   /\bNo chart data\b/gi,
   /\bNo graph data\b/gi,
@@ -197,21 +385,94 @@ const EMPTY_STATE_PATTERNS = [
   /\bNo comparison tickers configured\b/gi,
   /\bNo relationship tickers configured\b/gi,
   /\bNo overlapping price history\b/gi,
-  /\bLoading chart\.{0,3}\b/gi,
-  /\bRendering pane\.{0,3}\b/gi,
-  /\bNo tickers selected\b/gi,
-  /\bMarket data unavailable\b/gi,
+  /\bNo tickers? selected\b/gi,
   /\bNo data(?: available)?\b/gi,
+  /\bNothing to show yet\b/gi,
+  /\bNo transcribed calls(?: for [^.]+)? yet\b/gi,
+  /\bNo short interest (?:data|found)\b/gi,
+  /\bNo (?:House PTR |insider )?(?:trades|members|transactions|filings)\b/gi,
 ];
 
+function stateMarkers(text: string, patterns: RegExp[]): string[] {
+  return [...new Set(patterns.flatMap((pattern) => (
+    [...text.matchAll(pattern)].map((match) => match[0])
+  )))];
+}
+
 async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneShotRenderResult> {
   const result = await session.send("Runtime.evaluate", {
     expression: `(() => {
       const root = document.getElementById("root") || document.body;
+      const semanticUi = window.__GLOOM_CLI_SHOT_SEMANTIC_UI__ || [];
+      const normalize = (value) => String(value || "").replace(/\\s+/g, " ").trim();
+      const isVisible = (element) => {
+        if (!(element instanceof HTMLElement)) return false;
+        const style = getComputedStyle(element);
+        if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") return false;
+        const rect = element.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0
+          && rect.right > 0 && rect.bottom > 0
+          && rect.left < window.innerWidth && rect.top < window.innerHeight;
+      };
+      const semanticTables = semanticUi.filter((node) => node && node.role === "table");
+      const rows = [];
+      [...root.querySelectorAll('[data-gloom-role="data-table"]')]
+        .filter(isVisible)
+        .forEach((table, tableIndex) => {
+          const tableMetadata = semanticTables[tableIndex] && semanticTables[tableIndex].metadata || {};
+          const semanticColumns = Array.isArray(tableMetadata.columns) ? tableMetadata.columns : [];
+          const semanticRows = Array.isArray(tableMetadata.rows) ? tableMetadata.rows : [];
+          const headers = [...table.querySelectorAll('[data-gloom-role="data-table-header-cell"]')]
+            .map((cell) => normalize(cell.innerText || cell.textContent));
+          const rowElements = [...table.querySelectorAll(
+            '[data-gloom-role="data-table-row"], [data-gloom-role="data-table-section-header"]',
+          )].filter(isVisible);
+          rowElements.forEach((row, rowIndex) => {
+            const cellElements = [...row.querySelectorAll('[data-gloom-role="data-table-cell"]')];
+            const values = cellElements.length > 0 ? cellElements : [row];
+            const semanticRow = semanticRows[rowIndex] || {};
+            const cells = values.map((cell, cellIndex) => {
+              const semanticColumn = semanticColumns[cellIndex] || {};
+              return {
+                ...(typeof semanticColumn.id === "string" ? { columnId: semanticColumn.id } : {}),
+                columnLabel: typeof semanticColumn.label === "string"
+                  ? semanticColumn.label
+                  : headers[cellIndex] || (values.length === 1 ? "Row" : String(cellIndex + 1)),
+                text: normalize(cell.innerText || cell.textContent),
+              };
+            }).filter((cell) => cell.text.length > 0);
+            if (cells.length === 0) return;
+            rows.push({
+              tableIndex,
+              rowIndex,
+              ...(typeof semanticRow.key === "string" ? { key: semanticRow.key } : {}),
+              selected: row.getAttribute("data-selected") === "true" || semanticRow.selected === true,
+              cells,
+            });
+          });
+        });
+      if (rows.length === 0) {
+        [...root.querySelectorAll('[data-gloom-role="desktop-list-row"]')]
+          .filter(isVisible)
+          .forEach((row, rowIndex) => {
+            const text = normalize(row.innerText || row.textContent);
+            if (!text) return;
+            rows.push({
+              tableIndex: 0,
+              rowIndex,
+              selected: row.getAttribute("data-selected") === "true",
+              cells: [{ columnLabel: "Row", text }],
+            });
+          });
+      }
       return {
         visibleText: root.innerText || root.textContent || "",
         error: window.__GLOOM_CLI_SHOT_ERROR__ || "",
-        semanticUi: window.__GLOOM_CLI_SHOT_SEMANTIC_UI__ || [],
+        loadingStateDetected: root.querySelector('[data-gloom-status="loading"]') !== null,
+        errorStateDetected: root.querySelector('[data-gloom-status="error"]') !== null,
+        emptyStateDetected: root.querySelector('[data-gloom-status="empty"]') !== null,
+        rows,
+        semanticUi,
       };
     })()`,
     returnByValue: true,
@@ -220,6 +481,10 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
       value?: {
         visibleText?: string;
         error?: string;
+        loadingStateDetected?: boolean;
+        errorStateDetected?: boolean;
+        emptyStateDetected?: boolean;
+        rows?: DesktopPaneShotRenderedRow[];
         semanticUi?: RemoteUiNodeSnapshot[];
       };
     };
@@ -227,12 +492,16 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
   const value = result.result?.value;
   if (value?.error) throw new Error(value.error);
   const visibleText = (value?.visibleText ?? "").replace(/\s+/g, " ").trim();
-  const emptyStateMarkers = [...new Set(EMPTY_STATE_PATTERNS.flatMap((pattern) => (
-    [...visibleText.matchAll(pattern)].map((match) => match[0])
-  )))];
+  const loadingStateMarkers = stateMarkers(visibleText, LOADING_STATE_PATTERNS);
+  const errorStateMarkers = stateMarkers(visibleText, ERROR_STATE_PATTERNS);
+  const emptyStateMarkers = stateMarkers(visibleText, EMPTY_STATE_PATTERNS);
   return {
     visibleText,
-    emptyStateDetected: emptyStateMarkers.length > 0,
+    rows: Array.isArray(value?.rows) ? value.rows : [],
+    loadingStateDetected: value?.loadingStateDetected === true || loadingStateMarkers.length > 0,
+    errorStateDetected: value?.errorStateDetected === true || errorStateMarkers.length > 0,
+    errorStateMarkers,
+    emptyStateDetected: value?.emptyStateDetected === true || emptyStateMarkers.length > 0,
     emptyStateMarkers,
     semanticUi: Array.isArray(value?.semanticUi) ? value.semanticUi : [],
   };

package/src/cli/index.ts

@@ -121,7 +121,7 @@ function createCoreCliCommands(
       aliases: ["screenshot"],
       description: "Render a desktop-style screenshot for a pane-backed market function",
       help: {
-        usage: ["shot <function-or-pane> [argument] [--output path] [--width px] [--height px] [--key value]"],
+        usage: ["shot <function-or-pane> [argument] [--output path] [--width px] [--height px] [--theme id] [--scale n] [--watermark text] [--key value]"],
       },
       execute: async (args, ctx) => {
         await runPaneScreenshot(args, ctx);