@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/plugins/builtin/equity-screener/headless.ts

@@ -4,6 +4,8 @@ import {
   KPI_FIELDS,
   NUMERIC_FIELDS,
   type NumericField,
+  type ScreenMetric,
+  type ScreenPayload,
   type ScreenRow,
 } from "../../../api-client/equity-screener";
 import { KPI_COVERAGE_NOTE } from "../company-kpis/model";
@@ -12,9 +14,19 @@ import { buildQuoteKey } from "../../../market-data/selectors";
 import type { Quote } from "../../../types/financials";
 import { formatCurrency, formatPercentRaw } from "../../../utils/format";
 import { fetchSavedScreens, fetchScreen, fetchScreenCheck } from "./client";
+import { SCREEN_IDEAS, screenIdea } from "./ideas";
 import { checkRows, screenCheckSummary, screenCheckTicker } from "./screen-check";
 import { overlayScreenQuotes, screenExtendedSessions, sortLiveScreenRows } from "./live";
 import {
+  CATEGORY_NAMES_POINTER,
+  SCREEN_INDUSTRIES,
+  SCREEN_SECTORS,
+  unmatchedCategoryText,
+  unmatchedCategoryValues,
+} from "./categories";
+import { REPORT_ROWS } from "../shared/headless-options";
+import {
+  appendScreenPage,
   DEFAULT_SCREEN,
   EXAMPLE_SCREEN_DEFINITION,
   formatScreenMetric,
@@ -71,6 +83,75 @@ function extendedColumn(session: ExtendedSession): HeadlessPaneColumn {
   };
 }
 
+/** Rows a report lists without `--limit`: one page, as the pane loads before it pages. */
+const SCREEN_PAGE_ROWS = 100;
+/** The most rows `--limit` lists, read a page at a time. */
+const SCREEN_ROW_LIMIT = 500;
+/** The most rows the server returns in one page. */
+const SCREEN_MAX_PAGE = 200;
+
+/** The rows a report lists: pages of the screen, in its order, until `limit` rows or the last match. */
+async function fetchScreenRows(definition: ScreenDefinition, limit: number, ctx: HeadlessPaneContext): Promise<ScreenPayload> {
+  let data = await fetchScreen(definition, null, ctx.signal, ctx.apiClient, Math.min(limit, SCREEN_MAX_PAGE));
+  while (data.rows.length < limit && data.nextCursor) {
+    const page = await fetchScreen(definition, data.nextCursor, ctx.signal, ctx.apiClient, Math.min(limit - data.rows.length, SCREEN_MAX_PAGE));
+    data = { ...appendScreenPage(data, page), warnings: [...new Set([...data.warnings, ...page.warnings])] };
+  }
+  return data;
+}
+
+/** What a report of the first rows says of the rest. */
+function moreMatchesNotice(shown: number, matched: number): string {
+  return matched <= SCREEN_ROW_LIMIT
+    ? `Top ${shown} of ${matched} matches; --limit ${matched} lists them all.`
+    : `Top ${shown} of ${matched} matches; --limit lists up to ${SCREEN_ROW_LIMIT}, or narrow the criteria to see the rest.`;
+}
+
+const isNumericField = (field: string): field is NumericField => (NUMERIC_FIELDS as readonly string[]).includes(field);
+const metricToken = (value: string) => value.trim().toLowerCase().replace(/[\s_-]+/g, "");
+
+/** `--metric trailingPE,dividendYieldPercent` as the fields it names, each once, in order; an unknown one fails. */
+function readMetrics(value: string): NumericField[] {
+  const fields = value.split(",").map((part) => part.trim()).filter(Boolean).map((part) => {
+    const field = NUMERIC_FIELDS.find((candidate) => metricToken(candidate) === metricToken(part));
+    if (!field) throw new Error(`Invalid --metric value "${part}". Use one of: ${NUMERIC_FIELDS.join(", ")}.`);
+    return field;
+  });
+  if (fields.length === 0) throw new Error("--metric requires a value, such as --metric trailingPE.");
+  return [...new Set(fields)];
+}
+
+type ShownCategory = "sector" | "industry" | "currency";
+const CATEGORY_HEADERS: Record<ShownCategory, string> = { sector: "Sector", industry: "Industry", currency: "Currency" };
+/** Columns every report prints, so neither another metric nor the sort field adds them again. */
+const ALWAYS_SHOWN = new Set(["symbol", "exchange", "name", "price", "changePercent"]);
+
+/**
+ * The columns a report adds after the first metric's: the other metrics
+ * asked for, then the field the screen is sorted by, so the order of the
+ * rows is explained by a column (P/E focus, sorted by dividend yield). A
+ * column every report prints (Last, Chg%) is not added twice, and its raw
+ * number stays in the row.
+ */
+function extraScreenColumns(metrics: readonly NumericField[], sortField: string): Array<NumericField | ShownCategory> {
+  return [...new Set([...metrics.slice(1), sortField as NumericField | ShownCategory])]
+    .filter((field) => field !== metrics[0] && !ALWAYS_SHOWN.has(field));
+}
+
+/** Another metric's cell: its value as the focus column prints it, with the currency of a money value. */
+function extraMetricCell(field: NumericField, metric: ScreenMetric | undefined): string {
+  if (!metric) return "-";
+  if (metric.access === "pro") return "locked";
+  const value = formatScreenMetric(field, metric);
+  return metric.value != null && /^[A-Z]{3}$/.test(metric.unit) ? `${value} ${metric.unit}` : value;
+}
+
+/** What the State column's words mean, said once under a report whose first metric has them. */
+const STATE_LEGEND: ReadonlyArray<{ state: ScreenMetric["state"]; text: string }> = [
+  { state: "partial", text: "A partial State means the source gives no date for the figure, so As of is when it was collected, or that it covers part of what it measures." },
+  { state: "stale", text: "A stale State means the figure is older than its field allows, such as a quote over 4 days old or fundamentals collected over 7 days ago." },
+];
+
 /** A typed `--definition`, checked; every error points at the worked example. */
 function readDefinition(text: string): ScreenDefinition {
   const pointer = "The example in gloom catalog EQS is a valid definition to start from.";
@@ -112,6 +193,14 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
       shot: { reportOnly: "opens a saved screen for the report; open it from Saved in the EQS pane" },
       replaces: ["definition"],
     },
