vimamsa 0.1.26 → 0.1.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (170) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/appimage.yml +93 -0
  3. data/.gitignore +4 -1
  4. data/Dockerfile +7 -4
  5. data/README.md +62 -16
  6. data/custom_example.rb +43 -13
  7. data/doc/TODO.md +461 -0
  8. data/doc/bundling_plan.md +569 -0
  9. data/doc/key_bindings_report_plan.md +168 -0
  10. data/doc/missing_vim_bindings.md +71 -0
  11. data/doc/modules_settings_plan.md +433 -0
  12. data/doc/refactor_dedup_plan.md +117 -0
  13. data/doc/unused_code_plan.md +120 -0
  14. data/doc/vim_compatibility_plan.md +296 -0
  15. data/doc/vimlike_vim_conflicts.md +254 -0
  16. data/doc/vm_snapshots_plan.md +146 -0
  17. data/exe/run_tests.rb +117 -3
  18. data/exe/vimamsa +24 -4
  19. data/fonts/OFL-Oxanium.txt +93 -0
  20. data/fonts/Oxanium[wght].ttf +0 -0
  21. data/icon.png +0 -0
  22. data/img/demo.gif +0 -0
  23. data/lang/hyperplaintext.lang +6 -0
  24. data/lib/vimamsa/ack.rb +11 -1
  25. data/lib/vimamsa/actions.rb +4 -1
  26. data/lib/vimamsa/appimage_env.rb +35 -0
  27. data/lib/vimamsa/audio.rb +2 -5
  28. data/lib/vimamsa/bookmarks.rb +302 -0
  29. data/lib/vimamsa/buffer.rb +593 -82
  30. data/lib/vimamsa/buffer_changetext.rb +102 -42
  31. data/lib/vimamsa/buffer_cursor.rb +7 -0
  32. data/lib/vimamsa/buffer_list.rb +4 -0
  33. data/lib/vimamsa/buffer_manager.rb +4 -1
  34. data/lib/vimamsa/bundled_fonts.rb +32 -0
  35. data/lib/vimamsa/clipboard.rb +3 -0
  36. data/lib/vimamsa/conf.rb +59 -3
  37. data/lib/vimamsa/constants.rb +3 -0
  38. data/lib/vimamsa/crash_handler.rb +149 -0
  39. data/lib/vimamsa/debug.rb +4 -1
  40. data/lib/vimamsa/desktop_install.rb +96 -0
  41. data/lib/vimamsa/diff_buffer.rb +39 -10
  42. data/lib/vimamsa/easy_jump.rb +3 -0
  43. data/lib/vimamsa/editor.rb +263 -57
  44. data/lib/vimamsa/encrypt.rb +78 -29
  45. data/lib/vimamsa/file_finder.rb +4 -19
  46. data/lib/vimamsa/file_history.rb +3 -0
  47. data/lib/vimamsa/file_manager.rb +30 -15
  48. data/lib/vimamsa/fold.rb +226 -0
  49. data/lib/vimamsa/gui.rb +520 -106
  50. data/lib/vimamsa/gui_command_line.rb +208 -0
  51. data/lib/vimamsa/gui_dialog.rb +94 -42
  52. data/lib/vimamsa/gui_file_panel.rb +356 -25
  53. data/lib/vimamsa/gui_form_generator.rb +59 -35
  54. data/lib/vimamsa/gui_func_panel.rb +67 -22
  55. data/lib/vimamsa/gui_image.rb +3 -0
  56. data/lib/vimamsa/gui_keylog_panel.rb +246 -0
  57. data/lib/vimamsa/gui_menu.rb +23 -11
  58. data/lib/vimamsa/gui_select_window.rb +19 -48
  59. data/lib/vimamsa/gui_settings.rb +78 -37
  60. data/lib/vimamsa/gui_sourceview.rb +273 -19
  61. data/lib/vimamsa/gui_sourceview_autocomplete.rb +319 -90
  62. data/lib/vimamsa/gui_text.rb +63 -2
  63. data/lib/vimamsa/gui_theme.rb +606 -0
  64. data/lib/vimamsa/hook.rb +3 -0
  65. data/lib/vimamsa/hyper_plain_text.rb +3 -0
  66. data/lib/vimamsa/key_actions.rb +112 -13
  67. data/lib/vimamsa/key_binding_tree.rb +242 -215
  68. data/lib/vimamsa/key_bindings_notepad.rb +43 -0
  69. data/lib/vimamsa/key_bindings_report.rb +261 -0
  70. data/lib/vimamsa/key_bindings_vim.rb +354 -0
  71. data/lib/vimamsa/key_bindings_vimlike.rb +65 -9
  72. data/lib/vimamsa/langservp.rb +271 -54
  73. data/lib/vimamsa/macro.rb +3 -0
  74. data/lib/vimamsa/main.rb +14 -8
  75. data/lib/vimamsa/rbvma.rb +26 -1
  76. data/lib/vimamsa/search.rb +3 -0
  77. data/lib/vimamsa/search_replace.rb +11 -10
  78. data/lib/vimamsa/string_util.rb +120 -40
  79. data/lib/vimamsa/terminal.rb +3 -0
  80. data/lib/vimamsa/test_framework.rb +28 -2
  81. data/lib/vimamsa/tests.rb +3 -0
  82. data/lib/vimamsa/text_objects.rb +353 -0
  83. data/lib/vimamsa/text_transforms.rb +14 -0
  84. data/lib/vimamsa/util.rb +46 -7
  85. data/lib/vimamsa/version.rb +1 -1
  86. data/lib/vimamsa.rb +0 -1
  87. data/modules/color_highlight/color_highlight.rb +118 -0
  88. data/modules/color_highlight/color_highlight_info.rb +3 -0
  89. data/modules/dictation/dictation.rb +1054 -0
  90. data/modules/dictation/dictation_info.rb +3 -0
  91. data/modules/dictation/whisper_worker.py +273 -0
  92. data/modules/ollama/ollama.rb +107 -0
  93. data/modules/ollama/ollama_info.rb +3 -0
  94. data/modules/tts/tts.rb +119 -0
  95. data/modules/tts/tts_info.rb +3 -0
  96. data/run_e2e_vm.sh +28 -0
  97. data/run_tests_vm.sh +130 -0
  98. data/scripts/appimage/AppRun +54 -0
  99. data/scripts/appimage/Dockerfile +18 -0
  100. data/scripts/appimage/build.sh +19 -0
  101. data/scripts/appimage/build_in_container.sh +192 -0
  102. data/scripts/appimage/smoke_test.sh +27 -0
  103. data/scripts/demo/demo_steps.txt +59 -0
  104. data/scripts/demo/record_demo.rb +177 -0
  105. data/scripts/demo/shapes.rb +28 -0
  106. data/styles/134272-molokai.xml +3 -0
  107. data/styles/molokai_cyber.xml +48 -0
  108. data/styles/molokai_edit.xml +1 -0
  109. data/tests/support/virtual_keyboard.rb +254 -0
  110. data/tests/support/virtual_mic.rb +67 -0
  111. data/tests/test_ack.rb +22 -0
  112. data/tests/test_auto_format.rb +122 -0
  113. data/tests/test_autocomplete.rb +211 -0
  114. data/tests/test_autosave.rb +145 -0
  115. data/tests/test_basic_editing.rb +33 -3
  116. data/tests/test_bookmarks.rb +206 -0
  117. data/tests/test_bracket_match.rb +85 -0
  118. data/tests/test_bundling.rb +92 -0
  119. data/tests/test_color_highlight.rb +92 -0
  120. data/tests/test_command_line.rb +79 -0
  121. data/tests/test_command_line_file.rb +27 -0
  122. data/tests/test_context_menu_file.rb +129 -0
  123. data/tests/test_copy_paste.rb +80 -0
  124. data/tests/test_crash_handler.rb +39 -0
  125. data/tests/test_custom_two_phase.rb +92 -0
  126. data/tests/test_dialog_callback_errors.rb +44 -0
  127. data/tests/test_dictation.rb +294 -0
  128. data/tests/test_diff_buffer_name.rb +51 -0
  129. data/tests/test_double_click.rb +41 -0
  130. data/tests/test_drag_selection.rb +125 -0
  131. data/tests/test_e2e_cmdline.rb +116 -0
  132. data/tests/test_e2e_dictation.rb +98 -0
  133. data/tests/test_e2e_replace_char.rb +58 -0
  134. data/tests/test_extract_file_links.rb +55 -0
  135. data/tests/test_file_format.rb +217 -0
  136. data/tests/test_file_manager.rb +72 -0
  137. data/tests/test_file_panel.rb +269 -0
  138. data/tests/test_flash.rb +78 -0
  139. data/tests/test_fold.rb +111 -0
  140. data/tests/test_font_refresh.rb +56 -0
  141. data/tests/test_func_panel.rb +68 -0
  142. data/tests/test_grep_apply.rb +46 -0
  143. data/tests/test_gtk_sync.rb +126 -0
  144. data/tests/test_hpt_highlight_visible.rb +75 -0
  145. data/tests/test_hpt_link_highlight.rb +82 -0
  146. data/tests/test_jump_to_file.rb +41 -0
  147. data/tests/test_key_bindings.rb +208 -0
  148. data/tests/test_keylog_panel.rb +101 -0
  149. data/tests/test_lsp_clangd.rb +281 -0
  150. data/tests/test_lsp_jump.rb +87 -0
  151. data/tests/test_lsp_position_encoding.rb +49 -0
  152. data/tests/test_lsp_symbols.rb +68 -0
  153. data/tests/test_macro.rb +137 -0
  154. data/tests/test_markdown_highlight.rb +57 -0
  155. data/tests/test_mode_badge.rb +41 -0
  156. data/tests/test_notepad_bindings.rb +67 -0
  157. data/tests/test_popup_queue.rb +51 -0
  158. data/tests/test_random_edit.rb +109 -0
  159. data/tests/test_revert.rb +127 -0
  160. data/tests/test_startup_file.rb +58 -0
  161. data/tests/test_status_area.rb +50 -0
  162. data/tests/test_text_objects.rb +163 -0
  163. data/tests/test_text_transforms.rb +329 -0
  164. data/tests/test_tts.rb +68 -0
  165. data/tests/test_vim_bindings.rb +252 -0
  166. data/tests/test_vim_conflicts.rb +63 -0
  167. data/tests/test_window_layout.rb +219 -0
  168. data/vimamsa.gemspec +3 -1
  169. data/vm_guest_run.sh +109 -0
  170. metadata +112 -10
