feat(misc)!: update setup_termbg_sync() to use OSC 111 sequence

Details:
- Using "set color explicitly" doesn't work with transparent background
  in `tmux`.

Resolve #1128
Resolve nvim-mini/MiniMax#25

Author: echasnovski

CHANGELOG.md

@@ -8,6 +8,14 @@ There are following change types:
 
 # Version 0.18.0-dev
 
+## mini.misc
+
+### Evolve
+
+- Update `setup_termbg_sync()` to use OSC 111 control sequence to reset terminal emulator's background color. This provides a more robust behavior across platforms (like `tmux`).
+
+    The previous "reset by explicitly setting initial background color" behavior is available by setting the new `opts.explicit_reset` option to `true`.
+
 
 # Version 0.17.0
 

doc/mini-misc.txt

@@ -238,7 +238,7 @@ Parameters ~
 
 ------------------------------------------------------------------------------
                                                   *MiniMisc.setup_termbg_sync()*
-                         `MiniMisc.setup_termbg_sync`()
+                      `MiniMisc.setup_termbg_sync`({opts})
 Set up terminal background synchronization
 
 What it does:
@@ -247,8 +247,7 @@ What it does:
 - Creates autocommands for |ColorScheme| and |VimResume| events, which
   change terminal background to have same color as |guibg| of |hl-Normal|.
 - Creates autocommands for |VimLeavePre| and |VimSuspend| events which set
-  terminal background back to the color at the time this function was
-  called first time in current session.
+  terminal background back to its original color.
 - Synchronizes background immediately to allow not depend on loading order.
 
 Primary use case is to remove possible "frame" around current Neovim instance
@@ -257,6 +256,13 @@ used by terminal emulator itself.
 
 Works only on Neovim>=0.10.
 
+Parameters ~
+{opts} `(table|nil)` Options. Possible fields:
+  - <explicit_reset> `(boolean)` - whether to reset terminal background by
+    explicitly setting it to the color it had when this function was called.
+    Set to `true` if terminal emulator doesn't support OSC 111 control sequence.
+    Default: `false`.
+
 ------------------------------------------------------------------------------
                                                *MiniMisc.setup_restore_cursor()*
                     `MiniMisc.setup_restore_cursor`({opts})

lua/mini/misc.lua

@@ -370,16 +370,21 @@ H.root_cache = {}
 --- - Creates autocommands for |ColorScheme| and |VimResume| events, which
 ---   change terminal background to have same color as |guibg| of |hl-Normal|.
 --- - Creates autocommands for |VimLeavePre| and |VimSuspend| events which set
----   terminal background back to the color at the time this function was
----   called first time in current session.
+---   terminal background back to its original color.
 --- - Synchronizes background immediately to allow not depend on loading order.
 ---
 --- Primary use case is to remove possible "frame" around current Neovim instance
 --- which appears if Neovim's |hl-Normal| background color differs from what is
 --- used by terminal emulator itself.
 ---
 --- Works only on Neovim>=0.10.
-MiniMisc.setup_termbg_sync = function()
+---
+---@param opts table|nil Options. Possible fields:
+---   - <explicit_reset> `(boolean)` - whether to reset terminal background by
+---     explicitly setting it to the color it had when this function was called.
+---     Set to `true` if terminal emulator doesn't support OSC 111 control sequence.
+---     Default: `false`.
+MiniMisc.setup_termbg_sync = function(opts)
   -- Handling `'\027]11;?\007'` response was added in Neovim 0.10
   if vim.fn.has('nvim-0.10') == 0 then return H.notify('`setup_termbg_sync()` requires Neovim>=0.10', 'WARN') end
 
@@ -390,6 +395,12 @@ MiniMisc.setup_termbg_sync = function()
   end
   if not has_stdout_tty then return end
 
+  opts = vim.tbl_extend('force', { explicit_reset = false }, opts or {})
+
+  -- Choose a method for how terminal emulator background is reset
+  local reset = function() io.stdout:write('\027]111\027\\') end
+  if opts.explicit_reset then reset = function() io.stdout:write('\027]11;' .. H.termbg_init .. '\007') end end
+
   local augroup = vim.api.nvim_create_augroup('MiniMiscTermbgSync', { clear = true })
   local track_au_id, bad_responses, had_proper_response = nil, {}, false
   local f = function(args)