+    {
+      key: "preset",
+      type: "enum",
+      description: `A ready screen from Ideas, ranked by its own metric unless --metric says otherwise: ${SCREEN_IDEAS.map((entry) => `${entry.id} (${entry.name})`).join(", ")}. Cannot be combined with --saved or --definition.`,
+      values: SCREEN_IDEAS.map((entry) => ({ value: entry.id })),
+      example: "--preset golden-cross",
+      replaces: ["definition", "saved"],
+    },
     {
       key: "definition",
       type: "string",
@@ -126,15 +215,32 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
     {
       key: "metric",
       type: "enum",
+      list: true,
+      // No default: a preset leads with its own metric, anything else with marketCap.
       description:
-        "Metric to display with its source date and covered-universe rank.",
+        "Metric to display with its source date and covered-universe rank: marketCap, or the preset's own metric. Several, as a comma list or the flag again, add a column each after the first.",
+      example: "--metric trailingPE --metric dividendYieldPercent",
       values: NUMERIC_FIELDS.map((value) => ({ value })),
-      defaultValue: "marketCap",
+      normalize: (value) => readMetrics(value).join(","),
+    },
+    {
+      key: "limit",
+      type: "integer",
+      shot: REPORT_ROWS,
+      minimum: 1,
+      maximum: SCREEN_ROW_LIMIT,
+      defaultValue: SCREEN_PAGE_ROWS,
+      description: `Matching rows to list, in the screen's order, up to ${SCREEN_ROW_LIMIT}.`,
+      example: "--limit 40",
     },
   ],
   describe: "Equity screener",
   discovery: {
     aliases: ["EQS"],
+    reference: [
+      { title: "Sectors", items: [...SCREEN_SECTORS] },
+      { title: "Industries", items: [...SCREEN_INDUSTRIES] },
+    ],
     dataRequirements: ["Gloom Cloud stored screener snapshot"],
     limitations: [
       "Covered stored universe, not every listed equity.",
@@ -142,13 +248,18 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
       "Observed-subset insider activity cannot establish an absence.",
       "ATR% is the 14-session average true range as a percent of the last close, for US listings with at least 15 completed daily sessions.",
       "IV rank is a rank, not an IV percentile: 0 is the lowest 30-day implied volatility of the past 52 weeks and 100 the highest.",
+      "IV percentile is the share of the past 52 weeks' options closes with IV30 below the latest; IV30 changes are in volatility points (25% to 27% is +2). IV fields with no close in five days are unavailable. HV20 is 20-session realized volatility, annualized, and HV rank places it between its 52-week low and high.",
+      "Technical fields (RSI, moving averages, MACD and golden crosses, new highs and lows, Bollinger width) read US listings' completed daily sessions: they describe the last close, not the session in progress. A days-since field counts trading days, 0 at the last session.",
+      "Shares outstanding, float, short % of float and institutional ownership cover US filers: the 10-K or 10-Q cover count, the stored statistics float, the FINRA settlement, the 13F quarter. The source does not say when it measured the float, so float and short % of float are partial, dated by when the statistics were retrieved (within 30 days) and never above the dated shares outstanding. A stale or inconsistent input leaves a field unavailable with its reason. Institutional ownership is over the balance-sheet count at the 13F quarter end; over 100% is partial with its reason.",
     ],
   },
   async load(args, ctx) {
-    if (args.options.saved && args.options.definition) throw new Error("Choose --saved or --definition, not both.");
-    let definition = args.options.definition
+    if ([args.options.preset, args.options.saved, args.options.definition].filter(Boolean).length > 1)
+      throw new Error(args.options.preset ? "Choose one of --preset, --saved and --definition." : "Choose --saved or --definition, not both.");
+    const preset = screenIdea(args.options.preset == null ? undefined : String(args.options.preset));
+    let definition = preset?.definition ?? (args.options.definition
       ? readDefinition(String(args.options.definition))
-      : DEFAULT_SCREEN;
+      : DEFAULT_SCREEN);
     let savedName: string | undefined;
     if (args.options.saved) {
       const screens = await fetchSavedScreens(ctx.signal, ctx.apiClient);
@@ -189,8 +300,10 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
         },
       };
     }
