Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

55.3 KB
Raw Blame
/** @jsxImportSource @opentui/react */
/**
 * picker/ModelPicker.tsx — one inline dialog, one list, one cursor.
 *
 * WHAT THIS FILE IS A CORRECTION OF. The first build of this picker was a
 * full-screen two-pane dashboard: a provider rail beside a model list, a gradient
 * context meter and a gradient price meter on every row, an aggregate-distribution
 * panel, and a five-tier responsive column ladder to keep all of it on an
 * 80-column terminal. The owner's verdict, verbatim: *"no no no this is super
 * unclear what is happening, that should be dialog style"*. A three-model design
 * panel then voted unanimously that the form, not the engineering, was the defect.
 *
 * THE ROOT CAUSE IS MEASURABLE, WHICH IS WHY IT IS WORTH WRITING DOWN. The house
 * TUI guidance requires that over half of a whole frame be graphics rows. On a
 * screen whose content IS a list, a row counts as a graphics row only if it
 * carries a bar — so the gate did not permit a meter on every row, it REQUIRED
 * one. The result, measured on the rejected capture: of 32 visible rows 19 read
 * `1M`, and their meters were indistinguishable. The loudest element on the screen
 * carried the least information, and the aggregate panel above it was added (by
 * its own file header) pre-emptively to top up the same count. The gate is for
 * persistent monitoring surfaces. A picker is a one-shot question.
 *
 * THREE STRUCTURAL DECISIONS FOLLOW, and each one deletes a class of defect:
 *
 * 1. **Inline** (`screenMode: "main-screen"`). The shell prompt and the claudish
 *    banner stay on screen above the dialog. It reads as a program ASKING
 *    something rather than as a program that has taken the terminal, and the
 *    guidance's own `screenMode` table assigns inline to a one-shot command.
 * 2. **One list at a time, one cursor in it.** Two panes meant two cursors with
 *    only a border colour to say which one the arrow keys drove — the literal
 *    cause of "unclear what is happening".
 * 3. **No per-row graphics.** Plain aligned columns; colour reserved for meaning,
 *    one meaning each (`rows.tsx` lists them). The one meter left in the picker is
 *    the credential sweep's `done/total`, which is real progress over countable
 *    work.
 *
 * THE DEFAULT SCREEN IS THE PROVIDER LIST, AND NOTHING IS FETCHED BEFORE IT. An
 * intermediate build landed on a flat 574-row cross-provider list and warmed the
 * cloud catalog AND every credentialled provider's dynamic models catalog to fill it — a
 * `cloud catalog fetching…` screen with a `0/11 providers` discovery meter that the user had to
 * watch before he could do anything. The owner's three corrections, verbatim:
 * *"why we prefetching? we should not, as we show on demand"*, *"we should not
 * show the full list of models, we should show a list of providers by default and
 * only when we go inside we load and resolve all models"*, and *"we should not
 * show unsetted providers, just active"*. So:
 *
 *   · Startup does ONE thing: probe credentials, streaming each answer into the
 *     provider list as it settles. No catalog, no dynamic models catalog, no description index.
 *   · `⏎` on a provider fetches THAT provider's dynamic models catalog and shows it. The failure
 *     UX improves for free — a red panel now answers a request the user made.
 *   · `a` opens the cross-provider list, built from the ONE cached catalog fetch,
 *     enriched by whatever dynamic models catalogs he has already opened and by nothing else.
 *
 * NO AWAIT IS EVER SILENT, STRUCTURALLY RATHER THAN BY DILIGENCE. The provider list is
 * derived synchronously, so the first frame is complete before any effect runs;
 * every loader is an effect; and every in-flight task draws an affordance whose
 * SHAPE is chosen by what the caller can actually measure. Nothing invents a
 * denominator.
 *
 * CANCELLATION RETURNS A VALUE. Esc and Ctrl+C both call `onDone(null)`; nothing
 * here calls `process.exit`. The bootstrap's `finally` unmounts React and destroys
 * the renderer in that order, which is what restores the terminal with a fetch
 * still in flight.
 *
 * NO BRANDING IS DRAWN HERE. `printLogo` already wrote the wordmark, `Claude Code.
 * Any Model.` and the version to the scrollback before this renderer opened, and
 * inline mode keeps them on screen — so a second miniature wordmark inside the
 * dialog would be claudish reinventing a logo it already has. The dialog's title
 * bar is a panel title, not a mark.
 */

import { useKeyboard, useTerminalDimensions } from "@opentui/react";
import { type ReactNode, useEffect, useMemo, useState } from "react";
import type { ModelInfo } from "../model-selector.js";
import { EmptyState } from "../tui/components/EmptyState.js";
import { useAnimationFrame } from "../tui/hooks/useAnimationFrame.js";
import { truncate } from "../tui/viz/text.js";
import { tokens } from "../tui/viz/tokens.js";
import { DiscoveryNotice, discoveryNoticeContent, noticeRows } from "./DiscoveryNotice.js";
import {
  DISCOVERY_DEADLINE_MS,
  type DiscoveryShape,
  type PickerDataSource,
  type PickerProviderChoice,
} from "./PickerDataSource.js";
import { Dialog, FilterRow, Hints, type LoadTask, LoadTasks, Rule } from "./chrome.js";
import { DescriptionBlock, type ProviderFacts, ProviderLine, SelectionLine } from "./detail.js";
import { useModelDescriptions } from "./hooks/useModelDescriptions.js";
import {
  type PickerRow,
  dedupeByModelId,
  toPickerRow,
  usePickerModels,
} from "./hooks/usePickerModels.js";
import { type ProviderState, usePickerProviders } from "./hooks/usePickerProviders.js";
import { rowsFromOutcomes, useProviderDiscovery } from "./hooks/useProviderDiscovery.js";
import {
  deriveDialogLayout,
  deriveRowLayout,
  providerCellsFor,
  providerColumn,
  scrollWindow,
} from "./layout.js";
import { ColumnHeader, HintRow, ModelRow, ProviderRow, priceVaries } from "./rows.js";

