TUI: adopt a consistent layout and keybinding baseline

[jimisola]

The TUI works, but it does not read as one application. Each screen invented its own header height, its own footer format, and its own key set; navigation keys were hand-rolled as literal characters instead of going through TamboUI's binding layer; and the same key means different things on different screens. This issue collects the specific defects, a baseline drawn from TamboUI's own code and from established TUIs, and an ordered plan.

Everything below was checked against the code on main/feat/lst-daemon-11 and against sources I actually fetched (listed at the end).

---

1. What's wrong today

1.1 Vim navigation is hand-coded, against the framework's own default

Every list screen re-implements j/k by testing raw characters:

• atunko-tui/src/main/java/io/github/atunkodev/tui/view/BrowserView.java:162-169 — if (event.isDown() || event.isChar('j'))
• .../view/ConfirmRunView.java:151-156
• .../view/LoadConfigView.java:87-92
• .../view/RecipeOptionsView.java:155-160
• .../view/TagBrowserView.java:130-135 and :147-152
• .../view/ExecutionResultsView.java:164-169

TamboUI's default binding set is deliberately not vim. From dev/tamboui/tui/bindings/BindingSets.java in tamboui-tui-0.4.0-sources.jar:

standard() — Arrow keys only, no vim/emacs bindings (default) […] No vim or emacs-style bindings. This is the default set, safe for use with text input (no letter keys bound to navigation).

and standard.properties in the same artifact is exactly moveUp = Up, moveDown = Down, select = Enter, Space, cancel = Escape, focusNext = Tab, focusPrevious = Shift+Tab, quit = q, Q, Ctrl+c. A separate vim.properties (moveUp = Up, k, K, …) exists precisely so that apps that want vim opt in. atunko opts in by hand, in seven places, and the owner does not want vim bindings.

event.isUp()/isDown() already delegate to the configured bindings (KeyEvent.java:388-398, return matches(Actions.MOVE_UP)), so the || event.isChar('j') half is pure added vim. Similarly BrowserView.java:229 is event.isQuit() || event.isChar('q') — isQuit() already covers q, Q and Ctrl+C.

1.2 No central binding configuration exists

AtunkoTui.java:76-79 builds the runner without .bindings(...):