-    const data = await fetchScreen(definition, null, ctx.signal, ctx.apiClient);
-    const metric = (args.options.metric ?? "marketCap") as NumericField;
+    const limit = typeof args.options.limit === "number" ? args.options.limit : SCREEN_PAGE_ROWS;
+    const data = await fetchScreenRows(definition, limit, ctx);
+    const metrics = readMetrics(args.options.metric == null ? preset?.metric ?? "marketCap" : String(args.options.metric));
+    const metric = metrics[0]!;
     // Last, Chg% and market cap are the regular session, as `quote` and the
     // pane read each row's quote; an extended print is a column of its own.
     // A sort on one of them is redone on those figures.
@@ -204,21 +317,33 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
     const kpiGaps = !withheld && missing > 0 && (KPI_FIELDS as readonly string[]).includes(metric)
       ? [`${missing} of ${rows.length} ${rows.length === 1 ? "row has" : "rows have"} no ${screenLabel(metric)}. ${KPI_COVERAGE_NOTE}`]
       : [];
+    // A category value that names nothing (`Utility` for Utilities) says so with the names it was likely meant as.
+    const unmatched = unmatchedCategoryValues(data.definition, data, rows).map(unmatchedCategoryText);
+    const unmatchedText = unmatched.length > 0 ? [...unmatched, CATEGORY_NAMES_POINTER].join(" ") : null;
     // A CAD screen of listings quoted in USD is empty for its currency, not for want of companies: say so, and give the screen in USD.
     const currencyEmpty = rows.length === 0 ? screenCurrencyEmpty(data.definition, data.universe) : null;
