gloomberb 0.18.4 → 0.18.5

package/README.md

@@ -53,7 +53,7 @@ With [Bun](https://bun.sh), on any supported OS:
 bun install -g gloomberb
 ```
 
-Then run `gloom`. The command was called `gloomberb` before 0.19, and that name still works. For chart graphics, use a Kitty-compatible terminal such as Ghostty, Kitty, or WezTerm. Windows Terminal draws charts as text; the desktop app draws them in full.
+Then run `gloom`. The command was called `gloomberb` before 0.18.4, and that name still works. For chart graphics, use a Kitty-compatible terminal such as Ghostty, Kitty, or WezTerm. Windows Terminal draws charts as text; the desktop app draws them in full.
 
 ## Start
 

package/README.zh-CN.md

@@ -65,7 +65,7 @@ curl -fsSL gloom.sh/install | bash
 bun install -g gloomberb
 ```
 
-运行 `gloom` 即可启动。0.19 之前命令名为 `gloomberb`，该名称仍可使用。要显示图形，请使用兼容 Kitty 图形协议的终端，例如 Ghostty、Kitty 或 WezTerm。直接下载、安装位置与更新方式详见[安装指南（英文）](docs/installation.md)。
+运行 `gloom` 即可启动。0.18.4 之前命令名为 `gloomberb`，该名称仍可使用。要显示图形，请使用兼容 Kitty 图形协议的终端，例如 Ghostty、Kitty 或 WezTerm。直接下载、安装位置与更新方式详见[安装指南（英文）](docs/installation.md)。
 
 ## 开始使用
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gloomberb",
-  "version": "0.18.4",
+  "version": "0.18.5",
   "packageManager": "bun@1.3.11",
   "description": "Market research and portfolio tracker for the terminal",
   "module": "src/public/index.ts",

package/patches/electrobun@1.18.1.patch

@@ -74,7 +74,7 @@ index cdaa2bca0fabe577cb667056aa6f8f84211189c2..3839e5232742c2467180c344f51a30f1
  
  // Encrypt function
 diff --git a/dist/api/bun/core/Updater.ts b/dist/api/bun/core/Updater.ts
-index 39daf6d341780af8e30c2c50327162863f5977ec..0174d2ce1a9a4fa8ae0fd97367293fc5a794286a 100644
+index 39daf6d341780af8e30c2c50327162863f5977ec..65677cd1d642ef832cf4f90a315d3ffc977909a3 100644
 --- a/dist/api/bun/core/Updater.ts
 +++ b/dist/api/bun/core/Updater.ts
 @@ -132,6 +132,19 @@ let updateInfo: {
@@ -254,6 +254,37 @@ index 39daf6d341780af8e30c2c50327162863f5977ec..0174d2ce1a9a4fa8ae0fd97367293fc5
  
  						// Ensure launcher binary is executable
  						const launcherPath = join(appBundleDir, "bin", "launcher");
+@@ -1071,14 +1129,18 @@ del "%~f0"
+ 					// current process has exited first. The detached shell survives our
+ 					// exit and polls until the process is gone.
+ 					const pid = process.pid;
++					// The shell, sleep and open by their full paths, from /: a terminal
++					// launch can hand the app a PATH without them, and a spawn into a
++					// folder that is gone fails as if the shell were missing.
+ 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ 					Bun.spawn(
+ 						[
+-							"sh",
++							"/bin/sh",
+ 							"-c",
+-							`while kill -0 ${pid} 2>/dev/null; do sleep 0.5; done; sleep 1; open "${runningAppBundlePath}"`,
++							`while kill -0 ${pid} 2>/dev/null; do /bin/sleep 0.5; done; /bin/sleep 1; /usr/bin/open "${runningAppBundlePath}"`,
+ 						],
+ 						{
++							cwd: "/",
+ 							detached: true,
+ 							stdio: ["ignore", "ignore", "ignore"],
+ 						} as any,
+@@ -1087,7 +1149,8 @@ del "%~f0"
+ 					// On Linux, launch the launcher binary inside the app directory
+ 					const launcherPath = join(runningAppBundlePath, "bin", "launcher");
+ 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+-					Bun.spawn(["sh", "-c", `"${launcherPath}" &`], {
++					Bun.spawn(["/bin/sh", "-c", `"${launcherPath}" &`], {
++						cwd: "/",
+ 						detached: true,
+ 					} as any);
+ 				}
 diff --git a/dist/api/bun/preload/.generated/compiled.ts b/dist/api/bun/preload/.generated/compiled.ts
 index 3ab1d7d8de8938ae60823650fd3a29b952a76cb6..e0e841e6a87ce41533c6bdda8d29400aaf478e31 100644
 --- a/dist/api/bun/preload/.generated/compiled.ts

package/src/account/auth-model.ts

@@ -125,13 +125,17 @@ export async function performEmailAuth(mode: AccountMode, email: string, passwor
   } else {
     user = await apiClient.signIn(email, password);
   }
-  if (!user.emailVerified) {
-    await apiClient.sendVerification().catch(logFailure("account-auth", "Verification email request failed"));
-  }
+  if (apiClient.getCurrentUser()?.id !== user.id) throw new Error("Another sign-in replaced this request.");
   const sessionToken = apiClient.getSessionToken();
   if (sessionToken) {
     chatController.adoptSession(sessionToken, user);
   }
+  if (!user.emailVerified) {
+    await apiClient.sendVerification().catch(logFailure("account-auth", "Verification email request failed"));
+  }
+  if (apiClient.getSessionToken() !== sessionToken || apiClient.getCurrentUser()?.id !== user.id) {
+    throw new Error("Another sign-in replaced this request.");
+  }
   identifyResearchUser();
   await chatController.refreshSession().catch(logFailure("account-auth", "Session refresh after email authentication failed"));
   return user;

package/src/api-client/auth.ts

@@ -74,6 +74,7 @@ export class CloudAuthApi {
     username: string,
     name: string,
     password: string,
+    isCurrent: () => boolean = () => true,
   ): Promise<AuthUser> {
     const result = await this.options.request<{ user: AuthUser }>(
       "/auth/sign-up/email",
@@ -81,7 +82,9 @@ export class CloudAuthApi {
         method: "POST",
         body: JSON.stringify({ email, username, name, password }),
       },
+      isCurrent,
     );
+    if (!isCurrent()) throw new Error("Another sign-in replaced this request.");
     this.options.requireCapturedSession(
       "Account created, but Gloom could not save the login session. Please try logging in again.",
     );
@@ -89,14 +92,16 @@ export class CloudAuthApi {
     return result.user;
   }
 
-  async signIn(email: string, password: string): Promise<AuthUser> {
+  async signIn(email: string, password: string, isCurrent: () => boolean = () => true): Promise<AuthUser> {
     const result = await this.options.request<{ user: AuthUser }>(
       "/auth/sign-in/email",
       {
         method: "POST",
         body: JSON.stringify({ email, password }),
       },
+      isCurrent,
     );
+    if (!isCurrent()) throw new Error("Another sign-in replaced this request.");
     this.options.requireCapturedSession(
       "Logged in, but Gloom could not save the login session. Please try again.",
     );
@@ -127,11 +132,11 @@ export class CloudAuthApi {
     });
   }
 
-  async signOut(): Promise<void> {
+  async signOut(isCurrent: () => boolean = () => true): Promise<void> {
     try {
-      await this.options.request("/auth/sign-out", { method: "POST" });
+      await this.options.request("/auth/sign-out", { method: "POST" }, isCurrent);
     } finally {
-      this.options.setSessionToken(null);
+      if (isCurrent()) this.options.setSessionToken(null);
     }
   }
 

package/src/api-client/catalysts.ts

@@ -1,6 +1,7 @@
 type QuoteMatchMode = "exact" | "whitespace" | "normalized"
 
-export const CATALYST_TYPES = ["regulatory", "clinical", "litigation", "antitrust", "recall", "sanctions", "export_control", "tariff", "rulemaking", "approval", "advisory", "pdufa"] as const
+/** Regulator events, then the ones a company or its exchange dates itself (results, meetings, deals). */
+export const CATALYST_TYPES = ["regulatory", "clinical", "litigation", "antitrust", "recall", "sanctions", "export_control", "tariff", "rulemaking", "approval", "advisory", "pdufa", "results", "shareholder_meeting", "merger_vote", "deal_closing", "investor_day"] as const
 export type CatalystType = (typeof CATALYST_TYPES)[number]
 type DatePrecision = "day" | "month" | "year"
 interface CatalystIdentifiers {

package/src/api-client/data.ts

@@ -51,6 +51,7 @@ import type { CarbonBoard, CarbonHistory, EuropePowerBoard, EuropePowerHistory,
 import type { GpuBoardPayload, GpuEventsPayload, GpuHistoryPayload, GpuHistoryQuery } from "./gpu";
 import type { CpiBoardPayload } from "./cpi";
 import type { TapeRange, TapeSnapshot } from "./tape";
+import { LIVE_SCAN_PATH, type LiveScanPayload, type LiveScanWireDefinition } from "./live-scan";
 import { signalWithTimeout } from "../utils/async-deadline";
 import { ApiRequestError } from "./errors";
 import type { ExchangeRateSnapshot } from "../types/exchange-rate";
@@ -253,6 +254,10 @@ export class CloudDataApi {
     return this.request<import("./fund-facts").FundFactsPayload>(`/cloud/fund-facts/${encodeURIComponent(ticker)}`, options.signal ? { signal: options.signal } : undefined);
   }
 
+  getFundBreadth(fund: string) {
+    return this.request<import("./members").FundBreadthPayload>(`/cloud/members/${encodeURIComponent(fund)}/breadth`);
+  }
+
   getFundChanges(fund: string) {
     return this.request<import("./members").FundChangesPayload>(`/cloud/members/${encodeURIComponent(fund)}/changes`);
   }
@@ -897,6 +902,15 @@ export class CloudDataApi {
     return this.request<CentralBankRatesPayload>("/cloud/econ/central-bank-rates", { signal: AbortSignal.timeout(45_000) });
   }
 
+  /** A live scan's matches against Gloom Cloud's newest market-wide snapshot for this account's tier. */
+  getLiveScan(definition: LiveScanWireDefinition, signal?: AbortSignal) {
+    return this.request<LiveScanPayload>(LIVE_SCAN_PATH, {
+      method: "POST",
+      body: JSON.stringify({ scan: definition }),
+      signal: signalWithTimeout(signal, 20_000),
+    });
+  }
+
   /** Recorded FLOW prints older than the live tape (Pro); the plugin builds `search`. */
   getScannerFlowHistory(search: string, signal?: AbortSignal) {
     return this.request<ScannerFlowHistoryPage>(`/market/scanner/flow/history?${search}`, { signal });

package/src/api-client/index.ts

@@ -67,6 +67,8 @@ export const ASSIST_ARG_OPTION_LIMIT = 128;
 const ASSIST_ARG_OPTION_VALUE_MAX_LENGTH = 40;
 const ASSIST_ARG_OPTION_LABEL_MAX_LENGTH = 60;
 const ASSIST_REQUEST_TIMEOUT_MS = 6_000;
+const SESSION_REVALIDATION_INITIAL_MS = 1_000;
+const SESSION_REVALIDATION_MAX_MS = 30_000;
 
 /**
  * Fits a command's argument values inside the server caps. The value is what
@@ -94,8 +96,15 @@ interface PendingSessionRequest {
 
 class GloomApiClient {
   private currentUser: AuthUser | null = null;
-  /** Local identity of a verified user/credential pair, never serialized. */
+  /** Local user/credential binding, masked until verified and never serialized. */
   private verifiedSessionIdentity: object | null = null;
+  private verifiedSessionCredential: string | null = null;
+  private sessionTransitions = 0;
+  private sessionTransition: Promise<void> | null = null;
+  /** Device adoption and external session installs supersede pending email auth. */
+  private sessionInstallationGeneration = 0;
+  private sessionRevalidationGeneration = 0;
+  private sessionRevalidationTimer: ReturnType<typeof setTimeout> | null = null;
   private sessionChecked = false;
   /** Last few session transitions, content-free, for app://auth. */
   private authTrace: Array<{ at: number; event: string; token: boolean; user: string }> = [];
@@ -110,7 +119,7 @@ class GloomApiClient {
     request: (path, options, canApplySession) => this.request(path, options, canApplySession),
     requireCapturedSession: (message) => this.requireCapturedSession(message),
     setCurrentUser: (user) => this.setCurrentUser(user),
-    setSessionToken: (token) => this.setSessionToken(token),
+    setSessionToken: (token) => this.installSessionToken(token),
     updateCurrentUser: (updater) => this.updateCurrentUser(updater),
   });
   private readonly socket: CloudApiSocket = new CloudApiSocket({
@@ -123,7 +132,6 @@ class GloomApiClient {
     markCurrentUserUnverified: () => {
       if (this.currentUser) {
         this.currentUser = { ...this.currentUser, emailVerified: false };
-        this.verifiedSessionIdentity = null;
         this.emitCurrentUserChange();
       }
     },
@@ -165,6 +173,8 @@ class GloomApiClient {
   }
 
   setCookieSessionMode(enabled: boolean): void {
+    this.cancelSessionRevalidation();
+    this.sessionInstallationGeneration += 1;
     this.sessionChecked = false;
     this.verifiedSessionIdentity = null;
     this.transport.setCookieSessionMode(enabled);
@@ -172,12 +182,21 @@ class GloomApiClient {
   }
 
   setSessionToken(token: string | null): void {
+    if (this.transport.getSessionToken() !== token || !token) {
+      this.cancelSessionRevalidation();
+      this.sessionInstallationGeneration += 1;
+    }
+    this.installSessionToken(token);
+  }
+
+  private installSessionToken(token: string | null): void {
     const changed = this.transport.getSessionToken() !== token;
     this.sessionChecked = false;
     this.transport.setSessionToken(token);
     if (changed) this.verifiedSessionIdentity = null;
     this.traceAuth(changed ? "setSessionToken:changed" : "setSessionToken:same");
     if (!token) {
+      this.cancelSessionRevalidation();
       this.currentUser = null;
       this.verifiedSessionIdentity = null;
     }
@@ -224,7 +243,9 @@ class GloomApiClient {
 
   /** Null while a replacement credential still awaits its matching user. */
   getVerifiedSessionIdentity(): object | null {
-    return this.isVerified() ? this.verifiedSessionIdentity : null;
+    return this.sessionTransitions === 0 && this.isVerified()
+      && this.verifiedSessionCredential === this.transport.getSessionToken()
+      ? this.verifiedSessionIdentity : null;
   }
 
   /**
@@ -276,11 +297,18 @@ class GloomApiClient {
     if (this.authTrace.length > 24) this.authTrace.shift();
   }
 
-  private setCurrentUser(user: AuthUser | null): void {
+  private setCurrentUser(user: AuthUser | null, confirmSession = true): void {
+    const sameAccount = this.currentUser?.id === user?.id;
     const changed = this.socketEntitlementKey(this.currentUser) !== this.socketEntitlementKey(user);
     this.traceAuth("setCurrentUser", user);
     this.currentUser = user;
-    this.verifiedSessionIdentity = this.isVerified() ? {} : null;
+    if (confirmSession) {
+      this.clearSessionRevalidationTimer();
+      this.verifiedSessionIdentity = user ? {} : null;
+      this.verifiedSessionCredential = this.transport.getSessionToken();
+    } else if (!sameAccount || !user) {
+      this.verifiedSessionIdentity = null;
+    }
     this.socket.syncAuthState({ reconnect: changed });
     this.emitCurrentUserChange();
   }
@@ -291,7 +319,9 @@ class GloomApiClient {
 
   private updateCurrentUser(updater: (user: AuthUser) => AuthUser): void {
     if (!this.currentUser) return;
-    this.setCurrentUser(updater(this.currentUser));
+    // A socket/profile update is metadata, not proof that a replacement
+    // credential belongs to this user. Keep its existing binding, even null.
+    this.setCurrentUser(updater(this.currentUser), false);
   }
 
   private socketEntitlementKey(user: AuthUser | null): string {
@@ -326,11 +356,123 @@ class GloomApiClient {
     return this.currentUser?.emailVerified ? this.currentUser : null;
   }
 
-  signUp = this.auth.signUp.bind(this.auth);
-  signIn = this.auth.signIn.bind(this.auth);
+  signUp = (email: string, username: string, name: string, password: string) =>
+    this.withSessionTransition((isCurrent) => this.auth.signUp(email, username, name, password, isCurrent));
+  signIn = (email: string, password: string) =>
+    this.withSessionTransition((isCurrent) => this.auth.signIn(email, password, isCurrent));
   startDeviceSignIn = this.auth.startDeviceSignIn.bind(this.auth);
   pollDeviceSignIn = this.auth.pollDeviceSignIn.bind(this.auth);
-  signOut = this.auth.signOut.bind(this.auth);
+  signOut = () => this.withSessionTransition((isCurrent) => this.auth.signOut(isCurrent), false);
+
+  /** Cookies can change before an auth response's body arrives, including ones the browser hides. */
+  private withSessionTransition<T>(run: (isCurrent: () => boolean) => Promise<T>, reconcileFailure = true): Promise<T> {
+    const previous = this.sessionTransition;
+    this.cancelSessionRevalidation();
+    let revalidationGeneration = this.sessionRevalidationGeneration;
+    const generation = this.sessionInstallationGeneration;
+    const isCurrent = () => generation === this.sessionInstallationGeneration;
+    this.sessionTransitions += 1;
+    this.sessionChecked = false;
+    this.verifiedSessionIdentity = null;
+    this.sessionRequestGeneration += 1;
+    this.emitCurrentUserChange();
+    let needsRevalidation = false;
+    const operation = (async () => {
+      // Serialize credential-changing requests so a late response cannot pair
+      // one account's user with another request's installed cookie.
+      if (previous) await previous;
+      try {
+        if (!isCurrent()) throw new Error("Another sign-in replaced this request.");
+        // An earlier queued sign-out may have retired retries while clearing its token.
+        revalidationGeneration = this.sessionRevalidationGeneration;
+        this.sessionRequestGeneration += 1;
+        const result = await run(isCurrent);
+        if (!isCurrent()) throw new Error("Another sign-in replaced this request.");
+        return result;
+      } catch (error) {
+        if (isCurrent()) {
+          this.verifiedSessionIdentity = null;
+          this.sessionChecked = false;
+        }
+        if (isCurrent() && reconcileFailure && this.transport.hasSessionCredential()) {
+          // A failed body may already have changed the cookie. A fresh session
+          // check is the only way to resume; retry if it cannot validate yet.
+          needsRevalidation = true;
+          this.sessionRequestGeneration += 1;
+          await this.revalidateSession(() => isCurrent()
+            && revalidationGeneration === this.sessionRevalidationGeneration).catch((failure) => {
+            if (!isCurrent()) return;
+            this.verifiedSessionIdentity = null;
+            logFailure("cloud.auth", "Restore session after failed sign-in failed")(failure);
+          });
+        }
+        throw error;
+      } finally {
+        if (isCurrent()) this.sessionRequestGeneration += 1;
+        this.sessionTransitions -= 1;
+        if (isCurrent() && needsRevalidation) this.scheduleSessionRevalidation(revalidationGeneration);
+        this.emitCurrentUserChange();
+      }
+    })();
+    const settled = operation.then(() => {}, () => {
+      // Intentional ignore: the caller receives the error while the auth queue continues.
+    });
+    this.sessionTransition = settled;
+    void settled.then(() => { if (this.sessionTransition === settled) this.sessionTransition = null; });
+    return operation;
+  }
+
+  private clearSessionRevalidationTimer(): void {
+    if (this.sessionRevalidationTimer !== null) clearTimeout(this.sessionRevalidationTimer);
+    this.sessionRevalidationTimer = null;
+  }
+
+  private cancelSessionRevalidation(): void {
+    this.sessionRevalidationGeneration += 1;
+    this.clearSessionRevalidationTimer();
+  }
+
+  /** A failed auth response can replace a cookie even when its recovery read is offline. */
+  private scheduleSessionRevalidation(generation: number, delay = SESSION_REVALIDATION_INITIAL_MS): void {
+    const isCurrent = () => generation === this.sessionRevalidationGeneration;
+    const needsRevalidation = () => isCurrent() && this.sessionTransitions === 0
+      && !this.sessionChecked && this.verifiedSessionIdentity === null && this.transport.hasSessionCredential();
+    if (!needsRevalidation() || this.sessionRevalidationTimer !== null) return;
+    this.sessionRevalidationTimer = setTimeout(() => {
+      this.sessionRevalidationTimer = null;
+      if (!needsRevalidation()) return;
+      void this.revalidateSession(isCurrent).catch((error) => {
+        if (isCurrent()) logFailure("cloud.auth", "Retry session validation failed")(error);
+      }).finally(() => {
+        this.scheduleSessionRevalidation(generation, Math.min(delay * 2, SESSION_REVALIDATION_MAX_MS));
+      });
+    }, delay);
+    this.sessionRevalidationTimer.unref?.();
+  }
+
+  private async revalidateSession(isCurrent: () => boolean): Promise<void> {
+    const user = await this.getSession(isCurrent);
+    const credential = this.getSessionToken();
+    if (user || !credential || !isCurrent()) return;
+    // A native null-session response can retain a usable token. Validate it
+    // through the account endpoint, without pairing it with a cached user.
+    this.sessionChecked = false;
+    const previousUser = this.currentUser;
+    const canApply = () => isCurrent() && this.getSessionToken() === credential && this.currentUser === previousUser;
+    try {
+      const profile = await this.auth.getAccountProfile(canApply);
+      if (!canApply()) return;
+      this.sessionChecked = true;
+      this.auth.restoreCachedUser({ ...profile, updatedAt: profile.updatedAt ?? undefined });
+    } catch (error) {
+      if (!canApply()) return;
+      if (error instanceof ApiRequestError && error.status === 401) {
+        this.installSessionToken(null);
+        return;
+      }
+      throw error;
+    }
+  }
 
   async getSession(isCurrent: () => boolean = () => true): Promise<AuthUser | null> {
     if (!isCurrent()) return this.currentUser;
@@ -353,7 +495,10 @@ class GloomApiClient {
       credential: this.getSessionToken(),
       promise: this.auth.getSession(canApply)
         .then(({ user, validated }) => {
-          if (validated && canApply()) this.sessionChecked = true;
+          if (validated && canApply()) {
+            this.sessionChecked = true;
+            this.clearSessionRevalidationTimer();
+          }
           this.traceAuth(validated ? "getSession:done" : "getSession:retained", user);
           return user;
         })
@@ -753,6 +898,8 @@ class GloomApiClient {
   subscribeScanner = this.socket.subscribeScanner.bind(this.socket);
 
   dispose(): void {
+    this.cancelSessionRevalidation();
+    this.sessionInstallationGeneration += 1;
     this.sessionRequestGeneration += 1;
     this.sessionRequest = null;
     this.socket.dispose();
@@ -799,11 +946,13 @@ class GloomApiClient {
   getCloudCentralBankRates = this.data.getCloudCentralBankRates.bind(this.data);
   getMobileAlertHistory = this.data.getMobileAlertHistory.bind(this.data);
   getScannerFlowHistory = this.data.getScannerFlowHistory.bind(this.data);
+  getLiveScan = this.data.getLiveScan.bind(this.data);
   getCloudEstimateRevisions = this.data.getCloudEstimateRevisions.bind(this.data);
   getCloudMoneyMarkets = this.data.getCloudMoneyMarkets.bind(this.data);
   equityScreener = this.data.equityScreener.bind(this.data);
   getMemberFunds = this.data.getMemberFunds.bind(this.data);
   getFundMembers = this.data.getFundMembers.bind(this.data);
+  getFundBreadth = this.data.getFundBreadth.bind(this.data);
   getFundChanges = this.data.getFundChanges.bind(this.data);
   getFundFacts = this.data.getFundFacts.bind(this.data);
   getCloudExchangeAnnouncements = this.data.getCloudExchangeAnnouncements.bind(this.data);

package/src/api-client/live-scan.ts

@@ -0,0 +1,91 @@
+/**
+ * The live scanner's wire format: a user's own intraday conditions over a
+ * universe of US stocks, evaluated by Gloom Cloud against a market-wide
+ * snapshot it refreshes every few seconds (real-time for Pro, 15 minutes
+ * delayed otherwise). `GET /market/scanner/live?scan=<definition JSON>`.
+ */
+
+/** Minutes a move, a volume window or an event can look back over. */
+export const LIVE_SCAN_WINDOWS = [1, 5, 15, 30, 60] as const;
+export type LiveScanWindow = (typeof LIVE_SCAN_WINDOWS)[number];
+
+export const LIVE_SCAN_INDEXES = ["sp500", "sp400", "sp600", "russell1000", "russell2000"] as const;
+export type LiveScanIndex = (typeof LIVE_SCAN_INDEXES)[number];
+
+/** The universe as Gloom Cloud reads it; a watchlist goes as its symbols. */
+type LiveScanWireUniverse =
+  | { kind: "all" }
+  | { kind: "index"; index: LiveScanIndex }
+  | { kind: "sector"; sector: string }
+  | { kind: "symbols"; symbols: string[] };
+
+export type LiveScanDirection = "up" | "down" | "either";
+
+export type LiveScanCondition =
+  /** Volume over the window (or the session so far) against the 20-session average's pace. */
+  | { kind: "volume_spike"; window: LiveScanWindow | "day"; ratio: number }
+  /** Percent move over the last `window` minutes. */
+  | { kind: "move"; window: LiveScanWindow; direction: LiveScanDirection; percent: number }
+  /** A new session high (low) printed in the last `within` minutes. */
+  | { kind: "new_high" | "new_low"; within: LiveScanWindow }
+  /** Crossed the session VWAP in the last `within` minutes, and still on that side. */
+  | { kind: "vwap_cross"; direction: "above" | "below" | "either"; within: LiveScanWindow }
+  /** The session's open against the previous close. */
+  | { kind: "gap"; direction: LiveScanDirection; percent: number };
+
+export interface LiveScanWireDefinition {
+  version: 1;
+  universe: LiveScanWireUniverse;
+  conditions: LiveScanCondition[];
+  minPrice?: number;
+  minMarketCap?: number;
+  minVolume?: number;
+}
+
+type LiveScanStatus = "live" | "starting" | "closed" | "degraded";
+
+export interface LiveScanMatch {
+  symbol: string;
+  name: string | null;
+  /** Its US venue (NASDAQ, NYSE, ...), null when the screener does not list it. */
+  exchange?: string | null;
+  price: number;
+  changePercent: number | null;
+  volume: number | null;
+  /** The session's volume against the 20-session average's pace so far. */
+  relativeVolume: number | null;
+  /** Price against the session VWAP, in percent. */
+  vwapPercent: number | null;
+  gapPercent: number | null;
+  /**
+   * The figure each condition matched on, in the definition's order: a
+   * percent for a move or a gap, a multiple for a volume spike, the time of
+   * the event (epoch ms) for a new high or low or a VWAP cross.
+   */
+  values: Array<number | null>;
+  /** The latest event a condition matched on. */
+  signalAt: number | null;
+  /** When the price printed. */
+  at: number | null;
+}
+
+export interface LiveScanPayload {
+  status: LiveScanStatus;
+  access: "realtime" | "delayed";
+  delayMinutes: number;
+  /** The market time the snapshot shows. */
+  asOf: number | null;
+  /** When the snapshot was refreshed. */
+  takenAt: number | null;
+  /** How often the snapshot refreshes. */
+  refreshMs: number;
+  scanned: number;
+  matched: number;
+  matches: LiveScanMatch[];
+  /** Windows the scanner cannot measure yet after it started; a condition over one matches nothing until then. */
+  warmingWindows: LiveScanWindow[];
+  warnings: string[];
+}
+
+/** The scan travels in a POST body: a watchlist of 1,000 symbols would not fit a request line. */
+export const LIVE_SCAN_PATH = "/market/scanner/live";

package/src/api-client/members.ts

@@ -30,3 +30,15 @@ export interface FundChangesPayload {
   estimateLabel: string; attribution: { text: string; url: string } | null;
 }
 export interface MemberFundsPayload { funds: (MemberFund & { asOf: string | null })[] }
+
+interface BreadthCount { above: number; eligible: number; percent: number | null }
+export interface BreadthDay {
+  date: string; asOf: string; membershipAsOf: string; memberCount: number; observed: number;
+  advances: number; declines: number; unchanged: number; advanceDeclineEligible: number;
+  ma20: BreadthCount; ma50: BreadthCount; ma200: BreadthCount;
+  newHighs: number; newLows: number; highLowEligible: number; adLine: number | null;
+}
+export interface FundBreadthPayload {
+  fund: MemberFund; basis: "daily-close" | "intraday"; access?: "realtime" | "delayed"; membershipBasis: "current-members";
+  latest: BreadthDay | null; history: BreadthDay[]; stale: boolean;
+}