Ensemble v5.6 verification — modal interactions, composer editing, mouse copy, and statusline
Spec: #78. Tickets #79–#89 were integrated on integration/ensemble-v5.6; #89 is the cleanup and full-verification pass.
Environment: Node v26.12.1, OpenCode v2.2.5 (pinned plugin types 2.2.1), Linux/tmux, fake provider with the 60 ms chunk delay that makes the parked-message probe deterministic. The real check used the host model catalog and completed with one live model.
v5.6 behavior delivered
- #79 foundation/statusline. One pure interaction reducer owns Normal, Insert, Visual (char/line), Command, focus, overlay, command input, pending chord, selection, and transient message. Two reserved bottom rows show the mode chip, context, git state, position, pending chord, hints, and the
://input or latest message. The top header keeps workspace, paused, and busy state. - #80 command/search.
:has completion and per-kind history;/searches the transcript or filters the focused list;Up/Downrecall the right history;n/Nmove matches. Commands are navigation/state only. - #81 Normal grammar and Leader. Roster/chat/work share
j/k,gg/G,h/l,Tab,Enter,/, andSpace. Chatj/kscroll the transcript; there is no message cursor.Spaceopens the generated which-key menu and?opens help.~is retired. - #82 work list.
Enteropens a result;d,t,r,R,x, andodelegate, reassign, retry, restart, cancel, and open native sessions;TabandEscmove focus. - #83 settings. Tabs
h/l, rowsj/k,Enteredit/toggle,a/e/x,Spacetoggle,ppromote memory,J/Kreorder backups,ssave,/filter,Escclose. Text fields use Insert/Normal/Visual. - #84 wizard/dialogs. List steps use
j/k,Enter,Space,/,Esc; text steps use the shared editor grammar and the same Esc ladder. Pickers, prompts, confirms, results, and approvals share the dialog grammar. - #85 composer Vim. Enter sends and keeps Insert focus;
Shift+Enteradds a line; Esc goes Insert → composer Normal → chat;Ctrl+Gleaves immediately;Ctrl+Cstops work. Normal and Visual implement the documented Vim subset with per-Workspace and per-Direct-conversation drafts. - #86 Visual/clipboard.
v/V, motions,o,y,d/x,c,p/P, and the Esc exit. The system clipboard is primary; deletes are cuts; the internal register is the fallback; async pastes discard on focus/buffer change; successes and failures toast. - #87 mouse. The wheel scrolls the hovered pane; pane-bounded drag copies on release, clears on success, keeps on failure, and never changes mode or focus. Double-click selects a word; triple-click selects a line.
- #88 help.
?opens the complete, sectioned, searchable catalog generated from the same binding/command/mouse tables as the keymaps and statusline; a coverage test proves every source appears exactly once. - #89 cleanup. The retired interaction layer is gone, the Leader is documented as
Space, and the full matrix below is recorded.
#89 root causes and fixes
:was swallowed after an F2 native round-trip. The event shape was already{ name: ":", sequence: ":" }; normalization was not the cause. The host keeps the previous Ensemble page mounted when navigation pushes a new page, and both pages kept a rawrenderer.keyInputlistener. The stale listener received:first, opened Command mode in its hidden state, and calledstopPropagation, so the visible page never saw the key. A newpage-activation.tsmount stack lets only the newest mounted page handle raw keys and enables generated keymap layers; unmounting the top page reactivates the one beneath. Unit tests pin the stack, and the fake live harness now asserts:and/after F2.- Colon normalization hardening.
normalizeKeyTokennow maps:/colon, a:sequence, and Shift+;(including the shape a terminal may report after its keyboard protocol resets) to:. The raw Normal handler and composer Normal both use the normalized token, so:opens Command mode in every route and/still opens search. - Composer focus race.
focusComposerqueued a microtask while the Insert hint rendered immediately, so a fast key could land before the textarea received focus.focus.tsnow focuses an existing ref synchronously, keeps one queued retry for first mount (or a focus call that races the mount), and is shared by the composer, settings fields, wizard fields, prompts, and snapshot-refresh refocus. - Legacy bindings removed. Deleted the
legacy.*catalog entries (Ctrl+W,Ctrl+Shift+W,Ctrl+A,Ctrl+Shift+A,Ctrl+Shift+Delete) and their handlers, removed the dead platform keymap layer and the unusedplatform.tshelper/tests, and removed the stale~live probe. Archive, delete, and reset remain deliberate: rosterx/X, leaderSpace w/Space W/Space A/Space D, and the confirmed/reset-ensemblecomposer command. - Docs and tests.
GLOSSARY.mddefines the Leader asSpace; README, implementation notes, scripts README, live help checks, and generated help now useSpace/Space q/:q. Stale one-Esc real-live assertions were updated to the v5.6 two-step composer ladder.
Verification commands
| Command | Result |
|---|---|
npm run check | exit 0 |
npm test | 511 passed, 0 failed |
npm run test:live:fake | 5 consecutive passes, including the final post-merge run |
npm run test:live:fake:empty | pass (pre- and post-merge) |
npm run test:live | pass with a real host model (pre- and post-merge) |
The fake matrix includes the parked-message live probe (fake-queued-probe, queued marker, [x remove], exactly-once, removal), the help filter/completeness walk, settings promote/reorder, wizard Esc ladder, composer Insert/Normal/Visual, leader/which-key, :q, Space q, F2 round-trip, and the new :// after-F2 assertions.
Real-live follow-up: the first two attempts failed on the stale one-Esc-closes-composer assertion (the composer correctly stopped at composer Normal). After updating that assertion to the documented ladder, the run passed; this was a test expectation, not a product regression.
Static retired-key search
Command (excluding the dated historical verification records):
grep -rn -E '(~q|`~`|~ \?|Ctrl\+S|Ctrl\+N|Ctrl\+P|Ctrl\+W|Ctrl\+A|Ctrl\+Shift|ctrl\+s|ctrl\+n|ctrl\+p|ctrl\+w|ctrl\+a|ctrl\+shift)' \
README.md GLOSSARY.md docs/implementation.md docs/assessments/opentui.md \
scripts src/v2/tui --include='*.md' --include='*.sh' --include='*.ts' --include='*.tsx'Remaining intentional exceptions:
src/v2/tui/keymap.test.tsasserts the retired strings are absent from the catalog (regression guard, not a binding).src/v2/tui/help.test.tsassertsCtrl+P/Ctrl+Nand~are absent from generated help (regression guard).scripts/live-check-fake.shuses the host native TUI footer textctrl+p commandsas a marker that the native session opened; it is host-owned, not an Ensemble app action.~remains only as the home-directory notation in paths, docs, and the OpenTUI assessment's note about literal typed characters.- Dated verification records under
docs/verification/are historical and intentionally unchanged.
No catalog entry binds ~, ctrl+s, ctrl+up, ctrl+down, ctrl+n, ctrl+p, ctrl+w, ctrl+a, or any ctrl+shift app shortcut. Documented editor exceptions remain: Ctrl+C stop, Ctrl+D/Ctrl+U half-page, Ctrl+G leave editor, Ctrl+R redo.
Remaining limits
- macOS/Herdr manual check was not performed. This environment is Linux/tmux; there is no macOS host or Herdr session. The user should run the page on macOS with Herdr and confirm there is no clash with host shortcuts and that
Esc/Ctrl+Gbehave as documented while a native run streams. - The host keeps old plugin pages mounted; the page-activation guard protects key ownership, but the host owns whether those old pages are ultimately disposed. Their polling continues until the host removes them.
- Real mouse drag behavior remains a manual check because tmux mouse injection is not reliable; the reducer/clipboard seam is unit-covered.
- Windows-specific terminal behavior was out of scope in the spec.
Post-integration review-fix pass (same date)
Baseline: integration/ensemble-v5.6 at acbe168. Branch: fix/v56-review. This pass addressed the review findings without starting new features, editing/closing issues, or merging into the integration branch.
Findings and fixes
- Stale platform docs.
docs/implementation.mdno longer claims every Ctrl shortcut becomes Cmd on macOS or that labels follow the platform. It now records that the v5.6 platform keymap layer is gone and lists the only Ctrl app chords:Ctrl+Cstop,Ctrl+D/Ctrl+Uhalf page,Ctrl+Gleave editor, andCtrl+Rredo. - Unverified macOS/Herdr claim.
README.mdnow presents collision-freeCtrl+letterintent as design intent, explicitly unverified on a macOS/Herdr host, instead of claiming no collision. - EOF whitespace. Removed the blank line at the end of
src/v2/tui/vim.test.ts;git diff --checkis clean. - Clipboard cast. Replaced the silent
ascast withsrc/v2/tui/opentui-clipboard.ts, a typed adapter over the clipboard exports. Verified against the installed@opentui/core0.7.0 types and runtime (createHostClipboard,createClipboard,createRendererClipboardAdapterare all exported). The adapter keeps a capability guard: an older peer build returns null and Vim falls back to its in-memory register. - Reverse focus traversal. Added
Shift+Tabcatalog entries for the roster, transcript, and work list, and the purenextFocusZonehelper (forward: rail → chat → work → chat; reverse mirrors it). The composer is documented as entered withi/Enter, not Tab, in help and the README. - List half pages. Added
Ctrl+d/Ctrl+ubindings, handlers, and hints for the roster, work list, and settings rows, backed by the purehalfPageCursorhelper. - Ctrl+G in wizard/prompt fields. Added insert/field-Normal catalog entries and routed them through the reducer's
leave.editorintent. Wizard fields go back one step; prompt fields cancel; settings fields return to settings rows. Tests cover the typed intents. - One quit path. Removed
/leave.:qandSpace qboth call oneleaveEnsemblehelper; no other quit exists. - Catalog/handler drift.
handleHelpKey,handleCommandKey,handleComposerKey, and the wizard/prompt field handlers now resolve catalog ids throughsingleKeyEntry/resolveNormalKeyinstead of duplicating key lists. Added the missing composer NormalEnter/Ctrl+Gand://, full wizard/prompt/settings Vim tables generated from one shared spec, help page keys, and leader hints. Statusline hints, the in-chat composer line,footerLine1, and the settings field line are all catalog-generated. Tests now assert required handler bindings independently of the help catalog, plus help coverage of the special-case entries. - Mouse pane bound.
normalizeRendererSelectionrefuses a selection when the drag's start pane is unknown, instead of copying every selected renderable. The test that blessed the cross-pane fallback now asserts the selection is ignored. - Transcript position. Added
transcriptPosition(real scroll percentage) and fed it fromscrollTop/scrollHeight/viewport metrics; the bar no longer shows100%/scrolledas a boolean label. - Leader which-key delay.
Spaceactivates leader mode and actions immediately; the popup appears afterLEADER_POPUP_DELAY_MS(250 ms). PureleaderPopupVisibletests pin the timing and immediate key resolution. - macOS/Herdr. Not performed in this Linux/tmux environment. This record does not claim it passed; the manual check remains a user task.
Small cleanups completed: one keyChordLabel formatter (removed keyLabel), removed unused ParsedCommand.args, inlined the dialogFilterEdit wrapper, consolidated the duplicated contextLabel maps, and aliased InteractionSelection to the Vim Visual range type. The 4,000-line app.tsx split remains a follow-up and was not attempted.
Verification results (pre-merge, branch fix/v56-review)
| Command | Result |
|---|---|
git diff --check | exit 0, no whitespace errors |
npm run check | exit 0 |
npm test | 522 passed, 0 failed |
npm run test:live:fake | pass twice (runs 1 and 2) |
npm run test:live:fake:empty | pass |
npm run test:live | pass with the real host model catalog |
Post-merge rerun: git merge integration/ensemble-v5.6 was already up to date, then npm run check exited 0, npm test passed 522/522, npm run test:live:fake passed, npm run test:live:fake:empty passed, and npm run test:live passed again.
Remaining limits
- macOS/Herdr manual check is still unperformed. No macOS host or Herdr session is available here; collision-free intent and the
Esc/Ctrl+Gbehavior under a live native run remain unverified there. - Real mouse drag remains manual. tmux does not reliably inject drag gestures; the pane-bounded normalization/copy policy is unit-covered, but actual renderer drag behavior still needs a desktop terminal check.
- The host still owns disposal of old plugin pages; the page-activation guard prevents stale key ownership but cannot force disposal.
- The
app.tsxsplit is deferred; catalog completeness now has tests, but the file remains large.