@gloom-sh/terminal 0.19.1 → 0.19.3

package/src/types/financials.ts

@@ -268,7 +268,8 @@ export interface TtmConversion {
 }
 
 /**
- * How a served enterprise value ties to market cap + total debt - cash from the latest balance sheet served beside it.
+ * How a served enterprise value ties to market cap + total debt (+ leases, `leases`) - cash from the latest balance sheet
+ * served beside it.
  * `matches` within 5%; `differs` beyond it (or beyond 2% on the other side of the market cap from net debt), within
  * 0.7x to 1.5x, shown labelled as the provider's; `withdrawn` outside that band, with no EV or EV/revenue; `unchecked`
  * without a recent balance sheet carrying both lines. `computed`: an insurer's or a holding company's EV, which is
@@ -284,15 +285,24 @@ export interface EnterpriseValueCheck {
   /** The market cap the EV is measured on; absent only on a not-meaningful source EV served without one. */
   marketCap?: number;
   totalDebt?: number;
+  /** The balance sheet's lease liabilities the bridge adds to total debt, as FA's net debt does (utils/lease-liabilities); absent when none were added. */
+  leases?: number;
   cash?: number;
   /** YYYY-MM-DD of the balance sheet the debt and cash come from. */
   balanceSheetDate?: string;
-  /** marketCap + totalDebt - cash. */
+  /** marketCap + totalDebt + leases - cash. */
   computed?: number;
   /** `cash` is cash and equivalents alone: an insurer's or a holding company's investments stay in its EV. */
   investmentsKept?: true;
-  /** Why the EV is not meaningful (`not-meaningful`). */
+  /** Why the EV is not meaningful (`not-meaningful`), or why a withdrawn EV no balance sheet checked is withdrawn. */
   reason?: string;
+  /** A balance sheet in another currency than the market cap: its currency and the rate at its date
+   * (`currency` per unit of `from`) that `totalDebt`, `leases` and `cash` were converted at. */
+  fx?: { from: string; rate: number };
+  /** The provider converted its EV from the statements' currency. */
+  convertedFrom?: string;
+  /** Withdrawn because the provider applied that conversion twice: its EV over `computed` is the conversion rate. */
+  convertedTwice?: true;
 }
 
 /** How a trailing P/E converts the EPS it divides by, when that EPS is in another currency than the price. */
@@ -481,6 +491,18 @@ interface AnalystRecommendationTrend {
   strongSell?: number;
 }
 
