feat(tui): builtin UI (TUI) sets client info #30397

Problem:
The default builtin UI client does not declare its client info. This
reduces discoverability and makes it difficult for plugins to identify
the UI.

Solution:
- Call nvim_set_client_info after attaching, as recommended by `:help dev-ui`.
- Also set the "pid" field.
- Also change `ui_active()` to return a count. Not directly relevant to
  this commit, but will be useful later.

5 files changed, 65 insertions, 20 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index a7b59f20bc..45c6168e3d 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -779,7 +779,7 @@ nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
       • {chan}  channel_id, or 0 for current channel
 
     Return: ~
-        Dictionary describing a channel, with these keys:
+        Channel info dict with these keys:
         • "id" Channel id.
         • "argv" (optional) Job arguments list.
         • "stream" Stream underlying the channel.
@@ -792,11 +792,11 @@ nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
           • "terminal" |terminal| instance interprets ASCII sequences.
           • "rpc" |RPC| communication on the channel is active.
         • "pty" (optional) Name of pseudoterminal. On a POSIX system this is a
-          device path like "/dev/pts/1". If the name is unknown, the key will
-          still be present if a pty is used (e.g. for conpty on Windows).
-        • "buffer" (optional) Buffer with connected |terminal| instance.
+          device path like "/dev/pts/1". If unknown, the key will still be
+          present if a pty is used (e.g. for conpty on Windows).
+        • "buffer" (optional) Buffer connected to |terminal| instance.
         • "client" (optional) Info about the peer (client on the other end of
-          the RPC channel), if provided by it via |nvim_set_client_info()|.
+          the RPC channel), which it provided via |nvim_set_client_info()|.
 
 nvim_get_color_by_name({name})                      *nvim_get_color_by_name()*
     Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
@@ -1285,6 +1285,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
                         inclusive.
       • {attributes}  Arbitrary string:string map of informal client
                       properties. Suggested keys:
+                      • "pid": Process id.
                       • "website": Client homepage URL (e.g. GitHub
                         repository)
                       • "license": License description ("Apache 2", "GPLv3",
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 69e251e657..f0f2334ff6 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -6,14 +6,38 @@
 
 Nvim Graphical User Interface				*gui* *GUI*
 
+Any client that supports the Nvim |ui-protocol| can be used as a UI for Nvim.
+And multiple UIs can connect to the same Nvim instance! The terms "UI" and
+"GUI" are often used interchangeably because all Nvim UI clients have the same
+potential capabilities; the "TUI" refers to a UI client that outputs to your
+terminal, whereas a "GUI" outputs directly to the OS graphics system.
+
+Except where noted, this document describes UI capabilities available to both
+TUI and GUI (assuming the UI supports the given feature). See |TUI| for notes
+specific to the terminal UI. Help tags with the "gui-" prefix refer to UI
+features, whereas help tags with the "ui-" prefix refer to the |ui-protocol|.
+
+Nvim provides a default, builtin UI (the |TUI|), but there are many other
+(third-party) GUIs that you can use instead:
+
+- Firenvim (Nvim in your web browser!) https://github.com/glacambre/firenvim
+- vscode-neovim (Nvim in VSCode!) https://github.com/vscode-neovim/vscode-neovim
+- Neovide https://neovide.dev/
+- Goneovim https://github.com/akiyosi/goneovim
+- Nvy https://github.com/RMichelsen/Nvy
+- Neovim-Qt (Qt5) https://github.com/equalsraf/neovim-qt
+- VimR (macOS) https://github.com/qvacua/vimr
+- Others https://github.com/neovim/neovim/wiki/Related-projects#gui
+
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-Starting the GUI				*gui-start* *E229* *E233*
+Starting the GUI				*gui-config* *gui-start*
 
 				*ginit.vim* *gui-init* *gvimrc* *$MYGVIMRC*
 For GUI-specific configuration Nvim provides the |UIEnter| event.  This
-happens after other |initialization|s, like reading your vimrc file.
+happens after other |initialization|s, or whenever a UI attaches (multiple UIs
+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
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 515aef753d..1d95886356 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -189,6 +189,9 @@ TREESITTER
 
 TUI
 
+• The builtin UI declares info |nvim_set_client_info()| on its channel. See
+  |startup-tui|. To see the current UI info, try this: >
+    :lua =vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan)
 • |log| messages written by the builtin UI client (TUI, |--remote-ui|) are
   now prefixed with "ui" instead of "?".
 
diff --git a/runtime/doc/tui.txt b/runtime/doc/tui.txt
index d2af878239..9493f91b1e 100644
--- a/runtime/doc/tui.txt
+++ b/runtime/doc/tui.txt
@@ -6,28 +6,45 @@
 
 Terminal UI						*TUI* *tui*
 
-Nvim uses a list of terminal capabilities to display its user interface
-(except in |--embed| and |--headless| modes). If that information is wrong,
-the screen may be messed up or keys may not be recognized.
+By default when you run `nvim` (without |--embed| or |--headless|) it starts
+the builtin "terminal UI" (TUI). This default UI is optional: you can run Nvim
+as a "headless" server, or you can use a |GUI|.
 
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-Startup						*startup-terminal*
+Startup					*startup-tui* *startup-terminal*
+
+Nvim has a client-server architecture: by default when you run `nvim`, this
+starts the builtin UI client, which starts a `nvim --embed` server (child)
+process that the UI client connects to. After attaching to the server, the UI
+client calls |nvim_set_client_info()| (as recommended for all UIs |dev-ui|)
+and sets these fields on its channel: >
+
+  client = {
+    attributes = {
+      license = 'Apache 2',
+      pid = …,
+      website = 'https://neovim.io',
+    },
+    name = 'nvim-tui',
+    type = 'ui',
+    version = { … },
+  }
 
 Nvim guesses the terminal type when it starts (except in |--embed| and
 |--headless| modes). The |$TERM| environment variable is the primary hint that
 determines the terminal type.
 
 					*terminfo* *E557* *E558* *E559*
-The terminfo database is used if available.
-
-The Unibilium library (used by Nvim to read terminfo) allows you to override
-the system terminfo with one in $HOME/.terminfo/ directory, in part or in
-whole.
-
-Building your own terminfo is usually as simple as running this as
-a non-superuser:
+To display its user interface, Nvim reads a list of "terminal capabilities"
+from the system terminfo database (or builtin defaults if terminfo is not
+found). If that information is wrong, the screen may be messed up or keys may
+not be recognized.
+
+The Unibilium library (used to read terminfo) allows you to override the
+system terminfo with one in the "$HOME/.terminfo/" directory. Building your
+own terminfo is usually as simple as running this:
 >
   curl -LO https://invisible-island.net/datafiles/current/terminfo.src.gz
   gunzip terminfo.src.gz
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 1f5132bd30..42dfcd2fe7 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -9,7 +9,7 @@ Nvim UI protocol					*UI* *ui*
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-UI Events						*ui-events*
+UI Events						*ui-protocol* *ui-events*
 
 UIs can be implemented as external client processes communicating with Nvim
 over the RPC API. The default UI model is a terminal-like grid with a single,