refactor(wizard): let the wizard own its keyboard nav instead of toggling the stepper's

[dawsontoth]

Unblocks #142 (ink-stepper 0.2.1 → 0.2.3), and removes some plumbing that was never doing anything.

What was wrong

Every step in the configuration wizard mounted with disableNavigation() and unmounted with enableNavigation():

const { disableNavigation, enableNavigation } = useStepperInput();

useEffect(() => {
    disableNavigation();
    return () => enableNavigation();
}, [disableNavigation, enableNavigation]);

All five steps, unconditionally, for their whole lifetime — so the Stepper's keyboardNav bindings were suppressed 100% of the time despite being declared keyboardNav={true}. They never ran.

That's because each step already owns its keys: its widget (Select, MultiSelect, BlinkingTextInput) consumes <enter> and advances by calling goNext() from onConfirm, and each step binds <esc> itself. The Stepper's bindings would have double-handled <enter>, which is exactly what the disableNavigation() calls were there to prevent.

What this does

Says it directly — keyboardNav={false} on the Stepper — and drops the five identical effects. That part is a pure no-op: the same wizard, minus a layer that cancelled itself out.

Also: the <esc> double-fire (review follow-up)

While reviewing, we found a second self-cancelling layer of exactly the same shape. ConfigurationWizard ran its own useInput that handled <esc> by calling onComplete(). Ink delivers input to every mounted useInput, so that fired on top of the active step's own <esc> handler: on any step past the first, <esc> ran the step's onBack() (or left the Model step's custom-entry sub-mode) and completed the wizard on top of it — so <esc> effectively exited the wizard instead of going back.

Dropping that redundant <esc> branch (keeping ctrl+x → ExitUI) lets each step own <esc> as intended: the first step exits, the rest go back. This is the one behavior change in the PR — <esc> back-navigation now actually works. Added a ConfigurationWizard test asserting the wizard no longer completes on <esc>.

Why it unblocks #142

Through 0.2.1, disableNavigation() only gated the Stepper's own useInput handler:

useInput((_input, key) => {
  if (isValidating || isNavigationDisabled) return;   // keyboard only
  ...
}, { isActive: keyboardNav });

A programmatic goNext() still worked, so the wizard advanced fine.

0.2.3 added an isBlocked() guard to the navigation functions themselves:

const isBlocked = useCallback(() => isValidatingRef.current || isNavigationDisabledRef.current, []);

const goNext = useCallback(async () => {
  if (isBlocked()) return;    // <-- now also swallows programmatic calls
  ...

So the same flag every step was setting now also swallowed that step's own explicit goNext(). The wizard could never leave step 1 — the frame kept rendering the provider list with the progress dot stuck on the first step, and the four walkthrough tests in ink/main.test.tsx failed. Not touching the flag at all makes the wizard behave identically under both versions.

Verification

Node 24.18.0, full suite (npx vitest --run):

tree	ink-stepper	result
main	0.2.1	ink/main.test.tsx 6/6 (3 consecutive runs)
main	0.2.3	4 failed / 2 passed
this branch	0.2.1	344/344
this branch	0.2.3	344/344

npm run lint, npm run format, and npm run build all clean.

Re-verified after rebasing onto current main (which now carries the AI SDK v4 / @openai/agents 0.15 bumps and a CI build job) and adding the <esc> fix: build, lint, format, and the full suite all green — 345/345, including the new ConfigurationWizard <esc> test. The build is now exercised by CI too, not just locally.

This PR is app code only — no manifest or lockfile changes. Once it lands, #142 should go green on a rebase.

Two notes for follow-up

1. ink-stepper is major-risk while it's 0.x. This was a patch release that changed what disableNavigation() means. Worth a Renovate rule treating ink-stepper as a major-grade update until 1.0, alongside the existing AI SDK / OpenAI Agents groupings. I'll open an upstream issue too — "suppress the stepper's keybindings but still allow explicit programmatic navigation" is a legitimate use case that 0.2.3 removed with no replacement.

2. ink-stepper@0.2.2+ declares a dependency on ws (^8.21.2) that is never imported anywhere in its shipped dist/ — I checked every import/require in the bundle, and it only pulls react, ink, and react/jsx-runtime. Harmless, but the bump adds a WebSocket library to our production tree for nothing. Also worth mentioning upstream.

[gemini-code-assist]

Code Review

This pull request simplifies the configuration wizard by removing the useStepperInput hook and its associated navigation-disabling logic from individual step components and tests. Instead, keyboard navigation is disabled globally on the parent <Stepper> component using keyboardNav={false}. The review feedback points out an important issue where a conflicting global <esc> key handler in ConfigurationWizard intercepts the escape key and triggers onComplete(), which breaks the back-navigation of individual steps. Removing this redundant handler is recommended to fix the bug.

[github-actions]

🎉 This PR is included in version 0.16.43 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