terminal: swap priority of terminal, editor highlights

closes #9964

6 files changed, 90 insertions, 34 deletions

diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
index af94c60629..cfaec12520 100644
--- a/runtime/doc/nvim_terminal_emulator.txt
+++ b/runtime/doc/nvim_terminal_emulator.txt
@@ -7,8 +7,8 @@
 Terminal emulator				*terminal* *terminal-emulator*
 
 Nvim embeds a VT220/xterm terminal emulator based on libvterm. The terminal is
-presented as a special buffer type, asynchronously updated from the virtual
-terminal as data is received from the program connected to it.
+presented as a special 'buftype', asynchronously updated as data is received
+from the connected program.
 
 Terminal buffers behave like normal buffers, except:
 - With 'modifiable', lines can be edited but not deleted.
@@ -23,11 +23,11 @@ Terminal buffers behave like normal buffers, except:
 ==============================================================================
 Start						*terminal-start*
 
-There are 3 ways to create a terminal buffer:
+There are several ways to create a terminal buffer:
 
-- By invoking the |:terminal| ex command.
-- By calling the |termopen()| function.
-- By editing a file with a name matching `term://(.{-}//(\d+:)?)?\zs.*`.
+- Invoke the |:terminal| command.
+- Call the |termopen()| function.
+- Edit a file with a name matching `term://(.{-}//(\d+:)?)?\zs.*`.
   For example:
 >
     :edit term://bash
@@ -98,14 +98,21 @@ global configuration.
 - 'wrap' is disabled
 
 You can change the defaults with a TermOpen autocommand: >
-	au TermOpen * setlocal list
+    au TermOpen * setlocal list
 
 TERMINAL COLORS ~
 
-The `{g,b}:terminal_color_$NUM` variables control the terminal color palette,
-where `$NUM` is the color index between 0 and 255 inclusive. This setting only
-affects UIs with RGB capabilities; for normal terminals the color index is
-just forwarded. The variables are read only during |TermOpen|.
+The `{g,b}:terminal_color_x` variables control the terminal color palette,
+where `x` is the color index between 0 and 255 inclusive.  The variables are
+read during |TermOpen|. The value must be a color name or hexadecimal string.
+Example: >
+    let g:terminal_color_4 = '#ff0000'
+    let g:terminal_color_5 = 'green'
+Only works for RGB UIs (see 'termguicolors'); for 256-color terminals the
+color index is just forwarded.
+
+Editor highlighting (|syntax-highlighting|, |highlight-groups|, etc.) has
+higher precedence: it is applied after terminal colors are resolved.
 
 ==============================================================================
 Status Variables				*terminal-status*
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 5b9a9d5dd0..cce9f681f9 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -6131,9 +6131,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 						*'termguicolors'* *'tgc'*
 'termguicolors' 'tgc'	boolean (default off)
 			global
-	When on, uses |highlight-guifg| and |highlight-guibg| attributes in
-	the terminal (thus using 24-bit color). Requires a ISO-8613-3
-	compatible terminal.
+	Enables 24-bit RGB color in the |TUI|.  Uses "gui" |:highlight|
+	attributes instead of "cterm" attributes. |highlight-guifg|
+	Requires an ISO-8613-3 compatible terminal.
 
 						*'terse'* *'noterse'*
 'terse'			boolean	(default off)
diff --git a/src/nvim/screen.c b/src/nvim/screen.c
index cd472ea1e4..d61be4af1c 100644
--- a/src/nvim/screen.c
+++ b/src/nvim/screen.c
@@ -3275,16 +3275,18 @@ win_line (
           line = ml_get_buf(wp->w_buffer, lnum, FALSE);
           ptr = line + v;
 
-          if (!attr_pri)
+          if (!attr_pri) {
             char_attr = syntax_attr;
-          else
+          } else {
             char_attr = hl_combine_attr(syntax_attr, char_attr);
-          /* no concealing past the end of the line, it interferes
-           * with line highlighting */
-          if (c == NUL)
+          }
+          // no concealing past the end of the line, it interferes
+          // with line highlighting.
+          if (c == NUL) {
             syntax_flags = 0;
-          else
+          } else {
             syntax_flags = get_syntax_info(&syntax_seqnr);
+          }
         } else if (!attr_pri) {
           char_attr = 0;
         }
@@ -3376,7 +3378,7 @@ win_line (
         }
 
         if (wp->w_buffer->terminal) {
-          char_attr = hl_combine_attr(char_attr, term_attrs[vcol]);
+          char_attr = hl_combine_attr(term_attrs[vcol], char_attr);
         }
 
         // Found last space before word: check for line break.
diff --git a/test/functional/core/main_spec.lua b/test/functional/core/main_spec.lua
index a0981e9207..b793e531c9 100644
--- a/test/functional/core/main_spec.lua
+++ b/test/functional/core/main_spec.lua
@@ -7,19 +7,9 @@ local feed = helpers.feed
 local eval = helpers.eval
 local clear = helpers.clear
 local funcs = helpers.funcs