-    const empty = currencyEmpty
+    const empty = rows.length === 0 && unmatchedText
+      ? unmatchedText
+      : currencyEmpty
       ? [
         `${currencyEmpty.title} ${currencyEmpty.detail}`,
         `In the base currency, ${currencyEmpty.base.currency}: gloom fn EQS --definition '${spacedJson(currencyEmpty.base)}'${metric === "marketCap" ? "" : ` --metric ${metric}`}`,
       ].join("\n")
       : null;
+    const ytdBase = screenYtdBase(data.rows, data.snapshot?.assembledAt);
+    // The metrics after the first, then the field the rows are sorted by, so the order shown is explained by a column.
+    const extra = extraScreenColumns(metrics, data.definition.sort.field);
+    const states = new Set(rows.map((row) => row.metrics[metric].state));
+    const legend = STATE_LEGEND.filter(({ state }) => states.has(state)).map(({ text }) => text);
+    const notes = [...kpiGaps, ...legend];
     // Payload status also counts ordinary per-field sparsity; only generation
     // warnings are failures, and more pages are not an error.
     return {
       freshness: { asOf: data.snapshot?.sourceNewestAt ?? null },
       complete: !data.nextCursor && errors.length === 0,
       errors,
-      ...(kpiGaps.length ? { notes: kpiGaps } : {}),
+      ...(notes.length ? { notes } : {}),
+      ...(rows.length > 0 && unmatchedText ? { warnings: [unmatchedText] } : {}),
       sections: [
         {
           title: "Matching equities",
@@ -232,11 +357,14 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
             ...(metric === "changePercent" ? [] : [{ key: "changePercent", header: "Chg%", align: "right" as const, format: percent }]),
             ...extendedSessions.map(extendedColumn),
             // YTD names the close it is measured from: `YTD% vs 31 Dec close`.
-            { key: "value", header: screenColumnLabel(metric, screenYtdBase(data.rows, data.snapshot?.assembledAt), "report"), align: "right" },
+            { key: "value", header: screenColumnLabel(metric, ytdBase, "report"), align: "right" },
             { key: "unit", header: "Unit" },
             { key: "percentile", header: "Covered pctl", align: "right" },
             { key: "asOf", header: "As of" },
             { key: "state", header: "State" },
+            ...extra.map((field): HeadlessPaneColumn => isNumericField(field)
+              ? { key: field, header: screenColumnLabel(field, ytdBase, "report"), align: "right" }
+              : { key: field, header: CATEGORY_HEADERS[field] }),
           ],
           rows: rows.map((row) => {
             const observation = row.metrics[metric];
@@ -260,6 +388,9 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
                   : Math.round(observation.percentile.value),
               asOf: stamp.collected ? `${stamp.text} (collected)` : stamp.text,
               state: observation.access === "pro" ? "locked" : observation.state,
+              ...Object.fromEntries(extra.map((field) => [field, isNumericField(field)
+                ? extraMetricCell(field, row.metrics[field])
+                : row[field]])),
             };
           }),
         },
@@ -272,11 +403,11 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
         covered: data.universe.covered,
         returned: data.rows.length,
         hasMore: !!data.nextCursor,
+        metrics,
+        ...(unmatched.length > 0 ? { unmatchedValues: unmatchedCategoryValues(data.definition, data, rows) } : {}),
         priceBasis: "price, changePercent and the market cap are the regular session, read from each row's quote as `quote` reads it: after the close, its close and that close's move. A pre-market, after-hours or overnight print is in extendedPrice and extendedChangePercent, measured from that close. Membership and percentiles are the snapshot's, which ranks by the close; a sort on price, changePercent, volume or marketCap orders these rows by the figures shown.",
         notices: data.nextCursor
-          ? [
-              `Top ${data.rows.length} of ${data.universe.matched} matches; narrow the criteria to see the rest.`,
-            ]
+          ? [moreMatchesNotice(data.rows.length, data.universe.matched)]
           : [],
       },
     };

package/src/plugins/builtin/equity-screener/ideas.ts