/**
 * WHICH AFFORDANCE EACH IN-FLIGHT TASK EARNS — the honesty contract, as one pure
 * function so it can be asserted without a renderer.
 *
 * The credential sweep is the only task with a real denominator: the provider list is
 * derived synchronously, so `done/total` is work done over work TOTAL. The GET half
 * of discovery has a published DEADLINE and gets an elapsed-vs-deadline bar whose
 * label says `deadline`, because a deadline is not progress. Everything else gets an
 * elapsed figure and a shimmer, which claims only that time is passing.
 *
 * There is deliberately NO `resolving prices` task. `servedModels` resolves pricing
 * from the same local index the rows came from, so there is no second phase — and
 * drawing a label for a phase that never runs is the same lie as an invented
 * denominator.
 *
 * AND THERE IS NO PER-PROVIDER DISCOVERY TASK ANY MORE. It had the most defensible meter in
 * the file — a real `done/total` over the providers about to be asked — and it was
 * still wrong, because the work it measured was work nobody had asked for. A
 * truthful bar for an unwanted fan-out is a truthful answer to the wrong question.
 */
export function buildLoadTasks(input: {
  creds: { done: number; total: number } | null;
  catalog: boolean;
  modelsCatalog: { displayName: string; shape: DiscoveryShape; elapsed: number } | null;
}): LoadTask[] {
  const tasks: LoadTask[] = [];
  if (input.creds) {
    const { done, total } = input.creds;
    tasks.push({
      id: "creds",
      label: "credentials",
      pct: total > 0 ? (100 * done) / total : 0,
      value: `${done}/${total} checked`,
    });
  }
  if (input.catalog) tasks.push({ id: "catalog", label: "cloud catalog", value: "fetching…" });
  if (input.modelsCatalog) {
    const { displayName, shape, elapsed } = input.modelsCatalog;
    const secs = `${(elapsed / 1000).toFixed(1)}s`;
    tasks.push(
      shape === "deadline"
        ? {
            id: "discovery",
            label: displayName,
            pct: Math.min(100, (100 * elapsed) / DISCOVERY_DEADLINE_MS),
            value: `${secs} / ${(DISCOVERY_DEADLINE_MS / 1000).toFixed(1)}s deadline`,
          }
        : { id: "discovery", label: displayName, value: `discovering…  ${secs}` }
    );
  }
  return tasks;
}

export interface ModelPickerProps {
  source: PickerDataSource;
  /** A model spec, or `null` for cancelled. Called exactly once. */
  onDone: (spec: string | null) => void;
  /** Buffers a failed provider's diagnostic for the ONE write after teardown. */
  onDiscoveryFailure?: (provider: string, notice: readonly string[]) => void;
}

/**
 * Which dialog is on screen. ONE at a time, and one keyboard owner each — there is
 * never a second cursor to disambiguate.
 *
 * `providers` IS THE LANDING VIEW. `models` is reached by entering a provider
 * (`scope` set) or by asking for the cross-provider list (`scope` null); `esc`
 * from either comes back here, and `esc` HERE is what cancels the picker.
 */
type View = "models" | "providers" | "custom";

