feat(ui): UI :detach command

Problem:
Cannot detach the current UI.

Solution:
- Introduce `:detach`.
- Introduce `Channel.detach`.

Co-authored-by: bfredl <bjorn.linse@gmail.com>

3 files changed, 23 insertions, 2 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 92f5a261ee..4f76e7e058 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1208,8 +1208,8 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
 
                                                       *nvim_set_client_info()*
 nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
-    Self-identifies the client. Sets the `client` object returned by
-    |nvim_get_chan_info()|.
+    Self-identifies the client, and sets optional flags on the channel.
+    Defines the `client` object returned by |nvim_get_chan_info()|.
 
     Clients should call this just after connecting, to provide hints for
     debugging and orchestration. (Note: Something is better than nothing!
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index ecb4de09bb..780712df6c 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -47,6 +47,25 @@ can connect to any Nvim instance).
 Example: this sets "g:gui" to the value of the UI's "rgb" field:    >
         :autocmd UIEnter * let g:gui = filter(nvim_list_uis(),{k,v-> v.chan==v:event.chan})[0].rgb
 <
+------------------------------------------------------------------------------
+Stop or detach the current UI
+
+                                                *:detach*
+:detach
+                Detaches the current UI. Other UIs (if any) remain attached.
+                The server (typically `nvim --embed`) continues running as
+                a background process, and you can reattach to it later.
+                Before detaching, you may want to note the server address:
+                >vim
+                    :echo v:servername
+<
+                Note: The server closes the UI RPC channel, so :detach
+                inherently "works" for all UIs. But if a UI isn't expecting
+                the channel to be closed, it may be (incorrectly) reported as
+                an error.
+
+------------------------------------------------------------------------------
+GUI commands
 
                                                 *:winp* *:winpos* *E188*
 :winp[os]
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 1f1ad84a02..90a020bb4d 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -400,6 +400,8 @@ TUI
 
 UI
 
+• |:detach| the current UI, let the Nvim server continue running as a background
+  process. Works with the builtin TUI, and all GUIs.
 • |vim.ui.open()| (by default bound to |gx|) accepts an `opt.cmd` parameter
   which controls the tool used to open the given path or URL. If you want to
   globally set this, you can override vim.ui.open using the same approach