@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/plugins/builtin/macro-day/pane.tsx

@@ -13,7 +13,10 @@ import { useThemeColors } from "../../../theme/theme-context";
 import type { PaneProps } from "../../../types/plugin";
 import { Box } from "../../../ui";
 import { loadMacroDayEarnings, loadMacroDayHistory, loadMacroReleases, macroDayEarningsNotice } from "./client";
-import { macroDayEventLabel, macroDayStats, matchesSurprise, projectMacroDays, type MacroDayEvent, type MacroDayModel } from "./model";
+import {
+  formatMacroDayMove, macroDayEventLabel, macroDayMoveDecimals, macroDayStats, matchesSurprise, projectMacroDays, type MacroDayEvent,
+  type MacroDayModel, type MacroDayMoveBasis,
+} from "./model";
 import { MACRO_EVENT_KINDS, MACRO_EVENT_LABELS, MACRO_SURPRISE_LABELS, MACRO_SURPRISES, staleMacroReleasesNotice, type MacroEventKind,
   type MacroSurprise } from "./releases";
 
@@ -21,17 +24,13 @@ export const LOOKBACK_OPTIONS = [{ value: "1", label: "1Y" }, { value: "2", labe
 const RELEASE_OPTIONS = [{ value: "all", label: "All" }, ...MACRO_EVENT_KINDS.map((kind) => ({ value: kind, label: MACRO_EVENT_LABELS[kind] }))];
 const SURPRISE_OPTIONS = [{ value: "all", label: "All" }, ...MACRO_SURPRISES.map((surprise) => ({ value: surprise, label: MACRO_SURPRISE_LABELS[surprise] }))];
 
-function pct(value: number | null | undefined, signed = true): string {
-  if (value == null) return "--";
-  const fixed = (value * 100).toFixed(2);
-  return /[1-9]/.test(fixed) ? `${signed && value > 0 ? "+" : ""}${fixed}%` : "0.00%";
-}
 const times = (value: number | null | undefined) => value == null ? "--" : `${value.toFixed(1)}x`;
 
 const EARNINGS_MARK = "earnings";
 const DATE: DataTableColumn = { id: "date", label: "Date", width: 19, align: "left" };
-const MOVE: DataTableColumn[] = [
-  { id: "move", label: "Move", width: 9, align: "right" },
+/** The move and its multiple of a normal day's; a yield's move is in basis points, and its header says so. */
+const moveColumns = (basis: MacroDayMoveBasis): DataTableColumn[] => [
+  { id: "move", label: basis === "yield" ? "Move bp" : "Move", width: 9, align: "right" },
   { id: "multiple", label: "vs Normal", width: 10, align: "right" },
 ];
 /** What each release came out with, under the labels the economic calendar gives them. */
@@ -48,23 +47,25 @@ function figureColumns(rows: readonly MacroDayEvent[]): DataTableColumn[] {
  * With every release listed, the release's name, widened to take the earnings marker where a row has one. With one
  * selected, a column only for the marker: every row would repeat the name.
  */
-export function columnsFor(release: string, rows: readonly MacroDayEvent[]): DataTableColumn[] {
+export function columnsFor(release: string, rows: readonly MacroDayEvent[], basis: MacroDayMoveBasis = "return"): DataTableColumn[] {
   const marked = rows.some((event) => event.earnings);
-  const values = [...figureColumns(rows), ...MOVE];
+  const values = [...figureColumns(rows), ...moveColumns(basis)];
   if (release === "all") return [DATE, { id: "release", label: "Release", width: marked ? 15 : 8, align: "left" }, ...values];
   return marked ? [DATE, { id: "release", label: "Note", width: EARNINGS_MARK.length, align: "left" }, ...values] : [DATE, ...values];
 }
 
-/** By the sign the two-decimal text shows: an average that rounds to 0.00% is neither up nor down. */
-export const moveTone = (value: number | null) => value == null || !/[1-9]/.test((value * 100).toFixed(2)) ? undefined
-  : value > 0 ? "positive" as const : "negative" as const;
+/** By the sign the text shows: an average that rounds to 0.00% (or 0.0bp) is neither up nor down. */
+export const moveTone = (value: number | null, basis: MacroDayMoveBasis = "return") =>
+  value == null || !/[1-9]/.test((value * 100).toFixed(macroDayMoveDecimals(basis))) ? undefined
+    : value > 0 ? "positive" as const : "negative" as const;
 
 /** The figures over the days a surprise filter keeps: the same four as one release's. */
 function surpriseFigures(model: MacroDayModel, rows: readonly MacroDayEvent[]): StatItem[] {
   const stats = macroDayStats(rows, model.normal.meanAbs);
+  const pct = (value: number | null, signed = true) => formatMacroDayMove(value, model.basis, { signed });
   return [
     { id: "abs", label: "Avg |move|", value: pct(stats.meanAbs, false), detail: stats.count ? `${times(stats.multiple)} normal` : undefined },
-    { id: "mean", label: "Avg move", value: pct(stats.mean), tone: moveTone(stats.mean) },
+    { id: "mean", label: "Avg move", value: pct(stats.mean), tone: moveTone(stats.mean, model.basis) },
     { id: "up", label: "Up", value: stats.hitRate == null ? "--" : `${Math.round(stats.hitRate * 100)}%`,
       detail: stats.count ? `${Math.round(stats.hitRate! * stats.count)} of ${stats.count}` : undefined },
     { id: "normal", label: "Normal day", value: pct(model.normal.meanAbs, false), detail: "avg |move|" },
@@ -72,6 +73,7 @@ function surpriseFigures(model: MacroDayModel, rows: readonly MacroDayEvent[]):
 }
 
 function figures(model: MacroDayModel, release: string): StatItem[] {
+  const pct = (value: number | null, signed = true) => formatMacroDayMove(value, model.basis, { signed });
   const normal: StatItem = { id: "normal", label: "Normal day", value: pct(model.normal.meanAbs, false), detail: "avg |move|" };
   if (release === "all") {
     return [...model.kinds.map((kind): StatItem => {
@@ -84,7 +86,7 @@ function figures(model: MacroDayModel, release: string): StatItem[] {
   const stats = model.byKind[release as MacroEventKind];
   return [
     { id: "abs", label: "Avg |move|", value: pct(stats.meanAbs, false), detail: stats.count ? `${times(stats.multiple)} normal` : undefined },
-    { id: "mean", label: "Avg move", value: pct(stats.mean), tone: moveTone(stats.mean) },
+    { id: "mean", label: "Avg move", value: pct(stats.mean), tone: moveTone(stats.mean, model.basis) },
     { id: "up", label: "Up", value: stats.hitRate == null ? "--" : `${Math.round(stats.hitRate * 100)}%`,
       detail: stats.count ? `${Math.round(stats.hitRate! * stats.count)} of ${stats.count}` : undefined },
     normal,
@@ -123,7 +125,7 @@ export function MacroDayPane({ width, height, focused }: PaneProps) {
     && matchesSurprise(event, surprise)) : [], [model, release, surprise]);
   const stats = useMemo(() => !model?.events.length ? [] : surprise === "all" ? figures(model, release) : surpriseFigures(model, rows),
     [model, release, surprise, rows]);
-  const columns = useMemo(() => columnsFor(release, rows), [release, rows]);
+  const columns = useMemo(() => columnsFor(release, rows, model?.basis), [model?.basis, release, rows]);
 
   usePaneNoticeFooter({ registrationId: "macro-day-notices", focused,
     notices: [...new Set([identityError, history.error, history.data?.error, releasesNotice, earningsNotice].filter((value): value is string => !!value))] });
@@ -141,9 +143,14 @@ export function MacroDayPane({ width, height, focused }: PaneProps) {
       : event.figures?.surprise === "cool" ? colors.negative : undefined };
     if (column.id === "forecast") return { text: event.figures?.forecast ?? "" };
     if (column.id === "prior") return { text: event.figures?.prior ?? "" };
-    if (column.id === "move") return { text: pct(event.move), value: event.move * 100, color: shownPriceColor(event.move * 100, 2, colors) };
+    if (column.id === "move") {
+      const basis = model?.basis ?? "return";
+      // Under a column headed bp, a yield's move is the number alone.
+      return { text: formatMacroDayMove(event.move, basis, { unit: false }), value: event.move * 100,
+        color: shownPriceColor(event.move * 100, macroDayMoveDecimals(basis), colors) };
+    }
     return { text: times(event.multiple), value: event.multiple };
-  }, [colors, release]);
+  }, [colors, model?.basis, release]);
 
   const contentHeight = Math.max(4, height - 1 - statGridRows(stats, width));
   const key = (event: MacroDayEvent) => `${event.kind}:${event.date}`;
@@ -162,7 +169,8 @@ export function MacroDayPane({ width, height, focused }: PaneProps) {
           getItemKey={key} emptyStateTitle={surprise === "all" ? "No release days." : `No ${MACRO_SURPRISE_LABELS[surprise].toLowerCase()} prints.`} sortColumnId={null} sortDirection="desc" selectedTextOverridesCellColor
           selection={{ kind: "id", selectedId: selectedRow, getId: key, onChange: (id) => setSelectedRow(id) }}
           getExportMetadata={() => [["symbol", model.symbol], ["from", model.start ?? ""], ["to", model.asOf ?? ""],
-            ["units", "percent, close to close on the release day"]]}
+            ["units", model.basis === "yield" ? "percentage points of yield, close to close on the release day"
+              : "percent, close to close on the release day"]]}
           renderCell={renderCell} />
       </> : null}
     </PaneStatusBody>}

package/src/plugins/builtin/macro-day/release-table.ts

@@ -5,9 +5,9 @@ export const MACRO_RELEASE_TABLE: {
   coveredThrough: string;
   days: Record<"cpi" | "jobs" | "fomc", Record<number, readonly string[]>>;
 } = {
-  checkedAt: "2026-10-15",
+  checkedAt: "2026-10-28",
   /** The last day the lists are complete for: later sessions are left out, release day or not. */
-  coveredThrough: "2026-10-14",
+  coveredThrough: "2026-10-27",
   days: {
     // BLS Consumer Price Index, 8:30 ET.
     cpi: {

package/src/plugins/builtin/market-heatmap/data.ts

@@ -1,4 +1,5 @@
 import { apiClient } from "../../../api-client";
+import { createTtlCache } from "../../../data/ttl-cache";
 import type { MarketHeatmapResult, MarketHeatmapUniverseId } from "../../../api-client/market-discovery";
 export type { MarketHeatmapUniverseId } from "../../../api-client/market-discovery";
 
@@ -39,8 +40,7 @@ const MAX_MARKET_HEATMAP_COUNT = 500;
 export function heatmapCheckIntervalMs(board: Pick<MarketHeatmapResult, "access"> | null | undefined): number {
   return board?.access === "realtime" ? 15_000 : 60_000;
 }
-const activeFetches = new Map<string, Promise<MarketHeatmapBoard>>();
-const memoryCache = new Map<string, { expiresAt: number; result: MarketHeatmapBoard }>();
+const boards = createTtlCache<MarketHeatmapBoard>({ ttlMs: heatmapCheckIntervalMs });
 
 /**
  * One tile per symbol. A company listed on two exchanges (KHC on NASDAQ and
@@ -75,43 +75,18 @@ async function loadMarketHeatmap(universe: MarketHeatmapUniverseId, count: numbe
   };
 }
 
-export async function fetchMarketHeatmap(
+export function fetchMarketHeatmap(
   universe: MarketHeatmapUniverseId,
   options?: MarketHeatmapFetchOptions,
   sources?: MarketHeatmapSources,
 ): Promise<MarketHeatmapBoard> {
   const count = Math.max(1, Math.min(MAX_MARKET_HEATMAP_COUNT, Math.round(options?.count ?? DEFAULT_COUNT)));
-  const cacheKey = `${universe}:${count}`;
-  const useCache = options?.cache !== false && !sources?.client;
-  const now = Date.now();
-  const cached = memoryCache.get(cacheKey);
-  if (useCache && !options?.forceRefresh && cached && cached.expiresAt > now) {
-    return cached.result;
-  }
-
-  if (useCache) {
-    const active = activeFetches.get(cacheKey);
-    if (active) return active;
-  }
-
-  const fetchPromise = loadMarketHeatmap(universe, count, sources)
-    .then((result) => {
-      if (useCache) {
-        memoryCache.set(cacheKey, { result, expiresAt: Date.now() + heatmapCheckIntervalMs(result) });
-      }
-      return result;
-    })
-    .finally(() => {
-      if (activeFetches.get(cacheKey) === fetchPromise) {
-        activeFetches.delete(cacheKey);
-      }
-    });
-
-  if (useCache) activeFetches.set(cacheKey, fetchPromise);
-  return fetchPromise;
+  const load = () => loadMarketHeatmap(universe, count, sources);
+  // A board asked for uncached, or through another client, neither reads nor fills the shared cache.
+  if (options?.cache === false || sources?.client) return load();
+  return boards.load(`${universe}:${count}`, load, { force: options?.forceRefresh });
 }
 
 export function resetMarketHeatmapCache(): void {
-  activeFetches.clear();
-  memoryCache.clear();
+  boards.clear();
 }

package/src/plugins/builtin/market-movers/client.ts

@@ -6,6 +6,7 @@ import type {
 } from "../../../api-client/market-movers";
 import type { DataProvider } from "../../../types/data-provider";
 import { logFailure } from "../../../utils/log-failure";
+import { savedCopyMark } from "../../../data/saved-copies";
 import {
   CATEGORY_MAP,
   moverRegularSession,
@@ -24,6 +25,7 @@ import {
   type PreferredMoversOptions,
   type TrendingSymbol,
 } from "./screener";
+import { meetsMinFloat } from "./min-float";
 
 export interface MarketMoverTabResult extends MarketMoversResult {
   tab: ScreenerTabId;
@@ -100,14 +102,19 @@ export function marketMoverQuoteError(result: Pick<MarketMoverTabResult, "unavai
 export async function loadMarketMoverTab(
   tab: ScreenerTabId,
   provider: DataProvider | null,
-  options?: Pick<PreferredMoversOptions, "forceRefresh" | "metadataWaitMs"> & { basis?: MoverRankBasis },
+  options?: Pick<PreferredMoversOptions, "forceRefresh" | "metadataWaitMs"> & {
+    basis?: MoverRankBasis;
+    /** Keep the rows with a float of at least this many shares. Trending carries no float and ignores it. */
+    minFloat?: number | null;
+  },
   dependencies: MarketMoverTabDependencies = defaultDependencies,
 ): Promise<MarketMoverTabResult> {
-  const { basis, ...fetchOptions } = options ?? {};
+  const { basis, minFloat = null, ...fetchOptions } = options ?? {};
   if (tab === "trending") {
     const trending = await dependencies.fetchTrending(LIST_ROWS, fetchOptions);
     const hydrated = await hydrateTrending(trending.data, provider);
     return {
+      ...savedCopyMark(trending),
       tab,
       ...hydrated,
       source: "gloom",
@@ -116,13 +123,15 @@ export async function loadMarketMoverTab(
   }
   const category = CATEGORY_MAP[tab];
   // The server picks the candidates on the basis the list ranks by, so after the close they are the session's movers.
-  const result = await dependencies.fetchPreferred(category, category === "most_actives" ? LIST_ROWS : MOVER_CANDIDATES, {
+  // A minimum float drops rows, so Most Active then reads as many candidates as the price lists.
+  const result = await dependencies.fetchPreferred(category, category === "most_actives" && minFloat == null ? LIST_ROWS : MOVER_CANDIDATES, {
     ...fetchOptions,
     session: basis ?? "regular",
   });
   // Each row read as `ticker` reads it, then ranked by the move its Chg% shows.
   const { quotes, rankedBy } = rankMoverQuotes(category, result.quotes.map(moverRegularSession), basis);
-  return { ...result, quotes: quotes.slice(0, LIST_ROWS), rankedBy, tab };
+  const kept = quotes.filter((quote) => meetsMinFloat(quote.floatShares, minFloat));
+  return { ...result, quotes: kept.slice(0, LIST_ROWS), rankedBy, tab };
 }
 
 /** The server refused the list for the account's plan (gaps, without Pro). */
@@ -136,12 +145,23 @@ export class SessionMoversAccessError extends Error {
 export async function loadSessionMovers(
   view: CloudSessionMoversCategory,
   side: CloudSessionMoversSide,
-  options?: { forceRefresh?: boolean },
+  options?: { forceRefresh?: boolean; minFloat?: number | null },
 ): Promise<CloudSessionMoversPayload> {
-  const response = await apiClient.getCloudMarketScreener(view, 25, options?.forceRefresh ? "refresh" : "cache-first", side);
+  const minFloat = options?.minFloat ?? null;
+  // A minimum float drops rows, so it reads the most the server lists.
+  const response = await apiClient.getCloudMarketScreener(view, minFloat == null ? LIST_ROWS : MOVER_CANDIDATES, options?.forceRefresh ? "refresh" : "cache-first", side);
   if (response.reasonCode === "PRO_REQUIRED") throw new SessionMoversAccessError();
   if ((response.status === "success" || response.status === "partial") && response.data) {
-    return response.stale ? { ...response.data, stale: true } : response.data;
+    const payload = response.stale ? { ...response.data, stale: true } : response.data;
+    return minFloat == null ? payload : { ...payload, items: withMinFloat(payload.items, minFloat) };
   }
   throw new Error("Session movers temporarily unavailable");
 }
+
+/** The rows with a float of at least `minFloat`, the first LIST_ROWS of them, ranked again from 1. */
+export function withMinFloat<T extends { rank: number; floatShares: number | null }>(items: readonly T[], minFloat: number): T[] {
+  return items
+    .filter((item) => meetsMinFloat(item.floatShares, minFloat))
+    .slice(0, LIST_ROWS)
+    .map((item, index) => ({ ...item, rank: index + 1 }));
+}

package/src/plugins/builtin/market-movers/headless.ts

@@ -14,6 +14,8 @@ import { createRows, fiftyTwoWeekPositionPercent, formatMoverPrice, MOVER_RANKIN
 import { EXTENDED_SESSION_LABELS, type ExtendedSession } from "../../../market-data/market/status";
 import type { HeadlessPaneColumn } from "../../../types/headless";
 import { isSessionTab, resolveSide } from "./session";
+import { hasPartialFloat, minFloatShares, normalizeMinFloat, PARTIAL_FLOAT_NOTE } from "./min-float";
+import { savedCopyMark } from "../../../data/saved-copies";
 
 const rowPrice = (value: unknown, row: Record<string, unknown>) => formatMoverPrice(typeof value === "number" ? value : null, typeof row.currency === "string" ? row.currency : "", moverReferencePrice(row as unknown as MarketMoverRow));
 
@@ -69,15 +71,19 @@ function sessionColumns(view: CloudSessionMoversCategory) {
   ];
 }
 
+const FLOAT_COLUMN: HeadlessPaneColumn = { key: "floatShares", header: "Float", align: "right", format: compact };
+
 export interface MarketMoversHeadlessDependencies {
   load(
     args: HeadlessPaneLoadArgs,
     tab: ScreenerTabId,
     provider: DataProvider,
+    minFloat: number | null,
   ): Promise<MarketMoverTabResult>;
   loadSession(
     view: CloudSessionMoversCategory,
     side: CloudSessionMoversSide,
+    minFloat: number | null,
   ): Promise<CloudSessionMoversPayload>;
 }
 
@@ -89,8 +95,8 @@ export interface MarketMoversHeadlessDependencies {
 const ONE_SHOT_METADATA_WAIT_MS = 10_000;
 
 const defaultDependencies: MarketMoversHeadlessDependencies = {
-  load: (_args, tab, provider) => loadMarketMoverTab(tab, provider, { metadataWaitMs: ONE_SHOT_METADATA_WAIT_MS }),
-  loadSession: (view, side) => loadSessionMovers(view, side),
+  load: (_args, tab, provider, minFloat) => loadMarketMoverTab(tab, provider, { metadataWaitMs: ONE_SHOT_METADATA_WAIT_MS, minFloat }),
+  loadSession: (view, side, minFloat) => loadSessionMovers(view, side, { minFloat }),
 };
 
 export function createMarketMoversHeadless(
@@ -128,6 +134,14 @@ export function createMarketMoversHeadless(
       ],
       defaultValue: "up",
       pluginState: { pluginId: "market-overview", key: "sessionSide" },
+    }, {
+      key: "min-float",
+      description: "Keep the rows whose float (the one EQS serves) is at least this many shares, such as 10M or 500k; any lifts it. A row with no float is left out. Trending carries no float and ignores it.",
+      type: "string",
+      placeholder: "shares",
+      example: "--min-float 10M",
+      normalize: normalizeMinFloat,
+      pluginState: { pluginId: "market-overview", key: "minFloat" },
     }],
     columns: COLUMNS,
     describe: (args) => isSessionTab(String(args.options.list))
@@ -135,21 +149,26 @@ export function createMarketMoversHeadless(
       : `Market Movers | ${String(args.options.list)}`,
     async load(args, ctx) {
       const tab = args.options.list as TabId;
+      const minFloatValue = typeof args.options["min-float"] === "string" ? args.options["min-float"] : null;
+      const minFloat = minFloatShares(minFloatValue);
       if (isSessionTab(tab)) {
         const side = resolveSide(tab, String(args.options.side));
-        const payload = await dependencies.loadSession(tab, side);
+        const payload = await dependencies.loadSession(tab, side, minFloat);
         return {
           columns: sessionColumns(tab),
           rows: payload.items.map((item) => ({
             ...item,
             events: item.catalysts.map((catalyst) => CATALYST_LABEL[catalyst] ?? catalyst).join(" "),
           })),
-          metadata: { list: tab, side, session: payload.session, phase: payload.phase, asOf: payload.asOf, stale: payload.stale === true },
+          ...(hasPartialFloat(payload.items) ? { notes: [PARTIAL_FLOAT_NOTE] } : {}),
+          metadata: { list: tab, side, session: payload.session, phase: payload.phase, asOf: payload.asOf, stale: payload.stale === true, minFloat },
           // A Pro account's list is the live board; the free one says it is delayed.
           ...(payload.access === "delayed" ? {} : { freshness: { status: "live" as const } }),
         };
       }
-      const result = await dependencies.load(args, tab, ctx.marketData);
+      // Trending carries no float, so a minimum does not apply to it.
+      const floatFiltered = minFloat != null && tab !== "trending";
+      const result = await dependencies.load(args, tab, ctx.marketData, floatFiltered ? minFloat : null);
       const ranked = createRows(result.quotes);
       // Last and Change % are the regular session; an extended print is a column of its own.
       const extendedSessions = moverExtendedSessions(ranked);
@@ -168,16 +187,19 @@ export function createMarketMoversHeadless(
       // Beside an extended column, say which move the order follows.
       const rankedBy = result.rankedBy ?? null;
       const quoteError = marketMoverQuoteError(result);
+      const columns = [...COLUMNS.slice(0, 5), ...extendedSessions.map(extendedColumn), ...COLUMNS.slice(5), ...(floatFiltered ? [FLOAT_COLUMN] : [])];
+      const notes = [
+        ...(rankedBy && rankedBy !== "volume" && extendedSessions.length > 0 ? [`Ranked by ${MOVER_RANKING_LABELS[rankedBy]}.`] : []),
+        ...(minFloat != null && !floatFiltered ? ["Trending carries no float, so --min-float does not apply to it."] : []),
+        ...(floatFiltered && hasPartialFloat(rows) ? [PARTIAL_FLOAT_NOTE] : []),
+      ];
       return {
-        ...(extendedSessions.length > 0
-          ? { columns: [...COLUMNS.slice(0, 5), ...extendedSessions.map(extendedColumn), ...COLUMNS.slice(5)] }
-          : {}),
+        ...(columns.length !== COLUMNS.length ? { columns } : {}),
         rows,
         ...(quoteError ? { complete: false, unavailableSymbols: result.unavailableSymbols, errors: [quoteError] } : {}),
-        ...(rankedBy && rankedBy !== "volume" && extendedSessions.length > 0
-          ? { notes: [`Ranked by ${MOVER_RANKING_LABELS[rankedBy]}.`] }
-          : {}),
-        metadata: { list: tab, source: result.source, stale: result.stale, rankedBy },
+        ...(notes.length > 0 ? { notes } : {}),
+        // A list served from a saved copy ends with when it was saved.
+        metadata: { ...savedCopyMark(result), list: tab, source: result.source, stale: result.stale, rankedBy, minFloat: floatFiltered ? minFloat : null },
         // A Pro account's Gainers, Losers and Most Active are the real-time lists.
         ...(result.source === "cloud" ? { freshness: { status: "live" as const } } : {}),
       };

package/src/plugins/builtin/market-movers/index.tsx

@@ -1,7 +1,7 @@
 import { Box, useUiCapabilities } from "../../../ui";
 import { nextHeaderSort } from "../../../utils/sort-values";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { DataTableView, EmptyState, usePaneFooter, usePaneTabs, type DataTableKeyEvent } from "../../../components";
+import { DataTableView, EmptyState, QueryBar, usePaneFooter, usePaneTabs, type DataTableKeyEvent } from "../../../components";
 import { handleRefreshKey } from "../../../components/data-table/table-pane";
 import type { PaneProps } from "../../../types/plugin";
 import type { PluginModule } from "../plugin-module";
@@ -41,6 +41,7 @@ import { loadMarketMoverTab, marketMoverQuoteError } from "./client";
 import { summaryFooterSegments } from "./footer";
 import { isSessionTab, resolveActiveTab, usSessionAt, type UsSession } from "./session";
 import { SessionMoversBody } from "./session-body";
+import { ANY_FLOAT, minFloatEmptyTitle, minFloatFilter, minFloatShares, partialFloatFooter } from "./min-float";
 import { marketMoversHeadless } from "./headless";
 import { buildMarketMoverColumns, renderMarketMoverCell } from "./table";
 import type { ExtendedSession } from "../../../market-data/market/status";
@@ -152,16 +153,21 @@ function ScreenerMoversBody({ activeTab, focused, width, summaryQuotes, liveStre
 }) {
   const dataProvider = useAssetData();
   const { pinTicker } = usePluginTickerActions();
+  const [minFloatValue, setMinFloatValue] = usePluginPaneState<string>("minFloat", ANY_FLOAT);
+  // Trending carries no float, so the minimum is not offered there.
+  const floatFiltered = activeTab !== "trending";
+  const minFloat = floatFiltered ? minFloatShares(minFloatValue) : null;
+  const listKey = `${activeTab}:${minFloat ?? ""}`;
   const [quotes, setQuotes] = useState<MoverQuote[]>([]);
-  const [loadedTab, setLoadedTab] = useState<TabId | null>(null);
-  const visibleQuotes = loadedTab === activeTab ? quotes : NO_QUOTES;
+  const [loadedKey, setLoadedKey] = useState<string | null>(null);
+  const visibleQuotes = loadedKey === listKey ? quotes : NO_QUOTES;
   // The first load starts before the effect runs; an empty board is not "no data".
   const [loading, setLoading] = useState(true);
   const [loadError, setLoadError] = useState<string | null>(null);
   const [selectedSymbol, setSelectedSymbol] = useState<string | null>(null);
   const [sortPreference, setSortPreference] = useState<MarketMoverSortPreference>(DEFAULT_SORT_PREFERENCE);
   const [moversStale, setMoversStale] = useState(false);
-  const [lastSuccess, setLastSuccess] = useState<{ tab: ScreenerTabId; at: number } | null>(null);
+  const [lastSuccess, setLastSuccess] = useState<{ key: string; at: number } | null>(null);
 
   const fetchGenRef = useRef(0);
 
@@ -192,8 +198,8 @@ function ScreenerMoversBody({ activeTab, focused, width, summaryQuotes, liveStre
   // A pre-market or after-hours column only while a row has such a print.
   const extendedSessionsKey = moverExtendedSessions(rankedRows).join(",");
   const columns = useMemo(
-    () => buildMarketMoverColumns(width, extendedSessionsKey ? extendedSessionsKey.split(",") as ExtendedSession[] : []),
-    [extendedSessionsKey, width],
+    () => buildMarketMoverColumns(width, extendedSessionsKey ? extendedSessionsKey.split(",") as ExtendedSession[] : [], { float: minFloat != null }),
+    [extendedSessionsKey, minFloat, width],
   );
   const rows = useMemo(() => sortRows(rankedRows, sortPreference), [rankedRows, sortPreference]);
   const selectedIdx = selectedSymbol
@@ -223,6 +229,7 @@ function ScreenerMoversBody({ activeTab, focused, width, summaryQuotes, liveStre
     try {
       const result = await loadMarketMoverTab(tab, dataProvider, {
         forceRefresh: options?.forceRefresh,
+        minFloat,
       });
       if (fetchGenRef.current !== gen) return;
 
@@ -230,12 +237,12 @@ function ScreenerMoversBody({ activeTab, focused, width, summaryQuotes, liveStre
       // A partial list shows only its current rows; a total failure keeps this list's prior rows.
       if (!quoteError || result.quotes.length > 0) {
         setQuotes(result.quotes);
-        setLoadedTab(tab);
+        setLoadedKey(`${tab}:${minFloat ?? ""}`);
         if (!options?.background) setSelectedSymbol(null);
       }
       setMoversStale(result.stale);
       setLoadError(quoteError);
-      if (!quoteError && !result.stale) setLastSuccess({ tab, at: Date.now() });
+      if (!quoteError && !result.stale) setLastSuccess({ key: `${tab}:${minFloat ?? ""}`, at: Date.now() });
     } catch {
       if (fetchGenRef.current !== gen) return;
       setMoversStale(true);
@@ -244,7 +251,7 @@ function ScreenerMoversBody({ activeTab, focused, width, summaryQuotes, liveStre
     finally {
       if (fetchGenRef.current === gen && !options?.background) setLoading(false);
     }
-  }, [dataProvider]);
+  }, [dataProvider, minFloat]);
 
   useEffect(() => {
     setSelectedSymbol(null);
@@ -254,7 +261,7 @@ function ScreenerMoversBody({ activeTab, focused, width, summaryQuotes, liveStre
   const backgroundRefresh = useCallback(() => {
     void loadTab(activeTab, { background: true });
   }, [activeTab, loadTab]);
-  useAutoRefresh(lastSuccess?.tab === activeTab ? lastSuccess.at : null, backgroundRefresh);
+  useAutoRefresh(lastSuccess?.key === listKey ? lastSuccess.at : null, backgroundRefresh);
 
   const openSymbol = useCallback((row: MarketMoverRow) => {
     pinTicker(moverKey(row), { floating: true, paneType: TICKER_RESEARCH_PANE_ID, instrument: null });
@@ -281,16 +288,21 @@ function ScreenerMoversBody({ activeTab, focused, width, summaryQuotes, liveStre
         id: "feed",
         parts: [{ text: feedStatus, tone: feedStatus === "live" ? "value" as const : "muted" as const }],
       }] : []),
-      ...(moversStale && loadedTab === activeTab ? [{
+      ...(moversStale && loadedKey === listKey ? [{
         id: "stale",
         parts: [{ text: "stale", tone: "muted" as const }],
       }] : []),
+      // The FLOAT column shows while a minimum is set; a float the source does not date says so once.
+      ...partialFloatFooter(columns.some((column) => column.id === "floatShares"), rows),
     ],
-  }), [activeTab, feedStatus, loadedTab, loadError, loading, moversStale, summaryQuotes]);
+  }), [columns, feedStatus, listKey, loadedKey, loadError, loading, moversStale, rows, summaryQuotes]);
 
   return (
     <DataTableView<MarketMoverRow, MarketMoverColumn>
       focused={focused}
+      rootBefore={floatFiltered ? (
+        <QueryBar width={Math.max(1, width - 2)} filters={[minFloatFilter(minFloatValue, setMinFloatValue)]} />
+      ) : undefined}
       selection={{
         kind: "id",
         selectedId: selectedSymbol,
@@ -298,7 +310,7 @@ function ScreenerMoversBody({ activeTab, focused, width, summaryQuotes, liveStre
         onChange: (symbol) => setSelectedSymbol(symbol),
       }}
       onRootKeyDown={handleTableKeyDown}
-      resetScrollKey={activeTab}
+      resetScrollKey={listKey}
       sortable
       columns={columns}
       items={rows}
@@ -309,7 +321,7 @@ function ScreenerMoversBody({ activeTab, focused, width, summaryQuotes, liveStre
       onActivate={openSymbol}
       renderCell={renderCell}
       selectedTextOverridesCellColor
-      emptyStateTitle={loading ? "Loading movers..." : loadError ?? "No movers returned."}
+      emptyStateTitle={loading ? "Loading movers..." : loadError ?? (minFloat != null ? minFloatEmptyTitle(minFloatValue) : "No movers returned.")}
       emptyContent={loadError ? (
         <Box paddingX={1} paddingY={1}>
           <EmptyState title={loadError} message="Try again in a moment." />

package/src/plugins/builtin/market-movers/min-float.ts

@@ -0,0 +1,74 @@
+import type { PaneFooterSegment } from "../../../components";
+import type { QueryBarSelectFilter } from "../../../components/ui/query-bar";
+import { formatCompact } from "../../../utils/format";
+
+/** No minimum: every row, with or without a float. */
+export const ANY_FLOAT = "any";
+/** The minimums the pane's menu offers; `--min-float` takes any other. */
+const PRESETS = ["1M", "5M", "10M", "20M", "50M", "100M"] as const;
+const SCALE: Record<string, number> = { k: 1e3, m: 1e6, b: 1e9 };
+
+/** Shares in `text` (10M, 500k, 2.5M, 25000000), or null when it is not a share count. */
+function parseShares(text: string): number | null {
+  const match = /^((?:\d+(?:\.\d*)?|\.\d+))([kmb])?$/i.exec(text.trim().replace(/[_,]/g, ""));
+  if (!match) return null;
+  const value = Number(match[1]) * (match[2] ? SCALE[match[2].toLowerCase()]! : 1);
+  return Number.isFinite(value) ? value : null;
+}
+
+/** The minimum a saved or typed value sets, in shares; null for none (`any`, 0 or a value that is not a count). */
+export function minFloatShares(value: string | null | undefined): number | null {
+  if (!value || value.trim().toLowerCase() === ANY_FLOAT) return null;
+  const shares = parseShares(value);
+  return shares != null && shares > 0 ? shares : null;
+}
+
+/** `--min-float` as the pane keeps it: `10M` for 10m or 10000000, `any` for none. Throws on a value that is not a share count. */
+export function normalizeMinFloat(value: string): string {
+  if (value.trim().toLowerCase() === ANY_FLOAT) return ANY_FLOAT;
+  const shares = parseShares(value);
+  if (shares == null) throw new Error(`--min-float takes a share count such as 10M or 500k, or any; got "${value}".`);
+  return shares > 0 ? formatCompact(shares) : ANY_FLOAT;
+}
+
+/** A row passes with a float at or above the minimum; a row whose float is not known does not. */
+export function meetsMinFloat(floatShares: number | null | undefined, minimum: number | null): boolean {
+  return minimum == null || (floatShares != null && floatShares >= minimum);
+}
+
+/** The pane's Min float menu: Any and the presets, with a minimum set from the CLI kept as its own choice. */
+export function minFloatFilter(value: string, onChange: (value: string) => void): QueryBarSelectFilter {
+  const current = minFloatShares(value) == null ? ANY_FLOAT : value;
+  const presets: string[] = [...PRESETS];
+  const options = [ANY_FLOAT, ...(presets.includes(current) || current === ANY_FLOAT ? [] : [current]), ...presets]
+    .map((option) => ({ value: option, label: option === ANY_FLOAT ? "Any" : option }));
+  return {
+    id: "min-float",
+    label: "Min float",
+    title: "Minimum float",
+    value: current,
+    defaultValue: ANY_FLOAT,
+    options,
+    onChange,
+  };
+}
+
+/** What a list says under its Float column while a shown float is partial. */
+export const PARTIAL_FLOAT_NOTE = "Float is partial: the source does not say when it measured it.";
+
+/** Whether any row's float is partial, which the list then says once. */
+export function hasPartialFloat(rows: readonly { floatShares?: number | null; floatSharesState?: string }[]): boolean {
+  return rows.some((row) => row.floatShares != null && row.floatSharesState === "partial");
+}
+
+/** The footer's word for a FLOAT column of partial floats, or none. */
+export function partialFloatFooter(shown: boolean, rows: readonly { floatShares?: number | null; floatSharesState?: string }[]): PaneFooterSegment[] {
+  return shown && hasPartialFloat(rows)
+    ? [{ id: "float-partial", parts: [{ text: "FLOAT", tone: "label" }, { text: "partial, undated", tone: "muted" }] }]
+    : [];
+}
+
+/** The empty list's title while a minimum hides every row. */
+export function minFloatEmptyTitle(value: string): string {
+  return `No movers with a float of ${value} or more.`;
+}

package/src/plugins/builtin/market-movers/model.ts

@@ -50,7 +50,8 @@ type MarketMoverColumnId =
   | "volume"
   | "volumeRatio"
   | "range"
-  | "marketCap";
+  | "marketCap"
+  | "floatShares";
 export type MarketMoverColumn = DataTableColumn & { id: MarketMoverColumnId };
 /**
  * A list row. Price and change are the regular session's, as `ticker` reads
@@ -123,6 +124,8 @@ function getSortValue(
       return fiftyTwoWeekPositionPercent(row.price, row.fiftyTwoWeekLow, row.fiftyTwoWeekHigh);
     case "marketCap":
       return row.marketCap ?? null;
+    case "floatShares":
+      return row.floatShares ?? null;
   }
 }