export function ModelPicker({ source, onDone, onDiscoveryFailure }: ModelPickerProps): ReactNode {
  const { width, height } = useTerminalDimensions();
  // THE ONLY WORK STARTUP DOES. Every other loader below is gated on a view the
  // user has actually opened.
  const providers = usePickerProviders(source);

  const [view, setView] = useState<View>("providers");
  const [filter, setFilter] = useState("");
  /**
   * `/` was pressed: every printable key types, INCLUDING `c` and `r`.
   *
   * It exists for exactly one case, and that case is real: a model id beginning
   * with one of the two letter commands — `codex`, `r1` — would navigate on its
   * first keystroke instead of filtering. `/` is the escape hatch the design
   * names, and it costs nothing when it is not needed: a filter with anything in
   * it already types every key.
   */
  const [typing, setTyping] = useState(false);
  const [custom, setCustom] = useState("");
  const [cursor, setCursor] = useState(0);
  const [providerCursor, setProviderCursor] = useState(0);
  /**
   * Are the providers with NO credential on screen?
   *
   * Off by default, on the owner's instruction: *"we should not show unsetted
   * providers, just active"*. They are not deleted — one summary row says how many
   * were left out and which key brings them back — because an unexplained absence
   * is the defect class this whole feature is about. A fact behind one keystroke is
   * reachable; fourteen `○ needs SOMETHING_API_KEY` rows in front of the four the
   * user can actually use are not.
   */
  const [revealKeyless, setRevealKeyless] = useState(false);
  /** `null` = the cross-provider list; a name = scoped to that provider. */
  const [scope, setScope] = useState<string | null>(null);

  const scopedChoice = providers.providerList.find((r) => r.value === scope) ?? null;
  const scopedName = scope === null ? "" : source.displayName(scope);
  const hasDiscovery = scopedChoice?.hasDiscovery === true;
  /**
   * DISCOVERY RUNS ONLY WHILE A PROVIDER'S OWN LIST IS OPEN — the `null` when the
   * view is not `models` is the on-demand rule, in one argument. Outcomes already
   * settled stay in `seen`, so coming back to a provider costs nothing and the
   * all-models view can reuse what has been fetched.
   */
  const discovery = useProviderDiscovery(
    source,
    view === "models" ? scope : null,
    hasDiscovery,
    onDiscoveryFailure
  );
  /** Dynamic models catalogs the user has already opened. No fetch — see `rowsFromOutcomes`. */
  const liveRows = useMemo(() => rowsFromOutcomes(discovery.seen), [discovery.seen]);

  /**
   * THE CATALOG IS FETCHED FOR THE VIEWS THAT READ IT, AND FOR NO OTHER.
   *
   * The cross-provider list is built from it, and so is a provider that does not
   * list its own dynamic models catalog. A discovery provider needs nothing from it — its rows come
   * from its own endpoint — unless discovery comes back `unsupported`, at which
   * point the catalog IS the list and the warm starts then.
   */
  const wantCatalog =
    view === "models" &&
    (scope === null || !hasDiscovery || discovery.outcome?.kind === "unsupported");
  const catalog = usePickerModels(
    source,
    providers.providerList,
    providers.readySet,
    liveRows,
    wantCatalog
  );
  const descriptions = useModelDescriptions(source, view === "models");

  /**
   * WHICH PROVIDERS ARE ON SCREEN, and the one number that explains the rest.
   *
   * Active first and always; the keyless ones are appended only when `k` has asked
   * for them, so the cursor's index into this array stays valid across the toggle
   * for every row that was already visible.
   */
  const keyless = providers.missing;
  /** Which local providers are opt-in-and-not-opted-into — `unavailableNote`'s oracle. */
  const notEnabledLocal = useMemo(
    () => new Set(providers.notEnabledLocal),
    [providers.notEnabledLocal]
  );
  const providerPool: ProviderState[] = revealKeyless
    ? [...providers.ready, ...keyless]
    : providers.ready;
  /**
   * The provider list's own filter — SAME IDIOM AS THE MODEL LIST, same state.
   *
   * It used to have none, on the grounds that 17 named rows do not need narrowing.
   * The owner asked for it anyway — *"we need inline search in list of providers as
   * well"* — and the reason it is the same `filter`/`typing` pair rather than a second
   * one is that a picker with two search boxes has two sets of rules to learn. The
   * state cannot leak between the views: every transition INTO a model list clears it
   * explicitly, and `esc` out of a model list clears it before it goes back.
   *
   * IT MATCHES ON THE NAME AND THE SHORTCUT, which are the two things on the row that
   * a user would type — `kimi` and `kc@` both have to reach Kimi Coding. The shortcut
   * is matched by PREFIX (as the model list matches it) so `k` does not pull in every
   * provider with a `k` somewhere in its slug.
   */
  const providerRows: ProviderState[] = matchProviders(providerPool, filter);

  /**
   * A MODEL COUNT ONLY WHERE ONE IS ACTUALLY KNOWN — the owner's rule: *"we could
   * not show number of models for some of them"*.
   *
   * Two sources, both already in hand and neither of them a fetch this map causes.
   * A dynamic models catalog the user opened is the truest answer for that provider, so it wins;
   * the catalog answers for the rest, but ONLY once the user has asked for a view
   * that warmed it. A provider in neither set gets `null`, which `ProviderRow`
   * prints as nothing at all.
   */
  const counts = useMemo((): ReadonlyMap<string, number> => {
    const known = new Map<string, number>();
    for (const [name, rows] of liveRows) known.set(name, new Set(rows.map((m) => m.id)).size);
    if (catalog.phase === "ready") {
      for (const [name, n] of catalog.counts) if (!known.has(name)) known.set(name, n);
    }
    return known;
  }, [liveRows, catalog.counts, catalog.phase]);

  // ── which list is on screen, and where it came from ──────────────────────────
  //
  // PROVENANCE IS A PROPERTY OF THE LIST, NOT OF A ROW. One value decides all three
  // encodings — the dialog's status title, the per-row `catalog` mark and the
  // banner's provenance sentence — so they cannot disagree with each other.
  //
  // The UNSCOPED list is catalog-derived too, and is deliberately NOT marked. A
  // mark means "the dynamic models catalog was asked for and could not be had"; nothing asked
  // for a dynamic models catalog here, so marking every row would spend the loudest signal in
  // the feature on the ordinary case and teach the reader to ignore it.
  // ONE ROW PER MODEL INSIDE A PROVIDER, N ROWS ACROSS PROVIDERS. The owner stated
  // the rule: *"if model has more than one provider that going to be two lines in
  // 'all models' list. and if we enter to provider catalog, not all models — then
  // the model will be just one"*. The flat list's identity is `(provider, modelId)`
  // and `usePickerModels` applies it; every scoped branch below goes through
  // `dedupeByModelId`, so a dynamic models catalog overlapping the catalog for the SAME
  // provider cannot show the same model twice.
  const list = useMemo((): { rows: RowView[]; fallback: boolean; loading: boolean } => {
    if (scope === null) {
      return { rows: catalog.rows, fallback: false, loading: catalog.phase !== "ready" };
    }
    // A DYNAMIC MODELS CATALOG AND A CATALOG LIST GO THROUGH THE SAME ROW BUILDER, so a
    // fallback list cannot be distinguishable by accident — a different price
    // string or a different spec spelling — instead of by the three deliberate
    // provenance encodings.
    const project = (rows: ModelInfo[]): RowView[] =>
      scopedChoice === null ? [] : dedupeByModelId(rows.map((m) => toPickerRow(scopedChoice, m)));
    const scoped = dedupeByModelId(catalog.rows.filter((r) => r.provider === scope));
    if (!hasDiscovery) return { rows: scoped, fallback: false, loading: catalog.phase !== "ready" };
    const o = discovery.outcome;
    if (o === null) return { rows: [], fallback: false, loading: true };
    if (o.kind === "rows") return { rows: project(o.rows), fallback: false, loading: false };
    if (o.kind === "unsupported") return { rows: scoped, fallback: false, loading: false };
    return { rows: project(o.fallbackRows), fallback: true, loading: false };
  }, [scope, scopedChoice, hasDiscovery, discovery.outcome, catalog.rows, catalog.phase]);

  /**
   * The provider cell for every provider on screen — collision-proof by
   * construction, and computed from the PROVIDER LIST rather than from the rows so the
   * column does not change width as dynamic models catalogs merge in behind the cursor.
   */
  // The column budget depends only on the TERMINAL, never on the banner — a
  // banner takes rows, not columns — so it is derived from a base layout here and
  // stays put while a notice appears and disappears above the list.
  const providerCells = providerCellsFor(deriveDialogLayout(width, height).inner, list.fallback);
  const column = useMemo(
    () => providerColumn(providers.providerList, truncate, providerCells),
    [providers.providerList, providerCells]
  );
  /** Provider → its WHOLE display name, for the filter and the detail line. */
  const labels = useMemo(
    () => new Map(providers.providerList.map((r) => [r.value, r.label])),
    [providers.providerList]
  );
  /** Provider → what it IS: how it bills, and the credential it wants. */
  const facts = useMemo(
    () => new Map<string, ProviderFacts>(providers.providerList.map((r) => [r.value, factsOf(r)])),
    [providers.providerList]
  );

  const shown = useMemo(() => {
    const needle = filter.trim().toLowerCase();
    if (!needle) return list.rows;
    // THREE THINGS MATCH, and the readable NAME is one of them — the column now
    // prints `OpenRouter`, so typing `openr` must narrow to it or the filter
    // contradicts the screen. The shortcut still matches (`kc` reaches Kimi
    // Coding in three keystrokes, which is how provider scoping survived the
    // rail's deletion) and so does the model id.
    return list.rows.filter(
      (r) =>
        r.model.id.toLowerCase().includes(needle) ||
        r.shortcut.toLowerCase().startsWith(needle) ||
        (labels.get(r.provider) ?? "").toLowerCase().includes(needle)
    );
  }, [list.rows, filter, labels]);

  // ── in-flight affordances ───────────────────────────────────────────────────
  //
  // `catalog.phase === "loading"`, NEVER `!== "ready"`. The third state is `idle`,
  // which is what the catalog is on the provider list — not fetching, not fetched,
  // and not wanted. Drawing a `cloud catalog fetching…` row for it would put the
  // owner's own complaint back on the landing screen with no request behind it.
  const busy = providers.probing || catalog.phase === "loading" || discovery.busy;
  const frame = useAnimationFrame(busy);
  const tasks = buildLoadTasks({
    creds: providers.probing ? { done: providers.done, total: providers.total } : null,
    catalog: catalog.phase === "loading",
    modelsCatalog:
      discovery.busy && scope !== null
        ? {
            displayName: scopedName,
            shape: scopedChoice?.discoveryShape ?? "none",
            elapsed: discovery.startedAt === null ? 0 : Date.now() - discovery.startedAt,
          }
        : null,
  });
  // The loading DIALOG replaces the list only while there is nothing to show at
  // all. Once rows exist the list wins and the pending work drops to a footer
  // note: "models appear as soon as they are ready" is a promise the screen has to
  // keep, and a spinner in front of a usable list breaks it.
  const phase: "loading" | "list" = tasks.length > 0 && list.rows.length === 0 ? "loading" : "list";

  // ── layout ──────────────────────────────────────────────────────────────────
  const notice =
    scope !== null && discovery.outcome !== null
      ? discoveryNoticeContent(discovery.outcome, scopedName)
      : null;
  const base = deriveDialogLayout(width, height);
  const bannerRows =
    notice === null
      ? 0
      : noticeRows(notice, Math.max(8, base.inner - 2), MAX_BANNER_ROWS).lines.length;
  const layout = deriveDialogLayout(width, height, bannerRows);
  /**
   * IS THE PROVIDER COLUMN WORTH ITS CELLS HERE?
   *
   * In the cross-provider list it is the whole point — the same model id appears on
   * three providers and the column is what tells them apart. Inside a provider it
   * prints one repeated name under a dialog titled with that same name: 49 rows of
   * `OpenAI Codex` under `OpenAI Codex`, eating the columns the model id wants. The
   * owner said so from a live run. One flag through `deriveRowLayout`, so the header
   * and the rows cannot disagree about whether the cell exists.
   */
  const showProviderColumn = scope === null;
  /**
   * DOES THE PRICE COLUMN EARN CHIPS? Only where it VARIES — see `rows.tsx`. A
   * flat-rate or local provider answers the same word for every row, and a column of
   * identical fills is the solid rectangle the skill measured.
   */
  const chipPrices = priceVaries(scope === null ? null : (scopedChoice?.billing ?? null));
  // `column.cells`, not `providerCells`: a collision may have WIDENED the column
  // past what the row budgeted, and the header and the rows must agree whichever
  // number won.
  const rowLayout = deriveRowLayout(layout.inner, {
    mark: list.fallback,
    ...(showProviderColumn ? { providerCells: column.cells } : { provider: false }),
  });

  // The cursor can outlive the list it indexed — a filter keystroke, or a scope
  // whose dynamic models catalog came back shorter than the last one's.
  useEffect(() => {
    setCursor((c) => Math.max(0, Math.min(c, Math.max(0, shown.length - 1))));
  }, [shown.length]);
  // The SAME hazard on the provider list, from two directions: `k` folds fourteen
  // rows away under the cursor, and the list GROWS as probes settle under it.
  useEffect(() => {
    setProviderCursor((c) => Math.max(0, Math.min(c, Math.max(0, providerRows.length - 1))));
  }, [providerRows.length]);

  const top = scrollWindow(cursor, shown.length, layout.listRows);
  const window = shown.slice(top, top + layout.listRows);
  const selected = shown[cursor] ?? null;

  // ── keys: ONE handler, because `useKeyboard` is a BROADCAST ─────────────────
  //
  // Every mounted subscriber receives every key — no bubbling, no
  // `stopPropagation` — so mutual exclusion is hand-rolled. Here it is trivial,
  // because there is one view at a time and one cursor in it.
  //
  // FILTER-FIRST, WITH ONE ESCAPE HATCH. In the model view every printable key
  // that is not a bound command types into the filter immediately — there is no
  // search MODE to enter, which is one fewer thing the reader has to know before
  // the screen does anything. The commands that survive are the ones a filter
  // cannot express (`esc`, `enter`, the arrows) plus TWO letters, and those two are
  // live ONLY while the filter is empty and `/` has not been pressed: once anything
  // is typed they are letters again, because a user typing `codex` must get `codex`
  // and not the custom-spec dialog.
  //
  // THE PROVIDER LIST NOW TAKES THE SAME FILTER, UNDER THE SAME RULE. It used to
  // have none — its letters (`a`, `k`, `c`) were always commands, which was
  // affordable because 17 named rows do not need narrowing — and the owner asked for
  // one anyway: *"we need inline search in list of providers as well"*. Making it a
  // SECOND interaction would have been the mistake: one filter idiom, one set of
  // rules, applied on both screens. So `a`/`k`/`c` are live only while the filter is
  // empty, `/` is the escape hatch, and `esc` clears before it leaves.
  useKeyboard((key) => {
    const name = key.name;
    if (key.ctrl && name === "c") {
      onDone(null);
      return;
    }

    if (view === "custom") {
      if (name === "escape") {
        setView("models");
        return;
      }
      if (name === "return" || name === "enter") {
        const spec = custom.trim();
        if (spec) onDone(spec);
        return;
      }
      if (name === "backspace") {
        setCustom((v) => v.slice(0, -1));
        return;
      }
      if (printable(key.raw)) setCustom((v) => v + key.raw);
      return;
    }

    if (view === "providers") {
      // THE LANDING VIEW OWNS CANCEL — BUT THE FILTER COMES FIRST, which is the model
      // list's rule applied unchanged. `esc` goes one step back everywhere else in
      // this picker; here the step back is the filter while there is one, and only
      // then does `esc` return `null`. Two screens, one meaning for the key.
      if (name === "escape") {
        if (filter !== "" || typing) {
          setFilter("");
          setTyping(false);
          setProviderCursor(0);
          return;
        }
        onDone(null);
        return;
      }
      if (name === "up" || name === "down") {
        const d = name === "up" ? -1 : 1;
        setProviderCursor((c) => Math.max(0, Math.min(providerRows.length - 1, c + d)));
        return;
      }
      if (name === "pageup" || name === "pagedown") {
        const d = (name === "pageup" ? -1 : 1) * layout.listRows;
        setProviderCursor((c) => Math.max(0, Math.min(providerRows.length - 1, c + d)));
        return;
      }
      if (name === "home") {
        setProviderCursor(0);
        return;
      }
      if (name === "end") {
        setProviderCursor(Math.max(0, providerRows.length - 1));
        return;
      }
      if (name === "return" || name === "enter") {
        // ENTERING A PROVIDER IS WHAT FETCHES ITS DYNAMIC MODELS CATALOG. Nothing before this
        // keystroke asked that endpoint anything.
        const chosen = providerRows[providerCursor];
        if (chosen) {
          setScope(chosen.value);
          setFilter("");
          setTyping(false);
          setCursor(0);
          setView("models");
        }
        return;
      }
      if (name === "backspace") {
        setFilter((v) => v.slice(0, -1));
        setProviderCursor(0);
        return;
      }
      // THE THREE LETTER COMMANDS ARE LIVE ONLY WHILE THE FILTER IS EMPTY, which is
      // the model list's rule and it is load-bearing here for the same reason: a user
      // narrowing to `claude` must get `claude` and not the custom-spec dialog on the
      // `c`. `/` is the escape hatch for a search that STARTS with one of them.
      const providerCommands = filter === "" && !typing;
      if (providerCommands && key.raw === "a") {
        setScope(null);
        setFilter("");
        setTyping(false);
        setCursor(0);
        setView("models");
        return;
      }
      if (providerCommands && key.raw === "k") {
        setRevealKeyless((v) => !v);
        return;
      }
      if (providerCommands && key.raw === "c") {
        setView("custom");
        return;
      }
      if (key.raw === "/") {
        // Not inserted: `/` FOCUSES the filter, which here means "stop treating
        // a / k / c as commands". See `typing`.
        setTyping(true);
        return;
      }
      if (printable(key.raw)) {
        setFilter((v) => v + key.raw);
        setProviderCursor(0);
      }
      return;
    }

    if (name === "escape") {
      if (filter !== "" || typing) {
        setFilter("");
        setTyping(false);
        setCursor(0);
        return;
      }
      // ONE WAY BACK, AND IT IS THE SAME ONE FROM BOTH MODEL LISTS. A scoped list
      // and the cross-provider list are both something the user OPENED from the
      // provider list, so `esc` returns him to it rather than quitting — quitting
      // is `esc` there, or Ctrl+C anywhere.
      setView("providers");
      return;
    }
    if (name === "up" || name === "down") {
      const d = name === "up" ? -1 : 1;
      setCursor((c) => Math.max(0, Math.min(shown.length - 1, c + d)));
      return;
    }
    if (name === "pageup" || name === "pagedown") {
      const d = (name === "pageup" ? -1 : 1) * layout.listRows;
      setCursor((c) => Math.max(0, Math.min(shown.length - 1, c + d)));
      return;
    }
    if (name === "home") {
      setCursor(0);
      return;
    }
    if (name === "end") {
      setCursor(Math.max(0, shown.length - 1));
      return;
    }
    if (name === "return" || name === "enter") {
      if (selected) onDone(selected.spec);
      return;
    }
    if (name === "backspace") {
      setFilter((v) => v.slice(0, -1));
      setCursor(0);
      return;
    }
    const commandsLive = filter === "" && !typing;
    if (commandsLive && key.raw === "c") {
      setView("custom");
      return;
    }
    if (commandsLive && key.raw === "r" && scope !== null && hasDiscovery) {
      discovery.retry(scope);
      return;
    }
    if (key.raw === "/") {
      // Not inserted: `/` FOCUSES the filter, which here means "stop treating
      // c / r as commands". See `typing`.
      setTyping(true);
      return;
    }
    if (printable(key.raw)) {
      setFilter((v) => v + key.raw);
      setCursor(0);
    }
  });

  // ── the three dialogs ───────────────────────────────────────────────────────
  //
  // `key={view}-{phase}` FORCES A REMOUNT WHEN THE TREE CHANGES SHAPE. Inline mode
  // reserves rows by scrolling the main screen, and OpenTUI's in-place
  // reconciliation tore the panel when the chrome below a banner changed shape
  // (`probe-tui-app.tsx:1455-1462` records the same failure and the same cure). A
  // loading dialog flipping to a list dialog is exactly that transition.

  if (view === "custom") {
    return (
      <Centred width={width} height={height}>
        <Dialog
          key="custom"
          title="type a model spec"
          status="provider@model"
          width={layout.width}
          marginLeft={0}
        >
          <box height={1} flexShrink={0}>
            <text>
              <span fg={tokens.accent}>{"› "}</span>
              <span fg={tokens.text}>{custom}</span>
              <span fg={tokens.accent}>▍</span>
            </text>
          </box>
          <box height={1} flexShrink={0}>
            <text>
              <span fg={tokens.subtle}>
                {"e.g. or@openai/gpt-5, kc@kimi-k3, [email protected] — anything argv accepts"}
              </span>
            </text>
          </box>
          <Rule />
          <Hints
            hints={[
              { key: "⏎", label: "launch it", on: custom.trim() !== "" },
              { key: "esc", label: "back" },
            ]}
          />
        </Dialog>
      </Centred>
    );
  }

  if (view === "providers") {
    const settled = !providers.probing;
    // Taller than the model list's list: this dialog spends no column header and no
    // description block, and the rows it spends instead — the scroll position and the
    // credential sweep — are rendered blank rather than dropped, so the list does not
    // shift under the cursor when a sweep finishes or `k` is pressed.
    const windowRows = layout.listRows;
    const providerTop = scrollWindow(providerCursor, providerRows.length, windowRows);
    const providerWindow = providerRows.slice(providerTop, providerTop + windowRows);
    const here = providerRows[providerCursor] ?? null;
    return (
      <Centred width={width} height={height}>
        <Dialog
          key={`providers-${providerRows.length === 0 ? "empty" : "list"}`}
          title="choose a provider"
          status={
            settled
              ? `${providers.ready.length} of ${providers.total} have credentials`
              : `${providers.ready.length} ready · ${providers.done}/${providers.total} checked`
          }
          width={layout.width}
          marginLeft={0}
        >
          {/* THE SAME FILTER ROW THE MODEL LIST CARRIES, in the same place, with the
              same `matches of total` on the right. It is always rendered, blank
              prompt and all, because a search box that appears when you start typing
              cannot be found by someone who does not know it is there.
              `idle=""` — this list is not SORTED, it is in the curated picker order,
              so there is no `newest first` to claim here. That the model list's
              caption is the one string separating the two views in a frame capture
              (`listPainted`) is a happy consequence, not the reason. */}
          <FilterRow
            value={filter}
            matches={providerRows.length}
            total={providerPool.length}
            width={layout.inner}
            idle=""
          />
          {/* TWO ROWS WHEN IT IS EMPTY, because `EmptyState` with a hint IS two
              rows and a one-row box would overprint the second onto the row
              below it. */}
          <box
            flexDirection="column"
            height={Math.min(
              windowRows,
              Math.max(providerWindow.length === 0 ? 2 : 1, providerWindow.length)
            )}
            flexShrink={0}
            overflow="hidden"
          >
            {providerWindow.length === 0 ? (
              <EmptyState
                label={
                  filter !== ""
                    ? `no provider matches “${filter}”`
                    : settled
                      ? `no credential for any of the ${providers.total} providers`
                      : "checking which providers you have credentials for…"
                }
                {...(filter !== ""
                  ? { hint: "esc clears the filter" }
                  : settled
                    ? { hint: "k shows what each one needs" }
                    : {})}
              />
            ) : (
              providerWindow.map((r) => (
                <ProviderRow
                  key={r.value}
                  label={r.label}
                  shortcut={r.shortcut}
                  readiness={r.readiness}
                  billing={r.billing}
                  count={counts.get(r.value) ?? null}
                  hasDiscovery={r.hasDiscovery}
                  note={unavailableNote(r, notEnabledLocal)}
                  cursor={r.value === here?.value}
                  inner={layout.inner}
                />
              ))
            )}
          </box>
          {/* A list that silently stops is the same unexplained absence this
              feature exists to remove. */}
          <HintRow
            text={
              providerRows.length > providerWindow.length
                ? `${providerCursor + 1} of ${providerRows.length} — ↑↓ for more`
                : ""
            }
            width={layout.inner}
          />
          {/* THE TWO SUMMARY LINES THAT WERE HERE ARE GONE, on the owner's
              instruction — *"remove this, 5 lines which has no value"*. They were
              `+14 more need a key · k` and `ollama, lmstudio, vllm, mlx — local, not
              enabled in your config`.
              WHAT THEY WERE FOR SURVIVES, WHICH IS THE ONLY REASON THEY COULD GO.
              They existed so a dropped provider was an EXPLAINED absence rather than
              a silent one, and the explanation has simply moved somewhere better: the
              footer's `[k][show]` is the way in, and each revealed row now states its
              OWN reason in its tail — `needs MOONSHOT_API_KEY` for a missing
              credential, `not enabled in config` for a local provider that is opt-in
              (`unavailableNote`). A per-row reason is strictly more information than
              one counted summary, and it costs no rows at all when nothing is hidden.
              At 80×24 those two rows were 2 of the 13 the dialog has. */}
          {/* THE ONE METER IN THE PICKER, on the one screen that waits for anything.
              It is `done/total` over a provider list derived synchronously — real progress
              over countable work — and it disappears, leaving its row, when the last
              probe settles. */}
          {settled ? (
            <HintRow text="" width={layout.inner} />
          ) : (
            <LoadTasks
              tasks={tasks}
              frame={frame}
              labelWidth={12}
              barWidth={Math.max(8, Math.min(22, layout.inner - 40))}
            />
          )}
          <Rule />
          {/* The SAME line the model list carries, plus the count when one is
              known — so "what is this provider" has one answer wherever it is
              asked. */}
          <ProviderLine
            facts={here === null ? null : factsOf(here)}
            width={layout.inner}
            count={here === null ? null : (counts.get(here.value) ?? null)}
          />
          <Hints
            hints={[
              // `↑↓ move` IS THE HINT THIS ROW GAVE UP TO ANNOUNCE THE FILTER, and
              // the arithmetic is why rather than taste: MEASURED with `hintsWidth`,
              // this row was 70 cells against the 72 the dialog has at 80 columns, and
              // `/ filter` costs 11 more. `Hints` sets `overflow="hidden"`, so the
              // overflow would have been a silently clipped `esc qu` — the exact
              // failure the model list's footer already shipped once.
              //
              // Of the six, the arrows are the one hint that says what every list in
              // the program already does, and the ONE thing on this screen a reader
              // cannot guess is now the `/` prompt sitting above the list saying
              // nothing about itself. A test pins that putting `↑↓ move` back
              // overflows, so this stays a measurement and not a preference.
              { key: "⏎", label: "open", on: here !== null },
              { key: "/", label: "filter" },
              { key: "a", label: "all models" },
              // `show` / `hide`, NOT `needs key` — AND THE SHORTENING IS WHAT PAID FOR
              // THE PILLS. A keycap is two filled segments now (`chrome.tsx`), which
              // costs one cell per hint, and MEASURED at 80 columns the row ran three
              // cells past the 72 the dialog has: `esc quit` rendered as `esc qu`.
              //
              // This is the label that could shrink without losing anything, because
              // `needs key` DUPLICATED the row that used to sit directly above it.
              // That row is gone now and the duplication argument with it — but the
              // reason it names is not lost, it moved ONTO the revealed rows
              // (`unavailableNote`), which say it per provider and say it precisely.
              // (`keyless` was the label before that and said the OPPOSITE of what it
              // meant: these providers need a key, which is precisely why they are
              // hidden.)
              { key: "k", label: revealKeyless ? "hide" : "show", on: keyless.length > 0 },
              { key: "c", label: "custom" },
              // `clear`, then `quit` — the model list's exact rule. `esc` is one step
              // back and the filter is the first step there is.
              { key: "esc", label: filter !== "" ? "clear" : "quit" },
            ]}
          />
        </Dialog>
      </Centred>
    );
  }

  if (phase === "loading") {
    return (
      <Centred width={width} height={height}>
        <Dialog
          key="loading"
          title={scope === null ? "all models" : scopedName}
          status="finding models…"
          width={layout.width}
          marginLeft={0}
        >
          {/* NO SECOND LINE. It said `models appear as soon as they are ready`, which
              is a sentence about time passing: it names no operation, gives the reader
              nothing to act on, and would be equally true of any loading screen ever
              drawn. The owner's verdict was *"that text is silly"*.
              The information it was standing in for is already on the frame, said
              precisely and said live — the dialog title names the provider, `status`
              names the operation (`finding models…`), and each `LoadTasks` row names
              the request and its elapsed time or deadline. A line under that could
              only repeat one of them. */}
          <LoadTasks
            tasks={tasks}
            frame={frame}
            labelWidth={14}
            barWidth={Math.max(8, Math.min(22, layout.inner - 40))}
          />
          <Rule />
          <Hints hints={[{ key: "esc", label: "back" }]} />
        </Dialog>
      </Centred>
    );
  }

  // THE COUNT IS COMPUTED THE WAY IT IS LABELLED, and the two views count
  // differently because their rows mean different things. The flat list holds one
  // row per ROUTE — a model on three providers is three rows — so calling that
  // number "models" would be a claim about the catalog that is off by the exact
  // amount the list is useful. Both numbers are printed: the models are what the
  // reader is choosing between, the routes are why the same name appears twice. A
  // provider view has one route in scope, so its rows ARE models and it says so.
  const status =
    scope === null
      ? `${countModels(list.rows)} models · ${list.rows.length} routes · ${providers.ready.length}/${providers.total} providers`
      : (notice?.title ?? `${list.rows.length} models`);

  // THE CROSS-PROVIDER LIST IS LABELLED AS WHAT IT IS. It used to be the screen the
  // picker opened on, so `choose a model` was the whole dialog's purpose; it is now
  // one of the two things a provider list can open, and the other one is titled with
  // its provider's name. `all models` says which of the two you are looking at.
  return (
    <Centred width={width} height={height}>
      <Dialog
        key="models"
        title={scope === null ? "all models" : scopedName}
        status={status}
        width={layout.width}
        marginLeft={0}
      >
        {/* The banner sits ABOVE the rows it qualifies, never below them: the eye
            goes to the list, and a warning under a healthy-looking list is a warning
            nobody reads. That is the user's own report, verbatim. */}
        {discovery.outcome === null ? null : (
          <DiscoveryNotice
            outcome={discovery.outcome}
            displayName={scopedName}
            width={Math.max(8, layout.inner - 2)}
            maxRows={MAX_BANNER_ROWS}
          />
        )}

        {/* `idle=""` when the provider published its own order (Antigravity's
            `agentModelSorts`): the rows are not sorted, so `newest first` would
            be false — the same reason the provider list passes it. */}
        <FilterRow
          value={filter}
          matches={shown.length}
          total={list.rows.length}
          width={layout.inner}
          idle={
            discovery.outcome?.kind === "rows" && discovery.outcome.providerOrdered ? "" : undefined
          }
        />
        <ColumnHeader layout={rowLayout} />

        {/* CONTENT-SIZED, CAPPED — never `flexGrow`. A four-row Kimi fallback makes a
            short dialog; it does not make a tall dialog with fifteen rows of unpainted
            background in it, which is what the rejected full-screen build did and what
            the reader read as "this provider has nothing". The cap is `listRows`, and
            the banner's rows have already come out of it, so the box is bounded above
            in every state. */}
        <box
          flexDirection="column"
          height={Math.min(
            layout.listRows,
            Math.max(window.length === 0 && filter !== "" ? 2 : 1, window.length)
          )}
          flexShrink={0}
          overflow="hidden"
        >
          {window.length === 0 ? (
            <EmptyState
              label={emptyLabel(list.loading, filter, list.rows.length, scopedName, providers)}
              {...(filter === "" ? {} : { hint: "esc clears the filter" })}
            />
          ) : (
            window.map((r, i) => (
              <ModelRow
                key={r.spec}
                model={r.model}
                providerLabel={column.text.get(r.provider) ?? r.shortcut}
                price={r.price}
                layout={rowLayout}
                cursor={top + i === cursor}
                origin={list.fallback ? "catalog" : "discovered"}
                chip={chipPrices}
              />
            ))
          )}
        </box>

        {/* ONE status row, ALWAYS rendered — see `CHROME_ROWS`. It carries the
            scroll position when the list overflows, then whatever is still in
            flight, then nothing. There is no aggregate failure line any more:
            with the fan-out gone, the only dynamic models catalog that can fail is one the user
            opened, and that one gets the banner above this list. */}
        <HintRow
          text={statusRow(cursor, shown.length, window.length, tasks)}
          width={layout.inner}
        />

        <Rule />
        {/* THREE ROWS ON THE PANEL'S OWN BACKGROUND. They recede by their INK — a
            fill here was rejected on sight, and `Rule` above is already the
            separator a fill would have been a second copy of (`detail.tsx`). */}
        <SelectionLine
          model={selected?.model ?? null}
          spec={selected?.spec ?? null}
          width={layout.inner}
        />
        <ProviderLine
          facts={selected === null ? null : (facts.get(selected.provider) ?? null)}
          width={layout.inner}
        />
        <DescriptionBlock
          text={
            selected === null ? "" : descriptionOf(selected, descriptions.get.bind(descriptions))
          }
          width={layout.inner}
        />
        {/* ONE KEY PER ACTION, AND EVERY ACTION IN THE ROW. `p` is gone: `esc` is
            the way back to the provider list from both model lists, and a second
            key for the one destination bought nothing while costing the row the
            columns `r retry` needs at 80.

            `back`, NOT `providers`, AND THE SIX-HINT ROW IS WHY. A keycap is a pill
            of two fills now (`chrome.tsx`) and costs one cell more per hint, so with
            `r retry` present this row MEASURED 74 cells against the 72 the dialog has
            at 80 columns and clipped to `esc provider` — caught in
            `dialog7-failure-dark-80x24.png`, not by a test. `back` is already this
            file's word for the same move (the custom dialog's `esc`), so the row now
            uses one vocabulary and fits with three cells to spare. */}
        <Hints
          hints={[
            { key: "↑↓", label: "move" },
            { key: "⏎", label: "select", on: selected !== null },
            { key: "/", label: "filter" },
            ...(scope !== null && hasDiscovery ? [{ key: "r", label: "retry" }] : []),
            { key: "c", label: "custom" },
            { key: "esc", label: filter !== "" ? "clear" : "back" },
          ]}
        />
      </Dialog>
    </Centred>
  );
}