@@ -0,0 +1,49 @@
+import type { NumericField, ScreenCriterion, ScreenDefinition } from "../../../api-client/equity-screener";
+
+/** A ready screen in the Ideas tab and `--preset`: its definition and the metric it leads with. */
+export interface ScreenIdea {
+  id: string;
+  name: string;
+  metric: NumericField;
+  definition: ScreenDefinition;
+}
+
+/** Companies above 2B, so an idea lists names that trade, not every small listing that moved. */
+const TRADED: ScreenCriterion = { field: "marketCap", op: "gte", value: 2_000_000_000 };
+
+const idea = (
+  id: string,
+  name: string,
+  criteria: ScreenCriterion[],
+  sort: ScreenDefinition["sort"] & { field: NumericField },
+): ScreenIdea => ({
+  id,
+  name,
+  metric: sort.field,
+  definition: { version: 1, currency: "USD", criteria: [...criteria, TRADED], sort },
+});
+
+/** Technical ideas, read at the last completed session. */
+export const SCREEN_IDEAS: ScreenIdea[] = [
+  idea("oversold-uptrend", "Oversold in an uptrend", [
+    { field: "rsi14", op: "lte", value: 30 },
+    { field: "priceVsSma200Percent", op: "gt", value: 0 },
+  ], { field: "rsi14", direction: "asc" }),
+  idea("golden-cross", "Fresh golden cross", [
+    { field: "goldenCrossDays", op: "lte", value: 10 },
+  ], { field: "goldenCrossDays", direction: "asc" }),
+  // Every match is at its high, so the largest companies lead.
+  idea("52-week-high", "52-week high breakout", [
+    { field: "newHigh52wDays", op: "eq", value: 0 },
+  ], { field: "marketCap", direction: "desc" }),
+  idea("bollinger-squeeze", "Bollinger squeeze", [
+    { field: "bollingerWidthPercentile", op: "lte", value: 5 },
+  ], { field: "bollingerWidthPercentile", direction: "asc" }),
+  idea("macd-turn", "MACD turns up in an uptrend", [
+    { field: "macdBullishCrossDays", op: "lte", value: 3 },
+    { field: "priceVsSma200Percent", op: "gt", value: 0 },
+  ], { field: "macdBullishCrossDays", direction: "asc" }),
+];
+
+export const screenIdea = (id: string | undefined): ScreenIdea | undefined =>
+  SCREEN_IDEAS.find((entry) => entry.id === id);

package/src/plugins/builtin/equity-screener/model.ts

