docs/internal/plugin-usability-review.md
Review of plugin usability for: Find References, Live Grep, Git Grep, Git Find File, Search Replace in Project, and Path Complete.
Testing revealed two critical infrastructure bugs affecting multiple plugins, plus several plugin-specific usability issues. The core problems are in the plugin mode keybinding system and i18n template substitution.
Affected Plugins: Find References, Search Replace
Details: Keys defined via editor.defineMode() are completely non-functional:
q, Escape (close panel)Enter/Return (activate/jump)space, a, n, r (Search Replace actions)Navigation with arrow keys works (cursor moves), but all action keys fail. Users cannot close panels or activate items using the documented keybindings.
nngroup Violation: User control and freedom - users are trapped in panels with no way to exit via keyboard.
Expected behavior: All keybindings defined in editor.defineMode() should work when the virtual buffer has focus.
editor.t()Affected Plugins: Find References, Search Replace
Details: The i18n system returns template strings without interpolating parameters:
{symbol}, {count}, {limit} instead of actual valuesnngroup Violation: Visibility of system status - users cannot see actual counts or context.
Expected behavior: editor.t("key", { param: value }) should substitute {param} with value.
Details: When pressing Up/Down to navigate results, the preview pane stays on the first result instead of updating to show the currently selected item.
nngroup Violation: Visibility of system status
Details: The file that opens on Enter is different from what's shown in the preview. For example, preview shows build.rs:714 but types/fresh.d.ts.template opens.
nngroup Violation: Consistency and standards - unpredictable behavior
Details: Files open at line 1 instead of the matched line location, defeating the purpose of the search.
nngroup Violation: Match between system and real world
Affected Plugins: Live Grep, Git Grep, Git Find File, Find References, Search Replace
Details: When navigating results with arrow keys, there's no visual indication of which item is currently selected. Users navigate blind.
nngroup Violation: Visibility of system status
Affected: Live Grep, Git Grep, Git Find File, Search Replace
Details: These frequently-used commands have no keyboard shortcuts assigned. Users must open command palette every time.
nngroup Violation: Flexibility and efficiency of use
Details: Live Grep has a preview pane; Git Grep doesn't. This inconsistency can confuse users switching between similar tools.
nngroup Violation: Consistency and standards
Details: Important error messages are cut off in the status bar (e.g., "Failed to op..."). Users cannot see full error details.
nngroup Violation: Help users recognize, diagnose, and recover from errors
Details: When no files match the search, the "Create new file" option mentioned in code isn't visible to users.
Details: Tab replaces search text instead of being ignored or completing, causing accidental input loss.
Problem: Current plugins use obscure single-letter keybindings that users must memorize:
a - select alln - select noner - replaceq - closeThese are not discoverable and conflict with potential text input.
Recommendation: Follow VSCode-style patterns using standard keys:
| Action | Recommended Key | Rationale |
|---|---|---|
| Navigate items | Up / Down | Universal, already works |
| Activate/confirm | Enter | Universal standard |
| Close/cancel | Escape | Universal standard |
| Toggle selection | Space | Common in checkbox UIs |
| Select all | Ctrl+A | Universal shortcut |
| Execute action | Ctrl+Enter | VSCode pattern for "do it" |
Current Search Replace keybindings (too many):
[SPC] toggle [a] all [n] none [r] REPLACE [RET] preview [q] close
Recommended minimal set:
[Up/Down] navigate [Space] toggle [Enter] replace selected [Esc] close
Changes:
a (select all) - use Ctrl+A or remove entirely (start with all selected)n (select none) - rarely needed, can use toggle repeatedlyr - use Enter to execute (it's the primary action)q - Escape is sufficient and standardAll result-list plugins should use the same keys:
| Key | Action |
|---|---|
Up / Down | Navigate between items |
Enter | Activate selected item (open file, execute replace, jump to reference) |
Escape | Close panel |
Space | Toggle selection (only for multi-select plugins like Search Replace) |
These are the primary interaction keys. Users expect:
This is partially implemented - arrow keys work but Enter doesn't due to the mode keybinding bug.
editor.defineMode() keybinding activation - Unblocks all panel interactionseditor.t() parameter substitution - Restores status visibilityCurrent:
["Return", "references_goto"],
["q", "references_close"],
["Escape", "references_close"],
Recommended: Keep as-is (already minimal), just remove q.
Current:
["Return", "search_replace_preview"],
["space", "search_replace_toggle_item"],
["a", "search_replace_select_all"],
["n", "search_replace_select_none"],
["r", "search_replace_execute"],
["q", "search_replace_close"],
["Escape", "search_replace_close"],
Recommended:
["Return", "search_replace_execute"], // Primary action
["space", "search_replace_toggle_item"],
["Escape", "search_replace_close"],
["Ctrl+a", "search_replace_select_all"], // Optional, use standard shortcut
These use the prompt system with suggestions - keybindings are handled by the prompt, not custom modes. Ensure:
Up / Down navigate suggestionsEnter confirms selectionEscape cancelssrc/services/plugins/ - Plugin runtime, mode registrationsrc/app/plugin_commands.rs - Command handlers for plugin APIsrc/i18n.rs or plugin i18n handling - Template substitution logicplugins/live_grep.ts:331-345 - onLiveGrepSelectionChanged handlerplugins/git_grep.ts - File opening logicplugins/find_references.ts:35-44 - Mode keybinding definitionplugins/search_replace.ts:35-48 - Mode keybinding definition