/**
 * The full-height flex root that puts the dialog in the MIDDLE of the terminal.
 *
 * "why we not showing provider first and let show it in a middle of the screen".
 * The dialog used to be pinned to row one with the rest of a 45-row terminal
 * painted black below it, which is what "inline" bought — and it bought nothing,
 * because `CliRendererConfig` at `@opentui/[email protected]` has no `height` key, so
 * the renderer is sized to `stdout.rows` in `main-screen` mode exactly as it is in
 * the alternate screen. The region was always the whole terminal; only the dialog
 * was at the top.
 *
 * FLEXBOX, NOT SPACER BOXES. `justifyContent="center"` on a column root centres it
 * vertically and `alignItems="center"` horizontally, so neither axis needs the
 * margin arithmetic the previous build did by hand — and both re-centre on a
 * resize with no code at all. The dialog is a fixed-width, content-height flex
 * item, which is what makes it centre rather than stretch.
 */
function Centred({
  width,
  height,
  children,
}: {
  width: number;
  height: number;
  children: ReactNode;
}): ReactNode {
  return (
    <box
      flexDirection="column"
      width={Math.max(1, Math.floor(width))}
      height={Math.max(1, Math.floor(height))}
      justifyContent="center"
      alignItems="center"
    >
      {children}
    </box>
  );
}