@@ -4,9 +4,12 @@ import {
   HIRING_APP_FIELDS,
   CATEGORY_FIELDS,
   NUMERIC_FIELDS,
+  OPTION_VOLATILITY_FIELDS,
+  OWNERSHIP_FIELDS,
   RESEARCH_FIELDS,
   KPI_FIELDS,
   SOCIAL_FIELDS,
+  TECHNICAL_FIELDS,
   VOLATILITY_FIELDS,
   type NumericField,
   type ScreenMetric,
@@ -22,6 +25,7 @@ import { canonicalExchange } from "../../../utils/exchanges";
 import { LATEST_DISTRIBUTION, TRAILING_DIVIDEND_BASIS } from "../../../utils/forward-dividend";
 import { formatCompact, formatNumber } from "../../../utils/format";
 import { formatPriceEarnings, NOT_MEANINGFUL } from "../../../utils/price-earnings";
+import { ATTENTION_LISTED } from "../attention/listing";
 import { kpiFreeLimitNote } from "../company-kpis/model";
 
 /**
@@ -90,6 +94,20 @@ export const SHORT_LABELS: Record<NumericField, string> = {
   fromHigh52WPercent: "VS 52W HI%",
   beta: "BETA",
   atrPercent: "ATR%",
+  rsi14: "RSI 14",
+  priceVsSma20Percent: "VS SMA20%",
+  priceVsSma50Percent: "VS SMA50%",
+  priceVsSma200Percent: "VS SMA200%",
+  // Sessions since the event: 0 is the last completed session.
+  macdBullishCrossDays: "MACD BULL AGO",
+  macdBearishCrossDays: "MACD BEAR AGO",
+  goldenCrossDays: "GOLDEN X AGO",
+  deathCrossDays: "DEATH X AGO",
+  newHigh20dDays: "20D HIGH AGO",
+  newLow20dDays: "20D LOW AGO",
+  newHigh52wDays: "52W HIGH AGO",
+  newLow52wDays: "52W LOW AGO",
+  bollingerWidthPercentile: "BB WIDTH PCTL",
   priceToBook: "P/B",
   evToEbitda: "EV/EBITDA",
   roePercent: "FY ROE%",
@@ -97,6 +115,17 @@ export const SHORT_LABELS: Record<NumericField, string> = {
   analystUpsidePercent: "UPSIDE%",
   ivRank: "IV RANK",
   ivToHv: "IV/HV",
+  iv30Percent: "IV30%",
+  ivPercentile: "IV PCTL",
+  // Volatility points: IV30 25% to 27% is +2.
+  iv30Change1d: "IV30 CHG 1D",
+  iv30Change5d: "IV30 CHG 5D",
+  hv20Percent: "HV20%",
+  hvRank: "HV RANK",
+  sharesOutstanding: "SHARES OUT",
+  floatShares: "FLOAT",
+  shortPercentOfFloat: "SI % FLOAT",
+  institutionalOwnershipPercent: "INST OWN%",
   hiringOpenRoles: "OPEN ROLES",
   hiringNetAddsWeek: "NET ROLES/WK",
   hiringRemotePercent: "REMOTE%",
@@ -106,7 +135,7 @@ export const SHORT_LABELS: Record<NumericField, string> = {
   appRatingDrift7d: "RATING 7D",
   appRatingCountGrowth7d: "RATINGS 7D",
 };
-const COMPACT = new Set<NumericField>(["kpiArr", "kpiRpo", "kpiCrpo", "kpiSubscribers", "kpiDau", "kpiMau", "kpiGmv", "kpiStores", "kpiBacklog", "marketCap", "volume", "averageVolume20d", "shortInterestShares"]);
+const COMPACT = new Set<NumericField>(["kpiArr", "kpiRpo", "kpiCrpo", "kpiSubscribers", "kpiDau", "kpiMau", "kpiGmv", "kpiStores", "kpiBacklog", "marketCap", "volume", "averageVolume20d", "shortInterestShares", "sharesOutstanding", "floatShares"]);
 /** Daily counts: whole numbers below a thousand, compact above. */
 const DAILY_COUNTS = new Set<NumericField>(["xPostsPerDay", "wikiViewsPerDay"]);
 const RATIOS = new Set<NumericField>(["kpiBookToBill", "xPostsVsMedian", "wikiViewsVsMedian", "priceToBook", "evToEbitda", "ivToHv"]);
@@ -116,10 +145,15 @@ const SIGNED = new Set<NumericField>(["hiringNetAddsWeek", "hiringZScore", "appR
   "changePercent", "revenueGrowthPercent", "earningsGrowthPercent", "shortInterestChangePercent",
   "dividendGrowth1YPercent", "dividendGrowth3YPercent",
   ...RETURNS, "fromHigh52WPercent", "epsRevision30dPercent", "analystUpsidePercent",
+  "priceVsSma20Percent", "priceVsSma50Percent", "priceVsSma200Percent",
+  "iv30Change1d", "iv30Change5d",
 ]);
 /** Moves whose sign is the news: they take the sign colour. */
-export const SIGN_COLORED = new Set<NumericField>(["changePercent", ...RETURNS, "epsRevision30dPercent", "analystUpsidePercent"]);
-const COUNTS = new Set<NumericField>(["appRatingCountGrowth7d", "hiringNetAddsWeek", "hiringOpenRoles", "attentionResearchUnits", "insiderPurchases90d", "insiderSales90d", "institutionalHolders", "institutionalNewHolders", "institutionalExits", "ivRank"]);
+export const SIGN_COLORED = new Set<NumericField>(["changePercent", ...RETURNS, "epsRevision30dPercent", "analystUpsidePercent",
+  "priceVsSma20Percent", "priceVsSma50Percent", "priceVsSma200Percent"]);
+const COUNTS = new Set<NumericField>(["appRatingCountGrowth7d", "hiringNetAddsWeek", "hiringOpenRoles", "attentionResearchUnits", "insiderPurchases90d", "insiderSales90d", "institutionalHolders", "institutionalNewHolders", "institutionalExits", "ivRank", "ivPercentile", "hvRank",
+  "macdBullishCrossDays", "macdBearishCrossDays", "goldenCrossDays", "deathCrossDays",
+  "newHigh20dDays", "newLow20dDays", "newHigh52wDays", "newLow52wDays", "bollingerWidthPercentile"]);
 const MONETARY = new Set<NumericField>(["price", "marketCap", "kpiArr", "kpiRpo", "kpiCrpo", "kpiGmv", "kpiBacklog"]);
 /** Shown after the screen's own criteria when the pane has room. */
 const CONTEXT_FIELDS: NumericField[] = ["marketCap", "price", "changePercent", "trailingPE", "revenueGrowthPercent", "operatingMarginPercent", "dividendYieldPercent"];
@@ -161,13 +195,30 @@ export function metricDate(metric: ScreenMetric): { text: string; collected: boo
   return { text: "--", collected: false };
 }
 
-/** Focus metric, then the screen's numeric criteria, then context columns. Money needs one currency. */
-export function resultFields(definition: ScreenDefinition, metric: NumericField): NumericField[] {
-  const numeric = (field: string): field is NumericField => (NUMERIC_FIELDS as readonly string[]).includes(field);
-  const fields = [metric, ...definition.criteria.map((criterion) => criterion.field).filter(numeric), ...CONTEXT_FIELDS];
+const isNumeric = (field: string): field is NumericField => (NUMERIC_FIELDS as readonly string[]).includes(field);
+
+/**
+ * Focus metric, the other metrics asked for, the field the rows are sorted
+ * by (so their order is explained by a column), then the screen's numeric
+ * criteria and the context columns. Money needs one currency.
+ */
+export function resultFields(definition: ScreenDefinition, metric: NumericField, others: readonly NumericField[] = []): NumericField[] {
+  const sort = isNumeric(definition.sort.field) ? [definition.sort.field] : [];
+  const fields = [metric, ...others, ...sort, ...definition.criteria.map((criterion) => criterion.field).filter(isNumeric), ...CONTEXT_FIELDS];
   return [...new Set(fields)].filter((field) => definition.currency || !MONETARY.has(field) || field === metric);
 }
 
+/**
+ * The metrics a pane's `metric` setting names, the focus first: one field, or
+ * the comma list `--metric` leaves (`trailingPE,dividendYieldPercent`).
+ * Unknown names are skipped; none known leaves `fallback`.
+ */
+export function screenMetricSetting(setting: unknown, fallback: NumericField): [NumericField, ...NumericField[]] {
+  const fields = typeof setting === "string" ? setting.split(",").map((part) => part.trim()).filter(isNumeric) : [];
+  const unique = [...new Set(fields)];
+  return unique.length > 0 ? unique as [NumericField, ...NumericField[]] : [fallback];
+}
+
 /**
  * The close the screen's YTD returns are measured from, `31 Dec`: NYSE's last
  * session of the year before the newest session a row's YTD ends on, the
@@ -288,6 +339,19 @@ export const screenLabel = (field: string) =>
     fromHigh52WPercent: "From 52-week high %",
     beta: "Beta",
     atrPercent: "ATR%",
+    rsi14: "RSI 14",
+    priceVsSma20Percent: "Price vs SMA 20 %",
+    priceVsSma50Percent: "Price vs SMA 50 %",
+    priceVsSma200Percent: "Price vs SMA 200 %",
+    macdBullishCrossDays: "Days since MACD bullish cross",
+    macdBearishCrossDays: "Days since MACD bearish cross",
+    goldenCrossDays: "Days since golden cross",
+    deathCrossDays: "Days since death cross",
+    newHigh20dDays: "Days since new 20-day high",
+    newLow20dDays: "Days since new 20-day low",
+    newHigh52wDays: "Days since new 52-week high",
+    newLow52wDays: "Days since new 52-week low",
+    bollingerWidthPercentile: "Bollinger width percentile",
     priceToBook: "P/B",
     evToEbitda: "EV / EBITDA",
     roePercent: "Annual ROE %",
@@ -295,6 +359,16 @@ export const screenLabel = (field: string) =>
     analystUpsidePercent: "Analyst upside %",
     ivRank: "IV rank",
     ivToHv: "IV / HV",
+    iv30Percent: "IV30 %",
+    ivPercentile: "IV percentile",
+    iv30Change1d: "IV30 change 1D, vol pts",
+    iv30Change5d: "IV30 change 5D, vol pts",
+    hv20Percent: "HV20 %",
+    hvRank: "HV rank",
+    sharesOutstanding: "Shares outstanding",
+    floatShares: "Float",
+    shortPercentOfFloat: "Short interest % of float",
+    institutionalOwnershipPercent: "Institutional ownership % (13F)",
     hiringOpenRoles: "Hiring open roles",
     hiringNetAddsWeek: "Net open roles per week",
     hiringRemotePercent: "Remote roles %",
@@ -538,6 +612,21 @@ const unavailableMetric = (): ScreenMetric => ({
   state: "unavailable", scope: "reported", reason: "Not provided by this server", sourceUrl: null,
   percentile: { value: null, sampleCount: 0, scope: "covered-universe" },
 });
+/**
+ * The fields the field and metric pickers offer. ATTN's two (ATTN HRS,
+ * ATTN Z) stay out until ATTN is listed again (attention/listing.ts), but for
+ * one the screen already uses, so a saved screen still shows it.
+ */
+export function pickerFields<Field extends { id: string }>(
+  fields: readonly Field[],
+  inUse: readonly string[] = [],
+  listed: boolean = ATTENTION_LISTED,
+): Field[] {
+  if (listed) return [...fields];
+  const unlisted = new Set<string>(ATTENTION_FIELDS);
+  return fields.filter((field) => !unlisted.has(field.id) || inUse.includes(field.id));
+}
+
 /** Company KPIs, guidance, hiring and app attention: the server leaves them out of a screen for a caller without Gloom Pro. */
 const PRO_FIELDS: ReadonlySet<string> = new Set([...KPI_FIELDS, ...HIRING_APP_FIELDS]);
 const withheldMetric = (): ScreenMetric => ({ ...unavailableMetric(), reason: "Needs Gloom Pro", access: "pro" });
@@ -593,9 +682,9 @@ export function validateScreenPayload(value: unknown): ScreenPayload {
       throw new Error("Invalid screener listing identity.");
     ids.add(screenRowId(row));
     for (const field of NUMERIC_FIELDS) {
-      // A server from before social, research, volatility or dividend fields omits them; they read as unavailable.
-      // A Pro field it left out was held back from this caller.
-      if (!row.metrics[field] && ([...SOCIAL_FIELDS, ...RESEARCH_FIELDS, ...VOLATILITY_FIELDS, ...ATTENTION_FIELDS, ...HIRING_APP_FIELDS, ...KPI_FIELDS, ...DIVIDEND_FIELDS] as readonly string[]).includes(field))
+      // A server from before social, research, volatility, dividend, technical, option volatility or ownership fields
+      // omits them; they read as unavailable. A Pro field it left out was held back from this caller.
+      if (!row.metrics[field] && ([...SOCIAL_FIELDS, ...RESEARCH_FIELDS, ...VOLATILITY_FIELDS, ...TECHNICAL_FIELDS, ...OPTION_VOLATILITY_FIELDS, ...OWNERSHIP_FIELDS, ...ATTENTION_FIELDS, ...HIRING_APP_FIELDS, ...KPI_FIELDS, ...DIVIDEND_FIELDS] as readonly string[]).includes(field))
         row.metrics[field] = PRO_FIELDS.has(field) ? withheldMetric() : unavailableMetric();
       const metric = row.metrics[field];
       if (