docs: interaction review — model, decisions and work order - #63
Conversation
Records the 2026-09-04 review of teletui's interaction model, keymaps and interactive surfaces. Two documents: - docs/interaction-model.md: the rules the keyboard follows, the keymap by surface after the changes, the fourth badge, the hint sets, the reduced [keys] config, and fifteen numbered decisions (I-1..I-15) with reasons. - INTERACTION-REVIEW.md: fifteen tasks in four waves with files and acceptance, sequenced so parallel agents do not collide on app.go. Headlines: Esc never discards typed text; Alt and function keys are dropped for plain spellings (c, J/K, u, [/]); l/Enter/i in the chat list act on the cursored chat; j/k step messages and ctrl+e/y scroll lines; :quit confirms like q; the delete dialog names for whom; q closes no overlay; m marks read; one hint table keyed by surface replaces the mode-keyed bar and the unrendered helpLine; [keys] becomes one semantic. No code changes. README, TODO and KEYMAP-REVIEW gain pointers. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XpLowBC3Gf6EiRERJ3q2Cn
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 499c74c484
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | Attach picker | `enter attach · tab complete · esc cancel` | | ||
| | Contacts | `j/k move · enter open · esc close` | | ||
| | Search | `enter search · tab scope · esc close` | | ||
| | Dialog | `y/n answer · ←/→ choose · enter accept · esc cancel` | |
There was a problem hiding this comment.
For the three-button delete dialog specified in INTERACTION-REVIEW.md, the valid accelerators are n/m/e, so this single static dialog hint advertises y—which is inert there—and omits both delete actions. Since task 12 defines only one SurfaceDialog, opening a delete confirmation would immediately violate the new requirement that every hint describe the live surface; pass the active dialog's buttons into hint generation or distinguish confirm and choice dialogs.
Useful? React with 👍 / 👎.
| - Split `Reset` into *clear context* (mode, reply target, edit target, | ||
| attachment, notice) and *clear text*. The `Esc` cancel rung calls only | ||
| the first. `submit` still calls both. | ||
| - `EnterEditMode` parks the current draft (text and reply target) before | ||
| loading the message text; cancelling the edit or sending it restores the | ||
| parked draft. Reuse the per-chat `drafts` map's `draft` type rather than | ||
| adding a second one. | ||
| - Unstaging an attachment on `Esc` stays as it is. |
There was a problem hiding this comment.
When a reply/edit also has an attachment, the proposed clear context operation clears both the target and attachment on one Esc. That contradicts the newly authoritative one-step ladder, where cancelling a reply/edit target and unstaging an attachment are separate steps, and unexpectedly forces the user to reattach the file. Split those operations and add acceptance coverage for a reply/edit with an attachment pending.
Useful? React with 👍 / 👎.
| - Every field is *replace*. A collision — with another field or with a | ||
| fixed key the panels own — is refused, the default is kept, and the | ||
| warning is printed **at startup**, not only under `-migrate-config`. |
There was a problem hiding this comment.
For a normal launch with a colliding binding, the prescribed files do not add any path that can print this warning: the repository's only call to config.DetectKeyCollisions is inside runMigrateConfig in cmd/teletui/main.go, which runs only under -migrate-config. Refusing the value during resolution therefore still leaves ordinary users unaware unless this task also updates the normal startup entry point (or defines another explicit user-visible warning channel).
Useful? React with 👍 / 👎.
2 participants
Summary
Records the 2026-09-04 review of
teletui's interaction model, keymaps and interactive surfaces. Documentation only; no code changes.docs/interaction-model.md— the durable document: six rules the keyboard follows, the full keymap by surface after the planned changes, a four-label mode badge, the hint set per surface, the reduced[keys]config, and fifteen numbered decisions (I-1..I-15) with their reasons. Declares itself the authority over the keymap prose inkeymap.goand the mode sections of the TUI 2.0 record.INTERACTION-REVIEW.md— the work order, in theKEYMAP-REVIEW.mdshape: fifteen tasks in four waves with files and acceptance criteria, sequenced so parallel agents do not collide onapp.go.Headlines of the decisions
Escnever discards typed text; cancelling an edit restores the draft it displaced.ccontacts,J/Knext/prev chat,unext unread,[/]folders from both browsing panels.l,Enterandiin the chat list act on the cursored chat, not the last-opened one.j/kstep messages in the chat view;ctrl+e/ctrl+yscroll lines;}/{retire.:quitconfirms likeq;ctrl+qstays the unconditional exit.y/n.qcloses no overlay;Escdoes.mmarks read.helpLine; a drift test covers every surface including the chat list footer.[keys]becomes one semantic: replace, refuse collisions, warn at startup; nine fields removed and reported by-migrate-config.Test plan
go test ./internal/app/ ./internal/config/passes (doc-drift tests unaffected, since no key changed)🤖 Generated with Claude Code
https://claude.ai/code/session_01XpLowBC3Gf6EiRERJ3q2Cn
Generated by Claude Code