/**
 * The prose sentence for a row, or `""`.
 *
 * `catalogModelToModelInfo` substitutes `"<provider> model"` when the catalog has
 * no description, which every slim-catalog row hits — so a raw `model.description`
 * would print `unknown model` under half the list. The real index is tried first
 * and the placeholder is filtered out, because a blank line is honest and
 * `unknown model` is not.
 */
export function descriptionOf(
  row: { model: ModelInfo },
  lookup: (id: string) => string | undefined
): string {
  const found = lookup(row.model.id);
  if (found !== undefined && found !== "") return found;
  const own = (row.model.description ?? "").trim();
  return own === "" || /^\S+ model$/i.test(own) ? "" : own;
}

/**
 * How many DISTINCT models a list of rows covers.
 *
 * Exported so the title's arithmetic can be asserted: `N models · M routes` is
 * only honest if the two numbers are computed differently, and a regression that
 * made them equal would be invisible on a screenshot of a dynamic models catalog where no model
 * happens to be served twice.
 */
export function countModels(rows: readonly { model: ModelInfo }[]): number {
  return new Set(rows.map((r) => r.model.id)).size;
}

/**
 * WHY A REVEALED PROVIDER CANNOT BE LAUNCHED — the row's own tail, now that the
 * summary lines below the list are gone.
 *
 * TWO REASONS, AND THEY ARE NOT THE SAME REASON. A cloud provider is unavailable
 * because claudish found no credential for it, and the actionable fact is WHICH
 * credential — an env var name the user can go and set, or a sign-in for the
 * OAuth-only ones that have no env var at all. A built-in LOCAL provider is
 * unavailable for a different reason entirely: nothing is missing, it is opt-in in
 * the profile config (`config.localProviders`) and has not been opted into. Telling
 * that user to go and find an API key would send him looking for something that does
 * not exist.
 *
 * `notEnabledLocalProviders()` IS THE ORACLE, not `billing === "local"`. It is the
 * same derived list the deleted summary line printed, and it answers the precise
 * question — enabled in THIS config or not — where the billing mode only says what
 * kind of thing the provider is. An enabled-but-dead Ollama is a different state
 * again, and it is not this one: the probe answers for liveness.
 */
