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
@@ -0,0 +1,569 @@
1
+ # Plan: Vimamsa as a single downloadable app
2
+
3
+ ## Goal
4
+
5
+ A user downloads one file and runs it. They don't need to install Ruby, compile gems
6
+ or install `-dev` packages. Today, installing means: a system Ruby 3.x, about 15 GTK
7
+ `-dev` packages, `gem build` + `gem install`, which compiles the vmaext C extension and
8
+ all the Ruby-GNOME native extensions (`install.sh`, `Dockerfile`, `vm_guest_run.sh`).
9
+ That takes several minutes and fails easily on unusual systems.
10
+
11
+ This document replaces earlier informal AppImage notes with a checked, concrete plan.
12
+
13
+ ## What has to be bundled (verified 2026-11-19)
14
+
15
+ | Layer | Contents | Notes |
16
+ |---|---|---|
17
+ | Ruby runtime | Ruby 3.x interpreter + stdlib (dev: 3.4.9) | must be relocatable |
18
+ | Pure-Ruby gems | ripl, ripl-multi_line, differ, parallel, listen, language_server-protocol, rufo, ruby-lsp (+ prism, rbs, sorbet-runtime…) | `ruby-lsp` and `rufo` are runtime deps in the gemspec. Both stay in the bundle (see code change 5). |
19
+ | Native gems | glib2, gobject-introspection, gio2, cairo, cairo-gobject, pango, gdk_pixbuf2, gdk4, gtk4, gtksourceview5, gstreamer, vte4, ffi, rb-inotify (via listen), StrIdx | compiled against the build machine's libs |
20
+ | Own C extension | `ext/vmaext` (`vmaext.so`) | built by `extconf.rb` |
21
+ | **GI typelibs** | `Gtk-4.0`, `Gdk-4.0`, `Gsk-4.0`, `GtkSource-5`, `Gst-1.0`, `GstBase-1.0`, `Vte-3.91`, `Pango-1.0`, `PangoCairo`, `GLib/GObject/Gio-2.0`, `GdkPixbuf-2.0`, `Graphene-1.0`, `HarfBuzz-0.0`, `cairo-1.0`, `freetype2-2.0`, `GModule-2.0` … | **The main gotcha.** Ruby-GNOME loads most of the API at runtime through GObject Introspection (`/usr/lib/x86_64-linux-gnu/girepository-1.0/*.typelib`). The libraries the typelibs point to are `dlopen`ed, so `ldd`-based tools don't see them. |
22
+ | Shared libs | GTK4, GtkSourceView 5, VTE (gtk4), GStreamer core + base/good plugins, pango, cairo, harfbuzz, glib, libgirepository, graphene, gdk-pixbuf + loaders | leave out glibc, libGL/GPU drivers, fontconfig config (the standard AppImage excludelist) |
23
+ | Runtime data | `share/gtksourceview-5/` (language-specs incl. `def.lang`, `markdown.lang`; styles), GSettings schemas (compiled), gdk-pixbuf `loaders.cache`, Adwaita icon theme (symbolic icons; `gui.rb:619` forces the Adwaita theme), GStreamer `gst-plugin-scanner` | |
24
+ | App files | `lib/`, `exe/`, `ext/`, `lang/`, `styles/`, `fonts/`, `modules/`, `icon.png`, `custom_example.rb`, `demo.txt`, README.md | `ppath()` (`util.rb:357`) resolves `lib/vimamsa/../../<x>`, so the repo layout must stay intact |
25
+
26
+ **Not bundled; stays a host requirement or a module requirement:** ack, clang-format,
27
+ git, diff, gnome-terminal (`terminal.rb:22`), xdg-open, ollama, piper/aplay, and the
28
+ dictation Python worker (faster-whisper + CUDA is far too large). That matches
29
+ `doc/modules_settings_plan.md`: the modules page tells the user what to install.
30
+
31
+ ## Options
32
+
33
+ ### A. AppImage (recommended for "one downloadable file")
34
+
35
+ One executable file (`Vimamsa-x86_64.AppImage`): download, `chmod +x`, run. No sandbox,
36
+ so the many external tools the editor runs (ack, git, clang-format, gnome-terminal,
37
+ `bash -c`) work exactly as they do today. That decides it for a text editor.
38
+
39
+ Build steps (a script, `scripts/build_appimage.sh`, run inside a container):
40
+ 1. **Build host**: Ubuntu 22.04 (glibc 2.35, GTK 4.6, GtkSourceView 5.4, VTE 0.68)
41
+ gives the widest compatibility, but it's far behind the development GTK. Ubuntu
42
+ 24.04 (GTK 4.14) matches development. See "GTK version differences" below for
43
+ the trade-off. Decide after running the test suite on 22.04.
44
+ 2. **Ruby**: build from source with `--prefix=/usr --enable-load-relative
45
+ --enable-shared`, `make install DESTDIR=AppDir`. `load-relative` makes the
46
+ interpreter find its stdlib relative to the binary. (traveling-ruby isn't
47
+ reliably maintained; ruby-build + load-relative is simpler to control.)
48
+ 3. **Gems**: `AppDir/usr/bin/ruby -S gem install --no-document --install-dir AppDir/usr/lib/ruby/gems/3.x.0 vimamsa-*.gem`
49
+ (or `bundle install --deployment` from a Gemfile.lock to pin versions). This
50
+ compiles the native gems and vmaext against the build host's libs.
51
+ 4. **Libraries**: `linuxdeploy --appdir AppDir --plugin gtk --plugin gstreamer`
52
+ deploys the dependencies of every `.so` under AppDir (point it at the gem
53
+ extension `.so`s with `--library` / `--deploy-deps-only`). GTK4 support in
54
+ linuxdeploy-plugin-gtk is newer than its GTK3 support and may need patching.
55
+ Then **explicitly** add the libs that are only reached through typelibs:
56
+ libgtk-4, libgtksourceview-5, libvte-2.91-gtk4, libgstreamer-1.0, libgraphene,
57
+ libgirepository-1.0, and check with `GI_TYPELIB_PATH` + `LD_DEBUG=libs` that
58
+ nothing is loaded from the host.
59
+ 5. **Typelibs and data**: copy the typelibs listed above to
60
+ `AppDir/usr/lib/girepository-1.0/`, copy `share/gtksourceview-5`, the Adwaita
61
+ icons and the schemas, and run `glib-compile-schemas`.
62
+ 6. **AppRun**: a shell script that exports
63
+ `GI_TYPELIB_PATH=$APPDIR/usr/lib/girepository-1.0`,
64
+ `XDG_DATA_DIRS=$APPDIR/usr/share:${XDG_DATA_DIRS:-/usr/local/share:/usr/share}`,
65
+ `GSETTINGS_SCHEMA_DIR`, `GDK_PIXBUF_MODULE_FILE`, `GST_PLUGIN_SYSTEM_PATH`,
66
+ `GST_PLUGIN_SCANNER`, `GEM_HOME`/`GEM_PATH` (bundled only; unset the user's
67
+ `GEM_HOME` and `RUBYOPT`), and `LD_LIBRARY_PATH` if linuxdeploy didn't set an
68
+ rpath, then runs `exec "$APPDIR/usr/bin/ruby" "$APPDIR/usr/share/vimamsa/exe/vimamsa" "$@"`.
69
+ 7. **Pack**: `appimagetool` with the **new static type-2 runtime**. The old runtime
70
+ needs `libfuse2`, which Ubuntu 24.04 no longer installs by default; with the old
71
+ runtime users would need `sudo apt install libfuse2t64` or
72
+ `--appimage-extract-and-run`. Embed update info (zsync) for AppImageUpdate.
73
+ 8. **CI**: a GitHub Actions job in a container of the build host (proposed `ubuntu:24.04`) builds it on a tag and
74
+ attaches it to the GitHub release.
75
+
76
+ Expected size: Ruby + gems about 60–80 MB, GTK4 + deps about 60 MB, GStreamer
77
+ base/good about 30–60 MB. Roughly **150–250 MB uncompressed and 60–100 MB as an
78
+ AppImage** (squashfs/zstd). Trimming GStreamer to the plugins audio playback and
79
+ dictation capture need (`playbin`, `autoaudiosrc`, decodebin, mp3/ogg/wav) keeps it at
80
+ the low end.
81
+
82
+ #### The typelib problem is build-time only
83
+
84
+ The hardest part of the AppImage (step 4: finding every library and data file that
85
+ Ruby-GNOME loads at runtime through GObject Introspection) is a problem for **whoever
86
+ builds the AppImage**, not for users. `ldd`-based tools can't see those libraries, so
87
+ the build script has to list them by hand. If one is missed, the AppImage still works
88
+ on the build machine and the developer's desktop, because the library is there in
89
+ `/usr/lib`. It then fails on a user's machine that doesn't have it, with an error such
90
+ as `Typelib file for namespace 'GtkSource' not found`. That's why the clean-machine
91
+ test below is required. Once the list is complete, users see none of this.
92
+
93
+ #### What users of the AppImage have to do
94
+
95
+ Required:
96
+ 1. Download `Vimamsa-x86_64.AppImage`.
97
+ 2. Make it executable: `chmod +x Vimamsa-x86_64.AppImage`, or Properties ▸
98
+ "Allow executing file as program" in the file manager.
99
+ 3. Run it, by double-click or `./Vimamsa-x86_64.AppImage [file]`.
100
+
101
+ No Ruby, no gems, no `apt install`, no compiling. On first start the editor installs
102
+ its own launcher and icon into `~/.local/share` (`desktop_install.rb`), pointing at
103
+ the AppImage (code change 3), so after that it appears in the app menu. If the user
104
+ moves the file, the next start updates the launcher.
105
+
106
+ Only in special cases:
107
+ - **libfuse2**: not needed with the static type-2 runtime (step 7). If an older
108
+ runtime were used, Ubuntu 22.04+ users would need `sudo apt install libfuse2` /
109
+ `libfuse2t64`, or would have to run it with `--appimage-extract-and-run`. Using the
110
+ static runtime avoids this, and it's a build decision, not a user action.
111
+ - **System requirements**: x86_64 Linux with glibc at least the build host's: with
112
+ the proposed Ubuntu 24.04 build host, glibc ≥ 2.39 (Ubuntu 24.04, Debian 13, Fedora 40
113
+ or newer; 22.04 would allow glibc ≥ 2.35) and a Wayland or X11 desktop. Older distros or arm64 need a
114
+ separate build. The GPU driver and fonts come from the host, as with any
115
+ AppImage.
116
+ - **Restricted `/tmp` or home on `noexec`** (some corporate setups): AppImages can't
117
+ run from a `noexec` mount, so the user moves the file to e.g. `~/Applications`.
118
+
119
+ Optional, only for the features that use external programs (same as today, and the
120
+ modules page in `doc/modules_settings_plan.md` lists them with copyable commands):
121
+
122
+ | Feature | User action |
123
+ |---|---|
124
+ | Content search (ack) | `sudo apt install ack` |
125
+ | Auto-format C/C++/JS | `sudo apt install clang-format` (Ruby works out of the box: rufo is bundled) |
126
+ | Git diff | `git` (usually already installed) |
127
+ | Run line in terminal | `gnome-terminal` (until `cnf.terminal.command` exists) |
128
+ | LSP | Ruby: works out of the box with the bundled `ruby-lsp`. C/C++: `sudo apt install clangd` |
129
+ | Ollama, TTS, dictation modules | see each module's card (Ollama install + model; piper + voice; faster-whisper venv + ffmpeg) |
130
+
131
+ Everything else works without further steps: editing, highlighting, the file
132
+ panel, image display, audio playback (bundled GStreamer plugins) and the embedded
133
+ terminal (bundled VTE).
134
+
135
+ Updates: download the new AppImage, or use AppImageUpdate / a tool like Gear Lever,
136
+ which read the embedded zsync update info. An in-editor "new version available"
137
+ notice could come later.
138
+
139
+ ### B. Flatpak (good second step, for Flathub)
140
+
141
+ - **Runtime**: `org.gnome.Platform` (current release) already contains GTK4,
142
+ GtkSourceView 5, GStreamer and the typelibs. Check whether VTE (gtk4) is in the
143
+ runtime; if not, add it as a manifest module.
144
+ - **Ruby** isn't in the GNOME SDK, so build it as a module. Gems become generated
145
+ `sources` (flatpak-builder-tools has a RubyGems generator), since Flathub builds
146
+ run offline.
147
+ - Can also be shipped as one file (`flatpak build-bundle` → `vimamsa.flatpak`), but
148
+ the user needs Flatpak installed.
149
+ - **The problem for an editor is the sandbox.**
150
+ - It needs `--filesystem=host` to edit arbitrary files.
151
+ - Every external command (ack, git, clang-format, gnome-terminal, `bash -c` in
152
+ auto_format, `command_to_buf`, LSP servers like clangd/solargraph, ollama,
153
+ piper) would run *inside* the sandbox, where those tools don't exist.
154
+ - The fix is a `host_cmd` wrapper that prefixes `flatpak-spawn --host` when
155
+ `/.flatpak-info` exists, plus `--talk-name=org.freedesktop.Flatpak`. Flathub
156
+ reviewers accept that for IDEs, but every `system` / `IO.popen` / backtick call
157
+ site has to go through the wrapper.
158
+ - Upside: desktop integration and updates come free, and the size is small
159
+ (shared runtime).
160
+
161
+ ### C. Not recommended
162
+
163
+ - **Tebako / ruby-packer** (Ruby + gems in one executable): GTK4, the typelibs and
164
+ GStreamer still have to be on the host, so the user still runs `apt install`. That
165
+ only half solves the problem.
166
+ - **Snap**: similar sandbox problems to Flatpak (classic confinement needs a manual
167
+ review), and Ubuntu-centric.
168
+ - **Docker**: not a desktop app.
169
+
170
+ ## GTK version differences
171
+
172
+ The AppImage carries its own GTK, so users always run the **build host's** GTK version,
173
+ whatever their distro has. Development currently runs on **GTK 4.14.5 /
174
+ GtkSourceView 5.12** (Ubuntu 24.04). Ubuntu 22.04 would bundle **GTK 4.6 /
175
+ GtkSourceView 5.4**: two years and eight minor versions older. Problems, from most to
176
+ least likely:
177
+
178
+ 1. **Behavior differs from what was developed and tested.**
179
+ - API: a scan (2026-11-19) found none of the 4.10+ classes (`Gtk::FileDialog`,
180
+ `AlertDialog`, `ColorDialog`, `UriLauncher`, …). The code uses the older
181
+ `Gtk::FileChooserDialog` (`gui.rb`, `buffer.rb`, `gui_settings.rb`), so it
182
+ should *load* on 4.6.
183
+ - But many bugs were fixed between 4.6 and 4.14: popovers, clipboard (the editor
184
+ already has a workaround for ruby-gnome#1609), TextView child anchors (used by
185
+ the calculator, terminal and images), and focus/key handling. The editor
186
+ depends heavily on key-event details.
187
+ - The only reliable check is to **run the full test suite against the bundled
188
+ libraries**, not the host's. That means running `exe/run_tests.rb` with the
189
+ AppDir's Ruby and `GI_TYPELIB_PATH`/`LD_LIBRARY_PATH`, or inside the AppImage,
190
+ on a clean VM.
191
+ 2. **Visual and rendering differences.**
192
+ - Fractional scaling (`wp_fractional_scale`) arrived in GTK 4.12. With 4.6,
193
+ users on 125%/150% Wayland scaling get **blurry text**. For a text editor
194
+ that's the most user-visible risk.
195
+ - The renderers changed too (new GL/Vulkan renderers in 4.14), and so did font
196
+ rendering (hinting and subpixel positioning in 4.16).
197
+ - The built-in Adwaita theme (`gui.rb:619` forces it) looks different in each
198
+ version.
199
+ - CSS: `gui_theme.rb` and others load custom CSS. GTK 4.16 deprecated
200
+ `@define-color` / named colors in favor of CSS variables. CSS written and
201
+ tested on one version may render differently or warn on another. Keep the CSS
202
+ to features that 4.6 supports and that 4.16+ hasn't deprecated, or check the
203
+ version.
204
+ 3. **GtkSourceView 5.4 vs 5.12.**
205
+ - The markdown/markup styles (`def:heading`, `def:inline-code`, …, see the
206
+ markdown item in `doc/TODO.md`) may differ or be missing in 5.4's `def.lang`
207
+ / `markdown.lang`. Check before writing the overlay fix against 5.12.
208
+ - The style schemes in `styles/` and the generated overlay use features of the
209
+ `.xml` format. Check them on 5.4.
210
+ - `XDG_DATA_DIRS` ends with the host's `/usr/share`. If a language-spec is
211
+ missing from the bundle, the bundled (older) GtkSourceView can pick up the
212
+ host's (newer) `.lang` file, which may use features it doesn't support. Bundle
213
+ the complete `share/gtksourceview-5` so the bundled copies win.
214
+ 4. **Mixing the bundled GTK with modules from the host.**
215
+ - GTK loads plug-in modules from the host: input methods (IBus/Fcitx), GIO
216
+ modules (gvfs for trash and remote locations in the file chooser), the dconf
217
+ settings backend, and print backends. Modules built for the host's newer GTK
218
+ can fail to load or **crash** the bundled older GTK.
219
+ - The usual AppImage answer is to isolate them (`GTK_PATH`/`GIO_MODULE_DIR`
220
+ pointing into the AppDir). But then users of IBus/Fcitx (CJK input) lose their
221
+ input method, and get only GTK's built-in compose/dead-key handling. The editor
222
+ relies on input-method commits for AltGr/dead keys (`gui_sourceview.rb`), so
223
+ test this with a non-US keyboard layout.
224
+ - Decide: bundle the gvfs/ibus GTK4 modules from the build host (matching
225
+ version), or accept the limitation and document it.
226
+ 5. **Typelib vs library mismatch.** If a typelib is missing from the bundle,
227
+ GObject Introspection falls back to the host's
228
+ `/usr/lib/*/girepository-1.0` typelib. That one describes a *different version*
229
+ of the library than the bundled `.so`, which can cause wrong calls or crashes
230
+ instead of a clean error. It's the same as the build-time problem above:
231
+ bundle the complete set, and in the test run check that no typelib is loaded
232
+ from the host (`GI_DEBUG`, `strace -e openat`).
233
+ 6. **Host graphics stack.** libGL/Mesa/Vulkan come from the host (excludelist). A
234
+ newer host Mesa may need a newer `libstdc++`/`libdrm` than the bundled ones, the
235
+ classic AppImage "`GLIBCXX_3.4.xx` not found" error. Don't bundle `libstdc++` (or
236
+ bundle it with a version check). As a fallback, AppRun can set
237
+ `GSK_RENDERER=cairo` when GL initialization fails.
238
+ 7. **Ruby-GNOME gems vs GTK version.** The gems (4.3.x) are compiled against the
239
+ build host's headers, so they match the bundled GTK. That's fine as long as gems,
240
+ typelibs and libraries all come from the same build host. Never reuse gems
241
+ compiled on the development machine.
242
+ 8. **Future: deprecations.** `Gtk::FileChooserDialog` and friends are deprecated
243
+ since 4.10 and print warnings on newer GTK. They keep working in GTK 4, but are
244
+ gone in GTK 5. Not urgent, but don't start new code on deprecated APIs.
245
+
246
+ **Recommendation.** The build host trades compatibility against matching the tested
247
+ version:
248
+
249
+ | Build host | GTK / GSV | Runs on (glibc) | Risk |
250
+ |---|---|---|---|
251
+ | Ubuntu 22.04 | 4.6 / 5.4 | 22.04+, Debian 12, Fedora 36+ | biggest gap to development; no fractional scaling |
252
+ | Debian 12 | 4.8 / 5.6 | Debian 12+, Ubuntu 22.10+, Fedora 37+ | still no fractional scaling |
253
+ | Ubuntu 24.04 | 4.14 / 5.12 | 24.04+, Debian 13, Fedora 40+ | matches development; narrower range |
254
+
255
+ **Decided (2026-11-19): build on Ubuntu 24.04**, so the bundle runs exactly the GTK
256
+ the editor is developed and tested with, and fractional scaling works. Ubuntu 22.04
257
+ users (still supported until 2027) use `gem install` or the later Flatpak, which always
258
+ ships a current GNOME runtime and avoids the whole GTK-version question. Revisit if
259
+ 22.04-era users ask for the AppImage. Add a CI job that runs the test suite against the
260
+ bundled libraries.
261
+
262
+ ## Running on non-Ubuntu distros
263
+
264
+ An AppImage isn't tied to Ubuntu. Everything that differs between distros (Ruby, gems,
265
+ GTK, GtkSourceView, VTE, GStreamer, typelibs, data files) is inside the file, so all
266
+ distros run the same editor code on the same libraries. What still comes from the host:
267
+
268
+ | From the host | Requirement / note |
269
+ |---|---|
270
+ | **glibc** | at least the build host's: **≥ 2.39** with Ubuntu 24.04. This decides which distros work (table below). |
271
+ | CPU | x86_64 (an arm64 build would be separate) |
272
+ | Kernel | any modern one. The static type-2 runtime needs no `libfuse2`. FUSE itself is in every desktop kernel. |
273
+ | Graphics | host Mesa / NVIDIA driver (`libGL`, `libEGL`, Vulkan). Works on any distro; see "Host graphics stack" above. |
274
+ | Fonts | host fontconfig and fonts. The default `cnf.font.family = "Monospace"` (`conf.rb:170`) resolves to each distro's monospace font (DejaVu Sans Mono, Noto Sans Mono, …), so it can look slightly different. The bundled Oxanium font is unaffected. |
275
+ | Audio | GStreamer's bundled `pulsesink`/`pulsesrc` talk to PipeWire (pipewire-pulse) or PulseAudio, which every current desktop distro provides |
276
+ | Desktop integration | `.desktop` file + icon in `~/.local/share` follow the freedesktop spec, so they work in GNOME, KDE, Xfce and others. `desktop_install.rb` already skips `gtk-update-icon-cache` / `update-desktop-database` when they're missing (`which` guards at lines 73, 77). |
277
+ | Wayland / X11 | GTK4 runs on all common compositors (GNOME, KDE, Sway, Hyprland) and on X11 |
278
+
279
+ ### Which distros it runs on (glibc ≥ 2.39)
280
+
281
+ | Distro | glibc | Runs? |
282
+ |---|---|---|
283
+ | Ubuntu 24.04+, Linux Mint 22+, Pop!_OS 24.04, elementary OS 8, KDE neon (24.04 base) | 2.39+ | ✅ |
284
+ | Fedora 40+ | 2.39+ | ✅ |
285
+ | Debian 13 (trixie) | 2.41 | ✅ |
286
+ | Arch, Manjaro, EndeavourOS, openSUSE Tumbleweed, Gentoo, Void (glibc) | rolling | ✅ |
287
+ | openSUSE Leap 16 | 2.40 | ✅ |
288
+ | RHEL / Alma / Rocky 10 | 2.39 | ✅ |
289
+ | Fedora Silverblue / Kinoite, Bazzite (immutable) | 2.39+ | ✅ (AppImages suit immutable systems well; optional tools go through toolbox / distrobox) |
290
+ | WSL2 + WSLg with Ubuntu 24.04 | 2.39 | ✅ (not tested) |
291
+ | Ubuntu 22.04, Linux Mint 21, Zorin OS 17 | 2.35 | ❌ use `gem install` / Flatpak |
292
+ | Debian 12 (bookworm), ChromeOS Crostini (Debian 12) | 2.36 | ❌ |
293
+ | openSUSE Leap 15.6 | 2.38 | ❌ |
294
+ | RHEL / Alma / Rocky 9 | 2.34 | ❌ |
295
+ | NixOS | (no FHS) | ⚠️ needs `appimage-run` (or `programs.appimage.enable = true; binfmt = true;`) |
296
+ | Alpine, Void-musl, Chimera (musl libc) | — | ❌ glibc-only; would need the Flatpak |
297
+
298
+ On a too-old glibc the AppImage fails right at start with
299
+ `/lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.39' not found`. AppRun can't catch
300
+ this, because the bundled Ruby itself doesn't load. Mention it in the download
301
+ instructions (README: "requires glibc 2.39+: Ubuntu 24.04, Fedora 40, Debian 13 or
302
+ newer").
303
+
304
+ ### Distro-specific issues inside the editor
305
+
306
+ These aren't about the AppImage itself; they're about the external tools it calls.
307
+ They need fixing for non-Ubuntu users regardless of how the editor is packaged:
308
+
309
+ 1. **Hardcoded `gnome-terminal`** (`terminal.rb:22`): KDE (Konsole), Xfce
310
+ (xfce4-terminal) and most non-GNOME setups don't have it, so "Execute line in
311
+ terminal" fails silently there. Fix: a `cnf.terminal.command` setting, with
312
+ auto-detection in order: `$TERMINAL`, `x-terminal-emulator` (Debian alternatives),
313
+ `gnome-terminal`, `konsole`, `xfce4-terminal`, `kitty`, `alacritty`, `foot`,
314
+ `wezterm`, `xterm`, each with its own "run this command" arguments. This is
315
+ already noted in `doc/modules_settings_plan.md` ("Keep in core").
316
+ 2. **Install commands on the modules page are `apt`-only.** Read `ID` / `ID_LIKE`
317
+ from `/etc/os-release` and show the matching command. Package names also differ:
318
+
319
+ | Tool | Debian/Ubuntu | Fedora | Arch | openSUSE |
320
+ |---|---|---|---|---|
321
+ | ack | `ack` | `ack` | `ack` | `ack` |
322
+ | clang-format | `clang-format` | `clang-tools-extra` | `clang` | `clang-tools` |
323
+ | clangd | `clangd` | `clang-tools-extra` | `clang` | `clang-tools` |
324
+ | ffmpeg | `ffmpeg` | `ffmpeg-free` (or RPM Fusion `ffmpeg`) | `ffmpeg` | `ffmpeg` (Packman for full codecs) |
325
+ | aplay | `alsa-utils` | `alsa-utils` | `alsa-utils` | `alsa-utils` |
326
+
327
+ Verify these names when implementing. Fall back to the generic text
328
+ ("install clang-format with your package manager") for unknown distros.
329
+ Immutable distros need `toolbox`/`distrobox` or `rpm-ostree install`; show a hint
330
+ when `/run/ostree-booted` exists.
331
+ 3. **pip in a venv** (dictation, TTS) works the same on all distros. `python3 -m venv`
332
+ needs `python3-venv` on Debian/Ubuntu only; other distros include it.
333
+
334
+ ### Testing on other distros
335
+
336
+ - **CI smoke test matrix** in containers: `fedora:40`, `debian:trixie`, `archlinux`,
337
+ `opensuse/tumbleweed`, `ubuntu:24.04`. Install only `xvfb` (and Mesa for software
338
+ GL), then run `xvfb-run ./Vimamsa-x86_64.AppImage --appimage-extract-and-run --test <smoke test>`.
339
+ Containers have no FUSE, hence `--appimage-extract-and-run`. Also add a
340
+ `debian:bookworm` job that is *expected* to fail with the glibc error, so the
341
+ minimum stays documented and tested.
342
+ - **By hand, once per release** on a real desktop: Fedora (GNOME, SELinux on), KDE
343
+ (Kubuntu or Fedora KDE) for non-GNOME desktop integration, input methods and
344
+ terminal detection, and Arch. A live USB or another VirtualBox VM next to the test VM
345
+ is enough.
346
+
347
+ ## Alternative: a newer GTK (Ubuntu 26.04's) in the bundle
348
+
349
+ Checked 2026-11-19 in an `ubuntu:26.04` container on the development machine (Ubuntu
350
+ 24.04.5, glibc 2.39, GTK 4.14.5):
351
+
352
+ | | Ubuntu 24.04 (dev machine) | Ubuntu 26.04 |
353
+ |---|---|---|
354
+ | glibc | 2.39 | **2.43** |
355
+ | GTK | 4.14.5 | 4.22.4 |
356
+ | GtkSourceView | 5.12 | 5.18.0 |
357
+ | VTE (gtk4) | 0.76.0 | 0.84.0 |
358
+ | GLib | 2.80 | 2.88.0 |
359
+ | GStreamer | 1.24 | 1.28.2 |
360
+ | libgirepository-1.0 | yes | still shipped (1.86); 2.0 is in GLib 2.88 |
361
+
362
+ Both of the following can be done on the development machine with Docker (it's
363
+ installed), but they're very different.
364
+
365
+ **A. Build inside an `ubuntu:26.04` container.** Technically trivial: the same
366
+ build script with a different base image. But the AppImage then needs **glibc ≥ 2.43**.
367
+ It would *not* run on Ubuntu 24.04, the current LTS (including the development
368
+ machine itself), Debian 13 (2.41) or Fedora 43 (2.42). Only Ubuntu 26.04+, Fedora 44+
369
+ and the rolling distros could run it. **Not recommended** until 26.04-era distros are
370
+ the norm (about 2028).
371
+
372
+ **B. Build GTK 4.22 from source on top of the 24.04 base** (in a 24.04 container):
373
+ glibc stays 2.39 and compatibility stays the same, but the bundle gets the newer GTK
374
+ stack.
375
+ - Build into a prefix (e.g. `/opt/vma-gtk`) with meson, roughly in dependency order:
376
+ - GLib 2.88 (+ girepository)
377
+ - gobject-introspection 1.86
378
+ - wayland-protocols
379
+ - harfbuzz / pango / graphene / libepoxy as GTK 4.22 requires (check the minimum
380
+ versions in its `meson.build`; 24.04's may be too old)
381
+ - GTK 4.22
382
+ - GtkSourceView 5.18
383
+ - VTE 0.84 (C++20, gnutls, pcre2)
384
+
385
+ GStreamer can stay at 24.04's 1.24.
386
+ - Then compile Ruby and the Ruby-GNOME gems against that prefix
387
+ (`PKG_CONFIG_PATH=/opt/vma-gtk/lib/pkgconfig`), and point linuxdeploy at it.
388
+ - Use an existing build recipe rather than writing one: gnome-build-meta /
389
+ BuildStream, or a jhbuild moduleset.
390
+ - Effort: **about 2–4 extra days**, plus ongoing upkeep (rebuild for security
391
+ fixes, follow GTK's dependency bumps).
392
+ - Disk: about 10–15 GB for the build container. Check free space on the build
393
+ machine first.
394
+ - Risks:
395
+ - The bundled GLib (2.88) is newer than the host's on 24.04. Host GIO/GTK
396
+ modules (gvfs, dconf, IBus) are built against the older GLib/GTK. The bundle
397
+ isolates them anyway (see "GTK version differences" point 4), but it's one more
398
+ thing to test.
399
+ - Ruby-GNOME 4.3.x must work with GLib 2.88. GLib 2.80+ moved GIRepository
400
+ into GLib (`girepository-2.0`). Check which one the gem links, and use a recent
401
+ Ruby-GNOME release.
402
+
403
+ **Either way the test-coverage argument from "GTK version differences" applies in
404
+ reverse**: the editor is developed and tested on GTK 4.14, so a 4.22 bundle runs a GTK
405
+ nobody has tested it on. It's newer and has fewer bugs, but there are real behavior
406
+ changes:
407
+ - CSS: named colors are deprecated since 4.16
408
+ - new renderers and font rendering
409
+ - `FileChooserDialog` deprecation warnings
410
+ - GtkSourceView style changes
411
+
412
+ So the full test suite would have to run against the bundled 4.22 libraries in CI, and
413
+ ideally the development machine would move to the same GTK.
414
+
415
+ **Worth it?** GTK 4.14 already has fractional scaling, so 4.22 mainly brings
416
+ rendering and font polish, bug fixes, and GtkSourceView 5.18.
417
+
418
+ **Decided (2026-11-19): stay with the plain Ubuntu 24.04 build (system GTK 4.14) for
419
+ now.** Neither A nor B is planned. Reconsider only if a specific GTK bug or feature
420
+ needs a newer GTK; then use option B in a container, not option A. Look at it again
421
+ when the development machine moves to Ubuntu 26.04.
422
+
423
+ ## Code changes needed regardless of format
424
+
425
+ 1. **`exe/vimamsa` puts paths relative to the *current directory* on `$LOAD_PATH`:**
426
+ `$LOAD_PATH.unshift(File.expand_path("lib"))` and the same for `"ext"` (lines 44-45).
427
+ `scriptdir` is computed at line 9 and never used. From an AppImage, or when
428
+ started from another directory, it would pick up a random `./lib` from wherever
429
+ the user is. Use `File.join(scriptdir, "lib")`. This also affects running from
430
+ source.
431
+ 2. `lib/vimamsa.rb` adds `ext/stridx` to the load path, but that directory no longer
432
+ exists. StrIdx now comes from the gem. Remove the dead line.
433
+ 3. **`desktop_install.rb`** writes `Exec=vimamsa %F` (line 64), which only works when
434
+ the gem's binstub is on PATH. When `ENV["APPIMAGE"]` is set, write
435
+ `Exec="<$APPIMAGE>" %F` and refresh it if the AppImage has moved. (The
436
+ install-only-when-changed logic is already there.) Flatpak installs its own
437
+ desktop file, so skip this there.
438
+ 4. **Read-only app directory**: an AppImage is mounted read-only. Checked: nothing
439
+ writes through `ppath()` (generated styles go to `~/.config/vimamsa/styles`), so
440
+ this is OK today. Add a test or a review rule to keep it that way. This ties in
441
+ with the XDG item in `doc/TODO.md`.
442
+ 5. **Runtime deps: keep `ruby-lsp` in the bundle for now** (decided 2026-11-19).
443
+ It pulls in prism, rbs and sorbet-runtime (tens of MB), which is accepted. For it
444
+ to be usable from the bundle:
445
+ - AppRun puts `$APPDIR/usr/bin` on `PATH` and a `ruby-lsp` binstub there that
446
+ uses the bundled Ruby, so a `cnf.lsp.server` command of `ruby-lsp` (not
447
+ `bundle exec ruby-lsp` as in `custom_example.rb:94`) finds it. A built-in
448
+ default server preset could point at it directly (see the LSP presets in
449
+ `doc/modules_settings_plan.md`).
450
+ - Caveat: in a project with a Gemfile, ruby-lsp builds a "composed bundle" using
451
+ the *bundled* Ruby. If the project needs a different Ruby version, this can
452
+ fail, and then the user's own `ruby-lsp` (configured in `cnf.lsp.server`)
453
+ should be used instead. Mention this on the LSP module card.
454
+ - Revisit trimming it if the AppImage size becomes a problem.
455
+ Keep `rufo` too (small; makes Ruby auto-format work out of the box).
456
+ 6. **Version check at startup**: the bundled GTK is the build host's version. Guard
457
+ any newer GTK/GtkSourceView API use with `Gtk.check_version` (or keep the build
458
+ host's GTK as the CI baseline so it's caught).
459
+ 7. **Ruby version**: development is on 3.4. The gemspec doesn't say a version, so
460
+ add `required_ruby_version`. CLAUDE.md says 3.0+, but the Dockerfile uses 3.1.
461
+
462
+ ## Testing the bundle
463
+
464
+ - Smoke test in CI: `xvfb-run ./Vimamsa-x86_64.AppImage --version` (add the flag if
465
+ it's missing), then start it, open a file and quit, using a `--test` run of one
466
+ small built-in test file. Ship `tests/` inside the AppDir, or point `--test` at
467
+ the checkout.
468
+ - Run it on a **clean** machine with no Ruby or GTK dev packages:
469
+ - the test VM (`$VM_NAME`), restored to a snapshot taken before provisioning
470
+ - Fedora / Debian 12 / Ubuntu 24.04 live images
471
+ - Check with `LD_DEBUG=libs` / `GI_DEBUG` that nothing loads from host `/usr/lib`
472
+ except the excludelist.
473
+ - Check by hand: syntax highlighting (language-specs found), the file chooser
474
+ (schemas), icons, audio playback (GStreamer plugins), the embedded terminal (VTE),
475
+ single-instance forwarding (the `listen` gem / inotify), and the desktop launcher
476
+ pointing at the AppImage.
477
+
478
+ ## Effort estimate
479
+
480
+ | Step | Effort |
481
+ |---|---|
482
+ | Code changes 1–3, 5, 7 | small (about half a day) |
483
+ | Ruby + gems in an AppDir, typelibs and data, AppRun, working locally | 2–4 days. Most of it is finding all the typelib-reached libs and data paths. |
484
+ | CI job + release upload + clean-machine testing | 1–2 days |
485
+ | Flatpak (manifest, gem sources, `host_cmd` wrapper over all external commands) | 3–5 days more, plus Flathub review |
486
+
487
+ ## Recommended order
488
+
489
+ 1. Code changes 1–3, 5, 7 (useful on their own).
490
+ 2. Choose the build host (see "GTK version differences"; proposed Ubuntu 24.04).
491
+ If 22.04 is still wanted, run the test suite there first.
492
+ 3. Write `scripts/build_appimage.sh` in a build-host container and get a working AppImage
493
+ locally. Test it on the clean VM.
494
+ 4. CI build on tags plus a GitHub release asset. Update README.md's install section
495
+ ("Download the AppImage", with `gem install` as the alternative).
496
+ 5. Later: Flatpak/Flathub, with the `host_cmd` wrapper.
497
+
498
+ ## DONE
499
+
500
+ - **Code changes 1, 2, 3, 7** (2026-11-19, `24a1a88`): `exe/vimamsa` and
501
+ `exe/run_tests.rb` load `lib/`/`ext/` next to the script; dead `ext/stridx` load
502
+ path removed; the desktop launcher runs `$APPIMAGE` when set (quoted per the
503
+ Desktop Entry spec); gemspec `required_ruby_version >= 3.1` (3.1 untested; the VM
504
+ runs 3.2). Tests: `tests/test_bundling.rb`. Code change 5 (the `ruby-lsp` binstub
505
+ on PATH) belongs to AppRun, so it comes with `scripts/build_appimage.sh`.
506
+ - **AppImage build script** (2026-11-19, `bc43676`): `scripts/appimage/build.sh`
507
+ (host, Docker) runs `scripts/appimage/build_in_container.sh` in the Ubuntu 24.04
508
+ image from `scripts/appimage/Dockerfile`. Output:
509
+ `build/appimage/Vimamsa-<version>-x86_64.AppImage`, **92 MB** (249 MB unpacked).
510
+ Builds the committed `HEAD` (`VMA_REF` to change); Ruby and appimagetool are cached
511
+ in `build/appimage/cache`, so a rebuild takes about 3 minutes.
512
+ - Ruby 3.4.9 built with `--enable-load-relative`; gems installed with it.
513
+ - Libraries: no linuxdeploy. The script seeds the list with `ruby`, every gem/stdlib
514
+ `.so`, the GStreamer plugins, the gdk-pixbuf loaders, the dconf GIO module and the
515
+ `.so` named in each typelib (read with `strings`), then follows `ldd` and copies
516
+ everything except an excludelist (glibc, libstdc++, GL/DRM/Vulkan, X11/core
517
+ xcb/Wayland client, fontconfig/freetype/harfbuzz, sound servers, zlib, expat).
518
+ `patchelf` sets an `$ORIGIN` RUNPATH on every bundled ELF file, so **AppRun sets no
519
+ `LD_LIBRARY_PATH`** and programs the editor starts don't load bundled libs. The
520
+ build fails if any bundled file has an unresolved library.
521
+ - All 56 typelibs of the build host are copied (2.9 MB).
522
+ - `ruby-lsp` / `rufo` are reached through wrappers in `usr/lib/vimamsa/bin` on
523
+ `PATH` (code change 5), not by putting the bundled `ruby` first on `PATH`.
524
+ - Packed with appimagetool continuous (static type-2 runtime: no libfuse2 needed).
525
+ - Tests:
526
+ - Clean `ubuntu:24.04` container (no GTK, no Ruby, no typelibs; only the host
527
+ libs a desktop has): `test_basic_editing.rb` 14/14 from the AppImage. Loaded
528
+ from outside the image (`LD_DEBUG=libs`): only the excludelist and what the
529
+ host's Mesa/harfbuzz pull in.
530
+ - Test VM (`$VM_NAME`), real GNOME Wayland desktop, the AppImage itself (FUSE-mounted):
531
+ full suite 390 passed, 1 failed (the known `TestDictation` failure), 6 skipped.
532
+ The launcher becomes `Exec="<path to>/Vimamsa-x86_64.AppImage" %F`.
533
+
534
+ - **Started programs get the user's environment** (2026-11-19, `bc43676`): AppRun
535
+ lists every variable it changes in `VMA_APPIMAGE_ENV` and keeps the old values in
536
+ `VMA_HOST_<name>`. After startup, `restore_host_env` (`lib/vimamsa/appimage_env.rb`,
537
+ called at the end of `Editor#start`) puts them back. GLib/GIO/GI keep what they read
538
+ at startup. Before restoring, it initializes the parts that read their variables
539
+ lazily: gdk-pixbuf loaders, the GSettings schema source, GIO modules, and GStreamer
540
+ (loaded and `Gst.init`ed even when audio is off, so a module enabled later still
541
+ finds the bundled plugins). The `ruby-lsp`/`rufo` wrappers unset `GEM_HOME` etc.
542
+ themselves. `VMA_REF=WORKTREE` builds include uncommitted changes. VM, from the
543
+ AppImage: 392 passed, 1 failed (`TestDictation`); `test_appimage_children_get_host_environment`
544
+ checks that no variable except PATH/APPDIR/APPIMAGE points into the image and
545
+ that VTE, `playbin`, pixbuf loading and `ruby-lsp` still work afterwards.
546
+
547
+ - **CI build and release** (2026-11-19, `1192898`): `.github/workflows/appimage.yml`. On
548
+ a `vX.Y.Z` tag (must match `version.rb`) it builds with `scripts/appimage/build.sh`,
549
+ runs `scripts/appimage/smoke_test.sh` (clean `ubuntu:24.04`: no GTK/Ruby, only the
550
+ libraries a desktop has), signs a build provenance attestation and attaches
551
+ `Vimamsa-x86_64.AppImage` + `.sha256` to the release. A fixed file name, so
552
+ README links to `releases/latest/download/Vimamsa-x86_64.AppImage`. Run by hand,
553
+ it only builds and tests (workflow artifact). appimagetool 1.9.1 and the type-2
554
+ runtime 20251108 are pinned by SHA-256. The smoke test found that the MIME
555
+ database must be bundled (gdk-pixbuf couldn't detect PNG without
556
+ shared-mime-info). Not yet run on GitHub: the first tag push is its first run.
557
+
558
+ ## Follow-ups found while building
559
+
560
+ - **GTK modules from the host**: `libgtk-4` still looks in the host's
561
+ `/usr/lib/x86_64-linux-gnu/gtk-4.0/4.0.0` (print backends, media, IM modules). Fine
562
+ on 24.04-era hosts; check on a newer distro.
563
+ - **GStreamer size**: all of plugins-base/good are bundled (12 MB plus their deps).
564
+ Trimming to what playback/dictation need is possible later.
565
+ - **Gems are not pinned**: `gem install` resolves the newest matching versions
566
+ (Ruby-GNOME 4.3.9 here). Use a lockfile for reproducible releases.
567
+ - Not tested yet: another distro (Fedora/Arch), X11 session, non-US keyboard/IME,
568
+ HiDPI scaling.
569
+