data/doc/TODO.md ADDED
@@ -0,0 +1,461 @@
1
+ # TODO
2
+
3
+ Generic list of future actions. Larger efforts get their own plan in `doc/*_plan.md`
4
+ and are linked from here.
5
+
6
+ When an item is finished, move it to **DONE**. Add a short summary of what was done and
7
+ the git ref(s), as a short commit hash or a range.
8
+
9
+ ## Open
10
+
11
+ ### Stop writing to `~/.vimamsa`; use XDG dirs (`~/.config` / `~/.local/share`)
12
+
13
+ Nothing should be written to `~/.vimamsa` or other ad-hoc dot dirs. User-edited
14
+ configuration goes in `~/.config/vimamsa` (`$XDG_CONFIG_HOME`). Files the program
15
+ generates (history, session, backups, caches, downloaded models/venvs) go in
16
+ `~/.local/share/vimamsa` (`$XDG_DATA_HOME`).
17
+
18
+ Hardcoded paths found (2026-11-18). They also bypass `vma_user_dir` / `--user-dir`, so
19
+ the test suite (`~/.config/vimamsa-test`) can still touch the real user's files:
20
+ - `lib/vimamsa/gui_command_line.rb:20`: `HISTORY_FILE = "~/.vimamsa/cmd_history.txt"`.
21
+ Change to data dir.
22
+ - `lib/vimamsa/buffer.rb:2221`: backups in `~/.vimamsa/backup`. Change to data dir.
23
+ `editor.rb:189` already creates `get_dot_path("backup")`, which is a different
24
+ directory from the one backups are written to.
25
+ - `lib/vimamsa/macro.rb:219`: `save_macro` writes to `~/.config/.vimamsa`, a stray
26
+ third directory. Unify it with `NAMED_MACROS_FILE` (`macro.rb:46`). Saved macros are
27
+ user content, so they go in the config dir.
28
+
29
+ Currently everything else goes through `get_dot_path` → `~/.config/vimamsa`, including
30
+ generated state. It should be split as follows:
31
+ - Stays in config: `custom.rb`, `settings.rb`, `styles/`, bookmarks, named macros.
32
+ - Moves to data: `session.txt`, `buffers.txt` (`buffer_list.rb:5,14`), `backup/`,
33
+ `crash/`, `cmd_history.txt`, `dictation_prompts.json`. Also the `listen/` dir and
34
+ `ripl_ctrl` (`gui.rb:535`). Those two are runtime files, so `$XDG_RUNTIME_DIR` could
35
+ be an option, but `~/.local/share` is fine for now. `exe/vimamsa` uses `listen/`
36
+ too, and it must agree with the editor.
37
+
38
+ Plan sketch:
39
+ 1. Add `vma_data_dir` / `get_data_path(sfx)` beside `vma_user_dir` / `get_dot_path`
40
+ (`editor.rb:742-755`). They honor `$XDG_DATA_HOME`, and `--user-dir` overrides both
41
+ dirs, so tests stay isolated. Also honor `$XDG_CONFIG_HOME` in `vma_user_dir`.
42
+ 2. Route the three hardcoded paths and the data files above through these helpers.
43
+ 3. One-time migration at startup: if the old file exists and the new one doesn't, move
44
+ it (`~/.vimamsa/{cmd_history.txt,backup/}`, `~/.config/.vimamsa/macro_*`, and data
45
+ files from `~/.config/vimamsa`). Log what was moved.
46
+ 4. Fix docs that say `~/.vimamsa/...`:
47
+ - `README.md:62,158` (custom.rb is actually in `~/.config/vimamsa`)
48
+ - `modules/tts/tts.rb:14` and `modules/dictation/dictation.rb:24` ("settings.rb")
49
+ - `custom_example.rb`, if it applies
50
+ 5. Tests: with `$vma_user_dir` set, no file outside the test dirs is created. Run a test
51
+ that exercises history, backup and macro save, and check that `~/.vimamsa` is not
52
+ created.
53
+ 6. `doc/modules_settings_plan.md` already uses `~/.local/share/vimamsa/venv` for its
54
+ shared Python venv. Build it on `get_data_path("venv")`.
55
+
56
+ ### Descriptive names for key bindings that lack one
57
+
58
+ Many bindings show raw Ruby code instead of a description in Help ▸ Show key bindings
59
+ (`show_key_bindings`, `key_bindings_report.rb`) and in other places that show action
60
+ names. Example:
61
+
62
+ [C] d F space : buf.delete2(:to_char_backward,' ')
63
+
64
+ It should say something like `Delete backward to previous space`.
65
+
66
+ Cause: `KeyBindingTree#get_by_keywords` (`key_binding_tree.rb:404-417`) only looks up a
67
+ description when the action is a registered **Symbol** (`@actions[sym].method_name`).
68
+ Bindings whose action is an eval'd **String** are printed as they are. Counts
69
+ (2026-11-19), as `"keys" => "ruby string"` entries:
70
+
71
+ | Scheme | String bindings | Symbol bindings |
72
+ |---|---|---|
73
+ | `key_bindings_vimlike.rb` | 97 | 145 |
74
+ | `key_bindings_vim.rb` | 78 | 79 |
75
+ | `key_bindings_notepad.rb` | 4 | 9 |
76
+
77
+ Some registered symbols also have an empty description, e.g. `:jump_to_random`
78
+ (`key_actions.rb:67`) and `:ack_search` (`key_actions.rb:124`, a duplicate of line 151,
79
+ which does have one). These print as the bare symbol.
80
+
81
+ Other places that show the raw action and would benefit from the same lookup:
82
+ - the previous-action label in the toolbar (`gui.rb:829`)
83
+ - the key log panel (`gui_keylog_panel.rb:109`)
84
+
85
+ Plan sketch:
86
+ 1. **One description table keyed by the action string**, shared by all schemes. Many
87
+ strings are identical in vim and vimlike, e.g. `buf.delete2(:to_char_backward,' ')`
88
+ is in both, so each one is described once. For example, a new
89
+ `lib/vimamsa/key_action_descs.rb` (required in `rbvma.rb`):
90
+ ```ruby
91
+ KEY_ACTION_DESCS = {
92
+ "buf.move(FORWARD_CHAR)" => "Move forward one character",
93
+ "buf.delete2(:to_char_backward,' ')" => "Delete backward to previous space",
94
+ "buf.delete2(:to_char_backward,<char>)" => "Delete backward to previous <char>",
95
+ "bufs.close_current_buffer" => "Close current buffer",
96
+ ...
97
+ }
98
+ ```
99
+ Templates with `<char>` keep the placeholder in the description.
100
+ - Alternative: convert each string action to a `reg_act` symbol with a description.
101
+ That's cleaner in the long run (they also become searchable in Search for
102
+ Actions), but it touches every binding line in three scheme files, plus user
103
+ `custom.rb` files that rebind the same strings. Proposed: the table first.
104
+ Convert to symbols opportunistically, and especially convert actions that are
105
+ worth finding through Search for Actions.
106
+ 2. A helper `action_description(action)`: Symbol → `method_name` (if non-empty);
107
+ String → `KEY_ACTION_DESCS[action]`; otherwise the action itself. Use it in
108
+ `get_by_keywords`, `gui.rb:829` and the key log panel.
109
+ 3. Report format: show the description, with the raw code dimmed after it so power
110
+ users still see what runs. For example:
111
+ `[C] d F space : Delete backward to previous space ⟨buf.delete2(:to_char_backward,' ')⟩`.
112
+ Or show the code only for entries without a description.
113
+ 4. Fill in descriptions for all ~180 string bindings and the symbols with empty
114
+ descriptions. Remove the duplicate `:ack_search` registration.
115
+ 5. Test (`tests/test_key_bindings.rb` or a new one): for each scheme (load it with
116
+ `load_scheme_kbd`), every binding resolves to a non-empty description that isn't
117
+ the raw action. Print the missing ones, so new bindings without a description fail
118
+ the suite.
119
+
120
+ ### More Vim bindings: counts after operators, missing operator + motion combinations
121
+
122
+ The full design is step 1 of `doc/vim_compatibility_plan.md` (a generic operator +
123
+ motion layer). The gap list is in `doc/missing_vim_bindings.md`. This item tracks the
124
+ concrete bindings, ordered by usefulness and cost.
125
+
126
+ State (2026-11-19):
127
+ - A count *before* the command (`3dw`) works, because the key tree repeats the action
128
+ (`key_binding_tree.rb:888`).
129
+ - A count *after* the operator works only where a `<num>` binding was written out.
130
+ The only one is `"C d <num> e"` (`key_bindings_vimlike.rb:229`, handled by
131
+ `KeyBindingTree#match_num_key`).
132
+
133
+ 1. **Counts after the operator for bindings that already exist** (quick win, can come
134
+ before the operator layer):
135
+ - `d <num> w`, `d <num> d` (= `3dd`), `d <num> f x`, `d <num> F x`
136
+ - `y <num> w`, `y <num> e`, `y <num> y`
137
+ - `g U <num> w`, `g u <num> w`, `g ~ <num> w`
138
+ - vim scheme: `c <num> w`, `c <num> e`, `c <num> c`
139
+ - text objects: `d 2 i (` (today only `2 d i (` works)
140
+
141
+ Rather than writing every `<num>` binding by hand, let `match_num_key` accept digits
142
+ after any registered operator prefix (`C d`, `C y`, `C c`, `C g U`, `C g u`,
143
+ `C g ~`), so current and future operator bindings all get counts. Caveat: `c …`
144
+ must not just repeat its action (three insert-mode entries), so the change bindings
145
+ need actions that apply the count themselves (`method_handles_repeat`). Check
146
+ `delete_line` / `copy_cur_line` the same way.
147
+ 2. **Missing operator + motion combinations** (both schemes unless noted):
148
+ - `d b`, `c b`, `y b`
149
+ - `d t x`, `c t x`, `d T x`, `y t x`
150
+ - `d j`, `d k`: missing in both; in vimlike they're commented-out TODOs at
151
+ `key_bindings_vimlike.rb:222-223`
152
+ - `d G`, `d g g`; `d }`, `d {`, `y }`; `d %`; `d ^`, `y ^`
153
+ - vimlike has no change operator at all (`c`, `C`, `s`, `S` are bound to other
154
+ things), so it needs a key decision first. See `doc/vimlike_vim_conflicts.md`.
155
+ 3. **Missing motions** (they then also work after operators):
156
+ - `W` / `E` / `ge` (`B` is commented out in vimlike)
157
+ - `T x`, and `,` (`;` exists)
158
+ - `%`, `{` / `}`, `(` / `)`
159
+ - `H` / `L` (`M` is taken in vimlike), `#`
160
+ 4. **Doubled operators / other count commands**:
161
+ - `>>` / `<<` with counts, and Visual `>` / `<` in vimlike
162
+ - `ctrl-a` / `ctrl-x` (neither is in vimlike)
163
+ - check that `3 r x`, `3 p` and `J` / `gJ` with counts apply the count correctly
164
+ 5. **Larger, already planned**: line-wise `V`, block `ctrl-v`, `o` / `gv` in Visual
165
+ mode, named registers (`"a`). See plan steps 4–5.
166
+
167
+ Groups 2–3 should be done through the operator layer (plan step 1), not as about 100
168
+ hand-written bindings. Where there's a choice, new vimlike bindings avoid alt-/ctrl-
169
+ chords. Each group needs tests (`keys("d 3 w")` + `assert_buf`), and the real-Vim differential
170
+ check where available.
171
+
172
+ ### Organize the "Show key bindings" page
173
+
174
+ Bindings like `[C] d i <char> : buf.text_object_op(:delete, <char>, :i)` land in
175
+ **Others**. With the vim or notepad scheme almost everything does, because the report's
176
+ sections are hardcoded to vimlike keywords. Plan: `doc/key_bindings_report_plan.md`.
177
+ It covers:
178
+ - structured binding records
179
+ - a fixed category list via `cat:` keywords, plus automatic categories for minor
180
+ modes and modules
181
+ - splitting vimlike's 205-binding `core` block
182
+ - grouping by mode in definition order
183
+ - a text-object table
184
+ - readable conditions
185
+ - a test that fails on uncategorized bindings
186
+
187
+ Depends on the "Descriptive names for key bindings" item above for the description
188
+ column.
189
+
190
+ ### Function panel shows nothing on the key bindings help page
191
+
192
+ The key bindings page (`show_key_bindings`) is a hyperplaintext buffer with `❙…❙` /
193
+ `◼ …` headings, which the function panel can outline (`FuncPanel#hyperplaintext_outline_entries`).
194
+ On this page it shows "(no file)" instead. Three causes (found 2026-11-19):
195
+
196
+ 1. **The `fname` guard runs first.** `FuncPanel#refresh` (`gui_func_panel.rb:50-53`)
197
+ returns "(no file)" for any buffer without a file name before it checks for
198
+ hyperplaintext. Generated buffers (`create_new_buffer`) have `fname = nil`.
199
+ 2. **The language is only set on the GTK side.** The report calls
200
+ `gui_set_file_lang(b.id, "hyperplaintext")` (`key_bindings_report.rb:15,70`), which
201
+ sets the GtkSource buffer's language but not `Buffer#lang`. So
202
+ `hyperplaintext_buffer?` (`buf.lang == "hyperplaintext" || fname.end_with?(".txt")`)
203
+ is false even without the guard. `Buffer#set_language` (`buffer.rb:195`) sets both.
204
+ 3. **Refresh runs too early.** `create_new_buffer` (`editor.rb:622-629`) makes the
205
+ buffer current, which triggers `func_panel_refresh` from `buffer_list.rb:133`,
206
+ *before* `set_content` and before the caller sets the language. Nothing refreshes
207
+ the panel afterwards (the only other triggers are a buffer switch and the manual
208
+ `:refresh_func_panel`).
209
+
210
+ The same problem affects the other generated buffers that use `gui_set_file_lang`:
211
+ - the free-bindings report (`key_bindings_report.rb:15`)
212
+ - the vim-conflicts report (markdown, `:259`)
213
+ - diff buffers (`diff_buffer.rb:110,184,210`)
214
+
215
+ Fix:
216
+ 1. In `refresh`, check for hyperplaintext before the `fname` guard (it only needs the
217
+ text), and keep "(no file)" just for the LSP path.
218
+ 2. Make the report and other generated-buffer callers use `buf.set_language(...)`
219
+ instead of `gui_set_file_lang`. Or make `gui_set_file_lang` also update
220
+ `Buffer#lang`, which fixes every caller at once.
221
+ 3. Refresh the panel when a buffer's language changes (in `set_language`), and after
222
+ `create_new_buffer` has set the content. A debounced refresh on text change
223
+ (like `file_panel_marks_changed`) would also keep the outline current while editing
224
+ `.txt` files.
225
+ 4. Optional: outline markdown (`#` headings) the same way, so the vim-conflicts
226
+ report, README.md and the `doc/*.md` files get an outline without LSP. This fits
227
+ with the markdown highlighting item.
228
+ 5. Test (`tests/test_func_panel.rb`): with the panel shown, run `:show_key_bindings`
229
+ and assert that the panel's store has a row for the "Key bindings" title and the
230
+ `◼` sections, and does not show "(no file)".
231
+
232
+ ### Single downloadable app (AppImage, later Flatpak)
233
+
234
+ Plan: `doc/bundling_plan.md`. AppImage is recommended: one file, and no sandbox, so
235
+ external tools keep working. It has to bundle relocatable Ruby, the gems, the GI
236
+ typelibs and the GTK/GStreamer/VTE libs, built on Ubuntu 24.04 (to match the tested GTK 4.14; see "GTK version differences"). Code fixes needed
237
+ first:
238
+ - `exe/vimamsa` puts CWD-relative `lib`/`ext` on the load path
239
+ - the dead `ext/stridx` path
240
+ - `Exec=` in `desktop_install.rb` has to point at `$APPIMAGE`
241
+ - `ruby-lsp` stays bundled for now; AppRun exposes a `ruby-lsp` binstub on `PATH`
242
+ Before the AppImage helps non-Ubuntu users (see "Running on non-Ubuntu distros" in the plan):
243
+ - a `cnf.terminal.command` setting with auto-detection, to replace the hardcoded `gnome-terminal`
244
+ - modules page install commands per distro (read from `/etc/os-release`)
245
+
246
+ ### Resettable test VM: occasional fresh-install runs
247
+
248
+ The test VM (`$VM_NAME`) isn't blank any more. It was provisioned once and has collected state from
249
+ every run since, so a fresh install is never tested. Plan:
250
+ `doc/vm_snapshots_plan.md`.
251
+ - two VirtualBox snapshots: `clean` (fresh 24.04 + Guest Additions) and
252
+ `provisioned`
253
+ - `run_tests_vm.sh` restores `provisioned` before every run
254
+ - it automatically does a fresh run from `clean` when install inputs change or
255
+ weekly, and then retakes `provisioned`
256
+
257
+ The `clean` baseline needs a newly installed VM (one-time, manual).
258
+
259
+ ### Start in insert mode (command stays the base), new buffers inherit the mode, esc toggle
260
+
261
+ Goal: easier for new users without giving up modal editing. Command mode stays the
262
+ **base** of the mode stack, so `to_previous_mode` (`key_binding_tree.rb:156`) and
263
+ Visual → command keep working. Only the mode a buffer *starts* in changes.
264
+
265
+ **Rule for a new buffer's start mode** (decided 2026-11-19):
266
+ - A new buffer starts in **the most recent of command/insert in the previous buffer**,
267
+ i.e. the buffer that was current when the new one was created. Use the topmost
268
+ `:command` or `:insert` in its mode stack, and skip transient modes (Visual,
269
+ replace, minor modes) above it. Examples:
270
+ - `[command, visual]` → command
271
+ - `[command, insert]` → insert
272
+ - `[command, insert, visual]` → insert (Visual entered from insert, e.g.
273
+ shift-arrows)
274
+ - `[command]` → command
275
+ - Read the live stack (`vma.kbd.default_mode_stack`), not the buffer's saved
276
+ `mode_stack`. The saved copy is only updated on a buffer switch
277
+ (`buffer_list.rb:116`) and on mode changes with buffer scope (`editor.rb:111`), so
278
+ it can be stale.
279
+ - Start in insert → the new buffer's stack is `[command, insert]`, so esc returns to
280
+ command as usual. Start in command → `[command]`.
281
+ - **Fallbacks:**
282
+ - The previous buffer is a special-mode buffer (grep, bookmarks, file manager,
283
+ buffer list: `@buf.default_mode = :grep/:bmark/:file_exp/:buf_mgr`, so its stack
284
+ has no command/insert), or the keyboard is in an editor-scope mode
285
+ (`get_scope == :editor`): use the mode of the most recently used *regular*
286
+ buffer.
287
+ - The first buffer at startup, or no regular buffer yet: the **remembered last
288
+ mode** (see below). Only when nothing is remembered yet (first run ever, or the
289
+ state file is missing) use `cnf.start_in_insert`. It defaults to on for new
290
+ installs and is written as off into existing installs' `settings.rb` on first
291
+ start after the upgrade, so current users see no change.
292
+ - Session restore: all restored buffers get the startup mode, and the buffer that
293
+ becomes current decides what comes next.
294
+ - **Remembered across restarts** (decided 2026-11-19): the last command/insert mode
295
+ (the same "topmost command or insert" value the inheritance rule uses, taken from
296
+ the last *regular* buffer) is saved and used as the start mode at the next startup.
297
+ - Store it in the **data dir** (`get_data_path`, `editor.rb:776`), like the window
298
+ layout. `marshal_save` / `save_var_to_file` (`editor.rb:345-364`) currently write
299
+ to `get_dot_path` (the config dir), so either give them a data-dir variant or put
300
+ the value into the same state file as the layout.
301
+ - Save it in `Editor#save_state` / `shutdown` (`editor.rb:388-391`, next to
302
+ `save_window_layout`) **and** when the command/insert value changes, so it
303
+ survives a crash. Saving only on change keeps writes rare: one per mode toggle,
304
+ not per key.
305
+ - Ignore transient and special modes when saving. Leaving the editor in Visual
306
+ mode or with the grep buffer current stores the underlying command/insert of the
307
+ last regular buffer.
308
+ - One global value, not per file. (Per-buffer modes for session-restored buffers
309
+ could come later through `session.txt`.)
310
+ - Test mode (`vma_test_mode?`) neither reads nor writes it, as with the layout. A
311
+ corrupt or unknown value is ignored and falls back to `cnf.start_in_insert`.
312
+ - **Exempt buffers** keep their own mode: generated pages (key bindings help,
313
+ free-bindings and vim-conflicts reports, diffs, shell-command output,
314
+ `filelinks`) start in command, so a stray key can't edit them and `enter` still
315
+ follows links. Special-mode buffers keep their `default_mode`. Mark them with a
316
+ `create_new_buffer(..., start_mode: :command)` argument, or by the callers that
317
+ set `default_mode`.
318
+ - **Switching** to an existing buffer restores its own saved mode, as now. The
319
+ inheritance rule applies to *new* buffers only. Opening an already-open file is a
320
+ switch, not a new buffer.
321
+ - Implementation point: `Buffer#initialize` sets `@mode_stack = [@default_mode]`
322
+ (`buffer.rb:31-32`). Compute the start stack there (or in `create_new_buffer` /
323
+ the open-file path) through a helper such as `vma.kbd.inherited_start_mode`, and
324
+ apply it when the buffer becomes current.
325
+
326
+ **Esc toggles command → insert** (`cnf.esc_toggles_insert`):
327
+ - In Vim, esc in normal mode only cancels a pending command or count, and otherwise
328
+ does nothing (at most a beep). `C esc` is unbound in vimlike and vim today.
329
+ Vimlike already has the same toggle on a ctrl tap (`"C ctrl!" => :insert_mode`,
330
+ `"I esc || I ctrl!" => :prev_mode`, `key_bindings_vimlike.rb:78,83`).
331
+ - **The second esc in a row does nothing**, so `esc esc` (Vim users' "make sure I'm
332
+ in command mode") always ends in command mode. It's a deterministic rule, not a
333
+ timeout.
334
+ - Esc with a pending count (`3 esc`) only clears the count. Esc mid-sequence
335
+ (`, esc`) only cancels, as now (no matching child → back to root,
336
+ `key_binding_tree.rb:592-606`).
337
+ - On in vimlike (and notepad, where it's moot). **Never in the `vim` scheme**, which
338
+ must behave like Vim.
339
+ - The current mode must be clearly visible (cursor shape/color *and* a mode label).
340
+ Check that the label is prominent enough once modes toggle.
341
+
342
+ **Tests:**
343
+ - The harness forces command mode before each test (`test_framework.rb:124`), so
344
+ existing tests are unaffected.
345
+ - New tests:
346
+ - inheritance from `[command]`, `[command, insert]`, `[command, visual]` and
347
+ `[command, insert, visual]`
348
+ - fallback from a special-mode buffer
349
+ - generated pages start in command
350
+ - switching restores the saved mode
351
+ - `esc` toggles, `esc esc` ends in command, `3 esc` clears the count
352
+ - Visual → esc → esc
353
+ - in the vim scheme `esc` does nothing
354
+ - `cnf.start_in_insert` off reproduces today's behavior
355
+ - the remembered mode round-trips: save insert → "restart" (reload the state) →
356
+ first buffer starts in insert. A remembered value wins over
357
+ `cnf.start_in_insert`. A missing or corrupt file falls back to the setting.
358
+ Visual/special modes at shutdown store the underlying command/insert.
359
+
360
+ ### Help panel: the ~20 most important key bindings, shown by default for new users
361
+
362
+ A small side panel that lists the essential bindings for the **active scheme**. It
363
+ opens by default for new users and closes with a click (× button). The full list
364
+ stays on Help ▸ Show key bindings, which today is bound to `C , ; s k`. That's hard to
365
+ find, which is part of why this panel is needed.
366
+
367
+ Comments / design decisions:
368
+ - **Content is derived, not hardcoded.** Use a curated list of ~20 action symbols
369
+ (the same `BASIC_ACTIONS` list proposed in `doc/key_bindings_report_plan.md`, so the
370
+ panel and the "Basics" section of the full page agree). Look up their keys in the
371
+ live tree (`KeyBindingTree#act_bindings[mode][action]`, `key_binding_tree.rb:89,799`).
372
+ That way the panel is right for vimlike, vim and notepad, and for rebinds in
373
+ `custom.rb`. Actions with no binding in the active scheme are left out.
374
+ - List for vimlike, grouped (revised 2026-11-19):
375
+ - **Modes**: **`ctrl` (tap: press and release alone)**, the main way to switch:
376
+ command → insert (`"C ctrl!" => :insert_mode`), insert → command
377
+ (`"I ctrl!"`, `:prev_mode`), visual → command (`"V ctrl!"`). Then `esc`
378
+ command, `v` visual. (`i` is not listed: ctrl covers entering insert mode.) Show `ctrl` first and explain "tap" in the label,
379
+ since `ctrl!` notation means nothing to new users.
380
+ - **Moving** (command/visual): `h` `j` `k` `l` left / down / up / right, `w` next
381
+ word, `b` previous word
382
+ - **Files**: `ctrl-s` save, `ctrl-w` close, `, n b` new. File finding (`, f`,
383
+ `, h`, `, b`) is left out: menus and the file panel cover it, and the full page
384
+ lists it.
385
+ - **Editing** (command): `u` undo, `ctrl-r` redo, `x` delete char, `d d` delete
386
+ line, `y y` copy line, `p` paste
387
+ - **Selection** (visual): `d` delete, `y` copy
388
+ - **Search**: `/` find, `s` easy-jump
389
+ - **Help**: `, , s` search actions, `, ; s k` all key bindings
390
+ - **Quit**: `Q`
391
+
392
+ That's about 25 keys in about 20 rows: `h j k l` is one row, `w b` one row, and
393
+ the three `ctrl` tap directions one row.
394
+ - `l` was bound to a Ruby string (`buf.move(FORWARD_CHAR)`), which the
395
+ action-symbol lookup can't find. Fixed 2026-11-19 (`374cca1`): `"VC l"` now uses the existing
396
+ `:e_move_forward_char` in vimlike and vim. All the moving keys (`h j k l w b`) are
397
+ named actions now.
398
+
399
+ Labels come from the action descriptions (see the "Descriptive names" item), with
400
+ the keys shown as keycaps.
401
+ - **Mode-aware.** The top line shows the current mode in large text ("INSERT — type
402
+ normally, esc for commands" / "COMMAND — keys run commands, i to type"). The
403
+ group for the current mode is highlighted, and it updates on mode change. That
404
+ makes the panel the prominent mode indicator the start-in-insert / esc-toggle
405
+ item asks for.
406
+ - **Rows are clickable** and run the action (`call_action`). That helps new users
407
+ and means the panel is useful even before they learn the keys. The panel must
408
+ **not take keyboard focus** (`focusable = false` on its widgets), so typing always
409
+ goes to the editor. The e2e tests depend on that too.
410
+ - **Placement**: a right-side panel built like the key log panel, which wraps
411
+ `@minibuf_vpane` at the grid level, independent of the file/func panel and
412
+ two-column nesting (`gui.rb:1264-1300`). Narrow, about 220 px, and scrollable.
413
+ Not an overlay on the text, which would cover code. If both are open, the key log
414
+ panel and the help panel share the right side (stack them, or let showing one
415
+ hide the other).
416
+ - **Open by default only for new users.** Shown when there's no saved state (new
417
+ install). Closing it saves `help_panel_closed` once, globally (not per screen
418
+ resolution), together with the window/view layout state in the data dir
419
+ (`save_window_layout`), and it stays closed from then on. Existing installs get it
420
+ closed by default, using the same settings migration as `cnf.start_in_insert`.
421
+ Option: show it again once after a major version upgrade that changes bindings.
422
+ - **Reopening** must be easy to find: Help ▸ "Show help panel", a View-menu toggle
423
+ next to the other panels, and an action for Search for Actions. Add a vimlike
424
+ binding in the `, ;` help prefix without modifier chords, e.g. `, ; h`; check it's
425
+ free with Show free key bindings. The panel's footer says "Reopen: Help ▸ Show help
426
+ panel".
427
+ - Footer link: "All key bindings…" opens the full page (`show_key_bindings`).
428
+ - Test mode (`vma_test_mode?`) never auto-opens it, like the other panels.
429
+
430
+ Tests:
431
+ - In each scheme, the panel's rows resolve to non-empty keys and descriptions. No
432
+ raw Ruby is shown.
433
+ - Closing persists (reload the state → stays closed). A new state shows it.
434
+ - Clicking a row runs its action. Typing after a click still goes to the buffer.
435
+ - The mode header follows `esc` / `i`.
436
+
437
+ Depends on / ties in with:
438
+ - "Descriptive names for key bindings" (labels)
439
+ - "Organize the Show key bindings page" (`BASIC_ACTIONS`)
440
+ - "Start in insert mode" (mode indicator)
441
+ - the layout persistence in DONE
442
+
443
+ ### Modules page and module extraction
444
+
445
+ See `doc/modules_settings_plan.md`.
446
+
447
+ ## DONE
448
+
449
+ Format: `- **Item title** (2026-MM-DD, `abc1234`[..`def5678`]): one or two lines on what was changed.`
450
+
451
+ - **Restore window geometry and view layout on startup** (2026-11-18, `99cd484`): window
452
+ size/maximized, file/func/keylog panels with widths, two-column split and file, and
453
+ minibuffer history height are saved per screen resolution (last 5) in the data dir
454
+ and fitted to the current monitor on start. `idle_set_size` replaced by one
455
+ `set_default_size` before show. Off in test mode or with `cnf.restore_layout = false`.
456
+ Not yet checked in the VM: switching the guest resolution between runs.
457
+ - **Markdown (`.md`) syntax highlighting shows almost nothing with the bundled schemes**
458
+ (2026-11-19, `7a92079`): `markup_overlay_styles` (`gui_settings.rb`) adds `def:heading`,
459
+ `def:inline-code`, `def:link-text`, … to the generated overlay where the base scheme
460
+ lacks them, colored from its keyword/string/comment/hyperlink styles. Optional step 2
461
+ (hand-picked colors in `molokai_edit.xml`) not done.