export function unavailableNote(
  provider: { value: string; envVar: string },
  notEnabledLocal: ReadonlySet<string>
): string {
  if (notEnabledLocal.has(provider.value)) return "not enabled in config";
  return provider.envVar === "" ? "needs sign-in" : `needs ${provider.envVar}`;
}

/** A provider-list entry as the facts the detail line prints. Derived, never a table. */
function factsOf(choice: PickerProviderChoice): ProviderFacts {
  return {
    label: choice.label,
    shortcut: choice.shortcut,
    billing: choice.billing,
    envVar: choice.envVar,
  };
}

/** The banner's half of the inline row budget. */
const MAX_BANNER_ROWS = 5;

/**
 * The one status row's text, in priority order: where the cursor is in a list
 * longer than the window, then what is still loading, then nothing.
 *
 * IT NO LONGER CARRIES AN AGGREGATE FAILURE COUNT, because there is no longer an
 * aggregate. That line existed for the startup fan-out — thirteen dynamic models catalogs in
 * flight at once, where a banner per failure would have pushed the list off the
 * screen and a banner for the first would have spoken for the rest. With dynamic models catalogs
 * fetched one at a time, on request, the only dynamic models catalog that can fail is the one the
 * user just opened, and it gets the full banner above its own list.
 *
 * Pure so the priority can be asserted. The scroll position wins over the pending
 * work because it changes on every keypress.
 */
