create-pathfinder 1.6.0 → 1.8.0

package/src/cells.mjs

@@ -0,0 +1,324 @@
+/**
+ * How much room a string takes up on a terminal, and how to make it take less.
+ *
+ * Two functions, and the reason they exist is one measurement being wrong:
+ * `theme.ok("✓ Git repository detected")` has a `.length` of 34 and occupies 25
+ * cells. The nine-character difference is the SGR pair, which `.length` counts
+ * as text because it is text — the terminal simply does not draw it.
+ *
+ * A renderer that repaints has to know the difference. If a line it believes is
+ * one row wraps to two, every cursor-up it issues afterwards is off by one, and
+ * the block it is redrawing walks down the screen leaving copies of itself
+ * behind. That is not hypothetical: it was reproduced at 24 columns during the
+ * prototype, five copies of the question for four keypresses.
+ *
+ * **Deliberately not a text-processing library.** No wrapping, no padding, no
+ * alignment, no layout. Wrapping in particular is the tempting one and is
+ * exactly what must not appear here: a function that breaks a line into several
+ * is the beginning of a layout engine, and this module exists so that a caller
+ * can guarantee *one* line stays one line.
+ *
+ * **Pure, and stricter than the theme about it.** `createTheme` at least reads
+ * an environment it was handed. This reads nothing — no `process`, no glyph
+ * table, no capability. The same string always measures the same, which is what
+ * lets the tests state cell counts as constants.
+ *
+ * ## The character model, and what it is honest about
+ *
+ * Correct for everything Pathfinder actually prints, and not claimed to be
+ * correct for everything. What it handles:
+ *
+ * - **ANSI escapes occupy nothing.** They are drawn by no terminal.
+ * - **Wide characters occupy two cells** — CJK, Hangul, fullwidth forms, and
+ *   the emoji planes the glyph table draws from.
+ * - **Combining marks, zero-width joiners, and variation selectors occupy
+ *   nothing**, because they modify the character before them rather than
+ *   adding one.
+ * - **Everything else occupies one cell.**
+ *
+ * What it gets wrong, on purpose, because neither can occur in this CLI:
+ *
+ * - **Emoji joined by ZWJ** — `👨‍👩‍👧` is one glyph of two cells, and this counts
+ *   three of two, giving 6.
+ * - **Skin-tone modifiers** — `👍🏽` is one glyph of two cells, counted as 4.
+ *
+ * Both **overcount**, and the direction is the whole reason they are tolerable.
+ * Overcounting clips a line early, which is cosmetic. Undercounting lets a line
+ * wrap, which is the corruption this module was written to prevent. Every
+ * string that reaches a measured surface comes from a frozen registry or a
+ * literal in this package, so neither case arises; if user text ever reaches
+ * one, it will clip a little early rather than break the display.
+ *
+ * ## East Asian Ambiguous width is a policy, and the policy is "narrow"
+ *
+ * **Seven of the fourteen glyphs in `theme.mjs`** — `·`, `▲`, `—`, `…`, `━`,
+ * `│`, `█` — are classified `Ambiguous` by Unicode, meaning they are one cell
+ * beside Latin text and two in a legacy CJK context. **Feature 23's selector
+ * adds five more glyphs, of which three are also Ambiguous** — `○`, `↑`, `↓`.
+ * Ten of nineteen, once that lands.
+ *
+ * There is no correct answer available to a process that cannot ask the
+ * terminal, so this is a decision rather than a lookup: **Ambiguous is
+ * narrow**, which is what every modern terminal outside a CJK locale renders
+ * and what the alternative implementations default to. It is asserted in the
+ * tests so that changing it is a decision someone makes rather than a
+ * regression someone ships.
+ *
+ * Note which glyphs are *not* on that list, because the grouping is not
+ * intuitive: `✓`, `✗`, `░`, and `◉` are unambiguously narrow, while `○` beside
+ * them is not. Ambiguity is a property of a character's history in legacy East
+ * Asian encodings, not of how it looks.
+ */
+
+/**
+ * A CSI sequence: ESC `[`, parameter bytes, one final letter.
+ *
+ * Sticky rather than global, so it can be anchored at a position instead of
+ * searched for — the scanner below needs "is there an escape *here*", never
+ * "is there an escape somewhere after here".
+ *
+ * Only CSI is recognised, because only CSI is emitted: `theme.mjs` produces SGR
+ * colour codes and the two line primitives, all of which are CSI. An OSC
+ * sequence would be measured as its literal characters, which would be wrong —
+ * and is acceptable only because nothing in this package writes one. A stray
+ * `ESC` that begins no valid sequence falls through to the character path and
+ * measures zero, since it is a C0 control.
+ */
+const CSI = /\u001B\[[0-9;?]*[A-Za-z]/y;
+
+/** An SGR sequence — a CSI whose final byte is `m`. The only kind that paints. */
+const SGR_FINAL = "m";
+
+/** `ESC[0m` and its abbreviation `ESC[m`. Both end every span the theme opens. */
+const RESET = "\u001B[0m";
+const isReset = (sequence) => sequence === RESET || sequence === "\u001B[m";
+
+/**
+ * Ranges rendered two cells wide.
+ *
+ * The standard Wide and Fullwidth set. Written as a sorted table of pairs and
+ * searched linearly: it has twenty-one entries and is consulted once per
+ * character of a handful of short lines, so a binary search would trade
+ * legibility for time nobody is waiting on.
+ *
+ * **Sorted ascending, and `inRanges` depends on it** — that function stops as
+ * soon as a range starts above the code point, so an entry inserted out of
+ * order would not merely slow the search, it would silently stop matching.
+ *
+ * Four of these ranges cover no character this CLI prints today: `1F004`,
+ * `1F200–1F2FF`, `1F7E0–1F7EB`, and `1FA70–1FAFF`. They are here anyway, and
+ * the reason is the module's one safety property rather than coverage. Every
+ * documented inaccuracy in this file *over*counts, which clips a line early and
+ * costs a character. A missing Wide range does the opposite: it undercounts, so
+ * a line that measured as fitting wraps, and a repainting caller's cursor-up
+ * count is then wrong for every frame after it. Overcounting is cosmetic;
+ * undercounting corrupts the display. A glyph chosen later from any of these
+ * blocks — a coloured circle for a status dot is an entirely plausible future —
+ * must not be able to introduce that quietly.
+ */
+const WIDE = Object.freeze([
+  [0x1100, 0x115f], // Hangul Jamo initial consonants
+  [0x2e80, 0x303e], // CJK radicals, Kangxi, CJK symbols
+  [0x3041, 0x33ff], // Hiragana, Katakana, Bopomofo, CJK compatibility
+  [0x3400, 0x4dbf], // CJK Extension A
+  [0x4e00, 0x9fff], // CJK Unified Ideographs
+  [0xa000, 0xa4cf], // Yi
+  [0xa960, 0xa97f], // Hangul Jamo Extended-A
+  [0xac00, 0xd7a3], // Hangul syllables
+  [0xf900, 0xfaff], // CJK compatibility ideographs
+  [0xfe10, 0xfe19], // vertical forms
+  [0xfe30, 0xfe6f], // CJK compatibility forms, small form variants
+  [0xff00, 0xff60], // fullwidth forms
+  [0xffe0, 0xffe6], // fullwidth signs
+  [0x1f004, 0x1f004], // mahjong tile red dragon
+  [0x1f200, 0x1f2ff], // enclosed ideographic supplement
+  [0x1f300, 0x1f64f], // symbols, pictographs, emoticons — `🔍` `📦` `📋` `🎉`
+  [0x1f680, 0x1f6ff], // transport and map symbols
+  [0x1f7e0, 0x1f7eb], // geometric shapes extended — the coloured circles
+  [0x1f900, 0x1f9ff], // supplemental symbols and pictographs
+  [0x1fa70, 0x1faff], // symbols and pictographs extended-A
+  [0x20000, 0x3fffd], // CJK Extension B and beyond
+]);
+
+/**
+ * Ranges that add nothing to a line's width.
+ *
+ * Combining marks attach to the character before them, and the joiners and
+ * selectors steer how a sequence is drawn without being drawn themselves.
+ * Counting any of them would overstate every accented word.
+ */
+const ZERO_WIDTH = Object.freeze([
+  [0x0300, 0x036f], // combining diacritical marks
+  [0x1ab0, 0x1aff], // combining diacriticals extended
+  [0x1dc0, 0x1dff], // combining diacriticals supplement
+  [0x200b, 0x200f], // zero-width space, ZWNJ, ZWJ, directional marks
+  [0x20d0, 0x20f0], // combining marks for symbols
+  [0xfe00, 0xfe0f], // variation selectors
+  [0xfe20, 0xfe2f], // combining half marks
+  [0xe0100, 0xe01ef], // variation selectors supplement
+]);
+
+/** Is `code` inside any of these `[low, high]` pairs? */
+function inRanges(code, ranges) {
+  for (const [low, high] of ranges) {
+    if (code < low) return false; // sorted, so nothing later can match
+    if (code <= high) return true;
+  }
+  return false;
+}
+
+/**
+ * Cells occupied by one code point.
+ *
+ * C0 and C1 controls measure zero. They are not printable, and a terminal that
+ * receives one either acts on it or discards it — either way it draws nothing,
+ * so counting it would make every string containing an escape too wide.
+ */
+function codePointWidth(code) {
+  if (code < 0x20 || (code >= 0x7f && code < 0xa0)) return 0;
+  if (inRanges(code, ZERO_WIDTH)) return 0;
+  if (inRanges(code, WIDE)) return 2;
+  return 1;
+}
+
+/**
+ * Walk `text` as a sequence of escapes and code points.
+ *
+ * One scanner, shared by both public functions, so there is exactly one place
+ * that decides where an escape begins and ends. Two implementations of that
+ * question would eventually disagree, and the disagreement would show up as a
+ * clipped line that measures correctly and renders wrong.
+ *
+ * @param {string} text
+ * @yields {{escape: string|null, character: string|null, width: number}}
+ */
+function* scan(text) {
+  let index = 0;
+
+  while (index < text.length) {
+    CSI.lastIndex = index;
+    const match = CSI.exec(text);
+
+    if (match !== null) {
+      yield { escape: match[0], character: null, width: 0 };
+      index = CSI.lastIndex;
+      continue;
+    }
+
+    // `codePointAt` reads a surrogate pair as one value, and `fromCodePoint`
+    // rebuilds both halves, so a character is never split down the middle.
+    const code = text.codePointAt(index);
+    const character = String.fromCodePoint(code);
+
+    yield { escape: null, character, width: codePointWidth(code) };
+    index += character.length;
+  }
+}
+
+/**
+ * How many terminal cells `text` occupies when printed.
+ *
+ * @param {string} text
+ * @returns {number} cells, never negative
+ */
+export function width(text) {
+  let total = 0;
+  for (const token of scan(String(text))) total += token.width;
+  return total;
+}
+
+/**
+ * Shorten `text` to at most `cells` columns, leaving the terminal consistent.
+ *
+ * Three things it will not do, each of which is a way a naive slice breaks a
+ * terminal rather than merely a line:
+ *
+ * - **Never cuts an escape sequence in half.** The tail of a severed `ESC[32m`
+ *   is printed as literal text — `[32m` appears in the output — and the
+ *   sequence never takes effect.
+ * - **Never splits a character.** Half a surrogate pair is not a character;
+ *   it renders as a replacement glyph.
+ * - **Never leaves a colour open.** A cut inside a painted span drops that
+ *   span's reset, and the colour then bleeds into everything printed
+ *   afterwards, including output this package does not own. When that happens
+ *   a reset is appended — the one byte sequence this function adds, and it adds
+ *   it precisely so the damage stops at the clip.
+ *
+ * Escapes cost nothing against the budget, and every escape preceding text that
+ * survives the cut is kept — so a clipped line keeps its colour rather than
+ * losing its meaning. Severity in this CLI is carried by a glyph and a word as
+ * well, but a line that silently changed colour when the window narrowed would
+ * look like a different kind of message.
+ *
+ * What is *not* kept is an escape no visible character earned. See `pending`
+ * below: a colour that paints nothing is not decoration, it is noise.
+ *
+ * @param {string} text
+ * @param {number} cells - budget in columns. A budget of zero yields the empty
+ *   string for text whose leading run is escapes and visible characters, which
+ *   is every line this CLI renders. Two exceptions, both harmless and both
+ *   stated rather than tidied away: a text made only of escapes occupies zero
+ *   cells and is therefore already within any budget, so identity applies; and
+ *   a *zero-width character* such as a leading `\r` costs nothing against the
+ *   budget and is retained, so a string beginning with one clips to that
+ *   character rather than to `""`. Nothing measured by this module begins with
+ *   one — the progress bar does, and the progress bar is never clipped. A
+ *   budget at or above the text's width yields the text unchanged.
+ * @returns {string}
+ */
+export function clip(text, cells) {
+  const source = String(text);
+
+  // Identity when it already fits. Worth stating as its own case: the common
+  // call passes a line that fits, and it should come back the same object's
+  // value with nothing appended — including no reset.
+  if (width(source) <= cells) return source;
+
+  let kept = "";
+  let used = 0;
+  let painted = false;
+
+  // Escapes seen but not yet earned.
+  //
+  // An escape costs no cells, so the tempting thing is to emit it the moment it
+  // is seen. That produces two artefacts, both of which are output describing a
+  // colour that paints nothing: a zero budget returns `ESC[32mESC[0m` instead of
+  // the empty string, and a cut landing just after a paint leaves that paint
+  // and its reset bracketing no text at all.
+  //
+  // Holding them until a visible character is actually kept fixes both, and
+  // costs nothing else: escapes still never count against the budget, and every
+  // escape preceding retained text is still emitted, in order.
+  //
+  // Held as tokens rather than a concatenated string on purpose — flushing has
+  // to know which of them were SGR, and re-parsing a string to find out would
+  // be the second escape-parsing path this module exists to avoid.
+  let pending = [];
+
+  for (const token of scan(source)) {
+    if (token.escape !== null) {
+      pending.push(token.escape);
+      continue;
+    }
+
+    if (used + token.width > cells) break;
+
+    for (const escape of pending) {
+      kept += escape;
+      // Only SGR opens or closes a paint. A cursor movement is not a colour,
+      // and treating one as though it were would append resets to lines that
+      // never had a span to close.
+      if (escape.endsWith(SGR_FINAL)) painted = !isReset(escape);
+    }
+    pending = [];
+
+    kept += token.character;
+    used += token.width;
+  }
+
+  // Whatever is still pending trailed the last character we kept, so it is
+  // discarded — including, possibly, the reset that would have closed a span.
+  // That is exactly why `painted` is consulted here rather than trusted to the
+  // input: the span is closed by the reset appended below.
+  return painted ? kept + RESET : kept;
+}

package/src/cli.mjs

@@ -52,6 +52,15 @@ Options:
 Adapters are generated files Pathfinder owns and regenerates without --force.
 A file it did not generate is never replaced, at any path, without --force.
 
+Environment:
+  PATHFINDER_PROMPT=classic
+                  Ask every question as a numbered list and y/n instead of an
+                  arrow-key selector. Both are supported; use this for screen
+                  readers, for scripts, or simply if you prefer typing. It is
+                  also what a terminal narrower than 49 columns and TERM=dumb
+                  select on their own.
+  NO_COLOR        Print no colour. It does not disable the selector.
+
 Without a terminal on both stdin and stdout, nothing is ever asked. In that
 case a directory that is not a Git repository needs --git-init, or the install
 is refused, and neither your clipboard nor an editor is touched — --yes does
@@ -67,6 +76,7 @@ export async function run(
     env = {},
     platform = process.platform,
     stdoutIsTTY = false,
+    theme: injectedTheme = null,
     prompter = nonInteractivePrompter(),
   },
 ) {
@@ -86,11 +96,18 @@ export async function run(
   // the user reads what the tool found before reading what it wants to do.
   const findings = detect({ cwd, env, platform });
 
-  // Every capability question this run will ask is answered once, here, from
-  // the three things this function was handed. Threaded downward as an argument
-  // rather than reached for: a module-level theme would be a second opinion
-  // about the terminal that no test could disagree with.
-  const theme = createTheme({ env, platform, isTTY: stdoutIsTTY });
+  // Every capability question this run will ask is answered once and threaded
+  // downward as an argument rather than reached for: a module-level theme would
+  // be a second opinion about the terminal that no test could disagree with.
+  //
+  // Built here when nobody supplied one, which is every test and every caller
+  // that has nothing to say about stdin. `bin/` supplies one because it knows
+  // things this function is never handed — whether stdin is a terminal, whether
+  // it can be put into raw mode, how wide the window is — and those are exactly
+  // the three the selection capability is decided from. Accepting it keeps the
+  // property this comment has always claimed: one theme per run, not one per
+  // module that wants an opinion.
+  const theme = injectedTheme ?? createTheme({ env, platform, isTTY: stdoutIsTTY });
   const mark = theme.glyph;
 
   // The one branch in this file that chooses between whole presentations, and
@@ -324,25 +341,36 @@ async function selectHarnesses({ findings, options, prompter, out, theme }) {
   const entries = [...HARNESSES, SOMETHING_ELSE];
 
   // The sentinel's trailing ellipsis is the theme's, not a character baked into
-  // the label — and because it is the longest row, it also decides the column
-  // the arrows line up in. So the width is measured on the rendered label
-  // rather than the stored one: an ASCII terminal spends three characters on
-  // `...` where a UTF-8 one spends one, and the arrows must follow.
+  // the label: an ASCII terminal spends three characters on `...` where a UTF-8
+  // one spends one.
   const labelOf = (entry) =>
     entry === SOMETHING_ELSE ? `${entry.label}${theme.glyph.ellipsis}` : entry.label;
-  const width = Math.max(...entries.map((entry) => labelOf(entry).length));
 
+  // Three fields instead of one hand-built string.
+  //
+  // This used to compute the longest label and `padEnd` every other one to it,
+  // so that the `->` arrows lined up — a column of layout, measured in UTF-16
+  // units, inside a file whose job is deciding which tools to configure. It was
+  // wrong in the way `.length` is always wrong about a terminal, and it was
+  // wrong twice over: it produced a *rendering* that only one of the two
+  // question implementations could use.
+  //
+  // Now the call site says what each part *is* and the renderer decides where it
+  // goes. Both implementations get the same three fields and lay them out their
+  // own way, and neither this function nor any other in this file measures a
+  // string in cells.
   const answer = await prompter.chooseMany("Configure Pathfinder for which tools?", {
     options: entries.map((entry) => ({
       value: entry,
-      label:
-        `${labelOf(entry).padEnd(width)}  -> ` +
-        // The path is shown so nobody has to check a box to find out what it
-        // writes. The last entry earns the same courtesy by admitting it
-        // writes nothing, in the column where every other row names a file.
-        (entry === SOMETHING_ELSE
-          ? "nothing is generated"
-          : `${entry.skillsDir}/` + (detected.includes(entry) ? "   (detected)" : "")),
+      label: labelOf(entry),
+      // The path is shown so nobody has to check a box to find out what it
+      // writes. The last entry earns the same courtesy by admitting it writes
+      // nothing, in the column where every other row names a file.
+      hint: entry === SOMETHING_ELSE ? "nothing is generated" : `${entry.skillsDir}/`,
+      // Detection decides the default; this only says so out loud. It is the
+      // one part of a row a narrow terminal may drop, because the ENVIRONMENT
+      // block above has already reported it.
+      note: entry !== SOMETHING_ELSE && detected.includes(entry) ? "(detected)" : undefined,
     })),
     defaultSelection: detected,
   });

package/src/detect.mjs

@@ -119,7 +119,7 @@ function detectTool(tool, { cwd, home, env, platform }) {
  * Decided by counting skill directories rather than by testing for `CLAUDE.md`,
  * which any agent-assisted project may have written for its own reasons.
  * A `skills/<name>/SKILL.md` is a far more specific signature, and the count is
- * worth having on its own — it is what makes "already installed (20 skills)"
+ * worth having on its own — it is what makes "already installed (N skills)"
  * checkable by the person reading it.
  */
 function detectPathfinder(cwd) {

package/src/kickstart-prompt.mjs

@@ -4,7 +4,7 @@
  * This used to be one hardcoded string naming a file path, and that was right
  * for exactly as long as Pathfinder configured nothing. Once a run can generate
  * native adapters, the path form is no longer the best answer for someone who
- * just watched twenty skills be installed into their harness — it is the answer
+ * just watched the whole kit be installed into their harness — it is the answer
  * for someone whose tool cannot discover them.
  *
  * A pure function of the selection, deliberately: no filesystem, no detection,

package/src/prompt.mjs

@@ -10,10 +10,31 @@
  * nothing must also print nothing, and a guard bug that degrades silently would
  * show up as a script that hangs on someone's CI runner months later.
  *
- * The second is the decided interaction model: `node:readline` and printed
- * lines. No setRawMode, no keypress handler, no cursor control, no redraw. That
- * is what makes this work in a dumb terminal, over ssh, and inside an editor's
- * integrated console, and it is a decision rather than a default.
+ * The second is the decided interaction model. ~~`node:readline` and printed
+ * lines. No setRawMode, no keypress handler, no cursor control, no redraw.~~
+ * **Superseded in Feature 23**, in two different ways, and the sentence was
+ * partly wrong when it was written:
+ *
+ * - **"No setRawMode" was never true of the process**, only of this file.
+ *   `node:readline` turns raw mode on itself the moment its input is a TTY, and
+ *   turns it off again on `close()` — verified across five Node majors during
+ *   the spike. What is true, and is now the load-bearing statement, is that
+ *   **readline owns raw mode and Pathfinder never touches it.** The distinction
+ *   matters: the first is a claim about terminal state that a reader could check
+ *   and find false, and the second is the reason no interrupt can leave a
+ *   terminal broken.
+ * - **There is now a keypress handler and a redraw**, in `select.mjs`, borrowed
+ *   from readline and given back. Which is a change of interaction, not of
+ *   ownership.
+ *
+ * What has *not* changed is the reason the original sentence existed. The
+ * line-based path still works in a dumb terminal, over a pipe, and on a CI
+ * runner, and it is still here — every function below keeps its numbered/`y n`
+ * implementation intact and reaches for it whenever `theme.selection` is false.
+ * That is a supported way to use this tool, reachable deliberately with
+ * `PATHFINDER_PROMPT=classic`, and not a fallback anyone should feel they have
+ * been demoted to. `text()` never had anything to gain from a keypress loop and
+ * is untouched.
  *
  * Answers are bounded. Unparseable input is re-prompted a fixed number of times
  * and then gives up, so an input stream that will never produce a `y` cannot
@@ -24,14 +45,25 @@
 
 import { createInterface } from "node:readline";
 
+import { alignmentWidth, optionRow, select } from "./select.mjs";
+import { createTheme } from "./theme.mjs";
+
 const YES = new Set(["y", "yes"]);
 const NO = new Set(["n", "no"]);
 
 /**
  * A question-asker bound to one pair of streams.
  *
+ * `theme` decides *how* a question is asked and nothing else. Every function
+ * below returns the same values through either path, which is what lets the
+ * choice be made here instead of at four call sites — and what lets the whole
+ * existing test suite drive the classic path unchanged by simply not supplying
+ * one. The default theme knows about no terminal at all, so it answers no to
+ * `selection`, which is the conservative answer and the right one for a
+ * prompter built from streams nobody has described.
+ *
  * @param {{input: NodeJS.ReadableStream, output: NodeJS.WritableStream,
- *          interactive?: boolean, retries?: number}} options
+ *          interactive?: boolean, retries?: number, theme?: object}} options
  * @returns {{interactive: boolean,
  *            confirm: (question: string, options?: {defaultAnswer?: boolean}) => Promise<boolean|null>,
  *            chooseMany: (question: string, config?: object) => Promise<unknown[]|null>,
@@ -39,7 +71,13 @@ const NO = new Set(["n", "no"]);
  *            text: (question: string) => Promise<string|null>,
  *            close: () => void}}
  */
-export function createPrompter({ input, output, interactive = false, retries = 3 }) {
+export function createPrompter({
+  input,
+  output,
+  interactive = false,
+  retries = 3,
+  theme = createTheme(),
+}) {
   let reader = null;
 
   // Created on first use, not here. A run that never reaches a question — a
@@ -47,10 +85,23 @@ export function createPrompter({ input, output, interactive = false, retries = 3
   // reader to stdin, because attaching one resumes the stream and a process
   // holding an open stdin does not exit on its own.
   function ensureReader() {
-    if (reader === null) reader = createReader({ input, output });
+    if (reader === null) reader = createReader({ input, output, theme });
     return reader;
   }
 
+  /**
+   * Ask one question with the arrow keys.
+   *
+   * The Interface is handed over rather than a pair of streams, because the
+   * selector's whole contract is that it borrows from an open readline and
+   * gives it back. Nothing here consults `input.isTTY`: the decision was made
+   * once, in the theme, and a module that re-derived it could disagree with the
+   * one place that is allowed to have an opinion — and could not be tested over
+   * a pipe at all.
+   */
+  const ask = (question, config) =>
+    select({ readline: ensureReader().readline, theme, question, ...config });
+
   return {
     interactive,
 
@@ -59,6 +110,20 @@ export function createPrompter({ input, output, interactive = false, retries = 3
         throw new Error(`refusing to ask "${question}": this prompter is not interactive`);
       }
 
+      // Two rows rather than a typed letter. `y` and `n` still work and are
+      // deliberately not printed: the presented interaction is the one the hint
+      // line describes, and an accelerator that has to be advertised is a second
+      // thing to learn rather than a shortcut for people who already know it.
+      if (theme.selection) {
+        return ask(question, {
+          options: [
+            { label: "Yes", value: true, key: "y" },
+            { label: "No", value: false, key: "n" },
+          ],
+          initial: [defaultAnswer],
+        });
+      }
+
       const suffix = defaultAnswer ? "[Y/n]" : "[y/N]";
 
       for (let attempt = 0; attempt < retries; attempt += 1) {
@@ -103,12 +168,28 @@ export function createPrompter({ input, output, interactive = false, retries = 3
       }
       if (choices.length === 0) return [];
 
+      // A checkbox list, which is what this question always was. Note what does
+      // *not* move: the caller still supplies `{label, value}` and still reads
+      // back the chosen values in list order, so no decision about what the
+      // options mean has crossed into this file.
+      if (theme.selection) {
+        return ask(question, { options: choices, multi: true, initial: defaultSelection });
+      }
+
       const defaults = choices.filter((choice) => defaultSelection.includes(choice.value));
       const defaultNumbers = defaults.map((choice) => choices.indexOf(choice) + 1);
 
+      // The same option grammar the selector uses, inside a numbered list
+      // instead of a repainted block. An option that names the path it writes
+      // to is not a decoration the keyboard path earned — it is the answer to
+      // "what does checking this box do", and both paths owe it.
+      const labelWidth = alignmentWidth(choices, theme);
+
       const header = [
         `? ${question}`,
-        ...choices.map((choice, index) => `    ${index + 1}. ${choice.label}`),
+        ...choices.map(
+          (choice, index) => `    ${index + 1}. ${optionRow({ theme, option: choice, labelWidth })}`,
+        ),
         defaultNumbers.length > 0
           ? `  Numbers, comma-separated. Enter for the detected default [${defaultNumbers.join(",")}], or 0 for none.`
           : "  Numbers, comma-separated. Enter or 0 for none.",
@@ -158,12 +239,22 @@ export function createPrompter({ input, output, interactive = false, retries = 3
       if (choices.length === 0) return null;
 
       const fallback = choices.find((choice) => choice.value === defaultValue) ?? choices[0];
+
+      // The default becomes the highlighted row rather than a number in a
+      // sentence, so taking it still costs one keystroke.
+      if (theme.selection) {
+        return ask(question, { options: choices, initial: [fallback.value] });
+      }
+
       const defaultNumber = choices.indexOf(fallback) + 1;
+      const labelWidth = alignmentWidth(choices, theme);
 
       output.write(
         [
           `? ${question}`,
-          ...choices.map((choice, index) => `    ${index + 1}. ${choice.label}`),
+          ...choices.map(
+            (choice, index) => `    ${index + 1}. ${optionRow({ theme, option: choice, labelWidth })}`,
+          ),
           `  A number, or Enter for [${defaultNumber}].`,
           "",
         ].join("\n"),
@@ -266,8 +357,16 @@ export function nonInteractivePrompter() {
  * with a closed stdin must fall through to the caller's decision about an
  * unanswered question, not hang.
  */
-function createReader({ input, output }) {
-  const readline = createInterface({ input, output });
+function createReader({ input, output, theme }) {
+  // `terminal` is forced only where the selector will run, and only ever from
+  // false to true. On a real terminal readline works this out for itself and
+  // the flag changes nothing; over a pipe it is what makes the keypress decoder
+  // exist at all, which is the difference between a selector that can be tested
+  // and one that can only be tried. It is never forced *off*, so no classic run
+  // has its line editing altered by this.
+  const readline = createInterface(
+    theme?.selection ? { input, output, terminal: true } : { input, output },
+  );
   const delivered = [];
   const waiting = [];
   let closed = false;
@@ -284,6 +383,12 @@ function createReader({ input, output }) {
   });
 
   return {
+    // The Interface itself, for the one caller that needs the *owner* rather
+    // than a line: the selector borrows this object's listeners and hands them
+    // back. Exposed rather than re-created, because a second Interface over the
+    // same stdin would be a second thing turning raw mode on and off.
+    readline,
+
     /**
      * Print `text` and resolve with the next line, or null at end of input.
      *