pi-better-model-select 0.2.0 → 0.3.0

package/extensions/lib/picker-dialog.ts

@@ -1,21 +1,13 @@
-import { DynamicBorder } from "@earendil-works/pi-coding-agent";
-import { Container, Text } from "@earendil-works/pi-tui";
-import { ModelPicker, type PickerAction, type RankedModel } from "./picker.ts";
+import { ModelPicker, type PickerAction, type PickerOptions, type RankedModel } from "./picker.ts";
+import { resultPlacement } from "./tui.ts";
 
-export async function pickerDialog(ctx: any, rows: RankedModel[], title = "Better Model Select", assignment = false): Promise<PickerAction | undefined> {
-  return ctx.ui.custom((tui: any, theme: any, _kb: any, done: any) => {
-    const container = new Container();
-    const accent = (text: string) => typeof theme?.fg === "function" ? theme.fg("accent", text) : text;
-    container.addChild(new DynamicBorder(accent));
-    container.addChild(new Text(accent(title), 1, 0));
-    const picker = new ModelPicker(rows, theme, () => tui.requestRender(), done, assignment);
-    picker.focused = true;
-    container.addChild(picker);
-    container.addChild(new DynamicBorder(accent));
-    return {
-      render: (width: number) => container.render(width),
-      invalidate: () => container.invalidate(),
-      handleInput: (data: string) => picker.handleInput(data),
-    };
-  });
+export async function pickerDialog(
+  ctx: any, rows: RankedModel[], title = "Better Model Select", assignment = false,
+  options: PickerOptions = {},
+): Promise<PickerAction | undefined> {
+  // Return the Focusable itself. Pi's custom UI installs it in the prompt area,
+  // calls setFocus on it and restores the previous editor when done is called.
+  return ctx.ui.custom((tui: any, theme: any, _kb: any, done: any) =>
+    new ModelPicker(rows, theme, () => tui.requestRender(), done, assignment,
+      { ...options, placement: options.placement ?? resultPlacement() }, title));
 }

package/extensions/lib/picker.ts

@@ -1,20 +1,8 @@
-// The /bms picker: a filter Input stacked on a SelectList.
-//
-// Typing always goes to the search box, so plain letters can never be stolen
-// as action shortcuts. Actions are therefore ctrl-chords, which stay reachable
-// while the cursor sits in the search field.
+// The /bms prompt-area picker. Typing goes to search; ctrl-chords perform
+// actions. The action menu shares this dialog and never replaces its input.
 
-import {
-  Container,
-  fuzzyFilter,
-  Input,
-  matchesKey,
-  SelectList,
-  type Focusable,
-  type SelectItem,
-  type SelectListTheme,
-  Text,
-} from "@earendil-works/pi-tui";
+import { matchesKey, type Focusable, type SelectItem, type SelectListTheme } from "@earendil-works/pi-tui";
+import { TableSelect, type Placement, type SelectionState, type TableColumn } from "./tui.ts";
 import { loadUsage, usageKey, type ModelsConfig } from "./store.ts";
 
 export type PickerAction =
@@ -114,171 +102,110 @@ export function selectListTheme(theme: any): SelectListTheme {
   };
 }
 
-const HINT =
-  "↑↓ move  •  enter load  •  ctrl+a add  •  ctrl+u update  •  ctrl+x delete  •  ctrl+d default  •  ctrl+g agent defaults  •  ctrl+o options  •  ctrl+r reset  •  esc close";
+const HINT = "↑↓ move · enter load · ctrl+a add · ctrl+o actions · esc close";
 
