Skip to content

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/Down recall the right history; n/N move matches. Commands are navigation/state only.
  • #81 Normal grammar and Leader. Roster/chat/work share j/k, gg/G, h/l, Tab, Enter, /, and Space. Chat j/k scroll the transcript; there is no message cursor. Space opens the generated which-key menu and ? opens help. ~ is retired.
  • #82 work list. Enter opens a result; d, t, r, R, x, and o delegate, reassign, retry, restart, cancel, and open native sessions; Tab and Esc move focus.
  • #83 settings. Tabs h/l, rows j/k, Enter edit/toggle, a/e/x, Space toggle, p promote memory, J/K reorder backups, s save, / filter, Esc close. 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+Enter adds a line; Esc goes Insert → composer Normal → chat; Ctrl+G leaves immediately; Ctrl+C stops 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 ​

  1. : 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 raw renderer.keyInput listener. The stale listener received : first, opened Command mode in its hidden state, and called stopPropagation, so the visible page never saw the key. A new page-activation.ts mount 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.
  2. Colon normalization hardening. normalizeKeyToken now 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.
  3. Composer focus race. focusComposer queued a microtask while the Insert hint rendered immediately, so a fast key could land before the textarea received focus. focus.ts now 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.
  4. 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 unused platform.ts helper/tests, and removed the stale ~ live probe. Archive, delete, and reset remain deliberate: roster x/X, leader Space w / Space W / Space A / Space D, and the confirmed /reset-ensemble composer command.
  5. Docs and tests. GLOSSARY.md defines the Leader as Space; README, implementation notes, scripts README, live help checks, and generated help now use Space / Space q / :q. Stale one-Esc real-live assertions were updated to the v5.6 two-step composer ladder.

Verification commands ​

CommandResult
npm run checkexit 0
npm test511 passed, 0 failed
npm run test:live:fake5 consecutive passes, including the final post-merge run
npm run test:live:fake:emptypass (pre- and post-merge)
npm run test:livepass 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.

Command (excluding the dated historical verification records):

sh
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.ts asserts the retired strings are absent from the catalog (regression guard, not a binding).
  • src/v2/tui/help.test.ts asserts Ctrl+P/Ctrl+N and ~ are absent from generated help (regression guard).
  • scripts/live-check-fake.sh uses the host native TUI footer text ctrl+p commands as 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+G behave 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 ​

  1. Stale platform docs. docs/implementation.md no 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+C stop, Ctrl+D/Ctrl+U half page, Ctrl+G leave editor, and Ctrl+R redo.
  2. Unverified macOS/Herdr claim. README.md now presents collision-free Ctrl+letter intent as design intent, explicitly unverified on a macOS/Herdr host, instead of claiming no collision.
  3. EOF whitespace. Removed the blank line at the end of src/v2/tui/vim.test.ts; git diff --check is clean.
  4. Clipboard cast. Replaced the silent as cast with src/v2/tui/opentui-clipboard.ts, a typed adapter over the clipboard exports. Verified against the installed @opentui/core 0.7.0 types and runtime (createHostClipboard, createClipboard, createRendererClipboardAdapter are all exported). The adapter keeps a capability guard: an older peer build returns null and Vim falls back to its in-memory register.
  5. Reverse focus traversal. Added Shift+Tab catalog entries for the roster, transcript, and work list, and the pure nextFocusZone helper (forward: rail → chat → work → chat; reverse mirrors it). The composer is documented as entered with i/Enter, not Tab, in help and the README.
  6. List half pages. Added Ctrl+d/Ctrl+u bindings, handlers, and hints for the roster, work list, and settings rows, backed by the pure halfPageCursor helper.
  7. Ctrl+G in wizard/prompt fields. Added insert/field-Normal catalog entries and routed them through the reducer's leave.editor intent. Wizard fields go back one step; prompt fields cancel; settings fields return to settings rows. Tests cover the typed intents.
  8. One quit path. Removed /leave. :q and Space q both call one leaveEnsemble helper; no other quit exists.
  9. Catalog/handler drift. handleHelpKey, handleCommandKey, handleComposerKey, and the wizard/prompt field handlers now resolve catalog ids through singleKeyEntry/resolveNormalKey instead of duplicating key lists. Added the missing composer Normal Enter/Ctrl+G and ://, 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.
  10. Mouse pane bound. normalizeRendererSelection refuses 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.
  11. Transcript position. Added transcriptPosition (real scroll percentage) and fed it from scrollTop/scrollHeight/viewport metrics; the bar no longer shows 100%/scrolled as a boolean label.
  12. Leader which-key delay. Space activates leader mode and actions immediately; the popup appears after LEADER_POPUP_DELAY_MS (250 ms). Pure leaderPopupVisible tests pin the timing and immediate key resolution.
  13. 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) ​

CommandResult
git diff --checkexit 0, no whitespace errors
npm run checkexit 0
npm test522 passed, 0 failed
npm run test:live:fakepass twice (runs 1 and 2)
npm run test:live:fake:emptypass
npm run test:livepass 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+G behavior 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.tsx split is deferred; catalog completeness now has tests, but the file remains large.

Released under the MIT License.