try (ToolkitRunner r = ToolkitRunner.builder()
        .config(configure())
        .styleEngine(styleEngine)
        .build()) {

ToolkitRunner.Builder.bindings(Bindings) exists (ToolkitRunner.java:505 in the 0.4.0 sources) and is the intended place to declare an app-wide key map. Because atunko never uses it, there is no single list of what the app binds — the answer is spread across 65 isChar(...) calls across ten view classes.

Worth noting: .bindings() used to be silently ignored (tamboui#382). That was fixed by tamboui#383, merged 2026-06-18 20:06 UTC, and v0.4.0 was released 2026-06-18 22:09 UTC — so the version atunko already depends on (gradle/libs.versions.toml:5, tamboui = "0.4.0") has the fix. This is safe to adopt now.

(Aside: CLAUDE.md still says TamboUI 0.2.0-SNAPSHOT under "Key Dependencies". That's two minor versions stale.)

1.3 Tab and Shift-Tab are dead keys, and there is no panel focus model

Each screen marks exactly one element focusable — the root column (BrowserView.java:72, ConfirmRunView.java:71, DetailView.java:122, ExecutionResultsView.java:63,100,143, LoadConfigView.java:61, RecipeOptionsView.java:64, TagBrowserView.java:87, FileDiffView.java:68, ExportConfigView.java:56). The search input is explicitly opted out (BrowserView.java:293, .focusable(false)), as is the tag filter input (TagBrowserView.java:70).

The browser is a genuine two-pane screen — recipe list plus detail pane (BrowserView.java:52) — but there is nothing to move focus between them and nothing rendering which pane is active. focusNext/focusPrevious are bound by default to Tab/Shift-Tab and go nowhere. The one screen where Tab does something is ExportConfigView.java:69, where it toggles Minimal/Full — a meaning that exists on exactly one screen.

Neither themes/dark.tcss nor themes/light.tcss has a focus rule; the only highlight styling is the list row cursor (dark.tcss:69).

1.4 Help is not reachable from most screens

? is handled in three of ten screens: BrowserView.java:258, ConfirmRunView.java:146, DetailView.java:128. It is not handled in TagBrowserView, ExecutionResultsView, FileDiffView, LoadConfigView, RecipeOptionsView or ExportConfigView, and those screens' footers do not mention it either (FileDiffView.java:65 is the whole footer: " Esc/q:back").

1.5 The help "overlay" is not an overlay, and eats the next keystroke

BrowserView.java:48-54 and ConfirmRunView.java:39-41 replace the center content with the help panel. The recipe list disappears while you read about it, which is the opposite of what help is for.

Then BrowserView.java:108-111:

if (controller.isShowHelp()) {
    controller.toggleHelp();
    return EventResult.HANDLED;
}

Any key closes help and is swallowed. Read the help, learn that r opens the run dialog, press r — help closes and nothing else happens.

TamboUI supports real overlays: the Clear widget exists to blank an area "before rendering overlays" (widgets reference), and the filemanager demo renders its dialogs on top of the finished UI tree rather than in place of it (FileManagerView.java:63-75).

1.6 Key hints are hardcoded strings, triplicated, and already wrong

The same binding is written out in the footer, in HelpOverlay, in README.md and in docs/antora/.../cli.adoc. They have drifted:

• README.md:101 — "a | Cycle selection (none → all → none)". The code has a = select all and A = deselect all (BrowserView.java:178-185); cycleSelection() is not bound to anything in the browser.
• README.md:106 — "←/c | Collapse composite recipe". c is not bound in the browser (BrowserView.java:217 accepts only ← and <). It is bound in the run dialog (ConfirmRunView.java:183).
• BrowserView.java:369 — the browser status bar advertises o:options ?:help q:quit. Roughly a dozen other browser bindings are invisible unless the user finds ?.
• There is no TUI page in docs/antora/modules/ROOT/pages/ at all; the binding tables live inside cli.adoc:71-152.

TamboUI upstream has an open issue about exactly this duplication — tamboui#168, "Reverse bindings and display":

In many demos, we actually use hardcoded strings showing [q] Quit or [F1] Something. However, these are directly related to the Bindings in use. There should be a way to get these descriptions from the bindings rather than duplicate.

1.7 The same key means different things on different screens

• f = toggle favorite in the browser (BrowserView.java:250), = flatten composite in the run dialog (ConfirmRunView.java:187).
• F = cycle favorites filter (BrowserView.java:254), = flatten all (ConfirmRunView.java:191).
• e = expand (BrowserView.java:209) while E = expand all and W = collapse all (BrowserView.java:221-228). W has no mnemonic connection to "collapse"; it is E's neighbour on the keyboard.
• Case-sensitive pairs carry meaning throughout — a/A, f/F, n/N, E/W, S/L. Shift-as-modifier is invisible in a footer that renders a and A identically to a fast reader.
• Ctrl+↑/Ctrl+↓ reorder in the run dialog (ConfirmRunView.java:159-165) — a chord where +/- already exist for the same action.

1.8 Chrome is inconsistent screen to screen

• Header height: the browser docks a 3-line header (BrowserView.java:66, Constraint.length(3)); every other screen docks 1 (ConfirmRunView.java:65, ExecutionResultsView.java:133, TagBrowserView.java:84, …). The title bar jumps two rows on every navigation.
• Footer formatting is ad hoc: " Esc/q:back" (FileDiffView.java:65), " j/k:navigate Enter:load Esc/q:back" (LoadConfigView.java:54), " g:Gradle m:Maven Tab:Minimal/Full Esc:close" (ExportConfigView.java:51), " ↑↓/jk:navigate Enter:diff Esc/q:back" (ExecutionResultsView.java:130), "… o:options f:flatten F:flatten-all x:export ?:help Esc:back" (ConfirmRunView.java:57). Different separators, different orderings, key:action with no visual distinction between the key and its label.
• Two overlays (RecipeOptionsView, ExportConfigView) are dispatched by boolean flags checked at the top of two different render methods (BrowserView.java:41-43, ConfirmRunView.java:27-32) rather than being part of the Screen enum (Screen.java), so "what is on screen" has two competing sources of truth.

---

2. Best-practice baseline

Marked [TamboUI] where it is framework idiom and [general] where it is a cross-ecosystem TUI convention.

2.1 Layout

Convention	Source
One dock() per screen: .top(header, length(1)), .center(content), .bottom(keyHints, length(1)) — same heights on every screen	[TamboUI] filemanager demo, FileManagerView.java:63-66: dock().top(header(), Constraint.length(1)).center(browserRow(context)).bottom(helpBar(), Constraint.length(1)); jtop demo JTopDemo.java:63-71 uses the same shape
Footer is context-sensitive: it shows information about the current selection and the keys valid right now	[TamboUI] FileManagerView.java:319-336 — row(text(info).fill(), text("[Enter] Open [v] View [Backspace] Up [+] Mark All [-] Unmark").dim())
Key hints styled so key and label are visually separate (key bright/bold, label dim)	[TamboUI] jbang's TamboUI search UI, ArtifactSearchWidget.java:241-260: text(" ↑↓").yellow().bold(), text(" nav ").dim(), text("⏎").yellow().bold(), text(" select ").dim(), …
Dialogs/overlays render on top of the screen, not instead of it	[TamboUI] FileManagerView.java:69-75 renders the dialog after the main tree; Clear widget documented for exactly this
Persistent focus indication when more than one pane can take focus	[general] lazygit's multi-panel model; Textual's footer/focus model
? opens a keybindings screen, from anywhere	[general] k9s: "? — Show active keyboard mnemonics and help"; lazygit Global section: "? Open keybindings menu"

2.2 Bindings

Declare one Bindings object from BindingSets.standard() and handle events with event.matches(ACTION) — [TamboUI], and exactly what jbang (Max Andersen's own TamboUI consumer) does in ArtifactSearchWidget.java:114-124:

Bindings bindings = BindingSets.standard()
    .toBuilder()
    .unbind(Actions.FOCUS_NEXT)
    .unbind(Actions.FOCUS_PREVIOUS)
    .unbind(Actions.QUIT)
    .bind(KeyTrigger.ctrl('c'), Actions.QUIT)
    .bind(KeyTrigger.key(KeyCode.TAB), ACTION_SEARCH_CENTRAL)
    .bind(KeyTrigger.key(KeyCode.F5), ACTION_SEARCH_CENTRAL)
    .build();

ToolkitRunner.Builder builder = ToolkitRunner.builder().bindings(bindings);

Note what is absent: no j, no k, no hjkl, no chords beyond Ctrl+C. Arrows, Enter, Esc, Tab, F5.

Proposed baseline for atunko — all of it satisfies the no-vim/no-emacs constraint:

Key	Action	Scope	Rationale
↑ ↓	Move within list	global	standard.properties [TamboUI]
PgUp PgDn Home End	Page / jump	global	standard.properties; currently unbound anywhere in atunko [TamboUI]
→	Expand composite	lists	already bound; keep
←	Collapse composite	lists	already bound; keep
Tab / Shift+Tab	Move focus between panes	global	focusNext/focusPrevious [TamboUI]; makes the browser's two panes real
Enter	Primary action (open detail / load / confirm)	global	confirm [TamboUI]
Space	Toggle selection	lists	select [TamboUI]
Esc	Back / cancel — one level at a time	global	cancel [TamboUI]; today Esc in the browser clears everything (TuiController.java:779-787), which is not a cancel
? or F1	Keybindings screen	every screen	k9s, lazygit [general]
q / Ctrl+C	Quit	global	standard.properties quit [TamboUI]
/	Search / filter	browser, tag browser	k9s /, near-universal [general]
F2 … F8	Screen-level verbs: run, dry-run, options, save, load, export, tags	per screen	function keys are self-documenting in a footer and never collide with typing; the filemanager demo and jbang both use them
single letters	only as additional accelerators, never the sole way to reach an action, and never case-sensitive pairs	—	[general]

Two consequences worth calling out:

• Retire case-sensitive pairs. a/A, f/F, E/W, n/N, S/L should become distinct, spelled-out actions in the help screen with non-shifted or function-key accelerators.
• Same verb, same key, every screen. f cannot be "favorite" here and "flatten" there.

2.3 Discoverability

The strong pattern across ecosystems is that key hints are generated from the binding table, not typed twice:

• Textual: "The Footer widget can inspect bindings to display available keys"; each binding carries "a short human readable description" [general]
• Bubble Tea / bubbles help: "A customizable horizontal mini help view that automatically generates itself from your keybindings", with short and full modes; key.Binding pairs WithKeys(...) and WithHelp(...) [general]
• TamboUI has no such widget yet, and knows it — tamboui#168 [TamboUI]

So atunko should build the small version of this itself: one binding registry per screen, with a description per entry; the footer renders a subset, the ? screen renders all of it. That kills the drift in §1.6 by construction.

---

3. Proposed changes

Cheap wins (no architectural change)

1. Drop the hand-rolled vim keys. Delete every || event.isChar('j') / isChar('k') and the redundant || event.isChar('q').
   BrowserView.java:162-169,229, ConfirmRunView.java:151-156, LoadConfigView.java:87-92, RecipeOptionsView.java:155-160, TagBrowserView.java:130-135,147-152, ExecutionResultsView.java:164-169
2. Make ? work on every screen, and add ?:help to every footer.
   TagBrowserView, ExecutionResultsView, FileDiffView, LoadConfigView, RecipeOptionsView, ExportConfigView + HelpOverlay.java (needs the missing per-screen sections)
3. Stop swallowing the keystroke that closes help. Close on Esc/? only; let other keys fall through to the normal handler.
   BrowserView.java:108-111, ConfirmRunView.java:146
4. Unify the header to Constraint.length(1) so the title bar stops jumping.
   BrowserView.java:66
5. One footer helper — a single KeyHints.render(List<Entry>) producing bright-key/dim-label pairs in the jbang style, used by all ten screens.
   new .../view/KeyHints.java; call sites in all view/*.java
6. Fix the drifted docs: README.md:98-126 and docs/antora/modules/ROOT/pages/cli.adoc:71-152 (a, c, and the j/k column all wrong once (1) lands). A dedicated docs/antora/modules/ROOT/pages/tui.adoc would be the right home.
7. Update CLAUDE.md "Key Dependencies" — TamboUI is 0.4.0, not 0.2.0-SNAPSHOT.

Larger restructuring

8. Introduce an app-wide Bindings from BindingSets.standard(), wired through ToolkitRunner.builder().bindings(...), with atunko's own action constants (atunko.run, atunko.dryRun, atunko.options, atunko.flatten, …). Views switch from isChar('x') to event.matches(Actions.RUN).
   AtunkoTui.java:74-85 + new .../tui/AtunkoBindings.java + every view/*.java
9. A binding registry with descriptions, one per screen, as the single source for (a) dispatch, (b) the footer, (c) the ? screen. Replaces the hand-written HelpOverlay tables.
   HelpOverlay.java (rewritten) + AtunkoBindings.java
10. Resolve the cross-screen collisions using the table in §2.2: f/F split, E/W retired, Ctrl+↑/↓ retired in favour of +/-, function keys for screen verbs.
    BrowserView.java:178-270, ConfirmRunView.java:146-216
11. Real focus model in the browser: make the recipe list and the detail pane independently focusable, wire Tab/Shift-Tab, and add a focus style to themes/dark.tcss / themes/light.tcss.
    BrowserView.java:52,72, RecipeListRenderer.java, both .tcss files
12. Render overlays as overlays (help, recipe options, export) on top of the current screen instead of replacing the center, and fold them into Screen or an explicit overlay stack so there is one source of truth for what is displayed.
    BrowserView.java:41-54, ConfirmRunView.java:27-41, Screen.java, AtunkoTui.java:45-56
13. Bind the currently unreachable navigation: PgUp/PgDn/Home/End on every list.
    TuiController.java (new page/jump methods) + list views

Per project convention this needs an OpenSpec change proposed and approved before any of it is implemented.

---

4. Explicitly out of scope

• Vim-style bindings — no hjkl, no gg/G, no : command line, no modal normal/insert distinction. BindingSets.vim() will not be used.
• Emacs-style bindings — no Ctrl+n/Ctrl+p/Ctrl+f/Ctrl+b, no Ctrl+g. BindingSets.emacs() will not be used.
• Chorded or multi-key sequences generally. Ctrl+C for quit is the one accepted exception because it is a terminal convention, not an app binding.

The existing j/k bindings are the concrete violation and are removed by item (1).

---

5. How much real-world TamboUI usage exists — honestly

More than I expected, but the sample is still small and none of it is a published style guide.

Found and read:

• TamboUI's own demos: filemanager-demo (best layout exemplar), jtop-demo, action-handler-demo — the last shows the @OnAction annotation route
• jbang deps search (dev.jbang.search.ArtifactSearchWidget) — Max Andersen's own consumer, and the single best model for what atunko should do with bindings
• Apache Maven Pilot — a TamboUI TUI; the announcement blog confirms it exists and uses context-sensitive help on every screen (bound to h), but shows no layout code
• Apache Camel TUI — announced, TamboUI-based
• Spring Initializr TUI (Dan Vega) — a TamboUI consumer; the write-up describes keys (Enter, c, x, Tab, Esc) but no layout code

Did not find:

• Any showcase/gallery page or layout/keybinding style guide in the TamboUI docs. The docs index has bindings.html and layouts.html but no "how to structure an app screen" guidance and no key-hints or footer widget in the widget reference.
• Any Max Andersen post specifically about TUI layout or keybinding design. His announcement post covers motivation and architecture only; the Devoxx France 2026 talk "TamboUI: making 2026 the Year of Java in the Terminal" exists in the schedule but I found no recording or slides. I did not find LinkedIn/Mastodon/Bluesky posts on the topic. What I did find that is directly useful is his code (jbang) and his bug report (tamboui#382), both cited above.

So the §2 baseline is deliberately weighted: TamboUI's own demos and jbang for framework idiom, and k9s / lazygit / Textual / Bubble Tea for the general conventions that TamboUI has no opinion on yet.

---

6. Sources

TamboUI project:

• https://tamboui.dev/docs/main/
• https://tamboui.dev/docs/main/bindings.html
• https://tamboui.dev/docs/main/widgets.html
• https://github.com/tamboui/tamboui
• Reverse bindings and display tamboui/tamboui#168 — "Reverse bindings and display"
• ToolkitRunner.Builder.bindings() does not propagate to TerminalInputReader — custom bindings silently ignored tamboui/tamboui#382 + fix: propagate Builder.bindings() to TuiRunner input reader tamboui/tamboui#383 — .bindings() propagation fix, in v0.4.0
• https://github.com/orgs/tamboui/discussions/212 — "Show and tell!" (Maven, Camel, Hardwood)
• Source read locally from the Gradle cache (dev.tamboui:tamboui-tui:0.4.0, dev.tamboui:tamboui-toolkit:0.4.0 sources jars): BindingSets.java, Actions.java, KeyEvent.java, ToolkitRunner.java, standard.properties, vim.properties
• Demo sources via the GitHub API: demos/filemanager-demo/.../FileManagerView.java, tamboui-toolkit/demos/jtop-demo/.../JTopDemo.java, tamboui-toolkit/demos/action-handler-demo/...

TamboUI consumers:

• feat: replace JLine with TamboUI for dependency search TUI jbangdev/jbang#2465 and src/main/java/dev/jbang/search/ArtifactSearchWidget.java
• https://blog.gnodet.fr/posts/pilot-010-interactive-tui-for-maven/
• https://www.danvega.dev/blog/spring-initializr-tui
• https://xam.dk/blog/announcing-tamboui/
• https://m.devoxx.com/events/devoxxfr2026/talks/65346/tamboui-making-2026-the-year-of-java-in-the-terminal

General TUI prior art:

• https://textual.textualize.io/guide/input/
• https://github.com/charmbracelet/bubbles
• https://k9scli.io/topics/commands/
• https://github.com/jesseduffield/lazygit/blob/master/docs/keybindings/Keybindings_en.md

[jimisola]

Evidence base: TamboUI consumers surveyed

Follow-up to the issue body. I went looking for other TamboUI consumers to check whether the baseline in §2 reflects actual practice or just the two examples I happened to read first. It partly does not, and three specific criticisms in the issue need to be softened or reframed. Details below.

Method: GitHub code search for dev.tamboui in pom.xml (48 hits) / build.gradle* (104 hits, mostly TamboUI's own modules) / libs.versions.toml, plus repo search. I then shallow-cloned 15 candidates and grepped the source directly rather than eyeballing READMEs, and pulled stars/activity from gh api repos/... on 2026-08-10.

Comparison

Popularity caveat up front: for apache/camel, jbangdev/jbang, hardwood, aesh, jafar and venice the star count is for the host project, not for its TamboUI TUI. Those numbers say nothing about TamboUI adoption.

Repo	★	Last push	API tier	Layout	Binding approach	Vim keys	Focus model
apache/camel (camel-jbang-plugin-tui)	6282*	2026-08-10	low-level Layout/Frame	tabs + popups, Layout.vertical/horizontal ×142	hand-rolled, 143 × isChar	yes (j/k ×6)	none (0 focusable), Tab used ad hoc ×43
jbangdev/jbang (deps search)	1848*	2026-08-02	Toolkit DSL	dock().top/center/bottom	BindingSets.standard().toBuilder() + matches()	no	single element
hardwood-hq/hardwood	356*	2026-08-10	low-level	Layout.* ×8	1 × matches(), no BindingSets	no	none
danvega/spring-initializr-tui	163	2026-06-03	Toolkit DSL	column()-composed screens, no dock	hand-rolled, 13 × isChar	yes — fully modal	1 focusable
maveniverse/pilot	40	2026-08-10	low-level	Layout.vertical 1+1+fill header, fill+length(3) info bar	hand-rolled, 25 × isChar	no	Tab switches panes ×25, no focusable
Sanne/incus-spawn	34	2026-08-10	low-level	Layout.* ×19	hand-rolled, 36 × isChar	yes (j/k ×16)	none
luigidemasi/camel-kit	31	2026-07-31	(picocli only)	—	26 × matches("…")	no	none
maxandersen/zlip	3	2026-06-20	Toolkit DSL	dock().left/center + leftWidth	BindingSets ×1	no	none
lltx/ilink-tui	3	2026-04-20	Toolkit DSL	column/panel	hand-rolled	no	3 focusable
KyleKreuter/tamboui-spring	3	2026-02-23	Toolkit DSL	dock ×98 (it's a starter)	BindingSets ×1	no	2 focusable
ayagmar/quarkus-forge	2	2026-08-03	low-level	Layout.* ×11	BindingSets.vim().toBuilder() + ~30 custom actions	yes (opt-in)	none
maxandersen/jabtop	1	2026-08-10	low-level	Layout.* ×10	hand-rolled, 7 × isChar	no	none
jasondlee/ModuleGraph	0	2026-05-18	Toolkit DSL	column	BindingSets ×1	no	5 focusable
jtama/github-tui	0	2026-02-26	Toolkit DSL	3-panel column	hand-rolled	no	3 × .id().focusable() — real Tab focus
aneveux/garnish	0	2026-07-29	Toolkit DSL	component library	matches(Actions.*) ×20, BindingSets.defaults().toBuilder().unbind(...)	no	2 focusable
atunko (today)	—	—	Toolkit DSL	dock 3-line/1-line headers	hand-rolled, 65 × isChar	yes	1 focusable/screen

aeshell/aesh (162★) ships an aesh-tamboui integration module, not an application. btraceio/jafar (64★) and jlangch/venice (46★) appear in the build-file search but I did not verify a TUI in either.

Popularity verdict

TamboUI has essentially no popular independent third-party consumers yet. What it has is a small number of institutionally credible ones — Apache Camel's camel-jbang TUI plugin, jbang's deps search, and maveniverse/pilot (Maven ecosystem) — where TamboUI is one component of a project that was already popular for other reasons. Among repos that exist because they are TamboUI apps, the ceiling is danvega/spring-initializr-tui at 163★, then pilot at 40★ and incus-spawn at 34★; everything else is single-digit or zero stars. Most are two to six months old and several are demos or personal experiments.

So this is a young ecosystem where nobody has authority. Nothing below should be read as "the community has settled on X" — it hasn't.

What this changes in the issue

Four corrections, three of which weaken things I wrote.

(a) §1.7 — E/W is not arbitrary. Correction needed.
I wrote that W for collapse-all "has no mnemonic connection… it is E's neighbour on the keyboard." Maven Pilot uses the identical pair in three separate panes — ModuleTreePane.java:194-198, PomTui.java:286-290, TreeTui.java:350-355 — all if (key.isChar('E')) expandAll(...) / if (key.isChar('W')) collapseAll(...). Pilot also uses n/N for next/previous search match, s/S for sort, and f/F, which is atunko's scheme almost exactly.

The valid part of the criticism is that these are undiscoverable — not that they are wrong. Recommendation 10 should drop "retire E/W" and keep only "surface them in the footer and help".

(b) §1.7 — "retire case-sensitive pairs" overreaches. Reframe.
Shift-as-modifier (a/A, f/F, n/N) is common across the consumers I read, not an atunko quirk. The defensible requirement is that both halves appear in the help screen with distinct descriptions, not that the pattern be removed. Recommendation 10 should be reworded accordingly. The genuine defect stands and is separate: f meaning favorite on one screen and flatten on another is a collision regardless of case.

(c) §1.1 — the no-vim framing overstates consensus. Reframe, don't reverse.
I leaned on "TamboUI's default is non-vim and jbang follows it". Adopters are in fact split: 4 of 15 ship vim keys. Notably:

• danvega/spring-initializr-tui — the most-starred TUI-first consumer — is fully vim-modal: i enters insert mode, Esc leaves it (SpringInitializrTui.java:164-173), hjkl navigation, Ctrl+u/Ctrl+d paging, and its own help screen labels them "(vim)" (ui/HelpScreen.java:22-51). It also uses emacs Ctrl+P/Ctrl+N in search mode (:245,:270).
• apache/camel hand-rolls ke.isDown() || ke.isChar('j') — the same construct as atunko.
• Sanne/incus-spawn does likewise, 16 times in one 2000-line class.
• ayagmar/quarkus-forge opts in explicitly via BindingSets.vim().

The accurate statement is: TamboUI's default binding set is deliberately non-vim; adopters are split roughly 4:11; atunko's no-vim rule is a product decision by the owner, not conformance to a community norm. The recommendation does not change — item (1) still stands — but §1.1's rhetoric should be corrected so the issue doesn't claim support it doesn't have. Worth noting the split cuts the other way too: the counter-examples hand-roll vim exactly as atunko does, so the mechanism critique (bypassing the binding layer) survives intact even where the vim choice differs.

(d) §2.1 — half the "big" consumers aren't comparable. Scope note.
Camel, Pilot, hardwood, incus-spawn, quarkus-forge and jabtop are written against the low-level Layout/Frame API, not the Toolkit dock() DSL that atunko uses (Layout.vertical().constraints(...).split(area) and void render(Frame, Rect, RenderContext)). Their layout idioms don't transfer directly. atunko's actual peers on the Toolkit DSL are jbang, zlip, garnish, github-tui, ModuleGraph, ilink-tui and danvega. The §2.1 table is drawn from the right tier, but should say so.

What this strengthens

• Recommendation 11 (focus model) now has a working peer. jtama/github-tui gives each panel its own focusable list — list(repoNames).scrollbar().id("repoNames").focusable(), ×3 in UserProfileView.java:53-55 — so Tab genuinely cycles panels. jasondlee/ModuleGraph has 5 focusable elements. atunko's one-focusable-root is on the wrong side of this.
• Recommendation 12 (real overlays) is confirmed. Pilot's HelpOverlay is a scrollable panel that "slides up from the bottom of the screen… when fully open the help content fills the entire body area", composited over the body via Layout.vertical().constraints(fill(), length(helpH)).split(contentZone) (PilotShell.java:770-776). That's what atunko's should be instead of replacing the center.
  Curiosity worth flagging: atunko, Pilot and Camel each have a class named HelpOverlay, and Pilot's carries the identical record Entry(String key, String description) / record Section(String title, List<Entry> entries) shape as HelpOverlay.java:15-17. Convergent AI-assisted authoring, most likely. Pilot's version is simply further along.
• Recommendation 8 (central binding set) has good prior art. aneveux/garnish is the cleanest: matches(Actions.MOVE_UP) / MOVE_DOWN / PAGE_UP / PAGE_DOWN in FuzzyPicker.java:405-419, with BindingSets.defaults().toBuilder().unbind("focusNext").build() where Tab is needed for something else (:532-537). ayagmar/quarkus-forge's AppBindingsProfile.java declares ~30 named actions in one table — structurally exactly what recommendation 8 proposes, just built on vim() instead of standard().

Where the sample is too thin to conclude anything

• Nobody generates key hints from bindings. Not one of the 15 does it; every one hardcodes footer strings, same as atunko. quarkus-forge's central AppBindingsProfile is the closest anyone gets, and even it doesn't drive the help text. Combined with the framework gap (tamboui#168, still open), recommendation 9 has no prior art in this ecosystem — it's a reasonable design borrowed from Textual and Bubble Tea, but it should be labelled as novel work with correspondingly higher effort and risk, not as adopting a known pattern.
• Header/footer heights vary freely. jbang uses 1-line, Pilot uses two 1-line header rows and a 3-line info bar. There's no conventional height; the defensible claim is only internal consistency across atunko's own screens, which is what recommendation 4 asks for. The issue should not imply 1 line is a standard.
• ? for help is not universal — present in Camel, Pilot, danvega and quarkus-forge; absent from the rest. It's a general TUI convention (k9s, lazygit) rather than a TamboUI one, which is how §2.1 already labels it. That stands.

Net

No recommendation is withdrawn. Items 1–9 and 11–13 stand as written. Item 10 should be narrowed to the genuine f/F cross-screen collision plus discoverability, dropping the "retire E/W and case pairs" part. §1.1 and §1.7 need the reframing in (b) and (c) so the issue's claims match the evidence, and §2.1 should note the API-tier caveat from (d). Item 9 should carry a "no prior art, novel work" flag.

_{Repos cloned and grepped locally on 2026-08-10; star counts and push dates from gh api repos/<owner>/<repo> the same day.}

[jimisola]

Reference projects: verified API tiers

Repo owner asked whether Apache Camel's TUI also uses TamboUI, and flagged Maven Pilot as a good reference. Both verified directly against their build files today.

Apache Camel — yes. dsl/camel-jbang/camel-jbang-plugin-tui (pom.xml) depends on seven TamboUI artifacts: tamboui-tui, -css, -widgets, -jline3-backend, -image, -markdown, -aesh-backend.

Maven Pilot (pom.xml) manages tamboui-core, -tui, -widgets, -panama-backend, -jline3-backend at 0.4.0 — the same TamboUI version atunko is on. 40 stars, last push 2026-08-10.

The caveat that matters

Project	TamboUI artifacts	API tier
Maven Pilot	tamboui-tui + tamboui-widgets	low-level Layout/Frame
Apache Camel TUI	tamboui-tui + tamboui-widgets (+3)	low-level Layout/Frame
atunko	tamboui-toolkit (+ css, picocli, markdown)	Toolkit DSL

Confirmed by code search: Pilot and Camel reference tamboui-toolkit zero times; atunko references tamboui-widgets zero times.

So Pilot's layout code does not port to atunko. It composes Layout/Frame directly; atunko composes column(dock()...). Copying its structure would mean changing API tier, which is not what this issue is proposing.

What does port, because it is design rather than API:

• its keybinding scheme — the E/W, n/N, s/S, f/F pairs (this is the evidence that already retired the "E/W is arbitrary" criticism)
• its focus model — Tab cycling across panes, which atunko has nowhere
• its overlay help — a real slide-up scrollable overlay, not a content replacement
• its footer hint format

Recommendation: treat Pilot as the primary reference for interaction design, and jbang's deps search (ArtifactSearchWidget) as the primary reference for Toolkit DSL mechanics, since that one is on atunko's tier and uses BindingSets.standard().toBuilder(). Camel is useful as corroboration for the keybinding conventions but, like Pilot, is on the other tier.

This does not change the recommendations already in this issue; it sharpens which reference to consult for which part, and it removes the temptation to lift Pilot's layout code wholesale.

[jimisola]

Correction to the comment above

I mischaracterised tamboui-widgets, and it made the gap between atunko and Maven Pilot look bigger than it is. Correcting before anyone plans work around it.

tamboui-widgets is not a low-level API tier. Per the TamboUI docs, it is the widget implementation library — Block, Paragraph, List, Table, Chart — usable at any API level. The module split is:

Module	Role
tamboui-core	Buffer, Cell, Rect, Style, Text primitives, layout widgets
tamboui-widgets	Widget implementations (Block, Paragraph, List, Table, Chart)
tamboui-tui	High-level framework: TuiRunner, event handling, bindings, key helpers
tamboui-toolkit	Fluent declarative DSL, components, focus management

The real distinction is tamboui-tui vs tamboui-toolkit, and toolkit sits on top of tui.

More importantly: atunko already has all of it. ./gradlew :atunko-tui:dependencies --configuration runtimeClasspath resolves tamboui-tui:0.4.0 and tamboui-widgets:0.4.0 transitively through tamboui-toolkit. Verified in the jar:

dev/tamboui/tui/bindings/BindingSets.class
dev/tamboui/tui/bindings/Actions.class
dev/tamboui/tui/bindings/KeyTrigger.class

What this changes

• Recommendation 1 (adopt BindingSets.standard()) needs no new dependency. BindingSets, Actions and KeyTrigger are on the classpath today. atunko is not using an API it lacks; it is not using one it already has.
• Pilot's binding and focus code ports more directly than I said. Those live at the tamboui-tui level, which atunko has. My "does not port" claim applies only to the narrower question of how the screen is composed — Pilot builds Layout/Frame directly, atunko builds column(dock()...).
• The recommendation to use jbang's ArtifactSearchWidget for Toolkit DSL mechanics still stands, since it is the closest match to atunko's composition style.

Net effect: Pilot is a better reference than the previous comment implied, and the cheap wins are cheaper than stated. Nothing in the issue body needs to change.

[jimisola]

Structural comparison: layout, status line, navigation, tabs, preview, details

Bindings were the narrow part of this issue. Owner asked for the actual screen structure, so this compares atunko against Maven Pilot and Apache Camel's TUI by reading their source, not their READMEs. Pilot cloned at main; Camel read via raw.githubusercontent.

0. The root cause: atunko has no shared view contract

This is upstream of every other finding.

	Contract	Enforced members
Pilot	abstract class ToolPanel (873 lines), 8 subclasses	toolName(), render(), handleKeyEvent(), handleMouseEvent(), status(), keyHints(), helpSections()
Camel	interface MonitorTab	description(), render(), renderFooter(List<Span>), getHelpText(), isOverlayActive(), isDetailFocused(), navigateUp()/navigateDown()
atunko	none	—

atunko has 11 unrelated public final class views (BrowserView, DetailView, ConfirmRunView, ExecutionResultsView, TagBrowserView, RecipeOptionsView, LoadConfigView, ExportConfigView, FileDiffView, …), each a private constructor plus a static render(). Nothing obliges a view to declare its name, its key hints, or its help.

Both references make help and footer hints a required member of the view contract. That is precisely why theirs cannot drift and atunko's already has — README.md:106 documents c for collapse, which is not bound in the browser.

1. Layout — fixed frame vs per-view improvisation

Pilot, DependenciesTui.renderStandalone:

Layout.vertical().constraints(
    Constraint.length(3),                                    // header
    Constraint.fill(),                                       // content
    detailsVisible ? Constraint.percentage(25) : Constraint.length(0),  // details
    Constraint.length(3))                                    // info bar

Every ToolPanel subclass uses that same frame. atunko builds a fresh dock() per view, and the header height is length(3) in BrowserView.java:66, length(1) in every other view, and computed from metadataLineCount(...) in DetailView.java:104. The frame visibly jumps on every navigation.

2. Status line — one flat string vs a structured 3-row bar

atunko (BrowserView.java:363) builds one concatenated string and styles it uniformly:

String status = parentCount + " recipes | " + selected + " selected | src:" + source
        + " | fav:" + favorites + " | o:options  ?:help  q:quit";
return text(" " + status).addClass("status-bar");

State and key hints are interleaved in one sentence, and no key is visually distinguishable from its label.

Pilot (ToolPanel.java:319) splits the 3-row footer into blank / status / hints, and emits hints as span pairs:

Span.raw("y").bold(), Span.raw(":Save and quit  "),

Bright key, dim label. It is also context-sensitive — pendingQuitKeyHints(), diffOverlayKeyHints() and standaloneKeyHints() are swapped by state, so the footer describes the mode you are actually in. Camel does the same per tab via renderFooter(List<Span>).

3. Tabs — atunko uses the tab affordance for a sort control

BrowserView.java:297:

tabs(SortOrder.NAME.name(), SortOrder.TAGS.name(), SortOrder.RECENT.name())
        .selected(controller.sortOrder().ordinal())

Those are NAME / TAGS / RECENT — a sort order, not destinations. Meanwhile atunko has 11 screens and no tab navigation at all; you reach screens through single-letter keys and Esc.

Pilot's TabBar (TabBar.java:38) is view navigation, rendered [▸ Label], active yellow / inactive DARK_GRAY, with next() to cycle. Critically, the labels carry live counts (DependenciesTui.java:1232):

Tree: 87   Declared: 42 (3 unused)   Transitive: 118 (12 used)   Managed: 9

The tab bar doubles as the dashboard. atunko's tabs convey nothing but which sort is active — information already implied by the list order.

Camel is a third data point: one *Tab class per view, reachable by number keys.

4. Details pane — fixed sidebar vs collapsing pane with focus

• atunko: right-hand column, row(list fill(2), detail fill(1)) (BrowserView.java:52). Always present, static text, not scrollable, not focusable. Long descriptions or a composite's recipe list simply overflow.
• Pilot: bottom pane at percentage(25) that collapses to length(0) whenever an overlay is active, so the overlay gets the full frame.
• Camel: isDetailFocused() is part of the interface — detail focus is modelled state, not an accident.

atunko's detail panel cannot be focused or scrolled because no view marks more than the root column focusable — which is also why Tab/Shift-Tab do nothing anywhere.

5. Overlays and preview — replacement vs true overlay

atunko's help is not an overlay. BrowserView.java:49:

centerContent = row(spacer(), HelpOverlay.render(HelpOverlay.BROWSER_HELP), spacer())

It replaces the content, and then BrowserView.java:105 swallows the keystroke that dismisses it:

if (controller.isShowHelp()) { controller.toggleHelp(); return EventResult.HANDLED; }

So reading help and pressing r to run does nothing — you must press r twice.

Pilot models HelpOverlay and DiffOverlay as first-class objects with isActive(), drawn over the content area with their own title (" POM Changes "), while the footer swaps to that overlay's hints. Camel has a whole family of *Popup/*Overlay classes and isOverlayActive() on the interface.

Preview specifically: atunko's FileDiffView is a separate 77-line screen you navigate to. Pilot shows the same information as a DiffOverlay over the current context, so you never lose your place in the list.

Revised plan

Ordered by payoff, superseding the ordering in the issue body:

1. Introduce a view contract — abstract base or interface requiring title(), status(), keyHints(), helpSections(), render(). Everything below becomes cheap once this exists, and the docs drift stops being possible.
2. One shared frame — fixed 3-row header, fill() content, collapsible details, 3-row footer. Kills the 3→1 header jump.
3. Structured footer — bright-key/dim-label spans, context-sensitive per mode.
4. Repurpose tabs for navigation, with live counts in the labels; move sort to a status-bar indicator or a labelled control.
5. Real overlays for help and diff, and stop swallowing the dismissing keystroke.
6. Make the details pane focusable and scrollable, then Tab/Shift-Tab finally mean something.
7. Adopt BindingSets.standard() (already on the classpath — see correction above).

Items 1–3 and 5 are the ones that make it stop looking improvised.

Sources

• maveniverse/pilot — ToolPanel.java, TabBar.java, DependenciesTui.java, HelpOverlay.java, DiffOverlay.java, TableNavigation.java
• apache/camel — MonitorTab.java, AbstractTab.java, *Tab/*Popup/*Overlay

One correction to my own earlier note: Camel's AbstractTab is a helper bag, not a template — it declares no abstract methods. Camel's contract lives in the MonitorTab interface. Pilot's ToolPanel is the genuine template of the two.