@@ -406,7 +417,6 @@ MiniMisc.setup_termbg_sync = function()
 
     -- Set up reset to the color returned from the very first call
     H.termbg_init = H.termbg_init or termbg
-    local reset = function() io.stdout:write('\027]11;' .. H.termbg_init .. '\007') end
     vim.api.nvim_create_autocmd({ 'VimLeavePre', 'VimSuspend' }, { group = augroup, callback = reset })
 
     -- Set up sync

tests/test_misc.lua

@@ -711,8 +711,8 @@ T['setup_termbg_sync()']['works'] = new_set(
       end
       validate_event('VimResume', '\027]11;#dddddd\007')
       validate_event('ColorScheme', '\027]11;#dddddd\007')
-      validate_event('VimLeavePre', '\027]11;#11262d\007')
-      validate_event('VimSuspend', '\027]11;#11262d\007')
+      validate_event('VimLeavePre', '\027]111\027\\')
+      validate_event('VimSuspend', '\027]111\027\\')
     end,
   }
 )
@@ -734,7 +734,7 @@ T['setup_termbg_sync()']['can be called multiple times'] = function()
 
   -- Should reset to the color from the very first call
   child.api.nvim_exec_autocmds('VimLeavePre', {})
-  eq(child.lua_get('_G.log'), { { '\27]11;#11262d\a' } })
+  eq(child.lua_get('_G.log'), { { '\027]111\027\\' } })
 end
 
 T['setup_termbg_sync()']['does nothing if there is no proper stdout'] = function()
@@ -831,7 +831,7 @@ end
 T['setup_termbg_sync()']['handles different color formats'] = function()
   skip_if_no_010()
 
-  local validate = function(term_response_color, ref_color)
+  local validate = function(term_response_color)
     -- Mock clean start to overcome that color is parsed only once per session
     child.lua('package.loaded["mini.misc"] = nil')
     child.lua('require("mini.misc").setup_termbg_sync()')
@@ -840,7 +840,7 @@ T['setup_termbg_sync()']['handles different color formats'] = function()
     -- Should properly parse initial background and use it to reset on exit
     child.lua('_G.log = {}')
     child.api.nvim_exec_autocmds('VimLeavePre', {})
-    eq(child.lua_get('_G.log'), { { '\027]11;' .. ref_color .. '\007' } })
+    eq(child.lua_get('_G.log'), { { '\027]111\027\\' } })
 
     -- Clean up
     child.lua('_G.log = {}')
@@ -872,7 +872,33 @@ T['setup_termbg_sync()']['handles transparent `Normal` background'] = function()
   -- terminal background
   child.cmd('hi Normal guifg=#222222 guibg=NONE')
   child.api.nvim_exec_autocmds('ColorScheme', {})
-  eq(child.lua_get('_G.log'), { { '\27]11;#11262d\a' } })
+  eq(child.lua_get('_G.log'), { { '\027]111\027\\' } })
+end
+
+T['setup_termbg_sync()']['respects `opts.explicit_reset`'] = function()
+  skip_if_no_010()
+
+  child.cmd('hi Normal guifg=#222222 guibg=#dddddd')
+  child.lua('MiniMisc.setup_termbg_sync({ explicit_reset = true })')
+  child.api.nvim_exec_autocmds('TermResponse', { data = '\027]11;rgb:1111/2626/2d2d' })
+  child.lua('_G.log = {}')
+
+  -- Should still sync on appropriate events
+  local validate_event = function(event, log_entry)
+    child.api.nvim_exec_autocmds(event, {})
+    eq(child.lua_get('_G.log'), { { log_entry } })
+    child.lua('_G.log = {}')
+  end
+  validate_event('VimResume', '\027]11;#dddddd\007')
+  validate_event('ColorScheme', '\027]11;#dddddd\007')
+  -- - Should reset by setting initial color explicitly
+  validate_event('VimLeavePre', '\027]11;#11262d\007')
+  validate_event('VimSuspend', '\027]11;#11262d\007')
+
+  -- Should reset with explicit bg color on transparent `Normal` background
+  child.cmd('hi Normal guifg=#222222 guibg=NONE')
+  child.api.nvim_exec_autocmds('ColorScheme', {})
+  eq(child.lua_get('_G.log'), { { '\027]11;#11262d\a' } })
 end
 
 local restore_cursor_test_file = make_path(dir_misc_path, 'restore-cursor.lua')