@gonrocca/zero-pi 0.1.30 → 0.1.32

package/extensions/zero-models-picker.ts

@@ -0,0 +1,488 @@
+// zero-pi — the /zero-models interactive picker, pure-state module.
+//
+// The no-arg path of /zero-models is a single boxed-window TUI. This file holds
+// every *decision* of that picker — menu-entry construction, highlighted-index
+// movement, screen transitions, and the staged-edit accumulator — as pure,
+// dependency-free TypeScript so it is unit-testable with `node --test`. The
+// pi-TUI render+input shell lives in `zero-models.ts` and owns no navigation
+// logic; it holds one `PickerState`, forwards keystrokes here, and re-renders.
+//
+// This file has NO `node:fs` and NO pi imports. It takes injected data
+// (registry groups, current models/providers, pending suggestions) and returns
+// new state. Type-only imports are `import type` so `--experimental-strip-types`
+// erases them with no runtime resolution. Mirrors the `autotune.ts` precedent.
+
+import type { Phase, PhaseModels, PhaseProviders } from "./zero-models.ts";
+import type { AutotuneMode } from "./autotune.ts";
+import type { AutotunePending } from "./autotune-extension.ts";
+
+/** The SDD phases, in pipeline order — re-stated locally so the pure module
+ *  carries no value import. Must stay in lockstep with `PHASES` in
+ *  `zero-models.ts`. */
+const PHASES = ["explore", "plan", "build", "veredicto"] as const;
+
+/** The three autotune modes offered on the autotune screen. */
+const AUTOTUNE_MODES = ["auto", "ask", "off"] as const;
+
+// ---------------------------------------------------------------------------
+// Screen model
+// ---------------------------------------------------------------------------
+
+/** Which sub-screen the picker is currently showing. */
+export type Screen = "main" | "provider" | "model" | "autotune";
+
+/** One selectable row in the current screen. */
+export interface MenuEntry {
+  /** Stable kind discriminator for the transition functions. */
+  kind:
+    | "apply-pending" // ★ aplicar sugerencia      (main, conditional)
+    | "phase" // explore/plan/build/veredicto (main)
+    | "autotune" // autotune → <mode>          (main)
+    | "save" // — guardar y salir —        (main)
+    | "provider" // a concrete provider id     (provider screen)
+    | "custom-provider" // — otro provider (escribir) —
+    | "model" // a concrete model id        (model screen)
+    | "custom-model" // — otro modelo (escribir) —
+    | "autotune-mode"; // auto | ask | off           (autotune screen)
+  /** The text shown for the row (Spanish, voseo). */
+  label: string;
+  /** Payload: phase name, provider id, model id, or autotune mode. */
+  value: string;
+}
+
+// ---------------------------------------------------------------------------
+// Staged edits (the accumulator)
+// ---------------------------------------------------------------------------
+
+/** Edits staged in memory; only written to zero.json on save. */
+export interface StagedEdits {
+  /** From `readModels` — a mutated copy, never the caller's object. */
+  models: PhaseModels;
+  /** From `readProviders` — a mutated copy, parallel to {@link models}. */
+  providers: PhaseProviders;
+  /** The autotune mode, possibly changed from disk. */
+  autotuneMode: AutotuneMode;
+  /** Any phase model/provider changed. */
+  changed: boolean;
+  /** `autotuneMode` differs from disk. */
+  autotuneChanged: boolean;
+  /** A pending suggestion was applied. */
+  pendingApplied: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Picker state (the single value the component holds)
+// ---------------------------------------------------------------------------
+
+/** The full picker state — one mutable value the component holds for its
+ *  lifetime; the transition functions mutate-and-return it. */
+export interface PickerState {
+  /** The sub-screen currently shown. */
+  screen: Screen;
+  /** Highlighted row index, always within `[0, entries.length)`. */
+  cursor: number;
+  /** Menu rows for the current screen — derived, never hand-mutated. */
+  entries: MenuEntry[];
+  /** Staged, unsaved edits. */
+  edits: StagedEdits;
+  /** Pending autotune suggestions still un-applied (drives the apply entry). */
+  pending: AutotunePending[];
+  /** Provider→models registry groups, captured once at open. */
+  groups: Map<string, string[]>;
+  /** Fallback model list when the registry is empty. */
+  fallbackModels: readonly string[];
+  /** Drill-down context: the phase being edited (provider/model screens). */
+  drillPhase: Phase | null;
+  /** Drill-down context: provider chosen so far (model screen). */
+  drillProvider: string | null;
+  /** When non-null, the component shows an inline text input for this. */
+  textPrompt: { for: "provider" | "model"; label: string } | null;
+}
+
+// ---------------------------------------------------------------------------
+// Transition results
+// ---------------------------------------------------------------------------
+
+/** Discriminated outcome of `enter()`/`back()` — lets the component act. */
+export type EnterResult =
+  | { type: "state"; state: PickerState } // stay open, re-render
+  | { type: "save"; state: PickerState } // close, persist edits
+  | { type: "quit" }; // close, write nothing
+
+// ---------------------------------------------------------------------------
+// Initial state
+// ---------------------------------------------------------------------------
+
+/** The escape-row label for typing a custom provider id. */
+const CUSTOM_PROVIDER_LABEL = "— otro provider (escribir) —";
+/** The escape-row label for typing a custom model id. */
+const CUSTOM_MODEL_LABEL = "— otro modelo (escribir) —";
+/** The save-and-exit row label. */
+const SAVE_LABEL = "— guardar y salir —";
+
+/** Render a phase's current `provider/model` (provider omitted when empty). */
+function phaseLabel(
+  phase: Phase,
+  models: PhaseModels,
+  providers: PhaseProviders,
+): string {
+  const provider = providers[phase];
+  const model = provider ? `${provider}/${models[phase]}` : models[phase];
+  return `${phase}   →   ${model}`;
+}
+
+/** Render the `★ aplicar sugerencia` label from the pending adjustments. */
+function applyLabel(pending: readonly AutotunePending[]): string {
+  return `★ aplicar sugerencia: ${pending
+    .map((p) => `${p.phase} → ${p.to}`)
+    .join(", ")}`;
+}
+
+/**
+ * Build the initial main-screen picker state from disk-read inputs.
+ *
+ * The `models`/`providers` maps are copied so staged edits never mutate the
+ * caller's objects. `edits.autotuneMode` snapshots the disk value; the three
+ * change flags start `false`. The result is on `screen: "main"` with `cursor`
+ * at `0` and `entries` already built via `rebuildEntries`.
+ */
+export function createPickerState(input: {
+  models: PhaseModels;
+  providers: PhaseProviders;
+  autotuneMode: AutotuneMode;
+  pending: AutotunePending[];
+  groups: Map<string, string[]>;
+  fallbackModels: readonly string[];
+}): PickerState {
+  const state: PickerState = {
+    screen: "main",
+    cursor: 0,
+    entries: [],
+    edits: {
+      models: { ...input.models },
+      providers: { ...input.providers },
+      autotuneMode: input.autotuneMode,
+      changed: false,
+      autotuneChanged: false,
+      pendingApplied: false,
+    },
+    pending: [...input.pending],
+    groups: input.groups,
+    fallbackModels: input.fallbackModels,
+    drillPhase: null,
+    drillProvider: null,
+    textPrompt: null,
+  };
+  return rebuildEntries(state);
+}
+
+// ---------------------------------------------------------------------------
+// rebuildEntries
+// ---------------------------------------------------------------------------
+
+/** Build the rows for the `main` screen. */
+function mainEntries(state: PickerState): MenuEntry[] {
+  const entries: MenuEntry[] = [];
+
+  // Conditional apply-pending row, prepended when a suggestion is staged.
+  if (state.pending.length > 0) {
+    entries.push({
+      kind: "apply-pending",
+      label: applyLabel(state.pending),
+      value: "apply",
+    });
+  }
+
+  // One row per SDD phase, in pipeline order.
+  for (const phase of PHASES) {
+    entries.push({
+      kind: "phase",
+      label: phaseLabel(phase, state.edits.models, state.edits.providers),
+      value: phase,
+    });
+  }
+
+  // The autotune row, then the save row.
+  entries.push({
+    kind: "autotune",
+    label: `autotune   →   ${state.edits.autotuneMode}`,
+    value: "autotune",
+  });
+  entries.push({ kind: "save", label: SAVE_LABEL, value: "save" });
+
+  return entries;
+}
+
+/** Build the rows for the `provider` screen — sorted provider ids + escape. */
+function providerEntries(state: PickerState): MenuEntry[] {
+  const entries: MenuEntry[] = [];
+  for (const provider of [...state.groups.keys()].sort()) {
+    entries.push({ kind: "provider", label: provider, value: provider });
+  }
+  entries.push({
+    kind: "custom-provider",
+    label: CUSTOM_PROVIDER_LABEL,
+    value: "",
+  });
+  return entries;
+}
+
+/** Build the rows for the `model` screen — models for the drilled provider
+ *  (or `fallbackModels` when the registry is empty) + custom-model escape. */
+function modelEntries(state: PickerState): MenuEntry[] {
+  const models =
+    state.drillProvider !== null
+      ? (state.groups.get(state.drillProvider) ?? state.fallbackModels)
+      : state.fallbackModels;
+  const entries: MenuEntry[] = [];
+  for (const model of models) {
+    entries.push({ kind: "model", label: model, value: model });
+  }
+  entries.push({ kind: "custom-model", label: CUSTOM_MODEL_LABEL, value: "" });
+  return entries;
+}
+
+/** Build the rows for the `autotune` screen — the three modes. */
+function autotuneEntries(): MenuEntry[] {
+  return AUTOTUNE_MODES.map((mode) => ({
+    kind: "autotune-mode" as const,
+    label: mode,
+    value: mode,
+  }));
+}
+
+/**
+ * Recompute `state.entries` for the current screen + drill context.
+ *
+ * Idempotent: calling it twice in a row produces the same rows. After
+ * rebuilding, `cursor` is clamped into `[0, entries.length)` so a transition
+ * that shrinks the row list never leaves the highlight out of bounds. Mutates
+ * and returns the same `PickerState`.
+ */
+export function rebuildEntries(state: PickerState): PickerState {
+  switch (state.screen) {
+    case "main":
+      state.entries = mainEntries(state);
+      break;
+    case "provider":
+      state.entries = providerEntries(state);
+      break;
+    case "model":
+      state.entries = modelEntries(state);
+      break;
+    case "autotune":
+      state.entries = autotuneEntries();
+      break;
+  }
+
+  // Clamp the cursor — a shrunk list must never leave it past the last row.
+  const n = state.entries.length;
+  if (n === 0) {
+    state.cursor = 0;
+  } else if (state.cursor < 0) {
+    state.cursor = 0;
+  } else if (state.cursor >= n) {
+    state.cursor = n - 1;
+  }
+
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// navigate
+// ---------------------------------------------------------------------------
+
+/**
+ * Move the highlighted-row index by `dir` (`-1` up, `+1` down), wrapping
+ * cyclically at both ends: Up at index 0 lands on the last row, Down at the
+ * last row lands on row 0 (resolves Open Question 1). A single-entry list is
+ * a fixed point — any move stays on row 0. An empty list keeps `cursor` at 0.
+ *
+ * Mutates and returns the same `PickerState`; the filesystem is never touched.
+ */
+export function navigate(state: PickerState, dir: -1 | 1): PickerState {
+  const n = state.entries.length;
+  if (n === 0) {
+    state.cursor = 0;
+  } else {
+    state.cursor = (state.cursor + dir + n) % n;
+  }
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// enter / back — Enter/Esc dispatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Dispatch Enter on the highlighted entry. Returns an {@link EnterResult}:
+ *
+ * - `phase` → drills into provider selection (`screen: "provider"`), or
+ *   straight to `model` with `fallbackModels` when the registry is empty.
+ * - `provider` → records `drillProvider`, drills into model selection.
+ * - `custom-provider` / `custom-model` → opens `textPrompt`, stays on screen.
+ * - `model` → commits the model/provider into `edits` for `drillPhase`,
+ *   marks `edits.changed`, returns to `main`.
+ * - `autotune` → drills into the autotune-mode screen.
+ * - `autotune-mode` → records the mode, marks `autotuneChanged` when it
+ *   differs from the staged value, returns to `main`.
+ * - `apply-pending` → applies every pending `to` into `edits.models`,
+ *   marks `changed` + `pendingApplied`, clears `state.pending`.
+ * - `save` → `{ type: "save" }`.
+ *
+ * Every staying-open path rebuilds `entries`. Filesystem is never touched.
+ */
+export function enter(state: PickerState): EnterResult {
+  const entry = state.entries[state.cursor];
+  if (!entry) return { type: "state", state };
+
+  switch (entry.kind) {
+    case "phase": {
+      state.drillPhase = entry.value as Phase;
+      state.drillProvider = null;
+      // Skip the provider screen entirely when the registry is empty —
+      // jump straight to model selection over `fallbackModels`.
+      state.screen = state.groups.size === 0 ? "model" : "provider";
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "provider": {
+      state.drillProvider = entry.value;
+      state.screen = "model";
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "custom-provider": {
+      state.textPrompt = { for: "provider", label: entry.label };
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "custom-model": {
+      state.textPrompt = { for: "model", label: entry.label };
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "model": {
+      if (state.drillPhase !== null) {
+        const phase = state.drillPhase;
+        state.edits.models[phase] = entry.value;
+        // `drillProvider` is the provider picked/typed on the provider screen,
+        // or `null` when the empty-registry skip jumped straight here — in
+        // which case there is no provider, so `""`. (The design's middle
+        // `resolveProvider` term is unreachable in the pure module: a null
+        // `drillProvider` only ever co-occurs with an empty `groups`.)
+        state.edits.providers[phase] = state.drillProvider ?? "";
+        state.edits.changed = true;
+      }
+      state.screen = "main";
+      state.drillPhase = null;
+      state.drillProvider = null;
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "autotune": {
+      state.screen = "autotune";
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "autotune-mode": {
+      const mode = entry.value as AutotuneMode;
+      if (mode !== state.edits.autotuneMode) {
+        state.edits.autotuneMode = mode;
+        state.edits.autotuneChanged = true;
+      }
+      state.screen = "main";
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "apply-pending": {
+      for (const adj of state.pending) {
+        state.edits.models[adj.phase] = adj.to;
+      }
+      state.edits.changed = true;
+      state.edits.pendingApplied = true;
+      state.pending = [];
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "save":
+      return { type: "save", state };
+  }
+}
+
+/**
+ * Dispatch Esc. From a drill screen (`provider`/`model`/`autotune`) it
+ * returns to `main` with the drill context cleared and **no** edit
+ * committed. From `main` it returns `{ type: "quit" }` so the handler
+ * closes the picker without writing `zero.json`.
+ */
+export function back(state: PickerState): EnterResult {
+  if (state.screen === "main") {
+    return { type: "quit" };
+  }
+  state.screen = "main";
+  state.drillPhase = null;
+  state.drillProvider = null;
+  state.textPrompt = null;
+  state.cursor = 0;
+  return { type: "state", state: rebuildEntries(state) };
+}
+
+// ---------------------------------------------------------------------------
+// submitText — commit a typed custom value
+// ---------------------------------------------------------------------------
+
+/**
+ * Commit a typed custom value from the inline text input opened by a
+ * `custom-provider` / `custom-model` escape row.
+ *
+ * - `textPrompt.for === "provider"` → records the trimmed `typed` string as
+ *   `drillProvider` and advances to the `model` screen so a model can be
+ *   picked under the just-typed provider.
+ * - `textPrompt.for === "model"` → commits the trimmed `typed` string as the
+ *   drilled phase's model into `edits.models`, records the provider
+ *   (`drillProvider ?? ""`, matching the model-commit semantics of `enter`)
+ *   into `edits.providers`, sets `edits.changed`, and returns to `main`.
+ * - empty / whitespace `typed` → a no-op: nothing is committed, the screen is
+ *   left unchanged, only `textPrompt` is cleared so the list shows again.
+ *
+ * `textPrompt` is cleared on every path and `rebuildEntries` is always called.
+ * Mutates and returns the same `PickerState`; the filesystem is never touched.
+ */
+export function submitText(state: PickerState, typed: string): PickerState {
+  const prompt = state.textPrompt;
+  const value = typed.trim();
+
+  // Empty / whitespace input, or no prompt open: a no-op. Drop the prompt and
+  // re-show the current list screen unchanged — no edit is committed.
+  if (prompt === null || value === "") {
+    state.textPrompt = null;
+    return rebuildEntries(state);
+  }
+
+  if (prompt.for === "provider") {
+    state.drillProvider = value;
+    state.screen = "model";
+    state.cursor = 0;
+  } else {
+    // prompt.for === "model": commit the typed model into the drilled phase.
+    if (state.drillPhase !== null) {
+      const phase = state.drillPhase;
+      state.edits.models[phase] = value;
+      state.edits.providers[phase] = state.drillProvider ?? "";
+      state.edits.changed = true;
+    }
+    state.screen = "main";
+    state.drillPhase = null;
+    state.drillProvider = null;
+    state.cursor = 0;
+  }
+
+  state.textPrompt = null;
+  return rebuildEntries(state);
+}

package/extensions/zero-models.ts

@@ -19,16 +19,25 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-// `@earendil-works/pi-tui` is provided by the pi runtime as an ambient bare
-// specifier — it is NOT a `package.json` dependency. It is loaded lazily, via
-// a dynamic `import()` inside the no-arg handler branch, NOT a top-level value
-// import: a static `import { Box } from "@earendil-works/pi-tui"` would be
-// evaluated whenever any consumer imports this module — including
-// `zero-models.test.ts`, which imports the deterministic helpers — and would
-// crash `node --test` with `ERR_MODULE_NOT_FOUND`. `import type` below is
-// fully erased by `--experimental-strip-types`, so it never triggers
-// resolution. The runtime classes are reached only from inside pi.
-import type { Component } from "@earendil-works/pi-tui";
+// This module has NO `@earendil-works/pi-tui` import at all — not a value
+// import, not an `import type`. The no-arg picker is a `ctx.ui.custom()`
+// component, and `ctx.ui.custom`'s factory only needs an object that exposes
+// `render(width): string[]` (plus optional `handleInput`/`invalidate`) — pi's
+// own docs example returns exactly such a plain object literal. So the picker
+// builds its framed layout by hand with Unicode box-drawing characters and
+// satisfies the contract via the small local `Component` interface below. Not
+// importing the ambient `@earendil-works/pi-tui` specifier at all means even a
+// stray static reference can never crash `node --test` with
+// `ERR_MODULE_NOT_FOUND` when `zero-models.test.ts` imports the deterministic
+// helpers.
+
+/** The shape `ctx.ui.custom()`'s factory must return — a renderable component.
+ *  Declared locally so this module pulls in no ambient TUI specifier. */
+interface Component {
+  render(width: number): string[];
+  handleInput?(data: string): void;
+  invalidate?(): void;
+}
 
 import { readAutotuneMode, type AutotuneMode } from "./autotune.ts";
 import type { AutotunePending } from "./autotune-extension.ts";
@@ -206,18 +215,6 @@ export function groupByProvider(models: readonly PiModel[]): Map<string, string[
 interface PiTui {
   requestRender(): void;
 }
-/** A pi-TUI component that groups children vertically and renders a frame. */
-interface PiBox extends Component {
-  addChild(child: Component): void;
-}
-/** The slice of `@earendil-works/pi-tui` the boxed picker constructs at
- *  runtime — `Box`/`Text`/`Spacer` constructors, captured from the lazy
- *  dynamic `import()` so this module never statically resolves the specifier. */
-interface PiTuiModule {
-  Box: new (paddingX?: number, paddingY?: number) => PiBox;
-  Text: new (content: string, paddingX?: number, paddingY?: number) => Component;
-  Spacer: new (lines: number) => Component;
-}
 /** A pi theme — only the foreground-color helper the picker uses. */
 interface PiTheme {
   fg(color: string, text: string): string;
@@ -320,6 +317,60 @@ function clampLine(line: string, width: number): string {
   return line.length > width ? line.slice(0, width) : line;
 }
 
+/** Unicode box-drawing characters for the picker's 4-sided frame. */
+const BOX = {
+  topLeft: "┌",
+  topRight: "┐",
+  bottomLeft: "└",
+  bottomRight: "┘",
+  horizontal: "─",
+  vertical: "│",
+} as const;
+/** The theme color used for the picker's box frame. */
+const FRAME_COLOR = "accent";
+/** Below this `width` a real frame cannot be drawn — render unframed instead. */
+const MIN_BOX_WIDTH = 10;
+
+/**
+ * One content row of the boxed panel, given as *plain* text plus an optional
+ * theme color. {@link frameBox} measures the plain `text`, then sizes and
+ * colorizes it — so an ANSI escape is never fed to `clampLine`/`padEnd`.
+ */
+interface BoxRow {
+  text: string;
+  color?: string;
+}
+
+/**
+ * Wrap content rows in a true 4-sided Unicode box.
+ *
+ * `width` is the full outer box width. Each row's *plain* text is truncated
+ * and space-padded to the inner width (`width - 4`: two `│` columns plus one
+ * space of padding on each side) — measured *before* `theme.fg` runs, so an
+ * ANSI escape is never measured. The frame chars and the row content are
+ * themed separately. When `width` is too small to frame, the plain rows are
+ * returned unframed (defensive — never produce garbage).
+ */
+function frameBox(rows: readonly BoxRow[], width: number, theme: PiTheme): string[] {
+  if (width < MIN_BOX_WIDTH) {
+    return rows.map((row) => clampLine(row.text, Math.max(0, width)));
+  }
+  const inner = width - 4;
+  const frame = (s: string): string => theme.fg(FRAME_COLOR, s);
+  const horizontal = BOX.horizontal.repeat(width - 2);
+  const top = frame(`${BOX.topLeft}${horizontal}${BOX.topRight}`);
+  const bottom = frame(`${BOX.bottomLeft}${horizontal}${BOX.bottomRight}`);
+  const side = frame(BOX.vertical);
+
+  const body = rows.map((row) => {
+    // Size on plain text, then colorize — never measure an ANSI string.
+    const sized = clampLine(row.text, inner).padEnd(inner, " ");
+    const content = row.color ? theme.fg(row.color, sized) : sized;
+    return `${side} ${content} ${side}`;
+  });
+  return [top, ...body, bottom];
+}
+
 /**
  * Build the inline pi-TUI component for the no-arg picker.
  *
@@ -333,68 +384,62 @@ function clampLine(line: string, width: number): string {
  * `Input`): pi-tui's `Input` is not shipped with type definitions in this pi
  * build and an embedded-input + `Focusable` wiring is the design's named
  * highest-risk path — the inline buffer is self-contained, needs no ambient
- * class beyond `Box`/`Text`/`Spacer`, and keeps the pure module's `submitText`
- * contract untouched.
+ * TUI class at all, and keeps the pure module's `submitText` contract
+ * untouched.
  *
  * The whole `handleInput` body is wrapped in a `try/catch` that closes the
  * component cleanly via `done({ type: "quit" })` on any error (Req 9).
+ *
+ * `render(width)` builds the framed layout by hand with Unicode box-drawing
+ * characters ({@link frameBox}) — no pi-tui components are involved — so the
+ * picker draws as a real closed rectangle.
  */
 function createPickerComponent(
   initial: PickerState,
-  pitui: PiTuiModule,
   theme: PiTheme,
   tui: PiTui,
   done: (result: EnterResult) => void,
 ): Component {
-  const { Box, Text, Spacer } = pitui;
   // The single mutable state reference; reassigned from the pure functions.
   let state = initial;
   // Inline text buffer — non-null only while `state.textPrompt` is open.
   let buffer: string | null = null;
 
-  /** Render the boxed panel for the current state. */
+  /**
+   * Render the boxed panel for the current state.
+   *
+   * Builds plain-text content rows with an optional theme color each, then
+   * hands them to {@link frameBox} which sizes (on plain text) and colorizes
+   * last. Defensive — it must never throw: rows carry plain text, theming is
+   * deferred to `frameBox`, and `frameBox` degrades gracefully on a tiny
+   * `width`.
+   */
   function render(width: number): string[] {
-    const box = new Box(1, 1);
-    const inner = Math.max(1, width - 4); // account for the box's paddingX
+    const rows: BoxRow[] = [];
 
-    box.addChild(new Text(clampLine(PICKER_TITLE, inner), 0, 0));
-    box.addChild(new Spacer(1));
+    rows.push({ text: PICKER_TITLE });
+    rows.push({ text: "" });
 
     if (state.textPrompt) {
       // Inline text-entry mode: show the prompt label and the typed buffer.
-      box.addChild(
-        new Text(clampLine(state.textPrompt.label, inner), 0, 0),
-      );
-      const typed = `> ${buffer ?? ""}`;
-      box.addChild(
-        new Text(theme.fg("accent", clampLine(typed, inner)), 0, 0),
-      );
-      box.addChild(new Spacer(1));
-      box.addChild(
-        new Text(
-          theme.fg("dim", clampLine("enter confirmar · esc volver", inner)),
-          0,
-          0,
-        ),
-      );
-      return box.render(width);
+      rows.push({ text: state.textPrompt.label });
+      rows.push({ text: `> ${buffer ?? ""}`, color: "accent" });
+      rows.push({ text: "" });
+      rows.push({ text: "enter confirmar · esc volver", color: "dim" });
+      return frameBox(rows, width, theme);
     }
 
     state.entries.forEach((entry, index) => {
       if (index === state.cursor) {
-        const row = clampLine(`> ${entry.label}`, inner);
-        box.addChild(new Text(theme.fg("accent", row), 0, 0));
+        rows.push({ text: `> ${entry.label}`, color: "accent" });
       } else {
-        const row = clampLine(`  ${entry.label}`, inner);
-        box.addChild(new Text(theme.fg("dim", row), 0, 0));
+        rows.push({ text: `  ${entry.label}`, color: "dim" });
       }
     });
 
-    box.addChild(new Spacer(1));
-    box.addChild(
-      new Text(theme.fg("dim", clampLine(PICKER_HELP, inner)), 0, 0),
-    );
-    return box.render(width);
+    rows.push({ text: "" });
+    rows.push({ text: PICKER_HELP, color: "dim" });
+    return frameBox(rows, width, theme);
   }
 
   /** Apply an `EnterResult` — re-render on `state`, close on `save`/`quit`. */
@@ -560,16 +605,11 @@ export default function register(pi?: PiExtensionAPI): void {
           fallbackModels: FALLBACK_MODELS,
         });
 
-        // Load pi-tui lazily — the bare specifier resolves only inside pi.
-        // This `import()` lives in the handler (already inside the swallowing
-        // `try/catch`), so a resolution failure becomes an error notification
-        // and never escapes (Req 9).
-        const pitui = (await import(
-          "@earendil-works/pi-tui"
-        )) as unknown as PiTuiModule;
-
+        // The picker is a self-contained `ctx.ui.custom()` component — it
+        // renders its own framed layout with box-drawing characters, so no
+        // pi-tui module is loaded here.
         const result = await ctx.ui.custom<EnterResult>((tui, theme, _kb, done) =>
-          createPickerComponent(initialState, pitui, theme, tui, done),
+          createPickerComponent(initialState, theme, tui, done),
         );
 
         if (result.type !== "save") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow, per-phase model autotune, and skill auto-learning. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [
@@ -44,6 +44,7 @@
     "extensions/sdd-agents.ts",
     "extensions/conversation-resume.ts",
     "extensions/zero-models.ts",
+    "extensions/zero-models-picker.ts",
     "extensions/autotune.ts",
     "extensions/autotune-extension.ts",
     "extensions/spec-merge.ts",