export function statusRow(
  cursor: number,
  shown: number,
  visible: number,
  tasks: LoadTask[]
): string {
  if (shown > visible && visible > 0) return `${cursor + 1} of ${shown} — ↑↓ for more`;
  if (tasks.length > 0) return `still checking: ${tasks.map((t) => t.label).join(", ")}`;
  return "";
}

/**
 * Which providers a filter keeps. Pure, so the matching rules can be asserted
 * without a renderer — and exported because they ARE the rules, not an aid to them.
 *
 * THREE THINGS MATCH, and the first two are what is printed on the row: the readable
 * NAME (`Kimi / Moonshot`) and the routing SHORTCUT (`kc@`). The third is the
 * provider's internal `value` (`kimi-coding`), which is on no screen here but is what
 * the user types on argv and reads in `--debug` output, so a search for it finding
 * nothing would be a false absence.
 *
 * THE SHORTCUT MATCHES BY PREFIX, THE NAMES BY SUBSTRING, exactly as the model list
 * does it. A shortcut is a short token the user is spelling from the left; a display
 * name is a phrase he may recall the middle of.
 */
export function matchProviders<T extends { label: string; shortcut: string; value: string }>(
  rows: T[],
  filter: string
): T[] {
  const needle = filter.trim().toLowerCase();
  if (needle === "") return rows;
  return rows.filter(
    (r) =>
      r.label.toLowerCase().includes(needle) ||
      r.shortcut.toLowerCase().startsWith(needle) ||
      r.value.toLowerCase().includes(needle)
  );
}

/** One row of the list, whichever list it is. */
type RowView = PickerRow;

/** Every key that is not a command types into the filter. */
function printable(raw: string | undefined): raw is string {
  return raw !== undefined && raw.length === 1 && raw >= " " && raw !== "\x7f";
}

/**
 * SAY WHICH EMPTY IT IS. "Nothing here" covers five different situations — still
 * loading, no provider has a credential, loaded and genuinely empty, filtered to
 * nothing, and failed — and a picker that prints one sentence for all five is the
 * complaint this feature exists to fix. The failed case never reaches here: it goes
 * to the banner, which has a colour.
 */
function emptyLabel(
  loading: boolean,
  filter: string,
  total: number,
  scopedName: string,
  providers: { ready: unknown[]; probing: boolean; total: number }
): string {
  if (loading) return `loading ${scopedName || "models"}…`;
  if (filter !== "") return `no model matches “${filter}”`;
  if (providers.ready.length === 0 && !providers.probing) {
    return `no credential for any of the ${providers.total} providers — esc, then k, shows what each one needs`;
  }
  if (total === 0) return `no catalog entries for ${scopedName || "these providers"}`;
  return "nothing to show";
}