+/** Why a firm took an action, as public news coverage of it quotes the firm, word for word. */
+export interface AnalystRatingReason {
+  /** One line from the article, as it prints it. */
+  text: string;
+  /** The article. */
+  url: string;
+  /** Its publisher, when known. */
+  source?: string;
+  /** ISO time the article was published. */
+  publishedAt?: string;
+}
+
 export interface AnalystRatingRecord {
   date: string;
   firm: string;
@@ -489,6 +511,8 @@ export interface AnalystRatingRecord {
   prior?: string;
   currentPriceTarget?: number;
   priorPriceTarget?: number;
+  /** Absent when no coverage of the action gives a reason. */
+  reason?: AnalystRatingReason;
 }
 
 export interface AnalystEstimateRecord {
@@ -784,6 +808,11 @@ export interface FinancialStatement {
   date: string;
   /** Source of the fiscal period date; does not establish metric publication dates. */
   dateSource?: "sec" | "provider";
+  /**
+   * The accounting standard the issuer reports in, from the taxonomy of its latest annual report to the SEC (10-K,
+   * 20-F or 40-F): BABA's 20-F is US GAAP, NVO's IFRS. Absent for a company that files none with the SEC.
+   */
+  accountingStandard?: "us-gaap" | "ifrs";
   /** Original vendor period date when independent filing evidence changes it. */
   providerDate?: string;
   /** Filing evidence for the period identity only, not availability of every field. */
@@ -975,12 +1004,20 @@ export interface PricePoint {
    * or comparison with a day's count takes it.
    */
   venueVolume?: { venue: string; volume: number };
+  /**
+   * What the bar's volume counts, when the source says: `aggregate` for a
+   * total across venues (a coin's daily bar), `3 spot venues` for a sum over
+   * those (a coin's intraday bar).
+   */
+  volumeBasis?: string;
   /** The bar's period had not ended when it was served: its close is the latest price, and it may have no volume yet. */
   partial?: boolean;
   /** The bar's prices were rebuilt from shorter bars where the source left it empty or too coarse. */
   filled?: boolean;
   /** A future's session that has closed but whose settlement is not confirmed yet: its close is the last trade. */
   unsettled?: boolean;
+  /** A continuous future's bar (NG=F): the contract it closes on (NGZ26). A change from the bar before is a roll. */
+  contract?: string;
 }
 
 export interface StatementHistoryAttempt {

package/src/types/headless.ts

@@ -127,6 +127,8 @@ export interface HeadlessPaneContext {
   capabilities?: CapabilityInvoker;
   /** The catalog's name for the series charted as an expression (`FRED:DFII10`); undefined for one it does not list. */
   catalogSeriesName?: (expression: string) => string | undefined;
+  /** The catalog series a bare word is an alias of (`hashrate` is CAP:bitcoin:hashrate); undefined for any other word. */
+  catalogSeriesNamed?: (word: string) => { expression: string; name: string } | undefined;
   /** Locally registered broker adapters. Reports may read account data; they never submit orders. */
   resolveBroker?: (brokerType: string) => import("./broker").BrokerAdapter | null;
   /** Read one local portfolio without passing holdings through a remote endpoint. */
@@ -149,7 +151,9 @@ export interface HeadlessPaneContext {
    * `coinNote` is what `quote` says of a bare coin ticker read as a listing
    * that is not the coin (ETH, the Grayscale fund), for the report's warnings.
    */
-  resolveListing?: (symbol: string, argumentWith: (key: string) => string) => Promise<{ symbol: string; exchange?: string; name?: string; coinNote?: string } | null>;
+  resolveListing?: (symbol: string, argumentWith: (key: string) => string) => Promise<{ symbol: string; exchange?: string; name?: string; coinNote?: string;
+    /** What became of the company that had the symbol, as `quote` says it ("GOGL was Golden Ocean Group until 2025, now Cmb.Tech: CMBT"). */
+    successorNote?: string } | null>;
   /**
    * What a plugin keeps on this device only (its `ctx.resume` state, never
    * synced), such as ALRT's log of the alerts the app fired; null when none.
@@ -191,6 +195,13 @@ export interface HeadlessPaneColumn {
   stackRows?: number;
   /** The text table leaves the column out when fitted to fewer terminal columns than this; exports and piped output keep it. */
   minTableWidth?: number;
+  /**
+   * The narrow text table drops the column, rightmost first, before it moves any column under its rows: a figure
+   * the others imply (RETURN's interval $ beside its prices). Exports and a table that fits keep it.
+   */
+  optional?: boolean;
+  /** Among optional columns, a higher priority is dropped sooner. */
+  dropPriority?: number;
   description?: string;
   format?: (value: unknown, row: HeadlessPaneRow) => string;
   /** What the text report prints when it can say more than an export should (a unit word beside a number); CSV and NDJSON keep `format`. */
@@ -209,9 +220,10 @@ export interface HeadlessPaneColumn {
   /**
    * The text report prints the value on its own lines under the row instead
    * of in a column, for a footnote that belongs to that row; an empty value
-   * prints nothing. Exports keep it as a column.
+   * prints nothing. Exports keep it as a column. `"line"`: one line cut to
+   * the width, never wrapped (a story's summary under its headline).
    */
-  underRow?: boolean;
+  underRow?: boolean | "line";
 }
 
 export interface HeadlessPaneEntry {
@@ -284,6 +296,13 @@ export interface HeadlessPaneFreshness {
   delayMinutes?: number;
   /** What not-a-feed data is, in a few words: "filed data", "monthly release", "your inputs". */
   basis?: string;
+  /**
+   * The pane shows nothing from a market or a feed: the user's own notes and
+   * rules, the app's connections, documentation, an account. A screenshot's
+   * footer then carries no status line, which would date nothing or call the
+   * app's own state "not a live feed". `fn` still cites `source` and `basis`.
+   */
+  local?: boolean;
   /**
    * How often the data is published, when its dates mark the start of a period
    * (a monthly statistic is dated the 1st). The report then names the month,
@@ -403,12 +422,24 @@ export interface HeadlessPaneFreshness {
    * `newest story` dates a news list `newest story Tue 29 Sep 2026 20:17 UTC`.
    */
   asOfLabel?: string;
+  /**
+   * The newest observation is a bar of this many minutes that opens at the
+   * as-of: the line names its span, `last bar 15:00–16:00 UTC`, so the bar's
+   * open is not read as how far the data runs.
+   */
+  barMinutes?: number;
   /**
    * Say when the rows were retrieved too, after the newest one's date: a list
    * dated by its newest filing was not read then (`newest filing Tue 27 Oct
    * 2026 · retrieved Wed 28 Oct 2026 19:07 UTC`).
    */
   retrievedToo?: boolean;
+  /**
+   * When the source last read the data, when that is not now: a page the
+   * server reads hourly is retrieved when it read it, not when the report
+   * asked the server. An ISO instant; ignored when in the future.
+   */
+  retrievedAt?: string;
   /** What the figures are, said after the status: `funding = current estimate, pays 08:00 UTC`. */
   note?: string;
   /**
@@ -504,6 +535,13 @@ export interface HeadlessRowsResult extends HeadlessPaneResultBase {
 export type HeadlessBundleSection =
   | {
     title: string;
+    /**
+     * The heading the text report prints in place of `title`, when it can say
+     * more than an export's section name should (the scale its amounts are
+     * printed in, "Total revenue, USD millions"). JSON, CSV and NDJSON keep
+     * `title`, so a section read by its name stays where it was.
+     */
+    textTitle?: string;
     columns?: HeadlessPaneColumn[];
     rows: HeadlessPaneRow[];
     /** What the report says when `rows` is empty, in place of "No data.": why there are none, and what to run instead. */
@@ -576,6 +614,7 @@ export type HeadlessBundleSection =
     /** In a report with `exportDated`: the period the figures cover, and when they were released (an ISO date or instant), which each exported line names in `period` and `released`. */
     period?: string;
     released?: string;
+    textTitle?: never;
     columns?: never;
     rows?: never;
     textColumns?: never;

package/src/types/plugin.ts

@@ -183,7 +183,7 @@ export interface PaneDef {
    * `headless` model) cites, when "Gloom Cloud" with the state the footer
    * shows would be wrong: local data, a calculator, filed records.
    */
-  reportFreshness?: Pick<HeadlessPaneFreshness, "source" | "status" | "basis">;
+  reportFreshness?: Pick<HeadlessPaneFreshness, "source" | "status" | "basis" | "local">;
   /**
    * Options a rendered-view report takes (`fn OMON AAPL --strikes 10`):
    * each sets the pane setting of its key, is checked by its `normalize`, and
@@ -203,7 +203,14 @@ export interface PaneDef {
    * catalog lists it, and `fn` refuses an argument from a function that
    * declares none here, in its shortcut or in a `headless` model.
    */
-  reportArgument?: Pick<HeadlessPaneArgumentDef, "kind" | "placeholder" | "description" | "optional">;
+  reportArgument?: Pick<HeadlessPaneArgumentDef, "kind" | "placeholder" | "description" | "optional"> & {
+    /**
+     * The argument names something the pane opens by its own id (the story
+     * pane's story id), never a symbol: `fn` does not look it up as a ticker.
+     * A query (X Feed's) leaves it unset and keeps its ticker reading.
+     */
+    identifier?: boolean;
+  };
   /**
    * Lines a rendered-view report prints above its table, from the settings it
    * ran with: what the default view leaves out and how to see more. `--json`
@@ -220,6 +227,12 @@ export interface PaneDef {
    * for the symbol (`lock.context` reads it), so the note may resolve later.
    */
   reportLockNote?(lock: PaneLock): string | Promise<string>;
+  /**
+   * The sign-in wall covers the whole pane whenever there is no Gloom Cloud
+   * session (ASKG): a rendered-view report without one prints its
+   * `reportLockNote` at once rather than render the wall to read it.
+   */
+  signInWall?: boolean;
   /**
    * What a rendered-view report needs before it shows anything, such as a
    * sign-in: `gloom catalog` lists it under Requires, as it does a
@@ -540,6 +553,13 @@ export interface PaneTemplateDef {
   listed?: boolean;
   /** Template-specific headless model. Takes precedence over the pane-level model. */
   headless?: HeadlessPaneDefinition;
+  /**
+   * A one-ticker template whose pane also opens on several at once (DVD's
+   * ranking): `fn` and `shot` pass a typed list (`shot DVD KO JNJ`) to
+   * createInstance as `symbols`. Any other one-ticker template gets the list
+   * as it always has, in `symbol` and `arg`.
+   */
+  opensTickerList?: boolean;
   /**
    * Source and status of the view this template opens, for a template that
    * opens one view of a pane hosting several (Fixed Income's Issuer Debt).
@@ -547,9 +567,16 @@ export interface PaneTemplateDef {
    * `reportFreshness`: each field set here wins, the rest are the pane's. So
    * they date the filings on screen, not the issuer's stock quote.
    */
-  reportFreshness?: Pick<HeadlessPaneFreshness, "source" | "status" | "basis">;
+  reportFreshness?: Pick<HeadlessPaneFreshness, "source" | "status" | "basis" | "local">;
   wizard?: WizardStep[];
   canCreate?: (context: PaneTemplateContext, options?: PaneTemplateCreateOptions) => boolean;
+  /**
+   * Settings shown by catalog discovery without running createInstance. Supply
+   * these when opening a pane needs live data or has side effects. An empty
+   * object means there are no settings to describe before the pane is opened.
+   * When omitted, discovery derives settings from createInstance as before.
+   */
+  catalogSettings?: Record<string, unknown>;
   createInstance?: (
     context: PaneTemplateContext,
     options?: PaneTemplateCreateOptions,
@@ -962,6 +989,8 @@ export interface AppNotificationRequest {
     label: string;
     onClick: () => void;
   };
+  /** Runs once, when the in-app toast is first drawn. Not called when `toast` is false. */
+  onShown?: () => void;
 }
 
 export interface BrokerInstanceUpdateOptions {

package/src/ui/host.tsx

@@ -375,6 +375,17 @@ export interface ImageSurfaceProps extends BoxProps {
   src?: string;
   alt?: string;
   objectFit?: "contain" | "cover";
+  /**
+   * Draw `children` until the image has loaded, not only without a `src` or
+   * once it fails, so a box that waits on a picture shows its stand-in rather
+   * than an empty one. The terminal always does.
+   */
+  fallbackWhileLoading?: boolean;
+  /**
+   * A colour behind the picture once it has loaded (a logo made for a light
+   * page), never behind `children`. The terminal draws none.
+   */
+  imageBackground?: string;
 }
 export interface MediaSurfaceProps extends BoxProps {
   src?: string;
@@ -709,7 +720,12 @@ export interface SaveTextFileRequest {
 
 export interface RendererHost {
   requestExit(): void;
-  startWindowDrag?(): Promise<void> | void;
+  /**
+   * From a press on a title bar. `press.detail` counts the clicks: where the
+   * system's title bars maximize on a double-click, the second press does that
+   * instead of moving the window.
+   */
+  startWindowDrag?(press?: { detail?: number }): Promise<void> | void;
   controlWindow?(action: "minimize" | "toggle-maximize" | "close"): Promise<void> | void;
   /**
    * Opens a link in the person's browser. Resolves false when no browser could

package/src/ui/toast.tsx

@@ -1,4 +1,5 @@
-import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+import { createContext, useContext, useEffect, useRef, type ComponentType, type ReactNode } from "react";
+import { logFailure } from "../utils/log-failure";
 
 /** @public */
 export interface ToastAction {
@@ -14,6 +15,8 @@ export interface ToastOptions {
   action?: ToastAction;
   /** Rendered next to `action`. Use for a dismissing counterpart such as snooze. */
   secondaryAction?: ToastAction;
+  /** Runs once, after a viewport first draws the toast. */
+  onShown?(): void;
 }
 
 export interface ToastHost {
@@ -141,6 +144,28 @@ export function useToastHost(): ToastHost {
   return host;
 }
 
+/**
+ * Every viewport calls this with the toasts it draws: each toast's `onShown`
+ * runs once, after the commit that first puts it on screen.
+ */
+export function useToastsShown(toasts: readonly { id: number; options?: ToastOptions }[]): void {
+  const shown = useRef(new Set<number>());
+  useEffect(() => {
+    const current = new Set<number>();
+    for (const toast of toasts) {
+      current.add(toast.id);
+      if (shown.current.has(toast.id)) continue;
+      try {
+        toast.options?.onShown?.();
+      } catch (error) {
+        // One failing callback must not keep the others from running.
+        logFailure("toast", "A toast's shown callback failed")(error);
+      }
+    }
+    shown.current = current;
+  }, [toasts]);
+}
+
 export function ToastViewport(props: { position?: string }) {
   const { Viewport } = useToastHost();
   return <Viewport {...props} />;

package/src/utils/ascii-text.ts

@@ -0,0 +1,140 @@
+/**
+ * Text for a terminal that shows only ASCII: a C locale, or a Windows console
+ * on a legacy code page (437, 850, 1252), where UTF-8 bytes print as `—`.
+ * What the CLI writes itself keeps its meaning: a dash is `-`, the `·`
+ * between a source line's parts `|`, a price in euros `EUR211.25` (as one in
+ * kroner is `NOK393.90`) and one in US cents `447.50c`.
+ */
+
+/** Spelled out before single characters, so the yuan's `CN¥` is not read as the yen's `¥`. */
+const ASCII_SEQUENCES: ReadonlyArray<readonly [string, string]> = [
+  ["CN¥", "CNY"],
+  ["JP¥", "JPY"],
+];
+
+const ASCII_SPELLINGS: Readonly<Record<string, string>> = {
+  // Dashes and the minus sign.
+  "\u2012": "-", "\u2013": "-", "\u2014": "-", "\u2015": "-", "\u2212": "-",
+  // Separators and marks.
+  "\u00B7": "|", "\u2022": "*", "\u2026": "...", "\u00A6": "|",
+  // Currencies, as their codes; a minor unit as its letter.
+  "\u20AC": "EUR", "\u00A3": "GBP", "\u00A5": "JPY", "\u00A2": "c", "\u20B9": "INR", "\u20A9": "KRW", "\u20AA": "ILS",
+  "\u20AB": "VND", "\u20B1": "PHP", "\u20BA": "TRY", "\u20BD": "RUB", "\u20A6": "NGN", "\u20B4": "UAH", "\u20B8": "KZT",
+  "\u20BF": "BTC", "\u0E3F": "THB",
+  // Quotes and primes.
+  "\u2018": "'", "\u2019": "'", "\u201A": "'", "\u201C": "\"", "\u201D": "\"", "\u201E": "\"", "\u2032": "'", "\u2033": "\"",
+  "\u00AB": "\"", "\u00BB": "\"",
+  // Arithmetic.
+  "\u00D7": "x", "\u00F7": "/", "\u00B1": "+/-", "\u2248": "~", "\u2264": "<=", "\u2265": ">=", "\u2260": "!=", "\u00B0": "deg",
+  "\u00BC": "1/4", "\u00BD": "1/2", "\u00BE": "3/4", "\u2030": "per mille", "\u00B5": "u",
+  // Arrows and markers.
+  "\u2192": "->", "\u2190": "<-", "\u2191": "^", "\u2193": "v", "\u25B2": "^", "\u25BC": "v", "\u21B5": "Enter",
+  "\u2713": "ok", "\u2714": "ok", "\u2717": "x", "\u2715": "x",
+  // Box drawing.
+  "\u2502": "|", "\u2500": "-", "\u2503": "|", "\u2501": "-",
+  // Spaces.
+  "\u00A0": " ", "\u2009": " ", "\u202F": " ", "\u2007": " ", "\u2002": " ", "\u2003": " ",
+  // Letters that do not decompose.
+  "\u00DF": "ss", "\u00E6": "ae", "\u00C6": "AE", "\u0153": "oe", "\u0152": "OE", "\u00F8": "o", "\u00D8": "O",
+  "\u0111": "d", "\u0110": "D", "\u0142": "l", "\u0141": "L", "\u00FE": "th", "\u00DE": "Th", "\u0131": "i",
+  // Signs.
+  "\u2122": "(TM)", "\u00AE": "(R)", "\u00A9": "(C)",
+};
+
+const NON_ASCII = /[^\x00-\x7F]/;
+const COMBINING_MARKS = /[\u0300-\u036F]/g;
+
+/**
+ * `text` in ASCII: each character above with its spelling, an accented letter
+ * without its accent (Société Générale is Societe Generale), a box or block
+ * drawing character as `|`, `-`, `+` or `#`, and anything else as `?`.
+ * Escape sequences (colour) are ASCII and pass through.
+ */
+export function asciiText(text: string): string {
+  if (!NON_ASCII.test(text)) return text;
+  let folded = text;
+  for (const [sequence, spelling] of ASCII_SEQUENCES) folded = folded.split(sequence).join(spelling);
+  let out = "";
+  for (const character of folded) {
+    if (character.charCodeAt(0) < 0x80) {
+      out += character;
+      continue;
+    }
+    const spelled = ASCII_SPELLINGS[character];
+    if (spelled !== undefined) {
+      out += spelled;
+      continue;
+    }
+    const bare = character.normalize("NFD").replace(COMBINING_MARKS, "");
+    if (bare && !NON_ASCII.test(bare)) {
+      out += bare;
+      continue;
+    }
+    const code = character.codePointAt(0)!;
+    // Box drawing (U+2500-257F): corners and joins as +; block elements (U+2580-259F), a bar or sparkline's, as #.
+    out += code >= 0x2500 && code <= 0x257F ? "+" : code >= 0x2580 && code <= 0x259F ? "#" : "?";
+  }
+  return out;
+}
+
+type LocaleEnv = Readonly<Record<string, string | undefined>>;
+
+/**
+ * The locale text is written in, by the variable POSIX reads first (LC_ALL,
+ * then LC_CTYPE, then LANG; an empty one is unset), or null when none is set.
+ */
+function localeName(env: LocaleEnv): string | null {
+  return env.LC_ALL || env.LC_CTYPE || env.LANG || null;
+}
+
+/**
+ * Whether the terminal may not read UTF-8: a locale that names no UTF-8
+ * (`C`, `POSIX`, `en_US.ISO-8859-1`), or a Windows shell that sets none, whose
+ * console code page then decides (`consoleReadsUtf8`). A locale that is UTF-8,
+ * or none set elsewhere, is taken to read it.
+ */
+export function localeMayNotReadUtf8(env: LocaleEnv = process.env, platform: string = process.platform): boolean {
+  const locale = localeName(env);
+  if (locale) return !/utf-?8/i.test(locale);
+  return platform === "win32";
+}
+
+/**
+ * Where Windows keeps `chcp.com`. Windows looks a bare program name up in the
+ * current folder before the system's, so a `chcp.com` left in the folder a
+ * command runs in would run in its place; the full path never does.
+ */
+export function windowsChcpPath(env: Readonly<Record<string, string | undefined>> = process.env): string {
+  const root = [env.SystemRoot, env.SYSTEMROOT, env.windir, env.WINDIR]
+    .find((dir): dir is string => !!dir && /^[A-Za-z]:[\\/]/.test(dir)) ?? "C:\\Windows";
+  return `${root.replace(/[\\/]+$/, "")}\\System32\\chcp.com`;
+}
+
+/** The console's code page as `chcp` prints it ("Active code page: 437"), or null when it cannot be read. */
+function consoleCodePage(): number | null {
+  try {
+    if (typeof Bun === "undefined" || process.platform !== "win32") return null;
+    const answer = Bun.spawnSync([windowsChcpPath()], { stdout: "pipe", stderr: "ignore" });
+    const page = /(\d+)\D*$/.exec(answer.stdout.toString().trim());
+    return page ? Number(page[1]) : null;
+  } catch {
+    // Intentional ignore: a console whose code page cannot be read is left to show what it gets.
+    return null;
+  }
+}
+
+/**
+ * Whether the terminal reads UTF-8: by the locale when one is set, else on
+ * Windows by the console's code page (65001 is UTF-8). A code page that
+ * cannot be read is taken to read it, so nothing changes where it is unknown.
+ */
+export function localeReadsUtf8(
+  env: LocaleEnv = process.env,
+  platform: string = process.platform,
+  codePage: () => number | null = consoleCodePage,
+): boolean {
+  if (!localeMayNotReadUtf8(env, platform)) return true;
+  if (localeName(env)) return false;
+  const page = codePage();
+  return page == null || page === 65001;
+}