-local nvim_prog = helpers.nvim_prog
+local nvim_prog_abs = helpers.nvim_prog_abs
 local write_file = helpers.write_file
 
-local function nvim_prog_abs()
-  -- system(['build/bin/nvim']) does not work for whatever reason. It needs to
-  -- either be executable searched in $PATH or something starting with / or ./.
-  if nvim_prog:match('[/\\]') then
-    return funcs.fnamemodify(nvim_prog, ':p')
-  else
-    return nvim_prog
-  end
-end
-
 describe('Command-line option', function()
   describe('-s', function()
     local fname = 'Xtest-functional-core-main-s'
diff --git a/test/functional/helpers.lua b/test/functional/helpers.lua
index 7851a0fcba..fd10a6afcd 100644
--- a/test/functional/helpers.lua
+++ b/test/functional/helpers.lua
@@ -238,6 +238,16 @@ local function stop()
   session:stop()
 end
 
+local function nvim_prog_abs()
+  -- system(['build/bin/nvim']) does not work for whatever reason. It must
+  -- be executable searched in $PATH or something starting with / or ./.
+  if nvim_prog:match('[/\\]') then
+    return request('nvim_call_function', 'fnamemodify', {nvim_prog, ':p'})
+  else
+    return nvim_prog
+  end
+end
+
 -- Executes an ex-command. VimL errors manifest as client (lua) errors, but
 -- v:errmsg will not be updated.
 local function nvim_command(cmd)
@@ -826,6 +836,7 @@ local module = {
   nvim_async = nvim_async,
   nvim_dir = nvim_dir,
   nvim_prog = nvim_prog,
+  nvim_prog_abs = nvim_prog_abs,
   nvim_set = nvim_set,
   ok = ok,
   os_name = os_name,
diff --git a/test/functional/terminal/highlight_spec.lua b/test/functional/terminal/highlight_spec.lua
index 9579e0ea0b..48fedd5927 100644
--- a/test/functional/terminal/highlight_spec.lua
+++ b/test/functional/terminal/highlight_spec.lua
@@ -3,9 +3,12 @@ local Screen = require('test.functional.ui.screen')
 local thelpers = require('test.functional.terminal.helpers')
 local feed, clear, nvim = helpers.feed, helpers.clear, helpers.nvim
 local nvim_dir, command = helpers.nvim_dir, helpers.command
+local nvim_prog_abs = helpers.nvim_prog_abs
 local eq, eval = helpers.eq, helpers.eval
+local funcs = helpers.funcs
+local nvim_set = helpers.nvim_set
 
-describe(':terminal window highlighting', function()
+describe(':terminal highlight', function()
   local screen
 
   before_each(function()
@@ -112,8 +115,51 @@ describe(':terminal window highlighting', function()
   end)
 end)
 
+it(':terminal highlight has lower precedence than editor #9964', function()
+  clear()
+  local screen = Screen.new(30, 4)
+  screen:set_default_attr_ids({
+    -- "Normal" highlight emitted by the child nvim process.
+    N_child = {foreground = tonumber('0x4040ff'), background = tonumber('0xffff40')},
+    -- "Search" highlight emitted by the child nvim process.
+    S_child = {background = tonumber('0xffff40'), italic = true, foreground = tonumber('0x4040ff')},
+    -- "Search" highlight in the parent nvim process.
+    S = {background = Screen.colors.Green, italic = true, foreground = Screen.colors.Red},
+    -- "Question" highlight in the parent nvim process.
+    Q = {background = tonumber('0xffff40'), bold = true, foreground = Screen.colors.SeaGreen4},
+  })
+  screen:attach({rgb=true})
+  -- Child nvim process in :terminal (with cterm colors).
+  funcs.termopen({
+    nvim_prog_abs(), '-n', '-u', 'NORC', '-i', 'NONE', '--cmd', nvim_set,
+    '+hi Normal ctermfg=Blue ctermbg=Yellow',
+    '+norm! ichild nvim',
+    '+norm! oline 2',
+  })
+  screen:expect([[
+    {N_child:^child nvim                    }|
+    {N_child:line 2                        }|
+    {N_child:                              }|
+                                  |
+  ]])
+  command('hi Search gui=italic guifg=Red guibg=Green cterm=italic ctermfg=Red ctermbg=Green')
+  feed('/nvim<cr>')
+  screen:expect([[
+    {N_child:child }{S:^nvim}{N_child:                    }|
+    {N_child:line 2                        }|
+    {N_child:                              }|
+    /nvim                         |
+  ]])
+  command('syntax keyword Question line')
+  screen:expect([[
+    {N_child:child }{S:^nvim}{N_child:                    }|
+    {Q:line}{N_child: 2                        }|
+    {N_child:                              }|
+    /nvim                         |
+  ]])
+end)
 
-describe('terminal window highlighting with custom palette', function()
+describe(':terminal highlight with custom palette', function()
   local screen
 
   before_each(function()