-export class ModelPicker extends Container implements Focusable {
-  private search: Input;
-  private list: SelectList;
+export interface PickerOptions {
+  placement?: Placement;
+  /** Pass the same state object when reopening after an action. Updated in place. */
+  state?: SelectionState & { menuValue?: string };
+}
+
+const MODEL_COLUMNS: TableColumn[] = [
+  { key: "model", label: "MODEL" }, { key: "provider", label: "PROVIDER", width: 14 },
+  { key: "context", label: "CONTEXT", width: 7 }, { key: "uses", label: "USES", width: 5 },
+  { key: "status", label: "STATUS", width: 17 },
+];
+
+export class ModelPicker implements Focusable {
+  private table: TableSelect;
+  private menu?: TableSelect;
   private rows: RankedModel[];
-  private filtered: RankedModel[];
-  private hintText: Text;
-  private countText: Text;
-  // Plain fields rather than constructor parameter properties, so the source
-  // also loads under type-stripping runtimes that reject that syntax.
   private theme: any;
-  private onChange: () => void;
+  private changed: () => void;
   private done: (action: PickerAction) => void;
   private assignment: boolean;
-
+  private options: PickerOptions;
   private _focused = false;
-  get focused(): boolean {
-    return this._focused;
-  }
-  // Propagate focus to the Input so the hardware cursor lands correctly for IME.
+  get focused(): boolean { return this._focused; }
   set focused(value: boolean) {
     this._focused = value;
-    this.search.focused = value;
+    this.table.focused = value && !this.menu;
+    if (this.menu) this.menu.focused = value;
   }
 
-  constructor(
-    rows: RankedModel[],
-    theme: any,
-    onChange: () => void,
-    done: (action: PickerAction) => void,
-    assignment = false,
-  ) {
-    super();
+  constructor(rows: RankedModel[], theme: any, changed: () => void,
+    done: (action: PickerAction) => void, assignment = false, options: PickerOptions = {},
+    title = "Better Model Select") {
+    this.rows = rows;
     this.theme = theme;
-    this.onChange = onChange;
+    this.changed = changed;
     this.done = done;
     this.assignment = assignment;
-    this.rows = rows;
-    this.filtered = rows;
-
-    const fg =
-      typeof theme?.fg === "function"
-        ? (role: string, t: string) => theme.fg(role, t)
-        : (_role: string, t: string) => t;
-
-    this.search = new Input({
-      prompt: "  search ",
-      placeholder: "type to filter by name, id or provider…",
-      placeholderStyle: (t: string) => fg("dim", t),
-    });
-    this.search.onEscape = () => this.done({ kind: "close" });
-    this.search.onSubmit = () => this.loadSelected();
-
-    this.list = this.buildList(rows);
-
-    this.countText = new Text(fg("dim", this.countLabel()), 1, 0);
-    this.hintText = new Text(fg("dim", assignment ? "↑↓ move  •  enter assign  •  esc back" : HINT), 1, 0);
-
-    this.addChild(this.search);
-    this.addChild(this.list);
-    this.addChild(this.countText);
-    this.addChild(this.hintText);
-  }
-
-  /** SelectList has no public API to replace its items, so rebuild it. */
-  private buildList(rows: RankedModel[]): SelectList {
-    const list = new SelectList(
-      rows.map(toSelectItem),
-      Math.min(Math.max(rows.length, 1), 12),
-      selectListTheme(this.theme),
-    );
-    list.onSelect = () => this.loadSelected();
-    list.onCancel = () => this.done({ kind: "close" });
-    return list;
+    this.options = options;
+    this.table = new TableSelect({ title, columns: MODEL_COLUMNS,
+      rows: rows.map(row => ({ value: toSelectItem(row).value, label: row.label,
+        // IDs remain searchable but are not repeated under the display name.
+        description: row.modelId,
+        cells: { model: row.label, provider: row.provider, context: formatContext(row.contextWindow),
+          uses: String(row.count), status: [row.current ? "current" : "", row.default ? "default" : ""].filter(Boolean).join(" · ") },
+      })), placement: options.placement,
+      hint: assignment ? "↑↓ move · enter assign · esc back" : HINT,
+    }, theme, () => { this.saveState(); changed(); }, value => {
+      this.saveState();
+      if (value === undefined) done({ kind: "close" });
+      else this.action("load");
+    }, options.state);
+    if (options.state?.menuValue) this.openMenu();
   }
-
-  private countLabel(): string {
-    const total = this.rows.length;
-    const shown = this.filtered.length;
-    return shown === total ? `${total} models` : `${shown} of ${total} models`;
+  private saveState(): void { if (this.options.state) Object.assign(this.options.state, this.table.state); }
+  private currentRow(): RankedModel | undefined {
+    const value = this.table.currentItem()?.value;
+    return this.rows.find(row => toSelectItem(row).value === value);
   }
-
-  private currentRow(): RankedModel | null {
-    const item = this.list.getSelectedItem();
-    if (!item) return null;
-    const decoded = decodeValue(item.value);
-    if (!decoded) return null;
-    return (
-      this.filtered.find(
-        (r) => r.provider === decoded.provider && r.modelId === decoded.modelId,
-      ) ?? null
-    );
-  }
-
-  private loadSelected(): void {
+  private action(kind: PickerAction["kind"]): void {
+    this.saveState();
     const row = this.currentRow();
-    if (!row) return;
-    this.done({ kind: "load", provider: row.provider, modelId: row.modelId });
+    if (kind === "load" || kind === "set-default") {
+      if (row) this.done({ kind, provider: row.provider, modelId: row.modelId });
+    } else if (kind === "update" || kind === "delete") {
+      this.done({ kind, provider: row?.provider, modelId: row?.modelId });
+    } else this.done({ kind });
   }
-
-  /**
-   * Re-filter with fuzzyFilter rather than SelectList.setFilter, which only does
-   * a prefix match on item.value and would ignore the display name. Ranking is
-   * preserved because fuzzyFilter is stable over the already-sorted rows for
-   * equal scores, and exact-prefix hits still surface first.
-   */
-  private applyFilter(): void {
-    const query = this.search.getValue().trim();
-    this.filtered = query
-      ? fuzzyFilter(this.rows, query, (r) => `${r.label} ${r.modelId} ${r.provider}`)
-      : this.rows;
-
-    // Swap the list child in place; index 1 is the SelectList.
-    const next = this.buildList(this.filtered);
-    const idx = this.children.indexOf(this.list);
-    if (idx >= 0) this.children[idx] = next;
-    this.list = next;
-
-    const fg =
-      typeof this.theme?.fg === "function"
-        ? (role: string, t: string) => this.theme.fg(role, t)
-        : (_role: string, t: string) => t;
-    this.countText.setText(fg("dim", this.countLabel()));
+  private openMenu(): void {
+    const row = this.currentRow();
+    const actions: { value: PickerAction["kind"]; label: string }[] = [
+      ...(row ? [{ value: "load" as const, label: "Load selected model" },
+        { value: "set-default" as const, label: "Set selected model as default" }] : []),
+      { value: "add", label: "Add model" }, { value: "update", label: "Update model" },
+      { value: "delete", label: "Delete model" }, { value: "defaults", label: "Model and agent defaults" },
+      { value: "options", label: "Options" }, { value: "reset", label: "Reset usage ranking" },
+    ];
+    this.menu = new TableSelect({ title: "Models / Actions", rows: actions, search: false, initialValue: this.options.state?.menuValue,
+      hint: "↑↓ move · enter choose · esc back" }, this.theme, this.changed, value => {
+      if (this.options.state) {
+        if (value === undefined) delete this.options.state.menuValue;
+        else this.options.state.menuValue = value;
+      }
+      this.menu = undefined;
+      this.focused = this._focused;
+      if (value !== undefined) this.action(value as PickerAction["kind"]);
+      this.changed();
+    });
+    this.focused = this._focused;
+    this.changed();
   }
-
   handleInput(data: string): void {
-    if (matchesKey(data, "escape")) return this.done({ kind: "close" });
-    if (!this.assignment && matchesKey(data, "ctrl+g")) return this.done({ kind: "defaults" });
-    if (!this.assignment && matchesKey(data, "ctrl+d")) {
-      const row = this.currentRow();
-      if (row) this.done({ kind: "set-default", provider: row.provider, modelId: row.modelId });
-      return;
-    }
-    if (this.assignment && ["ctrl+a", "ctrl+o", "ctrl+r", "ctrl+u", "ctrl+x", "ctrl+d", "ctrl+g"].some(key => matchesKey(data, key as any))) return;
-    if (matchesKey(data, "ctrl+a")) return this.done({ kind: "add" });
-    if (matchesKey(data, "ctrl+o")) return this.done({ kind: "options" });
-    if (matchesKey(data, "ctrl+r")) return this.done({ kind: "reset" });
-
-    if (matchesKey(data, "ctrl+u")) {
-      const row = this.currentRow();
-      return this.done({ kind: "update", provider: row?.provider, modelId: row?.modelId });
-    }
-    if (matchesKey(data, "ctrl+x")) {
-      const row = this.currentRow();
-      return this.done({ kind: "delete", provider: row?.provider, modelId: row?.modelId });
+    if (this.menu) { this.menu.handleInput(data); return; }
+    const shortcuts: [string, PickerAction["kind"]][] = [
+      ["ctrl+a", "add"], ["ctrl+u", "update"], ["ctrl+x", "delete"], ["ctrl+d", "set-default"],
+      ["ctrl+g", "defaults"], ["ctrl+r", "reset"],
+    ];
+    if (matchesKey(data, "ctrl+o")) { if (!this.assignment) this.openMenu(); return; }
+    for (const [key, kind] of shortcuts) {
+      if (matchesKey(data, key as any)) { if (!this.assignment) this.action(kind); return; }
     }
-
-    // Navigation and submit belong to the list; everything else is search text.
-    if (
-      matchesKey(data, "up") ||
-      matchesKey(data, "down") ||
-      matchesKey(data, "pageUp") ||
-      matchesKey(data, "pageDown") ||
-      matchesKey(data, "enter")
-    ) {
-      this.list.handleInput(data);
-      this.onChange();
-      return;
-    }
-
-    const before = this.search.getValue();
-    this.search.handleInput(data);
-    if (this.search.getValue() !== before) this.applyFilter();
-    this.onChange();
+    this.table.handleInput(data);
   }
+  render(width: number): string[] { return (this.menu ?? this.table).render(width); }
+  invalidate(): void { this.table.invalidate(); this.menu?.invalidate(); }
 }

package/extensions/lib/store.ts

@@ -20,12 +20,14 @@ export const USAGE_PATH = (): string => join(getAgentDir(), "bms-usage.json");
 export interface BmsSettings {
   version: 1;
   writeMode: WriteMode;
+  resultPlacement: "above" | "below";
   disabledProviders: string[];
 }
 
 const DEFAULT_SETTINGS: BmsSettings = {
   version: 1,
   writeMode: "overlay",
+  resultPlacement: "below",
   disabledProviders: [],
 };
 
@@ -72,6 +74,7 @@ export function loadSettings(): BmsSettings {
     return {
       version: 1,
       writeMode: raw.writeMode === "direct" ? "direct" : "overlay",
+      resultPlacement: raw.resultPlacement === "above" ? "above" : "below",
       disabledProviders: Array.isArray(raw.disabledProviders)
         ? raw.disabledProviders.filter((value): value is string => typeof value === "string")
         : [],

package/extensions/lib/tui.ts

@@ -0,0 +1,320 @@
+import {
+  Input, fuzzyFilter, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi,
+  type Component, type Focusable,
+} from "@earendil-works/pi-tui";
+
+import { loadSettings } from "./store.ts";
+
+export type Placement = "above" | "below";
+
+// Also works with older settings files while the store migration is rolled out.
+export function resultPlacement(): Placement {
+  return (loadSettings() as { resultPlacement?: Placement }).resultPlacement ?? "below";
+}
+export interface TableColumn { key: string; label: string; width?: number }
+export interface TableRow {
+  value: string;
+  label: string;
+  description?: string;
+  cells?: Record<string, string>;
+}
+export interface TableSelectOptions {
+  title: string;
+  columns?: TableColumn[];
+  rows: TableRow[];
+  hint?: string;
+  search?: boolean;
+  placement?: Placement;
+  initialValue?: string;
+  state?: SelectionState;
+}
+export interface SelectionState { query?: string; selectedValue?: string }
+
+/** Distinguish keys from their actions; omit whole hints rather than cut a key. */
+export function shortcutLine(theme: any, hint: string, width: number): string {
+  const chunks = hint.split(/\s*·\s*/);
+  const rendered: string[] = [];
+  let used = 0;
+  for (const chunk of chunks) {
+    const match = chunk.match(/^(↑↓|enter|esc|space|ctrl\+[a-z])\s+(.*)$/i);
+    const key = match?.[1].replace(/^enter$/i, "Enter").replace(/^esc$/i, "Esc").replace(/^space$/i, "Space").replace(/^ctrl\+([a-z])$/i, (_, letter: string) => `Ctrl+${letter.toUpperCase()}`);
+    const plain = match ? `[${key}] ${match[2]}` : chunk;
+    if (used + plain.length + (rendered.length ? 3 : 0) > width) break;
+    rendered.push(match ? color(theme, "accent", `[${key}]`) + " " + color(theme, "muted", match[2]) : color(theme, "muted", chunk));
+    used += plain.length + (rendered.length > 1 ? 3 : 0);
+  }
+  return rendered.join(color(theme, "dim", "   "));
+}
+
+export function color(theme: any, role: string, text: string): string {
+  return typeof theme?.fg === "function" ? theme.fg(role, text) : text;
+}
+
+// Keep each cell on one terminal line. Widths are terminal cells, not JS length.
+function singleLine(text: string): string { return text.replace(/[\r\n\t]/g, " "); }
+export function fitCell(text: string, width: number): string {
+  const clipped = truncateToWidth(singleLine(text), Math.max(0, width), "…");
+  return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+}
+
+/** A prompt-area dialog. Pi focuses this object, which forwards focus to Input. */
+export class TableSelect implements Component, Focusable {
+  protected input: Input;
+  protected options: TableSelectOptions;
+  protected theme: any;
+  protected changed: () => void;
+  protected done: (value: string | undefined) => void;
+  protected filtered: TableRow[] = [];
+  protected selected = 0;
+  private start = 0;
+  private _focused = false;
+  get focused(): boolean { return this._focused; }
+  set focused(value: boolean) {
+    this._focused = value;
+    this.input.focused = value && this.options.search !== false;
+  }
+
+  constructor(options: TableSelectOptions, theme: any, changed: () => void,
+    done: (value: string | undefined) => void, state: SelectionState = {}) {
+    this.options = options;
+    this.theme = theme;
+    this.changed = changed;
+    this.done = done;
+    this.input = new Input({ prompt: "> ", placeholder: "Search…",
+      placeholderStyle: text => color(this.theme, "dim", text) });
+    this.input.setValue(state.query ?? "");
+    this.filter(state.selectedValue ?? options.initialValue);
+  }
+
+  get state(): SelectionState {
+    return { query: this.input.getValue(), selectedValue: this.currentItem()?.value };
+  }
+  currentItem(): TableRow | undefined { return this.filtered[this.selected]; }
+  private filter(preferred?: string): void {
+    const query = this.input.getValue().trim();
+    this.filtered = query ? fuzzyFilter(this.options.rows, query,
+      row => `${row.label} ${row.value} ${row.description ?? ""} ${Object.values(row.cells ?? {}).join(" ")}`)
+      : this.options.rows;
+    const index = this.filtered.findIndex(row => row.value === preferred);
+    this.selected = index < 0 ? 0 : index;
+    this.start = 0;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape")) { this.done(undefined); return; }
+    if (matchesKey(data, "enter")) {
+      const item = this.currentItem();
+      if (item) this.done(item.value);
+      return;
+    }
+    const up = matchesKey(data, "up") || matchesKey(data, "pageUp");
+    const down = matchesKey(data, "down") || matchesKey(data, "pageDown");
+    if (up || down) {
+      const direction = (up ? -1 : 1) * (this.options.search !== false && this.options.placement === "above" ? -1 : 1);
+      const step = matchesKey(data, "pageUp") || matchesKey(data, "pageDown") ? 6 : 1;
+      this.selected = Math.max(0, Math.min(this.filtered.length - 1, this.selected + direction * step));
+    } else if (this.options.search !== false) {
+      const before = this.input.getValue();
+      const selectedValue = this.currentItem()?.value;
+      this.input.handleInput(data);
+      if (this.input.getValue() !== before) this.filter(selectedValue);
+    }
+    this.changed();
+  }
+
+  protected tableLines(width: number): string[] {
+    const columns = this.options.columns ?? [
+      { key: "label", label: "", width: 28 }, { key: "description", label: "" },
+    ];
+    const cell = (row: TableRow, key: string) => row.cells?.[key]
+      ?? (key === "label" ? row.label : key === "description" ? row.description ?? "" : "");
+    // Reserve natural widths for metadata, give remaining room to the main label.
+    const sizes = columns.map(column => Math.max(1, column.width ?? Math.max(
+      visibleWidth(column.label), ...this.options.rows.map(row => visibleWidth(singleLine(cell(row, column.key)))))));
+    const available = Math.max(0, width - 2 - Math.max(0, columns.length - 1) * 2);
+    if (sizes.length) sizes[0] = Math.max(1, Math.min(24, Math.floor(width * 0.4)),
+      available - sizes.slice(1).reduce((a, b) => a + b, 0));
+    const line = (values: string[]) => values.map((value, i) => fitCell(value, sizes[i]!)).join("  ");
+    const header = columns.some(column => column.label)
+      ? [color(this.theme, "muted", truncateToWidth("  " + line(columns.map(column => column.label)), width, ""))] : [];
+    if (!this.filtered.length) return [...header, color(this.theme, "warning", truncateToWidth("  No matches", width, ""))];
+    this.start = Math.min(this.start, Math.max(0, this.filtered.length - 6));
+    if (this.selected < this.start) this.start = this.selected;
+    if (this.selected >= this.start + 6) this.start = this.selected - 5;
+    let indices = Array.from({ length: Math.min(6, this.filtered.length - this.start) }, (_, i) => this.start + i);
+    if (this.options.search !== false && this.options.placement === "above") indices = indices.reverse();
+    return [...header, ...indices.map(index => {
+      const row = this.filtered[index]!;
+      const text = fitCell((index === this.selected ? "› " : "  ") + line(columns.map(column => cell(row, column.key))), width);
+      if (index !== this.selected) return text;
+      const selected = color(this.theme, "accent", text);
+      return typeof this.theme?.bg === "function" ? this.theme.bg("selectedBg", selected) : selected;
+    })];
+  }
+
+  render(width: number): string[] {
+    width = Math.max(1, width);
+    const border = color(this.theme, "borderAccent", "─".repeat(width));
+    const prompt = this.options.search === false ? [] : [border, ...this.input.render(width), border];
+    const results = this.tableLines(width);
+    const count = this.filtered.length === this.options.rows.length
+      ? `${this.filtered.length} results` : `${this.filtered.length} of ${this.options.rows.length} results`;
+    const summary = color(this.theme, "dim", truncateToWidth(count, width, ""));
+    const shortcuts = shortcutLine(this.theme, this.options.hint ?? "↑↓ move · enter select · esc back", width);
+    return [color(this.theme, "accent", truncateToWidth(singleLine(this.options.title), width, "…")),
+      ...(this.options.placement === "above" && prompt.length
+        ? [shortcuts, summary, ...results, ...prompt]
+        : [...prompt, ...results, summary, shortcuts])];
+  }
+  invalidate(): void { this.input.invalidate(); }
+}
+
+export async function tableSelect(ctx: any, options: TableSelectOptions): Promise<string | undefined> {
+  return ctx.ui.custom((tui: any, theme: any, _kb: any, done: any) => {
+    const table = new TableSelect({ ...options, placement: options.placement ?? resultPlacement() }, theme, () => tui.requestRender(), value => {
+      if (options.state) Object.assign(options.state, table.state);
+      done(value);
+    }, options.state);
+    return table;
+  });
+}
+
+export interface ConfirmActionOptions { title: string; lines: string[]; confirmLabel: string }
+export class ConfirmAction extends TableSelect {
+  private lines: string[];
+  constructor(options: ConfirmActionOptions, theme: any, changed: () => void, done: (confirmed: boolean) => void) {
+    super({ title: options.title, search: false,
+      rows: [{ value: "cancel", label: "Cancel" }, { value: "confirm", label: options.confirmLabel }],
+    }, theme, changed, value => done(value === "confirm"));
+    this.lines = options.lines;
+  }
+  override render(width: number): string[] {
+    const [title, ...choices] = super.render(width);
+    return [title!, ...this.lines.flatMap(line => wrapTextWithAnsi(line, Math.max(1, width))), ...choices];
+  }
+}
+export async function confirmAction(ctx: any, options: ConfirmActionOptions): Promise<boolean> {
+  return (await ctx.ui.custom((tui: any, theme: any, _kb: any, done: any) =>
+    new ConfirmAction(options, theme, () => tui.requestRender(), done))) === true;
+}
+
+export interface FormField {
+  key: string; label: string; value: string; description?: string;
+  edit: () => Promise<string | undefined>;
+}
+export interface EditFormOptions {
+  title: string; fields: FormField[]; onSave: () => Promise<boolean | void>; hint?: string;
+}
+
+/** Field callbacks edit the caller's draft. Only onSave may persist it. */
+export class Form implements Component {
+  private options: EditFormOptions;
+  private theme: any;
+  private changed: () => void;
+  private done: (saved: boolean) => void;
+  private fields: FormField[];
+  private originals: string[];
+  private selected = 0;
+  private busy = false;
+  private discard = false;
+  private discardSelected = false;
+  private error = "";
+  private editField: (field: FormField) => Promise<string | undefined>;
+  private save: () => Promise<boolean | void>;
+  constructor(options: EditFormOptions, theme: any, changed: () => void, done: (saved: boolean) => void,
+    editField: (field: FormField) => Promise<string | undefined> = field => field.edit(),
+    save: () => Promise<boolean | void> = options.onSave) {
+    this.editField = editField;
+    this.save = save;
+    this.options = options;
+    this.theme = theme;
+    this.changed = changed;
+    this.done = done;
+    this.fields = options.fields.map(field => ({ ...field }));
+    this.originals = this.fields.map(field => field.value);
+  }
+  private get dirty(): boolean { return this.fields.some((field, i) => field.value !== this.originals[i]); }
+  private async run(action: () => Promise<void>): Promise<void> {
+    this.busy = true;
+    this.error = "";
+    this.changed();
+    try { await action(); } catch (error) { this.error = error instanceof Error ? error.message : String(error); }
+    finally { this.busy = false; this.changed(); }
+  }
+  handleInput(data: string): void {
+    if (this.busy) return;
+    if (this.discard) {
+      if (matchesKey(data, "escape")) this.discard = false;
+      else if (matchesKey(data, "up") || matchesKey(data, "down")) this.discardSelected = !this.discardSelected;
+      else if (matchesKey(data, "enter")) {
+        if (this.discardSelected) this.done(false);
+        else this.discard = false;
+      }
+    } else if (matchesKey(data, "escape")) {
+      if (!this.dirty) this.done(false);
+      else { this.discard = true; this.discardSelected = false; }
+    } else if (matchesKey(data, "ctrl+s") || (matchesKey(data, "enter") && this.selected === this.fields.length)) {
+      void this.run(async () => { if (await this.save() !== false) this.done(true); });
+    } else if (matchesKey(data, "enter") && this.selected === this.fields.length + 1) {
+      if (!this.dirty) this.done(false);
+      else { this.discard = true; this.discardSelected = false; }
+    } else if (matchesKey(data, "up")) this.selected = Math.max(0, this.selected - 1);
+    else if (matchesKey(data, "down")) this.selected = Math.min(this.fields.length + 1, this.selected + 1);
+    else if (matchesKey(data, "enter")) {
+      const field = this.fields[this.selected];
+      if (field) void this.run(async () => {
+        const value = await this.editField(field);
+        if (value !== undefined) field.value = value;
+      });
+    }
+    this.changed();
+  }
+  render(width: number): string[] {
+    const start = Math.max(0, this.selected - 5);
+    const labelWidth = Math.min(28, Math.max(18, ...this.fields.map(field => visibleWidth(field.label))));
+    const formRows = [...this.fields, { label: "Save configuration", value: "", key: "__save" }, { label: "Back", value: "", key: "__back" }];
+    const rows = this.discard ? ["Discard unsaved changes?",
+      `${!this.discardSelected ? "›" : " "} Keep editing`, `${this.discardSelected ? "›" : " "} Discard`]
+      : formRows.slice(start, start + 6).map((field, index) => {
+        const text = fitCell(`${index + start === this.selected ? "›" : " "} ${fitCell(field.label, labelWidth)}  ${field.value}`, width);
+        return index + start === this.selected && typeof this.theme?.bg === "function"
+          ? this.theme.bg("selectedBg", color(this.theme, "accent", text)) : text;
+      });
+    return [color(this.theme, "accent", this.options.title + (this.dirty ? " *" : "")),
+      color(this.theme, "muted", `  ${fitCell("FIELD", labelWidth)}  VALUE`), ...rows,
+      ...(this.fields[this.selected]?.description ? [color(this.theme, "dim", this.fields[this.selected]!.description!)] : []),
+      ...(this.options.hint ? this.options.hint.split("\n").map(line => color(this.theme, "dim", line)) : []),
+      ...(this.busy || this.error ? [this.busy ? "Working…" : color(this.theme, "error", this.error)] : []),
+      shortcutLine(this.theme, this.discard ? "↑↓ move · enter choose · esc back" : "↑↓ move · enter choose · ctrl+s save · esc back", width)]
+      .map(line => truncateToWidth(line, Math.max(1, width), "…"));
+  }
+  invalidate(): void {}
+}
+
+export async function editForm(ctx: any, options: EditFormOptions): Promise<boolean> {
+  // Pi restores its editor when a custom dialog closes. Suspend the form before
+  // opening child dialogs, then remount the same draft/selection afterwards.
+  let form: Form | undefined;
+  let finish: (value: any) => void = () => {};
+  let render = () => {};
+  let completed: boolean | undefined;
+  for (;;) {
+    const result: any = await ctx.ui.custom((tui: any, theme: any, _kb: any, done: any) => {
+      finish = done;
+      render = () => tui.requestRender();
+      form ??= new Form(options, theme, () => render(), saved => { completed = saved; finish(saved); },
+        field => new Promise<string | undefined>((resolve, reject) => {
+          finish({ edit: field.edit, resolve, reject });
+        }), () => new Promise<boolean | void>((resolve, reject) => {
+          finish({ edit: options.onSave, resolve, reject });
+        }));
+      return form;
+    });
+    if (typeof result === "boolean" || !result?.edit) return result === true;
+    try { result.resolve(await result.edit()); } catch (error) { result.reject(error); }
+    // Let the form's pending edit callback update its display before remounting.
+    await Promise.resolve();
+    await Promise.resolve();
+    if (completed !== undefined) return completed;
+  }
+}